@oscaner-skills/cdd-engine 4.7.0 → 4.9.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 +223 -72
- package/dist/contract/declare.js +4 -1
- package/dist/contract/invariants.js +120 -19
- package/dist/contract/rules.js +25 -5
- package/dist/contract/task-blocks.js +46 -0
- package/dist/face/board-view.js +6 -6
- package/dist/face/cli.js +102 -7
- package/dist/face/declare.js +5 -9
- package/dist/face/lifecycle.js +413 -18
- package/dist/face/preview.js +1 -1
- package/dist/face/words.js +4 -4
- package/dist/infra/carrier-seal.js +110 -0
- package/dist/infra/git.js +26 -0
- package/dist/infra/workspace.js +20 -3
- package/dist/render/templates.js +19 -4
- package/dist/session/carrier-integrity.js +128 -0
- package/dist/session/carrier-rulings.js +167 -0
- package/dist/session/dispatch-authority.js +58 -10
- package/dist/session/handoff-schema.js +8 -1
- package/dist/session/inflight.js +44 -18
- package/dist/session/ledger.js +159 -15
- package/dist/session/next.js +10 -9
- package/dist/session/preflight.js +5 -5
- package/dist/session/round-naming.js +44 -4
- package/dist/session/run.js +65 -12
- package/package.json +1 -1
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
// packages/cdd-engine/src-next/session/round-naming.ts
|
|
2
2
|
// P11 T4 — the round-naming single source: the frame → artifact-name derivations
|
|
3
3
|
// (report · evidence · brief) the lifecycle's read-back and the dry-run preview
|
|
4
|
-
// share, plus the frame → family-op mapping those names key on. The handoff carrier
|
|
5
|
-
// name is NOT derived here — it stays with the Ledger's HANDOFF_FAMILIES table
|
|
6
|
-
// naming table is the single truth, never a second list)
|
|
4
|
+
// share, plus the frame → family-op mapping those names key on. The handoff carrier's
|
|
5
|
+
// DRAFT name is NOT derived here — it stays with the Ledger's HANDOFF_FAMILIES table
|
|
6
|
+
// (the naming table is the single truth, never a second list); the FINAL name (P31
|
|
7
|
+
// §2.3) is that name with its suffix swapped, so the rule runs on the filled name.
|
|
7
8
|
//
|
|
8
9
|
// Module-level exports are the class — zero behavior-carrying bare functions.
|
|
9
|
-
import { TargetFaceTable } from "./faces.js";
|
|
10
|
+
import { TargetFaceTable, targetFaces } from "./faces.js";
|
|
10
11
|
/**
|
|
11
12
|
* RoundNaming — the one home of a round's prescribed artifact names. A frame's
|
|
12
13
|
* report / evidence / brief names derive here, so every consumer (the lifecycle's
|
|
@@ -19,6 +20,45 @@ export class RoundNaming {
|
|
|
19
20
|
constructor(workspace) {
|
|
20
21
|
this.#workspace = workspace;
|
|
21
22
|
}
|
|
23
|
+
/** The two carrier-name shapes this engine MINTS — the draft family spelling
|
|
24
|
+
* (`{line}-{op}[-{round}].json`) and its final twin (`…[-{round}].c{N}.json`). The
|
|
25
|
+
* line words come from the ONE target-face table (the wave line's spelling is the
|
|
26
|
+
* `tasks-` spine, never the `wave` word itself) and the ops from the ONE op
|
|
27
|
+
* vocabulary, so neither set is re-spelled here. */
|
|
28
|
+
static #CARRIER = RoundNaming.#carrierPattern();
|
|
29
|
+
/** The carrier-name predicate's compiled pattern — `tasks-{tasks}` is the one
|
|
30
|
+
* wave-only line (implement exists there alone), the other line words take the
|
|
31
|
+
* round-bearing ops. */
|
|
32
|
+
static #carrierPattern() {
|
|
33
|
+
const lines = Object.keys(targetFaces).filter((word) => word !== "wave");
|
|
34
|
+
return new RegExp(`^(?:tasks-.+-(?:implement|review|fix)(?:-\\d+)?|(?:${lines.join("|")})-(?:review|fix)(?:-\\d+)?)(?:\\.c\\d+)?\\.json$`);
|
|
35
|
+
}
|
|
36
|
+
/** The carrier's FINAL name of one round — the draft family name with its `.json`
|
|
37
|
+
* suffix swapped for `.c{round}.json` (P31 §2.3: the finalized carrier never
|
|
38
|
+
* overwrites the child's draft, so the two names share the stem and differ in the
|
|
39
|
+
* suffix). The draft spelling stays the Ledger's family table (`handoffName` — the
|
|
40
|
+
* naming truth); this rule runs on the name that table filled, so the two spellings
|
|
41
|
+
* cannot drift. A round-less family has no cycle to key on: the family name comes
|
|
42
|
+
* back unchanged, never a `.c.json` malformed suffix. */
|
|
43
|
+
finalName(draftName, round = undefined) {
|
|
44
|
+
if (round === undefined)
|
|
45
|
+
return draftName;
|
|
46
|
+
return `${draftName.replace(/\.json$/, "")}.c${round}.json`;
|
|
47
|
+
}
|
|
48
|
+
/** The final carrier's on-disk path — `finalName` resolved against the workspace
|
|
49
|
+
* (the name is the input, so an absolute path is never re-joined). */
|
|
50
|
+
finalPath(draftName, round = undefined) {
|
|
51
|
+
return this.#workspace.resolve(this.finalName(draftName, round));
|
|
52
|
+
}
|
|
53
|
+
/** Whether a workspace file name is one of the two carrier shapes this engine mints.
|
|
54
|
+
* Every neighbouring artifact — `progress.json` · `base.json` · the test-evidence
|
|
55
|
+
* sibling · a carrier's `.rulings.json` sidecar · a report · a crash record — is NOT
|
|
56
|
+
* a carrier, so the sweep that seals carriers can never touch them. Static: the
|
|
57
|
+
* judgment reads a NAME and nothing else, so the seal sweep (`CarrierSeal`) applies
|
|
58
|
+
* the same predicate without holding a workspace. */
|
|
59
|
+
static isCarrierName(name) {
|
|
60
|
+
return RoundNaming.#CARRIER.test(name);
|
|
61
|
+
}
|
|
22
62
|
/** The handoff-family op of a frame — branch-review rides the review family. The
|
|
23
63
|
* artifact stems embed this op, so the mapping is a naming fact owned here (the
|
|
24
64
|
* lifecycle's op read delegates, never a second copy of the rule). */
|
package/dist/session/run.js
CHANGED
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
import { readFileSync } from "node:fs";
|
|
21
21
|
import { PlanDocType } from "../contract/doc.js";
|
|
22
22
|
import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
|
|
23
|
-
import {
|
|
23
|
+
import { CarrierSeal } from "../infra/carrier-seal.js";
|
|
24
|
+
import { Ledger, RoundViolation, } from "./ledger.js";
|
|
24
25
|
import { NextStepRouter } from "./next.js";
|
|
25
26
|
import { PipelineFrontier } from "./pipeline.js";
|
|
26
27
|
import { ReviewedIdentity } from "./reviewed-identity.js";
|
|
@@ -33,6 +34,11 @@ export const EMPTY_RUN_STATE = {
|
|
|
33
34
|
frontier: () => [],
|
|
34
35
|
markDone: () => undefined,
|
|
35
36
|
};
|
|
37
|
+
/** The P31 §2.7 write-back observation — the round could not tell whether it touched
|
|
38
|
+
* the reviewed document (no dispatch baseline, or git unreadable). The bind keeps
|
|
39
|
+
* today's behaviour and this entry records the blindness; it is SOFT, so it never
|
|
40
|
+
* flips the verdict or blocks the next dispatch. */
|
|
41
|
+
const WRITE_BACK_UNMEASURED = "the reviewed-revision write-back could not measure whether this round touched the document (no dispatch baseline or an unreadable repository) — the current bytes were bound";
|
|
36
42
|
/**
|
|
37
43
|
* PlanStructure — one plan document's STRUCTURE face: the task-id set and each task's
|
|
38
44
|
* declared `DependsOn` set (design spec §7.3).
|
|
@@ -427,11 +433,12 @@ export class Lifecycle {
|
|
|
427
433
|
// -------------------------------------------------------------------------
|
|
428
434
|
/** Bookkeeping — persist the round's handoff carrier and record the round. The
|
|
429
435
|
* persisted carrier is either the dispatch's materialized form (the production
|
|
430
|
-
* read-back reconstruct — outcome.carrier
|
|
431
|
-
*
|
|
432
|
-
*
|
|
433
|
-
*
|
|
434
|
-
*
|
|
436
|
+
* read-back reconstruct — outcome.carrier) or — on the INJECTED face alone (an
|
|
437
|
+
* outcome carrying no verdict) — the engine-built fallback from the outcome fields.
|
|
438
|
+
* Either way it lands as the FINAL carrier beside the child's draft, never over it
|
|
439
|
+
* (P31 §2.3: the draft keeps the child's bytes, the final carries the engine's
|
|
440
|
+
* materialization, and the record names both paths). A production round that wrote
|
|
441
|
+
* no carrier is booked with `carrierPath: null` and no file at either name: the
|
|
435
442
|
* completion criterion owns the absence (§3.3), and a re-dispatch's draft read must
|
|
436
443
|
* see the child's own draft, never an engine synthesis of it. A failure round
|
|
437
444
|
* WITHOUT a carrier leaves the child's draft untouched (no-overwrite on failure) but
|
|
@@ -441,6 +448,8 @@ export class Lifecycle {
|
|
|
441
448
|
#bookkeep(frame, outcome) {
|
|
442
449
|
const blocked = outcome.status === "BLOCKED" || outcome.status === "TIMEOUT";
|
|
443
450
|
let carrierPath = null;
|
|
451
|
+
let carrierDigest = null;
|
|
452
|
+
let draftPath = null;
|
|
444
453
|
if (outcome.carrier !== undefined || (outcome.verdict === undefined && !blocked)) {
|
|
445
454
|
const op = this.#opOf(frame.phase);
|
|
446
455
|
// T2 — the engine-built fallback rides the FRAME's op-derived plane (never the
|
|
@@ -463,12 +472,35 @@ export class Lifecycle {
|
|
|
463
472
|
// (`HandoffSchema.conclusionOf` → rollup(findings)), never a stored field (D27).
|
|
464
473
|
if (plane === "work" && carrier.status === undefined && outcome.status !== undefined)
|
|
465
474
|
carrier.status = outcome.status;
|
|
466
|
-
|
|
475
|
+
// P31 §2.2/§2.3 — the persist hands the FINAL carrier path, the draft path it
|
|
476
|
+
// landed beside and the payload digest, so the round record can name both
|
|
477
|
+
// artifacts and replay the comparison on every later read of this carrier.
|
|
478
|
+
const persisted = this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
|
|
479
|
+
carrierPath = persisted.path;
|
|
480
|
+
carrierDigest = persisted.digest;
|
|
481
|
+
draftPath = persisted.draftPath;
|
|
482
|
+
}
|
|
483
|
+
else {
|
|
484
|
+
// P31 T5 §2.4 — a round that books NO carrier still owns its two names: the
|
|
485
|
+
// draft the child may have written before the round failed must not stay
|
|
486
|
+
// writable. The persistence seals its own pair above; this is the failure
|
|
487
|
+
// face's leg (the lifecycle's terminals seal too — one invariant, two entry
|
|
488
|
+
// points, so an injected dispatcher can never leave the window open).
|
|
489
|
+
this.#sealRoundCarriers(frame);
|
|
467
490
|
}
|
|
468
491
|
// The recorded CYCLE is the frame's own round — its identity (fix-K ⟷ review-K ·
|
|
469
492
|
// D28): a skipped cycle records its own number, never a flattened ordinal. The
|
|
470
493
|
// attempt was allocated once by the frame builder and rides both the record and
|
|
471
494
|
// the round log's name.
|
|
495
|
+
//
|
|
496
|
+
// P31 §2.7 — the write-back's three states become a graded entry HERE, before the
|
|
497
|
+
// record is written: an UNMEASURABLE range (`null`) keeps today's bind and books
|
|
498
|
+
// one soft observation (never a verdict flip); `true` / `false` / unmeasured ride
|
|
499
|
+
// the write-back gate below.
|
|
500
|
+
const violations = [
|
|
501
|
+
...(outcome.violations ?? []),
|
|
502
|
+
...(outcome.touchedDoc === null ? [RoundViolation.soft(WRITE_BACK_UNMEASURED)] : []),
|
|
503
|
+
];
|
|
472
504
|
const record = this.#ledger.recordRound(frame.key, {
|
|
473
505
|
op: this.#opOf(frame.phase),
|
|
474
506
|
cycle: frame.round,
|
|
@@ -481,8 +513,10 @@ export class Lifecycle {
|
|
|
481
513
|
treeClean: outcome.treeClean ?? true,
|
|
482
514
|
targetAction: !blocked,
|
|
483
515
|
},
|
|
484
|
-
violations
|
|
516
|
+
violations,
|
|
485
517
|
carrierPath,
|
|
518
|
+
carrierDigest,
|
|
519
|
+
draftPath,
|
|
486
520
|
}, frame.type);
|
|
487
521
|
// The completed-round revision write-back is gated on the round's VERDICT (a
|
|
488
522
|
// hard-failed round must not bind the current revision — that would silently
|
|
@@ -497,7 +531,14 @@ export class Lifecycle {
|
|
|
497
531
|
// real run records nothing while the preview still states the brief leg. The
|
|
498
532
|
// record methods keep their own defensive narrowing; an unreadable input records
|
|
499
533
|
// nothing (present facts only).
|
|
500
|
-
|
|
534
|
+
//
|
|
535
|
+
// P31 §2.7 — the bind is conditional on the round's OWN bytes: a READABLE range
|
|
536
|
+
// that touched the document not at all (`false`) keeps the OLD binding, so the
|
|
537
|
+
// existing drift / reopen face pushes the line back to review instead of silently
|
|
538
|
+
// closing it on bytes the round never delivered. `true`, `null` (unmeasurable —
|
|
539
|
+
// its soft entry is booked above) and `undefined` (hermetic / injected dispatchers)
|
|
540
|
+
// keep today's bind.
|
|
541
|
+
const leg = record.verdict.targetAction && outcome.touchedDoc !== false
|
|
501
542
|
? ReviewedIdentity.legOf(frame.phase, frame.target.kind)
|
|
502
543
|
: null;
|
|
503
544
|
if (leg !== null) {
|
|
@@ -603,6 +644,15 @@ export class Lifecycle {
|
|
|
603
644
|
#opOf(phase) {
|
|
604
645
|
return phase === "branch-review" ? "review" : phase;
|
|
605
646
|
}
|
|
647
|
+
/** P31 §2.4 — seal one round's OWN carrier names (its draft and its final). The
|
|
648
|
+
* derivation is the same pair the lifecycle's preflight opens; a round-less family
|
|
649
|
+
* (implement) resolves both to one path, so the seal is idempotent by construction. */
|
|
650
|
+
#sealRoundCarriers(frame) {
|
|
651
|
+
const op = this.#opOf(frame.phase);
|
|
652
|
+
const draftName = this.#ledger.handoffName(op, frame.type, frame.params);
|
|
653
|
+
CarrierSeal.seal(this.#ledger.handoffPath(op, frame.type, frame.params));
|
|
654
|
+
CarrierSeal.seal(this.#ledger.naming().finalPath(draftName, frame.params.round));
|
|
655
|
+
}
|
|
606
656
|
// -------------------------------------------------------------------------
|
|
607
657
|
// next routing + the capsule interaction
|
|
608
658
|
// -------------------------------------------------------------------------
|
|
@@ -701,12 +751,15 @@ export class Lifecycle {
|
|
|
701
751
|
const naming = this.#ledger.naming();
|
|
702
752
|
// The failure face's handoff is the crash record — the engine's own postmortem
|
|
703
753
|
// artifact, its existence the emission condition; the success face keeps the
|
|
704
|
-
// round's handoff carrier path
|
|
705
|
-
//
|
|
754
|
+
// round's handoff carrier path — the FINAL carrier the round wrote (P31 §2.3),
|
|
755
|
+
// resolved through the ledger's ONE read-name rule (the draft's family spelling is
|
|
756
|
+
// the fallback, never the cell's own derivation). The crash name derives from the
|
|
757
|
+
// frame through the ONE naming source (`RoundNaming`), the same name the lifecycle
|
|
758
|
+
// wrote it under.
|
|
706
759
|
const crash = failure ? this.#ledger.readCrash(naming.crashName(frame)) : null;
|
|
707
760
|
const handoff = crash !== null
|
|
708
761
|
? naming.crashPath(frame)
|
|
709
|
-
: this.#ledger.
|
|
762
|
+
: this.#ledger.resolveHandoffPath(op, frame.type, frame.params);
|
|
710
763
|
return this.#capsule.emit(outcome.status, handoff, hop, crash !== null, summary);
|
|
711
764
|
}
|
|
712
765
|
/** The frame's RouteTarget — the dispatch-ready literal's target identity (the
|