@oscaner-skills/cdd-engine 2.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/{src-next/bin.ts → dist/bin.js} +18 -21
  4. package/dist/contract/declare.js +998 -0
  5. package/dist/contract/doc.js +565 -0
  6. package/dist/contract/frontmatter.js +209 -0
  7. package/dist/contract/home-extractors.js +379 -0
  8. package/dist/contract/invariants.js +1030 -0
  9. package/dist/contract/judge.js +109 -0
  10. package/dist/contract/lint.js +206 -0
  11. package/dist/contract/project.js +371 -0
  12. package/dist/contract/skill-anatomy.js +156 -0
  13. package/dist/contract/translate.js +85 -0
  14. package/dist/face/artifacts.js +189 -0
  15. package/dist/face/board-view.js +522 -0
  16. package/dist/face/capsule.js +141 -0
  17. package/dist/face/cli.js +891 -0
  18. package/dist/face/declare.js +241 -0
  19. package/dist/face/gate.js +158 -0
  20. package/dist/face/graph-view.js +66 -0
  21. package/dist/face/host.js +211 -0
  22. package/dist/face/lifecycle.js +603 -0
  23. package/dist/face/preview.js +136 -0
  24. package/dist/face/projection.js +259 -0
  25. package/dist/face/route-render.js +162 -0
  26. package/dist/face/termination.js +482 -0
  27. package/dist/face/words.js +220 -0
  28. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  29. package/dist/infra/doc-roots.js +19 -0
  30. package/dist/infra/git.js +37 -0
  31. package/dist/infra/process.js +22 -0
  32. package/dist/infra/root.js +62 -0
  33. package/dist/infra/runtime.js +85 -0
  34. package/dist/infra/workspace.js +276 -0
  35. package/dist/render/brief.js +82 -0
  36. package/dist/render/issue-body.js +129 -0
  37. package/dist/render/skeleton.js +434 -0
  38. package/dist/render/templates.js +520 -0
  39. package/dist/session/faces.js +38 -0
  40. package/dist/session/graph.js +309 -0
  41. package/dist/session/handoff-schema.js +295 -0
  42. package/dist/session/ledger.js +762 -0
  43. package/dist/session/next.js +211 -0
  44. package/dist/session/preflight.js +194 -0
  45. package/dist/session/round-naming.js +73 -0
  46. package/dist/session/run.js +441 -0
  47. package/dist/session/state.js +8 -0
  48. package/dist/session/wave.js +92 -0
  49. package/package.json +8 -7
  50. package/templates/report/issue-body.json +0 -46
  51. package/src-next/__tests__/bin.test.ts +0 -128
  52. package/src-next/__tests__/smoke.integration.test.ts +0 -202
  53. package/src-next/__tests__/zero-dep.test.ts +0 -134
  54. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
  55. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
  58. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
  59. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
  62. package/src-next/contract/__tests__/declare.test.ts +0 -242
  63. package/src-next/contract/__tests__/doc.test.ts +0 -358
  64. package/src-next/contract/__tests__/judge.test.ts +0 -873
  65. package/src-next/contract/__tests__/lint.test.ts +0 -314
  66. package/src-next/contract/__tests__/project.test.ts +0 -419
  67. package/src-next/contract/__tests__/translate.test.ts +0 -96
  68. package/src-next/contract/declare.ts +0 -983
  69. package/src-next/contract/doc.ts +0 -753
  70. package/src-next/contract/invariants.ts +0 -1268
  71. package/src-next/contract/judge.ts +0 -142
  72. package/src-next/contract/lint.ts +0 -275
  73. package/src-next/contract/project.ts +0 -596
  74. package/src-next/contract/skill-anatomy.ts +0 -273
  75. package/src-next/contract/translate.ts +0 -113
  76. package/src-next/face/__tests__/board-view.test.ts +0 -948
  77. package/src-next/face/__tests__/capsule.test.ts +0 -276
  78. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
  79. package/src-next/face/__tests__/cli.test.ts +0 -4643
  80. package/src-next/face/__tests__/face.test.ts +0 -289
  81. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  82. package/src-next/face/__tests__/host.test.ts +0 -24
  83. package/src-next/face/__tests__/negation.ts +0 -6
  84. package/src-next/face/__tests__/projection.test.ts +0 -301
  85. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
  86. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  87. package/src-next/face/artifacts.ts +0 -195
  88. package/src-next/face/board-view.ts +0 -662
  89. package/src-next/face/capsule.ts +0 -149
  90. package/src-next/face/cli.ts +0 -819
  91. package/src-next/face/declare.ts +0 -326
  92. package/src-next/face/gate.ts +0 -170
  93. package/src-next/face/graph-view.ts +0 -74
  94. package/src-next/face/host.ts +0 -326
  95. package/src-next/face/lifecycle.ts +0 -700
  96. package/src-next/face/projection.ts +0 -282
  97. package/src-next/face/route-render.ts +0 -160
  98. package/src-next/face/words.ts +0 -296
  99. package/src-next/infra/__tests__/infra.test.ts +0 -287
  100. package/src-next/infra/git.ts +0 -39
  101. package/src-next/infra/process.ts +0 -34
  102. package/src-next/infra/runtime.ts +0 -185
  103. package/src-next/infra/workspace.ts +0 -232
  104. package/src-next/render/__tests__/render.test.ts +0 -499
  105. package/src-next/render/__tests__/skeleton.test.ts +0 -466
  106. package/src-next/render/brief.ts +0 -121
  107. package/src-next/render/issue-body.ts +0 -159
  108. package/src-next/render/skeleton.ts +0 -437
  109. package/src-next/render/templates.ts +0 -650
  110. package/src-next/session/__tests__/graph.test.ts +0 -270
  111. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  112. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  113. package/src-next/session/__tests__/ledger.test.ts +0 -744
  114. package/src-next/session/__tests__/next.test.ts +0 -368
  115. package/src-next/session/__tests__/preflight.test.ts +0 -491
  116. package/src-next/session/__tests__/run.test.ts +0 -1014
  117. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  118. package/src-next/session/__tests__/wave.test.ts +0 -469
  119. package/src-next/session/faces.ts +0 -110
  120. package/src-next/session/graph.ts +0 -411
  121. package/src-next/session/handoff-schema.ts +0 -373
  122. package/src-next/session/ledger.ts +0 -1004
  123. package/src-next/session/next.ts +0 -192
  124. package/src-next/session/preflight.ts +0 -240
  125. package/src-next/session/run.ts +0 -606
  126. package/src-next/session/state.ts +0 -30
  127. package/src-next/session/wave.ts +0 -139
@@ -1,606 +0,0 @@
1
- // packages/cdd-engine/src-next/session/run.ts
2
- // T8 — the parameterized single lifecycle (design spec §3.3): the three old
3
- // near-isomorphic lifecycles converge into ONE class whose per-type variance is the
4
- // faces table (faces.ts). advance() runs one dispatch step — one dispatch, one
5
- // advance:
6
- //
7
- // frontier → dispatch → result → bookkeeping → next routing
8
- //
9
- // The lifecycle composes the T6 execution state (the frontier dynamic face + the
10
- // done-set), the T7 NextStepRouter (the C5 next-generation single point) and the T9
11
- // ledger (progress · handoff · round — the on-disk record of every round). The
12
- // capsule interaction point (face/capsule — T10) is a seam: the CapsuleFace
13
- // interface declared here is satisfied by T10's Capsule, and the lifecycle advances
14
- // without a capsule (non-hard consumption — T8 builds no hard dependency toward
15
- // T10); the attachCapsule seam only renders the step's round facts when a capsule is
16
- // connected.
17
- //
18
- // Module-level exports are types / the class / one empty-state data const — zero
19
- // behavior-carrying bare functions (the plan's zero-bare-function discipline).
20
-
21
- import { readFileSync } from "node:fs";
22
- import type { DispatchPhase, ReviewLead, RouteTarget, TargetFace, TargetType } from "./faces.ts";
23
- import {
24
- type HandoffParams,
25
- Ledger,
26
- type LedgerKey,
27
- type OpType,
28
- type RoundFinding,
29
- type RoundStatus,
30
- } from "./ledger.ts";
31
- import type { Route } from "./next.ts";
32
- import { NextStepRouter } from "./next.ts";
33
- import type { PreFlightVerdict } from "./preflight.ts";
34
- import type { ExecutionState, Frontier } from "./state.ts";
35
-
36
- /** The pre-flight dispatch-entry gate — the lifecycle's hard "no child on a refused
37
- * frame" wiring (P4.1 T1): the CLI computes the seam verdict ONCE and hands it to
38
- * the lifecycle as the gate, so a refused dispatch is structurally never passed to
39
- * the child. Null = no gate wired (a gate-less lifecycle advances unguarded — the
40
- * seam-less callers keep their existing behavior). */
41
- export interface PreFlightGate {
42
- /** The pre-flight verdict for one dispatch frame (null = no verdict for the frame
43
- * — the dispatch proceeds; a refused verdict blocks the dispatch). */
44
- gate(frame: OpenFrame): PreFlightVerdict | null;
45
- }
46
-
47
- /** The run-state the lifecycle drives — the T6 query surfaces (frontier dynamic
48
- * face + the done-set) plus the done marking. TaskGraph implements the whole face;
49
- * the branch/spec/plan lines pass EMPTY_RUN_STATE. */
50
- export interface RunState extends ExecutionState, Frontier {
51
- /** Record a completed task — the frontier only advances past marked tasks. */
52
- markDone(id: number): void;
53
- }
54
-
55
- /** The empty run state — a target line with no task frontier (branch/spec/plan):
56
- * the frontier query faces are always empty (a single-target line never continues
57
- * a batch) and markDone is a no-op. */
58
- export const EMPTY_RUN_STATE: RunState = {
59
- doneTasks: () => new Set(),
60
- readyBatch: () => [],
61
- frontier: () => [],
62
- markDone: () => undefined,
63
- };
64
-
65
- /** The audit target of one dispatch step — what the round audits. */
66
- export type AuditTarget =
67
- /** wave (T26 · the wave-unitary model): the frontier's open wave — the whole ready
68
- * batch is ONE dispatch unit (one brief · one child · one commit · one round). */
69
- | { kind: "wave"; tasks: readonly number[] }
70
- /** branch: the branch line itself (no commit identity — the review's scope anchor
71
- * rides the engine-injected BASE_BRANCH, never a stored range). */
72
- | { kind: "branch" }
73
- /** spec/plan: the audit document path. */
74
- | { kind: "doc"; doc: string };
75
-
76
- /** One dispatch step's full identity — what the lifecycle dispatches. */
77
- export interface OpenFrame {
78
- /** The target face the step runs on. */
79
- type: TargetType;
80
- /** The round's dispatch phase. */
81
- phase: DispatchPhase;
82
- /** The round number (the handoff increment: review rounds count up; fix rounds
83
- * source their source review's number). */
84
- round: number;
85
- /** The audit target the round audits. */
86
- target: AuditTarget;
87
- /** The handoff params the round writes under. */
88
- params: HandoffParams;
89
- /** The progress ledger key the round records under (a wave key string / a
90
- * line-type constant — branch · spec · plan). */
91
- key: LedgerKey;
92
- }
93
-
94
- /** One round's dispatch outcome — what the lifecycle records and routes on. */
95
- export interface DispatchOutcome {
96
- /** The round's concluding status. */
97
- status: RoundStatus;
98
- /** The round's findings (review: this round's own; fix: the source review's
99
- * input findings, C5-1). */
100
- findings?: readonly RoundFinding[];
101
- /** The artifact paths the round produced (brief/report/…). */
102
- artifacts?: Record<string, string>;
103
- /** The materialized final carrier (the production dispatch's read-back
104
- * reconstruct — §3.6: the child draft validated and built into the carrier the
105
- * bookkeep persists verbatim, full-replace at the SAME path; agent draft →
106
- * finalized, the engine stays the single author). Absent for the hermetic /
107
- * dry-run dispatchers — the bookkeep builds the carrier from the outcome fields. */
108
- carrier?: Record<string, unknown>;
109
- }
110
-
111
- /** The dispatch instruction — runs one round's actual work (the harness call in
112
- * production; a stub in tests). The lifecycle never inspects how the work runs. */
113
- export type DispatchStep = (frame: OpenFrame) => DispatchOutcome;
114
-
115
- /** The capsule interaction seam — the face/capsule contact. T10's Capsule satisfies
116
- * this shape; the lifecycle advances without a capsule (non-hard consumption) and
117
- * attachCapsule only renders the step's round facts when a capsule is connected. */
118
- export interface CapsuleFace {
119
- /** Render the capsule lines for one round's facts — byte-stable `status · blocker
120
- * · handoff` plus the optional `next:` line (the words ride the face's word
121
- * table). The additive optional RouteTarget supplies the dispatch frame's own
122
- * type + id for the dispatch-ready `next:` literal (v1.25 — the 4-param call
123
- * stays valid: the target is an optional 5th). */
124
- emit(
125
- status: string,
126
- blocker: string,
127
- handoff: string,
128
- next?: Route | string | null,
129
- target?: RouteTarget | null,
130
- ): string[];
131
- }
132
-
133
- /** One advance step's result — the facts the caller drives on. */
134
- export interface StepResult {
135
- /** The frame the step dispatched. */
136
- frame: OpenFrame;
137
- /** The round count on record after bookkeeping. */
138
- round: number;
139
- /** The C5 next-hop route after this step (consumed per the face's next
140
- * semantics: a next-wave advances the task batch — batch faces only). */
141
- route: Route | null;
142
- /** The capsule lines rendered at the interaction point (empty when no capsule is
143
- * attached — the seam is non-hard). */
144
- capsuleLines: readonly string[];
145
- /** The pre-flight verdict of a refused dispatch — the lifecycle's dispatch-entry
146
- * gate blocked the frame before ANY child dispatch (absent on ordinary steps).
147
- * The refused frame is NOT recorded — the frontier re-offers it (resume). */
148
- preflight?: PreFlightVerdict;
149
- }
150
-
151
- /**
152
- * Lifecycle — the parameterized single lifecycle over one target-type face. One
153
- * instance drives one target line. advance() runs one dispatch step:
154
- *
155
- * frontier — resolve the open frame from the face's audit descriptor;
156
- * dispatch — run the injected dispatch instruction, capture the outcome;
157
- * bookkeep — persist the handoff carrier + record the progress round;
158
- * close — the recorded round's C5 route is the single closure verdict: the
159
- * lifecycle marks the task done when the route kind closes the line
160
- * (terminal ⇔ route.kind ∈ {done, next-wave} — desync-proof, the
161
- * router's point, never a folded table);
162
- * route — the delivered C5 next-hop Route, re-judged with the closed task out
163
- * of the ready batch (a closing review routes `done`, not a phantom
164
- * next-wave of the just-closed task).
165
- */
166
- export class Lifecycle {
167
- /** The target face this instance drives — the row of the faces table. */
168
- readonly #face: TargetFace;
169
- /** The run state the lifecycle reads and marks. */
170
- readonly #state: RunState;
171
- /** The session ledger — the round + progress single author. */
172
- readonly #ledger: Ledger;
173
- /** The C5 next router — the next-hop single point. */
174
- readonly #router: NextStepRouter;
175
- /** The dispatch instruction — the round's actual work, injected. */
176
- readonly #dispatch: DispatchStep;
177
- /** The fixed audit target of a branch-tree / doc-path face (the task face
178
- * resolves it from the frontier). */
179
- readonly #target: AuditTarget | null;
180
- /** The attached capsule face — null = the step advances output-less. */
181
- #capsule: CapsuleFace | null;
182
- /** The dispatch-entry pre-flight gate — null = unguarded (the seam-less callers
183
- * keep their existing behavior). */
184
- readonly #preflight: PreFlightGate | null;
185
- /** The workspace plan path — the `next:` implement literal's required `--plan`
186
- * arg (P4.1 T4 — the task face's implement-consuming fact). */
187
- readonly #planPath: string | null;
188
-
189
- constructor(opts: {
190
- face: TargetFace;
191
- state: RunState;
192
- ledger: Ledger;
193
- dispatch: DispatchStep;
194
- router?: NextStepRouter;
195
- /** The fixed audit target for a branch-tree / doc-path face. */
196
- target?: AuditTarget;
197
- /** The capsule face to attach at construction (optional — the seam is non-hard). */
198
- capsule?: CapsuleFace | null;
199
- /** The dispatch-entry pre-flight gate (P4.1 T1 — the lifecycle's hard "no child
200
- * on a refused frame" wiring; optional, null = unguarded). */
201
- preflight?: PreFlightGate | null;
202
- /** The workspace plan path (P4.1 T4 — the implement `next:` literal's `--plan`). */
203
- planPath?: string | null;
204
- }) {
205
- this.#face = opts.face;
206
- this.#state = opts.state;
207
- this.#ledger = opts.ledger;
208
- this.#dispatch = opts.dispatch;
209
- this.#router = opts.router ?? new NextStepRouter();
210
- this.#target = opts.target ?? null;
211
- this.#capsule = opts.capsule ?? null;
212
- this.#preflight = opts.preflight ?? null;
213
- this.#planPath = opts.planPath ?? null;
214
- }
215
-
216
- /** The face row this instance drives. */
217
- face(): TargetFace {
218
- return this.#face;
219
- }
220
-
221
- /** Attach the capsule face — the interaction point (T10's Capsule plugs in; null
222
- * detaches and the step advances output-less). Returns this for chaining. */
223
- attachCapsule(capsule: CapsuleFace | null): this {
224
- this.#capsule = capsule;
225
- return this;
226
- }
227
-
228
- /** Peek the line's next open frame WITHOUT dispatching — the CLI's per-invocation
229
- * cursor pre-checks the next step against the requested verb before it advances
230
- * (a mismatch must not consume the round: advance() dispatches on entry — the
231
- * {16,22,24} bug's loop reordered lookahead-after-dispatch and spent the next
232
- * phase's round in the same invocation). Null = the run is exhausted / capped. */
233
- peekNext(): OpenFrame | null {
234
- return this.#openFrame();
235
- }
236
-
237
- /** advance() — one dispatch step: frontier → pre-flight gate → dispatch → result →
238
- * bookkeeping → next routing. Null when the line holds no open frame (the run is
239
- * exhausted or a capped line defers to the user). A refused pre-flight gate blocks
240
- * the dispatch (child zero) and returns the frame as a preflight-blocked step —
241
- * neither persisted nor recorded (the frontier re-offers it: resume). */
242
- advance(): StepResult | null {
243
- const frame = this.#openFrame();
244
- if (frame === null) return null;
245
- if (this.#preflight !== null) {
246
- const verdict = this.#preflight.gate(frame);
247
- if (verdict !== null && !verdict.ok) {
248
- return {
249
- frame,
250
- round: this.#ledger.roundCount(frame.key, frame.phase),
251
- route: null,
252
- capsuleLines: [],
253
- preflight: verdict,
254
- };
255
- }
256
- }
257
- const outcome = this.#dispatch(frame);
258
- const round = this.#bookkeep(frame, outcome);
259
- // The closure verdict rides the recorded round's C5 route — mark the task done
260
- // when the route kind says the line closed (the router's single point, never a
261
- // folded copy of the closure table).
262
- this.#markTerminal(frame, this.#routeNext(frame));
263
- // The delivered route re-judges the batch AFTER the done-marking: a closing
264
- // review empties the ready batch, so the step routes `done` (an exhausted run),
265
- // not a phantom next-wave of the just-closed task.
266
- const route = this.#routeNext(frame);
267
- return {
268
- frame,
269
- round,
270
- route,
271
- capsuleLines: this.#capsuleLines(frame, outcome, route),
272
- };
273
- }
274
-
275
- // -------------------------------------------------------------------------
276
- // frontier — the open dispatch frame
277
- // -------------------------------------------------------------------------
278
-
279
- /** Resolve the line's next open frame — null when the line is exhausted. */
280
- #openFrame(): OpenFrame | null {
281
- if (this.#face.audit.kind === "task-graph") return this.#openWaveFrame();
282
- const target = this.#target;
283
- if (target === null) return null; // a fixed-target face without its target holds
284
- return this.#openLineFrame(target);
285
- }
286
-
287
- /** The task face's next open frame — THE OPEN WAVE as ONE dispatch step (the
288
- * wave-unitary model · T26): the frontier's whole ready batch is the frame's
289
- * target — one brief, one child, one commit, one round, one phase train. Null
290
- * when the frontier holds no open wave. */
291
- #openWaveFrame(): OpenFrame | null {
292
- const done = this.#state.doneTasks();
293
- const ready = this.#state.frontier(done); // the open wave (the whole ready batch, ascending)
294
- if (ready.length === 0) return null;
295
- const key = ready.join(",");
296
- const phase = this.#nextWavePhase(key);
297
- if (phase === null) return null;
298
- const target = { kind: "wave", tasks: ready } as const;
299
- const round = this.#roundFor(phase, key);
300
- return {
301
- type: "wave",
302
- phase,
303
- round,
304
- target,
305
- params: this.#paramsOf({ type: "wave", phase, target, round }),
306
- key,
307
- };
308
- }
309
-
310
- /** The next phase of one wave line — the SAME single derivation the wave gate reads
311
- * (`Ledger#waveLinePhase` · D26: one fact, one place). The lifecycle's frame
312
- * frontier and the three-verb WaveGate must agree on the open wave's phase, or a
313
- * drift-reopened wave deadlocks (the gate accepts `review` while the frontier
314
- * demands `fix`). Null when the line is closed (its latest round's C5 route is
315
- * done / next-wave / soft-cap — the soft cap defers to the user). */
316
- #nextWavePhase(key: string): DispatchPhase | null {
317
- return this.#ledger.waveLinePhase(key);
318
- }
319
-
320
- /** The branch/spec/plan line's next open frame — the fixed audit target's round
321
- * sequence (review-lead → fix → re-review → closure). */
322
- #openLineFrame(target: AuditTarget): OpenFrame | null {
323
- const key = this.#lineKey(target);
324
- const reviewLead = this.#face.product.reviewLead;
325
- const phase = this.#nextLinePhase(key, target, reviewLead);
326
- if (phase === null) return null;
327
- const round = this.#roundFor(phase, key);
328
- return {
329
- type: this.#face.type,
330
- phase,
331
- round,
332
- target,
333
- params: this.#paramsOf({ type: this.#face.type, phase, target, round }),
334
- key,
335
- };
336
- }
337
-
338
- /** The next phase of a single-target line — the doc-revision gate (lifecycle-side:
339
- * its reviewGate needs the target doc path) then the ledger's SINGLE rounds/routes
340
- * judge (`Ledger#linePhase`, D40 — the retired lifecycle twin). A CLOSED doc line
341
- * reopens through the identity verdict (T7): a drifted doc opens the review lead
342
- * whatever the round/route state says (the fix-awaited route never freezes a
343
- * revised doc); an unchanged doc with the pending fix derived opens the fix; the
344
- * unbound / same-without-pending faces fall through to the shared rounds/routes
345
- * walk (a completed-fix line reopens review through the fix round's route). */
346
- #nextLinePhase(
347
- key: LedgerKey,
348
- target: AuditTarget,
349
- reviewLead: ReviewLead,
350
- ): DispatchPhase | null {
351
- if (target.kind === "doc") {
352
- const verdict = this.#ledger.reviewGate(key, target.doc, this.#face.type);
353
- if (verdict.kind === "open") return reviewLead;
354
- if (verdict.kind === "same" && verdict.pending) return "fix";
355
- }
356
- return this.#ledger.linePhase(key, this.#face.type);
357
- }
358
-
359
- /** The round number one phase dispatches under: implement = the fixed family (1);
360
- * the review-lead = the next increment; fix = the source review-lead round. */
361
- #roundFor(phase: DispatchPhase, key: LedgerKey): number {
362
- if (phase === "implement") return 1;
363
- if (phase === "fix") {
364
- const reviews = this.#reviewCount(key);
365
- return reviews > 0 ? reviews : 1;
366
- }
367
- return this.#reviewCount(key) + 1;
368
- }
369
-
370
- /** The review-lead round count of a key (branch counts its branch-review mode,
371
- * the others the review mode — the face row's single source). */
372
- #reviewCount(key: LedgerKey): number {
373
- return this.#ledger.roundCount(key, this.#face.product.reviewLead);
374
- }
375
-
376
- /** The progress key of a single-target line — the line's STABLE key (find #9 ·
377
- * spec §6.5/§3.7 — `"branch"` per workspace for the branch line, accumulating
378
- * across re-reviews; the doc line keys by its line-type constant `"spec"`/`"plan"`
379
- * — the argv path copy never resets the round: a moved argv string (absolute vs
380
- * relative) must not fork the same line into two ledger rows). The task face
381
- * never routes here — frames key by the wave key. */
382
- #lineKey(target: AuditTarget): LedgerKey {
383
- if (target.kind === "doc") return this.#face.type;
384
- return "branch";
385
- }
386
-
387
- // -------------------------------------------------------------------------
388
- // the frame → handoff params shaping
389
- // -------------------------------------------------------------------------
390
-
391
- /** The handoff params one frame fills — the type's placeholders from the target
392
- * and round. The round rides the increment families (review / fix / branch-review
393
- * — the family name carries it); the fixed implement family stays round-less. */
394
- #paramsOf(frame: {
395
- type: TargetType;
396
- phase: DispatchPhase;
397
- target: AuditTarget;
398
- round: number;
399
- }): HandoffParams {
400
- switch (frame.type) {
401
- case "wave": {
402
- const waveTarget = frame.target as { kind: "wave"; tasks: readonly number[] };
403
- const params: HandoffParams = { tasks: waveTarget.tasks.join(",") };
404
- if (frame.phase !== "implement") params.round = frame.round;
405
- return params;
406
- }
407
- case "branch":
408
- return { round: frame.round };
409
- case "spec":
410
- case "plan":
411
- return { round: frame.round };
412
- }
413
- }
414
-
415
- // -------------------------------------------------------------------------
416
- // dispatch → result → bookkeeping
417
- // -------------------------------------------------------------------------
418
-
419
- /** Bookkeeping — persist the round's handoff carrier and record the progress round.
420
- * The persisted carrier is either the dispatch's materialized form (the production
421
- * read-back reconstruct — outcome.carrier, full-replace at the SAME path, so the
422
- * child's draft becomes the finalized carrier — the two-state single file, the engine is the single
423
- * author) or the engine-built fallback from the outcome fields (hermetic / dry-run
424
- * dispatchers). A BLOCKED/TIMEOUT round WITHOUT a carrier is neither persisted nor
425
- * recorded — the child's draft (if any) stays untouched (no-overwrite on failure) and the
426
- * frontier re-offers the same round (resume = re-run the same command); a BLOCKED
427
- * round WITH a carrier (e.g. the evidence-contract override — the child's work is
428
- * preserved as the BLOCKED carrier) is persisted but not counted as a completed
429
- * round, so the frontier still re-dispatches it. Returns the round count on record
430
- * (the task done-marking rides the step's C5 route — #markTerminal, after
431
- * #routeNext). */
432
- #bookkeep(frame: OpenFrame, outcome: DispatchOutcome): number {
433
- const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
434
- if (outcome.carrier !== undefined || !blocked) {
435
- const op = this.#opOf(frame.phase);
436
- // T2 — the engine-built fallback rides the FRAME's declared face (the family's
437
- // `schema` selector, never the outcome's field presence): a findings-face round
438
- // (review / docs-fix) builds the findings carrier — its schema-required findings
439
- // key, empty on a conclusion-only round (a fix advances no new findings); a
440
- // work-face round builds the findings-free work carrier — zero findings
441
- // injection. The review finding-severity route reads the round carrier's
442
- // findings; the conclusion rides only the work face's declared status (the
443
- // findings face derives its conclusion at judgment time).
444
- const face = this.#ledger.handoffFaceOf(op, frame.type);
445
- const carrier: Record<string, unknown> =
446
- outcome.carrier ??
447
- (face === "findings"
448
- ? this.#ledger.buildHandoff("findings", {
449
- findings: [...(outcome.findings ?? [])],
450
- artifacts: outcome.artifacts,
451
- })
452
- : this.#ledger.buildHandoff("work", {
453
- artifacts: outcome.artifacts,
454
- }));
455
- // The work face ALONE persists the conclusion (the child's declared status); the
456
- // findings carrier holds no status — its conclusion derives at judgment time
457
- // (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
458
- if (face === "work" && carrier.status === undefined && outcome.status !== undefined)
459
- carrier.status = outcome.status;
460
- this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
461
- }
462
- if (!blocked) {
463
- // The recorded CYCLE is the frame's own round — its identity (fix-K ⟷ review-K ·
464
- // D28): a skipped cycle records its own number, never a flattened ordinal.
465
- const count = this.#ledger.recordRound(frame.key, frame.phase, frame.round);
466
- // The completed-review revision write-back — the doc line and the wave line
467
- // each bind their OWN reviewed revision (T7 doc · T11 wave / D16 / D30): a
468
- // completed review binds the CURRENT revision of the reviewed input — read at
469
- // bookkeep, the clean-tree dispatch gate keeps the read-only review's input
470
- // stable across the round. For a doc line that input is the target doc (the
471
- // whole-content doc-revision). For a wave line it is the RENDERED BRIEF —
472
- // `#recordReviewedWaveBrief` → `recordReviewedBrief(String(frame.key),
473
- // #planPath)` hashes the brief the plan renders to, holding #planPath only as
474
- // the plan the brief renders FROM (the render-from POINTER, not the hashed
475
- // identity; the wave gate derives the plan path FROM this record, so
476
- // cli.ts/preflight.ts stay untouched). The two legs do NOT share one gate —
477
- // each ref kind carries its own reviewed identity. An unreadable input records
478
- // nothing (present facts only); a null plan path (no plan fact) leaves a legacy
479
- // wave row — null stays backward compatible.
480
- if (frame.phase === "review") {
481
- if (frame.target.kind === "doc") this.#recordReviewedDocRevision(frame);
482
- else if (frame.target.kind === "wave") this.#recordReviewedWaveBrief(frame);
483
- }
484
- return count;
485
- }
486
- return this.#ledger.roundCount(frame.key, frame.phase);
487
- }
488
-
489
- /** The reviewed-revision write-back — bind the reviewed input's revision to the
490
- * line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
491
- * doc face binds its target doc's whole-content revision; the wave face binds its
492
- * RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
493
- * never the whole plan: transcript edits outside the wave's task sections must not
494
- * void a reviewed wave). An unreadable input records nothing — the line keeps the
495
- * legacy closed face (only present facts land, never an invented identity). */
496
- #recordReviewedDocRevision(frame: OpenFrame): void {
497
- if (frame.target.kind !== "doc") return;
498
- try {
499
- const content = readFileSync(frame.target.doc, "utf8");
500
- this.#ledger.recordReviewedRevision(
501
- frame.key,
502
- this.#ledger.refs().docRevision(frame.target.doc, content),
503
- );
504
- } catch {
505
- // unreadable input — no reviewed identity recorded (present facts only)
506
- }
507
- }
508
-
509
- /** The wave line's reviewed-brief write-back (D30) — bind the RENDERED brief's
510
- * revision for the wave's tasks to the row (the D30 wave-gate reopen basis). Null
511
- * plan path / underivable brief records nothing (present facts only). */
512
- #recordReviewedWaveBrief(frame: OpenFrame): void {
513
- if (frame.target.kind !== "wave" || this.#planPath === null) return;
514
- this.#ledger.recordReviewedBrief(String(frame.key), this.#planPath);
515
- }
516
-
517
- /** Mark the wave done when the concluding route says its line closed — the C5
518
- * verdict is the single closure gate (terminal ⇔ route.kind ∈ {done, next-wave},
519
- * the v1.20 closure side): a clean review or a blocker-free fix closes the wave
520
- * (every member task), while a re-review / soft-cap / a null route (BLOCKED,
521
- * TIMEOUT, a missing base) holds it. Marking the closed wave lets the next
522
- * frontier pass exclude it. The task-less faces never mark — for them the route
523
- * IS the gate. */
524
- #markTerminal(frame: OpenFrame, route: Route | null): void {
525
- if (frame.type !== "wave") return;
526
- if (!Ledger.routeClosed(route)) return;
527
- const waveTarget = frame.target as { kind: "wave"; tasks: readonly number[] };
528
- for (const id of waveTarget.tasks) this.#state.markDone(id);
529
- }
530
-
531
- /** The handoff-family op of a phase — branch-review rides the review family. */
532
- #opOf(phase: DispatchPhase): OpType {
533
- return phase === "branch-review" ? "review" : phase;
534
- }
535
-
536
- // -------------------------------------------------------------------------
537
- // next routing + the capsule interaction
538
- // -------------------------------------------------------------------------
539
-
540
- /** The next-hop route — the recorded round read back through the ledger (the fix
541
- * round carries the SOURCE review's findings, C5-1) and judged by the router.
542
- * Null when the round is unreadable (no invented next hop from absent facts). */
543
- #routeNext(frame: OpenFrame): Route | null {
544
- const op = this.#opOf(frame.phase);
545
- const carried = this.#ledger.round(op, frame.type, frame.params, frame.round);
546
- if (carried === null) return null;
547
- return this.#router.next(this.#routeState(), carried);
548
- }
549
-
550
- /** The execution state the router judges next against — the real run state for
551
- * the batch faces (task), the empty single-target state for the rest (their
552
- * nextSemantics.batch is false — a review-approved closes the line, never a batch
553
- * continuation). */
554
- #routeState(): ExecutionState {
555
- return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
556
- }
557
-
558
- /** The capsule lines of one step — empty unless a capsule is attached (the non-hard
559
- * interaction point). The blocker cell carries the round's blocker count; the
560
- * dispatch-ready `next:` literal rides the frame's own RouteTarget identity
561
- * (type + id — the v1.25 combination point: frame.type + params.tasks + route
562
- * are all present here). */
563
- #capsuleLines(
564
- frame: OpenFrame,
565
- outcome: DispatchOutcome,
566
- route: Route | null,
567
- ): readonly string[] {
568
- if (this.#capsule === null) return [];
569
- const op = this.#opOf(frame.phase);
570
- const blockers = (outcome.findings ?? []).filter(
571
- (finding) => finding.severity === "blocker",
572
- ).length;
573
- const handoff = this.#ledger.handoffPath(op, frame.type, frame.params);
574
- return this.#capsule.emit(
575
- outcome.status,
576
- String(blockers),
577
- handoff,
578
- route,
579
- this.#routeTarget(frame),
580
- );
581
- }
582
-
583
- /** The frame's RouteTarget — the dispatch-ready literal's target identity (the
584
- * frame's own facts: the wave task key · the branch line key · the doc path).
585
- * `type` rides the wave target type; `id` the frame's parameters; `plan` the
586
- * workspace plan path (the implement literal's required `--plan`). */
587
- #routeTarget(frame: OpenFrame): RouteTarget | null {
588
- switch (frame.type) {
589
- case "wave":
590
- return { type: "wave", id: frame.params.tasks ?? "", plan: this.#planPath ?? undefined };
591
- case "branch":
592
- // The branch line's stable id — the workspace plan path carries the
593
- // fix/re-review literals' `--plan` (a plan-less `#sceneOf` would resolve
594
- // to the empty directory · the workspace double identity · zero
595
- // orchestrator fallback).
596
- return {
597
- type: "branch",
598
- id: "branch",
599
- plan: this.#planPath ?? undefined,
600
- };
601
- case "spec":
602
- case "plan":
603
- return { type: frame.type, id: (frame.target as { kind: "doc"; doc: string }).doc };
604
- }
605
- }
606
- }
@@ -1,30 +0,0 @@
1
- // packages/cdd-engine/src-next/session/state.ts
2
- // T6 — the execution-state query surface (design spec §3.1): the frontier dynamic
3
- // face + the ExecutionState query surface. Both are contracts the run carrier
4
- // implements — TaskGraph today, the round ledger's ProgressLedger later — and the
5
- // query methods (doneTasks() / readyBatch()) are METHODS on the carrier, never
6
- // standalone state classes. Module-level exports are interfaces only — zero
7
- // behavior-carrying bare functions (the plan's zero-bare-function discipline).
8
-
9
- /**
10
- * The frontier contract — the pure dynamic readiness face of a task run: given
11
- * the set of completed task ids, which tasks are ready to execute next.
12
- */
13
- export interface Frontier {
14
- /** The ready task ids — every not-yet-done task whose declared dependencies are
15
- * all done, in ascending id order. */
16
- frontier(done: ReadonlySet<number>): readonly number[];
17
- }
18
-
19
- /**
20
- * The execution-state query surface — a carrier's projection of the running
21
- * session. Implemented as methods on TaskGraph (this task) / ProgressLedger (the
22
- * round ledger), never a separate state class.
23
- */
24
- export interface ExecutionState {
25
- /** The completed task ids — a snapshot copy, never a live handle into the run state. */
26
- doneTasks(): Set<number>;
27
- /** The current ready batch — the not-yet-done tasks whose dependencies are all
28
- * done, in ascending id order (the frontier over the carrier's done set). */
29
- readyBatch(): number[];
30
- }