@oscaner-skills/cdd-engine 4.12.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). */
@@ -250,11 +241,22 @@ export class Ledger {
250
241
  /** The round-naming single source over this ledger's workspace — the crash
251
242
  * artifact names derive here (zero second derivation). */
252
243
  #naming;
253
- constructor(workspace, config, plan) {
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) {
254
254
  this.#workspace = workspace;
255
255
  this.#families = config.handoffNamespace().families;
256
256
  this.#plan = plan;
257
257
  this.#naming = new RoundNaming(workspace);
258
+ this.#artifacts = artifacts ?? null;
259
+ this.#router = new NextStepRouter(this.#artifacts);
258
260
  }
259
261
  /** The review-reference face — the refKind three-type derivation + binding (T25). */
260
262
  refs() {
@@ -301,36 +303,29 @@ export class Ledger {
301
303
  }
302
304
  /** Read progress.json; null when missing/corrupt (the ledger never invents state). */
303
305
  readProgress() {
304
- return this.#read("progress.json");
306
+ return this.#read(this.#progressName());
305
307
  }
306
308
  /** Write progress.json — the progress single-author write. */
307
309
  writeProgress(data) {
308
- 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));
309
319
  }
310
320
  /** The ledger-row lookup single point — a scalar key (or the single-task wave key
311
321
  * `"1"`) resolves the `{ task }` row; a multi-task wave key (`"1,2"`) the `{ wave }` row.
312
- * A DOCUMENT-line lookup falls back to a row still carrying the retired `spec` key —
313
- * the read-time alias keeps an in-flight line's recorded reviews/fixes on its board
314
- * (the normalization is never written back: the stored key stays byte-frozen). The
315
- * alias keys on the workspace's DECLARED line word (`identity` — the caller's
316
- * declaration), never on the requested word alone: the retired row IS the line whose
317
- * declaration names it (`phase-spec` / `overall` / `single-spec`). A caller holding no
318
- * declaration keeps the pre-rename default (the `phase-spec` line). A row read is a
319
- * pure function of the progress data, so every face — this class and the board's
320
- * read-only line face — enters through this ONE lookup (no second key spelling). */
321
- static rowFor(data, key, identity = null) {
322
- const literal = data.waves.find((row) => row.wave === String(key));
323
- if (literal !== undefined || !_a.#retiredSpecApplies(key, identity))
324
- return literal;
325
- return data.waves.find((row) => row.wave === RETIRED_SPEC_KEY);
326
- }
327
- /** Whether a retired `spec` row IS the requested line — the requested word must be a
328
- * document-line word and, when the declaration is known, BE that declaration. */
329
- static #retiredSpecApplies(key, identity) {
330
- const word = String(key);
331
- if (!RETIRED_SPEC_LINE_KEYS.has(word))
332
- return false;
333
- 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));
334
329
  }
335
330
  /** The fresh row for an absent key — always the wave form (a single trivial
336
331
  * wave `"1"` is still the `{ wave: "1" }` row — one row form, T26). */
@@ -350,25 +345,26 @@ export class Ledger {
350
345
  .map((record) => record.cycle)),
351
346
  ];
352
347
  }
353
- /** The row's round records — the ONE read face the ledger's consumers share. A
354
- * caller holding the line's DECLARED word passes it, so the retired `spec` row
355
- * resolves as that line (the same basis as `rowFor`'s). */
356
- 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) {
357
353
  const data = this.readProgress();
358
354
  if (data === null)
359
355
  return [];
360
- return RoundRecords.of(_a.rowFor(data, key, identity));
356
+ return RoundRecords.of(_a.rowFor(data, key));
361
357
  }
362
358
  /** One op's COMPLETED cycles on a key — only `verdict.targetAction === true` records.
363
359
  * The completion questions read this face; the dispatch-number allocation reads
364
360
  * `roundCount` (every in-register cycle). The caller holding the line's DECLARED
365
361
  * word passes it, so a migrated row is judged as that line (one basis with
366
362
  * `rowFor`'s). */
367
- completedCycles(key, op, identity = null) {
363
+ completedCycles(key, op) {
368
364
  const data = this.readProgress();
369
365
  if (data === null)
370
366
  return [];
371
- return RoundRecords.of(_a.rowFor(data, key, identity))
367
+ return RoundRecords.of(_a.rowFor(data, key))
372
368
  .filter((record) => record.op === op && record.verdict.targetAction)
373
369
  .map((record) => record.cycle);
374
370
  }
@@ -376,22 +372,22 @@ export class Ledger {
376
372
  * (the round COUNT: the length of the recorded cycle identity set — for a
377
373
  * contiguous review line this equals the latest cycle, but the identity is the
378
374
  * cycle list, never the count, and a re-attempt at an existing cycle adds none). */
379
- roundCount(key, mode, identity = null) {
375
+ roundCount(key, mode) {
380
376
  const data = this.readProgress();
381
377
  if (data === null)
382
378
  return 0;
383
- return this.#cyclesOf(_a.rowFor(data, key, identity), mode).length;
379
+ return this.#cyclesOf(_a.rowFor(data, key), mode).length;
384
380
  }
385
381
  /** Whether a dispatch key + mode has a round REGISTERED for a given CYCLE — the
386
382
  * identity test for the register (a fix cycle that skipped a number is present at
387
383
  * its own number, not at its ordinal — D28). This is the test/seeding face: it
388
384
  * answers register membership, NOT completion (a hard-failed round is registered),
389
385
  * so no production completion question reads it — those read `completedCycles`. */
390
- roundRecorded(key, mode, cycle, identity = null) {
386
+ roundRecorded(key, mode, cycle) {
391
387
  const data = this.readProgress();
392
388
  if (data === null)
393
389
  return false;
394
- return this.#cyclesOf(_a.rowFor(data, key, identity), mode).includes(cycle);
390
+ return this.#cyclesOf(_a.rowFor(data, key), mode).includes(cycle);
395
391
  }
396
392
  /** Record a dispatched round — the on-disk round record (the ledger edge of the
397
393
  * ExecutionState carrier: TaskGraph in memory, the ledger on disk). Every dispatched
@@ -404,9 +400,9 @@ export class Ledger {
404
400
  * identity does not double it. A caller holding the line's DECLARED word passes it
405
401
  * too, so a migrated row is APPENDED TO rather than forked into a second identity
406
402
  * row (the same one basis `rowFor` reads by). */
407
- recordRound(key, init, identity = null) {
403
+ recordRound(key, init) {
408
404
  const data = this.readProgress() ?? this.emptyProgress();
409
- let row = _a.rowFor(data, key, identity);
405
+ let row = _a.rowFor(data, key);
410
406
  if (row === undefined) {
411
407
  row = this.entryFor(key);
412
408
  data.waves.push(row);
@@ -447,9 +443,9 @@ export class Ledger {
447
443
  * recorded revision, and BLOCKs revision-aware when unchanged). The kind IS part
448
444
  * of the identity: a doc line binds a doc-revision (T7), a wave line a
449
445
  * brief-revision (D30) — one row, one reviewed identity. */
450
- recordReviewedRevision(key, revision, identity = null) {
446
+ recordReviewedRevision(key, revision) {
451
447
  const data = this.readProgress() ?? this.emptyProgress();
452
- let row = _a.rowFor(data, key, identity);
448
+ let row = _a.rowFor(data, key);
453
449
  if (row === undefined) {
454
450
  row = this.entryFor(key);
455
451
  data.waves.push(row);
@@ -466,12 +462,12 @@ export class Ledger {
466
462
  * `#briefRevision` keeps): the drift comparator relativizes only its current side,
467
463
  * so an absolute argv-erasure shape handed in by a future caller would otherwise
468
464
  * read as a false drift. */
469
- recordReviewedPlanRevision(key, planPath, identity) {
465
+ recordReviewedPlanRevision(key, planPath) {
470
466
  const read = this.#plan.readPath(planPath);
471
467
  const text = read.text();
472
468
  if (text === null)
473
469
  return;
474
- this.recordReviewedRevision(key, this.#refs.docRevision(this.#rel(planPath), text), identity);
470
+ this.recordReviewedRevision(key, this.#refs.docRevision(this.#rel(planPath), text));
475
471
  }
476
472
  /** Record a wave line's reviewed BRIEF revision (D30) — the hash of the wave's
477
473
  * TASK-ONLY projection (P29 §2.2: the task sections, `## Constraints` excluded).
@@ -510,11 +506,11 @@ export class Ledger {
510
506
  /** A line's recorded reviewed identity — null when none on record (a line with no
511
507
  * reviewed identity keeps the legacy closed face). Callers narrow by `kind`: a doc
512
508
  * line binds a doc-revision, a wave line a brief-revision (the kinds never mix). */
513
- reviewedRevisionOf(key, identity = null) {
509
+ reviewedRevisionOf(key) {
514
510
  const data = this.readProgress();
515
511
  if (data === null)
516
512
  return null;
517
- return _a.rowFor(data, key, identity)?.reviewedRevision ?? null;
513
+ return _a.rowFor(data, key)?.reviewedRevision ?? null;
518
514
  }
519
515
  /** Record a wave row's plan-task snapshot — the task set the plan carried at the
520
516
  * instant the wave CLOSED. The write is IDEMPOTENT: an existing snapshot is never
@@ -545,8 +541,8 @@ export class Ledger {
545
541
  /** The doc line's recorded reviewed doc revision — the doc-revision narrowing of
546
542
  * `reviewedRevisionOf` (null when none on record, or when a non-doc kind sits on
547
543
  * the row — a doc line is never a wave line). */
548
- reviewedDocRevisionOf(key, identity = null) {
549
- const reviewed = this.reviewedRevisionOf(key, identity);
544
+ reviewedDocRevisionOf(key) {
545
+ const reviewed = this.reviewedRevisionOf(key);
550
546
  return reviewed !== null && reviewed.kind === "doc-revision" ? reviewed : null;
551
547
  }
552
548
  /** The doc line's identity verdict (T7) — the current doc revision vs the line's
@@ -557,8 +553,8 @@ export class Ledger {
557
553
  * `same` → unchanged (the revision-aware BLOCK). Null when no reviewed revision
558
554
  * is on record or the doc is unreadable (the legacy closed face keeps its
559
555
  * generic message — only present facts land). */
560
- docLineVerdict(key, doc, identity = null) {
561
- const pair = this.#docRevisionPair(key, doc, identity);
556
+ docLineVerdict(key, doc) {
557
+ const pair = this.#docRevisionPair(key, doc);
562
558
  if (pair === null)
563
559
  return null;
564
560
  return this.#identity.verdict(pair.reviewed, { ref: pair.current }) === "same"
@@ -570,8 +566,8 @@ export class Ledger {
570
566
  * unreadable). ONE read for TWO consumers: the drift verdict (`docLineVerdict`) and
571
567
  * the refusal's mandatory diagnosis (`docDriftHashes`), so the two can never
572
568
  * compare different bytes. */
573
- #docRevisionPair(key, doc, identity) {
574
- const reviewed = this.reviewedDocRevisionOf(key, identity);
569
+ #docRevisionPair(key, doc) {
570
+ const reviewed = this.reviewedDocRevisionOf(key);
575
571
  if (reviewed === null)
576
572
  return null;
577
573
  try {
@@ -590,8 +586,8 @@ export class Ledger {
590
586
  * the review bound, on the ONE persisted basis) and both hash ends. Null when there
591
587
  * is no recorded revision or the document is unreadable: a diagnosis never invents
592
588
  * a fact. */
593
- docDriftHashes(key, doc, identity = null) {
594
- const pair = this.#docRevisionPair(key, doc, identity);
589
+ docDriftHashes(key, doc) {
590
+ const pair = this.#docRevisionPair(key, doc);
595
591
  if (pair === null)
596
592
  return null;
597
593
  return {
@@ -623,11 +619,11 @@ export class Ledger {
623
619
  * re-review resumes the same round (nothing pre-binds). `unbound` (no identity on
624
620
  * record / an unreadable doc) keeps the legacy round/route judgment. */
625
621
  reviewGate(key, doc, type) {
626
- const verdict = this.docLineVerdict(key, doc, type);
622
+ const verdict = this.docLineVerdict(key, doc);
627
623
  if (verdict === "drift")
628
624
  return { kind: "open" };
629
625
  if (verdict === "same") {
630
- const reviewed = this.reviewedDocRevisionOf(key, type);
626
+ const reviewed = this.reviewedDocRevisionOf(key);
631
627
  if (reviewed === null)
632
628
  return { kind: "unbound" };
633
629
  return { kind: "same", pending: this.#pendingFix(key, type), reviewed };
@@ -682,8 +678,11 @@ export class Ledger {
682
678
  // The `--reviews` identity is the ROUTE's own (P31 §2.3): the round read resolves
683
679
  // the FINAL carrier the record names, so a draft beside it never becomes the input
684
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.
685
684
  return {
686
- kind: "fix",
685
+ ...route,
687
686
  reviews: route.reviews ??
688
687
  this.resolveHandoffPath("review", "wave", { tasks: waveKey, round: latestReview }),
689
688
  };
@@ -762,7 +761,7 @@ export class Ledger {
762
761
  const data = this.readProgress();
763
762
  if (data === null)
764
763
  return false;
765
- const row = _a.rowFor(data, key, type);
764
+ const row = _a.rowFor(data, key);
766
765
  if (row === undefined)
767
766
  return false;
768
767
  const reviews = this.#latestLiveCycleOfRow(row, "review");
@@ -862,7 +861,7 @@ export class Ledger {
862
861
  const data = this.readProgress();
863
862
  if (data === null)
864
863
  return false;
865
- const row = _a.rowFor(data, key, type);
864
+ const row = _a.rowFor(data, key);
866
865
  if (row === undefined)
867
866
  return false;
868
867
  return this.#rowClosed(type, type === "wave" ? { tasks: String(key) } : {}, row);
@@ -902,7 +901,7 @@ export class Ledger {
902
901
  const data = this.readProgress();
903
902
  if (data === null)
904
903
  return { kind: "review" };
905
- const row = _a.rowFor(data, key, type);
904
+ const row = _a.rowFor(data, key);
906
905
  if (row === undefined)
907
906
  return { kind: "review" };
908
907
  const reviewLead = targetFaces[type].product.reviewLead;
@@ -1056,11 +1055,11 @@ export class Ledger {
1056
1055
  * with its requesting review's cycle (D28 unchanged). Idempotent: a second stamp of
1057
1056
  * the same record is a no-op rewrite. Returns whether a completed review of that
1058
1057
  * cycle was stamped. */
1059
- supersedeReview(key, type, cycle, byCycle) {
1058
+ supersedeReview(key, cycle, byCycle) {
1060
1059
  const data = this.readProgress();
1061
1060
  if (data === null)
1062
1061
  return false;
1063
- const row = _a.rowFor(data, key, type);
1062
+ const row = _a.rowFor(data, key);
1064
1063
  if (row === undefined)
1065
1064
  return false;
1066
1065
  const records = [...RoundRecords.of(row)];
@@ -1169,15 +1168,13 @@ export class Ledger {
1169
1168
  digest,
1170
1169
  };
1171
1170
  }
1172
- /** The handoff file NAME a read actually resolves — the canonical family name, or a
1173
- * DOCUMENT line's retired `spec` twin when the canonical file is absent (the
1174
- * one-release read alias, P22 D73). The alias reports the name it RESOLVED, not the
1175
- * one it was asked for: a hop that points a later round at this carrier
1176
- * (`--reviews`, `INPUT_REVIEWS`, the criterion's input set) must name the file that
1177
- * exists — a read alias that renamed only the row would leave a never-minted path
1178
- * behind. The alias keys on the line's declared word and never covers the node
1179
- * shapes; it is READ-ONLY (every write goes through `persistHandoff`'s canonical
1180
- * 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. */
1181
1178
  resolveHandoffName(op, type, params = {}) {
1182
1179
  // The attempt the read resolves is the round's LATEST recorded one unless the
1183
1180
  // caller names it: a re-dispatched review lands at `-a{n}`, and its fix leg only
@@ -1191,33 +1188,7 @@ export class Ledger {
1191
1188
  const final = RoundNaming.renderName(_a.#artifactOf(op, type, resolved), "final");
1192
1189
  if (final !== canonical && this.#read(final) !== null)
1193
1190
  return final;
1194
- if (!RETIRED_SPEC_LINE_KEYS.has(type)) {
1195
- return this.#legacyCarrierName(op, type, resolved) ?? canonical;
1196
- }
1197
- if (this.#read(canonical) !== null)
1198
- return canonical;
1199
- const retired = _a.#retiredCarrierName(op, params);
1200
- return this.#read(retired) === null ? canonical : retired;
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;
1191
+ return canonical;
1221
1192
  }
1222
1193
  /** The params one READ resolves under — the caller's attempt when it names one, else
1223
1194
  * the round's latest recorded attempt (a fix leg knows the cycle, not the review's
@@ -1234,13 +1205,10 @@ export class Ledger {
1234
1205
  return this.#workspace.resolve(this.resolveHandoffName(op, type, params));
1235
1206
  }
1236
1207
  /** Read a handoff carrier; null when missing/corrupt. A DOCUMENT-line read falls
1237
- * back to the retired `spec` file name (the one-release read alias, P22 D73): the
1238
- * rounds a line recorded before the vocabulary unification stay judgeable — the
1239
- * closure walk still reads their C5 route, so a closed line does not re-open. The
1240
- * alias keys on the line's declared word (`phase-spec` / `overall` / `single-spec`,
1241
- * the same basis as `rowFor`'s) and never covers the node shapes. Every WRITE goes
1242
- * through `persistHandoff`'s current spelling — the alias is read-only, and the name
1243
- * 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.
1244
1212
  *
1245
1213
  * P31 §2.2 — the read is CHECKED: the (op, type, round) round's latest recorded
1246
1214
  * attempt supplies the digest the engine wrote, and `CarrierIntegrity.read` compares
@@ -1276,7 +1244,7 @@ export class Ledger {
1276
1244
  #latestRecordOf(op, type, params) {
1277
1245
  const mode = RoundRecords.opOf(op) ?? op;
1278
1246
  const round = params.round === undefined ? null : Number(params.round);
1279
- return this.recordsOf(this.#roundKey(type, params), type)
1247
+ return this.recordsOf(this.#roundKey(type, params))
1280
1248
  .filter((record) => record.op === mode)
1281
1249
  .filter((record) => round === null || record.cycle === round)
1282
1250
  .filter((record) => params.attempt === undefined || record.attempt === params.attempt)
@@ -1311,14 +1279,11 @@ export class Ledger {
1311
1279
  const name = this.#resolvedCarrierName(type, key, record);
1312
1280
  return this.#read(name) === null ? "" : this.#workspace.resolve(name);
1313
1281
  }
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. */
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. */
1318
1286
  #resolvedCarrierName(type, key, record) {
1319
- if (key === RETIRED_SPEC_KEY) {
1320
- return _a.#retiredCarrierName(record.op, { round: record.cycle });
1321
- }
1322
1287
  const params = {
1323
1288
  tasks: type === "wave" ? key : undefined,
1324
1289
  round: record.cycle,
@@ -1326,125 +1291,92 @@ export class Ledger {
1326
1291
  };
1327
1292
  return this.resolveHandoffName(record.op, type, params);
1328
1293
  }
1329
- /** The retired document-line carrier name of one round — `spec-review-{round}.json` /
1330
- * `spec-fix-{round}.json`. It lives here, never in the family table: it is a read
1331
- * fallback for already-recorded rounds, not a name the engine can mint. */
1332
- static #retiredCarrierName(op, params) {
1333
- return `${RETIRED_SPEC_KEY}-${op}-${params.round ?? ""}.json`;
1334
- }
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.
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.
1343
1303
  *
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.
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).
1348
1311
  *
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. */
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.
1315
+ *
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.
1324
+ *
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. */
1353
1327
  orphanHandoffs() {
1328
+ const artifacts = this.#artifacts;
1329
+ if (artifacts === null)
1330
+ return [];
1354
1331
  const progress = this.readProgress() ?? this.emptyProgress();
1355
1332
  const orphans = [];
1356
- for (const name of this.#workspaceFiles()) {
1357
- const owner = _a.#handoffOwner(name);
1358
- if (owner === null)
1359
- continue;
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)
1333
+ for (const name of this.#workspace.names()) {
1334
+ const attributed = artifacts.attribute(name);
1335
+ if (attributed === null) {
1365
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);
1366
1346
  }
1367
1347
  return orphans.sort();
1368
1348
  }
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
- }
1382
- /** A handoff file's key as a declared line word — the three document words declare
1383
- * themselves; every other key (a wave's tasks, `plan`, `branch`) declares nothing
1384
- * and reads literally. */
1385
- static #lineWord(key) {
1386
- return RETIRED_SPEC_LINE_KEYS.has(key) ? key : null;
1387
- }
1388
- /** The workspace directory's file names (an absent/unreadable directory is an
1389
- * empty fact — the orphan face degrades, never throws). */
1390
- #workspaceFiles() {
1391
- try {
1392
- return readdirSync(this.#workspace.path, { withFileTypes: true })
1393
- .filter((entry) => entry.isFile())
1394
- .map((entry) => entry.name);
1395
- }
1396
- catch {
1397
- return [];
1398
- }
1399
- }
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) {
1407
- // A FINAL carrier (`<stem>.c{round}.json`, P31 §2.3) is the same artifact as its
1408
- // draft — the cycle is the name's own suffix, never a second family.
1409
- const draft = name.replace(/\.c\d+\.json$/, ".json");
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
- };
1433
- }
1434
- 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);
1435
1372
  }
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);
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 };
1448
1380
  }
1449
1381
  // -------------------------------------------------------------------------
1450
1382
  // crash — the lane crash → recovery record
@@ -1539,7 +1471,7 @@ export class Ledger {
1539
1471
  // cycle 2 (D28). A count comparison would flatten that to 1 and refuse the read.
1540
1472
  // Completion is the recorded VERDICT, never membership — every dispatched round
1541
1473
  // is recorded now, so a failed round's cycle is in register but reads no carrier.
1542
- const recorded = this.recordsOf(this.#roundKey(type, params), type)
1474
+ const recorded = this.recordsOf(this.#roundKey(type, params))
1543
1475
  .filter((record) => record.op === op && record.cycle === round)
1544
1476
  .reduce((latest, record) => latest === undefined || record.attempt >= latest.attempt ? record : latest, undefined);
1545
1477
  if (recorded === undefined || !recorded.verdict.targetAction)