@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.
- package/README.md +38 -9
- package/README.zh-CN.md +44 -10
- package/dist/contract/completion-criterion.js +351 -0
- package/dist/contract/declare.js +181 -43
- package/dist/contract/doc.js +84 -271
- package/dist/contract/frontmatter.js +2 -1
- package/dist/contract/home-extractors.js +49 -316
- package/dist/contract/invariants.js +400 -296
- package/dist/contract/judge.js +74 -49
- package/dist/contract/lint.js +3 -2
- package/dist/contract/liveness-signal.js +103 -0
- package/dist/contract/markdown-document.js +410 -0
- package/dist/contract/markdown-tree-types.js +6 -0
- package/dist/contract/markdown-tree.js +137 -0
- package/dist/contract/project.js +1 -1
- package/dist/contract/rules.js +106 -0
- package/dist/contract/selector-engine.js +332 -0
- package/dist/contract/selector-spec.js +74 -0
- package/dist/contract/skill-anatomy.js +29 -1
- package/dist/contract/task-block-grammar.js +285 -0
- package/dist/contract/task-blocks.js +65 -0
- package/dist/contract/translate.js +21 -0
- package/dist/contract/wave-width.js +15 -0
- package/dist/face/board-view.js +382 -172
- package/dist/face/capsule.js +73 -88
- package/dist/face/cli.js +152 -38
- package/dist/face/declare.js +42 -19
- package/dist/face/gate.js +119 -40
- package/dist/face/init.js +84 -25
- package/dist/face/lifecycle.js +540 -123
- package/dist/face/plugins.js +70 -2
- package/dist/face/preview.js +69 -18
- package/dist/face/route-render.js +60 -21
- package/dist/face/termination.js +135 -261
- package/dist/face/words.js +139 -13
- package/dist/infra/atomic.js +15 -0
- package/dist/infra/git.js +25 -0
- package/dist/infra/proc.js +150 -0
- package/dist/infra/round-log.js +104 -0
- package/dist/infra/runtime.js +16 -4
- package/dist/infra/workspace.js +7 -2
- package/dist/render/brief.js +15 -17
- package/dist/render/skeleton.js +41 -28
- package/dist/render/templates.js +128 -84
- package/dist/session/faces.js +47 -20
- package/dist/session/graph.js +13 -37
- package/dist/session/handoff-schema.js +16 -8
- package/dist/session/inflight.js +282 -0
- package/dist/session/ledger.js +603 -145
- package/dist/session/line-identity.js +33 -0
- package/dist/session/next.js +140 -80
- package/dist/session/pipeline.js +247 -0
- package/dist/session/preflight.js +276 -68
- package/dist/session/reviewed-identity.js +54 -0
- package/dist/session/round-naming.js +56 -8
- package/dist/session/run.js +364 -80
- package/dist/session/wave.js +94 -14
- 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
|
+
}
|
package/dist/session/next.js
CHANGED
|
@@ -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.
|
|
31
|
-
//
|
|
32
|
-
//
|
|
33
|
-
//
|
|
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 =
|
|
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
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
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
|
|
63
|
-
* iterates it, so a consumer maps key → facts and declares NO
|
|
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
|
|
69
|
-
* record the ruling in 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
|
|
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
|
|
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
|
+
}
|