@oscaner-skills/cdd-engine 4.10.0 → 4.12.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/dist/contract/completion-criterion.js +19 -28
- package/dist/contract/doc.js +24 -0
- package/dist/contract/invariants.js +11 -8
- package/dist/contract/judge.js +45 -4
- package/dist/contract/project.js +12 -1
- package/dist/contract/task-block-grammar.js +3 -1
- package/dist/face/board-view.js +327 -138
- package/dist/face/cli.js +172 -63
- package/dist/face/gate.js +6 -3
- package/dist/face/lifecycle.js +191 -128
- package/dist/face/words.js +51 -0
- package/dist/infra/plan-source.js +359 -0
- package/dist/infra/runtime.js +20 -52
- package/dist/render/brief.js +34 -32
- package/dist/render/templates.js +63 -29
- package/dist/session/carrier-integrity.js +0 -8
- package/dist/session/dispatch-authority.js +1 -1
- package/dist/session/handoff-schema.js +135 -73
- package/dist/session/ledger.js +269 -104
- package/dist/session/pipeline.js +2 -2
- package/dist/session/preflight.js +65 -34
- package/dist/session/round-naming.js +138 -89
- package/dist/session/run.js +73 -74
- package/package.json +1 -1
package/dist/session/run.js
CHANGED
|
@@ -18,13 +18,13 @@
|
|
|
18
18
|
// Module-level exports are types / the class / one empty-state data const — zero
|
|
19
19
|
// behavior-carrying bare functions (the plan's zero-bare-function discipline).
|
|
20
20
|
import { readFileSync } from "node:fs";
|
|
21
|
-
import { PlanDocType } from "../contract/doc.js";
|
|
22
21
|
import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
|
|
23
22
|
import { CarrierSeal } from "../infra/carrier-seal.js";
|
|
24
23
|
import { Ledger, RoundViolation, } from "./ledger.js";
|
|
25
24
|
import { NextStepRouter } from "./next.js";
|
|
26
25
|
import { PipelineFrontier } from "./pipeline.js";
|
|
27
26
|
import { ReviewedIdentity } from "./reviewed-identity.js";
|
|
27
|
+
import { RoundNaming } from "./round-naming.js";
|
|
28
28
|
/** The empty run state — a target line with no task frontier (branch/spec/plan):
|
|
29
29
|
* the frontier query faces are always empty (a single-target line never continues
|
|
30
30
|
* a batch) and markDone is a no-op. */
|
|
@@ -150,21 +150,20 @@ export class Lifecycle {
|
|
|
150
150
|
/** The dispatch-entry pre-flight gate — null = unguarded (the seam-less callers
|
|
151
151
|
* keep their existing behavior). */
|
|
152
152
|
#preflight;
|
|
153
|
-
/** The
|
|
154
|
-
* arg
|
|
155
|
-
*
|
|
156
|
-
* (
|
|
157
|
-
*
|
|
158
|
-
|
|
153
|
+
/** The plan read this lifecycle drives (the `next:` implement literal's required
|
|
154
|
+
* `--plan` arg, the branch line's identity document, the brief hash's and the
|
|
155
|
+
* plan snapshot's source, and the pipeline frontier's plan cells). The frontier
|
|
156
|
+
* path is `stationPath()` — the document that read out (its front matter
|
|
157
|
+
* parsed), so a `syntax` plan keeps its face while an `io` failure carries none.
|
|
158
|
+
* REQUIRED: every command preamble holds a value (`undeclared` is a value), so no
|
|
159
|
+
* harness can silently drop the brief hash and the plan snapshot by omission. */
|
|
160
|
+
#plan;
|
|
159
161
|
/** The pipeline frontier's declared identity — the spec line's DECLARED word (the
|
|
160
162
|
* `doc-type:` head key) and its document path. A node with no spec document
|
|
161
163
|
* (`#specPath === null`) keeps this line's own hop assembly: the frontier's rules
|
|
162
164
|
* anchor on an absent identity face, which would print a passed phase's transition. */
|
|
163
165
|
#specType;
|
|
164
166
|
#specPath;
|
|
165
|
-
/** The plan's task graph — the pipeline frontier's guarded plan read, injected by
|
|
166
|
-
* the composition root (the session plane reads no file). */
|
|
167
|
-
#planGraph;
|
|
168
167
|
/** The pipeline frontier — the ONE hop assembly this lifecycle's capsule renders
|
|
169
168
|
* (the same object the board renders). */
|
|
170
169
|
#frontier;
|
|
@@ -182,10 +181,9 @@ export class Lifecycle {
|
|
|
182
181
|
this.#target = opts.target ?? null;
|
|
183
182
|
this.#capsule = opts.capsule ?? null;
|
|
184
183
|
this.#preflight = opts.preflight ?? null;
|
|
185
|
-
this.#
|
|
184
|
+
this.#plan = opts.plan;
|
|
186
185
|
this.#specType = opts.specType ?? null;
|
|
187
186
|
this.#specPath = opts.specPath ?? null;
|
|
188
|
-
this.#planGraph = opts.planGraph ?? null;
|
|
189
187
|
this.#frontier = new PipelineFrontier(this.#ledger);
|
|
190
188
|
this.#docClassOf = opts.docClassOf ?? Lifecycle.#docClassByType;
|
|
191
189
|
}
|
|
@@ -301,7 +299,7 @@ export class Lifecycle {
|
|
|
301
299
|
phase,
|
|
302
300
|
round,
|
|
303
301
|
target,
|
|
304
|
-
params: this.#paramsOf({ type: "wave", phase, target, round }),
|
|
302
|
+
params: this.#paramsOf({ type: "wave", phase, target, round, attempt }),
|
|
305
303
|
key,
|
|
306
304
|
attempt,
|
|
307
305
|
};
|
|
@@ -338,7 +336,7 @@ export class Lifecycle {
|
|
|
338
336
|
phase,
|
|
339
337
|
round,
|
|
340
338
|
target,
|
|
341
|
-
params: this.#paramsOf({ type: this.#face.type, phase, target, round }),
|
|
339
|
+
params: this.#paramsOf({ type: this.#face.type, phase, target, round, attempt }),
|
|
342
340
|
key,
|
|
343
341
|
attempt,
|
|
344
342
|
};
|
|
@@ -365,8 +363,9 @@ export class Lifecycle {
|
|
|
365
363
|
// after the terminal branch review reopens the branch-review lead, an unchanged
|
|
366
364
|
// plan keeps the line closed. Same gate, same judgment — only the doc path is
|
|
367
365
|
// the line's plan (the audit target itself carries no doc).
|
|
368
|
-
|
|
369
|
-
|
|
366
|
+
const planPath = this.#plan.stationPath();
|
|
367
|
+
if (target.kind === "branch" && planPath !== null) {
|
|
368
|
+
const verdict = this.#ledger.reviewGate(key, planPath, "branch");
|
|
370
369
|
if (this.#ledger.docReopens(key, "branch", verdict))
|
|
371
370
|
return reviewLead;
|
|
372
371
|
if (verdict.kind === "same" && verdict.pending)
|
|
@@ -407,25 +406,22 @@ export class Lifecycle {
|
|
|
407
406
|
// -------------------------------------------------------------------------
|
|
408
407
|
// the frame → handoff params shaping
|
|
409
408
|
// -------------------------------------------------------------------------
|
|
410
|
-
/** The handoff params one frame fills — the type's placeholders from the target
|
|
411
|
-
* and
|
|
412
|
-
*
|
|
409
|
+
/** The handoff params one frame fills — the type's placeholders from the target,
|
|
410
|
+
* the round and the attempt. EVERY family carries its cycle now (P34 T1: the
|
|
411
|
+
* implement family included, so its draft and final are two names), and every
|
|
412
|
+
* family carries the attempt the naming face renders as `-a{n}`. */
|
|
413
413
|
#paramsOf(frame) {
|
|
414
414
|
switch (frame.type) {
|
|
415
415
|
case "wave": {
|
|
416
416
|
const waveTarget = frame.target;
|
|
417
|
-
|
|
418
|
-
if (frame.phase !== "implement")
|
|
419
|
-
params.round = frame.round;
|
|
420
|
-
return params;
|
|
417
|
+
return { tasks: waveTarget.tasks.join(","), round: frame.round, attempt: frame.attempt };
|
|
421
418
|
}
|
|
422
419
|
case "branch":
|
|
423
|
-
return { round: frame.round };
|
|
424
420
|
case "phase-spec":
|
|
425
421
|
case "overall":
|
|
426
422
|
case "plan":
|
|
427
423
|
case "single-spec":
|
|
428
|
-
return { round: frame.round };
|
|
424
|
+
return { round: frame.round, attempt: frame.attempt };
|
|
429
425
|
}
|
|
430
426
|
}
|
|
431
427
|
// -------------------------------------------------------------------------
|
|
@@ -437,19 +433,17 @@ export class Lifecycle {
|
|
|
437
433
|
* outcome carrying no verdict) — the engine-built fallback from the outcome fields.
|
|
438
434
|
* Either way it lands as the FINAL carrier beside the child's draft, never over it
|
|
439
435
|
* (P31 §2.3: the draft keeps the child's bytes, the final carries the engine's
|
|
440
|
-
* materialization, and the
|
|
441
|
-
*
|
|
442
|
-
*
|
|
443
|
-
* see the child's own draft, never an
|
|
444
|
-
* WITHOUT a carrier leaves the child's
|
|
445
|
-
* is STILL recorded — every dispatched
|
|
446
|
-
* verdict, never a membership test. Returns the in-register round count (the task
|
|
436
|
+
* materialization, and the ledger DERIVES the record's path from its own identity —
|
|
437
|
+
* the record remembers the digest, never a path). A production round that wrote no
|
|
438
|
+
* carrier leaves no file at either name: the completion criterion owns the absence
|
|
439
|
+
* (§3.3), and a re-dispatch's draft read must see the child's own draft, never an
|
|
440
|
+
* engine synthesis of it. A failure round WITHOUT a carrier leaves the child's
|
|
441
|
+
* draft untouched (no-overwrite on failure) but is STILL recorded — every dispatched
|
|
442
|
+
* round lands; "completed" is the record's verdict, never a membership test. Returns the in-register round count (the task
|
|
447
443
|
* done-marking rides the step's C5 route — #markTerminal, after #routeNext). */
|
|
448
444
|
#bookkeep(frame, outcome) {
|
|
449
445
|
const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
450
|
-
let carrierPath = null;
|
|
451
446
|
let carrierDigest = null;
|
|
452
|
-
let draftPath = null;
|
|
453
447
|
if (outcome.carrier !== undefined || (outcome.verdict === undefined && !blocked)) {
|
|
454
448
|
const op = this.#opOf(frame.phase);
|
|
455
449
|
// T2 — the engine-built fallback rides the FRAME's op-derived plane (never the
|
|
@@ -472,13 +466,12 @@ export class Lifecycle {
|
|
|
472
466
|
// (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
|
|
473
467
|
if (plane === "work" && carrier.status === undefined && outcome.status !== undefined)
|
|
474
468
|
carrier.status = outcome.status;
|
|
475
|
-
// P31 §2.2/§2.3 — the persist
|
|
476
|
-
//
|
|
477
|
-
//
|
|
469
|
+
// P31 §2.2/§2.3 — the persist seals the round's two names and hands back the
|
|
470
|
+
// payload digest, so the record can replay the comparison on every later read of
|
|
471
|
+
// this carrier. The PATHS stay out of the record: the ledger derives them from
|
|
472
|
+
// the record's own identity.
|
|
478
473
|
const persisted = this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
|
|
479
|
-
carrierPath = persisted.path;
|
|
480
474
|
carrierDigest = persisted.digest;
|
|
481
|
-
draftPath = persisted.draftPath;
|
|
482
475
|
}
|
|
483
476
|
else {
|
|
484
477
|
// P31 T5 §2.4 — a round that books NO carrier still owns its two names: the
|
|
@@ -514,9 +507,9 @@ export class Lifecycle {
|
|
|
514
507
|
targetAction: !blocked,
|
|
515
508
|
},
|
|
516
509
|
violations,
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
510
|
+
// A round that persisted no carrier records no digest column at all — the
|
|
511
|
+
// absence is the fact, never a null placeholder.
|
|
512
|
+
...(carrierDigest === null ? {} : { carrierDigest }),
|
|
520
513
|
}, frame.type);
|
|
521
514
|
// The completed-round revision write-back is gated on the round's VERDICT (a
|
|
522
515
|
// hard-failed round must not bind the current revision — that would silently
|
|
@@ -582,23 +575,29 @@ export class Lifecycle {
|
|
|
582
575
|
* review or fix round. Null plan path / underivable brief records nothing (present
|
|
583
576
|
* facts only). */
|
|
584
577
|
#recordReviewedWaveBrief(frame) {
|
|
585
|
-
|
|
578
|
+
const planPath = this.#plan.stationPath();
|
|
579
|
+
if (frame.target.kind !== "wave" || planPath === null)
|
|
586
580
|
return;
|
|
587
|
-
this.#ledger.recordReviewedBrief(String(frame.key),
|
|
581
|
+
this.#ledger.recordReviewedBrief(String(frame.key), planPath);
|
|
588
582
|
}
|
|
589
583
|
/** The branch line's reviewed identity (P21 §4.1) — its PLAN document's
|
|
590
584
|
* `doc-revision`, the same ref kind the doc lines bind (no new ref kind, no commit
|
|
591
585
|
* sha). A later plan revision reopens the line; an unchanged plan keeps it closed.
|
|
592
|
-
*
|
|
586
|
+
* The document is re-read at round completion THROUGH the ledger's plan seam (the
|
|
587
|
+
* ONE plan read point), so a fix that edited the plan binds the edited bytes and
|
|
588
|
+
* the write-back never turns a repoRoot-relative path into a cwd-relative syscall.
|
|
589
|
+
* A null plan path records nothing (present facts only). */
|
|
593
590
|
#recordReviewedBranchRevision(frame) {
|
|
594
|
-
|
|
591
|
+
const planPath = this.#plan.stationPath();
|
|
592
|
+
if (planPath === null)
|
|
595
593
|
return;
|
|
596
|
-
this.#
|
|
594
|
+
this.#ledger.recordReviewedPlanRevision(frame.key, planPath, frame.type);
|
|
597
595
|
}
|
|
598
596
|
/** The doc-revision write-back body — read the round's document and bind its
|
|
599
|
-
* current revision to the line row (the ONE read + hash + record path the doc
|
|
600
|
-
* branch
|
|
601
|
-
* nothing — the line keeps the legacy closed face (present facts
|
|
597
|
+
* current revision to the line row (the ONE read + hash + record path the doc
|
|
598
|
+
* leg owns; the branch leg binds the plan read it already judged). An unreadable
|
|
599
|
+
* input records nothing — the line keeps the legacy closed face (present facts
|
|
600
|
+
* only). */
|
|
602
601
|
#recordDocRevisionOf(key, path, identity) {
|
|
603
602
|
try {
|
|
604
603
|
const content = readFileSync(path, "utf8");
|
|
@@ -630,34 +629,30 @@ export class Lifecycle {
|
|
|
630
629
|
this.#recordPlanSnapshot(frame);
|
|
631
630
|
}
|
|
632
631
|
/** Record the closing wave's plan-task snapshot — the plan's CURRENT task-id set
|
|
633
|
-
* read from the plan
|
|
634
|
-
*
|
|
635
|
-
* records nothing: the snapshot is a present fact only, never a
|
|
636
|
-
* (an absent snapshot reads conservatively as "stall" in the wave
|
|
632
|
+
* read from the SAME plan read the brief hashes (the injected `PlanRead`), so the
|
|
633
|
+
* snapshot and the reviewed basis can never describe two different documents. A
|
|
634
|
+
* non-ready plan records nothing: the snapshot is a present fact only, never a
|
|
635
|
+
* fabricated `[]` (an absent snapshot reads conservatively as "stall" in the wave
|
|
636
|
+
* gate). */
|
|
637
637
|
#recordPlanSnapshot(frame) {
|
|
638
|
-
|
|
638
|
+
const doc = this.#plan.doc();
|
|
639
|
+
if (doc === null)
|
|
639
640
|
return;
|
|
640
|
-
|
|
641
|
-
const lines = readFileSync(this.#planPath, "utf8").split("\n");
|
|
642
|
-
const parsed = new PlanDocType("plan").parse(lines);
|
|
643
|
-
this.#ledger.recordPlanTasks(String(frame.key), parsed.taskBlocks.map((block) => block.id));
|
|
644
|
-
}
|
|
645
|
-
catch {
|
|
646
|
-
// unreadable plan — skip the snapshot (present facts only)
|
|
647
|
-
}
|
|
641
|
+
this.#ledger.recordPlanTasks(String(frame.key), doc.taskBlocks.map((block) => block.id));
|
|
648
642
|
}
|
|
649
643
|
/** The handoff-family op of a phase — branch-review rides the review family. */
|
|
650
644
|
#opOf(phase) {
|
|
651
645
|
return phase === "branch-review" ? "review" : phase;
|
|
652
646
|
}
|
|
653
647
|
/** P31 §2.4 — seal one round's OWN carrier names (its draft and its final). The
|
|
654
|
-
* derivation is the same pair the lifecycle's preflight opens
|
|
655
|
-
* (
|
|
648
|
+
* derivation is the same pair the lifecycle's preflight opens, off the frame's own
|
|
649
|
+
* identity (cycle + attempt): two rounds of the same line never close each other's
|
|
650
|
+
* window. */
|
|
656
651
|
#sealRoundCarriers(frame) {
|
|
657
652
|
const op = this.#opOf(frame.phase);
|
|
658
|
-
const
|
|
659
|
-
CarrierSeal.seal(this.#ledger.
|
|
660
|
-
CarrierSeal.seal(this.#ledger.naming().
|
|
653
|
+
const artifact = RoundNaming.artifactOf(op, frame.type, frame.params);
|
|
654
|
+
CarrierSeal.seal(this.#ledger.naming().renderPath(artifact, "draft"));
|
|
655
|
+
CarrierSeal.seal(this.#ledger.naming().renderPath(artifact, "final"));
|
|
661
656
|
}
|
|
662
657
|
// -------------------------------------------------------------------------
|
|
663
658
|
// next routing + the capsule interaction
|
|
@@ -711,7 +706,7 @@ export class Lifecycle {
|
|
|
711
706
|
if (frame.target.kind === "plan" || frame.target.kind === "spec")
|
|
712
707
|
return frame.target.doc;
|
|
713
708
|
if (frame.target.kind === "branch")
|
|
714
|
-
return this.#
|
|
709
|
+
return this.#plan.stationPath();
|
|
715
710
|
return null;
|
|
716
711
|
}
|
|
717
712
|
/** The round's rendered hop — the PIPELINE frontier's ONE assembly when the node
|
|
@@ -731,8 +726,8 @@ export class Lifecycle {
|
|
|
731
726
|
return {
|
|
732
727
|
specType: this.#specType,
|
|
733
728
|
specPath: this.#specPath,
|
|
734
|
-
planPath: this.#
|
|
735
|
-
|
|
729
|
+
planPath: this.#plan.stationPath(),
|
|
730
|
+
plan: this.#plan,
|
|
736
731
|
};
|
|
737
732
|
}
|
|
738
733
|
/** Whether the branch line has a dispatchable open round — the wave closure's
|
|
@@ -740,7 +735,7 @@ export class Lifecycle {
|
|
|
740
735
|
* shared hop assembly's sixth cell). The lifecycle now holds no copy of the gate /
|
|
741
736
|
* route combination. */
|
|
742
737
|
#branchLineOpen() {
|
|
743
|
-
return this.#frontier.branchLineOpen(this.#
|
|
738
|
+
return this.#frontier.branchLineOpen(this.#plan.stationPath());
|
|
744
739
|
}
|
|
745
740
|
/** The capsule lines of one step — empty unless a capsule is attached (the non-hard
|
|
746
741
|
* interaction point). A success round carries the handoff carrier path; a failure
|
|
@@ -775,7 +770,11 @@ export class Lifecycle {
|
|
|
775
770
|
#routeTarget(frame) {
|
|
776
771
|
switch (frame.type) {
|
|
777
772
|
case "wave":
|
|
778
|
-
return {
|
|
773
|
+
return {
|
|
774
|
+
type: "wave",
|
|
775
|
+
id: frame.params.tasks ?? "",
|
|
776
|
+
plan: this.#plan.stationPath() ?? undefined,
|
|
777
|
+
};
|
|
779
778
|
case "branch":
|
|
780
779
|
// The branch line's stable id — the workspace plan path carries the
|
|
781
780
|
// fix/re-review literals' `--plan` (a plan-less `#sceneOf` would resolve
|
|
@@ -784,7 +783,7 @@ export class Lifecycle {
|
|
|
784
783
|
return {
|
|
785
784
|
type: "branch",
|
|
786
785
|
id: "branch",
|
|
787
|
-
plan: this.#
|
|
786
|
+
plan: this.#plan.stationPath() ?? undefined,
|
|
788
787
|
};
|
|
789
788
|
case "phase-spec":
|
|
790
789
|
case "overall":
|