@oscaner-skills/cdd-engine 1.0.0 → 2.0.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 +9 -8
- package/README.zh-CN.md +9 -8
- package/package.json +15 -22
- package/src-next/__tests__/bin.test.ts +128 -0
- package/src-next/__tests__/smoke.integration.test.ts +202 -0
- package/src-next/__tests__/zero-dep.test.ts +134 -0
- package/src-next/bin.ts +61 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
- package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
- package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
- package/src-next/contract/__tests__/declare.test.ts +242 -0
- package/src-next/contract/__tests__/doc.test.ts +358 -0
- package/src-next/contract/__tests__/judge.test.ts +873 -0
- package/src-next/contract/__tests__/lint.test.ts +314 -0
- package/src-next/contract/__tests__/project.test.ts +419 -0
- package/src-next/contract/__tests__/translate.test.ts +96 -0
- package/src-next/contract/declare.ts +983 -0
- package/src-next/contract/doc.ts +753 -0
- package/src-next/contract/invariants.ts +1268 -0
- package/src-next/contract/judge.ts +142 -0
- package/src-next/contract/lint.ts +275 -0
- package/src-next/contract/project.ts +596 -0
- package/src-next/contract/skill-anatomy.ts +273 -0
- package/src-next/contract/translate.ts +113 -0
- package/src-next/face/__tests__/board-view.test.ts +948 -0
- package/src-next/face/__tests__/capsule.test.ts +276 -0
- package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
- package/src-next/face/__tests__/cli.test.ts +4643 -0
- package/src-next/face/__tests__/face.test.ts +289 -0
- package/src-next/face/__tests__/graph-view.test.ts +61 -0
- package/src-next/face/__tests__/host.test.ts +24 -0
- package/src-next/face/__tests__/negation.ts +6 -0
- package/src-next/face/__tests__/projection.test.ts +301 -0
- package/src-next/face/__tests__/sync-runner.test.ts +70 -0
- package/src-next/face/__tests__/words.guard.test.ts +93 -0
- package/src-next/face/artifacts.ts +195 -0
- package/src-next/face/board-view.ts +662 -0
- package/src-next/face/capsule.ts +149 -0
- package/src-next/face/cli.ts +819 -0
- package/src-next/face/declare.ts +326 -0
- package/src-next/face/gate.ts +170 -0
- package/src-next/face/graph-view.ts +74 -0
- package/src-next/face/host.ts +326 -0
- package/src-next/face/lifecycle.ts +700 -0
- package/src-next/face/projection.ts +282 -0
- package/src-next/face/route-render.ts +160 -0
- package/src-next/face/words.ts +296 -0
- package/src-next/infra/__tests__/infra.test.ts +287 -0
- package/src-next/infra/config.ts +42 -0
- package/src-next/infra/git.ts +39 -0
- package/src-next/infra/process.ts +34 -0
- package/src-next/infra/runtime.ts +185 -0
- package/src-next/infra/workspace.ts +232 -0
- package/src-next/render/__tests__/render.test.ts +499 -0
- package/src-next/render/__tests__/skeleton.test.ts +466 -0
- package/src-next/render/brief.ts +121 -0
- package/src-next/render/issue-body.ts +159 -0
- package/src-next/render/skeleton.ts +437 -0
- package/src-next/render/templates.ts +650 -0
- package/src-next/session/__tests__/graph.test.ts +270 -0
- package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
- package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
- package/src-next/session/__tests__/ledger.test.ts +744 -0
- package/src-next/session/__tests__/next.test.ts +368 -0
- package/src-next/session/__tests__/preflight.test.ts +491 -0
- package/src-next/session/__tests__/run.test.ts +1014 -0
- package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
- package/src-next/session/__tests__/wave.test.ts +469 -0
- package/src-next/session/faces.ts +110 -0
- package/src-next/session/graph.ts +411 -0
- package/src-next/session/handoff-schema.ts +373 -0
- package/src-next/session/ledger.ts +1004 -0
- package/src-next/session/next.ts +192 -0
- package/src-next/session/preflight.ts +240 -0
- package/src-next/session/run.ts +606 -0
- package/src-next/session/state.ts +30 -0
- package/src-next/session/wave.ts +139 -0
- package/templates/report/issue-body.json +18 -20
- package/dist/chunks/branch.mjs +0 -480
- package/dist/chunks/docs.mjs +0 -253
- package/dist/chunks/task.mjs +0 -913
- package/dist/cli.mjs +0 -5457
- package/dist/documents/schema/add-phase-protocol.json +0 -126
- package/dist/documents/schema/overall.json +0 -361
- package/dist/documents/schema/phase-spec.json +0 -145
- package/dist/documents/schema/plan.json +0 -191
- package/dist/documents/schema/skill-anatomy.json +0 -233
- package/dist/resources/harness-registry.json +0 -49
- package/dist/shared/cdd-engine.liioziig.mjs +0 -184
- package/templates/engine-config.json +0 -302
- package/templates/schema/cache-profile-schema.json +0 -23
- package/templates/schema/docs-handoff-schema.json +0 -129
- package/templates/schema/task-handoff-schema.json +0 -332
- package/templates/template-contract.json +0 -231
|
@@ -0,0 +1,606 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/session/run.ts
|
|
2
|
+
// T8 — the parameterized single lifecycle (design spec §3.3): the three old
|
|
3
|
+
// near-isomorphic lifecycles converge into ONE class whose per-type variance is the
|
|
4
|
+
// faces table (faces.ts). advance() runs one dispatch step — one dispatch, one
|
|
5
|
+
// advance:
|
|
6
|
+
//
|
|
7
|
+
// frontier → dispatch → result → bookkeeping → next routing
|
|
8
|
+
//
|
|
9
|
+
// The lifecycle composes the T6 execution state (the frontier dynamic face + the
|
|
10
|
+
// done-set), the T7 NextStepRouter (the C5 next-generation single point) and the T9
|
|
11
|
+
// ledger (progress · handoff · round — the on-disk record of every round). The
|
|
12
|
+
// capsule interaction point (face/capsule — T10) is a seam: the CapsuleFace
|
|
13
|
+
// interface declared here is satisfied by T10's Capsule, and the lifecycle advances
|
|
14
|
+
// without a capsule (non-hard consumption — T8 builds no hard dependency toward
|
|
15
|
+
// T10); the attachCapsule seam only renders the step's round facts when a capsule is
|
|
16
|
+
// connected.
|
|
17
|
+
//
|
|
18
|
+
// Module-level exports are types / the class / one empty-state data const — zero
|
|
19
|
+
// behavior-carrying bare functions (the plan's zero-bare-function discipline).
|
|
20
|
+
|
|
21
|
+
import { readFileSync } from "node:fs";
|
|
22
|
+
import type { DispatchPhase, ReviewLead, RouteTarget, TargetFace, TargetType } from "./faces.ts";
|
|
23
|
+
import {
|
|
24
|
+
type HandoffParams,
|
|
25
|
+
Ledger,
|
|
26
|
+
type LedgerKey,
|
|
27
|
+
type OpType,
|
|
28
|
+
type RoundFinding,
|
|
29
|
+
type RoundStatus,
|
|
30
|
+
} from "./ledger.ts";
|
|
31
|
+
import type { Route } from "./next.ts";
|
|
32
|
+
import { NextStepRouter } from "./next.ts";
|
|
33
|
+
import type { PreFlightVerdict } from "./preflight.ts";
|
|
34
|
+
import type { ExecutionState, Frontier } from "./state.ts";
|
|
35
|
+
|
|
36
|
+
/** The pre-flight dispatch-entry gate — the lifecycle's hard "no child on a refused
|
|
37
|
+
* frame" wiring (P4.1 T1): the CLI computes the seam verdict ONCE and hands it to
|
|
38
|
+
* the lifecycle as the gate, so a refused dispatch is structurally never passed to
|
|
39
|
+
* the child. Null = no gate wired (a gate-less lifecycle advances unguarded — the
|
|
40
|
+
* seam-less callers keep their existing behavior). */
|
|
41
|
+
export interface PreFlightGate {
|
|
42
|
+
/** The pre-flight verdict for one dispatch frame (null = no verdict for the frame
|
|
43
|
+
* — the dispatch proceeds; a refused verdict blocks the dispatch). */
|
|
44
|
+
gate(frame: OpenFrame): PreFlightVerdict | null;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The run-state the lifecycle drives — the T6 query surfaces (frontier dynamic
|
|
48
|
+
* face + the done-set) plus the done marking. TaskGraph implements the whole face;
|
|
49
|
+
* the branch/spec/plan lines pass EMPTY_RUN_STATE. */
|
|
50
|
+
export interface RunState extends ExecutionState, Frontier {
|
|
51
|
+
/** Record a completed task — the frontier only advances past marked tasks. */
|
|
52
|
+
markDone(id: number): void;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** The empty run state — a target line with no task frontier (branch/spec/plan):
|
|
56
|
+
* the frontier query faces are always empty (a single-target line never continues
|
|
57
|
+
* a batch) and markDone is a no-op. */
|
|
58
|
+
export const EMPTY_RUN_STATE: RunState = {
|
|
59
|
+
doneTasks: () => new Set(),
|
|
60
|
+
readyBatch: () => [],
|
|
61
|
+
frontier: () => [],
|
|
62
|
+
markDone: () => undefined,
|
|
63
|
+
};
|
|
64
|
+
|
|
65
|
+
/** The audit target of one dispatch step — what the round audits. */
|
|
66
|
+
export type AuditTarget =
|
|
67
|
+
/** wave (T26 · the wave-unitary model): the frontier's open wave — the whole ready
|
|
68
|
+
* batch is ONE dispatch unit (one brief · one child · one commit · one round). */
|
|
69
|
+
| { kind: "wave"; tasks: readonly number[] }
|
|
70
|
+
/** branch: the branch line itself (no commit identity — the review's scope anchor
|
|
71
|
+
* rides the engine-injected BASE_BRANCH, never a stored range). */
|
|
72
|
+
| { kind: "branch" }
|
|
73
|
+
/** spec/plan: the audit document path. */
|
|
74
|
+
| { kind: "doc"; doc: string };
|
|
75
|
+
|
|
76
|
+
/** One dispatch step's full identity — what the lifecycle dispatches. */
|
|
77
|
+
export interface OpenFrame {
|
|
78
|
+
/** The target face the step runs on. */
|
|
79
|
+
type: TargetType;
|
|
80
|
+
/** The round's dispatch phase. */
|
|
81
|
+
phase: DispatchPhase;
|
|
82
|
+
/** The round number (the handoff increment: review rounds count up; fix rounds
|
|
83
|
+
* source their source review's number). */
|
|
84
|
+
round: number;
|
|
85
|
+
/** The audit target the round audits. */
|
|
86
|
+
target: AuditTarget;
|
|
87
|
+
/** The handoff params the round writes under. */
|
|
88
|
+
params: HandoffParams;
|
|
89
|
+
/** The progress ledger key the round records under (a wave key string / a
|
|
90
|
+
* line-type constant — branch · spec · plan). */
|
|
91
|
+
key: LedgerKey;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** One round's dispatch outcome — what the lifecycle records and routes on. */
|
|
95
|
+
export interface DispatchOutcome {
|
|
96
|
+
/** The round's concluding status. */
|
|
97
|
+
status: RoundStatus;
|
|
98
|
+
/** The round's findings (review: this round's own; fix: the source review's
|
|
99
|
+
* input findings, C5-1). */
|
|
100
|
+
findings?: readonly RoundFinding[];
|
|
101
|
+
/** The artifact paths the round produced (brief/report/…). */
|
|
102
|
+
artifacts?: Record<string, string>;
|
|
103
|
+
/** The materialized final carrier (the production dispatch's read-back
|
|
104
|
+
* reconstruct — §3.6: the child draft validated and built into the carrier the
|
|
105
|
+
* bookkeep persists verbatim, full-replace at the SAME path; agent draft →
|
|
106
|
+
* finalized, the engine stays the single author). Absent for the hermetic /
|
|
107
|
+
* dry-run dispatchers — the bookkeep builds the carrier from the outcome fields. */
|
|
108
|
+
carrier?: Record<string, unknown>;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** The dispatch instruction — runs one round's actual work (the harness call in
|
|
112
|
+
* production; a stub in tests). The lifecycle never inspects how the work runs. */
|
|
113
|
+
export type DispatchStep = (frame: OpenFrame) => DispatchOutcome;
|
|
114
|
+
|
|
115
|
+
/** The capsule interaction seam — the face/capsule contact. T10's Capsule satisfies
|
|
116
|
+
* this shape; the lifecycle advances without a capsule (non-hard consumption) and
|
|
117
|
+
* attachCapsule only renders the step's round facts when a capsule is connected. */
|
|
118
|
+
export interface CapsuleFace {
|
|
119
|
+
/** Render the capsule lines for one round's facts — byte-stable `status · blocker
|
|
120
|
+
* · handoff` plus the optional `next:` line (the words ride the face's word
|
|
121
|
+
* table). The additive optional RouteTarget supplies the dispatch frame's own
|
|
122
|
+
* type + id for the dispatch-ready `next:` literal (v1.25 — the 4-param call
|
|
123
|
+
* stays valid: the target is an optional 5th). */
|
|
124
|
+
emit(
|
|
125
|
+
status: string,
|
|
126
|
+
blocker: string,
|
|
127
|
+
handoff: string,
|
|
128
|
+
next?: Route | string | null,
|
|
129
|
+
target?: RouteTarget | null,
|
|
130
|
+
): string[];
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** One advance step's result — the facts the caller drives on. */
|
|
134
|
+
export interface StepResult {
|
|
135
|
+
/** The frame the step dispatched. */
|
|
136
|
+
frame: OpenFrame;
|
|
137
|
+
/** The round count on record after bookkeeping. */
|
|
138
|
+
round: number;
|
|
139
|
+
/** The C5 next-hop route after this step (consumed per the face's next
|
|
140
|
+
* semantics: a next-wave advances the task batch — batch faces only). */
|
|
141
|
+
route: Route | null;
|
|
142
|
+
/** The capsule lines rendered at the interaction point (empty when no capsule is
|
|
143
|
+
* attached — the seam is non-hard). */
|
|
144
|
+
capsuleLines: readonly string[];
|
|
145
|
+
/** The pre-flight verdict of a refused dispatch — the lifecycle's dispatch-entry
|
|
146
|
+
* gate blocked the frame before ANY child dispatch (absent on ordinary steps).
|
|
147
|
+
* The refused frame is NOT recorded — the frontier re-offers it (resume). */
|
|
148
|
+
preflight?: PreFlightVerdict;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Lifecycle — the parameterized single lifecycle over one target-type face. One
|
|
153
|
+
* instance drives one target line. advance() runs one dispatch step:
|
|
154
|
+
*
|
|
155
|
+
* frontier — resolve the open frame from the face's audit descriptor;
|
|
156
|
+
* dispatch — run the injected dispatch instruction, capture the outcome;
|
|
157
|
+
* bookkeep — persist the handoff carrier + record the progress round;
|
|
158
|
+
* close — the recorded round's C5 route is the single closure verdict: the
|
|
159
|
+
* lifecycle marks the task done when the route kind closes the line
|
|
160
|
+
* (terminal ⇔ route.kind ∈ {done, next-wave} — desync-proof, the
|
|
161
|
+
* router's point, never a folded table);
|
|
162
|
+
* route — the delivered C5 next-hop Route, re-judged with the closed task out
|
|
163
|
+
* of the ready batch (a closing review routes `done`, not a phantom
|
|
164
|
+
* next-wave of the just-closed task).
|
|
165
|
+
*/
|
|
166
|
+
export class Lifecycle {
|
|
167
|
+
/** The target face this instance drives — the row of the faces table. */
|
|
168
|
+
readonly #face: TargetFace;
|
|
169
|
+
/** The run state the lifecycle reads and marks. */
|
|
170
|
+
readonly #state: RunState;
|
|
171
|
+
/** The session ledger — the round + progress single author. */
|
|
172
|
+
readonly #ledger: Ledger;
|
|
173
|
+
/** The C5 next router — the next-hop single point. */
|
|
174
|
+
readonly #router: NextStepRouter;
|
|
175
|
+
/** The dispatch instruction — the round's actual work, injected. */
|
|
176
|
+
readonly #dispatch: DispatchStep;
|
|
177
|
+
/** The fixed audit target of a branch-tree / doc-path face (the task face
|
|
178
|
+
* resolves it from the frontier). */
|
|
179
|
+
readonly #target: AuditTarget | null;
|
|
180
|
+
/** The attached capsule face — null = the step advances output-less. */
|
|
181
|
+
#capsule: CapsuleFace | null;
|
|
182
|
+
/** The dispatch-entry pre-flight gate — null = unguarded (the seam-less callers
|
|
183
|
+
* keep their existing behavior). */
|
|
184
|
+
readonly #preflight: PreFlightGate | null;
|
|
185
|
+
/** The workspace plan path — the `next:` implement literal's required `--plan`
|
|
186
|
+
* arg (P4.1 T4 — the task face's implement-consuming fact). */
|
|
187
|
+
readonly #planPath: string | null;
|
|
188
|
+
|
|
189
|
+
constructor(opts: {
|
|
190
|
+
face: TargetFace;
|
|
191
|
+
state: RunState;
|
|
192
|
+
ledger: Ledger;
|
|
193
|
+
dispatch: DispatchStep;
|
|
194
|
+
router?: NextStepRouter;
|
|
195
|
+
/** The fixed audit target for a branch-tree / doc-path face. */
|
|
196
|
+
target?: AuditTarget;
|
|
197
|
+
/** The capsule face to attach at construction (optional — the seam is non-hard). */
|
|
198
|
+
capsule?: CapsuleFace | null;
|
|
199
|
+
/** The dispatch-entry pre-flight gate (P4.1 T1 — the lifecycle's hard "no child
|
|
200
|
+
* on a refused frame" wiring; optional, null = unguarded). */
|
|
201
|
+
preflight?: PreFlightGate | null;
|
|
202
|
+
/** The workspace plan path (P4.1 T4 — the implement `next:` literal's `--plan`). */
|
|
203
|
+
planPath?: string | null;
|
|
204
|
+
}) {
|
|
205
|
+
this.#face = opts.face;
|
|
206
|
+
this.#state = opts.state;
|
|
207
|
+
this.#ledger = opts.ledger;
|
|
208
|
+
this.#dispatch = opts.dispatch;
|
|
209
|
+
this.#router = opts.router ?? new NextStepRouter();
|
|
210
|
+
this.#target = opts.target ?? null;
|
|
211
|
+
this.#capsule = opts.capsule ?? null;
|
|
212
|
+
this.#preflight = opts.preflight ?? null;
|
|
213
|
+
this.#planPath = opts.planPath ?? null;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/** The face row this instance drives. */
|
|
217
|
+
face(): TargetFace {
|
|
218
|
+
return this.#face;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/** Attach the capsule face — the interaction point (T10's Capsule plugs in; null
|
|
222
|
+
* detaches and the step advances output-less). Returns this for chaining. */
|
|
223
|
+
attachCapsule(capsule: CapsuleFace | null): this {
|
|
224
|
+
this.#capsule = capsule;
|
|
225
|
+
return this;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/** Peek the line's next open frame WITHOUT dispatching — the CLI's per-invocation
|
|
229
|
+
* cursor pre-checks the next step against the requested verb before it advances
|
|
230
|
+
* (a mismatch must not consume the round: advance() dispatches on entry — the
|
|
231
|
+
* {16,22,24} bug's loop reordered lookahead-after-dispatch and spent the next
|
|
232
|
+
* phase's round in the same invocation). Null = the run is exhausted / capped. */
|
|
233
|
+
peekNext(): OpenFrame | null {
|
|
234
|
+
return this.#openFrame();
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/** advance() — one dispatch step: frontier → pre-flight gate → dispatch → result →
|
|
238
|
+
* bookkeeping → next routing. Null when the line holds no open frame (the run is
|
|
239
|
+
* exhausted or a capped line defers to the user). A refused pre-flight gate blocks
|
|
240
|
+
* the dispatch (child zero) and returns the frame as a preflight-blocked step —
|
|
241
|
+
* neither persisted nor recorded (the frontier re-offers it: resume). */
|
|
242
|
+
advance(): StepResult | null {
|
|
243
|
+
const frame = this.#openFrame();
|
|
244
|
+
if (frame === null) return null;
|
|
245
|
+
if (this.#preflight !== null) {
|
|
246
|
+
const verdict = this.#preflight.gate(frame);
|
|
247
|
+
if (verdict !== null && !verdict.ok) {
|
|
248
|
+
return {
|
|
249
|
+
frame,
|
|
250
|
+
round: this.#ledger.roundCount(frame.key, frame.phase),
|
|
251
|
+
route: null,
|
|
252
|
+
capsuleLines: [],
|
|
253
|
+
preflight: verdict,
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
const outcome = this.#dispatch(frame);
|
|
258
|
+
const round = this.#bookkeep(frame, outcome);
|
|
259
|
+
// The closure verdict rides the recorded round's C5 route — mark the task done
|
|
260
|
+
// when the route kind says the line closed (the router's single point, never a
|
|
261
|
+
// folded copy of the closure table).
|
|
262
|
+
this.#markTerminal(frame, this.#routeNext(frame));
|
|
263
|
+
// The delivered route re-judges the batch AFTER the done-marking: a closing
|
|
264
|
+
// review empties the ready batch, so the step routes `done` (an exhausted run),
|
|
265
|
+
// not a phantom next-wave of the just-closed task.
|
|
266
|
+
const route = this.#routeNext(frame);
|
|
267
|
+
return {
|
|
268
|
+
frame,
|
|
269
|
+
round,
|
|
270
|
+
route,
|
|
271
|
+
capsuleLines: this.#capsuleLines(frame, outcome, route),
|
|
272
|
+
};
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
// -------------------------------------------------------------------------
|
|
276
|
+
// frontier — the open dispatch frame
|
|
277
|
+
// -------------------------------------------------------------------------
|
|
278
|
+
|
|
279
|
+
/** Resolve the line's next open frame — null when the line is exhausted. */
|
|
280
|
+
#openFrame(): OpenFrame | null {
|
|
281
|
+
if (this.#face.audit.kind === "task-graph") return this.#openWaveFrame();
|
|
282
|
+
const target = this.#target;
|
|
283
|
+
if (target === null) return null; // a fixed-target face without its target holds
|
|
284
|
+
return this.#openLineFrame(target);
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/** The task face's next open frame — THE OPEN WAVE as ONE dispatch step (the
|
|
288
|
+
* wave-unitary model · T26): the frontier's whole ready batch is the frame's
|
|
289
|
+
* target — one brief, one child, one commit, one round, one phase train. Null
|
|
290
|
+
* when the frontier holds no open wave. */
|
|
291
|
+
#openWaveFrame(): OpenFrame | null {
|
|
292
|
+
const done = this.#state.doneTasks();
|
|
293
|
+
const ready = this.#state.frontier(done); // the open wave (the whole ready batch, ascending)
|
|
294
|
+
if (ready.length === 0) return null;
|
|
295
|
+
const key = ready.join(",");
|
|
296
|
+
const phase = this.#nextWavePhase(key);
|
|
297
|
+
if (phase === null) return null;
|
|
298
|
+
const target = { kind: "wave", tasks: ready } as const;
|
|
299
|
+
const round = this.#roundFor(phase, key);
|
|
300
|
+
return {
|
|
301
|
+
type: "wave",
|
|
302
|
+
phase,
|
|
303
|
+
round,
|
|
304
|
+
target,
|
|
305
|
+
params: this.#paramsOf({ type: "wave", phase, target, round }),
|
|
306
|
+
key,
|
|
307
|
+
};
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/** The next phase of one wave line — the SAME single derivation the wave gate reads
|
|
311
|
+
* (`Ledger#waveLinePhase` · D26: one fact, one place). The lifecycle's frame
|
|
312
|
+
* frontier and the three-verb WaveGate must agree on the open wave's phase, or a
|
|
313
|
+
* drift-reopened wave deadlocks (the gate accepts `review` while the frontier
|
|
314
|
+
* demands `fix`). Null when the line is closed (its latest round's C5 route is
|
|
315
|
+
* done / next-wave / soft-cap — the soft cap defers to the user). */
|
|
316
|
+
#nextWavePhase(key: string): DispatchPhase | null {
|
|
317
|
+
return this.#ledger.waveLinePhase(key);
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/** The branch/spec/plan line's next open frame — the fixed audit target's round
|
|
321
|
+
* sequence (review-lead → fix → re-review → closure). */
|
|
322
|
+
#openLineFrame(target: AuditTarget): OpenFrame | null {
|
|
323
|
+
const key = this.#lineKey(target);
|
|
324
|
+
const reviewLead = this.#face.product.reviewLead;
|
|
325
|
+
const phase = this.#nextLinePhase(key, target, reviewLead);
|
|
326
|
+
if (phase === null) return null;
|
|
327
|
+
const round = this.#roundFor(phase, key);
|
|
328
|
+
return {
|
|
329
|
+
type: this.#face.type,
|
|
330
|
+
phase,
|
|
331
|
+
round,
|
|
332
|
+
target,
|
|
333
|
+
params: this.#paramsOf({ type: this.#face.type, phase, target, round }),
|
|
334
|
+
key,
|
|
335
|
+
};
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
/** The next phase of a single-target line — the doc-revision gate (lifecycle-side:
|
|
339
|
+
* its reviewGate needs the target doc path) then the ledger's SINGLE rounds/routes
|
|
340
|
+
* judge (`Ledger#linePhase`, D40 — the retired lifecycle twin). A CLOSED doc line
|
|
341
|
+
* reopens through the identity verdict (T7): a drifted doc opens the review lead
|
|
342
|
+
* whatever the round/route state says (the fix-awaited route never freezes a
|
|
343
|
+
* revised doc); an unchanged doc with the pending fix derived opens the fix; the
|
|
344
|
+
* unbound / same-without-pending faces fall through to the shared rounds/routes
|
|
345
|
+
* walk (a completed-fix line reopens review through the fix round's route). */
|
|
346
|
+
#nextLinePhase(
|
|
347
|
+
key: LedgerKey,
|
|
348
|
+
target: AuditTarget,
|
|
349
|
+
reviewLead: ReviewLead,
|
|
350
|
+
): DispatchPhase | null {
|
|
351
|
+
if (target.kind === "doc") {
|
|
352
|
+
const verdict = this.#ledger.reviewGate(key, target.doc, this.#face.type);
|
|
353
|
+
if (verdict.kind === "open") return reviewLead;
|
|
354
|
+
if (verdict.kind === "same" && verdict.pending) return "fix";
|
|
355
|
+
}
|
|
356
|
+
return this.#ledger.linePhase(key, this.#face.type);
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
/** The round number one phase dispatches under: implement = the fixed family (1);
|
|
360
|
+
* the review-lead = the next increment; fix = the source review-lead round. */
|
|
361
|
+
#roundFor(phase: DispatchPhase, key: LedgerKey): number {
|
|
362
|
+
if (phase === "implement") return 1;
|
|
363
|
+
if (phase === "fix") {
|
|
364
|
+
const reviews = this.#reviewCount(key);
|
|
365
|
+
return reviews > 0 ? reviews : 1;
|
|
366
|
+
}
|
|
367
|
+
return this.#reviewCount(key) + 1;
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
/** The review-lead round count of a key (branch counts its branch-review mode,
|
|
371
|
+
* the others the review mode — the face row's single source). */
|
|
372
|
+
#reviewCount(key: LedgerKey): number {
|
|
373
|
+
return this.#ledger.roundCount(key, this.#face.product.reviewLead);
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/** The progress key of a single-target line — the line's STABLE key (find #9 ·
|
|
377
|
+
* spec §6.5/§3.7 — `"branch"` per workspace for the branch line, accumulating
|
|
378
|
+
* across re-reviews; the doc line keys by its line-type constant `"spec"`/`"plan"`
|
|
379
|
+
* — the argv path copy never resets the round: a moved argv string (absolute vs
|
|
380
|
+
* relative) must not fork the same line into two ledger rows). The task face
|
|
381
|
+
* never routes here — frames key by the wave key. */
|
|
382
|
+
#lineKey(target: AuditTarget): LedgerKey {
|
|
383
|
+
if (target.kind === "doc") return this.#face.type;
|
|
384
|
+
return "branch";
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
// -------------------------------------------------------------------------
|
|
388
|
+
// the frame → handoff params shaping
|
|
389
|
+
// -------------------------------------------------------------------------
|
|
390
|
+
|
|
391
|
+
/** The handoff params one frame fills — the type's placeholders from the target
|
|
392
|
+
* and round. The round rides the increment families (review / fix / branch-review
|
|
393
|
+
* — the family name carries it); the fixed implement family stays round-less. */
|
|
394
|
+
#paramsOf(frame: {
|
|
395
|
+
type: TargetType;
|
|
396
|
+
phase: DispatchPhase;
|
|
397
|
+
target: AuditTarget;
|
|
398
|
+
round: number;
|
|
399
|
+
}): HandoffParams {
|
|
400
|
+
switch (frame.type) {
|
|
401
|
+
case "wave": {
|
|
402
|
+
const waveTarget = frame.target as { kind: "wave"; tasks: readonly number[] };
|
|
403
|
+
const params: HandoffParams = { tasks: waveTarget.tasks.join(",") };
|
|
404
|
+
if (frame.phase !== "implement") params.round = frame.round;
|
|
405
|
+
return params;
|
|
406
|
+
}
|
|
407
|
+
case "branch":
|
|
408
|
+
return { round: frame.round };
|
|
409
|
+
case "spec":
|
|
410
|
+
case "plan":
|
|
411
|
+
return { round: frame.round };
|
|
412
|
+
}
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
// -------------------------------------------------------------------------
|
|
416
|
+
// dispatch → result → bookkeeping
|
|
417
|
+
// -------------------------------------------------------------------------
|
|
418
|
+
|
|
419
|
+
/** Bookkeeping — persist the round's handoff carrier and record the progress round.
|
|
420
|
+
* The persisted carrier is either the dispatch's materialized form (the production
|
|
421
|
+
* read-back reconstruct — outcome.carrier, full-replace at the SAME path, so the
|
|
422
|
+
* child's draft becomes the finalized carrier — the two-state single file, the engine is the single
|
|
423
|
+
* author) or the engine-built fallback from the outcome fields (hermetic / dry-run
|
|
424
|
+
* dispatchers). A BLOCKED/TIMEOUT round WITHOUT a carrier is neither persisted nor
|
|
425
|
+
* recorded — the child's draft (if any) stays untouched (no-overwrite on failure) and the
|
|
426
|
+
* frontier re-offers the same round (resume = re-run the same command); a BLOCKED
|
|
427
|
+
* round WITH a carrier (e.g. the evidence-contract override — the child's work is
|
|
428
|
+
* preserved as the BLOCKED carrier) is persisted but not counted as a completed
|
|
429
|
+
* round, so the frontier still re-dispatches it. Returns the round count on record
|
|
430
|
+
* (the task done-marking rides the step's C5 route — #markTerminal, after
|
|
431
|
+
* #routeNext). */
|
|
432
|
+
#bookkeep(frame: OpenFrame, outcome: DispatchOutcome): number {
|
|
433
|
+
const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
434
|
+
if (outcome.carrier !== undefined || !blocked) {
|
|
435
|
+
const op = this.#opOf(frame.phase);
|
|
436
|
+
// T2 — the engine-built fallback rides the FRAME's declared face (the family's
|
|
437
|
+
// `schema` selector, never the outcome's field presence): a findings-face round
|
|
438
|
+
// (review / docs-fix) builds the findings carrier — its schema-required findings
|
|
439
|
+
// key, empty on a conclusion-only round (a fix advances no new findings); a
|
|
440
|
+
// work-face round builds the findings-free work carrier — zero findings
|
|
441
|
+
// injection. The review finding-severity route reads the round carrier's
|
|
442
|
+
// findings; the conclusion rides only the work face's declared status (the
|
|
443
|
+
// findings face derives its conclusion at judgment time).
|
|
444
|
+
const face = this.#ledger.handoffFaceOf(op, frame.type);
|
|
445
|
+
const carrier: Record<string, unknown> =
|
|
446
|
+
outcome.carrier ??
|
|
447
|
+
(face === "findings"
|
|
448
|
+
? this.#ledger.buildHandoff("findings", {
|
|
449
|
+
findings: [...(outcome.findings ?? [])],
|
|
450
|
+
artifacts: outcome.artifacts,
|
|
451
|
+
})
|
|
452
|
+
: this.#ledger.buildHandoff("work", {
|
|
453
|
+
artifacts: outcome.artifacts,
|
|
454
|
+
}));
|
|
455
|
+
// The work face ALONE persists the conclusion (the child's declared status); the
|
|
456
|
+
// findings carrier holds no status — its conclusion derives at judgment time
|
|
457
|
+
// (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
|
|
458
|
+
if (face === "work" && carrier.status === undefined && outcome.status !== undefined)
|
|
459
|
+
carrier.status = outcome.status;
|
|
460
|
+
this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
|
|
461
|
+
}
|
|
462
|
+
if (!blocked) {
|
|
463
|
+
// The recorded CYCLE is the frame's own round — its identity (fix-K ⟷ review-K ·
|
|
464
|
+
// D28): a skipped cycle records its own number, never a flattened ordinal.
|
|
465
|
+
const count = this.#ledger.recordRound(frame.key, frame.phase, frame.round);
|
|
466
|
+
// The completed-review revision write-back — the doc line and the wave line
|
|
467
|
+
// each bind their OWN reviewed revision (T7 doc · T11 wave / D16 / D30): a
|
|
468
|
+
// completed review binds the CURRENT revision of the reviewed input — read at
|
|
469
|
+
// bookkeep, the clean-tree dispatch gate keeps the read-only review's input
|
|
470
|
+
// stable across the round. For a doc line that input is the target doc (the
|
|
471
|
+
// whole-content doc-revision). For a wave line it is the RENDERED BRIEF —
|
|
472
|
+
// `#recordReviewedWaveBrief` → `recordReviewedBrief(String(frame.key),
|
|
473
|
+
// #planPath)` hashes the brief the plan renders to, holding #planPath only as
|
|
474
|
+
// the plan the brief renders FROM (the render-from POINTER, not the hashed
|
|
475
|
+
// identity; the wave gate derives the plan path FROM this record, so
|
|
476
|
+
// cli.ts/preflight.ts stay untouched). The two legs do NOT share one gate —
|
|
477
|
+
// each ref kind carries its own reviewed identity. An unreadable input records
|
|
478
|
+
// nothing (present facts only); a null plan path (no plan fact) leaves a legacy
|
|
479
|
+
// wave row — null stays backward compatible.
|
|
480
|
+
if (frame.phase === "review") {
|
|
481
|
+
if (frame.target.kind === "doc") this.#recordReviewedDocRevision(frame);
|
|
482
|
+
else if (frame.target.kind === "wave") this.#recordReviewedWaveBrief(frame);
|
|
483
|
+
}
|
|
484
|
+
return count;
|
|
485
|
+
}
|
|
486
|
+
return this.#ledger.roundCount(frame.key, frame.phase);
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
/** The reviewed-revision write-back — bind the reviewed input's revision to the
|
|
490
|
+
* line record (the T7 doc + D30 wave identity gates' reopen-compare basis). The
|
|
491
|
+
* doc face binds its target doc's whole-content revision; the wave face binds its
|
|
492
|
+
* RENDERED BRIEF's revision (D30 — the wave's true judgment input is the brief,
|
|
493
|
+
* never the whole plan: transcript edits outside the wave's task sections must not
|
|
494
|
+
* void a reviewed wave). An unreadable input records nothing — the line keeps the
|
|
495
|
+
* legacy closed face (only present facts land, never an invented identity). */
|
|
496
|
+
#recordReviewedDocRevision(frame: OpenFrame): void {
|
|
497
|
+
if (frame.target.kind !== "doc") return;
|
|
498
|
+
try {
|
|
499
|
+
const content = readFileSync(frame.target.doc, "utf8");
|
|
500
|
+
this.#ledger.recordReviewedRevision(
|
|
501
|
+
frame.key,
|
|
502
|
+
this.#ledger.refs().docRevision(frame.target.doc, content),
|
|
503
|
+
);
|
|
504
|
+
} catch {
|
|
505
|
+
// unreadable input — no reviewed identity recorded (present facts only)
|
|
506
|
+
}
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
/** The wave line's reviewed-brief write-back (D30) — bind the RENDERED brief's
|
|
510
|
+
* revision for the wave's tasks to the row (the D30 wave-gate reopen basis). Null
|
|
511
|
+
* plan path / underivable brief records nothing (present facts only). */
|
|
512
|
+
#recordReviewedWaveBrief(frame: OpenFrame): void {
|
|
513
|
+
if (frame.target.kind !== "wave" || this.#planPath === null) return;
|
|
514
|
+
this.#ledger.recordReviewedBrief(String(frame.key), this.#planPath);
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
/** Mark the wave done when the concluding route says its line closed — the C5
|
|
518
|
+
* verdict is the single closure gate (terminal ⇔ route.kind ∈ {done, next-wave},
|
|
519
|
+
* the v1.20 closure side): a clean review or a blocker-free fix closes the wave
|
|
520
|
+
* (every member task), while a re-review / soft-cap / a null route (BLOCKED,
|
|
521
|
+
* TIMEOUT, a missing base) holds it. Marking the closed wave lets the next
|
|
522
|
+
* frontier pass exclude it. The task-less faces never mark — for them the route
|
|
523
|
+
* IS the gate. */
|
|
524
|
+
#markTerminal(frame: OpenFrame, route: Route | null): void {
|
|
525
|
+
if (frame.type !== "wave") return;
|
|
526
|
+
if (!Ledger.routeClosed(route)) return;
|
|
527
|
+
const waveTarget = frame.target as { kind: "wave"; tasks: readonly number[] };
|
|
528
|
+
for (const id of waveTarget.tasks) this.#state.markDone(id);
|
|
529
|
+
}
|
|
530
|
+
|
|
531
|
+
/** The handoff-family op of a phase — branch-review rides the review family. */
|
|
532
|
+
#opOf(phase: DispatchPhase): OpType {
|
|
533
|
+
return phase === "branch-review" ? "review" : phase;
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
// -------------------------------------------------------------------------
|
|
537
|
+
// next routing + the capsule interaction
|
|
538
|
+
// -------------------------------------------------------------------------
|
|
539
|
+
|
|
540
|
+
/** The next-hop route — the recorded round read back through the ledger (the fix
|
|
541
|
+
* round carries the SOURCE review's findings, C5-1) and judged by the router.
|
|
542
|
+
* Null when the round is unreadable (no invented next hop from absent facts). */
|
|
543
|
+
#routeNext(frame: OpenFrame): Route | null {
|
|
544
|
+
const op = this.#opOf(frame.phase);
|
|
545
|
+
const carried = this.#ledger.round(op, frame.type, frame.params, frame.round);
|
|
546
|
+
if (carried === null) return null;
|
|
547
|
+
return this.#router.next(this.#routeState(), carried);
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
/** The execution state the router judges next against — the real run state for
|
|
551
|
+
* the batch faces (task), the empty single-target state for the rest (their
|
|
552
|
+
* nextSemantics.batch is false — a review-approved closes the line, never a batch
|
|
553
|
+
* continuation). */
|
|
554
|
+
#routeState(): ExecutionState {
|
|
555
|
+
return this.#face.nextSemantics.batch ? this.#state : EMPTY_RUN_STATE;
|
|
556
|
+
}
|
|
557
|
+
|
|
558
|
+
/** The capsule lines of one step — empty unless a capsule is attached (the non-hard
|
|
559
|
+
* interaction point). The blocker cell carries the round's blocker count; the
|
|
560
|
+
* dispatch-ready `next:` literal rides the frame's own RouteTarget identity
|
|
561
|
+
* (type + id — the v1.25 combination point: frame.type + params.tasks + route
|
|
562
|
+
* are all present here). */
|
|
563
|
+
#capsuleLines(
|
|
564
|
+
frame: OpenFrame,
|
|
565
|
+
outcome: DispatchOutcome,
|
|
566
|
+
route: Route | null,
|
|
567
|
+
): readonly string[] {
|
|
568
|
+
if (this.#capsule === null) return [];
|
|
569
|
+
const op = this.#opOf(frame.phase);
|
|
570
|
+
const blockers = (outcome.findings ?? []).filter(
|
|
571
|
+
(finding) => finding.severity === "blocker",
|
|
572
|
+
).length;
|
|
573
|
+
const handoff = this.#ledger.handoffPath(op, frame.type, frame.params);
|
|
574
|
+
return this.#capsule.emit(
|
|
575
|
+
outcome.status,
|
|
576
|
+
String(blockers),
|
|
577
|
+
handoff,
|
|
578
|
+
route,
|
|
579
|
+
this.#routeTarget(frame),
|
|
580
|
+
);
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/** The frame's RouteTarget — the dispatch-ready literal's target identity (the
|
|
584
|
+
* frame's own facts: the wave task key · the branch line key · the doc path).
|
|
585
|
+
* `type` rides the wave target type; `id` the frame's parameters; `plan` the
|
|
586
|
+
* workspace plan path (the implement literal's required `--plan`). */
|
|
587
|
+
#routeTarget(frame: OpenFrame): RouteTarget | null {
|
|
588
|
+
switch (frame.type) {
|
|
589
|
+
case "wave":
|
|
590
|
+
return { type: "wave", id: frame.params.tasks ?? "", plan: this.#planPath ?? undefined };
|
|
591
|
+
case "branch":
|
|
592
|
+
// The branch line's stable id — the workspace plan path carries the
|
|
593
|
+
// fix/re-review literals' `--plan` (a plan-less `#sceneOf` would resolve
|
|
594
|
+
// to the empty directory · the workspace double identity · zero
|
|
595
|
+
// orchestrator fallback).
|
|
596
|
+
return {
|
|
597
|
+
type: "branch",
|
|
598
|
+
id: "branch",
|
|
599
|
+
plan: this.#planPath ?? undefined,
|
|
600
|
+
};
|
|
601
|
+
case "spec":
|
|
602
|
+
case "plan":
|
|
603
|
+
return { type: frame.type, id: (frame.target as { kind: "doc"; doc: string }).doc };
|
|
604
|
+
}
|
|
605
|
+
}
|
|
606
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// packages/cdd-engine/src-next/session/state.ts
|
|
2
|
+
// T6 — the execution-state query surface (design spec §3.1): the frontier dynamic
|
|
3
|
+
// face + the ExecutionState query surface. Both are contracts the run carrier
|
|
4
|
+
// implements — TaskGraph today, the round ledger's ProgressLedger later — and the
|
|
5
|
+
// query methods (doneTasks() / readyBatch()) are METHODS on the carrier, never
|
|
6
|
+
// standalone state classes. Module-level exports are interfaces only — zero
|
|
7
|
+
// behavior-carrying bare functions (the plan's zero-bare-function discipline).
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* The frontier contract — the pure dynamic readiness face of a task run: given
|
|
11
|
+
* the set of completed task ids, which tasks are ready to execute next.
|
|
12
|
+
*/
|
|
13
|
+
export interface Frontier {
|
|
14
|
+
/** The ready task ids — every not-yet-done task whose declared dependencies are
|
|
15
|
+
* all done, in ascending id order. */
|
|
16
|
+
frontier(done: ReadonlySet<number>): readonly number[];
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* The execution-state query surface — a carrier's projection of the running
|
|
21
|
+
* session. Implemented as methods on TaskGraph (this task) / ProgressLedger (the
|
|
22
|
+
* round ledger), never a separate state class.
|
|
23
|
+
*/
|
|
24
|
+
export interface ExecutionState {
|
|
25
|
+
/** The completed task ids — a snapshot copy, never a live handle into the run state. */
|
|
26
|
+
doneTasks(): Set<number>;
|
|
27
|
+
/** The current ready batch — the not-yet-done tasks whose dependencies are all
|
|
28
|
+
* done, in ascending id order (the frontier over the carrier's done set). */
|
|
29
|
+
readyBatch(): number[];
|
|
30
|
+
}
|