@oscaner-skills/cdd-engine 4.8.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.
@@ -23,8 +23,8 @@
23
23
  // Module-level exports are types / the declared registry / the class — zero
24
24
  // behavior-carrying bare functions.
25
25
  var _a, _b;
26
- import { readFileSync } from "node:fs";
27
26
  import path from "node:path";
27
+ import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
28
28
  import { RoundViolation, } from "../session/ledger.js";
29
29
  /**
30
30
  * CommitsSinceGroupBase — the implement criterion: the round is done when the GROUP
@@ -214,18 +214,12 @@ export const FIX_DISPOSITIONS_UNRECORDED = "the requesting review round records
214
214
  * answers from the carrier, never from the diff.
215
215
  */
216
216
  export class FixDispositions {
217
- /** The requesting carrier's path — the completed review record of the SAME key (the
218
- * row's records are already the key's) and the SAME cycle as the fix round; a
219
- * legacy record without `carrierPath` falls back to the route's `--reviews` path. */
217
+ /** The requesting carrier's path — the LATEST attempt of the same-cycle review of the
218
+ * SAME key (the row's records are already the key's), the record whose digest the
219
+ * checked read compares against; a legacy record without `carrierPath` falls back to
220
+ * the route's `--reviews` path. */
220
221
  static requesterPathOf(records, cycle, reviewsPath) {
221
- for (const record of records) {
222
- if (record.op !== "review" || record.cycle !== cycle)
223
- continue;
224
- if (!record.verdict.targetAction)
225
- continue;
226
- return record.carrierPath ?? reviewsPath;
227
- }
228
- return reviewsPath;
222
+ return _b.#requesterOf(records, cycle)?.carrierPath ?? reviewsPath;
229
223
  }
230
224
  /** Read the requesting carrier's input set (the findings, deduped by disposition
231
225
  * key in carrier order). The read is synchronous on purpose: the input is ONE small
@@ -235,17 +229,33 @@ export class FixDispositions {
235
229
  * Every path resolves against `repoRoot`, never `process.cwd()`: the engine runs
236
230
  * from a subdirectory too, `--reviews` arrives repoRoot-relative and a record's
237
231
  * `carrierPath` arrives absolute — both must land on the one basis (`RepoRoot`'s
238
- * rule). The reported `path` is the resolved one, so a failure names a real file. */
232
+ * rule). The reported `path` is the resolved one, so a failure names a real file.
233
+ *
234
+ * P31 §2.2 — the read is the ONE checked carrier read (`CarrierIntegrity.read`):
235
+ * the requesting round's recorded digest decides ok / mismatch, so a tampered
236
+ * input throws instead of being judged as if the round had written those bytes. */
239
237
  static requesterInputOf(records, cycle, reviewsPath, repoRoot) {
240
- const declared = _b.requesterPathOf(records, cycle, reviewsPath);
238
+ const requester = _b.#requesterOf(records, cycle);
239
+ const declared = requester?.carrierPath ?? reviewsPath;
241
240
  if (declared === null)
242
241
  return { kind: "unrecorded" };
243
242
  const target = path.resolve(repoRoot, declared);
244
243
  let carrier;
245
244
  try {
246
- carrier = JSON.parse(readFileSync(target, "utf8"));
245
+ // P31 §2.2 — the input carrier is read through the ONE checked seam: the
246
+ // requesting review record's digest when it declared the path, no comparison on
247
+ // the legacy `--reviews` fallback. A mismatch is NOT an `unreadable` input (that
248
+ // would silently judge the tampered bytes): the error propagates and the CLI's
249
+ // blocked channel names it.
250
+ const bytes = CarrierIntegrity.read(target, _b.#requesterDigestOf(requester));
251
+ if (bytes === null) {
252
+ return { kind: "unreadable", path: target, detail: "the file is absent or not JSON" };
253
+ }
254
+ carrier = JSON.parse(bytes);
247
255
  }
248
- catch {
256
+ catch (raw) {
257
+ if (raw instanceof CarrierMismatchError)
258
+ throw raw;
249
259
  return { kind: "unreadable", path: target, detail: "the file is absent or not JSON" };
250
260
  }
251
261
  const findings = carrier?.findings;
@@ -266,6 +276,25 @@ export class FixDispositions {
266
276
  }
267
277
  return { kind: "read", path: target, findings: set.findings };
268
278
  }
279
+ /** THE requesting record — the LATEST attempt of the same-cycle review (a re-dispatch
280
+ * supersedes its predecessor, the same rule the ledger's checked carrier read and the
281
+ * dispatch gate apply). Path AND digest come from this one record, so a re-dispatched
282
+ * review is never read against its predecessor's digest: the gate and this criterion
283
+ * cannot disagree about which review round the fix is answering. */
284
+ static #requesterOf(records, cycle) {
285
+ return records
286
+ .filter((record) => record.op === "review" && record.cycle === cycle)
287
+ .reduce((newest, record) => newest === undefined || record.attempt >= newest.attempt ? record : newest, undefined);
288
+ }
289
+ /** The digest the requesting review round recorded — read off the SAME record
290
+ * `requesterPathOf` selects. Null when that record declared no path (the legacy
291
+ * `--reviews` fallback carries no digest, so the read performs no comparison) or when
292
+ * the record predates the digest column. */
293
+ static #requesterDigestOf(record) {
294
+ if (record === undefined || record.carrierPath === null)
295
+ return null;
296
+ return record.carrierDigest ?? null;
297
+ }
269
298
  /** The carrier's `dispositions` map — null when the slot is absent or not an
270
299
  * object (the criterion's own shape refusal; the schema only pins the slot type). */
271
300
  static dispositionsOf(carrier) {
@@ -9,7 +9,7 @@
9
9
  // cross-doc-chain · section-scoped-domain ·
10
10
  // phase-design-spec-is-phase-spec;
11
11
  // the change-history family — change-history-version-unique ·
12
- // change-history-row-shape ·
12
+ // change-history-header-columns · change-history-row-shape ·
13
13
  // change-history-latest-matches-front-matter ·
14
14
  // front-matter-version-in-lineage ·
15
15
  // change-history-row-not-in-other-table · list-marker-not-doubled;
@@ -447,6 +447,31 @@ export class ChangeHistoryRowShapeInvariant extends Invariant {
447
447
  return findings;
448
448
  }
449
449
  }
450
+ /** The DECLARED `## Change history` column set — the header must equal it cell for
451
+ * cell (after `trim`). The row-shape leg judges a row against whatever the header
452
+ * declares; this declaration is what makes the header itself a judged fact. */
453
+ export const CHANGE_HISTORY_COLUMNS = ["Version", "date", "summary", "author"];
454
+ /** change-history-header-columns — the `## Change history` header must BE the declared
455
+ * column set: a grown, dropped or renamed column silently redefines what every row
456
+ * means, so it is reported once, independently of the row widths (the two legs are
457
+ * orthogonal: this one reads the header, `change-history-row-shape` reads the rows
458
+ * against that header). An absent section / header judges nothing here. */
459
+ export class ChangeHistoryHeaderColumnsInvariant extends Invariant {
460
+ name = "change-history-header-columns";
461
+ evaluate(ctx) {
462
+ const header = this.changeHistory(ctx).headerRow;
463
+ if (header === null || header.length === 0)
464
+ return [];
465
+ const cells = header.map((cell) => cell.trim());
466
+ const declared = CHANGE_HISTORY_COLUMNS;
467
+ const conforms = cells.length === declared.length && cells.every((cell, index) => cell === declared[index]);
468
+ if (conforms)
469
+ return [];
470
+ return [
471
+ this.finding(ctx, "Change history", `the Change-history header reads "${cells.join(" | ")}" against the declared "${declared.join(" | ")}"`, `write the header as | ${declared.join(" | ")} | — the column set is declared, not free-form`),
472
+ ];
473
+ }
474
+ }
450
475
  /** change-history-latest-matches-front-matter — the front-matter `version:` IS the
451
476
  * lineage's newest numeric version: appending a row lifts both in the same edit, so
452
477
  * the two sides can never disagree. */
@@ -18,15 +18,15 @@
18
18
  // multi-surface strategies of the old family were split per leg (uniqueness → three,
19
19
  // order → one section-order row, selfBounded → one lineage row), so a declaration row
20
20
  // never hides a second rule. Version ORDER stays presentation, not data integrity; the
21
- // header-to-newest-row agreement and the row's cell shape are declared legs of their
22
- // own (`change-history-latest-matches-front-matter` · `change-history-row-shape`), and
23
- // the lineage identity read is membership-plus-anchor (the first cell must BE a
24
- // version).
21
+ // header-to-newest-row agreement, the header's own column set and the row's cell shape
22
+ // are declared legs of their own (`change-history-latest-matches-front-matter` ·
23
+ // `change-history-header-columns` · `change-history-row-shape`), and the lineage
24
+ // identity read is membership-plus-anchor (the first cell must BE a version).
25
25
  //
26
26
  // Module-level exports are types / the declared data — zero behavior-carrying bare
27
27
  // functions.
28
- import { ChangeHistoryLatestMatchesFrontMatterInvariant, ChangeHistoryRowShapeInvariant, ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseDesignSpecIsPhaseSpecInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
29
- /** The rule registry — doc scope 23 rows + ledger scope 2 rows = 25. */
28
+ import { ChangeHistoryHeaderColumnsInvariant, ChangeHistoryLatestMatchesFrontMatterInvariant, ChangeHistoryRowShapeInvariant, ChangeHistoryVersionUniqueInvariant, ContinuityInvariant, CrossDocChainInvariant, CrosslinkInvariant, DomainInvariant, FileExistenceInvariant, FrontMatterVersionInLineageInvariant, HollowInvariant, LedgerLayeringRule, LedgerTaskSetRule, LinkShapeInvariant, ListMarkerInvariant, PhaseDesignSpecIsPhaseSpecInvariant, PhaseIdUniqueInvariant, PresenceInvariant, ResidueInvariant, RowHomeInvariant, SectionOrderInvariant, SectionScopedDomainInvariant, SiblingScanInvariant, SlugRefInvariant, TaskIdUniqueInvariant, WaveWidthInvariant, } from "./invariants.js";
29
+ /** The rule registry — doc scope 24 rows + ledger scope 2 rows = 26. */
30
30
  export const RULE_REGISTRY = [
31
31
  { scope: "doc", id: "presence", docKeys: "all", create: () => new PresenceInvariant() },
32
32
  {
@@ -41,6 +41,12 @@ export const RULE_REGISTRY = [
41
41
  docKeys: "all",
42
42
  create: () => new ChangeHistoryRowShapeInvariant(),
43
43
  },
44
+ {
45
+ scope: "doc",
46
+ id: "change-history-header-columns",
47
+ docKeys: "all",
48
+ create: () => new ChangeHistoryHeaderColumnsInvariant(),
49
+ },
44
50
  {
45
51
  scope: "doc",
46
52
  id: "change-history-latest-matches-front-matter",
@@ -44,6 +44,7 @@ import { RepoRoot } from "../infra/root.js";
44
44
  import { ENGINE_RUNTIME } from "../infra/runtime.js";
45
45
  import { SlugIndex } from "../infra/slug-index.js";
46
46
  import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
47
+ import { CarrierIntegrity } from "../session/carrier-integrity.js";
47
48
  import { TaskGraph } from "../session/graph.js";
48
49
  import { Ledger, RoundRecords } from "../session/ledger.js";
49
50
  import { PipelineFrontier } from "../session/pipeline.js";
@@ -265,13 +266,12 @@ export class BoardView {
265
266
  }
266
267
  /** One round's findings count — the `findings` array length of the carrier the round
267
268
  * persisted (the judge plane's declared field). Zero when the record carries no
268
- * carrier path or the file is absent/unreadable/unparseable (present facts only,
269
- * never a throw on a read face). */
269
+ * carrier path or the file is absent (present facts only). P31 §2.2 — the read goes
270
+ * through the ONE checked seam: a carrier whose bytes no longer match the recorded
271
+ * digest THROWS (`carrier-mismatch` rides the CLI's blocked channel), never a
272
+ * silent zero. */
270
273
  static #findingsCountOf(record) {
271
- const at = record.carrierPath;
272
- if (at === null)
273
- return 0;
274
- const text = BoardView.#read(at);
274
+ const text = CarrierIntegrity.readFor(record);
275
275
  if (text === null)
276
276
  return 0;
277
277
  try {
package/dist/face/cli.js CHANGED
@@ -60,6 +60,7 @@ import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
60
60
  import { BriefRenderer } from "../render/brief.js";
61
61
  import { IssueBodyRenderer } from "../render/issue-body.js";
62
62
  import { TemplateAssembler } from "../render/templates.js";
63
+ import { CarrierMismatchError } from "../session/carrier-integrity.js";
63
64
  import { DispatchAuthority, } from "../session/dispatch-authority.js";
64
65
  import { TargetFaceTable, targetFaces, } from "../session/faces.js";
65
66
  import { TaskGraph } from "../session/graph.js";
@@ -222,6 +223,15 @@ export class Cli {
222
223
  * invalid argument (incl. the preAction conditional-required) · excess args ·
223
224
  * missing required) → 2, an unexpected error → 1. */
224
225
  #normalizeExit(err) {
226
+ // P31 §2.2 — a carrier whose bytes no longer digest to the recorded value is a
227
+ // hard stop on the CDD_BLOCKED channel (the ordered-rank of every blocked gate),
228
+ // with the existing blocked exit code. The read faces that can meet it (board's
229
+ // `+N` count, the fix criterion's input, the ledger's carrier read) all throw it
230
+ // through their own seam.
231
+ if (err instanceof CarrierMismatchError) {
232
+ this.#io.stderr(`${this.#words.station("blocked")} ${err.message}\n`);
233
+ return 1;
234
+ }
225
235
  if (err instanceof CommanderError) {
226
236
  if (err.code === "commander.help")
227
237
  return err.exitCode === 0 ? 0 : 2;
@@ -15,15 +15,19 @@ var _a;
15
15
  // The module exports the shared seams + the lifecycle class — zero behavior-carrying
16
16
  // bare functions.
17
17
  import { existsSync, readFileSync } from "node:fs";
18
+ import path from "node:path";
18
19
  import process from "node:process";
19
20
  import { printParseErrorCode } from "jsonc-parser";
20
21
  import { CompletionCriteria, FixDispositions } from "../contract/completion-criterion.js";
21
22
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
23
+ import { CarrierSeal } from "../infra/carrier-seal.js";
22
24
  import { GitClient } from "../infra/git.js";
23
25
  import { ProcessFacts } from "../infra/proc.js";
24
26
  import { RoundLog } from "../infra/round-log.js";
25
27
  import { BriefRenderer } from "../render/brief.js";
26
28
  import { TemplateAssembler } from "../render/templates.js";
29
+ import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
30
+ import { CarrierRulings } from "../session/carrier-rulings.js";
27
31
  import { TargetFaceTable } from "../session/faces.js";
28
32
  import { HandoffSchema } from "../session/handoff-schema.js";
29
33
  import { InFlight } from "../session/inflight.js";
@@ -200,8 +204,19 @@ export class CliLifecycle {
200
204
  violations: [ABORT_INTERRUPTED],
201
205
  carrierPath: null,
202
206
  }, "wave");
207
+ // P31 T5 §2.4 — the killed round's carrier names close with its abort record: the
208
+ // draft the dead child may have left writable and the final it never materialized.
209
+ // The identity is the record's OWN (the same op/cycle the abort booked), never a
210
+ // re-derivation from the current frontier.
211
+ this.#sealRoundCarriersOf(op, "wave", _a.#waveParams(key, cycle, op));
203
212
  return true;
204
213
  }
214
+ /** The handoff params of a wave round, replayed from a dead holder's record — the
215
+ * same shaping the frame builder applies (the implement family is round-less, the
216
+ * review / fix families carry the cycle). */
217
+ static #waveParams(key, cycle, op) {
218
+ return op === "implement" ? { tasks: key } : { tasks: key, round: cycle };
219
+ }
205
220
  /** One dispatch — the round's work, the observation facts every record carries (the
206
221
  * dispatch baseline HEAD captured before the spawn, the dispatch-after
207
222
  * `treeClean` observation) and the TERMINAL VERDICT the round is booked under
@@ -228,6 +243,9 @@ export class CliLifecycle {
228
243
  ...drafted,
229
244
  dispatchBase: this.#dispatchBase,
230
245
  treeClean: await this.#git.isClean(this.#scene.workspace.root.repoRoot),
246
+ // P31 §2.7 — whether THIS round's commits touched the document its write-back
247
+ // binds. Measured once, here, from the same baseline the postmortem reads.
248
+ touchedDoc: await this.#touchedDocOf(carried),
231
249
  };
232
250
  const judged = await this.#verdictOf(carried, observed);
233
251
  // The death faces author their own entry AND emit their own line (`#reject`), so
@@ -247,6 +265,31 @@ export class CliLifecycle {
247
265
  violations: judged.violations,
248
266
  };
249
267
  }
268
+ /** The document path the round's write-back would bind (P31 §2.7) — the doc leg's
269
+ * target document, the branch leg's plan document. The wave leg binds a brief
270
+ * PROJECTION rather than a document, so it does not participate (null). */
271
+ #reviewedDocTargetOf(frame) {
272
+ if (frame.target.kind === "plan" || frame.target.kind === "spec")
273
+ return frame.target.doc;
274
+ if (frame.type === "branch")
275
+ return this.#scene.planPath;
276
+ return null;
277
+ }
278
+ /** Whether this round's own commits touched that document — `true` / `false` read off
279
+ * the `dispatchBase..HEAD` path set, `null` when the range cannot be read (no
280
+ * baseline / unreadable repo), `undefined` when the leg binds no document. The four
281
+ * states stay distinct all the way to the bookkeep: only `false` may skip the bind,
282
+ * and `null` books its own soft observation. */
283
+ async #touchedDocOf(frame) {
284
+ const target = this.#reviewedDocTargetOf(frame);
285
+ if (target === null)
286
+ return undefined;
287
+ const repoRoot = this.#scene.workspace.root.repoRoot;
288
+ const touched = await this.#git.pathsSince(repoRoot, this.#dispatchBase);
289
+ if (touched === null)
290
+ return null;
291
+ return touched.includes(path.relative(repoRoot, path.resolve(repoRoot, target)));
292
+ }
250
293
  /** The round's concluded status under its verdict — a done round keeps its handoff
251
294
  * conclusion (APPROVED when the handoff was never written: the completion criterion
252
295
  * concluded it), and a hard-failed round concludes BLOCKED — or keeps TIMEOUT, the
@@ -471,6 +514,34 @@ export class CliLifecycle {
471
514
  this.#io.stderr("CDD_BLOCKED: no host harness detected (run cdd from within a supported harness)\n");
472
515
  return { status: "BLOCKED" };
473
516
  }
517
+ // P31 T5 §2.4 — the preflight half of the seal cycle: the workspace's ORPHAN
518
+ // carriers first (a process killed outside the engine leaves a writable carrier
519
+ // behind), then this round's OWN two names become writable — its draft for the
520
+ // child, its final for the materialization. The scope is the round's own paths,
521
+ // never the directory or the slug: an input carrier of an earlier round (the fix
522
+ // leg's `--reviews`) stays 0o444 for the whole dispatch.
523
+ this.#openRoundCarriers(frame);
524
+ // P31 T3 — the carrier-integrity gate: the fix round's requesting carrier is
525
+ // compared against the digest its round recorded BEFORE the in-flight record and
526
+ // the child, so a tampered input never reaches a child (the read-back and the CLI
527
+ // catch are the fallbacks, never the gate). It runs BEFORE the ruling gate: the
528
+ // integrity diagnostic is the fact, and a sidecar judged against tampered bytes
529
+ // would name a ruling reason for a carrier whose bytes simply changed.
530
+ const carrierRefusal = this.#carrierRefusal(frame);
531
+ if (carrierRefusal !== null) {
532
+ this.#sealRoundCarriers(frame);
533
+ this.#blocked(carrierRefusal, false);
534
+ return { status: "BLOCKED", violations: [RoundViolation.hard(carrierRefusal)] };
535
+ }
536
+ // P31 T2 — the ruling sidecar gate: a sidecar the strict schema refuses stops the
537
+ // round HERE, before the in-flight record is acquired and before any child exists
538
+ // (a written-but-invisible ruling is the defect this gate removes).
539
+ const rulingsRefusal = this.#rulingsRefusal(frame);
540
+ if (rulingsRefusal !== null) {
541
+ this.#sealRoundCarriers(frame);
542
+ this.#blocked(rulingsRefusal, false);
543
+ return { status: "BLOCKED", violations: [RoundViolation.hard(rulingsRefusal)] };
544
+ }
474
545
  const prompt = this.#template.render(this.#valuesOf(frame));
475
546
  const row = HOSTS[host];
476
547
  const cliName = row.cli;
@@ -482,7 +553,17 @@ export class CliLifecycle {
482
553
  // A sibling dispatch that won the lock in between makes `acquire` throw
483
554
  // `HoldingError` (carrying the holder's facts), which rides the CLI's held BLOCK.
484
555
  this.#dispatchBase = await this.#git.head(this.#scene.workspace.root.repoRoot);
485
- await this.#inflight.acquire(await this.#recordOf(frame), { recover: this.#recover });
556
+ try {
557
+ await this.#inflight.acquire(await this.#recordOf(frame), { recover: this.#recover });
558
+ }
559
+ catch (raw) {
560
+ // P31 T5 §2.4 — the preflight half already opened this round's two names, so
561
+ // EVERY exit after it closes them, including this one: a losing dispatch (the
562
+ // gate→acquire race the CLI renders as the held BLOCK) must not leave a
563
+ // writable carrier behind for the next preflight sweep to recover.
564
+ this.#sealRoundCarriers(frame);
565
+ throw raw;
566
+ }
486
567
  // The round's own log file — created BEFORE the spawn (append stream open, zero
487
568
  // bytes), so the channel exists from the dispatch's first millisecond. A create
488
569
  // failure is a named soft observation and the round continues on the CPU leg
@@ -713,6 +794,11 @@ export class CliLifecycle {
713
794
  // carrier; a review writes its own draft (INPUT_REVIEWS === OUTPUT_HANDOFF
714
795
  // would be a short-circuit).
715
796
  INPUT_REVIEWS: op === "fix" ? this.#rel(this.#reviewsPath(frame) ?? "") : "",
797
+ // P31 T2 — the ruling sidecar rides the fix input side alone (the review round's
798
+ // own context has no sidecar yet). The path derives from the requesting carrier
799
+ // by the ONE `.json` → `.rulings.json` rule; an absent sidecar leaves the slot
800
+ // empty, so the assembler drops the line entirely.
801
+ INPUT_RULINGS: this.#rulingsInputOf(frame),
716
802
  // The kind-named judged-doc anchors (the semantic retirement of the generic
717
803
  // INPUT_DOC): the plan/branch lines carry the plan document (INPUT_PLAN — the
718
804
  // doc path on a plan line, the plan path on a branch line, whose review/fix
@@ -797,6 +883,47 @@ export class CliLifecycle {
797
883
  return lines.slice(-STDOUT_TAIL_MAX);
798
884
  }
799
885
  // -------------------------------------------------------------------------
886
+ // the carrier seal cycle (P31 T5 §2.4) — the round's own write window
887
+ // -------------------------------------------------------------------------
888
+ /** P31 §2.4 preflight — recover the workspace's orphans, then open THIS round's own
889
+ * two names. The sweep runs FIRST so a carrier this round is about to own (a stale
890
+ * draft of a retried round) is already closed when it is reopened here: the window
891
+ * is the two names, never a third file. */
892
+ #openRoundCarriers(frame) {
893
+ CarrierSeal.sweep(this.#scene.workspace.path, []);
894
+ for (const name of this.#roundCarrierNames(frame))
895
+ CarrierSeal.unseal(name);
896
+ }
897
+ /** P31 §2.4 terminal — close the round's own write window. Every exit path that ran
898
+ * the preflight half calls this (a gate refusal, a death face, an abort fold), so no
899
+ * terminal leaves an engine carrier writable. */
900
+ #sealRoundCarriers(frame) {
901
+ this.#sealRoundCarriersOf(this.#opOf(frame), frame.type, frame.params);
902
+ }
903
+ /** The seal of one (op, type, params) identity — the frame-shaped callers and the
904
+ * dead-holder fold share this ONE derivation. */
905
+ #sealRoundCarriersOf(op, type, params) {
906
+ for (const name of this.#roundCarrierNamesOf(op, type, params))
907
+ CarrierSeal.seal(name);
908
+ }
909
+ /** A frame's own carrier paths — the child's draft (`Ledger#handoffPath`, the family
910
+ * table's fill) and the engine's final (`RoundNaming#finalPath`, `.c{N}` suffixed).
911
+ * A round-less family (implement) resolves both to the same path — one name, sealed
912
+ * once. */
913
+ #roundCarrierNames(frame) {
914
+ return this.#roundCarrierNamesOf(this.#opOf(frame), frame.type, frame.params);
915
+ }
916
+ /** `#roundCarrierNames` over an identity — the abort fold's entry (it holds a dead
917
+ * holder's op/cycle, never a frame). */
918
+ #roundCarrierNamesOf(op, type, params) {
919
+ const ledger = this.#scene.ledger;
920
+ const draftName = ledger.handoffName(op, type, params);
921
+ return [
922
+ this.#scene.workspace.resolve(draftName),
923
+ this.#naming.finalPath(draftName, params.round),
924
+ ];
925
+ }
926
+ // -------------------------------------------------------------------------
800
927
  // the read-back reconstruct (§3.6) — the draft is the round's content
801
928
  // -------------------------------------------------------------------------
802
929
  /** The ONE draft-read point — the frame's handoff draft read with the lenient
@@ -917,11 +1044,24 @@ export class CliLifecycle {
917
1044
  // carriers the ledger reads back, never a schema-validated draft).
918
1045
  const status = schema.conclusionOf(plane, draft) ?? "BLOCKED";
919
1046
  const carrier = this.#materialize(frame, plane, draft, status);
1047
+ // P31 §2.2 — the disposition summary reads the REQUESTING carrier. A mismatch
1048
+ // found here (the bytes moved inside the round) is a BLOCKED outcome: the read-back
1049
+ // is the FALLBACK behind the pre-dispatch gate, never the gate itself.
1050
+ let summary;
1051
+ try {
1052
+ summary = this.#dispositionsSummary(frame, plane, carrier);
1053
+ }
1054
+ catch (raw) {
1055
+ if (!(raw instanceof CarrierMismatchError))
1056
+ throw raw;
1057
+ this.#blocked(raw.message, false);
1058
+ return { status: "BLOCKED", violations: [RoundViolation.hard(raw.message)] };
1059
+ }
920
1060
  return {
921
1061
  status,
922
1062
  findings: plane === "judge" ? schema.findingsOf(findings) : undefined,
923
1063
  carrier,
924
- dispositionsSummary: this.#dispositionsSummary(frame, plane, carrier),
1064
+ dispositionsSummary: summary,
925
1065
  };
926
1066
  }
927
1067
  /** The fix round's ONE summary line (design spec §3.4) — computed from the PERSISTED
@@ -943,8 +1083,12 @@ export class CliLifecycle {
943
1083
  /** The requesting review carrier's path — the fix round's `--reviews` input, or the
944
1084
  * ledger's resolved review handoff path when the route carried none (the ONE
945
1085
  * resolution the round context's INPUT_REVIEWS and the disposition summary share).
946
- * A migrated line resolves the carrier that EXISTS — the retired twin's name, never
947
- * the never-minted canonical spelling.
1086
+ * Four layers, ONE identity (P31 §2.3): the explicit `--reviews` flag → the
1087
+ * same-cycle review record's own `carrierPath` (the FINAL carrier the round wrote) →
1088
+ * the ledger's resolved family name (a draft, or a migrated line's retired twin —
1089
+ * the carrier that EXISTS, never the never-minted canonical spelling) → the legacy
1090
+ * `null`. Record-present means final-wins: a draft sitting beside the final never
1091
+ * becomes the judged input.
948
1092
  *
949
1093
  * A same-cycle review record that RECORDED no carrier path, with no carrier at
950
1094
  * either spelling on disk, leaves the requester input UNRECORDED: the answer is
@@ -955,6 +1099,9 @@ export class CliLifecycle {
955
1099
  #reviewsPath(frame) {
956
1100
  if (this.#reviews !== null)
957
1101
  return this.#reviews;
1102
+ const recorded = this.#requesterRecord(frame)?.carrierPath;
1103
+ if (typeof recorded === "string" && recorded !== "")
1104
+ return recorded;
958
1105
  const resolved = this.#scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
959
1106
  if (existsSync(resolved))
960
1107
  return resolved;
@@ -963,6 +1110,136 @@ export class CliLifecycle {
963
1110
  .some((record) => record.op === "review" && record.cycle === frame.round && record.carrierPath === null);
964
1111
  return legacy ? null : resolved;
965
1112
  }
1113
+ /** The same-cycle review record this fix round answers — its LATEST attempt (a
1114
+ * re-dispatched review supersedes its predecessor, the same rule the round-read gate
1115
+ * applies). Null when the line records no review for this cycle. ONE basis for the
1116
+ * requesting carrier's path and its digest. */
1117
+ #requesterRecord(frame) {
1118
+ const reviewed = this.#scene.ledger
1119
+ .recordsOf(frame.key, frame.type)
1120
+ .filter((record) => record.op === "review" && record.cycle === frame.round);
1121
+ return reviewed.reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
1122
+ }
1123
+ /** The fix input's carrier-integrity gate — the `carrier-mismatch` refusal when the
1124
+ * requesting review carrier no longer digests to the value its round recorded, null
1125
+ * when the round may proceed (P31 §2.2). Only the fix face reads a carrier that
1126
+ * already existed before this dispatch (`INPUT_REVIEWS` is its own input), so every
1127
+ * other phase has no gate to set. A carrier with no recorded digest — a legacy round,
1128
+ * or a resolved path no record declared — is read as present facts: no comparison,
1129
+ * no refusal. */
1130
+ #carrierRefusal(frame) {
1131
+ if (this.#opOf(frame) !== "fix")
1132
+ return null;
1133
+ const carrier = this.#reviewsPath(frame);
1134
+ if (carrier === null)
1135
+ return null;
1136
+ const digest = this.#requesterDigest(frame);
1137
+ if (digest === null)
1138
+ return null;
1139
+ try {
1140
+ CarrierIntegrity.read(path.resolve(this.#repoRootValue().absolute, carrier), digest);
1141
+ return null;
1142
+ }
1143
+ catch (raw) {
1144
+ if (raw instanceof CarrierMismatchError)
1145
+ return raw.message;
1146
+ throw raw;
1147
+ }
1148
+ }
1149
+ /** The digest the requesting review round recorded — the same-cycle review record's
1150
+ * latest attempt (the round `#reviewsPath` resolves). Null when no record carries
1151
+ * one: the present-facts read. */
1152
+ #requesterDigest(frame) {
1153
+ return this.#requesterRecord(frame)?.carrierDigest ?? null;
1154
+ }
1155
+ /** The fix round's ruling sidecar as the round-context value — the repo-relative
1156
+ * sidecar path when a conforming sidecar sits beside the requesting carrier, plus the
1157
+ * ruling bodies it carries, the empty string otherwise (off the fix face, with no
1158
+ * resolved carrier, and when the sidecar is absent — the assembler drops the empty
1159
+ * line). The strict judgment is the dispatch gate's `#rulingsRefusal`; this cell
1160
+ * names the file the round may read AND states the verdicts (§2.5 AC: the rendered
1161
+ * text matches the sidecar), so a ruling is never merely a path the child must
1162
+ * re-open to discover. */
1163
+ #rulingsInputOf(frame) {
1164
+ if (this.#opOf(frame) !== "fix")
1165
+ return "";
1166
+ const carrier = this.#reviewsPath(frame);
1167
+ if (carrier === null)
1168
+ return "";
1169
+ const verdict = this.#rulingsVerdict(frame, carrier);
1170
+ if (verdict.kind !== "ok")
1171
+ return "";
1172
+ const sidecar = this.#rel(CarrierRulings.pathFor(carrier));
1173
+ return [sidecar, ...verdict.rulings.map((ruling) => this.#rulingLine(ruling))].join("\n");
1174
+ }
1175
+ /** One rendering of a recorded ruling — the finding id it answers and the ruling's
1176
+ * own text VERBATIM (never re-worded: the sidecar is the orchestrator's words, and
1177
+ * the round context quotes them). Indented under the sidecar path's bullet so the
1178
+ * cell reads as one input. */
1179
+ #rulingLine(ruling) {
1180
+ return ` - \`${ruling.finding}\` — ${ruling.ruling}`;
1181
+ }
1182
+ /** The pre-dispatch ruling gate — the strict sidecar verdict's refusal reason, or null
1183
+ * when the round may proceed (no fix face, no resolved carrier, an absent sidecar, or
1184
+ * a conforming one). A refusal is HARD and lands before the in-flight record and the
1185
+ * child, so a broken ruling set can never be dispatched unnoticed (§2.6).
1186
+ *
1187
+ * A `carrier-mismatch` from the sidecar's id read is the integrity refusal, never a
1188
+ * ruling reason: a tampered carrier is not judged (its id set is not a fact this
1189
+ * round may read), so the diagnostic names the bytes that changed. */
1190
+ #rulingsRefusal(frame) {
1191
+ if (this.#opOf(frame) !== "fix")
1192
+ return null;
1193
+ const carrier = this.#reviewsPath(frame);
1194
+ if (carrier === null)
1195
+ return null;
1196
+ let verdict;
1197
+ try {
1198
+ verdict = this.#rulingsVerdict(frame, carrier);
1199
+ }
1200
+ catch (raw) {
1201
+ if (!(raw instanceof CarrierMismatchError))
1202
+ throw raw;
1203
+ return raw.message;
1204
+ }
1205
+ return verdict.kind === "invalid" ? `rulings sidecar — ${verdict.reason}` : null;
1206
+ }
1207
+ /** The strict sidecar verdict over the requesting carrier's CHECKED id set — one call
1208
+ * shape for the gate and the round-context cell, so neither can read the ids by a
1209
+ * path the other does not take. */
1210
+ #rulingsVerdict(frame, carrier) {
1211
+ return CarrierRulings.verdict(carrier, this.#carrierFindingIds(frame, carrier));
1212
+ }
1213
+ /** The requesting carrier's engine-written finding ids (`F1`, `F2` …) — the id set a
1214
+ * ruling must name. The read is the ONE checked carrier read (`CarrierIntegrity.read`,
1215
+ * the digest its review round recorded): a tampered carrier is never observed at all —
1216
+ * the mismatch throws and the integrity refusal wins over any ruling reason. An absent
1217
+ * or unparseable carrier declares no ids, so any ruling beside it is refused by the
1218
+ * strict schema instead of being accepted against an empty set. */
1219
+ #carrierFindingIds(frame, carrier) {
1220
+ const ids = new Set();
1221
+ let carrierJson;
1222
+ try {
1223
+ const bytes = CarrierIntegrity.read(path.resolve(this.#repoRootValue().absolute, carrier), this.#requesterDigest(frame));
1224
+ if (bytes === null)
1225
+ return ids;
1226
+ carrierJson = JSON.parse(bytes);
1227
+ }
1228
+ catch (raw) {
1229
+ if (raw instanceof CarrierMismatchError)
1230
+ throw raw;
1231
+ return ids;
1232
+ }
1233
+ const findings = carrierJson?.findings;
1234
+ if (!Array.isArray(findings))
1235
+ return ids;
1236
+ for (const finding of findings) {
1237
+ const id = finding?.id;
1238
+ if (typeof id === "string")
1239
+ ids.add(id);
1240
+ }
1241
+ return ids;
1242
+ }
966
1243
  /** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
967
1244
  * same-command resume's decision source: the attempted handoff + the resume
968
1245
  * command) + NO carrier (the bookkeep leaves the draft untouched). The crash
@@ -1002,6 +1279,11 @@ export class CliLifecycle {
1002
1279
  // failure is named, never a silent absence (§3.3). The cause rides the death facts'
1003
1280
  // existing vocabulary (no new enum row).
1004
1281
  const violations = [RoundViolation.hard(reason, cause)];
1282
+ // P31 T5 §2.4 — the death face seals the round's own names: the draft the child may
1283
+ // have written before it died, and the final the round never materialized. A seal
1284
+ // here keeps the failure face from leaving the writable window open for whatever
1285
+ // the late-landing child still tries to write.
1286
+ this.#sealRoundCarriers(frame);
1005
1287
  if (death.termination === null)
1006
1288
  return { status: "BLOCKED", violations };
1007
1289
  return { status: "TIMEOUT", termination: death.termination, violations };
@@ -1214,7 +1496,12 @@ export class CliLifecycle {
1214
1496
  // the retained `--spec` flag.
1215
1497
  return `cdd review --type ${frame.type} --spec ${this.#docOf(frame)}`;
1216
1498
  case "fix": {
1217
- const findings = scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
1499
+ // The `--reviews` input is the SAME carrier the fix prompt names (P31 §2.3): one
1500
+ // four-layer resolution, never a second family spelling spliced here. The
1501
+ // fallback fires only when the recorded face resolves to `null` (a legacy record
1502
+ // with no carrier on disk) — the never-null guard keeps a command shape.
1503
+ const findings = this.#reviewsPath(frame) ??
1504
+ scene.ledger.resolveHandoffPath("review", frame.type, frame.params);
1218
1505
  const target = frame.target.kind === "plan"
1219
1506
  ? `--plan ${frame.target.doc}`
1220
1507
  : frame.target.kind === "spec"