@oscaner-skills/cdd-engine 4.3.0 → 4.5.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,260 @@
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 the wave FACE was ever entered — the face-level predicate (P25 §6), never
219
+ * a per-key one (the private scan's own judgment). Public because the dispatch
220
+ * authority's upstream leg asks the SAME question (P27 §2.3: a face the pipeline
221
+ * never entered holds no station), and no second entered-scan may exist. */
222
+ wavesEntered(graph) {
223
+ return this.#wavesEntered(graph);
224
+ }
225
+ /** Whether every derived wave is done — the wave face's closure cell (a plan with
226
+ * no wave holds nothing closed). Public for the same reason as `wavesEntered`: the
227
+ * upstream leg's criterion ② reads this ONE judge, never a local task walk. */
228
+ wavesExhausted(graph) {
229
+ return this.#wavesExhausted(graph);
230
+ }
231
+ /** Whether every derived wave is done — the wave face's closure cell (a plan with
232
+ * no wave holds nothing closed). */
233
+ #wavesExhausted(graph) {
234
+ const report = graph.report(this.#ledger.closedWaves());
235
+ const done = new Set(report.done);
236
+ return (report.waves.length > 0 && report.waves.every((wave) => wave.every((id) => done.has(id))));
237
+ }
238
+ /** The anchor face's OWN pipeline exit — the row its render TARGET declares
239
+ * (`PIPELINE_NEXT[target.type]`, the SAME one table the capsule's `done` face reads
240
+ * through the ONE derivation). The identity face's target type IS the document's
241
+ * declared word, so a `single-spec` closes onto its `done` row, never the phase-spec
242
+ * line's `cdd-plan` ref; every node face's target type is its face key, so the lookup
243
+ * is the face key there. A face with no target (never entered) falls back to its
244
+ * pipeline face's row. */
245
+ static #exitRoute(faceIndex, state) {
246
+ if (state.target === null)
247
+ return NextStepRouter.handoff(PIPELINE_FACES[faceIndex]);
248
+ return { kind: "handoff", entry: PIPELINE_NEXT[state.target.type] };
249
+ }
250
+ /** The index of the last OBSERVED face carrying a render target — the last face the
251
+ * pipeline has REACHED. A face carries no target when its document is absent OR its
252
+ * own entry predicate never held; either way it was never entered. -1 when none is. */
253
+ static #lastEnteredIndex(states) {
254
+ for (let i = states.length - 1; i >= 0; i--) {
255
+ if (states[i].target !== null)
256
+ return i;
257
+ }
258
+ return -1;
259
+ }
260
+ }
@@ -1,14 +1,16 @@
1
1
  // packages/cdd-engine/src-next/session/preflight.ts
2
- // P4.1 T1 — the lifecycle pre-flight seam (design spec §1): the dispatch gates
2
+ // P4.1 T1 — the lifecycle pre-flight seam (design spec §1): the STRUCTURE gates
3
3
  // converge into ONE single-entry gate a work command consults before ANY child
4
4
  // dispatch — the clean-tree hard gate (tree-clean → BLOCKED with the commit/discard
5
5
  // guidance, the skill-side claim `engine entry gate: dirty → BLOCKED` finally made
6
- // real), then the plan/ledger structure gate (`plan-ledger`, P21 §3.1/§6.4), the
7
- // wave-side gates (graph validate + the three-verb WaveGate) and the doc-side gate
8
- // (Contract.validate over the target doc).
6
+ // real), then the in-flight gate, the plan/ledger structure gate (`plan-ledger`, P21
7
+ // §3.1/§6.4), the graph validate and the doc-side gate (Contract.validate over the
8
+ // target doc). The dispatch's own phase — the wave face's gate and the doc/branch
9
+ // line's — is NOT judged here: it belongs to the ONE dispatch authority
10
+ // (`session/dispatch-authority.ts`, P27 §2), the seam's single consumer.
9
11
  //
10
12
  // Gate order (the design's pinned sequence, judgeable on every verdict):
11
- // tree-clean → in-flight → graph → plan-ledger → (wave face) WaveGate.vet →
13
+ // tree-clean → in-flight → graph → plan-ledger →
12
14
  // (spec/plan faces) Contract.validate → dispatch
13
15
  // The evidence/read-back gates stay at the dispatch child face (the seam never
14
16
  // touches the round's produced artifacts — non-pre-flight by design).
@@ -32,7 +34,6 @@ import { SlugIndex } from "../infra/slug-index.js";
32
34
  import { TargetFaceTable } from "./faces.js";
33
35
  import { TaskGraph } from "./graph.js";
34
36
  import { RoundRecords } from "./ledger.js";
35
- import { WaveGate } from "./wave.js";
36
37
  /**
37
38
  * PreFlight — the single pre-flight seam of the work dispatch. One `vet` call runs
38
39
  * the whole gate sequence in the pinned order and returns the verdict the CLI
@@ -44,8 +45,6 @@ export class PreFlight {
44
45
  #git;
45
46
  /** The doc-contract coordinator the doc faces judge through. */
46
47
  #contract;
47
- /** The three-verb unified wave gate the wave face consults. */
48
- #waveGate;
49
48
  /** The word table the BLOCK wording rides. */
50
49
  #words;
51
50
  /** The filesystem seam the doc-contract gate reads (defaults to node:fs). */
@@ -54,12 +53,11 @@ export class PreFlight {
54
53
  this.#git = opts.git;
55
54
  this.#contract = opts.contract;
56
55
  this.#words = opts.words;
57
- this.#waveGate = opts.waveGate ?? new WaveGate();
58
56
  this.#fs = opts.fs ?? new NodeFs();
59
57
  }
60
58
  /** vet(ctx) — the single seam call: tree-clean → in-flight → graph → plan-ledger
61
- * → wave → doc-contract. The first refused gate owns the verdict; the gates that
62
- * ran precede it (the judgeable order). */
59
+ * → doc-contract. The first refused gate owns the verdict; the gates that ran
60
+ * precede it (the judgeable order). */
63
61
  async vet(ctx) {
64
62
  const gates = [];
65
63
  const checked = [];
@@ -135,21 +133,7 @@ export class PreFlight {
135
133
  }
136
134
  }
137
135
  }
138
- // 5. wave — the three-verb unified wave gate.
139
- if (ctx.type === "wave" && graph !== null && ctx.ledger !== null && ctx.tasks !== null) {
140
- gates.push("wave");
141
- checked.push("wave");
142
- const verdict = this.#waveGate.vet(ctx.tasks, ctx.verb, graph, ctx.ledger, this.#words);
143
- if (!verdict.ok) {
144
- return this.#refusal({
145
- ok: false,
146
- gate: "wave",
147
- reason: verdict.reason,
148
- message: verdict.message ?? "",
149
- }, gates, checked, this.#docOutcomeOf(ctx), ledgerOutcome);
150
- }
151
- }
152
- // 6. doc-contract — the doc shapes' structural gate (the doc-scope rules).
136
+ // 5. doc-contract — the doc shapes' structural gate (the doc-scope rules).
153
137
  // The four document shapes (`phase-spec` · `overall` · `plan` · `single-spec`)
154
138
  // are judged by the SAME gate: the document's declared `doc-type:` picks the
155
139
  // contract, never the command's `--type` spelling.
@@ -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
+ }