@oscaner-skills/cdd-engine 4.2.0 → 4.4.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 (58) hide show
  1. package/README.md +38 -9
  2. package/README.zh-CN.md +44 -10
  3. package/dist/contract/completion-criterion.js +351 -0
  4. package/dist/contract/declare.js +181 -43
  5. package/dist/contract/doc.js +84 -271
  6. package/dist/contract/frontmatter.js +2 -1
  7. package/dist/contract/home-extractors.js +49 -316
  8. package/dist/contract/invariants.js +400 -296
  9. package/dist/contract/judge.js +74 -49
  10. package/dist/contract/lint.js +3 -2
  11. package/dist/contract/liveness-signal.js +103 -0
  12. package/dist/contract/markdown-document.js +410 -0
  13. package/dist/contract/markdown-tree-types.js +6 -0
  14. package/dist/contract/markdown-tree.js +137 -0
  15. package/dist/contract/project.js +1 -1
  16. package/dist/contract/rules.js +106 -0
  17. package/dist/contract/selector-engine.js +332 -0
  18. package/dist/contract/selector-spec.js +74 -0
  19. package/dist/contract/skill-anatomy.js +29 -1
  20. package/dist/contract/task-block-grammar.js +285 -0
  21. package/dist/contract/task-blocks.js +65 -0
  22. package/dist/contract/translate.js +21 -0
  23. package/dist/contract/wave-width.js +15 -0
  24. package/dist/face/board-view.js +382 -172
  25. package/dist/face/capsule.js +73 -88
  26. package/dist/face/cli.js +152 -38
  27. package/dist/face/declare.js +42 -19
  28. package/dist/face/gate.js +119 -40
  29. package/dist/face/init.js +84 -25
  30. package/dist/face/lifecycle.js +540 -123
  31. package/dist/face/plugins.js +70 -2
  32. package/dist/face/preview.js +69 -18
  33. package/dist/face/route-render.js +60 -21
  34. package/dist/face/termination.js +135 -261
  35. package/dist/face/words.js +139 -13
  36. package/dist/infra/atomic.js +15 -0
  37. package/dist/infra/git.js +25 -0
  38. package/dist/infra/proc.js +150 -0
  39. package/dist/infra/round-log.js +104 -0
  40. package/dist/infra/runtime.js +16 -4
  41. package/dist/infra/workspace.js +7 -2
  42. package/dist/render/brief.js +15 -17
  43. package/dist/render/skeleton.js +41 -28
  44. package/dist/render/templates.js +128 -84
  45. package/dist/session/faces.js +47 -20
  46. package/dist/session/graph.js +13 -37
  47. package/dist/session/handoff-schema.js +16 -8
  48. package/dist/session/inflight.js +282 -0
  49. package/dist/session/ledger.js +603 -145
  50. package/dist/session/line-identity.js +33 -0
  51. package/dist/session/next.js +140 -80
  52. package/dist/session/pipeline.js +247 -0
  53. package/dist/session/preflight.js +276 -68
  54. package/dist/session/reviewed-identity.js +54 -0
  55. package/dist/session/round-naming.js +56 -8
  56. package/dist/session/run.js +364 -80
  57. package/dist/session/wave.js +94 -14
  58. package/package.json +13 -3
@@ -0,0 +1,33 @@
1
+ // packages/cdd-engine/src-next/session/line-identity.ts
2
+ // T3 — LineIdentity: the ONE drift judgment of the three line kinds (P21 §4.1).
3
+ // Today's session carried two parallel comparisons (the doc line's doc-revision and
4
+ // the wave line's brief-revision); the branch line had none at all. This class is the
5
+ // single identity face all three read:
6
+ // · spec / plan — the document's `doc-revision` (a hash of the whole content);
7
+ // · wave — the RENDERED brief's `brief-revision` (its task sections plus the
8
+ // plan's `## Constraints` — a plan edit elsewhere is not a drift);
9
+ // · branch — its plan document's `doc-revision` (the SAME kind, no new ref
10
+ // kind, no commit sha — the ledger keeps no second code identity).
11
+ //
12
+ // The judgment is deliberately two-valued + unknown: `same` (the recorded identity
13
+ // still describes the current input), `drift` (the input moved past it — the line
14
+ // reopens), `null` (no recorded identity, or an unreadable input — only PRESENT facts
15
+ // land a judgment, and a line with no record keeps the legacy closed face). The
16
+ // same-ref predicate itself stays where it already lived (`ReviewRefs.sameRef`,
17
+ // injected) so the identity kind comparison has exactly one definition.
18
+ //
19
+ // Module-level exports are types / the class — zero behavior-carrying bare functions.
20
+ /** LineIdentity — the one drift judgment of the three line kinds. */
21
+ export class LineIdentity {
22
+ /** The same-ref predicate's home (`ReviewRefs`) — injected, never re-declared. */
23
+ #refs;
24
+ constructor(refs) {
25
+ this.#refs = refs;
26
+ }
27
+ /** Judge a line: the recorded reviewed identity against the current input. */
28
+ verdict(recorded, current) {
29
+ if (recorded === null || current === null)
30
+ return null;
31
+ return this.#refs.sameRef(recorded, current.ref) ? "same" : "drift";
32
+ }
33
+ }
@@ -27,17 +27,25 @@
27
27
  //
28
28
  // D40 — ONE "next step" concept: the face-INTERNAL C5 hop and the face-TO-face
29
29
  // handoff are the SAME `Route` union (a `handoff` kind carries the pipeline entry),
30
- // so a consumer never consults a second table. `NextStepRouter.resolve` is the ONE
31
- // "one line → next" resolver: an active C5 hop passes through, a drained line yields
32
- // the face-to-face handoff. Both the board (its per-line walk) and the capsule
33
- // (the round's own line) call it — single resolver, single renderer.
30
+ // so a consumer never consults a second table. The face-to-face station selection
31
+ // rides the ONE derivation (`nextHop`): a `done` route's `to` cell is
32
+ // `PIPELINE_NEXT`'s row for the judged doc class, a `handoff` route carries its own
33
+ // entry, and the pipeline traversal itself belongs to the session plane's
34
+ // `PipelineFrontier` — no second resolver.
34
35
  //
35
36
  // Module-level exports are types / constants / the class — zero behavior-carrying
36
37
  // bare functions (the plan's zero-bare-function discipline).
38
+ var _a;
37
39
  /** The review-cycle soft cap — the consecutive-S1 run length at which the fix face
38
40
  * defers the next hop to user adjudication (soft by nature: a default suggestion,
39
41
  * never a hard stop — the user / the plan write authority override it). */
40
- export const REVIEW_CYCLE_CAP = 20;
42
+ export const REVIEW_CYCLE_CAP = 50;
43
+ /** The wave-width ceiling (design spec §6) — at most this many tasks per dispatch wave.
44
+ * Declared once on the contract plane (`contract/wave-width.ts`), so the plan-scope
45
+ * rule reads it without importing this session plane, and re-exported here as the
46
+ * dispatch face's constant beside `REVIEW_CYCLE_CAP`. Three readers share the one
47
+ * value: the plan rule, the wave gate's two rejections and their wording. */
48
+ export { MAX_TASKS_PER_WAVE } from "../contract/wave-width.js";
41
49
  /** The decision-edge words of the Route union — the C5 hop kinds that a review/fix
42
50
  * closure decision edge renders as a `next:` label (`done` · `next-wave` · `review`
43
51
  * · `fix` · `soft-cap`). The pure face-to-face `handoff` kind is EXCLUDED: it carries
@@ -46,34 +54,49 @@ export const REVIEW_CYCLE_CAP = 20;
46
54
  * runtime Route lexicon is the ONE source, never a second hand-written list. */
47
55
  export const ROUTE_DECISION_WORDS = ["done", "next-wave", "review", "fix", "soft-cap"];
48
56
  /** The pipeline next table — the ONE face-indirection source (D33 · single-addressed
49
- * at session/next.ts):
50
- * the doc-class key → the next pipeline entrypoint. The skill refs ride REFS
51
- * (face/host.ts) resolved per host at the render — never a hard-coded plugin
52
- * spelling; the wave literal's `<plan>` slot is filled by the capsule with the
53
- * frame's plan fact. */
57
+ * at session/next.ts), keyed by the SAME TargetType the CLI declares: the target
58
+ * type → the next pipeline entrypoint. The two program-level rows (`overall` and
59
+ * the standalone `single-spec`) are the pipeline's terminals — nothing follows a
60
+ * closed charter line. The skill refs ride REFS (face/host.ts) resolved per host
61
+ * at the render — never a hard-coded plugin spelling; the wave literal's `<plan>`
62
+ * slot is filled by the capsule with the frame's plan fact. */
54
63
  export const PIPELINE_NEXT = {
55
64
  "phase-spec": { kind: "ref", ref: "kairos:cdd-plan" },
56
65
  overall: { kind: "done" },
57
66
  plan: { kind: "ref", ref: "kairos:cdd-dev" },
67
+ "single-spec": { kind: "done" },
58
68
  wave: { kind: "literal", literal: "review --type branch --plan <plan>" },
59
69
  branch: { kind: "ref", ref: "kairos:cdd-close" },
60
70
  };
61
71
  /** The pipeline's phase-level face order (D40) — the face-to-face traversal
62
- * `spec → plan → wave → branch`, the ONE order declaration; `NextStepRouter.walk`
63
- * iterates it, so a consumer maps key → facts and declares NO order of its own. */
72
+ * `spec → plan → wave → branch`, the ONE order declaration: the session plane's
73
+ * `PipelineFrontier` iterates it, so a consumer maps key → facts and declares NO
74
+ * order of its own. */
64
75
  export const PIPELINE_FACES = ["phase-spec", "plan", "wave", "branch"];
76
+ /** The single reason table (§5.2) — every `NextHop.reason` value comes from here, so
77
+ * the four read faces and the CLI rejection message name a fact by ONE spelling (a
78
+ * hyphenated fact name, never a sentence). */
79
+ export const NEXT_HOP_REASON = {
80
+ docDrift: "doc-drift",
81
+ pendingFix: "pending-fix",
82
+ closedLine: "closed-line",
83
+ faceClosed: "face-closed",
84
+ softCap: "soft-cap",
85
+ taskOpen: "task-open",
86
+ docClassBlocked: "doc-class-blocked",
87
+ };
65
88
  /** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
66
89
  export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
67
90
  /** The fix-route readback suffix — appended verbatim to the fix findings path on the
68
- * route's `next:` render (`(confirm the findings · if a finding needs a ruling,
69
- * record the ruling in the findings file)`), a pure wording prompt: the
91
+ * route's `next:` render (`(confirm the reviews handoff · if a finding needs a
92
+ * ruling, record the ruling in the handoff file)`), a pure wording prompt: the
70
93
  * anti-blind-fix mechanical guard is the ledger round / C5-1, the suffix only
71
94
  * reminds the orchestrator to confirm the captured findings and, when a finding
72
- * needs a user ruling, record that ruling back into the findings file the fix
95
+ * needs a user ruling, record that ruling back into the reviews handoff the fix
73
96
  * round consumes. `annotate` names the carrier action alone — distinct from
74
97
  * `backfill` (a durable fact landed into its owning doc), which stays the
75
98
  * ruling's destination when it asserts a project-level fact. */
76
- export const FIX_READBACK_SUFFIX = "(confirm the findings · if a finding needs a ruling, record the ruling in the findings file)";
99
+ export const FIX_READBACK_SUFFIX = "(confirm the reviews handoff · if a finding needs a ruling, record the ruling in the handoff file)";
77
100
  /** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
78
101
  * produces no `next:` line on any op. Exported as the ONE failure-status set: the
79
102
  * skill-anatomy contract's `edgeConditionWords` derivation reads it to exclude the
@@ -137,6 +160,106 @@ export class NextStepRouter {
137
160
  #blockerCount(ref) {
138
161
  return ref.findings.filter((finding) => finding.severity === "blocker").length;
139
162
  }
163
+ // ---------------------------------------------------------------------------
164
+ // the ONE next-hop derivation (§5.2) — a presentation read of the count table
165
+ // ---------------------------------------------------------------------------
166
+ /** hopOf(route, face) — the ONE constant Route → Hop mapping. It reads the face
167
+ * because a `review` route carries NO face of its own: the branch face's review is
168
+ * the `branch-review` skill, every other face's is `review`. `done` / `handoff` /
169
+ * `soft-cap` are not hops — they close the line (the count table's judgment). */
170
+ hopOf(route, face) {
171
+ switch (route.kind) {
172
+ case "next-wave":
173
+ return "implement";
174
+ case "review":
175
+ return face === "branch" ? "branch-review" : "review";
176
+ case "fix":
177
+ return "fix";
178
+ case "soft-cap":
179
+ case "done":
180
+ case "handoff":
181
+ return null;
182
+ }
183
+ }
184
+ /** nextHop(input) — the ONE derivation of a line's next hop (§5.2), once per call
185
+ * and per line (never cached, never shared across calls).
186
+ *
187
+ * The judgment stays the count table's: `hop` is READ OUT of the route the table
188
+ * produced (`hopOf`), never re-derived here, and `reason` names the fact that
189
+ * selected it (§5.1: any second criterion is the regression the phase names). The
190
+ * face axis is read out of the ONE verdict (`#faceOf`), so the three read faces
191
+ * fill facts and never re-assemble the chain. `to` follows the same path for
192
+ * `done` and `handoff`; the doc-class discrimination is injected at the assembly
193
+ * entry, so this module never imports a face class. */
194
+ nextHop(input) {
195
+ const route = input.route;
196
+ const verdict = input.verdict;
197
+ const face = _a.#faceOf(verdict);
198
+ return {
199
+ face,
200
+ target: input.target,
201
+ // No route (the failure face) is no hop; otherwise `hopOf` is the ONE answer to
202
+ // "which route kinds are hops" — the closure kinds are not enumerated twice.
203
+ hop: route === null ? null : this.hopOf(route, face),
204
+ to: this.#entryOf(input, route, verdict),
205
+ reason: this.#reasonOf(input, route, verdict),
206
+ route,
207
+ };
208
+ }
209
+ /** message(hop, station) — the ONE rejection-message shape (§5.2): a hop names the
210
+ * verb, a closed face names its handoff station (`station` renders the entry through
211
+ * the shared route renderer), and neither renders the bare reason — no invented
212
+ * verb slot. */
213
+ message(hop, station) {
214
+ if (hop.hop !== null)
215
+ return `${hop.reason} · the next round is ${hop.hop}`;
216
+ if (hop.to !== null)
217
+ return `${hop.reason} · next: ${station(hop.to)}`;
218
+ return hop.reason;
219
+ }
220
+ /** The face axis of one verdict — the ONE `verdict → face` assembly (§5.2): the two
221
+ * unroutable classes carry no face, every pipeline key is its own face. */
222
+ static #faceOf(verdict) {
223
+ return verdict === "blocked" || verdict === "terminal" ? null : verdict;
224
+ }
225
+ /** The pipeline station of a closure route — `handoff` carries its own entry, `done`
226
+ * derives it from the doc class (`PIPELINE_NEXT` is data, never a judgment), and a
227
+ * `blocked` / `terminal` class (or no route at all) has no station. The wave face is
228
+ * the ONE class whose row depends on the NEXT line (P21 §4.2): a closed branch line
229
+ * hands the wave line to the branch face's own exit, not a literal its gate refuses. */
230
+ #entryOf(input, route, verdict) {
231
+ if (route === null)
232
+ return null;
233
+ if (route.kind === "handoff")
234
+ return route.entry;
235
+ if (route.kind !== "done")
236
+ return null;
237
+ if (verdict === "blocked" || verdict === "terminal")
238
+ return null;
239
+ if (verdict === "wave" && input.nextLineOpen === false)
240
+ return PIPELINE_NEXT.branch;
241
+ return PIPELINE_NEXT[verdict];
242
+ }
243
+ /** The named fact behind the hop — one `NEXT_HOP_REASON` row, in this order: the
244
+ * soft cap · a pending fix · a drift-reopened line (its reviewed identity moved —
245
+ * a doc revision or a wave's brief revision) · an open line advancing · an
246
+ * unjudgeable doc class · a closed face · the closed line's handoff. Drift never
247
+ * outranks a pending fix (an unclosed line's blocker keeps the fix hop). */
248
+ #reasonOf(input, route, verdict) {
249
+ if (route?.kind === "soft-cap")
250
+ return NEXT_HOP_REASON.softCap;
251
+ if (route?.kind === "fix")
252
+ return NEXT_HOP_REASON.pendingFix;
253
+ if (route?.kind === "review" && input.gate.drift)
254
+ return NEXT_HOP_REASON.docDrift;
255
+ if (route !== null && this.hopOf(route, _a.#faceOf(verdict)) !== null)
256
+ return NEXT_HOP_REASON.taskOpen;
257
+ if (verdict === "blocked")
258
+ return NEXT_HOP_REASON.docClassBlocked;
259
+ if (route === null || verdict === "terminal")
260
+ return NEXT_HOP_REASON.faceClosed;
261
+ return NEXT_HOP_REASON.closedLine;
262
+ }
140
263
  /** The face-to-face handoff route for a pipeline doc-class (D40) — the next-face
141
264
  * entry (`PIPELINE_NEXT[key]`). One of the two ways the ONE "next step" concept
142
265
  * is produced (the C5 hop is the other), so a consumer never consults a second
@@ -144,68 +267,5 @@ export class NextStepRouter {
144
267
  static handoff(key) {
145
268
  return { kind: "handoff", entry: PIPELINE_NEXT[key] };
146
269
  }
147
- /** Resolve a line's next step (D40) — the capsule's "one line → next" point for the
148
- * round's OWN line: an ACTIVE C5 hop (`review` / `fix` / `implement` / `next-wave` /
149
- * `soft-cap`) passes through as the line's next step; a drained / not-yet-started
150
- * line (the C5 `done` / no active round) yields the face-to-face handoff carrying
151
- * the pipeline entry. A null doc-class (no face seam — the overall line / a bare
152
- * terminal) renders the bare `done` word. A whole-slug walk is `walk` (the board's
153
- * face-to-face traversal); this is the single-line form the capsule holds. Pure. */
154
- static resolve(active, key) {
155
- if (active !== null && active.kind !== "done")
156
- return active;
157
- return key === null ? { kind: "done" } : NextStepRouter.handoff(key);
158
- }
159
- /** Walk(face report) → the ONE next step (D40 · the board's face-to-face traversal
160
- * as a single router method). The caller REPORTS each face's facts keyed by its
161
- * `PIPELINE_FACES` key; the router iterates the ONE order and DECIDES the next step
162
- * — so no consumer re-derives the order OR the face-transition rule (the retired
163
- * board fork handed off via the frontier LINE's own key, so a slug whose spec just
164
- * closed but whose plan was not yet authored rendered `plan`'s exit `cdd-dev`
165
- * instead of the spec's exit `cdd-plan` — a face-boundary off-by-one the ONE walk
166
- * eliminates). The rule:
167
- * · the FRONTIER face (first not-closed) with an active C5 hop → render that hop
168
- * (the in-flight work — `review` / `fix` / `implement` / `next-wave`);
169
- * · the frontier has no active hop but IS entered (`target` present — an empty
170
- * wave segment, a drained-but-reached face) → its OWN pipeline exit entry;
171
- * · the frontier is NOT entered (no target — an absent doc, e.g. no plan yet) →
172
- * the transition INTO it, i.e. the PRECEDING entered face's exit entry (so a
173
- * just-closed spec hands off to the spec's exit `cdd-plan`, never the absent
174
- * plan's exit); no preceding entered face → the FIRST face's exit entry;
175
- * · every face closed → the LAST entered face's exit entry (the pipeline
176
- * terminus — `cdd-close` for a phase slug). */
177
- static walk(report) {
178
- const states = PIPELINE_FACES.map((key) => report[key]);
179
- const frontierIndex = states.findIndex((face) => !face.closed);
180
- if (frontierIndex === -1) {
181
- const terminalIndex = NextStepRouter.#lastEnteredIndex(states);
182
- const terminal = terminalIndex === -1 ? null : states[terminalIndex];
183
- return terminal === null
184
- ? { route: { kind: "done" }, target: null }
185
- : {
186
- route: NextStepRouter.handoff(PIPELINE_FACES[terminalIndex]),
187
- target: terminal.target,
188
- };
189
- }
190
- const frontier = states[frontierIndex];
191
- if (frontier.active !== null)
192
- return { route: frontier.active, target: frontier.target };
193
- const anchorIndex = frontier.target !== null
194
- ? frontierIndex
195
- : Math.max(0, NextStepRouter.#lastEnteredIndex(states.slice(0, frontierIndex)));
196
- const anchor = states[anchorIndex];
197
- return {
198
- route: NextStepRouter.handoff(PIPELINE_FACES[anchorIndex]),
199
- target: anchor.target,
200
- };
201
- }
202
- /** The index of the last OBSERVED face carrying a render target — the last face the
203
- * pipeline has REACHED (a face with no target was never entered). -1 when none is. */
204
- static #lastEnteredIndex(states) {
205
- for (let i = states.length - 1; i >= 0; i--) {
206
- if (states[i].target !== null)
207
- return i;
208
- }
209
- return -1;
210
- }
211
270
  }
271
+ _a = NextStepRouter;
@@ -0,0 +1,247 @@
1
+ // packages/cdd-engine/src-next/session/pipeline.ts
2
+ // The pipeline frontier — the session plane's ONE judge over "which face is in
3
+ // flight" (D40 · P22 §5.2). The four face-order rules and the ONE hop derivation
4
+ // live HERE, next to the ledger they read; the board face only OBSERVES each face's
5
+ // facts and RENDERS the result (`PipelineFrontier.next`'s `{ route, target }`).
6
+ //
7
+ // P24 §11 — the ASSEMBLY lives here too, beside `next` (`PipelineFrontier#hopOf`):
8
+ // one `next(input)` verdict → the six hop cells derived from that verdict's TARGET →
9
+ // `Ledger#nextHopOf` → one `NextHop`. The capsule (`session/run.ts`) and the board
10
+ // (`face/board-view.ts` `BoardNext`) both call this ONE assembly and each only
11
+ // renders the result, so the two faces cannot disagree by construction.
12
+ //
13
+ // Constructed with the node's `Ledger` (the `Ledger` / `Lifecycle` shape: one read
14
+ // face injected, no global state). The plan is never read here — the guarded plan
15
+ // read stays on the board side and rides in as `planGraph`, so this module holds
16
+ // zero file-system read and no second plan parse.
17
+ //
18
+ // The four rules over the ONE `PIPELINE_FACES` order:
19
+ // · the FRONTIER face (first not-closed) with an active C5 hop renders that hop
20
+ // (the in-flight work — `review` / `fix` / `implement` / `next-wave`);
21
+ // · the frontier has no active hop but IS entered (a target is present) → its
22
+ // OWN pipeline exit entry;
23
+ // · the frontier is NOT entered (no target — the document is absent, OR the
24
+ // face's own entry predicate never held) → the transition INTO it: the
25
+ // PRECEDING entered face's exit entry (a just-closed spec hands off to
26
+ // `cdd-plan`, never the absent plan's `cdd-dev`); none preceding → the
27
+ // FIRST face's exit entry;
28
+ // · every face closed → the LAST entered face's exit entry (the terminus —
29
+ // `cdd-close` for a phase slug).
30
+ // Rules 1 / 2 answer the frontier face (the route is that face's own); rules 3 / 4
31
+ // are EXCHANGE rules — the route belongs to the anchor face, so `face` is null and
32
+ // the anchor is read back off `target`.
33
+ //
34
+ // Module-level exports are types / the class — zero behavior-carrying bare functions
35
+ // (the plan's zero-bare-function discipline).
36
+ import { NextStepRouter, PIPELINE_FACES, PIPELINE_NEXT, } from "./next.js";
37
+ /** The three modes a wave row records — the wave face's entry scan (P25 §6). A wave
38
+ * row is written by the dispatch rounds only; `branch-review` rides the branch face. */
39
+ const WAVE_ROUND_MODES = ["implement", "review", "fix"];
40
+ export class PipelineFrontier {
41
+ /** The node's ledger — the ONE round/closure read face the per-face facts come
42
+ * from (no second closure or drift judge lives in this module). */
43
+ #ledger;
44
+ constructor(ledger) {
45
+ this.#ledger = ledger;
46
+ }
47
+ /** The next pipeline step — the four face-order rules over the ONE
48
+ * `PIPELINE_FACES` order (imported, never re-declared here). */
49
+ next(input) {
50
+ const states = PIPELINE_FACES.map((face) => this.#stateOf(face, input));
51
+ const frontierIndex = states.findIndex((state) => !state.closed);
52
+ if (frontierIndex === -1)
53
+ return PipelineFrontier.#terminal(states);
54
+ const frontierFace = PIPELINE_FACES[frontierIndex];
55
+ const frontier = states[frontierIndex];
56
+ if (frontier.active !== null)
57
+ return { face: frontierFace, route: frontier.active, target: frontier.target };
58
+ if (frontier.target !== null)
59
+ return {
60
+ face: frontierFace,
61
+ route: PipelineFrontier.#exitRoute(frontierIndex, frontier),
62
+ target: frontier.target,
63
+ };
64
+ const anchorIndex = Math.max(0, PipelineFrontier.#lastEnteredIndex(states.slice(0, frontierIndex)));
65
+ const anchor = states[anchorIndex];
66
+ return {
67
+ face: null,
68
+ route: PipelineFrontier.#exitRoute(anchorIndex, anchor),
69
+ target: anchor.target,
70
+ };
71
+ }
72
+ /** The pipeline hop — the session plane's ONE assembly: one `next(input)` verdict,
73
+ * the six hop cells derived from that verdict's TARGET (never from a dispatch
74
+ * frame), the ledger's own branch-line fact as the sixth cell, and the injected
75
+ * station discrimination, handed to the ONE derivation (`Ledger#nextHopOf`).
76
+ * `face/board-view.ts` and `session/run.ts` BOTH call this and only render the
77
+ * result, so the board's `next:` and the capsule's `next:` are one object by
78
+ * construction. */
79
+ hopOf(input, ports) {
80
+ const verdict = this.next(input);
81
+ const target = verdict.target;
82
+ return this.#ledger.nextHopOf({
83
+ type: target?.type ?? "branch",
84
+ key: target?.type === "wave" ? target.id : (target?.type ?? "branch"),
85
+ route: verdict.route,
86
+ target,
87
+ doc: PipelineFrontier.#docOf(target),
88
+ // The wave half is gated on the target TYPE: off the wave face `target.id` is a
89
+ // document path, never a wave key. The cell can only reach a `reason:` row.
90
+ briefDrift: target?.type === "wave" ? this.#ledger.briefDrifted(String(target.id)) : undefined,
91
+ // The sixth cell — the ledger's OWN branch-line fact, read by ONE judge here and
92
+ // by the line frontier's `Lifecycle#branchLineOpen` (a delegation).
93
+ nextLineOpen: this.branchLineOpen(input.planPath),
94
+ docClassOf: ports.docClassOf,
95
+ });
96
+ }
97
+ /** Whether the branch line has a dispatchable open round — the SIXTH hop cell's ONE
98
+ * judge (P21 §4.2): the branch row's drift-aware gate (the plan moved past its
99
+ * reviewed revision) or a still-active C5 hop. `undefined` when no plan fact
100
+ * exists. Both hop assemblies read this one copy. */
101
+ branchLineOpen(planPath) {
102
+ if (planPath === null)
103
+ return undefined;
104
+ if (this.#ledger.reviewGate("branch", planPath, "branch").kind === "open")
105
+ return true;
106
+ return this.#ledger.lineRoute("branch", "branch") !== null;
107
+ }
108
+ /** The judged document of one render target — the node shapes' own id, a branch
109
+ * target's plan (its identity document); null for a target-less verdict. */
110
+ static #docOf(target) {
111
+ if (target === null)
112
+ return null;
113
+ return target.type === "branch" ? (target.plan ?? null) : target.id;
114
+ }
115
+ /** Rule 4 — every face closed: the terminus is the LAST entered face's exit; a
116
+ * pipeline that entered no face at all holds no step (`done`). */
117
+ static #terminal(states) {
118
+ const terminalIndex = PipelineFrontier.#lastEnteredIndex(states);
119
+ if (terminalIndex === -1)
120
+ return { face: null, route: { kind: "done" }, target: null };
121
+ const terminal = states[terminalIndex];
122
+ return {
123
+ face: null,
124
+ route: PipelineFrontier.#exitRoute(terminalIndex, terminal),
125
+ target: terminal.target,
126
+ };
127
+ }
128
+ /** One face's observed facts — the pivot onto the per-face judges below. */
129
+ #stateOf(face, input) {
130
+ if (face === "phase-spec")
131
+ return this.#identityState(input);
132
+ if (face === "plan")
133
+ return this.#planState(input);
134
+ if (face === "wave")
135
+ return this.#waveState(input);
136
+ return this.#branchState(input);
137
+ }
138
+ /** The identity face's closure is judged AT its identity document: a spec revision
139
+ * past the one the clean review bound reopens the face, so the frontier holds here
140
+ * (the SAME drift-aware judge the branch face reads) instead of walking on to a
141
+ * plan command the dispatch would reject. */
142
+ #identityState(input) {
143
+ const type = input.specType ?? "phase-spec";
144
+ return {
145
+ closed: this.#ledger.lineStateAt(type, type, input.specPath) === "closed",
146
+ active: input.specPath === null ? null : this.#ledger.lineRoute(type, type),
147
+ target: input.specPath === null ? null : { type, id: input.specPath },
148
+ };
149
+ }
150
+ /** The plan face — the plan document is its own identity document, so the closure
151
+ * judge and the active hop read the SAME path. */
152
+ #planState(input) {
153
+ const planPath = input.planPath;
154
+ return {
155
+ closed: this.#ledger.lineStateAt("plan", "plan", planPath) === "closed",
156
+ active: planPath === null ? null : this.#ledger.lineRoute("plan", "plan"),
157
+ target: planPath === null ? null : { type: "plan", id: planPath, plan: planPath },
158
+ };
159
+ }
160
+ /** The wave face — exhausted (skipped) only when the plan yields a wave set and
161
+ * every wave is done: an empty wave segment (a plan with no task block) closes
162
+ * nothing, so it is not an exhausted face. The active hop reads the READY batch's
163
+ * wave key (`TaskGraph#frontier`, never a local walk) through the ledger's ONE wave
164
+ * route.
165
+ *
166
+ * P25 §6 — the face-level ENTRY predicate. `waveLineRoute` answers `next-wave` for
167
+ * a batch that was never dispatched, which is right for the LINE but must not read
168
+ * as "this face is in flight": the documented window is plan-closed + graph present
169
+ * + zero wave rounds, and there the pipeline owes the plan face's `cdd-dev`
170
+ * handoff. A plan with no task block holds no batch at all, so it is the same
171
+ * never-entered case. BOTH cells are gated on the SAME predicate — clearing `active`
172
+ * alone would fall into rule 2 and render the wave face's own exit
173
+ * (`PIPELINE_NEXT.wave`), a worse literal than the one being removed. */
174
+ #waveState(input) {
175
+ const graph = input.planGraph;
176
+ const waveKey = graph === null ? null : this.#waveKeyOf(graph);
177
+ const entered = graph !== null && this.#wavesEntered(graph);
178
+ return {
179
+ closed: graph !== null && this.#wavesExhausted(graph),
180
+ active: entered && waveKey !== null ? this.#ledger.waveLineRoute(waveKey) : null,
181
+ target: !entered || input.planPath === null
182
+ ? null
183
+ : { type: "wave", id: waveKey ?? "", plan: input.planPath },
184
+ };
185
+ }
186
+ /** The branch face — judged AT its identity document (the plan): a plan revision
187
+ * past the one the completed branch review bound reopens the face. The branch line
188
+ * is always present (a live tree), so its target is never null. */
189
+ #branchState(input) {
190
+ const planPath = input.planPath;
191
+ return {
192
+ closed: this.#ledger.lineStateAt("branch", "branch", planPath) === "closed",
193
+ active: this.#ledger.lineRoute("branch", "branch"),
194
+ target: { type: "branch", id: "branch", plan: planPath ?? undefined },
195
+ };
196
+ }
197
+ /** The plan's open frontier wave key — the ready batch over the node's
198
+ * `closedWaves()` set, the SAME derivation the dispatch engine's task-graph
199
+ * frontier walks (T26, the wave-unitary model). Null when no wave remains open. */
200
+ #waveKeyOf(graph) {
201
+ const frontier = graph.frontier(this.#ledger.closedWaves());
202
+ return frontier.length === 0 ? null : frontier.join(",");
203
+ }
204
+ /** Whether the wave FACE was ever entered — the face-level predicate (P25 §6), never
205
+ * a per-key one: `#waveKeyOf` answers the READY batch, whose own row is empty the
206
+ * moment the previous batch closes, so a per-key read would call every batch
207
+ * boundary "never entered" and retreat to the plan handoff mid-plan. The scan
208
+ * therefore walks EVERY derived batch's key (the same `join(",")` spelling as
209
+ * `#waveKeyOf`) and sums the three dispatch modes' round counts — a dispatched but
210
+ * BLOCKED round counts, because the face WAS entered. No `identity` argument: a wave
211
+ * row is keyed by its joined task ids alone (`rowFor` matches `row.wave`). */
212
+ #wavesEntered(graph) {
213
+ return graph.batches().some((batch) => {
214
+ const key = batch.join(",");
215
+ return WAVE_ROUND_MODES.some((mode) => this.#ledger.roundCount(key, mode) > 0);
216
+ });
217
+ }
218
+ /** Whether every derived wave is done — the wave face's closure cell (a plan with
219
+ * no wave holds nothing closed). */
220
+ #wavesExhausted(graph) {
221
+ const report = graph.report(this.#ledger.closedWaves());
222
+ const done = new Set(report.done);
223
+ return (report.waves.length > 0 && report.waves.every((wave) => wave.every((id) => done.has(id))));
224
+ }
225
+ /** The anchor face's OWN pipeline exit — the row its render TARGET declares
226
+ * (`PIPELINE_NEXT[target.type]`, the SAME one table the capsule's `done` face reads
227
+ * through the ONE derivation). The identity face's target type IS the document's
228
+ * declared word, so a `single-spec` closes onto its `done` row, never the phase-spec
229
+ * line's `cdd-plan` ref; every node face's target type is its face key, so the lookup
230
+ * is the face key there. A face with no target (never entered) falls back to its
231
+ * pipeline face's row. */
232
+ static #exitRoute(faceIndex, state) {
233
+ if (state.target === null)
234
+ return NextStepRouter.handoff(PIPELINE_FACES[faceIndex]);
235
+ return { kind: "handoff", entry: PIPELINE_NEXT[state.target.type] };
236
+ }
237
+ /** The index of the last OBSERVED face carrying a render target — the last face the
238
+ * pipeline has REACHED. A face carries no target when its document is absent OR its
239
+ * own entry predicate never held; either way it was never entered. -1 when none is. */
240
+ static #lastEnteredIndex(states) {
241
+ for (let i = states.length - 1; i >= 0; i--) {
242
+ if (states[i].target !== null)
243
+ return i;
244
+ }
245
+ return -1;
246
+ }
247
+ }