Second pre-push review of PR #86, T-2327/bugfix-flaky-timing-dependent-unit-tests, diffed against origin/main at 640830ae. The first round returned Needs fixes (minor) with four findings and four nits; commit 4f65ae0b claims to address all eight. This round checks that claim and reviews the branch as a whole.
4f65ae0b, each verified in the code rather than taken from the commit message.generatePreviewIfValid; every path that cancels a preview sets state itself, so no transition is lost.SubmissionGate.wait() traced under four cancellation orderings (before entry, between handler and lock, while the lock is held, after append): one resume per continuation, no leak, no deadlock.make test-only over the ten suites the branch touches or whose mock recorders it changed, on iPhone 17 Pro,OS=26.5 — 187 tests, 0 failures, working tree clean afterwards.testing.md line 129 still says the teaching-preview tests use "the private spin helper that file had on main" (it is the shared one since ac3ac8ef) and line 96 says "above" for a section that is below.obsoleteGenerationCannotPublish's 150 ms delay never engages (both edits run before either task; pre-existing) and with the pre-call guard the superseded task never reaches the post-call check, so that guard now has no test.async let guard tests, three unbounded Task.yield() spins, the AsyncStream gate in CharacterReviewModelTests, and ~60 fixed sleeps on the same view model. Recommend a follow-up ticket.Ready to push
All eight items from the first round are resolved in 4f65ae0b and verified against the code: SubmissionGate.wait() is wrapped in withTaskCancellationHandler and both guard tests #require the count after the spin; yieldUntil's bound is 1,000 (the Core precedent); testing.md no longer claims the recorder lock fixed theFollowUpChainIsBounded and credits PassGate/ReadGate; the inert urlDefinition assertion, the callLog append, the pointer comment and the duplicated seven-line comments are all as described. The production guard is correct and changes no observable state transition; the gate is race-free under every cancellation ordering; the ten suites touched pass (187 tests, 0 failures) on a simulator of their own. What remains is minor: two wording slips in the testing.md entry (a stale clause that contradicts a later paragraph, and "above" for a section that is below), a test comment that names the wrong reason for its ordering guarantee, one sibling test (obsoleteGenerationCannotPublish) whose post-call guard is now exercised by nothing, and the same latent shape left in four duplicate-guard tests, three unbounded spins and ~60 fixed sleeps that the ticket's scope did not cover. None of it blocks the push; the two doc lines are worth a one-line fix first and the rest a follow-up ticket.
a492a1d1 T-2327: Fix five timing-dependent AsterismTests flakes ac3ac8ef T-2327: Pin the pre-call preview guard and share yieldUntil 4f65ae0b T-2327: Review round 2 — cancellation-aware gate, honest chain note, Core spin bound Five unit tests in the app's test bundle would occasionally fail when the whole suite ran on a busy machine, even though nothing was wrong with the code they tested. Each of them assumed something about timing: that two operations started back-to-back would overlap, or that a background job would be finished within 30 milliseconds. On a quiet machine those assumptions hold; under load they sometimes do not, and the test reports a failure that looks like a real bug.
This branch rewrites those tests so they wait for the actual event they care about instead of guessing how long it takes, and it adds two small shared helpers for that: SubmissionGate, which lets a test deliberately hold one operation open while it starts a second one, and yieldUntil, which repeatedly hands control back to the system until a condition becomes true.
While doing that, the author found a real (if rare) bug in the app: a preview request that had already been cancelled could still call the library before noticing it was cancelled. A one-line guard now checks for cancellation before the call as well as after, and a new test pins that behaviour.
A test that fails at random teaches everyone to ignore failures. The project's notes had documented these as "known flaky" and every branch since had to argue its way around them. Fixing the root cause means a red test is worth investigating again. The production guard also stops wasted work: a cancelled preview no longer costs a library call.
isSubmitting) that makes a second tap of a Save button do nothing while the first is still in progress. To test it you need the first submission to still be in progress when the second arrives — which is exactly what the old tests could not guarantee.wait() and open(): anything that calls wait() pauses until someone calls open().ComposedTeachingViewModel.generatePreviewIfValid (production): the previewTask closure now guards !Task.isCancelled && currentGeneration == generation before calling library.projectComposedTeaching, not only after it returns.MockLibraryProvider: createWorkHold and commitReparseHold hooks (the existing commitDecisionHold shape) run after the call is recorded and before the result is returned; createWorkCallCount, commitReparseCallCount, and the six reconcile/duplicate-follow-up recorders become computed properties over recorderLock-guarded storage, following the projectComposedRequests precedent.Helpers/SubmissionGate.swift (new): an NSLock + [CheckedContinuation] one-shot gate whose wait() is wrapped in withTaskCancellationHandler.Helpers/YieldUntil.swift (new): the @MainActor spin helper, 1,000-yield bound, replacing two private copies on main and two more the first commit had added.duplicateCreateSuppressed and duplicateSubmissionSuppressed hold the first call open, spin until the mock has recorded it, #require the count, then drive the second; applyingRegeneratesThePreview and effectiveRuleFollowsSuggestionOnTaughtSide replace Task.sleep(30 ms) with yieldUntil { vm.state == .previewReady }; supersededPreviewNeverReachesTheRepository is new.docs/agent-notes/testing.md: the two "known flaky" sections become one T-2327 entry, with an explicit "not established" paragraph for theFollowUpChainIsBounded.The duplicate-submission guards set isSubmitting synchronously before any suspension, so two async let children only exercise the guard if the second starts while the first is suspended inside the mock. The fix makes that ordering explicit: the mock's hold suspends the first call on the gate, the test spins until the recorded count reads 1, and only then starts the second. The #require after the spin is what turns the bad interleaving (spin exhausted, count still 0) into a failure rather than a hang, and the gate's cancellation handler is what releases the held child when that failure unwinds the async let scope.
The teaching-preview tests wait on the model's own .previewReady transition, which is the signal that previewTask published. That alone still raced once under load: a task cancelled before it ever ran (two edits with no suspension between them) still called the mock on its way to the post-call check and could clobber lastProjectComposedRequest. Hence the production guard.
theFollowUpChainIsBounded flaking. The note says so rather than claiming a fix.yieldUntil's bound is a yield count (1,000, the Core target's awaitRegistration shape), not a wall-clock time. That keeps it deterministic but means a never-satisfied condition costs 1,000 main-actor turns before the following assertion fails.SubmissionGate is the third gate of its kind (PassGate, ReadGate) and the first shared one; the two private ones are left in place rather than migrated.The production guard. updateURLRule runs invalidatePreview() (bumps generation, sets state = .ready) and then Task { await generatePreviewIfValid() }. Two synchronous edits therefore enqueue two main-actor tasks A and B; A creates previewTask A′ (capturing generation N+2, since both edits have run), B cancels A′ and creates B′. A′ runs cancelled. Before this branch it still issued the projection call and only then hit the post-call guard, so the mock recorded a stale request that could land after B′'s. The pre-call guard returns before projectComposedTeaching. Observable state is unchanged: state was already .previewing from the fresh task and B′ publishes or errors as before; cancel() sets .cancelled itself. Because A′ and B′ are enqueued in a fixed order on the main actor's serial executor, supersededPreviewNeverReachesTheRepository is deterministic and asserts the call count, not the last request — both tasks would send fresh, so the request is not a discriminator.
SubmissionGate.wait() installs the cancellation handler before the continuation body runs. If the task is already cancelled the handler fires immediately and sets isOpen, so the body resumes at once; if cancellation lands while the body holds the lock, open() blocks on the same lock and resumes the appended waiter afterwards; if it lands later, the waiter is in the array and open() drains it. Every continuation is resumed exactly once because the array is swapped out under the lock. Cancellation opens the gate for every waiter, which is a one-shot semantics acceptable for a test helper.
The `#require` after the spin. If the spin exhausts with the count still 0, throwing exits the test body, the implicit async let cancels the child, the child's create()/confirm() reaches the mock, the mock awaits the hold, and the now-cancellation-aware wait() returns. Without the cancellation handler the child would suspend forever and the test would hang on the implicit await at scope exit.
Test-side only, except for the ~1-line guard. The mock's recorder pattern (computed property over locked storage) now covers reconcile state too, so tests reading those from a non-main context no longer race against writes from inside a pass. callLog.append inside reconcileAfterSync moves under the lock, matching commitDecision; the rest of callLog remains an unlocked var, which is the existing state of that file.
async let shape (MoveToModelTests.duplicateMoveSuppressed, WorkDetailModelTests save, EntryDetailModelTests update, RuleSuggestionCoordinatorTests activationSweep). They have not been observed flaking, and they are out of the ticket's scope, but the latent race is identical.lastNewWorkDraft and lastCommittedReparseContract are still written outside the lock beside the locked counter — harmless in these tests (read only after the await), but not the fully consistent shape.theFollowUpChainIsBounded failure is explicitly not established; the note gives the next place to look.Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swift
Why it matters. The only production change. A preview task cancelled before its first suspension point no longer calls the repository; previously it did and could clobber whatever a caller read off the fresh request. Also stops one wasted projection per superseded edit.
What to look at. ComposedTeachingViewModel.swift:1220-1230
Asterism/AsterismTests/Helpers/SubmissionGate.swift
Why it matters. The primitive the two duplicate-submission tests hang their determinism on. Its wait() must release a held task on cancellation or a bad interleaving turns into a suite hang.
What to look at. SubmissionGate.swift:25-58
Asterism/AsterismTests/MoveToAndNewWorkModelTests.swift
Why it matters. This sequence is what makes the isSubmitting guard actually exercised rather than hoped for. The #require between the spin and the second async let is load-bearing.
What to look at. MoveToAndNewWorkModelTests.swift:197-210; ReparseViewModelTests.swift:222-235
Asterism/AsterismTests/Helpers/MockLibraryProvider.swift
Why it matters. Six recorders become lock-backed computed properties, and reconcileAfterSync/takeDuplicateFollowUp/armDuplicateFollowUp mutate under one critical section. The note is explicit that this is consistency, not the fix for theFollowUpChainIsBounded.
What to look at. MockLibraryProvider.swift:575-645
Asterism/AsterismTests/Helpers/YieldUntil.swift
Why it matters. Replaces four private copies (two on main, two added by the first commit) and the two 30 ms sleeps. The 1,000-yield bound matches SyncMonitorTests.awaitRegistration and BackgroundExportPassTests.awaitWaiting in the Core target.
What to look at. YieldUntil.swift:16-21
docs/agent-notes/testing.md
Why it matters. The two 'known flaky' sections that every branch argued around are replaced. Getting the claim right matters: an over-claim would send the next investigator away from the real cause.
What to look at. testing.md:91-163
The guard is set synchronously, so only a first call that is observably in flight exercises it. A longer sleep would only move the race. Source: commit a492a1d1, SubmissionGate doc comment.
Both preview tasks build their request after both edits, so the superseded one would also send fresh; lastProjectComposedRequest cannot discriminate. The inert urlDefinition assertion from the first draft was dropped with a comment saying why. Source: test comment, commit 4f65ae0b.
The stale call is wasted work and a real ordering race, not just a test seam. The post-call guard stays because cancellation can also land mid-projection. Source: inline comment in generatePreviewIfValid, commit a492a1d1.
The follow-up chain is strictly sequential (each successor starts inside its predecessor and the test awaits waitForDuplicateFollowUp()), so no two writes were ever concurrent. The note records the 2026-09-06 failure as unexplained and points at the chain's actor hops. Source: commit 4f65ae0b, testing.md.
Two suites need the shared gate; the two existing private ones (an actor with one waiter in EmptyLibraryModelTests, a lock-and-waiters class in the Core target) are credited as prior art rather than migrated. The Core one cannot share a file with the app test bundle in any case. Source: SubmissionGate doc comment; the non-migration is inferred.
A yield count is a scheduling bound, not a time; the Core target's awaitRegistration / awaitWaiting already use 1,000. Source: YieldUntil.swift doc comment, commit 4f65ae0b.
duplicateMoveSuppressed, the work-detail save guard, the entry-detail update guard and the activation-sweep guard keep the shape this branch replaces elsewhere. They were not among the five observed flakes and the ticket is scoped to those five. Not stated by the author.
| Severity | Area | Finding | Resolution |
|---|---|---|---|
| minor | docs/agent-notes/testing.md:129 | "replaced their sleep with yieldUntil { ... } — using the private spin helper that file had on main" is stale since ac3ac8ef: both teaching-preview tests call the shared Helpers/YieldUntil.swift, and the paragraph at lines 144-149 says so. The two contradict each other in the entry the first round asked to be made honest. | Drop the clause, or say "then that file's private helper, shared since the second commit (below)". Not applied: review is read-only per instructions. |
| minor | ComposedTeachingViewModelTests.swift:445-464 obsoleteGenerationCannotPublish | Both setURLRuleDefinition calls run before either preview task is created (edits enqueue Task { await generatePreviewIfValid() }), so composedProjectionDelay is already nil when the 'slow' task would call the mock — the 150 ms delay never engages (pre-existing on main). On main the superseded task still reached the post-call guard, which is what kept the test meaningful; with the pre-call guard it exits before the call, so the post-call guard (line ~1238) is now exercised by no test, and this one only fails if both guards are removed. Its 250 ms + 30 ms of sleep buys nothing. | Follow-up: keep the delay set, yieldUntil { mock.projectComposedTeachingCallCount == n + 1 } so the slow call is observably in flight, then make the fast edit and yieldUntil { vm.previewGeneration == fastGeneration }. That pins the post-call guard deterministically. Out of T-2327's five; ticket it. |
| minor | ComposedTeachingViewModelTests.swift:475-477 supersededPreviewNeverReachesTheRepository comment | The ordering is deterministic, but the comment names the wrong reason. 'The main actor is a serial executor' does not by itself give FIFO; the test relies on Task {} created from main-actor isolation being enqueued on the main actor in creation order at equal priority, so the queue reads [A, B], A schedules A', B cancels A' before A' runs. Swift does not document that as a guarantee. Also, both tasks capture the same generation (g+2), so only the cancel half of the guard is what this test exercises. | Reword to say the test relies on FIFO enqueue of same-priority tasks from one isolation, and that the generation half is not what it pins. Keep the test; there is no better seam without changing production. |
| minor | Sibling tests on the diagnosed shape (out of scope) | The note declares the family closed, but the same root cause is still live elsewhere: four two-async-let guard tests (MoveToModelTests.duplicateMoveSuppressed :126, WorkDetailModelTests :110-118, EntryDetailModelTests :715-727, CharacterReviewModelTests :1144-1152 — the last already has commitDecisionHold, so it is the cheapest to convert); three unbounded `while … { await Task.yield() }` spins (CharacterReviewModelTests:806, RuleSuggesterTests:385, RuleSuggestionCoordinatorTests:597 — the file whose private yieldUntil this branch deleted); a byte-for-byte yieldUntil clone at WorkDetailFindCoverTests:354-357; the inline AsyncStream gate at CharacterReviewModelTests:802-804, which is the direct precedent for the *Hold-plus-gate pattern and is not cancellation-aware; and ~31 fixed sleeps in ComposedTeachingViewModelTests plus ~28 in ComposedTeachingPreviewTests/OptionalSequenceTeachingMessagesTests of the `await vm.load(); Task.sleep(30-50 ms); #require(mock.lastProjectComposedRequest)` shape. | Not for this branch — the ticket is scoped to the five that failed, and a ~60-site sweep is its own change. Open a follow-up ticket so the family is not re-documented as 'known flaky' when one of these fires. |
| nit | docs/agent-notes/testing.md:96 | "the store-digest family above" — that section ("Fixed (T-2293): the store-digest comparisons") is at line 205, below the new entry at line 91. The text it replaced said "below". | "below". |
| nit | SubmissionGate.swift:21-24 and testing.md 'third gate of its kind' | Undercounts. Besides PassGate and ReadGate there is a DispatchSemaphore Gate (AppLibraryModelBackgroundExportTests:80, needed because it is called from a synchronous factory), StubSuggester.isGated/openGate (RuleSuggestionCoordinatorTests:41-56, re-armable), and the inline AsyncStream gate above. ReadGate cannot be shared (Core test target, no shared test-support product), and PassGate has a latent defect SubmissionGate fixes: a second wait() overwrites the stored continuation and leaks the first. | Either correct the count or say which two are candidates to migrate. Optional. |
| nit | Helpers/YieldUntil.swift:17-20 | `for _ in 0..<1_000 where !condition()` filters iterations rather than stopping: once the condition holds the loop keeps evaluating condition() synchronously for the remaining iterations (up to 1,000 lock acquisitions on a locked counter). Harmless — nothing yields between them — but "costs nothing when the condition is already true" is slightly overstated, and the bound is turns not time: a never-satisfied condition fails in ~10-50 ms on an idle actor and is not suited to waiting on wall-clock work off-actor. Inherited from the Core precedent. | Optional: `while !condition(), spins < 1_000` (main's shape), or one sentence in the doc comment that it is not for wall-clock waits. |
| nit | MockLibraryProvider.swift:167-168, 669-670 | lastNewWorkDraft / lastCommittedReparseContract are written outside recorderLock beside the locked counter; commitDecision keeps its record inside the lock. Safe here (every reader awaits the call first), but it is the shape the lock section of testing.md (line 188) warns about. Also `exportInputDelay` (:228) is a sleep-based hold the hook pattern supersedes. | Move the two assignments into the withLock block, or leave a one-line comment. Optional. |
Source: local run at 2026-09-22T15:47:11+10:00 · snapshot 4f65ae0b0fd90dc7cc2e1322959493eb17b2c1a5
Baseline: none
Execution: passed · JUnit: 1 file · Coverage: none · Baseline: absent
Coverage scope: as the project configures it
Totals: 187 passed · 0 failed · 0 skipped · 0 errored · 0 flaky
Derived by declaration name, from the diff (no baseline run).
Files that import a changed file on the left, changed files in the centre, files a changed file imports on the right. Snapshot working-tree against base 640830ae63a6c7de18c2fe738205f87152e00e24.
Click to expand.
diff --git a/Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swift b/Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swiftindex 37321a4f..c06697e7 100644--- a/Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swift+++ b/Asterism/Asterism/ViewModels/ComposedTeachingViewModel.swift@@ -1217,6 +1217,17 @@ public final class ComposedTeachingViewModel { state = .previewing previewTask = Task { [weak self] in guard let self else { return }+ // Checked *before* the projection call, not only after: a preview+ // cancelled in the same turn it was scheduled (an edit followed+ // immediately by another, or a suggestion applied right after+ // `load()`'s own initial preview) is superseded before this task+ // ever runs, and calling the repository anyway is both wasted+ // work and a race — a stale call can still land *after* the+ // fresh one that superseded it, clobbering whatever a caller+ // reads off the request the fresh preview was built from+ // (T-2327). The post-call check stays: cancellation can still+ // land while the projection itself is in flight.+ guard !Task.isCancelled, currentGeneration == self.generation else { return } let signpostID = Self.performanceSignposter.makeSignpostID() let signpostState = Self.performanceSignposter.beginInterval( "ComposedFinalPreviewPublication", id: signpostID)
diff --git a/Asterism/AsterismTests/ComposedTeachingViewModelTests.swift b/Asterism/AsterismTests/ComposedTeachingViewModelTests.swiftindex 80929e28..a805035f 100644--- a/Asterism/AsterismTests/ComposedTeachingViewModelTests.swift+++ b/Asterism/AsterismTests/ComposedTeachingViewModelTests.swift@@ -463,6 +463,33 @@ struct ComposedTeachingViewModelTests { #expect(vm.previewGeneration == fastGeneration) } + @Test("A preview superseded before it runs never reaches the repository (T-2327)")+ func supersededPreviewNeverReachesTheRepository() async throws {+ let (vm, mock) = makeSUT()+ await vm.load()+ await yieldUntil { vm.state == .previewReady }+ let callsBeforeEdits = mock.projectComposedTeachingCallCount++ // Two edits with no suspension between them: the first preview task is+ // cancelled by the second before it ever runs. The main actor is a+ // serial executor, so the ordering is fixed — this is not a race the+ // test hopes to win. Without the pre-call guard the cancelled task+ // still calls the repository on its way to the post-call check, and+ // the count below reads two.+ let stale = URLRuleDefinition.sequence(locator: .query(name: ExactScalarString("stale")))+ let fresh = URLRuleDefinition.sequence(locator: .query(name: ExactScalarString("fresh")))+ vm.setURLRuleDefinition(stale)+ vm.setURLRuleDefinition(fresh)+ await yieldUntil { vm.state == .previewReady }++ // The call count is what pins the fix. `lastProjectComposedRequest`+ // would read `fresh` with or without the guard: both tasks build their+ // request after both edits, so the superseded one would send `fresh`+ // too — it is the call itself that must not happen.+ #expect(mock.projectComposedTeachingCallCount == callsBeforeEdits + 1)+ #expect(vm.previewGeneration == vm.generation)+ }+ @Test("Cancel before any edit leaves the surface cancelled") func cancelLeavesCancelled() async { let (vm, mock) = makeSUT()@@ -1034,16 +1061,6 @@ struct ComposedTeachingViewModelTests { return (coordinator, suggester) } - /// Spins the main actor until the condition holds. The on-open delivery is a- /// child task, so there is something to wait for but nothing to sleep on.- private func yieldUntil(_ condition: () -> Bool) async {- var spins = 0- while !condition(), spins < 200 {- await Task.yield()- spins += 1- }- }- @Test("A held suggestion seeds both untaught sides and marks them") func heldSuggestionSeedsUntaughtSides() async throws { let held = Self.suggestion(title: try Self.suggestedTitle(), url: Self.suggestedURL)@@ -1201,11 +1218,18 @@ struct ComposedTeachingViewModelTests { await vm.load() await vm.requestSuggestion()- try await Task.sleep(for: .milliseconds(30))+ // `generatePreviewIfValid()` is fire-and-forget: it schedules+ // `previewTask` and returns without awaiting it, so the mock call it+ // makes is still in flight when `requestSuggestion()` returns. A+ // fixed sleep assumed it would land within 30 ms, which does not hold+ // under full-suite load (T-2327); `.previewReady` is the model's own+ // signal that the task published.+ await yieldUntil { vm.state == .previewReady } #expect(vm.effectiveTitleRule?.definition == suggested.definition) let request = try #require(mock.lastProjectComposedRequest) #expect(request.titleDefinition == suggested.definition)+ #expect(vm.state == .previewReady) } @Test("A rule the opened capture cannot depict restores the snapshot and raises no notice")@@ -1409,7 +1433,13 @@ struct ComposedTeachingViewModelTests { let (vm, mock) = makeSUT(entry: Self.suggestionEntry(), suggestions: coordinator) await vm.load()- try await Task.sleep(for: .milliseconds(30))+ // `load()` seeds the held suggestion and re-previews through the same+ // fire-and-forget `previewTask` `requestSuggestion()` uses, so it can+ // still be in flight when `load()` returns. Waiting on the model's+ // own `.previewReady` signal replaces the fixed sleep that assumed it+ // would land within 30 ms — which does not hold under full-suite load+ // (T-2327).+ await yieldUntil { vm.state == .previewReady } let request = try #require(mock.lastProjectComposedRequest) #expect(request.titleDefinition == held.title?.definition)
diff --git a/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift b/Asterism/AsterismTests/Helpers/MockLibraryProvider.swiftindex 59135779..4c012d6d 100644--- a/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift+++ b/Asterism/AsterismTests/Helpers/MockLibraryProvider.swift@@ -16,7 +16,6 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable { var workCallCount = 0 var updateEntryCallCount = 0 var deleteEntryCallCount = 0- var createWorkCallCount = 0 var updateWorkCallCount = 0 var moveEntryCallCount = 0 var workDestinationsCallCount = 0@@ -149,10 +148,25 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable { /// What the new-Work form sent. A Work is born on exactly one site (Req /// 3.3), so the hostname it carries is the membership the repository mints. var lastNewWorkDraft: NewWorkDraft?+ /// Recorded under `recorderLock`, like the composed-teaching and+ /// rule-suggestion recorders: a test holding this call open with+ /// `createWorkHold` needs to see the increment the instant the call has+ /// landed, before the hold releases it — not after two `Task`s have+ /// happened to interleave under load (T-2327).+ var createWorkCallCount: Int {+ recorderLock.withLock { storedCreateWorkCallCount }+ }+ private var storedCreateWorkCallCount = 0+ /// Runs after the call is recorded and before the result is returned, so a+ /// test can hold one submission open while it drives a second and observes+ /// the duplicate-submission guard deterministically instead of relying on+ /// a sleep or an assumed interleaving.+ var createWorkHold: (@Sendable () async -> Void)? func createWork(_ draft: NewWorkDraft) async throws -> WorkSnapshot {- createWorkCallCount += 1+ recorderLock.withLock { storedCreateWorkCallCount += 1 } lastNewWorkDraft = draft+ if let hold = createWorkHold { await hold() } return try createWorkResult.get() } @@ -472,8 +486,16 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable { var projectReparseCallCount = 0 var commitReparseResult: Result<ReparseCommitOutcome, Error> = .failure(MockError.notConfigured)- var commitReparseCallCount = 0+ /// Recorded under `recorderLock` for the same reason `createWorkCallCount`+ /// is (T-2327).+ var commitReparseCallCount: Int {+ recorderLock.withLock { storedCommitReparseCallCount }+ }+ private var storedCommitReparseCallCount = 0 var lastCommittedReparseContract: ReparseContract?+ /// Runs after the call is recorded and before the result is returned —+ /// `createWorkHold`'s counterpart for the re-parse sheet's guard.+ var commitReparseHold: (@Sendable () async -> Void)? var projectCaptureResult: Result<CaptureContract, Error> = .failure(MockError.notConfigured) var projectCaptureCallCount = 0@@ -550,43 +572,76 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable { return interruptedImportReport } - var reconcileAfterSyncCallCount = 0 var reconcileAfterSyncResult: Result<ReconciliationOutcome, Error> = .success( ReconciliationOutcome())+ /// The follow-up chain drives several sequential passes and reads its own+ /// recorded state back to decide the next one (`scheduleDuplicateFollowUpIfNeeded`,+ /// `scheduleDuplicateSuccessorIfNeeded`), and a test reads it again after+ /// `waitForDuplicateFollowUp()` — all under `recorderLock`, like the+ /// composed-teaching and rule-suggestion recorders, so neither a write from+ /// inside a pass nor the test's read can tear (T-2327).+ var reconcileAfterSyncCallCount: Int {+ recorderLock.withLock { storedReconcileAfterSyncCallCount }+ } /// The tiers `reconcileAfterSync` was called with, in order (Q53/Q58).- var reconcileAfterSyncTiers: [ReconcilePassTier] = []+ var reconcileAfterSyncTiers: [ReconcilePassTier] {+ recorderLock.withLock { storedReconcileAfterSyncTiers }+ } /// What `takeDuplicateFollowUp()` reports, and how many times it was asked.- var duplicateFollowUpNeeded = false- var takeDuplicateFollowUpCallCount = 0- var armDuplicateFollowUpCallCount = 0+ var duplicateFollowUpNeeded: Bool {+ get { recorderLock.withLock { storedDuplicateFollowUpNeeded } }+ set { recorderLock.withLock { storedDuplicateFollowUpNeeded = newValue } }+ }+ var takeDuplicateFollowUpCallCount: Int {+ recorderLock.withLock { storedTakeDuplicateFollowUpCallCount }+ }+ var armDuplicateFollowUpCallCount: Int {+ recorderLock.withLock { storedArmDuplicateFollowUpCallCount }+ } /// How many of the passes from here on re-arm the latch, standing in for a /// deleting commit that aborted (Req 2.9). `.max` never stops re-arming, /// which is what the chain bound has to survive.- var duplicateFollowUpNeededAfterReconcileCount = 0+ var duplicateFollowUpNeededAfterReconcileCount: Int {+ get { recorderLock.withLock { storedDuplicateFollowUpNeededAfterReconcileCount } }+ set { recorderLock.withLock { storedDuplicateFollowUpNeededAfterReconcileCount = newValue } }+ }++ private var storedReconcileAfterSyncCallCount = 0+ private var storedReconcileAfterSyncTiers: [ReconcilePassTier] = []+ private var storedDuplicateFollowUpNeeded = false+ private var storedTakeDuplicateFollowUpCallCount = 0+ private var storedArmDuplicateFollowUpCallCount = 0+ private var storedDuplicateFollowUpNeededAfterReconcileCount = 0 @discardableResult func reconcileAfterSync(tier: ReconcilePassTier) async throws -> ReconciliationOutcome {- reconcileAfterSyncCallCount += 1- reconcileAfterSyncTiers.append(tier)- callLog.append("reconcileAfterSync")- if duplicateFollowUpNeededAfterReconcileCount > 0 {- if duplicateFollowUpNeededAfterReconcileCount != .max {- duplicateFollowUpNeededAfterReconcileCount -= 1+ recorderLock.withLock {+ storedReconcileAfterSyncCallCount += 1+ storedReconcileAfterSyncTiers.append(tier)+ if storedDuplicateFollowUpNeededAfterReconcileCount > 0 {+ if storedDuplicateFollowUpNeededAfterReconcileCount != .max {+ storedDuplicateFollowUpNeededAfterReconcileCount -= 1+ }+ storedDuplicateFollowUpNeeded = true }- duplicateFollowUpNeeded = true+ callLog.append("reconcileAfterSync") } return try reconcileAfterSyncResult.get() } func takeDuplicateFollowUp() async -> Bool {- takeDuplicateFollowUpCallCount += 1- defer { duplicateFollowUpNeeded = false }- return duplicateFollowUpNeeded+ recorderLock.withLock {+ storedTakeDuplicateFollowUpCallCount += 1+ defer { storedDuplicateFollowUpNeeded = false }+ return storedDuplicateFollowUpNeeded+ } } func armDuplicateFollowUp() async {- armDuplicateFollowUpCallCount += 1- duplicateFollowUpNeeded = true+ recorderLock.withLock {+ storedArmDuplicateFollowUpCallCount += 1+ storedDuplicateFollowUpNeeded = true+ } } func projectInitialTeaching(hostname: String, patternDefinition: PatternDefinition) async throws -> TeachingContract {@@ -611,8 +666,9 @@ final class MockLibraryProvider: LibraryProviding, @unchecked Sendable { } func commitReparse(_ contract: ReparseContract) async throws -> ReparseCommitOutcome {- commitReparseCallCount += 1+ recorderLock.withLock { storedCommitReparseCallCount += 1 } lastCommittedReparseContract = contract+ if let hold = commitReparseHold { await hold() } return try commitReparseResult.get() }
diff --git a/Asterism/AsterismTests/Helpers/SubmissionGate.swift b/Asterism/AsterismTests/Helpers/SubmissionGate.swiftnew file mode 100644index 00000000..5a685108--- /dev/null+++ b/Asterism/AsterismTests/Helpers/SubmissionGate.swift@@ -0,0 +1,58 @@+import Foundation++/// A one-shot gate a test hands to a mock's `*Hold` hook, so a submission can+/// be held open deliberately while the test drives a second one and observes+/// a duplicate-submission guard — the deterministic alternative to a fixed+/// sleep and an assumed `Task` interleaving that may not happen under+/// full-suite load (T-2327).+///+/// The guards under test set `isSubmitting` synchronously before the mock is+/// ever called, so the second call only exercises one while the first is+/// still in flight — and two bare `Task`s have no guarantee of that under+/// load; the first can finish before the second starts, and then both+/// commit. Holding the first call open and spinning until the mock has+/// recorded it makes the ordering explicit. The `#require` on the count that+/// follows the spin is load-bearing: if the spin ran out first, the *second*+/// call could be the one held, and awaiting it would never return. The+/// `#require` turns that into a failure; the cancellation handler in `wait()`+/// is the backstop, so a waiter whose task is cancelled is let through+/// rather than left suspended for good.+///+/// The third of its kind: `EmptyLibraryModelTests` has a private `PassGate`+/// (an actor, one waiter) and `CaptureStateTests` in the Core target a+/// private `ReadGate` (this lock-and-waiters shape). Shared because two+/// suites need it.+final class SubmissionGate: @unchecked Sendable {+ private let lock = NSLock()+ private var isOpen = false+ private var waiters: [CheckedContinuation<Void, Never>] = []++ /// Suspends until `open()` is called — or returns immediately if it+ /// already was, or if the calling task is already cancelled. A+ /// cancellation that lands while suspended opens the gate.+ func wait() async {+ await withTaskCancellationHandler {+ await withCheckedContinuation { continuation in+ let resumeNow = lock.withLock { () -> Bool in+ guard !isOpen, !Task.isCancelled else { return true }+ waiters.append(continuation)+ return false+ }+ if resumeNow { continuation.resume() }+ }+ } onCancel: {+ open()+ }+ }++ /// Releases every call currently suspended in `wait()`, and lets any+ /// later call through without suspending.+ func open() {+ let waiting = lock.withLock { () -> [CheckedContinuation<Void, Never>] in+ isOpen = true+ defer { waiters = [] }+ return waiters+ }+ for waiter in waiting { waiter.resume() }+ }+}
diff --git a/Asterism/AsterismTests/Helpers/YieldUntil.swift b/Asterism/AsterismTests/Helpers/YieldUntil.swiftnew file mode 100644index 00000000..365e1269--- /dev/null+++ b/Asterism/AsterismTests/Helpers/YieldUntil.swift@@ -0,0 +1,21 @@+import Foundation++/// Spins the main actor until `condition` holds, or until the bound is+/// reached. No wall-clock sleep is involved: it costs nothing when the+/// condition is already true, and a model that never gets there fails the+/// assertion that follows rather than hanging the suite.+///+/// This is the deterministic alternative to a fixed sleep for a+/// fire-and-forget child task — a coordinator's on-open delivery, a view+/// model's `previewTask`, a held call's first observation — where there is+/// something to wait for but nothing to sleep on (T-2293, T-2327).+///+/// The bound is a count of yields, not a time, and matches the Core target's+/// `awaitRegistration` / `awaitWaiting` (`SyncMonitorTests`,+/// `BackgroundExportPassTests`): 1,000 turns of the main actor.+@MainActor+func yieldUntil(_ condition: () -> Bool) async {+ for _ in 0..<1_000 where !condition() {+ await Task.yield()+ }+}
diff --git a/Asterism/AsterismTests/MoveToAndNewWorkModelTests.swift b/Asterism/AsterismTests/MoveToAndNewWorkModelTests.swiftindex 7dc24fa4..b758b299 100644--- a/Asterism/AsterismTests/MoveToAndNewWorkModelTests.swift+++ b/Asterism/AsterismTests/MoveToAndNewWorkModelTests.swift@@ -187,15 +187,26 @@ struct NewWorkFormModelTests { } @Test("Duplicate create is suppressed")- @MainActor func duplicateCreateSuppressed() async {+ @MainActor func duplicateCreateSuppressed() async throws { let mock = MockLibraryProvider() mock.createWorkResult = .success(TestFixtures.makeWork()) let model = NewWorkFormModel(library: mock, onMutation: {}) model.draftTitle = "Work" model.draftHostname = "example.com"++ // The first `create()` is held open while the second meets the guard;+ // `SubmissionGate` says why, and why the `#require` follows the spin.+ let gate = SubmissionGate()+ mock.createWorkHold = { await gate.wait() }+ async let first: () = model.create()+ await yieldUntil { mock.createWorkCallCount == 1 }+ try #require(mock.createWorkCallCount == 1) async let second: () = model.create()- _ = await (first, second)+ _ = await second+ gate.open()+ _ = await first+ #expect(mock.createWorkCallCount == 1) } }
diff --git a/Asterism/AsterismTests/ReparseViewModelTests.swift b/Asterism/AsterismTests/ReparseViewModelTests.swiftindex 3a136cc2..74bc6e2d 100644--- a/Asterism/AsterismTests/ReparseViewModelTests.swift+++ b/Asterism/AsterismTests/ReparseViewModelTests.swift@@ -215,12 +215,23 @@ struct ReparseViewModelTests { } @Test("Duplicate submission is suppressed")- @MainActor func duplicateSubmissionSuppressed() async {+ @MainActor func duplicateSubmissionSuppressed() async throws { let (model, mock, _) = makeSUT() await model.load()++ // The first `confirm()` is held open while the second meets the guard;+ // `SubmissionGate` says why, and why the `#require` follows the spin.+ let gate = SubmissionGate()+ mock.commitReparseHold = { await gate.wait() }+ async let first: () = model.confirm()+ await yieldUntil { mock.commitReparseCallCount == 1 }+ try #require(mock.commitReparseCallCount == 1) async let second: () = model.confirm()- _ = await (first, second)+ _ = await second+ gate.open()+ _ = await first+ #expect(mock.commitReparseCallCount == 1) }
diff --git a/Asterism/AsterismTests/RuleSuggestionCoordinatorTests.swift b/Asterism/AsterismTests/RuleSuggestionCoordinatorTests.swiftindex 59d39ebf..26758b01 100644--- a/Asterism/AsterismTests/RuleSuggestionCoordinatorTests.swift+++ b/Asterism/AsterismTests/RuleSuggestionCoordinatorTests.swift@@ -165,18 +165,6 @@ struct RuleSuggestionCoordinatorTests { return (coordinator, mock, suggester, environment, client) } - /// Spins the main actor until `condition` holds, or until the bound is- /// reached. No wall-clock sleep is involved: it costs nothing when the- /// condition is already true, and a coordinator that never gets there fails- /// the assertion that follows rather than hanging the suite.- private func yieldUntil(_ condition: () -> Bool) async {- var spins = 0- while !condition(), spins < 100 {- await Task.yield()- spins += 1- }- }- // MARK: - The activation sweep (Req 5.1) @Test("The sweep attempts the three most recent auto-eligible hostnames, newest first")
diff --git a/docs/agent-notes/testing.md b/docs/agent-notes/testing.mdindex 8183a806..8ae843d1 100644--- a/docs/agent-notes/testing.md+++ b/docs/agent-notes/testing.md@@ -88,47 +88,79 @@ Check for another run first (`ps -axo pid,etime,command | grep xcodebuild`), and give a concurrent run a simulator of its own: `make test-quick SIMULATOR='iPhone 17 Pro,OS=26.5'`. The same run is green there. -## Known flaky family: the double-submission guards, and the async-chain counts--Several `AsterismTests` cases assert a **call count** on a `MockLibraryProvider`-that is only correct if two `Task`s interleave the way they do on an unloaded-machine. Under full-suite load they intermittently do not, and the failure reads-like a real defect: a count one higher (or lower) than expected.--- `ReparseViewModelTests.duplicateSubmissionSuppressed`- (`mock.commitReparseCallCount → 2`), seen 2026-08-12 on a branch whose only- change was the share extension plist.-- `NewWorkFormModelTests.duplicateCreateSuppressed`- (`mock.createWorkCallCount → 2`), seen 2026-09-06 on the `T-2308` branch,- whose changes are entirely in the work detail and the merge model.-- `AppLibraryModelSyncArrivalTests.theFollowUpChainIsBounded`- (`reconcileAfterSyncTiers.count`), seen 2026-09-06 on the same branch.--**How it presents**: a *different* one of them fails per run, each passes on an-isolated `make test-only TEST=AsterismTests/<Suite>`, and a repeat full run is-green. Three consecutive full runs on `T-2308` failed-`ComposedTeachingViewModelTests` (two cases), then-`theFollowUpChainIsBounded`, then nothing — the same "different name each run"-signature the store-digest family below has.--One isolated failure of any of these is not a regression signal. Rerun the suite-alone, then rerun the full pass; only a failure that repeats in the same place-is worth investigating.--## Known flaky unit test: "Applying a suggestion regenerates the preview for the whole hostname"--`ComposedTeachingViewModelTests.applyingRegeneratesThePreview` (AsterismTests,-simulator) sleeps 30 ms after `load()` and then asserts the held suggestion has-been applied to the projection request. Under full-suite load the apply had not-landed yet and the request still carried the `.segment` definition — seen-2026-09-05 on the T-2301 branch, whose changes are entirely in entry detail. It-passed on an isolated rerun of the suite and in two full runs the same day. One-isolated failure of this test is not a regression signal; rerun before-investigating.--`ComposedTeachingViewModelTests.effectiveRuleFollowsSuggestionOnTaughtSide` fails-the same way and for the same reason (seen 2026-09-06, T-2308); it belongs to-the family above.+## T-2327: the double-submission guards, the teaching preview sleeps, and the async-chain count++Five `AsterismTests` cases used to fail intermittently under full-suite load,+each passing on an isolated `make test-only TEST=AsterismTests/<Suite>` and on+a repeat full run — the same "a different one fails each time" signature the+store-digest family above has. Documented here from 2026-08-12 as two "known+flaky" sections and argued-around by every branch since. T-2327 (2026-09-22)+fixed four of them with a root cause in hand; the fifth got a consistency+change and an honest note, below.++- `ReparseViewModelTests.duplicateSubmissionSuppressed` and+ `NewWorkFormModelTests.duplicateCreateSuppressed` drove the guard with two+ bare `async let`s and asserted `mock.commitReparseCallCount` /+ `mock.createWorkCallCount == 1`. The guard (`isSubmitting`) is set+ synchronously before the mock is ever called, so the assertion is only+ exercising it if the second call runs while the first is still in flight —+ and two unstructured `Task`s have no guarantee of that under load; the first+ can simply finish before the second starts, and then both commit.+- `ComposedTeachingViewModelTests.applyingRegeneratesThePreview` and+ `effectiveRuleFollowsSuggestionOnTaughtSide` slept 30 ms after `load()` /+ `requestSuggestion()` before reading `mock.lastProjectComposedRequest`.+ Both call paths schedule `generatePreviewIfValid()`'s `previewTask`+ fire-and-forget rather than awaiting it, so the mock call it makes can+ still be in flight when the sleep's 30 ms run out.++**The fix**: `MockLibraryProvider` gained `createWorkHold` and+`commitReparseHold` (the `commitDecisionHold` shape) so a test can pause a+call open and observe the guard deterministically, plus a `SubmissionGate`+helper (`Helpers/SubmissionGate.swift`) to drive them. It is the third gate+of its kind — `EmptyLibraryModelTests` has a private `PassGate` and+`CaptureStateTests` in the Core target a private `ReadGate` — and the first+shared one. Its `wait()` is cancellation-aware, and each test `#require`s the+call count after its spin: without that, a spin that ran out before the+first call landed could leave the *second* call as the held one, and the+test would hang on it instead of failing. The two teaching-preview tests+replaced their sleep with `yieldUntil { vm.state == .previewReady }` — the+model's own signal that the fire-and-forget preview task published — using+the private spin helper that file had on `main`.++Waiting for `.previewReady` alone still flaked once under load (2026-09-22): a+*superseded* `previewTask` — cancelled before it ever ran, because nothing+suspended between scheduling it and invalidating it — was still calling+`projectComposedTeaching` on its way to the post-call cancellation check, and+could land *after* the fresh task that replaced it, clobbering+`mock.lastProjectComposedRequest` with the stale request. That is a real+`ComposedTeachingViewModel` bug, not just a test seam: `generatePreviewIfValid`+now checks `Task.isCancelled`/`generation` **before** the projection call too,+so a task cancelled ahead of its first suspension point never reaches the+repository at all. `supersededPreviewNeverReachesTheRepository` pins that+deterministically: two edits with no suspension between them, one projection+call.++The spin helper now lives in `Helpers/YieldUntil.swift`. `main` had two+private copies (`RuleSuggestionCoordinatorTests`,+`ComposedTeachingViewModelTests`); T-2327's first commit added two more+before its second consolidated all four. Its bound is 1,000 yields, the+count the Core target's `awaitRegistration` / `awaitWaiting` use — a+scheduling bound, not a time.++**Not established: `AppLibraryModelSyncArrivalTests.theFollowUpChainIsBounded`**+(`mock.reconcileAfterSyncTiers.count`, seen once on 2026-09-06 on the `T-2308`+branch). T-2327 moved `MockLibraryProvider`'s reconcile recorders+(`reconcileAfterSyncTiers`, `reconcileAfterSyncCallCount`, the+duplicate-follow-up latch) under `recorderLock`, the `projectComposedRequests`+precedent — but that is consistency with the other recorders, not a fix for+this failure. The chain the test exercises is strictly sequential: the test+awaits `waitForDuplicateFollowUp()`, which awaits each link's `task.value`,+and each successor is started from inside its predecessor, so no two writes+to those recorders were ever concurrent. Whatever produced the wrong count+that day is not identified. If it recurs, the recorder lock has already been+ruled out; look at the chain itself (`scheduleDuplicateFollowUpIfNeeded`,+`scheduleDuplicateSuccessorIfNeeded`, the `duplicateFollowUpTask == nil`+re-checks across their actor hops) with the failing count in hand. ## `bootstrap()` no longer publishes the works snapshot; await `waitForLaunchTail()`
SubmissionGate.wait() cancellation-aware: withTaskCancellationHandler { … } onCancel: { open() }, plus in-lock Task.isCancelled check — yes.#require after the spin in both guard tests — yes (MoveToAndNewWorkModelTests:203, ReparseViewModelTests:228).yieldUntil bound 1,000 — yes.testing.md no longer claims the lock fixed the chain test — yes, explicit "Not established" paragraph.urlDefinition assertion dropped with a comment — yes.callLog append under the lock — yes.Confirmed the count reads 2 without the guard only because A′ is created (by A) before B runs and B cancels it before A′ runs. If the runtime ever ran A′ ahead of B, A′ would suspend inside the mock and the count would read 2 with the guard. That is a FIFO-at-equal-priority property of main-actor enqueue, not of serial execution. Stable on this toolchain; worth knowing if it ever fires.
Not the full make test-quick: ten suites via make test-only (the five the ticket names plus MoveToModelTests and the four other AppLibraryModel* suites that read the relocked reconcile recorders). The author reports make build-mac and the five suites green; the first round's test-quick.log in this job directory shows MAKE_EXIT=0 on the pre-4f65ae0b tree. A CoreData "disk I/O error" line in the log is from a test that deliberately simulates an interrupted clear.