@oscaner-skills/cdd-engine 4.3.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.
@@ -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
+ }
@@ -0,0 +1,54 @@
1
+ // packages/cdd-engine/src-next/session/reviewed-identity.ts
2
+ // P25 — the reviewed-revision write-back judgment's ONE home. Two faces state the
3
+ // same write-back: the lifecycle's `#bookkeep` (the record a real run appends) and
4
+ // the preview renderer's `#recordsOf` (the `would record:` forecast). Both ask this
5
+ // file which reviewed input a completed round binds: the phase whitelist is declared
6
+ // here once and the kind → leg mapping is decided here once, so one face can no
7
+ // longer drift from the other.
8
+ //
9
+ // The leg vocabulary is 1:1 with the lifecycle's three write-back methods: `doc` →
10
+ // `#recordReviewedDocRevision` (the plan and spec targets share it — the doc path
11
+ // rides the frame's target), `brief` → `#recordReviewedWaveBrief` (the RENDERED
12
+ // brief, D30), `branch` → `#recordReviewedBranchRevision` (the branch line's plan
13
+ // document).
14
+ //
15
+ // Three same-site facts that are INPUTS, never part of this judgment:
16
+ // 1. `targetAction` — the round verdict's completion flag, held by a real run alone;
17
+ // a dry run never has it, so each face applies it on its own side.
18
+ // 2. the plan path — the branch leg's identity SOURCE (the record method reads it;
19
+ // the preview states it from the scene). Because that path is an input, the
20
+ // branch target carries a leg name of its own instead of folding into `doc`.
21
+ // 3. the wave leg's asymmetry — when the line carries no plan path the real run
22
+ // records nothing while the preview still states the brief leg. Kept as it was:
23
+ // a face-side input difference, not a second judgment.
24
+ //
25
+ // Zero module-level bare functions — this module is one type, one const and the class.
26
+ /** The phases whose completed round binds a reviewed revision — the whitelist's ONE
27
+ * declaration: a completed review binds the revision it judged, a completed fix the
28
+ * revision it produced (so a warn-only fix cannot leave the line adrift in its own
29
+ * delta), and a branch-review rides the review family. `implement` binds nothing. */
30
+ export const REVIEWED_WRITE_PHASES = ["review", "branch-review", "fix"];
31
+ /** The reviewed-revision write-back judgment — which leg (if any) one round writes.
32
+ *
33
+ * A class rather than an arrow-constant object: the repo's zero-bare-function
34
+ * discipline admits no standalone judgment function, and a static-only class is the
35
+ * established shape for one pure read face (precedent: `TargetFaceTable`). */
36
+ // biome-ignore lint/complexity/noStaticOnlyClass: the judgment's one pure read face — the zero-bare-function discipline admits no standalone judgment function.
37
+ export class ReviewedIdentity {
38
+ /** The leg one round binds — null when the phase is outside the whitelist or the
39
+ * target kind has no write-back. An unlisted kind answers null on BOTH faces: a
40
+ * target union that ever grows writes nothing, never a silent doc write-back.
41
+ * Pure: it reads (phase, kind) and nothing else — no ledger, no file, no verdict,
42
+ * no plan path. */
43
+ static legOf(phase, kind) {
44
+ if (!REVIEWED_WRITE_PHASES.includes(phase))
45
+ return null;
46
+ if (kind === "wave")
47
+ return "brief";
48
+ if (kind === "plan" || kind === "spec")
49
+ return "doc";
50
+ if (kind === "branch")
51
+ return "branch";
52
+ return null;
53
+ }
54
+ }
@@ -22,6 +22,8 @@ import { PlanDocType } from "../contract/doc.js";
22
22
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
23
23
  import { Ledger, } from "./ledger.js";
24
24
  import { NextStepRouter } from "./next.js";
25
+ import { PipelineFrontier } from "./pipeline.js";
26
+ import { ReviewedIdentity } from "./reviewed-identity.js";
25
27
  /** The empty run state — a target line with no task frontier (branch/spec/plan):
26
28
  * the frontier query faces are always empty (a single-target line never continues
27
29
  * a batch) and markDone is a no-op. */
@@ -143,8 +145,23 @@ export class Lifecycle {
143
145
  * keep their existing behavior). */
144
146
  #preflight;
145
147
  /** The workspace plan path — the `next:` implement literal's required `--plan`
146
- * arg (P4.1 T4 — the task face's implement-consuming fact). */
148
+ * arg (P4.1 T4 — the task face's implement-consuming fact), and the plan cell of
149
+ * the pipeline frontier's input. A `--spec` round fills it from the document index
150
+ * (the same-slug plan the argv does not name); the plan / branch lines carry their
151
+ * argv value. */
147
152
  #planPath;
153
+ /** The pipeline frontier's declared identity — the spec line's DECLARED word (the
154
+ * `doc-type:` head key) and its document path. A node with no spec document
155
+ * (`#specPath === null`) keeps this line's own hop assembly: the frontier's rules
156
+ * anchor on an absent identity face, which would print a passed phase's transition. */
157
+ #specType;
158
+ #specPath;
159
+ /** The plan's task graph — the pipeline frontier's guarded plan read, injected by
160
+ * the composition root (the session plane reads no file). */
161
+ #planGraph;
162
+ /** The pipeline frontier — the ONE hop assembly this lifecycle's capsule renders
163
+ * (the same object the board renders). */
164
+ #frontier;
148
165
  /** The pipeline-station discrimination the hop derivation injects (P22 §5.2) —
149
166
  * the SAME face read the capsule/board use (`BoardView.docClassOf`). The
150
167
  * composition root passes it; the session-plane default keys by target type
@@ -160,6 +177,10 @@ export class Lifecycle {
160
177
  this.#capsule = opts.capsule ?? null;
161
178
  this.#preflight = opts.preflight ?? null;
162
179
  this.#planPath = opts.planPath ?? null;
180
+ this.#specType = opts.specType ?? null;
181
+ this.#specPath = opts.specPath ?? null;
182
+ this.#planGraph = opts.planGraph ?? null;
183
+ this.#frontier = new PipelineFrontier(this.#ledger);
163
184
  this.#docClassOf = opts.docClassOf ?? Lifecycle.#docClassByType;
164
185
  }
165
186
  /** The session-plane default discrimination — the target type's own pipeline key.
@@ -185,10 +206,10 @@ export class Lifecycle {
185
206
  * cursor pre-checks the next step against the requested verb before it advances
186
207
  * (a mismatch must not consume the round: advance() dispatches on entry — the
187
208
  * {16,22,24} bug's loop reordered lookahead-after-dispatch and spent the next
188
- * phase's round in the same invocation). The returned `hop` is the SAME `NextHop`
189
- * object the board and the CLI rejection message read (P22 §5.2's fourth read
190
- * face): one derivation over this line's facts, never a lookahead-only copy.
191
- * Null = the run is exhausted / capped (no open frame → no line to name). */
209
+ * phase's round in the same invocation). The returned `hop` is this line's own
210
+ * LINE FRONTIER assembly (`#hopOf`): the frame-keyed hop the CLI rejection message
211
+ * reads — never the pipeline frontier's assembly, which the capsule and the board
212
+ * share. Null = the run is exhausted / capped (no open frame → no line to name). */
192
213
  peekNext() {
193
214
  const frame = this.#openFrame();
194
215
  if (frame === null)
@@ -237,7 +258,7 @@ export class Lifecycle {
237
258
  frame,
238
259
  round,
239
260
  route,
240
- capsuleLines: this.#capsuleLines(frame, outcome, failed ? null : this.#hopOf(frame, route)),
261
+ capsuleLines: this.#capsuleLines(frame, outcome, failed ? null : this.#roundHop(frame, route)),
241
262
  termination: outcome.termination,
242
263
  };
243
264
  }
@@ -463,35 +484,39 @@ export class Lifecycle {
463
484
  violations: outcome.violations ?? [],
464
485
  carrierPath,
465
486
  }, frame.type);
466
- // The completed-review revision write-back is gated on the round's VERDICT (a
467
- // hard-failed review must not bind the current revision — that would silently
468
- // close the drift identity the review never judged). The doc line and the wave
469
- // line each bind their OWN reviewed revision (T7 doc · T11 wave / D16 / D30): a
470
- // completed review binds the CURRENT revision of the reviewed input — read at
471
- // bookkeep, the clean-tree dispatch gate keeps the read-only review's input
472
- // stable across the round. For a doc line that input is the target doc (the
473
- // whole-content doc-revision). For a wave line it is the RENDERED BRIEF —
474
- // `#recordReviewedWaveBrief` → `recordReviewedBrief(String(frame.key),
475
- // #planPath)` hashes the brief the plan renders to, holding #planPath only as
476
- // the plan the brief renders FROM (the render-from POINTER, not the hashed
477
- // identity; the wave gate derives the plan path FROM this record, so
478
- // cli.ts/preflight.ts stay untouched). The two legs do NOT share one gate —
479
- // each ref kind carries its own reviewed identity. An unreadable input records
480
- // nothing (present facts only); a null plan path (no plan fact) leaves a legacy
481
- // wave row — null stays backward compatible.
482
- if (record.verdict.targetAction &&
483
- (frame.phase === "review" || frame.phase === "branch-review")) {
484
- if (frame.target.kind === "plan" || frame.target.kind === "spec")
485
- this.#recordReviewedDocRevision(frame);
486
- else if (frame.target.kind === "wave")
487
- this.#recordReviewedWaveBrief(frame);
488
- else if (frame.target.kind === "branch")
489
- this.#recordReviewedBranchRevision(frame);
487
+ // The completed-round revision write-back is gated on the round's VERDICT (a
488
+ // hard-failed round must not bind the current revision — that would silently
489
+ // close the drift identity the round never delivered). WHICH reviewed input the
490
+ // round binds is ONE judgment, shared with the preview face:
491
+ // `ReviewedIdentity.legOf(frame.phase, frame.target.kind)`. Its phases — review,
492
+ // branch-review, fix — are declared there once, and its legs are 1:1 with this
493
+ // class's three `#record…` methods (doc · brief · branch). Two facts stay this
494
+ // face's OWN input, never the judgment: the verdict's `targetAction` (a real run
495
+ // alone holds it) and the plan path (the branch leg's render-from pointer). One
496
+ // asymmetry is preserved: on a wave round whose line carries no plan path the
497
+ // real run records nothing while the preview still states the brief leg. The
498
+ // record methods keep their own defensive narrowing; an unreadable input records
499
+ // nothing (present facts only).
500
+ const leg = record.verdict.targetAction
501
+ ? ReviewedIdentity.legOf(frame.phase, frame.target.kind)
502
+ : null;
503
+ if (leg !== null) {
504
+ switch (leg) {
505
+ case "doc":
506
+ this.#recordReviewedDocRevision(frame);
507
+ break;
508
+ case "brief":
509
+ this.#recordReviewedWaveBrief(frame);
510
+ break;
511
+ case "branch":
512
+ this.#recordReviewedBranchRevision(frame);
513
+ break;
514
+ }
490
515
  }
491
516
  return this.#ledger.roundCount(frame.key, frame.phase, frame.type);
492
517
  }
493
- /** The reviewed-revision write-back — bind the reviewed input's revision to the
494
- * line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
518
+ /** The reviewed-revision write-back — bind the completed round's input revision to
519
+ * the line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
495
520
  * doc face binds its target doc's whole-content revision; the wave face binds its
496
521
  * RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
497
522
  * never the whole plan: transcript edits outside the wave's task sections must not
@@ -503,8 +528,9 @@ export class Lifecycle {
503
528
  this.#recordDocRevisionOf(frame.key, frame.target.doc, frame.type);
504
529
  }
505
530
  /** The wave line's reviewed-brief write-back (D30) — bind the RENDERED brief's
506
- * revision for the wave's tasks to the row (the D30 wave-gate reopen basis). Null
507
- * plan path / underivable brief records nothing (present facts only). */
531
+ * revision for the wave's tasks to the row (the D30 wave-gate reopen basis) on a
532
+ * completed review or fix round. Null plan path / underivable brief records nothing
533
+ * (present facts only). */
508
534
  #recordReviewedWaveBrief(frame) {
509
535
  if (frame.target.kind !== "wave" || this.#planPath === null)
510
536
  return;
@@ -519,7 +545,7 @@ export class Lifecycle {
519
545
  return;
520
546
  this.#recordDocRevisionOf(frame.key, this.#planPath, frame.type);
521
547
  }
522
- /** The doc-revision write-back body — read the reviewed document and bind its
548
+ /** The doc-revision write-back body — read the round's document and bind its
523
549
  * current revision to the line row (the ONE read + hash + record path the doc and
524
550
  * branch legs share; each passes its own path source). An unreadable input records
525
551
  * nothing — the line keeps the legacy closed face (present facts only). */
@@ -594,14 +620,15 @@ export class Lifecycle {
594
620
  #routeState() {
595
621
  return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
596
622
  }
597
- /** The line's ONE next-hop object (§5.2) — this lifecycle's facts handed to the
598
- * ONE derivation (`Ledger#nextHopOf`): the recorded round's route, the line's
599
- * completed records, the drift-aware gate and the injected station
600
- * discrimination. The nullable route is handed over UNJUDGED — the assembly owns
601
- * the exit-side decision (a closed line's `null` route is where the drift reopen
602
- * lands), so the frontier face reads the same object the board and the gate read.
603
- * The failure face's absent hop is the CALLER's fact (`advance` passes null for a
604
- * BLOCKED/TIMEOUT round), never a second short-circuit here. */
623
+ /** The line's OWN next-hop object — the LINE FRONTIER assembly: this lifecycle's
624
+ * frame facts handed to the ONE derivation (`Ledger#nextHopOf`): the recorded
625
+ * round's route, the line's completed records, the drift-aware gate and the
626
+ * injected station discrimination. The nullable route is handed over UNJUDGED — the
627
+ * assembly owns the exit-side decision (a closed line's `null` route is where the
628
+ * drift reopen lands). Serves `peekNext` and the capsule's spec-less degradation
629
+ * only; the capsule's ordinary hop is the pipeline frontier's assembly
630
+ * (`#roundHop`). The failure face's absent hop is the CALLER's fact (`advance`
631
+ * passes null for a BLOCKED/TIMEOUT round), never a second short-circuit here. */
605
632
  #hopOf(frame, route) {
606
633
  const target = this.#routeTarget(frame);
607
634
  return this.#ledger.nextHopOf({
@@ -613,6 +640,9 @@ export class Lifecycle {
613
640
  // The wave closure's NEXT-line fact (P21 §4.2) rides the derivation's input
614
641
  // face — the retired render-side patch parameter is gone, the fact is not.
615
642
  nextLineOpen: frame.type === "wave" ? this.#branchLineOpen() : undefined,
643
+ // The wave line's OWN drift fact (D30): the reason cell's second source. Only
644
+ // the wave face injects it — every doc line reads its gate verdict instead.
645
+ briefDrift: frame.type === "wave" ? this.#ledger.briefDrifted(String(frame.key)) : undefined,
616
646
  docClassOf: (candidate) => this.#docClassOf(candidate),
617
647
  });
618
648
  }
@@ -625,25 +655,40 @@ export class Lifecycle {
625
655
  return this.#planPath;
626
656
  return null;
627
657
  }
658
+ /** The round's rendered hop — the PIPELINE frontier's ONE assembly when the node
659
+ * holds a spec document (the object the board's `next:` row renders, so the two
660
+ * faces state one hop), this line's own frame-keyed assembly otherwise. The
661
+ * degradation key is `#specPath === null` and nothing else: a plan-only phase is the
662
+ * ordinary spec-less shape, and there the frontier's rules anchor on an absent
663
+ * identity face (rule 3) — it would print a transition the line has already taken. */
664
+ #roundHop(frame, route) {
665
+ if (this.#specPath === null)
666
+ return this.#hopOf(frame, route);
667
+ return this.#frontier.hopOf(this.#pipelineInput(), { docClassOf: (c) => this.#docClassOf(c) });
668
+ }
669
+ /** The pipeline frontier's four declared cells — assembled once from the injected
670
+ * facts so no second judge is introduced here. */
671
+ #pipelineInput() {
672
+ return {
673
+ specType: this.#specType,
674
+ specPath: this.#specPath,
675
+ planPath: this.#planPath,
676
+ planGraph: this.#planGraph,
677
+ };
678
+ }
628
679
  /** Whether the branch line has a dispatchable open round — the wave closure's
629
- * NEXT-line fact (P21 §4.2), read HERE (the ledger-holding side) from the two
630
- * already-registered ledger faces: the branch row's drift-aware gate (the plan
631
- * moved past its reviewed doc-revision) or a still-active C5 hop. `undefined` when
632
- * no plan fact exists (the wave row keeps its plain station). */
680
+ * NEXT-line fact (P21 §4.2), delegated to the pipeline frontier's ONE judge (the
681
+ * shared hop assembly's sixth cell). The lifecycle now holds no copy of the gate /
682
+ * route combination. */
633
683
  #branchLineOpen() {
634
- if (this.#planPath === null)
635
- return undefined;
636
- const gate = this.#ledger.reviewGate("branch", this.#planPath, "branch");
637
- if (gate.kind === "open")
638
- return true;
639
- return this.#ledger.lineRoute("branch", "branch") !== null;
684
+ return this.#frontier.branchLineOpen(this.#planPath);
640
685
  }
641
686
  /** The capsule lines of one step — empty unless a capsule is attached (the non-hard
642
687
  * interaction point). A success round carries the handoff carrier path; a failure
643
688
  * round (TIMEOUT / BLOCKED) carries the crash record as its handoff cell, emitted
644
689
  * only when that record exists (a no-host BLOCKED writes none). The fix round's
645
690
  * disposition summary is handed to the capsule as its `summary` — the render places
646
- * it between the status line and the trailing `next:` literal (P22 §10). */
691
+ * it between the status line and the `next:` row (P22 §10). */
647
692
  #capsuleLines(frame, outcome, hop) {
648
693
  const summary = outcome.dispositionsSummary;
649
694
  if (this.#capsule === null)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.3.0",
3
+ "version": "4.4.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {