@oscaner-skills/cdd-engine 4.8.0 → 4.9.1

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.
@@ -24,7 +24,9 @@ var _a;
24
24
  import { createHash } from "node:crypto";
25
25
  import { readdirSync, readFileSync } from "node:fs";
26
26
  import { DocBodyProjection } from "../contract/doc-body.js";
27
+ import { CarrierSeal } from "../infra/carrier-seal.js";
27
28
  import { BriefRenderer } from "../render/brief.js";
29
+ import { CarrierIntegrity } from "./carrier-integrity.js";
28
30
  import { targetFaces } from "./faces.js";
29
31
  import { HandoffSchema } from "./handoff-schema.js";
30
32
  import { LineIdentity } from "./line-identity.js";
@@ -245,9 +247,10 @@ export class Ledger {
245
247
  return this.#basis().resolve(this.#basis().relativize(value));
246
248
  }
247
249
  // ---- the single author's write/read primitives ----
248
- /** Persist a JSON artifact — the ledger's single write point (engine sole author). */
250
+ /** Persist a JSON artifact — the ledger's single write point (engine sole author).
251
+ * Returns the digest of the written bytes (the carrier record's `carrierDigest`). */
249
252
  #persist(name, data) {
250
- this.#workspace.writeJson(name, data);
253
+ return this.#workspace.writeJsonHashed(name, data);
251
254
  }
252
255
  /** Read a JSON artifact; null when missing/corrupt (the ledger's read face keeps the
253
256
  * collapsed contract — the tri-state discrimination lives at the read-back
@@ -385,6 +388,11 @@ export class Ledger {
385
388
  verdict: init.verdict ?? { treeClean: true, targetAction: true },
386
389
  violations: init.violations ?? [],
387
390
  carrierPath: init.carrierPath ?? null,
391
+ // The digest column exists only on rounds that recorded one (a legacy record
392
+ // keeps no key at all — the read then compares nothing, zero migration).
393
+ ...(init.carrierDigest === undefined ? {} : { carrierDigest: init.carrierDigest }),
394
+ // …and the same for the draft path column (P31 §2.3).
395
+ ...(init.draftPath === undefined ? {} : { draftPath: init.draftPath }),
388
396
  };
389
397
  const existing = records.findIndex((candidate) => candidate.op === record.op &&
390
398
  candidate.cycle === record.cycle &&
@@ -617,9 +625,13 @@ export class Ledger {
617
625
  // The fix-awaited face — a drifted wave BRIEF reopens at review (D30/D16), else fix.
618
626
  if (this.briefDrifted(waveKey))
619
627
  return { kind: "review" };
628
+ // The `--reviews` identity is the ROUTE's own (P31 §2.3): the round read resolves
629
+ // the FINAL carrier the record names, so a draft beside it never becomes the input
630
+ // — the board's `next:` and the dispatch's read the same file by construction.
620
631
  return {
621
632
  kind: "fix",
622
- reviews: this.handoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
633
+ reviews: route.reviews ??
634
+ this.resolveHandoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
623
635
  };
624
636
  }
625
637
  return null;
@@ -1058,11 +1070,40 @@ export class Ledger {
1058
1070
  carrier.findings = init.findings;
1059
1071
  return carrier;
1060
1072
  }
1061
- /** Persist a handoff payload at the canonical name — the single-author full-replace
1062
- * write (never a merge: the engine owns the file). Returns the written path. */
1073
+ /** Persist a handoff payload as the round's FINAL carrier — the engine's single-author
1074
+ * write, at a name the child's DRAFT never occupies (P31 §2.3). Returns the final
1075
+ * path (what the round is judged by), the draft path it landed beside, and the
1076
+ * payload's digest, so the round record can remember all three.
1077
+ *
1078
+ * The digest covers the PAYLOAD, never the file bytes that hold it: `H = sha256(JSON
1079
+ * containing H)` is unsatisfiable, so the value is taken BEFORE the `contentSha256`
1080
+ * key joins the payload — the key is appended LAST and the payload is written once
1081
+ * (the read recomputes by the same rule: drop the key, re-serialize, sha256). The
1082
+ * draft is neither written nor deleted here: it is the child's artifact, and the
1083
+ * final is the engine's answer to it.
1084
+ *
1085
+ * P31 §2.4 — the write CLOSES the carrier: the final and the draft name beside it
1086
+ * land at `0o444` in the same step, so a carrier is read-only from the instant the
1087
+ * engine authored it. A name that never landed (a round whose child wrote no draft,
1088
+ * a round-less family whose draft IS the final) is not an error — the seal is
1089
+ * idempotent and absence is the round's own fact. */
1063
1090
  persistHandoff(op, type, params, data) {
1064
- this.#persist(this.handoffName(op, type, params), data);
1065
- return this.handoffPath(op, type, params);
1091
+ const draftName = this.handoffName(op, type, params);
1092
+ const payload = { ...data };
1093
+ // The engine owns this key — a caller-supplied value never seeds a self-covering digest.
1094
+ delete payload.contentSha256;
1095
+ const digest = CarrierIntegrity.digestOf(payload);
1096
+ payload.contentSha256 = digest;
1097
+ const finalName = this.#naming.finalName(draftName, params.round);
1098
+ this.#persist(finalName, payload);
1099
+ // The carrier is read-only the moment it exists; the draft beside it closes with it.
1100
+ CarrierSeal.seal(this.#workspace.resolve(finalName));
1101
+ CarrierSeal.seal(this.#workspace.resolve(draftName));
1102
+ return {
1103
+ path: this.#workspace.resolve(finalName),
1104
+ draftPath: this.#workspace.resolve(draftName),
1105
+ digest,
1106
+ };
1066
1107
  }
1067
1108
  /** The handoff file NAME a read actually resolves — the canonical family name, or a
1068
1109
  * DOCUMENT line's retired `spec` twin when the canonical file is absent (the
@@ -1075,6 +1116,13 @@ export class Ledger {
1075
1116
  * spelling). */
1076
1117
  resolveHandoffName(op, type, params = {}) {
1077
1118
  const canonical = this.handoffName(op, type, params);
1119
+ // P31 §2.3 — the FINAL carrier wins the read whenever the round has one: it is the
1120
+ // round's finalized answer, and the draft beside it is the child's raw input (an
1121
+ // un-materialized payload whose findings carry no engine id). A round-less family
1122
+ // (implement) has one name only, so `final` equals the canonical spelling.
1123
+ const final = this.#naming.finalName(canonical, params.round);
1124
+ if (final !== canonical && this.#read(final) !== null)
1125
+ return final;
1078
1126
  if (!RETIRED_SPEC_LINE_KEYS.has(type) || this.#read(canonical) !== null) {
1079
1127
  return canonical;
1080
1128
  }
@@ -1093,9 +1141,55 @@ export class Ledger {
1093
1141
  * alias keys on the line's declared word (`phase-spec` / `overall` / `single-spec`,
1094
1142
  * the same basis as `rowFor`'s) and never covers the node shapes. Every WRITE goes
1095
1143
  * through `persistHandoff`'s current spelling — the alias is read-only, and the name
1096
- * it resolves is `resolveHandoffName`'s ONE answer. */
1144
+ * it resolves is `resolveHandoffName`'s ONE answer.
1145
+ *
1146
+ * P31 §2.2 — the read is CHECKED: the (op, type, round) round's latest recorded
1147
+ * attempt supplies the digest the engine wrote, and `CarrierIntegrity.read` compares
1148
+ * the bytes against it before they are parsed (a mismatch throws
1149
+ * `CarrierMismatchError`, never a silently-judged tampered carrier). A legacy record
1150
+ * with no digest — or no record at all — reads as present facts, zero comparison. */
1097
1151
  readHandoff(op, type, params) {
1098
- return this.#read(this.resolveHandoffName(op, type, params));
1152
+ const name = this.resolveHandoffName(op, type, params);
1153
+ const bytes = CarrierIntegrity.read(this.#workspace.resolve(name), this.#carrierDigestOf(op, type, params));
1154
+ if (bytes === null)
1155
+ return null;
1156
+ try {
1157
+ return JSON.parse(bytes);
1158
+ }
1159
+ catch {
1160
+ return null;
1161
+ }
1162
+ }
1163
+ /** The digest the round recorded for the carrier this read resolves — its LATEST
1164
+ * attempt of the (op, type, round) identity (a re-dispatch supersedes its
1165
+ * predecessor, the same rule the round-read gate applies). Null when no record
1166
+ * carries one: the present-facts face (legacy rows, and reads of a round that never
1167
+ * booked its own carrier). */
1168
+ #carrierDigestOf(op, type, params) {
1169
+ return this.#latestRecordOf(op, type, params)?.carrierDigest ?? null;
1170
+ }
1171
+ /** The latest recorded attempt of an (op, type, round) identity — null when the line
1172
+ * carries no record for it (a legacy row, or a round never dispatched). ONE basis for
1173
+ * every "what did that round record" question (the digest the read compares against,
1174
+ * the carrier path `--reviews` names). */
1175
+ #latestRecordOf(op, type, params) {
1176
+ const mode = RoundRecords.opOf(op) ?? op;
1177
+ const round = params.round === undefined ? null : Number(params.round);
1178
+ return this.recordsOf(this.#roundKey(type, params), type)
1179
+ .filter((record) => record.op === mode)
1180
+ .filter((record) => round === null || record.cycle === round)
1181
+ .reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
1182
+ }
1183
+ /** The review carrier a round's fix leg reads as `--reviews` — the round's OWN
1184
+ * recorded carrier path (the FINAL carrier, P31 §2.3) when the record names one, and
1185
+ * the resolved family name (the draft spelling — legacy rows, and a round that
1186
+ * persisted no carrier) otherwise. Record-present means final-wins: a draft sitting
1187
+ * beside a final never becomes the judged input. */
1188
+ #reviewsPathOf(type, params, round) {
1189
+ const recorded = this.#latestRecordOf("review", type, { ...params, round })?.carrierPath;
1190
+ if (typeof recorded === "string" && recorded !== "")
1191
+ return recorded;
1192
+ return this.resolveHandoffPath("review", type, { ...params, round });
1099
1193
  }
1100
1194
  /** The retired document-line carrier name of one round — `spec-review-{round}.json` /
1101
1195
  * `spec-fix-{round}.json`. It lives here, never in the family table: it is a read
@@ -1151,10 +1245,13 @@ export class Ledger {
1151
1245
  * `{line}-{op}-{round}.json`, plus a document line's retired `spec` twin (the
1152
1246
  * pre-rename name a still-unbooked draft can carry). Null for a non-handoff file. */
1153
1247
  static #handoffOwner(name, families) {
1248
+ // A FINAL carrier (`<stem>.c{round}.json`, P31 §2.3) is the same artifact as its
1249
+ // draft — the cycle is the name's own suffix, never a second family.
1250
+ const draft = name.replace(/\.c\d+\.json$/, ".json");
1154
1251
  for (const [family, record] of Object.entries(families)) {
1155
1252
  const [op = "", type = ""] = family.split(".");
1156
1253
  for (const spelling of _a.#familySpellings(record.name, type)) {
1157
- const captures = _a.#familyCaptures(spelling, name);
1254
+ const captures = _a.#familyCaptures(spelling, draft);
1158
1255
  if (captures === null)
1159
1256
  continue;
1160
1257
  const key = type === "wave" ? (captures.tasks ?? "") : type;
@@ -1308,7 +1405,7 @@ export class Ledger {
1308
1405
  // source shared with the fix leg below (`HandoffSchema.conclusionOf`).
1309
1406
  status: this.#handoffSchema.conclusionOf("judge", carrier),
1310
1407
  findings: this.#findingsOf(carrier),
1311
- reviewsPath: this.resolveHandoffPath("review", type, reviewParams),
1408
+ reviewsPath: this.#reviewsPathOf(type, params, round),
1312
1409
  consecutiveS1: this.#consecutiveS1Run(type, params, round),
1313
1410
  };
1314
1411
  }
@@ -1328,7 +1425,7 @@ export class Ledger {
1328
1425
  // work plane reads its status) — the same `conclusionOf` single source (D27).
1329
1426
  status: this.#handoffSchema.conclusionOf(this.planeOf("fix"), fixCarrier),
1330
1427
  findings: this.#findingsOf(reviewCarrier),
1331
- reviewsPath: this.resolveHandoffPath("review", type, reviewParams),
1428
+ reviewsPath: this.#reviewsPathOf(type, params, round),
1332
1429
  consecutiveS1: this.#consecutiveS1Run(type, params, round),
1333
1430
  };
1334
1431
  }
@@ -134,15 +134,16 @@ export const NEXT_HOP_REASON = {
134
134
  /** The review-cycle soft-cap suggestion (the C5-0 suggestion face — user adjudicates). */
135
135
  export const SOFT_CAP_SUGGESTION = "BLOCKED: review-cycle-cap — user adjudicates";
136
136
  /** The fix-route readback suffix — appended verbatim to the fix findings path on the
137
- * route's `next:` render (`(confirm the reviews handoff · if a finding needs a
138
- * ruling, record the ruling in the handoff file)`), a pure wording prompt: the
139
- * anti-blind-fix mechanical guard is the ledger round / C5-1, the suffix only
140
- * reminds the orchestrator to confirm the captured findings and, when a finding
141
- * needs a user ruling, record that ruling back into the reviews handoff the fix
142
- * round consumes. `annotate` names the carrier action alone — distinct from
143
- * `backfill` (a durable fact landed into its owning doc), which stays the
144
- * ruling's destination when it asserts a project-level fact. */
145
- export const FIX_READBACK_SUFFIX = "(confirm the reviews handoff · if a finding needs a ruling, record the ruling in the handoff file)";
137
+ * route's `next:` render (`(confirm the reviews handoff · if a finding needs a ruling,
138
+ * record it beside that handoff — same path with .json replaced by .rulings.json)`), a
139
+ * pure wording prompt: the anti-blind-fix mechanical guard is the ledger round / C5-1,
140
+ * the suffix only reminds the orchestrator to confirm the captured findings and, when a
141
+ * finding needs a user ruling, to record it in the SIDECAR beside the reviews handoff
142
+ * (the carrier's bytes are frozen — the ruling never edits them; P31 §2.1/§2.5).
143
+ * `annotate` names the carrier action alone — distinct from `backfill` (a durable fact
144
+ * landed into its owning doc), which stays the ruling's destination when it asserts a
145
+ * project-level fact. */
146
+ export const FIX_READBACK_SUFFIX = "(confirm the reviews handoff · if a finding needs a ruling, record it beside that handoff — same path with .json replaced by .rulings.json)";
146
147
  /** The failure face — a BLOCKED/TIMEOUT round goes the stderr CDD_BLOCKED channel and
147
148
  * produces no `next:` line on any op. Exported as the ONE failure-status set: the
148
149
  * skill-anatomy contract's `edgeConditionWords` derivation reads it to exclude the
@@ -51,4 +51,19 @@ export class ReviewedIdentity {
51
51
  return "branch";
52
52
  return null;
53
53
  }
54
+ /** Whether one binding phase is gated by the round's own-bytes measurement
55
+ * (`touchedDoc`) — the second half of this file's one judgment: `legOf` says WHICH
56
+ * leg a completed round writes, this says whether that leg is CONDITIONAL.
57
+ *
58
+ * The split's ground is whether the phase is EXPECTED to rewrite the document it
59
+ * judges: a `fix` is (so an untouched claim keeps the old binding and the next
60
+ * review reports drift), a `review` / `branch-review` is not (its job is to
61
+ * conclude on existing bytes, so a completed conclusion binds them — otherwise
62
+ * every review leaves no trace and the line is dispatched forever). `implement`
63
+ * binds nothing (`legOf` answers null), so its answer never applies.
64
+ *
65
+ * Pure: it reads the phase and nothing else. */
66
+ static gatedByTouchedDoc(phase) {
67
+ return phase === "fix";
68
+ }
54
69
  }
@@ -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,20 @@ 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, but ONLY where the
536
+ // phase is expected to produce those bytes (P32 §2.1): a READABLE range that
537
+ // touched the document not at all (`false`) keeps the OLD binding on a `fix` round,
538
+ // so the existing drift / reopen face pushes the line back to review instead of
539
+ // silently closing it on bytes the round never delivered. A `review` /
540
+ // `branch-review` is not gated: its job is to conclude on bytes it does not write,
541
+ // and a completed conclusion must bind them or the drift identity never closes.
542
+ // WHICH phases are gated is the judgment's own cell
543
+ // (`ReviewedIdentity.gatedByTouchedDoc`), beside the leg decision; `true`, `null`
544
+ // (unmeasurable — its soft entry is booked above) and `undefined` (hermetic /
545
+ // injected dispatchers) keep today's bind.
546
+ const leg = record.verdict.targetAction &&
547
+ (!ReviewedIdentity.gatedByTouchedDoc(frame.phase) || outcome.touchedDoc !== false)
501
548
  ? ReviewedIdentity.legOf(frame.phase, frame.target.kind)
502
549
  : null;
503
550
  if (leg !== null) {
@@ -603,6 +650,15 @@ export class Lifecycle {
603
650
  #opOf(phase) {
604
651
  return phase === "branch-review" ? "review" : phase;
605
652
  }
653
+ /** 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; a round-less family
655
+ * (implement) resolves both to one path, so the seal is idempotent by construction. */
656
+ #sealRoundCarriers(frame) {
657
+ const op = this.#opOf(frame.phase);
658
+ const draftName = this.#ledger.handoffName(op, frame.type, frame.params);
659
+ CarrierSeal.seal(this.#ledger.handoffPath(op, frame.type, frame.params));
660
+ CarrierSeal.seal(this.#ledger.naming().finalPath(draftName, frame.params.round));
661
+ }
606
662
  // -------------------------------------------------------------------------
607
663
  // next routing + the capsule interaction
608
664
  // -------------------------------------------------------------------------
@@ -701,12 +757,15 @@ export class Lifecycle {
701
757
  const naming = this.#ledger.naming();
702
758
  // The failure face's handoff is the crash record — the engine's own postmortem
703
759
  // 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.
760
+ // round's handoff carrier path — the FINAL carrier the round wrote (P31 §2.3),
761
+ // resolved through the ledger's ONE read-name rule (the draft's family spelling is
762
+ // the fallback, never the cell's own derivation). The crash name derives from the
763
+ // frame through the ONE naming source (`RoundNaming`), the same name the lifecycle
764
+ // wrote it under.
706
765
  const crash = failure ? this.#ledger.readCrash(naming.crashName(frame)) : null;
707
766
  const handoff = crash !== null
708
767
  ? naming.crashPath(frame)
709
- : this.#ledger.handoffPath(op, frame.type, frame.params);
768
+ : this.#ledger.resolveHandoffPath(op, frame.type, frame.params);
710
769
  return this.#capsule.emit(outcome.status, handoff, hop, crash !== null, summary);
711
770
  }
712
771
  /** 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.8.0",
3
+ "version": "4.9.1",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {