Skip to content

Commit 9cafe8f

Browse files
committed
fix(lifecycle): give fan-out invariants teeth and correct GAP-report inventory
1 parent 26e1f36 commit 9cafe8f

3 files changed

Lines changed: 33 additions & 6 deletions

File tree

‎docs/architecture/task-lifecycle-gap-report.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ The delegated-mode reader checker remains proxy refinement evidence: it executes
115115

116116
#### Formal-model decision
117117

118-
No broad tool-state checker is added in this PR. A green model would have to invent a unified owner across parser, handler singleton, webview approval, task state, message files, lifecycle records, and replay. Initial child-state persistence has no production transition to import; approval correlation lacks task/action identity; canonical call identity spans multiple embedded I/O paths. Until those owners are extracted, stable gaps and deterministic witness criteria are stronger evidence than an abstract passing model. The existing parser, lifecycle, handoff, cleanup, completion, and fan-out checkers remain explicitly local.
118+
No broad tool-state checker is added in this PR. A green model would have to invent a unified owner across parser, handler singleton, webview approval, task state, message files, lifecycle records, and replay. Initial child-state persistence has no production transition to import; approval correlation lacks task/action identity; canonical call identity spans multiple embedded I/O paths. Until those owners are extracted, stable gaps and deterministic witness criteria are stronger evidence than an abstract passing model. The existing parser, lifecycle, store-concurrency, handoff, cleanup, completion, and delegated-mode-reader checkers remain explicitly local, as does the separate optional fan-out checker.
119119

120120
### Delegation, interruption, cancellation, completion, and abandonment
121121

@@ -292,8 +292,8 @@ Four workstreams can proceed concurrently after foundation decisions:
292292

293293
| Dependency | Enables |
294294
| ---------------------------------------------- | ------------------------------------------------------------- |
295-
| Disk-authoritative ownership/generation design | LIFE-GAP-001, 002, 012 |
296-
| Durable operation intent/recovery design | LIFE-GAP-004, 005, 006, 023 |
295+
| Disk-authoritative ownership/generation design | LIFE-GAP-001, 002, 012, 020 |
296+
| Durable operation intent/recovery design | LIFE-GAP-004, 005, 006, 021, 023 |
297297
| Task-local execution-context owner | LIFE-GAP-007 and optional future fan-out |
298298
| Request generation and terminal cleanup owner | LIFE-GAP-010, 024, 025, 026 |
299299
| Event notification/barrier contract | LIFE-GAP-009, 011, 027, 028 |
@@ -327,7 +327,7 @@ Four workstreams can proceed concurrently after foundation decisions:
327327

328328
## Completeness statement
329329

330-
At the audited commit, this report covers every tracked definition and directly discoverable caller matching the lifecycle domains in scope, including tool argument assembly, validation, approval, child initialization, partial presentation, result/pending-action identity, todo rehydration, all six baseline checkers and the separate optional fan-out checker, their documented bounds/properties, primary focused suites, lifecycle E2E files, root package scripts, and CI workflow invocations. It does not claim semantic completeness for dynamic calls, generated code, dependencies, ignored files, deployment settings, or production histories. A future code change can invalidate completeness; `LIFE-GAP-016` and `LIFE-GAP-034` exist specifically to make this inventory mechanically maintainable.
330+
At the audited commit, this report covers every tracked definition and directly discoverable caller matching the lifecycle domains in scope, including tool argument assembly, validation, approval, child initialization, partial presentation, result/pending-action identity, todo rehydration, all seven baseline checkers and the separate optional fan-out checker, their documented bounds/properties, primary focused suites, lifecycle E2E files, root package scripts, and CI workflow invocations. It does not claim semantic completeness for dynamic calls, generated code, dependencies, ignored files, deployment settings, or production histories. A future code change can invalidate completeness; `LIFE-GAP-016` and `LIFE-GAP-034` exist specifically to make this inventory mechanically maintainable.
331331

332332
## Historical provenance
333333

‎docs/architecture/task-lifecycle-model.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ Merged PR #1625 changed the confirmed downstream readers: `getEnvironmentDetails
101101

102102
## Task fan-out protocol model
103103

104-
`scripts/check-task-fanout-protocol.ts` is a separate, optional bounded protocol model for the #369/#372 fan-out safety contract. It explores a live parent with two sibling slots, a two-permit scheduler, independent result readiness, explicit child-to-parent delivery, parent loss, orphan cancellation, and permit release. It checks scheduler capacity and exact permit ownership, one writer and at-most-once delivery per child, readiness before delivery, and no result routing after parent loss. Named landmarks require concurrent siblings beneath a live parent, out-of-order result delivery, parent loss while work is running, and complete orphan cleanup to remain reachable. Injected unsafe states confirm those invariants reject wrong writers, early and duplicate delivery, post-parent-loss routing, and scheduler over-allocation.
104+
`scripts/check-task-fanout-protocol.ts` is a separate, optional bounded protocol model for the #369/#372 fan-out safety contract. It explores a live parent with two sibling slots, a two-permit scheduler, independent result readiness, explicit child-to-parent delivery, parent loss, orphan cancellation, and permit release. It checks scheduler capacity and exact permit ownership, one writer and at-most-once delivery per child, readiness before delivery, and no result routing after parent loss. Named landmarks require concurrent siblings beneath a live parent, out-of-order result delivery, single-writer results, parent loss while work is running, and complete orphan cleanup to remain reachable. Injected unsafe states confirm those invariants reject wrong writers, early and duplicate delivery, post-parent-loss routing, and scheduler over-allocation.
105105

106106
This model checks an intended abstract composition boundary without claiming that concurrent sibling fan-out is enabled in production. It imports no production fan-out transition and is excluded from `pnpm lifecycle:model-check` and baseline CI. `TaskScheduler` provides generic bounded permits, but `ClineProvider` constructs it at the default capacity of one and production delegation persists a singular `awaitingChildId`. Raising production concurrency still requires live-parent result integration and extension-host coverage before fan-out can ship.
107107

‎scripts/check-task-fanout-protocol.ts‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,21 @@ const KNOWN_BAD_STATES: Array<{ name: string; state: ModelState; expected: strin
7878
state: { ...initialState(), permitOwners: ["a", "b", "a"] },
7979
expected: "scheduler capacity exceeded",
8080
},
81+
{
82+
name: "duplicate-permit-owner",
83+
state: { ...initialState(), children: { a: "running", b: "idle" }, permitOwners: ["a", "a"] },
84+
expected: "duplicate permit owner",
85+
},
86+
{
87+
name: "active-without-permit",
88+
state: { ...initialState(), children: { a: "running", b: "idle" }, permitOwners: [] },
89+
expected: "a: active without permit ownership",
90+
},
91+
{
92+
name: "idle-child-owns-permit",
93+
state: { ...initialState(), permitOwners: ["a"] },
94+
expected: "a: idle child owns a permit",
95+
},
8196
]
8297

8398
for (const unsafe of KNOWN_BAD_STATES) {
@@ -144,6 +159,12 @@ function transitions(state: ModelState): Transition[] {
144159
action(`deliver(${child}, parent)`, "deliver", state, (next) => {
145160
next.children[child] = "delivered"
146161
next.deliveries.push(child)
162+
// Record the parent-liveness observed at delivery time so the "result routed
163+
// after parent loss" invariant is coupled to the delivery mechanism, not a flag
164+
// no transition writes. The guard above keeps this false in the correct spec, so
165+
// the model still passes; if a future edit drops the guard, delivery fires with
166+
// !parentLive, this sets the flag, and the invariant catches the regression.
167+
next.deliveryAfterParentLoss ||= !state.parentLive
147168
}),
148169
)
149170
}
@@ -214,7 +235,13 @@ function action(name: string, kind: string, state: ModelState, update: (next: Mo
214235
}
215236

216237
function canonical(state: ModelState): string {
217-
return JSON.stringify({ ...state, permitOwners: [...state.permitOwners].sort() })
238+
// resultWriters is built incrementally in finish(), so key insertion order varies by
239+
// interleaving; sort keys so logically identical states dedupe. deliveries stays ordered
240+
// (the out-of-order-results landmark depends on it).
241+
const resultWriters = Object.fromEntries(
242+
(Object.keys(state.resultWriters) as Child[]).sort().map((child) => [child, state.resultWriters[child]]),
243+
)
244+
return JSON.stringify({ ...state, permitOwners: [...state.permitOwners].sort(), resultWriters })
218245
}
219246

220247
function formatViolation(violations: string[], trace: TraceStep[]): string {

0 commit comments

Comments
 (0)