@oscaner-skills/cdd-engine 3.0.0 → 3.1.0

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