@oscaner-skills/cdd-engine 4.11.0 → 4.13.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.
@@ -22,7 +22,7 @@
22
22
  // carrying bare functions (the plan's zero-bare-function discipline).
23
23
  var _a;
24
24
  import { createHash } from "node:crypto";
25
- import { readdirSync, readFileSync } from "node:fs";
25
+ import { readFileSync } from "node:fs";
26
26
  import { basename } from "node:path";
27
27
  import { DocBodyProjection } from "../contract/doc-body.js";
28
28
  import { CarrierSeal } from "../infra/carrier-seal.js";
@@ -32,6 +32,7 @@ import { targetFaces } from "./faces.js";
32
32
  import { HandoffSchema } from "./handoff-schema.js";
33
33
  import { LineIdentity } from "./line-identity.js";
34
34
  import { NextStepRouter } from "./next.js";
35
+ import { ArtifactRegistry, roundIdentityKey } from "./round-artifacts.js";
35
36
  import { RoundNaming } from "./round-naming.js";
36
37
  import { EMPTY_RUN_STATE } from "./run.js";
37
38
  /** The cause a declared BLOCKED / TIMEOUT round books on the entry it synthesizes when
@@ -147,21 +148,6 @@ export class RoundRecords {
147
148
  return Array.from({ length: count }, (_unused, index) => index + 1);
148
149
  }
149
150
  }
150
- /** The retired phase-spec row key — the spelling the round records carried before the
151
- * target vocabulary unified on `phase-spec` (P22 D73). Rows already on disk keep it
152
- * byte-frozen; the row read normalizes it (see `Ledger.rowFor`). */
153
- const RETIRED_SPEC_KEY = "spec";
154
- /** The identity-DOCUMENT line words a retired `spec` row may belong to — the words a
155
- * workspace's document line keys under after the vocabulary unification. A workspace
156
- * holds at most ONE identity document, so a retired `spec` row is exactly that
157
- * document's line: `phase-spec` (the pre-rename default), a charter's `overall`, or a
158
- * standalone `single-spec`. The plan line carried `plan` before the rename too and
159
- * never lived under `spec`, so it stays out. */
160
- const RETIRED_SPEC_LINE_KEYS = new Set([
161
- "phase-spec",
162
- "overall",
163
- "single-spec",
164
- ]);
165
151
  /**
166
152
  * ReviewRefs — the review-reference face (T25): the two-layer bindings (`docRevision`
167
153
  * — the doc hash from its content · `briefRevision` — the wave's task-only projection
@@ -221,8 +207,13 @@ export class Ledger {
221
207
  * input (the file names are the naming face's one mint, never a table here). */
222
208
  #families;
223
209
  /** The C5 next router — the closure-side judge of the round carriers (stateless;
224
- * the `closedWaves()` read face and the wave gate share the same router). */
225
- #router = new NextStepRouter();
210
+ * the `closedWaves()` read face and the wave gate share the same router). Built in
211
+ * the constructor body, never as a field initializer: the injected artifact matrix
212
+ * is a constructor argument, and a field initializer runs before it is assigned. */
213
+ #router;
214
+ /** The artifact matrix this ledger's names resolve through — the composition root's
215
+ * single instance, held (never minted) so a read face asks one table. */
216
+ #artifacts;
226
217
  /** The handoff-schema face — the conclusion single source (`conclusionOf`), one
227
218
  * instance per ledger (the round verdict derives from the op's carrier plane at
228
219
  * judgment time · D27). */
@@ -241,13 +232,31 @@ export class Ledger {
241
232
  * dispatch input (a backfill touching other tasks, or a Constraints reword, must
242
233
  * not void a reviewed wave). */
243
234
  #brief = new BriefRenderer();
235
+ /** The plan read seam (D30) — the reviewed brief's ONLY read of `reviewed.plan`:
236
+ * the drift judgment re-reads the path the round recorded, through the same
237
+ * per-command `PlanSource` the dispatch read its plan through. The ledger itself
238
+ * never opens a file for the brief, so the observation face can never make the
239
+ * hash subject drift. */
240
+ #plan;
244
241
  /** The round-naming single source over this ledger's workspace — the crash
245
242
  * artifact names derive here (zero second derivation). */
246
243
  #naming;
247
- constructor(workspace, config) {
244
+ /** `artifacts` is the composition root's matrix, and it is OPTIONAL here — unlike
245
+ * `CliLifecycle#artifacts`, which is required because a wiring bug there would read as
246
+ * a legal `absent` carrier. The null callers are hermetic fixtures that read the
247
+ * ledger's own record face, and the TWO cells `null` silences stay on the observation
248
+ * side of the house: `orphanHandoffs()` ⇒ `[]`, and — because the router below is
249
+ * built from this same value — the fix hop's read-back hint (`Route.rulings`)
250
+ * vanishes, which the render face prints as zero sentence rather than an empty slot.
251
+ * Neither is an identity judgment: `null` can not turn a judgment into a visible
252
+ * `absent`. Production passes the single instance at every construction point. */
253
+ constructor(workspace, config, plan, artifacts) {
248
254
  this.#workspace = workspace;
249
255
  this.#families = config.handoffNamespace().families;
256
+ this.#plan = plan;
250
257
  this.#naming = new RoundNaming(workspace);
258
+ this.#artifacts = artifacts ?? null;
259
+ this.#router = new NextStepRouter(this.#artifacts);
251
260
  }
252
261
  /** The review-reference face — the refKind three-type derivation + binding (T25). */
253
262
  refs() {
@@ -294,36 +303,29 @@ export class Ledger {
294
303
  }
295
304
  /** Read progress.json; null when missing/corrupt (the ledger never invents state). */
296
305
  readProgress() {
297
- return this.#read("progress.json");
306
+ return this.#read(this.#progressName());
298
307
  }
299
308
  /** Write progress.json — the progress single-author write. */
300
309
  writeProgress(data) {
301
- this.#persist("progress.json", data);
310
+ this.#persist(this.#progressName(), data);
311
+ }
312
+ /** The progress row's name — the injected matrix's render when the composition root
313
+ * wired one, else the matrix's module-level entry to the SAME row render (the
314
+ * fixture plane constructs a ledger with no matrix; the spelling still has one
315
+ * home and the two entry forms cannot drift — `nameOf` delegates to `render`). */
316
+ #progressName() {
317
+ const identity = { domain: "workspace", tasks: null };
318
+ return (this.#artifacts?.render(identity, "progress") ?? ArtifactRegistry.nameOf("progress", null));
302
319
  }
303
320
  /** The ledger-row lookup single point — a scalar key (or the single-task wave key
304
321
  * `"1"`) resolves the `{ task }` row; a multi-task wave key (`"1,2"`) the `{ wave }` row.
305
- * A DOCUMENT-line lookup falls back to a row still carrying the retired `spec` key —
306
- * the read-time alias keeps an in-flight line's recorded reviews/fixes on its board
307
- * (the normalization is never written back: the stored key stays byte-frozen). The
308
- * alias keys on the workspace's DECLARED line word (`identity` — the caller's
309
- * declaration), never on the requested word alone: the retired row IS the line whose
310
- * declaration names it (`phase-spec` / `overall` / `single-spec`). A caller holding no
311
- * declaration keeps the pre-rename default (the `phase-spec` line). A row read is a
312
- * pure function of the progress data, so every face — this class and the board's
313
- * read-only line face — enters through this ONE lookup (no second key spelling). */
314
- static rowFor(data, key, identity = null) {
315
- const literal = data.waves.find((row) => row.wave === String(key));
316
- if (literal !== undefined || !_a.#retiredSpecApplies(key, identity))
317
- return literal;
318
- return data.waves.find((row) => row.wave === RETIRED_SPEC_KEY);
319
- }
320
- /** Whether a retired `spec` row IS the requested line — the requested word must be a
321
- * document-line word and, when the declaration is known, BE that declaration. */
322
- static #retiredSpecApplies(key, identity) {
323
- const word = String(key);
324
- if (!RETIRED_SPEC_LINE_KEYS.has(word))
325
- return false;
326
- return identity === null ? word === "phase-spec" : word === identity;
322
+ * The lookup is LITERAL: the pre-`phase-spec` `spec` row key is no longer recognized
323
+ * (a retired workspace's document row reads as absent, and its carrier files land on
324
+ * the `orphan:` observation face instead of a silent alias). A row read is a pure
325
+ * function of the progress data, so every face — this class and the board's read-only
326
+ * line face — enters through this ONE lookup (no second key spelling). */
327
+ static rowFor(data, key) {
328
+ return data.waves.find((row) => row.wave === String(key));
327
329
  }
328
330
  /** The fresh row for an absent key — always the wave form (a single trivial
329
331
  * wave `"1"` is still the `{ wave: "1" }` row — one row form, T26). */
@@ -343,25 +345,26 @@ export class Ledger {
343
345
  .map((record) => record.cycle)),
344
346
  ];
345
347
  }
346
- /** The row's round records — the ONE read face the ledger's consumers share. A
347
- * caller holding the line's DECLARED word passes it, so the retired `spec` row
348
- * resolves as that line (the same basis as `rowFor`'s). */
349
- recordsOf(key, identity = null) {
348
+ /** The row's round records — the ONE read face the ledger's consumers share. The
349
+ * read is literal (`rowFor`'s ONE basis): the retired `spec` row resolves for no
350
+ * document word, so a legacy row contributes no records and the board shows its
351
+ * line as missing. */
352
+ recordsOf(key) {
350
353
  const data = this.readProgress();
351
354
  if (data === null)
352
355
  return [];
353
- return RoundRecords.of(_a.rowFor(data, key, identity));
356
+ return RoundRecords.of(_a.rowFor(data, key));
354
357
  }
355
358
  /** One op's COMPLETED cycles on a key — only `verdict.targetAction === true` records.
356
359
  * The completion questions read this face; the dispatch-number allocation reads
357
360
  * `roundCount` (every in-register cycle). The caller holding the line's DECLARED
358
361
  * word passes it, so a migrated row is judged as that line (one basis with
359
362
  * `rowFor`'s). */
360
- completedCycles(key, op, identity = null) {
363
+ completedCycles(key, op) {
361
364
  const data = this.readProgress();
362
365
  if (data === null)
363
366
  return [];
364
- return RoundRecords.of(_a.rowFor(data, key, identity))
367
+ return RoundRecords.of(_a.rowFor(data, key))
365
368
  .filter((record) => record.op === op && record.verdict.targetAction)
366
369
  .map((record) => record.cycle);
367
370
  }
@@ -369,22 +372,22 @@ export class Ledger {
369
372
  * (the round COUNT: the length of the recorded cycle identity set — for a
370
373
  * contiguous review line this equals the latest cycle, but the identity is the
371
374
  * cycle list, never the count, and a re-attempt at an existing cycle adds none). */
372
- roundCount(key, mode, identity = null) {
375
+ roundCount(key, mode) {
373
376
  const data = this.readProgress();
374
377
  if (data === null)
375
378
  return 0;
376
- return this.#cyclesOf(_a.rowFor(data, key, identity), mode).length;
379
+ return this.#cyclesOf(_a.rowFor(data, key), mode).length;
377
380
  }
378
381
  /** Whether a dispatch key + mode has a round REGISTERED for a given CYCLE — the
379
382
  * identity test for the register (a fix cycle that skipped a number is present at
380
383
  * its own number, not at its ordinal — D28). This is the test/seeding face: it
381
384
  * answers register membership, NOT completion (a hard-failed round is registered),
382
385
  * so no production completion question reads it — those read `completedCycles`. */
383
- roundRecorded(key, mode, cycle, identity = null) {
386
+ roundRecorded(key, mode, cycle) {
384
387
  const data = this.readProgress();
385
388
  if (data === null)
386
389
  return false;
387
- return this.#cyclesOf(_a.rowFor(data, key, identity), mode).includes(cycle);
390
+ return this.#cyclesOf(_a.rowFor(data, key), mode).includes(cycle);
388
391
  }
389
392
  /** Record a dispatched round — the on-disk round record (the ledger edge of the
390
393
  * ExecutionState carrier: TaskGraph in memory, the ledger on disk). Every dispatched
@@ -397,9 +400,9 @@ export class Ledger {
397
400
  * identity does not double it. A caller holding the line's DECLARED word passes it
398
401
  * too, so a migrated row is APPENDED TO rather than forked into a second identity
399
402
  * row (the same one basis `rowFor` reads by). */
400
- recordRound(key, init, identity = null) {
403
+ recordRound(key, init) {
401
404
  const data = this.readProgress() ?? this.emptyProgress();
402
- let row = _a.rowFor(data, key, identity);
405
+ let row = _a.rowFor(data, key);
403
406
  if (row === undefined) {
404
407
  row = this.entryFor(key);
405
408
  data.waves.push(row);
@@ -440,9 +443,9 @@ export class Ledger {
440
443
  * recorded revision, and BLOCKs revision-aware when unchanged). The kind IS part
441
444
  * of the identity: a doc line binds a doc-revision (T7), a wave line a
442
445
  * brief-revision (D30) — one row, one reviewed identity. */
443
- recordReviewedRevision(key, revision, identity = null) {
446
+ recordReviewedRevision(key, revision) {
444
447
  const data = this.readProgress() ?? this.emptyProgress();
445
- let row = _a.rowFor(data, key, identity);
448
+ let row = _a.rowFor(data, key);
446
449
  if (row === undefined) {
447
450
  row = this.entryFor(key);
448
451
  data.waves.push(row);
@@ -450,6 +453,22 @@ export class Ledger {
450
453
  row.reviewedRevision = revision;
451
454
  this.writeProgress(data);
452
455
  }
456
+ /** Record a branch line's reviewed PLAN revision (P21 §4.1) — the plan
457
+ * document's body revision as the round LEFT it. The read rides the ledger's own
458
+ * `PlanSource` (the ONE plan read point), so a round that edited its plan binds the
459
+ * edited bytes — never the dispatch-time snapshot — while a non-ready read records
460
+ * nothing (present facts only, the symmetric failure face to `recordReviewedBrief`).
461
+ * The recorded path is normalized HERE, not by the caller (the same discipline
462
+ * `#briefRevision` keeps): the drift comparator relativizes only its current side,
463
+ * so an absolute argv-erasure shape handed in by a future caller would otherwise
464
+ * read as a false drift. */
465
+ recordReviewedPlanRevision(key, planPath) {
466
+ const read = this.#plan.readPath(planPath);
467
+ const text = read.text();
468
+ if (text === null)
469
+ return;
470
+ this.recordReviewedRevision(key, this.#refs.docRevision(this.#rel(planPath), text));
471
+ }
453
472
  /** Record a wave line's reviewed BRIEF revision (D30) — the hash of the wave's
454
473
  * TASK-ONLY projection (P29 §2.2: the task sections, `## Constraints` excluded).
455
474
  * A backfill touching OTHER tasks leaves this projection byte-identical, and so
@@ -463,14 +482,21 @@ export class Ledger {
463
482
  /** The wave line's reviewed-basis revision (D30) — the hash of the wave's TASK-ONLY
464
483
  * projection (`BriefRenderer#taskBody`: the task sections, `## Constraints`
465
484
  * excluded — P29 §2.2). The `plan` layer is the plan the brief renders from, the
466
- * `brief_hash` layer the projection's own digest. Null when the plan is unreadable
467
- * or a requested task is absent (present facts only). */
485
+ * `brief_hash` layer the projection's own digest. The read rides the injected
486
+ * `PlanSource` (the ONE plan read seam), so a non-ready read — an unreadable plan,
487
+ * a grammar break — records nothing. Null when the plan is unreadable or a
488
+ * requested task is absent (present facts only). */
468
489
  #briefRevision(waveKey, planPath) {
490
+ const read = this.#plan.readPath(planPath);
491
+ const text = read.text();
492
+ const doc = read.doc();
493
+ if (text === null || doc === null)
494
+ return null;
469
495
  try {
470
496
  const tasks = waveKey.split(",").map((part) => Number(part));
497
+ const brief = this.#brief.taskBody(text, doc, tasks);
471
498
  // The plan layer is stored repoRoot-relative (P9 T4 §2.7) — one basis with
472
- // every persisted path field; the read erases to absolute at the syscall edge.
473
- const brief = this.#brief.taskBody(readFileSync(this.#abs(planPath), "utf8"), tasks);
499
+ // every persisted path field.
474
500
  return this.#refs.briefRevision(this.#rel(planPath), brief);
475
501
  }
476
502
  catch {
@@ -480,11 +506,11 @@ export class Ledger {
480
506
  /** A line's recorded reviewed identity — null when none on record (a line with no
481
507
  * reviewed identity keeps the legacy closed face). Callers narrow by `kind`: a doc
482
508
  * line binds a doc-revision, a wave line a brief-revision (the kinds never mix). */
483
- reviewedRevisionOf(key, identity = null) {
509
+ reviewedRevisionOf(key) {
484
510
  const data = this.readProgress();
485
511
  if (data === null)
486
512
  return null;
487
- return _a.rowFor(data, key, identity)?.reviewedRevision ?? null;
513
+ return _a.rowFor(data, key)?.reviewedRevision ?? null;
488
514
  }
489
515
  /** Record a wave row's plan-task snapshot — the task set the plan carried at the
490
516
  * instant the wave CLOSED. The write is IDEMPOTENT: an existing snapshot is never
@@ -515,8 +541,8 @@ export class Ledger {
515
541
  /** The doc line's recorded reviewed doc revision — the doc-revision narrowing of
516
542
  * `reviewedRevisionOf` (null when none on record, or when a non-doc kind sits on
517
543
  * the row — a doc line is never a wave line). */
518
- reviewedDocRevisionOf(key, identity = null) {
519
- const reviewed = this.reviewedRevisionOf(key, identity);
544
+ reviewedDocRevisionOf(key) {
545
+ const reviewed = this.reviewedRevisionOf(key);
520
546
  return reviewed !== null && reviewed.kind === "doc-revision" ? reviewed : null;
521
547
  }
522
548
  /** The doc line's identity verdict (T7) — the current doc revision vs the line's
@@ -527,8 +553,8 @@ export class Ledger {
527
553
  * `same` → unchanged (the revision-aware BLOCK). Null when no reviewed revision
528
554
  * is on record or the doc is unreadable (the legacy closed face keeps its
529
555
  * generic message — only present facts land). */
530
- docLineVerdict(key, doc, identity = null) {
531
- const pair = this.#docRevisionPair(key, doc, identity);
556
+ docLineVerdict(key, doc) {
557
+ const pair = this.#docRevisionPair(key, doc);
532
558
  if (pair === null)
533
559
  return null;
534
560
  return this.#identity.verdict(pair.reviewed, { ref: pair.current }) === "same"
@@ -540,8 +566,8 @@ export class Ledger {
540
566
  * unreadable). ONE read for TWO consumers: the drift verdict (`docLineVerdict`) and
541
567
  * the refusal's mandatory diagnosis (`docDriftHashes`), so the two can never
542
568
  * compare different bytes. */
543
- #docRevisionPair(key, doc, identity) {
544
- const reviewed = this.reviewedDocRevisionOf(key, identity);
569
+ #docRevisionPair(key, doc) {
570
+ const reviewed = this.reviewedDocRevisionOf(key);
545
571
  if (reviewed === null)
546
572
  return null;
547
573
  try {
@@ -560,8 +586,8 @@ export class Ledger {
560
586
  * the review bound, on the ONE persisted basis) and both hash ends. Null when there
561
587
  * is no recorded revision or the document is unreadable: a diagnosis never invents
562
588
  * a fact. */
563
- docDriftHashes(key, doc, identity = null) {
564
- const pair = this.#docRevisionPair(key, doc, identity);
589
+ docDriftHashes(key, doc) {
590
+ const pair = this.#docRevisionPair(key, doc);
565
591
  if (pair === null)
566
592
  return null;
567
593
  return {
@@ -593,11 +619,11 @@ export class Ledger {
593
619
  * re-review resumes the same round (nothing pre-binds). `unbound` (no identity on
594
620
  * record / an unreadable doc) keeps the legacy round/route judgment. */
595
621
  reviewGate(key, doc, type) {
596
- const verdict = this.docLineVerdict(key, doc, type);
622
+ const verdict = this.docLineVerdict(key, doc);
597
623
  if (verdict === "drift")
598
624
  return { kind: "open" };
599
625
  if (verdict === "same") {
600
- const reviewed = this.reviewedDocRevisionOf(key, type);
626
+ const reviewed = this.reviewedDocRevisionOf(key);
601
627
  if (reviewed === null)
602
628
  return { kind: "unbound" };
603
629
  return { kind: "same", pending: this.#pendingFix(key, type), reviewed };
@@ -652,8 +678,11 @@ export class Ledger {
652
678
  // The `--reviews` identity is the ROUTE's own (P31 §2.3): the round read resolves
653
679
  // the FINAL carrier the record names, so a draft beside it never becomes the input
654
680
  // — the board's `next:` and the dispatch's read the same file by construction.
681
+ // The router's own fix payload rides through: its `rulings` value (the rendered
682
+ // sidecar path) is part of the ONE fix hop, so this fallback-only repair must not
683
+ // rebuild the route from scratch and silently drop it.
655
684
  return {
656
- kind: "fix",
685
+ ...route,
657
686
  reviews: route.reviews ??
658
687
  this.resolveHandoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
659
688
  };
@@ -732,7 +761,7 @@ export class Ledger {
732
761
  const data = this.readProgress();
733
762
  if (data === null)
734
763
  return false;
735
- const row = _a.rowFor(data, key, type);
764
+ const row = _a.rowFor(data, key);
736
765
  if (row === undefined)
737
766
  return false;
738
767
  const reviews = this.#latestLiveCycleOfRow(row, "review");
@@ -832,7 +861,7 @@ export class Ledger {
832
861
  const data = this.readProgress();
833
862
  if (data === null)
834
863
  return false;
835
- const row = _a.rowFor(data, key, type);
864
+ const row = _a.rowFor(data, key);
836
865
  if (row === undefined)
837
866
  return false;
838
867
  return this.#rowClosed(type, type === "wave" ? { tasks: String(key) } : {}, row);
@@ -872,7 +901,7 @@ export class Ledger {
872
901
  const data = this.readProgress();
873
902
  if (data === null)
874
903
  return { kind: "review" };
875
- const row = _a.rowFor(data, key, type);
904
+ const row = _a.rowFor(data, key);
876
905
  if (row === undefined)
877
906
  return { kind: "review" };
878
907
  const reviewLead = targetFaces[type].product.reviewLead;
@@ -1026,11 +1055,11 @@ export class Ledger {
1026
1055
  * with its requesting review's cycle (D28 unchanged). Idempotent: a second stamp of
1027
1056
  * the same record is a no-op rewrite. Returns whether a completed review of that
1028
1057
  * cycle was stamped. */
1029
- supersedeReview(key, type, cycle, byCycle) {
1058
+ supersedeReview(key, cycle, byCycle) {
1030
1059
  const data = this.readProgress();
1031
1060
  if (data === null)
1032
1061
  return false;
1033
- const row = _a.rowFor(data, key, type);
1062
+ const row = _a.rowFor(data, key);
1034
1063
  if (row === undefined)
1035
1064
  return false;
1036
1065
  const records = [...RoundRecords.of(row)];
@@ -1139,15 +1168,13 @@ export class Ledger {
1139
1168
  digest,
1140
1169
  };
1141
1170
  }
1142
- /** The handoff file NAME a read actually resolves — the canonical family name, or a
1143
- * DOCUMENT line's retired `spec` twin when the canonical file is absent (the
1144
- * one-release read alias, P22 D73). The alias reports the name it RESOLVED, not the
1145
- * one it was asked for: a hop that points a later round at this carrier
1146
- * (`--reviews`, `INPUT_REVIEWS`, the criterion's input set) must name the file that
1147
- * exists — a read alias that renamed only the row would leave a never-minted path
1148
- * behind. The alias keys on the line's declared word and never covers the node
1149
- * shapes; it is READ-ONLY (every write goes through `persistHandoff`'s canonical
1150
- * spelling). */
1171
+ /** The handoff file NAME a read resolves — the canonical family name, or the round's
1172
+ * FINAL when that is what landed (the finalized answer, not the child's raw draft).
1173
+ * The retired `spec` twin and the cycle-less implement rung are gone (P36 §3): the
1174
+ * answer is the ladder's, never a historical spelling, so the old carriers read as
1175
+ * absent here and surface as `orphan:` observations instead of silent aliases. The
1176
+ * read is READ-ONLY — every write goes through `persistHandoff`'s canonical
1177
+ * spelling. */
1151
1178
  resolveHandoffName(op, type, params = {}) {
1152
1179
  // The attempt the read resolves is the round's LATEST recorded one unless the
1153
1180
  // caller names it: a re-dispatched review lands at `-a{n}`, and its fix leg only
@@ -1161,33 +1188,7 @@ export class Ledger {
1161
1188
  const final = RoundNaming.renderName(_a.#artifactOf(op, type, resolved), "final");
1162
1189
  if (final !== canonical && this.#read(final) !== null)
1163
1190
  return final;
1164
- if (!RETIRED_SPEC_LINE_KEYS.has(type)) {
1165
- return this.#legacyCarrierName(op, type, resolved) ?? canonical;
1166
- }
1167
- if (this.#read(canonical) !== null)
1168
- return canonical;
1169
- const retired = _a.#retiredCarrierName(op, params);
1170
- return this.#read(retired) === null ? canonical : retired;
1171
- }
1172
- /** The pre-P34 cycle-less spelling of the round's own family name — the ONE carrier
1173
- * the P34 respelling moved (`tasks-{tasks}-implement.json` → `…-implement-{cycle}.json`),
1174
- * so a folded legacy record (no recorded path, no digest) still resolves its own
1175
- * bytes instead of reading as absent while the orphan scan still claims the file.
1176
- * The rung is READ-ONLY and cycle-1 · attempt-1 alone: the legacy spelling carried
1177
- * neither coordinate, so no later cycle or attempt may read it. null when the op is
1178
- * not an implement, the round is past its first cycle/attempt, the family does not
1179
- * exist, the legacy name IS the canonical one, or the file is absent. */
1180
- #legacyCarrierName(op, type, params) {
1181
- if (RoundRecords.opOf(op) !== "implement")
1182
- return null;
1183
- if ((params.round ?? 1) !== 1 || (params.attempt ?? 1) !== 1)
1184
- return null;
1185
- if (!this.#families.includes(`${op}.${type}`))
1186
- return null;
1187
- const legacy = this.handoffName(op, type, { tasks: params.tasks });
1188
- if (legacy === this.handoffName(op, type, params))
1189
- return null;
1190
- return this.#read(legacy) === null ? null : legacy;
1191
+ return canonical;
1191
1192
  }
1192
1193
  /** The params one READ resolves under — the caller's attempt when it names one, else
1193
1194
  * the round's latest recorded attempt (a fix leg knows the cycle, not the review's
@@ -1204,13 +1205,10 @@ export class Ledger {
1204
1205
  return this.#workspace.resolve(this.resolveHandoffName(op, type, params));
1205
1206
  }
1206
1207
  /** Read a handoff carrier; null when missing/corrupt. A DOCUMENT-line read falls
1207
- * back to the retired `spec` file name (the one-release read alias, P22 D73): the
1208
- * rounds a line recorded before the vocabulary unification stay judgeable — the
1209
- * closure walk still reads their C5 route, so a closed line does not re-open. The
1210
- * alias keys on the line's declared word (`phase-spec` / `overall` / `single-spec`,
1211
- * the same basis as `rowFor`'s) and never covers the node shapes. Every WRITE goes
1212
- * through `persistHandoff`'s current spelling — the alias is read-only, and the name
1213
- * it resolves is `resolveHandoffName`'s ONE answer.
1208
+ * through `resolveHandoffName`'s ONE answer, which no longer carries a historical
1209
+ * spelling (P36 §3): a retired `spec-<op>-<round>.json` carrier reads as absent —
1210
+ * the file stays on disk untouched and surfaces as an `orphan:` observation. Every
1211
+ * WRITE goes through `persistHandoff`'s current spelling.
1214
1212
  *
1215
1213
  * P31 §2.2 — the read is CHECKED: the (op, type, round) round's latest recorded
1216
1214
  * attempt supplies the digest the engine wrote, and `CarrierIntegrity.read` compares
@@ -1246,7 +1244,7 @@ export class Ledger {
1246
1244
  #latestRecordOf(op, type, params) {
1247
1245
  const mode = RoundRecords.opOf(op) ?? op;
1248
1246
  const round = params.round === undefined ? null : Number(params.round);
1249
- return this.recordsOf(this.#roundKey(type, params), type)
1247
+ return this.recordsOf(this.#roundKey(type, params))
1250
1248
  .filter((record) => record.op === mode)
1251
1249
  .filter((record) => round === null || record.cycle === round)
1252
1250
  .filter((record) => params.attempt === undefined || record.attempt === params.attempt)
@@ -1281,14 +1279,11 @@ export class Ledger {
1281
1279
  const name = this.#resolvedCarrierName(type, key, record);
1282
1280
  return this.#read(name) === null ? "" : this.#workspace.resolve(name);
1283
1281
  }
1284
- /** Step ② of `carrierPathOf` — the NAME the record's identity resolves to: the
1285
- * retired `spec-{op}-{round}.json` spelling for a migrated row (its `spec` family is
1286
- * not in the live config table, so the ladder would throw), the read ladder's answer
1287
- * for every live line. */
1282
+ /** Step ② of `carrierPathOf` — the NAME the record's identity resolves to: the read
1283
+ * ladder's answer, seeded with the record's full identity. A retired `spec` row's
1284
+ * carrier is no longer a named exception: the row itself no longer resolves, so the
1285
+ * files stay orphan observations. */
1288
1286
  #resolvedCarrierName(type, key, record) {
1289
- if (key === RETIRED_SPEC_KEY) {
1290
- return _a.#retiredCarrierName(record.op, { round: record.cycle });
1291
- }
1292
1287
  const params = {
1293
1288
  tasks: type === "wave" ? key : undefined,
1294
1289
  round: record.cycle,
@@ -1296,125 +1291,92 @@ export class Ledger {
1296
1291
  };
1297
1292
  return this.resolveHandoffName(record.op, type, params);
1298
1293
  }
1299
- /** The retired document-line carrier name of one round — `spec-review-{round}.json` /
1300
- * `spec-fix-{round}.json`. It lives here, never in the family table: it is a read
1301
- * fallback for already-recorded rounds, not a name the engine can mint. */
1302
- static #retiredCarrierName(op, params) {
1303
- return `${RETIRED_SPEC_KEY}-${op}-${params.round ?? ""}.json`;
1304
- }
1305
- /** The workspace's ORPHAN handoff files — the carrier files (draft or final) whose
1306
- * (line key, op, cycle, attempt) never landed in `progress.json`. The board and the
1307
- * `--dry-run` preview render them; this is a PURE READ — the engine never writes,
1308
- * moves or deletes a carrier. The family names are the ledger's own single naming
1309
- * truth (no second pattern), and the owning row is read through the ONE basis
1310
- * `rowFor` establishes — the file's own line word IS its declaration — so a
1311
- * migrated workspace's carrier resolves its live row instead of reading as an
1312
- * orphan.
1294
+ /** The workspace's ORPHAN handoff files — the TWO-TIER judgment (spec §2.5, an
1295
+ * explicit narrowing of the single-tier "a name `attribute` does not know is an
1296
+ * orphan" reading):
1297
+ *
1298
+ * (i) the name does not attribute at all — a matrix-external name, an unknown
1299
+ * spelling. Observation, never a refusal;
1300
+ * (ii) the name attributes to the ROUND domain's carrier pair (`draft` /
1301
+ * `final`) and no progress record claims it — a carrier already on disk that
1302
+ * the ledger never booked stays visible, so a recovery pass can see it.
1303
+ *
1304
+ * Every other attributable name is NOT an orphan: the workspace literals and the
1305
+ * brief are the board's own bookkeeping, the four document rows are identity
1306
+ * documents, and `rulings` / `report` / `log` / `crash` / `evidence` are the
1307
+ * board's own observations and attachments, not handoff carriers. Reading tier (ii)
1308
+ * literally over those kinds would flood the board with `orphan:` rows for files it
1309
+ * wrote or the orchestrator recorded (the 51 rulings sidecars this very workspace
1310
+ * holds).
1311
+ *
1312
+ * The candidate set is the WHOLE directory (`Workspace#names()`, the same read the
1313
+ * artifact matrix's `misplaced` judgment uses), not the names a carrier pattern
1314
+ * recognized — tier (i) can only exist if unrecognized names are looked at.
1313
1315
  *
1314
- * OWNERSHIP IS THE RECORD, NEVER ITS VERDICT (spec §2.12): a round that acted and
1315
- * then failed still owns the file it wrote — completion is the judgment face, and
1316
- * reading it here would relabel an honest failure's carrier as an orphan and hand it
1317
- * to a recovery pass that deletes child work.
1316
+ * Claiming keeps BOTH tiers P34/D89 delivered: the record's `(op, cycle, attempt)`
1317
+ * equals the name's identity read through `roundIdentityKey` (the matrix's own key, so a
1318
+ * cycle-less name is never claimed by a cycle-1 record — only the attempt default
1319
+ * folds), or the record's own `carrierPath` basename equals the name (a pre-P34 record
1320
+ * remembers an absolute path while the scan yields a bare name — read once through
1321
+ * `carrierPathOf`, the only accessor of that fact). Completion is irrelevant:
1322
+ * ownership is the record (spec §2.12), so an honestly failed round's carrier is
1323
+ * owned. Zero writes: this is a PURE READ, the engine never moves or deletes.
1318
1324
  *
1319
- * The identity is the fast tier; the LEGACY tier compares the record's own carrier
1320
- * path by basename (a pre-P34 row remembers an absolute path while the scan yields a
1321
- * bare name), read once through `carrierPathOf` — the only accessor of the record's
1322
- * carrier identity. */
1325
+ * A ledger constructed with NO matrix answers `[]`: attribution is the matrix's, and
1326
+ * "no matrix" has no second name grammar to fall back on. */
1323
1327
  orphanHandoffs() {
1328
+ const artifacts = this.#artifacts;
1329
+ if (artifacts === null)
1330
+ return [];
1324
1331
  const progress = this.readProgress() ?? this.emptyProgress();
1325
1332
  const orphans = [];
1326
- for (const name of this.#workspaceFiles()) {
1327
- const owner = _a.#handoffOwner(name);
1328
- if (owner === null)
1329
- continue;
1330
- const records = RoundRecords.of(_a.#ownerRow(progress, owner.key));
1331
- const identity = `${owner.op}:${owner.round}:${owner.attempt}`;
1332
- const claimed = records.some((record) => `${record.op}:${record.cycle}:${record.attempt}` === identity ||
1333
- basename(this.carrierPathOf(owner.type, owner.key, record)) === name);
1334
- if (!claimed)
1333
+ for (const name of this.#workspace.names()) {
1334
+ const attributed = artifacts.attribute(name);
1335
+ if (attributed === null) {
1335
1336
  orphans.push(name);
1337
+ continue;
1338
+ }
1339
+ if (attributed.kind !== "draft" && attributed.kind !== "final")
1340
+ continue;
1341
+ if (attributed.identity.domain !== "round")
1342
+ continue;
1343
+ if (this.#claimed(progress, attributed.identity, name))
1344
+ continue;
1345
+ orphans.push(name);
1336
1346
  }
1337
1347
  return orphans.sort();
1338
1348
  }
1339
- /** The row one carrier file's line word resolves to. The retired `spec` twin is a FILE
1340
- * NAME a live row already outlived: the workspace holds ONE identity document, so the
1341
- * word resolves onto whichever document word that row now declares (`phase-spec` /
1342
- * `overall` / `single-spec`), never onto a row name the migration retired. Every other
1343
- * word — a wave's tasks, `plan`, `branch` — reads through `rowFor`'s ONE basis. */
1344
- static #ownerRow(progress, key) {
1345
- if (key !== RETIRED_SPEC_KEY)
1346
- return _a.rowFor(progress, key, _a.#lineWord(key));
1347
- const literal = _a.rowFor(progress, key, null);
1348
- if (literal !== undefined)
1349
- return literal;
1350
- return progress.waves.find((row) => RETIRED_SPEC_LINE_KEYS.has(row.wave));
1351
- }
1352
- /** A handoff file's key as a declared line word — the three document words declare
1353
- * themselves; every other key (a wave's tasks, `plan`, `branch`) declares nothing
1354
- * and reads literally. */
1355
- static #lineWord(key) {
1356
- return RETIRED_SPEC_LINE_KEYS.has(key) ? key : null;
1357
- }
1358
- /** The workspace directory's file names (an absent/unreadable directory is an
1359
- * empty fact — the orphan face degrades, never throws). */
1360
- #workspaceFiles() {
1361
- try {
1362
- return readdirSync(this.#workspace.path, { withFileTypes: true })
1363
- .filter((entry) => entry.isFile())
1364
- .map((entry) => entry.name);
1365
- }
1366
- catch {
1367
- return [];
1368
- }
1369
- }
1370
- /** Which recorded round one handoff file belongs to — the ONE renderer read
1371
- * backwards: `<line>-<op>[-<cycle>][-a<attempt>][.c<cycle>].json`, the retired
1372
- * document-line `spec` twin included (a still-unbooked draft can carry it). The
1373
- * parse yields the same four coordinates the naming face renders, so the orphan
1374
- * test compares an identity with an identity — never a spelling with a spelling.
1375
- * Null for a non-carrier file. */
1376
- static #handoffOwner(name) {
1377
- // A FINAL carrier (`<stem>.c{round}.json`, P31 §2.3) is the same artifact as its
1378
- // draft — the cycle is the name's own suffix, never a second family.
1379
- const draft = name.replace(/\.c\d+\.json$/, ".json");
1380
- const wave = _a.#WAVE_CARRIER.exec(draft);
1381
- if (wave !== null) {
1382
- const [, line = "", op = "", cycle, attempt] = wave;
1383
- // The wave row keys the task GROUP alone — the `tasks-` spine is the name's, not
1384
- // the key's. The legacy cycle-less implement spelling is the fixed family's round 1.
1385
- return {
1386
- type: "wave",
1387
- key: line.replace(/^tasks-/, ""),
1388
- op,
1389
- round: cycle === undefined ? 1 : Number(cycle),
1390
- attempt: _a.#attemptOf(attempt),
1391
- };
1392
- }
1393
- const line = _a.#LINE_CARRIER.exec(draft);
1394
- if (line !== null) {
1395
- const [, key = "", op = "", cycle = "", attempt] = line;
1396
- return {
1397
- type: key,
1398
- key,
1399
- op,
1400
- round: Number(cycle),
1401
- attempt: _a.#attemptOf(attempt),
1402
- };
1403
- }
1404
- return null;
1349
+ /** Whether a progress record claims one attributed carrier name — the identity tier
1350
+ * first (the record's own `(op, cycle, attempt)` through the matrix's OWN identity key),
1351
+ * the recorded-path tier second (a pre-P34 record's absolute `carrierPath` compared by
1352
+ * basename).
1353
+ *
1354
+ * The first tier compares with `roundIdentityKey`, so it answers exactly the question
1355
+ * the matrix answered when it attributed the name: a cycle-less spelling
1356
+ * (`tasks-<n>-implement.json`) is the cycle-less identity, NEVER a cycle-1 record's
1357
+ * name (the renderer mints `tasks-<n>-implement-1.json` for cycle 1 — two coordinates,
1358
+ * spec §2.2). Only the `attempt` default folds (attempt 1 and an absent attempt render
1359
+ * the same name). A cycle-less carrier therefore stays claimed only through tier two —
1360
+ * a record that REMEMBERS that path — which is exactly the division spec §2.5 states. */
1361
+ #claimed(progress, identity, name) {
1362
+ const { type, key } = _a.#lineOf(identity.line);
1363
+ const records = RoundRecords.of(_a.rowFor(progress, key));
1364
+ const expected = roundIdentityKey(identity);
1365
+ return records.some((record) => roundIdentityKey({
1366
+ domain: "round",
1367
+ line: identity.line,
1368
+ op: record.op,
1369
+ cycle: record.cycle,
1370
+ attempt: record.attempt,
1371
+ }) === expected || basename(this.carrierPathOf(type, key, record)) === name);
1405
1372
  }
1406
- /** The wave line's carrier spelling, read backwards — the task key is a lazy span,
1407
- * the op one of the three words, the cycle and the attempt optional (the legacy
1408
- * cycle-less implement name harvests no cycle). */
1409
- static #WAVE_CARRIER = /^(tasks-.+?)-(implement|review|fix)(?:-(\d+))?(?:-a(\d+))?\.json$/;
1410
- /** The single-target lines' carrier spelling — `branch` and the doc words (the
1411
- * words of the ONE target-face table, the retired `spec` twin included), every one
1412
- * of which carries its cycle. */
1413
- static #LINE_CARRIER = new RegExp(`^(${[...Object.keys(targetFaces).filter((word) => word !== "wave"), RETIRED_SPEC_KEY].join("|")})-(review|fix)-(\\d+)(?:-a(\\d+))?\\.json$`);
1414
- /** An absent attempt segment is the first attempt — the naming face never renders
1415
- * `-a1`, so the parse and the render agree on the identity of attempt 1. */
1416
- static #attemptOf(captured) {
1417
- return captured === undefined ? 1 : Number(captured);
1373
+ /** The progress row one carrier identity belongs to: a wave line keys the task GROUP
1374
+ * (the `tasks-` spine is the name's, never the key's), every other line word keys
1375
+ * itself. */
1376
+ static #lineOf(line) {
1377
+ return line.startsWith("tasks-")
1378
+ ? { type: "wave", key: line.slice("tasks-".length) }
1379
+ : { type: line, key: line };
1418
1380
  }
1419
1381
  // -------------------------------------------------------------------------
1420
1382
  // crash — the lane crash → recovery record
@@ -1509,7 +1471,7 @@ export class Ledger {
1509
1471
  // cycle 2 (D28). A count comparison would flatten that to 1 and refuse the read.
1510
1472
  // Completion is the recorded VERDICT, never membership — every dispatched round
1511
1473
  // is recorded now, so a failed round's cycle is in register but reads no carrier.
1512
- const recorded = this.recordsOf(this.#roundKey(type, params), type)
1474
+ const recorded = this.recordsOf(this.#roundKey(type, params))
1513
1475
  .filter((record) => record.op === op && record.cycle === round)
1514
1476
  .reduce((latest, record) => latest === undefined || record.attempt >= latest.attempt ? record : latest, undefined);
1515
1477
  if (recorded === undefined || !recorded.verdict.targetAction)