@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.
- package/README.md +2 -2
- package/README.zh-CN.md +1 -1
- package/dist/contract/doc-body.js +77 -0
- package/dist/contract/invariants.js +58 -1
- package/dist/contract/rules.js +8 -2
- package/dist/face/board-view.js +130 -190
- package/dist/face/capsule.js +26 -18
- package/dist/face/cli.js +175 -105
- package/dist/face/declare.js +6 -1
- package/dist/face/gate.js +61 -147
- package/dist/face/init.js +83 -24
- package/dist/face/plugins.js +70 -2
- package/dist/face/preview.js +27 -9
- package/dist/face/route-render.js +9 -0
- package/dist/face/words.js +8 -4
- package/dist/session/dispatch-authority.js +282 -0
- package/dist/session/ledger.js +45 -26
- package/dist/session/line-identity.js +2 -1
- package/dist/session/next.js +62 -21
- package/dist/session/pipeline.js +260 -0
- package/dist/session/preflight.js +10 -26
- package/dist/session/reviewed-identity.js +54 -0
- package/dist/session/run.js +107 -61
- package/dist/session/wave.js +6 -6
- package/package.json +1 -1
|
@@ -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
|
|
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
|
|
7
|
-
//
|
|
8
|
-
//
|
|
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 →
|
|
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
|
-
* →
|
|
62
|
-
*
|
|
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.
|
|
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
|
+
}
|