@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.
@@ -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 (the
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). */
@@ -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 { Ledger, } from "./ledger.js";
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, full-replace at the SAME path, so the
431
- * child's draft becomes the finalized carrier — the two-state single file, the engine is the single
432
- * author) or — on the INJECTED face alone (an outcome carrying no verdict) — the
433
- * engine-built fallback from the outcome fields. A production round that wrote no
434
- * carrier is booked with `carrierPath: null` and no file at the handoff path: the
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
- carrierPath = this.#ledger.persistHandoff(op, frame.type, frame.params, carrier);
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: outcome.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
- const leg = record.verdict.targetAction
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. The name derives from the frame through the ONE
705
- // naming source (`RoundNaming`), the same name the lifecycle wrote it under.
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.handoffPath(op, frame.type, frame.params);
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.7.0",
3
+ "version": "4.9.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {