@oscaner-skills/cdd-engine 4.10.0 → 4.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,6 +23,7 @@
23
23
  var _a;
24
24
  import { createHash } from "node:crypto";
25
25
  import { readdirSync, readFileSync } from "node:fs";
26
+ import { basename } from "node:path";
26
27
  import { DocBodyProjection } from "../contract/doc-body.js";
27
28
  import { CarrierSeal } from "../infra/carrier-seal.js";
28
29
  import { BriefRenderer } from "../render/brief.js";
@@ -33,6 +34,10 @@ import { LineIdentity } from "./line-identity.js";
33
34
  import { NextStepRouter } from "./next.js";
34
35
  import { RoundNaming } from "./round-naming.js";
35
36
  import { EMPTY_RUN_STATE } from "./run.js";
37
+ /** The cause a declared BLOCKED / TIMEOUT round books on the entry it synthesizes when
38
+ * it authored NO fact of its own — the round's own conclusion (`round-blocked`),
39
+ * never `contract-violation`: nothing about the record broke (P34 T5). */
40
+ export const CONCLUDED_BLOCKED_CAUSE = "round-blocked";
36
41
  /** The graded-violation literals' ONE construction point — the cause vocabulary is
37
42
  * a declared convergence point, so its shape is held here rather than copied per
38
43
  * call site. `cause` defaults to `contract-violation`, the ledger's existing row
@@ -107,9 +112,29 @@ export class RoundRecords {
107
112
  dispatchBase: null,
108
113
  verdict: { treeClean: true, targetAction: true },
109
114
  violations: [],
110
- carrierPath: null,
111
115
  };
112
116
  }
117
+ /** Whether a record OWNS its carrier path (spec §2.7) — no other record of the same
118
+ * line sits on that path with a larger `(cycle, attempt)`. New records are each
119
+ * their own owner (their names are unique by identity), so the judgment only
120
+ * discriminates LEGACY rows: a row whose carrier path was overwritten by a later
121
+ * round is present facts, never a mismatch (the engine cannot tell a lawful
122
+ * overwrite from a tamper). The path comes in as a projection — the record's own
123
+ * identity, never a stored cell (`RoundRecords` has no workspace to resolve a
124
+ * name). */
125
+ static ownerOf(records, record, pathOf) {
126
+ const path = pathOf(record);
127
+ if (path === "")
128
+ return false;
129
+ return !records.some((other) => RoundRecords.#laterRound(other, record) && pathOf(other) === path);
130
+ }
131
+ /** Whether `other` is the later round of the two — `(cycle, attempt)` order, the
132
+ * round identity's own sequence. Identical identities are not later. */
133
+ static #laterRound(other, record) {
134
+ return other.cycle === record.cycle
135
+ ? other.attempt > record.attempt
136
+ : other.cycle > record.cycle;
137
+ }
113
138
  /** The op a recorded mode key belongs to — branch-review rides the review family;
114
139
  * an unknown mode key reads null (a hand-written row is not a round record). */
115
140
  static opOf(mode) {
@@ -192,7 +217,8 @@ export class ReviewRefs {
192
217
  export class Ledger {
193
218
  /** The one dispatch workspace this ledger records. */
194
219
  #workspace;
195
- /** The handoff-family records, keyed by `op.type` — the naming truth the ledger fills. */
220
+ /** The handoff-family key set, keyed by `op.type` — the loud unknown-family check's
221
+ * input (the file names are the naming face's one mint, never a table here). */
196
222
  #families;
197
223
  /** The C5 next router — the closure-side judge of the round carriers (stateless;
198
224
  * the `closedWaves()` read face and the wave gate share the same router). */
@@ -215,12 +241,19 @@ export class Ledger {
215
241
  * dispatch input (a backfill touching other tasks, or a Constraints reword, must
216
242
  * not void a reviewed wave). */
217
243
  #brief = new BriefRenderer();
244
+ /** The plan read seam (D30) — the reviewed brief's ONLY read of `reviewed.plan`:
245
+ * the drift judgment re-reads the path the round recorded, through the same
246
+ * per-command `PlanSource` the dispatch read its plan through. The ledger itself
247
+ * never opens a file for the brief, so the observation face can never make the
248
+ * hash subject drift. */
249
+ #plan;
218
250
  /** The round-naming single source over this ledger's workspace — the crash
219
251
  * artifact names derive here (zero second derivation). */
220
252
  #naming;
221
- constructor(workspace, config) {
253
+ constructor(workspace, config, plan) {
222
254
  this.#workspace = workspace;
223
255
  this.#families = config.handoffNamespace().families;
256
+ this.#plan = plan;
224
257
  this.#naming = new RoundNaming(workspace);
225
258
  }
226
259
  /** The review-reference face — the refKind three-type derivation + binding (T25). */
@@ -387,12 +420,10 @@ export class Ledger {
387
420
  dispatchBase: init.dispatchBase ?? null,
388
421
  verdict: init.verdict ?? { treeClean: true, targetAction: true },
389
422
  violations: init.violations ?? [],
390
- carrierPath: init.carrierPath ?? null,
391
423
  // 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).
424
+ // keeps no key at all — the read then compares nothing, zero migration). The
425
+ // carrier PATH is never written (spec §2.10): it is derived from this identity.
393
426
  ...(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 }),
396
427
  };
397
428
  const existing = records.findIndex((candidate) => candidate.op === record.op &&
398
429
  candidate.cycle === record.cycle &&
@@ -426,6 +457,22 @@ export class Ledger {
426
457
  row.reviewedRevision = revision;
427
458
  this.writeProgress(data);
428
459
  }
460
+ /** Record a branch line's reviewed PLAN revision (P21 §4.1) — the plan
461
+ * document's body revision as the round LEFT it. The read rides the ledger's own
462
+ * `PlanSource` (the ONE plan read point), so a round that edited its plan binds the
463
+ * edited bytes — never the dispatch-time snapshot — while a non-ready read records
464
+ * nothing (present facts only, the symmetric failure face to `recordReviewedBrief`).
465
+ * The recorded path is normalized HERE, not by the caller (the same discipline
466
+ * `#briefRevision` keeps): the drift comparator relativizes only its current side,
467
+ * so an absolute argv-erasure shape handed in by a future caller would otherwise
468
+ * read as a false drift. */
469
+ recordReviewedPlanRevision(key, planPath, identity) {
470
+ const read = this.#plan.readPath(planPath);
471
+ const text = read.text();
472
+ if (text === null)
473
+ return;
474
+ this.recordReviewedRevision(key, this.#refs.docRevision(this.#rel(planPath), text), identity);
475
+ }
429
476
  /** Record a wave line's reviewed BRIEF revision (D30) — the hash of the wave's
430
477
  * TASK-ONLY projection (P29 §2.2: the task sections, `## Constraints` excluded).
431
478
  * A backfill touching OTHER tasks leaves this projection byte-identical, and so
@@ -439,14 +486,21 @@ export class Ledger {
439
486
  /** The wave line's reviewed-basis revision (D30) — the hash of the wave's TASK-ONLY
440
487
  * projection (`BriefRenderer#taskBody`: the task sections, `## Constraints`
441
488
  * excluded — P29 §2.2). The `plan` layer is the plan the brief renders from, the
442
- * `brief_hash` layer the projection's own digest. Null when the plan is unreadable
443
- * or a requested task is absent (present facts only). */
489
+ * `brief_hash` layer the projection's own digest. The read rides the injected
490
+ * `PlanSource` (the ONE plan read seam), so a non-ready read — an unreadable plan,
491
+ * a grammar break — records nothing. Null when the plan is unreadable or a
492
+ * requested task is absent (present facts only). */
444
493
  #briefRevision(waveKey, planPath) {
494
+ const read = this.#plan.readPath(planPath);
495
+ const text = read.text();
496
+ const doc = read.doc();
497
+ if (text === null || doc === null)
498
+ return null;
445
499
  try {
446
500
  const tasks = waveKey.split(",").map((part) => Number(part));
501
+ const brief = this.#brief.taskBody(text, doc, tasks);
447
502
  // The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
448
- // every persisted path field; the read erases to absolute at the syscall edge.
449
- const brief = this.#brief.taskBody(readFileSync(this.#abs(planPath), "utf8"), tasks);
503
+ // every persisted path field.
450
504
  return this.#refs.briefRevision(this.#rel(planPath), brief);
451
505
  }
452
506
  catch {
@@ -1039,13 +1093,13 @@ export class Ledger {
1039
1093
  // -------------------------------------------------------------------------
1040
1094
  // handoff — naming / carrier / single-author persist
1041
1095
  // -------------------------------------------------------------------------
1042
- /** The family record of an op/type pair — the engine-config handoff namespace data
1043
- * (loud on an unknown family: the naming table is the single truth, never a second list). */
1096
+ /** The family key check of an op/type pair — the engine-config handoff namespace data
1097
+ * (loud on an unknown family: the key set is the resolution truth, never a second list;
1098
+ * the NAME is the naming face's one mint). */
1044
1099
  #family(op, type) {
1045
- const family = this.#families[`${op}.${type}`];
1046
- if (family === undefined)
1100
+ if (!this.#families.includes(`${op}.${type}`)) {
1047
1101
  throw new Error(`unknown handoff family: ${op}.${type}`);
1048
- return family;
1102
+ }
1049
1103
  }
1050
1104
  /** The carrier PLANE of an op — the ONE op-derived derivation (`HandoffSchema.planeOf`).
1051
1105
  * The plane-aware read/write/bookkeep spine: a judge-plane round (review) rides the
@@ -1054,11 +1108,20 @@ export class Ledger {
1054
1108
  planeOf(op) {
1055
1109
  return HandoffSchema.planeOf(op);
1056
1110
  }
1057
- /** The canonical handoff file name — the family's `{placeholder}` pattern, filled. */
1111
+ /** The canonical handoff file name — the round identity's DRAFT, rendered by the
1112
+ * ONE naming rule (`RoundNaming#renderName`). The family key set still guards the
1113
+ * op/type pairs (a loud unknown-family throw), but it spells no name: the renderer
1114
+ * does, so the draft, its final, the report, the log and the crash record cannot
1115
+ * drift apart. */
1058
1116
  handoffName(op, type, params = {}) {
1059
- return this.#family(op, type)
1060
- .name.replaceAll("{tasks}", params.tasks ?? "")
1061
- .replaceAll("{round}", String(params.round ?? ""));
1117
+ this.#family(op, type);
1118
+ return RoundNaming.renderName(_a.#artifactOf(op, type, params), "draft");
1119
+ }
1120
+ /** The identity of one (op, type, params) triple — the ONE adapter from the
1121
+ * params-carrying surface onto the naming renderer. */
1122
+ static #artifactOf(op, type, params) {
1123
+ const artifactOp = (RoundRecords.opOf(op) ?? op);
1124
+ return RoundNaming.artifactOf(artifactOp, type, params);
1062
1125
  }
1063
1126
  /** The canonical on-disk handoff path. */
1064
1127
  handoffPath(op, type, params = {}) {
@@ -1071,9 +1134,9 @@ export class Ledger {
1071
1134
  return carrier;
1072
1135
  }
1073
1136
  /** 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.
1137
+ * write, at a name the child's DRAFT never occupies (P31 §2.3). Writes the final,
1138
+ * seals the draft + final pair, returns the payload digest the record remembers — the
1139
+ * record names neither path, it derives both from its own identity.
1077
1140
  *
1078
1141
  * The digest covers the PAYLOAD, never the file bytes that hold it: `H = sha256(JSON
1079
1142
  * containing H)` is unsatisfiable, so the value is taken BEFORE the `contentSha256`
@@ -1085,16 +1148,17 @@ export class Ledger {
1085
1148
  * P31 §2.4 — the write CLOSES the carrier: the final and the draft name beside it
1086
1149
  * land at `0o444` in the same step, so a carrier is read-only from the instant the
1087
1150
  * 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
1151
+ * a legacy cycle-less name whose draft IS the final) is not an error — the seal is
1089
1152
  * idempotent and absence is the round's own fact. */
1090
1153
  persistHandoff(op, type, params, data) {
1091
- const draftName = this.handoffName(op, type, params);
1154
+ const artifact = _a.#artifactOf(op, type, params);
1155
+ const draftName = RoundNaming.renderName(artifact, "draft");
1092
1156
  const payload = { ...data };
1093
1157
  // The engine owns this key — a caller-supplied value never seeds a self-covering digest.
1094
1158
  delete payload.contentSha256;
1095
1159
  const digest = CarrierIntegrity.digestOf(payload);
1096
1160
  payload.contentSha256 = digest;
1097
- const finalName = this.#naming.finalName(draftName, params.round);
1161
+ const finalName = RoundNaming.renderName(artifact, "final");
1098
1162
  this.#persist(finalName, payload);
1099
1163
  // The carrier is read-only the moment it exists; the draft beside it closes with it.
1100
1164
  CarrierSeal.seal(this.#workspace.resolve(finalName));
@@ -1115,20 +1179,55 @@ export class Ledger {
1115
1179
  * shapes; it is READ-ONLY (every write goes through `persistHandoff`'s canonical
1116
1180
  * spelling). */
1117
1181
  resolveHandoffName(op, type, params = {}) {
1118
- const canonical = this.handoffName(op, type, params);
1182
+ // The attempt the read resolves is the round's LATEST recorded one unless the
1183
+ // caller names it: a re-dispatched review lands at `-a{n}`, and its fix leg only
1184
+ // knows the cycle. Without this the read would address attempt 1's name (or its
1185
+ // final) while the digest gate compares the latest attempt's — a false mismatch.
1186
+ const resolved = this.#attemptAware(op, type, params);
1187
+ const canonical = this.handoffName(op, type, resolved);
1119
1188
  // P31 §2.3 — the FINAL carrier wins the read whenever the round has one: it is the
1120
1189
  // 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);
1190
+ // un-materialized payload whose findings carry no engine id).
1191
+ const final = RoundNaming.renderName(_a.#artifactOf(op, type, resolved), "final");
1124
1192
  if (final !== canonical && this.#read(final) !== null)
1125
1193
  return final;
1126
- if (!RETIRED_SPEC_LINE_KEYS.has(type) || this.#read(canonical) !== null) {
1127
- return canonical;
1194
+ if (!RETIRED_SPEC_LINE_KEYS.has(type)) {
1195
+ return this.#legacyCarrierName(op, type, resolved) ?? canonical;
1128
1196
  }
1197
+ if (this.#read(canonical) !== null)
1198
+ return canonical;
1129
1199
  const retired = _a.#retiredCarrierName(op, params);
1130
1200
  return this.#read(retired) === null ? canonical : retired;
1131
1201
  }
1202
+ /** The pre-P34 cycle-less spelling of the round's own family name — the ONE carrier
1203
+ * the P34 respelling moved (`tasks-{tasks}-implement.json` → `…-implement-{cycle}.json`),
1204
+ * so a folded legacy record (no recorded path, no digest) still resolves its own
1205
+ * bytes instead of reading as absent while the orphan scan still claims the file.
1206
+ * The rung is READ-ONLY and cycle-1 · attempt-1 alone: the legacy spelling carried
1207
+ * neither coordinate, so no later cycle or attempt may read it. null when the op is
1208
+ * not an implement, the round is past its first cycle/attempt, the family does not
1209
+ * exist, the legacy name IS the canonical one, or the file is absent. */
1210
+ #legacyCarrierName(op, type, params) {
1211
+ if (RoundRecords.opOf(op) !== "implement")
1212
+ return null;
1213
+ if ((params.round ?? 1) !== 1 || (params.attempt ?? 1) !== 1)
1214
+ return null;
1215
+ if (!this.#families.includes(`${op}.${type}`))
1216
+ return null;
1217
+ const legacy = this.handoffName(op, type, { tasks: params.tasks });
1218
+ if (legacy === this.handoffName(op, type, params))
1219
+ return null;
1220
+ return this.#read(legacy) === null ? null : legacy;
1221
+ }
1222
+ /** The params one READ resolves under — the caller's attempt when it names one, else
1223
+ * the round's latest recorded attempt (a fix leg knows the cycle, not the review's
1224
+ * attempt). Absent records leave the params untouched (the present-facts face). */
1225
+ #attemptAware(op, type, params) {
1226
+ if (params.attempt !== undefined)
1227
+ return params;
1228
+ const latest = this.#latestRecordOf(op, type, params)?.attempt;
1229
+ return latest === undefined ? params : { ...params, attempt: latest };
1230
+ }
1132
1231
  /** The resolved handoff path — `resolveHandoffName`'s on-disk form (the read face's
1133
1232
  * single path exit; the writers keep `handoffPath`). */
1134
1233
  resolveHandoffPath(op, type, params = {}) {
@@ -1169,27 +1268,63 @@ export class Ledger {
1169
1268
  return this.#latestRecordOf(op, type, params)?.carrierDigest ?? null;
1170
1269
  }
1171
1270
  /** 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). */
1271
+ * carries no record for it (a legacy row, or a round never dispatched). When the
1272
+ * caller NAMES an attempt (`params.attempt`), that attempt is the one selected: the
1273
+ * name a read resolves and the digest it compares against come from the SAME record,
1274
+ * so a re-dispatched cycle (attempt 2 booked, attempt 1's final still on disk by
1275
+ * conservation) can never read attempt 1's bytes against attempt 2's digest. */
1175
1276
  #latestRecordOf(op, type, params) {
1176
1277
  const mode = RoundRecords.opOf(op) ?? op;
1177
1278
  const round = params.round === undefined ? null : Number(params.round);
1178
1279
  return this.recordsOf(this.#roundKey(type, params), type)
1179
1280
  .filter((record) => record.op === mode)
1180
1281
  .filter((record) => round === null || record.cycle === round)
1282
+ .filter((record) => params.attempt === undefined || record.attempt === params.attempt)
1181
1283
  .reduce((newest, record) => (newest === null || record.attempt >= newest.attempt ? record : newest), null);
1182
1284
  }
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. */
1285
+ /** The review carrier a round's fix leg reads as `--reviews` — the same-cycle review
1286
+ * record's own carrier identity through the ONE accessor (step ① the recorded path,
1287
+ * step ②③ the read ladder a pre-P31 row needs). A record that resolves no carrier
1288
+ * (the ladder's candidates are all absent) reads `""` — the soft `unrecorded` face,
1289
+ * never a fabricated name. No record at all falls back to the family name of the
1290
+ * cycle's latest review attempt (attempt 1 when none): a fix leg knows the cycle,
1291
+ * never the review's attempt, so the FRAME's attempt is deliberately not inherited. */
1188
1292
  #reviewsPathOf(type, params, round) {
1189
- const recorded = this.#latestRecordOf("review", type, { ...params, round })?.carrierPath;
1293
+ const reviewParams = { tasks: params.tasks, round };
1294
+ const record = this.#latestRecordOf("review", type, reviewParams);
1295
+ if (record === null)
1296
+ return this.resolveHandoffPath("review", type, reviewParams);
1297
+ return this.carrierPathOf(type, String(this.#roundKey(type, params)), record);
1298
+ }
1299
+ /** One record's carrier PATH — the ONE read face of a record's carrier identity
1300
+ * (spec §2.10), so no consumer spells `record.carrierPath` itself. Step ① returns the
1301
+ * path the record already remembers (the historical fact — a pre-P34 row keeps its
1302
+ * own spelling, zero migration). Step ② otherwise resolves the read ladder
1303
+ * `resolveHandoffName` owns, seeded with the record's FULL identity (line · op ·
1304
+ * cycle · attempt) — a bare `renderPath("final")` would miss a pre-P31 row that never
1305
+ * minted the `.c{cycle}` spelling. Step ③ probes the ladder's answer: a ladder that
1306
+ * reports a never-minted name reads as "no carrier" (empty), never as a path. */
1307
+ carrierPathOf(type, key, record) {
1308
+ const recorded = record.carrierPath;
1190
1309
  if (typeof recorded === "string" && recorded !== "")
1191
1310
  return recorded;
1192
- return this.resolveHandoffPath("review", type, { ...params, round });
1311
+ const name = this.#resolvedCarrierName(type, key, record);
1312
+ return this.#read(name) === null ? "" : this.#workspace.resolve(name);
1313
+ }
1314
+ /** Step ② of `carrierPathOf` — the NAME the record's identity resolves to: the
1315
+ * retired `spec-{op}-{round}.json` spelling for a migrated row (its `spec` family is
1316
+ * not in the live config table, so the ladder would throw), the read ladder's answer
1317
+ * for every live line. */
1318
+ #resolvedCarrierName(type, key, record) {
1319
+ if (key === RETIRED_SPEC_KEY) {
1320
+ return _a.#retiredCarrierName(record.op, { round: record.cycle });
1321
+ }
1322
+ const params = {
1323
+ tasks: type === "wave" ? key : undefined,
1324
+ round: record.cycle,
1325
+ attempt: record.attempt,
1326
+ };
1327
+ return this.resolveHandoffName(record.op, type, params);
1193
1328
  }
1194
1329
  /** The retired document-line carrier name of one round — `spec-review-{round}.json` /
1195
1330
  * `spec-fix-{round}.json`. It lives here, never in the family table: it is a read
@@ -1197,31 +1332,53 @@ export class Ledger {
1197
1332
  static #retiredCarrierName(op, params) {
1198
1333
  return `${RETIRED_SPEC_KEY}-${op}-${params.round ?? ""}.json`;
1199
1334
  }
1200
- /** The workspace's ORPHAN handoff drafts — the `handoff` family files whose
1201
- * (line key, op, round) never landed in `progress.json` (a draft written by a
1202
- * round that never booked). The board and the `--dry-run` preview render them;
1203
- * this is a PURE READ — the engine never writes, moves or deletes a draft. The
1204
- * family names are the ledger's own single naming truth (no second pattern), and
1205
- * the owning row is read through the ONE basis `rowFor` establishes — the draft's
1206
- * own line word IS its declaration — so a migrated workspace's carrier resolves
1207
- * its retired row instead of reading as an orphan. */
1335
+ /** The workspace's ORPHAN handoff files — the carrier files (draft or final) whose
1336
+ * (line key, op, cycle, attempt) never landed in `progress.json`. The board and the
1337
+ * `--dry-run` preview render them; this is a PURE READ — the engine never writes,
1338
+ * moves or deletes a carrier. The family names are the ledger's own single naming
1339
+ * truth (no second pattern), and the owning row is read through the ONE basis
1340
+ * `rowFor` establishes — the file's own line word IS its declaration — so a
1341
+ * migrated workspace's carrier resolves its live row instead of reading as an
1342
+ * orphan.
1343
+ *
1344
+ * OWNERSHIP IS THE RECORD, NEVER ITS VERDICT (spec §2.12): a round that acted and
1345
+ * then failed still owns the file it wrote — completion is the judgment face, and
1346
+ * reading it here would relabel an honest failure's carrier as an orphan and hand it
1347
+ * to a recovery pass that deletes child work.
1348
+ *
1349
+ * The identity is the fast tier; the LEGACY tier compares the record's own carrier
1350
+ * path by basename (a pre-P34 row remembers an absolute path while the scan yields a
1351
+ * bare name), read once through `carrierPathOf` — the only accessor of the record's
1352
+ * carrier identity. */
1208
1353
  orphanHandoffs() {
1209
1354
  const progress = this.readProgress() ?? this.emptyProgress();
1210
1355
  const orphans = [];
1211
1356
  for (const name of this.#workspaceFiles()) {
1212
- const owner = _a.#handoffOwner(name, this.#families);
1357
+ const owner = _a.#handoffOwner(name);
1213
1358
  if (owner === null)
1214
1359
  continue;
1215
- const row = _a.rowFor(progress, owner.key, _a.#lineWord(owner.key));
1216
- const completed = RoundRecords.of(row)
1217
- .filter((record) => record.verdict.targetAction)
1218
- .map((record) => `${record.op}:${record.cycle}`);
1219
- if (!completed.includes(`${RoundRecords.opOf(owner.op) ?? owner.op}:${owner.round}`)) {
1360
+ const records = RoundRecords.of(_a.#ownerRow(progress, owner.key));
1361
+ const identity = `${owner.op}:${owner.round}:${owner.attempt}`;
1362
+ const claimed = records.some((record) => `${record.op}:${record.cycle}:${record.attempt}` === identity ||
1363
+ basename(this.carrierPathOf(owner.type, owner.key, record)) === name);
1364
+ if (!claimed)
1220
1365
  orphans.push(name);
1221
- }
1222
1366
  }
1223
1367
  return orphans.sort();
1224
1368
  }
1369
+ /** The row one carrier file's line word resolves to. The retired `spec` twin is a FILE
1370
+ * NAME a live row already outlived: the workspace holds ONE identity document, so the
1371
+ * word resolves onto whichever document word that row now declares (`phase-spec` /
1372
+ * `overall` / `single-spec`), never onto a row name the migration retired. Every other
1373
+ * word — a wave's tasks, `plan`, `branch` — reads through `rowFor`'s ONE basis. */
1374
+ static #ownerRow(progress, key) {
1375
+ if (key !== RETIRED_SPEC_KEY)
1376
+ return _a.rowFor(progress, key, _a.#lineWord(key));
1377
+ const literal = _a.rowFor(progress, key, null);
1378
+ if (literal !== undefined)
1379
+ return literal;
1380
+ return progress.waves.find((row) => RETIRED_SPEC_LINE_KEYS.has(row.wave));
1381
+ }
1225
1382
  /** A handoff file's key as a declared line word — the three document words declare
1226
1383
  * themselves; every other key (a wave's tasks, `plan`, `branch`) declares nothing
1227
1384
  * and reads literally. */
@@ -1240,51 +1397,54 @@ export class Ledger {
1240
1397
  return [];
1241
1398
  }
1242
1399
  }
1243
- /** Which recorded round one handoff file belongs to — the family name pattern is
1244
- * the ONE naming truth, read backwards: `tasks-{tasks}-{op}[-{round}].json` /
1245
- * `{line}-{op}-{round}.json`, plus a document line's retired `spec` twin (the
1246
- * pre-rename name a still-unbooked draft can carry). Null for a non-handoff file. */
1247
- static #handoffOwner(name, families) {
1400
+ /** Which recorded round one handoff file belongs to — the ONE renderer read
1401
+ * backwards: `<line>-<op>[-<cycle>][-a<attempt>][.c<cycle>].json`, the retired
1402
+ * document-line `spec` twin included (a still-unbooked draft can carry it). The
1403
+ * parse yields the same four coordinates the naming face renders, so the orphan
1404
+ * test compares an identity with an identity — never a spelling with a spelling.
1405
+ * Null for a non-carrier file. */
1406
+ static #handoffOwner(name) {
1248
1407
  // A FINAL carrier (`<stem>.c{round}.json`, P31 §2.3) is the same artifact as its
1249
1408
  // draft — the cycle is the name's own suffix, never a second family.
1250
1409
  const draft = name.replace(/\.c\d+\.json$/, ".json");
1251
- for (const [family, record] of Object.entries(families)) {
1252
- const [op = "", type = ""] = family.split(".");
1253
- for (const spelling of _a.#familySpellings(record.name, type)) {
1254
- const captures = _a.#familyCaptures(spelling, draft);
1255
- if (captures === null)
1256
- continue;
1257
- const key = type === "wave" ? (captures.tasks ?? "") : type;
1258
- // Each family carries the placeholder IT declares: a wave's review/fix name
1259
- // carries `{tasks}` AND `{round}`, a document / branch line carries `{round}`
1260
- // alone, and the fixed implement family carries `{tasks}` alone (round 1).
1261
- const round = captures.round === null ? 1 : Number(captures.round);
1262
- return { key, op, round };
1263
- }
1410
+ const wave = _a.#WAVE_CARRIER.exec(draft);
1411
+ if (wave !== null) {
1412
+ const [, line = "", op = "", cycle, attempt] = wave;
1413
+ // The wave row keys the task GROUP alone — the `tasks-` spine is the name's, not
1414
+ // the key's. The legacy cycle-less implement spelling is the fixed family's round 1.
1415
+ return {
1416
+ type: "wave",
1417
+ key: line.replace(/^tasks-/, ""),
1418
+ op,
1419
+ round: cycle === undefined ? 1 : Number(cycle),
1420
+ attempt: _a.#attemptOf(attempt),
1421
+ };
1422
+ }
1423
+ const line = _a.#LINE_CARRIER.exec(draft);
1424
+ if (line !== null) {
1425
+ const [, key = "", op = "", cycle = "", attempt] = line;
1426
+ return {
1427
+ type: key,
1428
+ key,
1429
+ op,
1430
+ round: Number(cycle),
1431
+ attempt: _a.#attemptOf(attempt),
1432
+ };
1264
1433
  }
1265
1434
  return null;
1266
1435
  }
1267
- /** The name spellings one family answers to — its canonical pattern, and for a
1268
- * document line the retired `spec` twin it was minted under before the rename. */
1269
- static #familySpellings(name, type) {
1270
- if (!RETIRED_SPEC_LINE_KEYS.has(type))
1271
- return [name];
1272
- return [name, name.replace(`${type}-`, `${RETIRED_SPEC_KEY}-`)];
1273
- }
1274
- /** One family spelling matched against a file name — the `{tasks}` / `{round}`
1275
- * tokens read backwards as NAMED captures, so a family's round is read from the
1276
- * group its own name actually carries (a document family's sole group is the
1277
- * round; `tasks-{tasks}-implement.json`'s is the task list, never a round). A
1278
- * positional read would resolve every `{round}`-only family to 1. */
1279
- static #familyCaptures(spelling, name) {
1280
- const escaped = spelling.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
1281
- const pattern = new RegExp(`^${escaped
1282
- .replace("\\{tasks\\}", "(?<tasks>.+?)")
1283
- .replace("\\{round\\}", "(?<round>\\d+)")}$`);
1284
- const match = pattern.exec(name);
1285
- if (match === null)
1286
- return null;
1287
- return { tasks: match.groups?.tasks ?? null, round: match.groups?.round ?? null };
1436
+ /** The wave line's carrier spelling, read backwards — the task key is a lazy span,
1437
+ * the op one of the three words, the cycle and the attempt optional (the legacy
1438
+ * cycle-less implement name harvests no cycle). */
1439
+ static #WAVE_CARRIER = /^(tasks-.+?)-(implement|review|fix)(?:-(\d+))?(?:-a(\d+))?\.json$/;
1440
+ /** The single-target lines' carrier spelling — `branch` and the doc words (the
1441
+ * words of the ONE target-face table, the retired `spec` twin included), every one
1442
+ * of which carries its cycle. */
1443
+ static #LINE_CARRIER = new RegExp(`^(${[...Object.keys(targetFaces).filter((word) => word !== "wave"), RETIRED_SPEC_KEY].join("|")})-(review|fix)-(\\d+)(?:-a(\\d+))?\\.json$`);
1444
+ /** An absent attempt segment is the first attempt — the naming face never renders
1445
+ * `-a1`, so the parse and the render agree on the identity of attempt 1. */
1446
+ static #attemptOf(captured) {
1447
+ return captured === undefined ? 1 : Number(captured);
1288
1448
  }
1289
1449
  // -------------------------------------------------------------------------
1290
1450
  // crash — the lane crash → recovery record
@@ -1337,7 +1497,10 @@ export class Ledger {
1337
1497
  #consecutiveS1Run(type, params, round) {
1338
1498
  let run = 0;
1339
1499
  for (let index = round; index >= 1; index--) {
1340
- const carrier = this.readHandoff("review", type, { ...params, round: index });
1500
+ // The frame's attempt belongs to the op it was allocated for — a review read
1501
+ // resolves the review's own latest attempt (the ledger's own fallback), never
1502
+ // the fix frame's.
1503
+ const carrier = this.readHandoff("review", type, { tasks: params.tasks, round: index });
1341
1504
  if (carrier === null)
1342
1505
  break;
1343
1506
  if (this.#blockerCountOf(carrier) === 0)
@@ -1393,8 +1556,11 @@ export class Ledger {
1393
1556
  consecutiveS1: 0,
1394
1557
  };
1395
1558
  }
1559
+ // The review side is addressed by the CYCLE alone: an attempt belongs to the op it
1560
+ // was allocated for, so a fix at attempt 2 must never address the review's `-a2`
1561
+ // (the read's own attempt fallback resolves the review's latest recorded one).
1562
+ const reviewParams = { tasks: params.tasks, round };
1396
1563
  if (op === "review") {
1397
- const reviewParams = { ...params, round };
1398
1564
  const carrier = this.readHandoff("review", type, reviewParams);
1399
1565
  if (carrier === null)
1400
1566
  return null;
@@ -1405,8 +1571,8 @@ export class Ledger {
1405
1571
  // source shared with the fix leg below (`HandoffSchema.conclusionOf`).
1406
1572
  status: this.#handoffSchema.conclusionOf("judge", carrier),
1407
1573
  findings: this.#findingsOf(carrier),
1408
- reviewsPath: this.#reviewsPathOf(type, params, round),
1409
- consecutiveS1: this.#consecutiveS1Run(type, params, round),
1574
+ reviewsPath: this.#reviewsPathOf(type, reviewParams, round),
1575
+ consecutiveS1: this.#consecutiveS1Run(type, reviewParams, round),
1410
1576
  };
1411
1577
  }
1412
1578
  // op === "fix" — the C5-1 fingerprint: the fix round judges the source review's input
@@ -1414,9 +1580,8 @@ export class Ledger {
1414
1580
  // matching the review branch's contract: a fix whose blocker set was never read must
1415
1581
  // not be judged a clean zero-findings round — the next-hop derivation cannot close a
1416
1582
  // line it could not read.
1417
- const reviewParams = { ...params, round };
1418
1583
  const reviewCarrier = this.readHandoff("review", type, reviewParams);
1419
- const fixCarrier = this.readHandoff("fix", type, reviewParams);
1584
+ const fixCarrier = this.readHandoff("fix", type, { ...params, round });
1420
1585
  if (reviewCarrier === null || fixCarrier === null)
1421
1586
  return null;
1422
1587
  return {
@@ -1425,8 +1590,8 @@ export class Ledger {
1425
1590
  // work plane reads its status) — the same `conclusionOf` single source (D27).
1426
1591
  status: this.#handoffSchema.conclusionOf(this.planeOf("fix"), fixCarrier),
1427
1592
  findings: this.#findingsOf(reviewCarrier),
1428
- reviewsPath: this.#reviewsPathOf(type, params, round),
1429
- consecutiveS1: this.#consecutiveS1Run(type, params, round),
1593
+ reviewsPath: this.#reviewsPathOf(type, reviewParams, round),
1594
+ consecutiveS1: this.#consecutiveS1Run(type, reviewParams, round),
1430
1595
  };
1431
1596
  }
1432
1597
  }
@@ -12,7 +12,7 @@
12
12
  //
13
13
  // Constructed with the node's `Ledger` (the `Ledger` / `Lifecycle` shape: one read
14
14
  // face injected, no global state). The plan is never read here — the guarded plan
15
- // read stays on the board side and rides in as `planGraph`, so this module holds
15
+ // read stays on the board side and rides in as `plan`, so this module holds
16
16
  // zero file-system read and no second plan parse.
17
17
  //
18
18
  // The four rules over the ONE `PIPELINE_FACES` order:
@@ -172,7 +172,7 @@ export class PipelineFrontier {
172
172
  * alone would fall into rule 2 and render the wave face's own exit
173
173
  * (`PIPELINE_NEXT.wave`), a worse literal than the one being removed. */
174
174
  #waveState(input) {
175
- const graph = input.planGraph;
175
+ const graph = input.plan.graph();
176
176
  const waveKey = graph === null ? null : this.#waveKeyOf(graph);
177
177
  const entered = graph !== null && this.#wavesEntered(graph);
178
178
  return {