@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.
@@ -43,7 +43,8 @@ import { RepoRoot } from "../infra/root.js";
43
43
  import { ENGINE_RUNTIME } from "../infra/runtime.js";
44
44
  import { SlugIndex } from "../infra/slug-index.js";
45
45
  import { Workspace, WorkspaceRoot } from "../infra/workspace.js";
46
- import { CarrierIntegrity } from "../session/carrier-integrity.js";
46
+ import { ArtifactReads } from "../session/artifact-reads.js";
47
+ import { CarrierIntegrity, CarrierMismatchError } from "../session/carrier-integrity.js";
47
48
  import { Ledger, RoundRecords } from "../session/ledger.js";
48
49
  import { PipelineFrontier } from "../session/pipeline.js";
49
50
  import { PROGRESS_LEGEND, PROGRESS_MARKERS } from "./graph-view.js";
@@ -55,6 +56,11 @@ const VERB_ORDER = ["implement", "review", "branch-review", "fix"];
55
56
  /** The judgement glyphs of one aggregated token (spec §5.3 — the mark is MANDATORY:
56
57
  * `✓` a completed round, `✗` a round that failed its target action). */
57
58
  const JUDGEMENT_MARKERS = { passed: "✓", failed: "✗", recovered: "✗→✓" };
59
+ /** The closed projection — no matrix, default view. The value a caller that observes
60
+ * no artifacts passes (a `null` registry answers zero `art:` rows). */
61
+ export const NO_ARTIFACTS = { registry: null, showAll: false };
62
+ /** The empty slot — one shared value, never a freshly minted arm. */
63
+ const NO_DOC = { kind: "none" };
58
64
  /** The DocKey domain of the `doc-type:` declaration — the declared value must
59
65
  * be one of the four keys; anything else reads null (present facts, never a
60
66
  * fabricated type). Derived from the ONE DocKey declaration (contract/project.ts
@@ -73,6 +79,17 @@ const PHASE_TITLE_MAX = 60;
73
79
  /** The label column of the board's line rows — ` ` + the label padded to this
74
80
  * width (`overall` is the longest verb at 7), so every value starts in one column. */
75
81
  const LABEL_WIDTH = 9;
82
+ /** The `art:` fact block's continuation keys — the board's OWN spelling of the three
83
+ * facts a judgment carries (spec §2.6). Deliberately independent of
84
+ * `Words#artifactIdentity`: that row is the gate's §2.4 contract (`derived: `,
85
+ * a colon inside its own two-space column), while the board's rows are the §2.6
86
+ * contract (`derived`, no colon, the board's continuation column). One source per
87
+ * contract, and the board's half is pinned by its byte assertions. */
88
+ const ARTIFACT_FACT_LABELS = {
89
+ derived: "derived",
90
+ found: "found",
91
+ reason: "reason",
92
+ };
76
93
  /** One board line's carrier facts — the `+N` count's WHOLE read face (spec §2.7 ·
77
94
  * §2.10). The record's path comes from the ledger's ONE accessor, bound to this
78
95
  * line's type + key; ownership excludes a legacy record whose path a later round of
@@ -184,22 +201,70 @@ export class BoardView {
184
201
  * the program overall the identity's `program:` names. An entry that is itself
185
202
  * a plan contributes the plan and resolves its spec by the same slug. The
186
203
  * `programMissing` fact is the phase-spec hard gate: a `program:` that names no
187
- * on-disk overall (or no `program:` at all). Zero filename derivation. */
204
+ * on-disk overall (or no `program:` at all). Zero filename derivation and zero
205
+ * "first document": each slot is the index's SET answer (0 / 1 / n).
206
+ *
207
+ * Naming the entry document on argv (`cdd board --spec` / `--plan`) does NOT
208
+ * exempt its slot from the set: the entry's identity is still its slug, so a
209
+ * second same-class document makes that slot `many` and the row renders the
210
+ * marker plus every declared home. `own` survives only where the set cannot be
211
+ * asked — no legal slug, or an undeclared `doc-type:` that no class can hold. */
188
212
  static #nodeSources(index, entry) {
189
213
  const slug = BoardView.#validSlug(entry);
190
214
  const isPlan = entry.docType === "plan";
191
- const spec = slug === null ? (isPlan ? null : entry) : isPlan ? index.identityDoc(slug) : entry;
192
- const plan = isPlan ? entry : slug === null ? null : index.planOf(slug);
193
- const overall = spec?.docType === "phase-spec" && spec.program !== null
194
- ? index.overallOf(spec.program)
215
+ const own = { kind: "one", entry };
216
+ const spec = slug === null
217
+ ? isPlan
218
+ ? NO_DOC
219
+ : own
220
+ : entry.docType === null
221
+ ? own
222
+ : BoardView.#docSlotOf(index, slug, "identity");
223
+ const plan = slug === null ? (isPlan ? own : NO_DOC) : BoardView.#docSlotOf(index, slug, "plan");
224
+ const specEntry = BoardView.#slotEntry(spec);
225
+ const overall = specEntry?.docType === "phase-spec" && specEntry.program !== null
226
+ ? index.overallOf(specEntry.program)
195
227
  : null;
196
228
  return {
197
229
  spec,
198
230
  plan,
199
231
  overall,
200
- programMissing: spec !== null && BoardView.#programMissing(index, spec),
232
+ programMissing: specEntry !== null && BoardView.#programMissing(index, specEntry),
201
233
  };
202
234
  }
235
+ /** One doc slot — the index's SET answer for a class, filtered and then counted,
236
+ * never searched with `.find`. Two documents of the class are `many`, and every
237
+ * caller renders the marker and the whole set instead of choosing one. */
238
+ static #docSlotOf(index, slug, role) {
239
+ const docs = index
240
+ .docsOf(slug)
241
+ .filter((doc) => role === "plan" ? doc.docType === "plan" : doc.docType !== null && doc.docType !== "plan");
242
+ if (docs.length === 0)
243
+ return NO_DOC;
244
+ if (docs.length === 1)
245
+ return { kind: "one", entry: docs[0] };
246
+ return { kind: "many", found: docs };
247
+ }
248
+ /** The single document a slot carries — `null` for both the empty and the
249
+ * ambiguous arm: neither has ONE document to speak about. */
250
+ static #slotEntry(slot) {
251
+ return slot.kind === "one" ? slot.entry : null;
252
+ }
253
+ /** One document slot's violation marker — the single arm asks `#entryMark` (the ONE
254
+ * duplicate / identity judgment the pre-flight gate shares), and an ambiguous set
255
+ * renders the same `duplicated` marker the doc domain's `read` refuses on. */
256
+ static #slotMark(index, slot, role) {
257
+ if (slot.kind === "one")
258
+ return BoardView.#entryMark(index, slot.entry, role);
259
+ return slot.kind === "many" ? MARK_SLUG_DUPLICATED : null;
260
+ }
261
+ /** The cell of a doc row whose slug names MORE than one document of its class: the
262
+ * existing duplicate marker plus every path of the set. No version, no status, no
263
+ * rounds — those are facts of ONE document, and this identity has none. */
264
+ static #duplicateDocLine(label, found) {
265
+ const paths = found.map((doc) => doc.rel).join(" · ");
266
+ return ` ${label.padEnd(LABEL_WIDTH)}${MARK_SLUG_DUPLICATED} ${paths}`;
267
+ }
203
268
  /** The entry's valid slug — the workspace key, or null when the declaration is
204
269
  * absent or illegal (an illegal value is a violation, never a directory name). */
205
270
  static #validSlug(entry) {
@@ -235,7 +300,7 @@ export class BoardView {
235
300
  * `overall` line). The ledger is the one that OWNS `progress` — a node board reads
236
301
  * the overall line from the program's workspace, never the node's. */
237
302
  static #lineOf(label, key, entry, progress, ledger) {
238
- const rounds = BoardView.#rowRounds(progress, key, entry?.docType ?? null);
303
+ const rounds = BoardView.#rowRounds(progress, key);
239
304
  return {
240
305
  label,
241
306
  version: entry?.version ?? null,
@@ -244,6 +309,8 @@ export class BoardView {
244
309
  rounds,
245
310
  carriers: LineCarriers.ofLedger(ledger, key, key, rounds),
246
311
  marker: null,
312
+ type: key,
313
+ key,
247
314
  };
248
315
  }
249
316
  /** summaryCell(records) — the line's aggregated rounds cell (P24 §12): the SUCCESS
@@ -432,7 +499,7 @@ export class BoardView {
432
499
  // the render face (spec §5.3) — the entry document → board layout + next render
433
500
  // -------------------------------------------------------------------------
434
501
  /** render(readTable, plan, index, entry, repoRoot, words, host, channels, holding,
435
- * next) — the entry document's board (spec §3.1): the entry's declared `doc-type:`
502
+ * next, projection) — the entry document's board (spec §3.1): the declared `doc-type:`
436
503
  * picks the shape — `overall` → the program board, every other type → the node
437
504
  * board. The index supplies every related node (`program:` → overall; same slug →
438
505
  * spec / plan), so no filename grammar participates. `next` is the INJECTED
@@ -451,8 +518,12 @@ export class BoardView {
451
518
  * the wave segment reads. A single-document board is a table of length 1 — its one
452
519
  * row is the argv face's read (solo `--plan`) or the derived face's (`--spec`).
453
520
  * The board therefore holds no plan-reading seam of its own: the ONE read point is
454
- * the injected `PlanSource`, and a value is never re-read here. */
455
- static render(readTable, plan, index, entry, repoRoot, words, host, channels = {}, holding = { kind: "absent" }, next = null) {
521
+ * the injected `PlanSource`, and a value is never re-read here.
522
+ *
523
+ * `projection` is the artifact observation's ONE input (the matrix seam plus the
524
+ * `--artifacts` switch) — the two halves travel together so neither can arrive
525
+ * without the other. */
526
+ static render(readTable, plan, index, entry, repoRoot, words, host, channels = {}, holding = { kind: "absent" }, next = null, projection = NO_ARTIFACTS) {
456
527
  const lines = [`cdd board: ${entry.slug ?? "(none)"}`, ""];
457
528
  // The repo-basis value object — constructed ONCE at this boundary, the ONE
458
529
  // conversion exit the doc cells and the `next:` render normalize their embedded
@@ -461,12 +532,12 @@ export class BoardView {
461
532
  // one form).
462
533
  const root = new RepoRoot(repoRoot);
463
534
  const exitCode = entry.docType === "overall"
464
- ? BoardView.#programBoard(readTable, plan, lines, index, entry, root, words)
535
+ ? BoardView.#programBoard(readTable, plan, lines, index, entry, root, words, projection)
465
536
  : BoardView.#nodeBoard(
466
537
  // A node board is ONE document: the caller's single row. An empty table
467
538
  // means no document was read at all — the seam's own undeclared value is
468
539
  // that read result (no file is opened, so this mints no second read).
469
- readTable[0] ?? plan.readFor(null), plan, lines, index, entry, root, words, host, channels, holding, next);
540
+ readTable[0] ?? plan.readFor(null), plan, lines, index, entry, root, words, host, channels, holding, next, projection);
470
541
  lines.push("", PROGRESS_LEGEND.board);
471
542
  return { lines, exitCode };
472
543
  }
@@ -479,14 +550,18 @@ export class BoardView {
479
550
  * ONE plan value (spec §2.1): the plan row, the wave row and the `! no-spec`
480
551
  * spec row all take their facts from it, so the document the board names and
481
552
  * the document it read are one fact. */
482
- static #nodeBoard(read, plan, lines, index, entry, root, words, host, channels, holding, next) {
553
+ static #nodeBoard(read, plan, lines, index, entry, root, words, host, channels, holding, next, projection) {
483
554
  const repoRoot = root.absolute;
484
555
  const sources = BoardView.#nodeSources(index, entry);
485
556
  const nodeSlug = BoardView.#validSlug(entry);
486
- const ledger = nodeSlug === null ? null : BoardView.#ledgerOf(plan, nodeSlug, repoRoot);
557
+ const nodeSeat = nodeSlug === null ? null : BoardView.#ledgerOf(plan, nodeSlug, repoRoot, projection.registry);
558
+ const ledger = nodeSeat?.ledger ?? null;
487
559
  const progress = ledger?.readProgress() ?? null;
488
560
  const overallSlug = BoardView.#validSlug(sources.overall);
489
- const overallLedger = overallSlug === null ? null : BoardView.#ledgerOf(plan, overallSlug, repoRoot);
561
+ const overallSeat = overallSlug === null
562
+ ? null
563
+ : BoardView.#ledgerOf(plan, overallSlug, repoRoot, projection.registry);
564
+ const overallLedger = overallSeat?.ledger ?? null;
490
565
  const overallProgress = overallLedger?.readProgress() ?? null;
491
566
  // The tree's dispatch fact + the node workspace's orphan drafts + the node's
492
567
  // crashed rounds render before the line rows (a reader answers "is anyone working
@@ -505,23 +580,25 @@ export class BoardView {
505
580
  // identity breakage outranks the read value, so neither the plan row nor the spec
506
581
  // row asks a `PlanRead` accessor, and no `! no-spec` literal (the orphan fold or
507
582
  // the degraded wave row) can appear beside a broken identity.
508
- const specMark = BoardView.#entryMark(index, sources.spec, "identity") ??
583
+ const specMark = BoardView.#slotMark(index, sources.spec, "identity") ??
509
584
  (sources.programMissing ? MARK_PROGRAM_MISSING : null);
510
- const planMark = BoardView.#entryMark(index, sources.plan, "plan");
585
+ const planMark = BoardView.#slotMark(index, sources.plan, "plan");
586
+ const specEntry = BoardView.#slotEntry(sources.spec);
587
+ const planEntry = BoardView.#slotEntry(sources.plan);
511
588
  const planIdentityClean = planMark === null;
512
589
  const identityClean = planIdentityClean && specMark === null;
513
590
  const docRows = [
514
591
  {
515
592
  label: "overall",
516
- entry: sources.overall,
593
+ slot: sources.overall === null ? NO_DOC : { kind: "one", entry: sources.overall },
517
594
  line: BoardView.#lineOf("overall", "overall", sources.overall, overallProgress, overallLedger),
518
595
  mark: BoardView.#entryMark(index, sources.overall, "identity"),
519
596
  override: null,
520
597
  },
521
598
  {
522
599
  label: "spec",
523
- entry: sources.spec,
524
- line: BoardView.#lineOf("spec", BoardView.#lineWordOf(sources.spec), sources.spec, progress, ledger),
600
+ slot: sources.spec,
601
+ line: BoardView.#lineOf("spec", BoardView.#lineWordOf(specEntry), specEntry, progress, ledger),
525
602
  mark: specMark,
526
603
  // The reverse-lookup orphan's spec row (spec §2.7 ①): the identity-clean
527
604
  // row bypasses `#entryMark` / `#docCell` accounting — landing in the mark
@@ -530,24 +607,29 @@ export class BoardView {
530
607
  },
531
608
  {
532
609
  label: "plan",
533
- entry: sources.plan,
534
- line: BoardView.#lineOf("plan", "plan", sources.plan, progress, ledger),
610
+ slot: sources.plan,
611
+ line: BoardView.#lineOf("plan", "plan", planEntry, progress, ledger),
535
612
  mark: planMark,
536
- override: BoardView.#planCellOf(read, sources.plan, planMark, words),
613
+ override: BoardView.#planCellOf(read, planEntry, planMark, words),
537
614
  },
538
615
  ];
539
616
  // The doc-name column is fixed-width: every name is padded to the widest one, so
540
617
  // the version column aligns down the block (spec §5.3).
541
- const nameWidth = Math.max(0, ...docRows
542
- .filter((row) => row.entry !== null)
543
- .map((row) => path.basename(row.entry.path).length));
618
+ const nameWidth = Math.max(0, ...docRows.flatMap((row) => row.slot.kind === "one" ? [path.basename(row.slot.entry.path).length] : []));
544
619
  let blocked = false;
545
620
  for (const row of docRows) {
621
+ // An ambiguous set is its own row: the marker plus every path, never one
622
+ // document's header facts (spec §2.3 — the read face answers a set with a set).
623
+ if (row.slot.kind === "many") {
624
+ lines.push(BoardView.#duplicateDocLine(row.label, row.slot.found));
625
+ blocked = true;
626
+ continue;
627
+ }
546
628
  if (row.override !== null) {
547
629
  lines.push(` ${row.label.padEnd(LABEL_WIDTH)}${row.override}`.trimEnd());
548
630
  continue;
549
631
  }
550
- const cell = BoardView.#docCell(row.entry, row.line, nameWidth, row.mark);
632
+ const cell = BoardView.#docCell(BoardView.#slotEntry(row.slot), row.line, nameWidth, row.mark);
551
633
  lines.push(` ${row.label.padEnd(LABEL_WIDTH)}${cell.text}`.trimEnd());
552
634
  blocked ||= cell.blocked;
553
635
  }
@@ -560,11 +642,13 @@ export class BoardView {
560
642
  // render, so a reader can tell a missing plan from a plan that does not read.
561
643
  const specAbsent = read.orphan()?.cause === "spec-absent";
562
644
  const degraded = specAbsent && !planIdentityClean ? null : read.degradedWaveRow(words);
645
+ // The wave segment is derived ONCE — the rendered rows and the `art:` projection's
646
+ // record set read the same lines (never a second derivation over the same read).
647
+ const waves = degraded === null ? BoardView.#waveLines(read, progress, ledger) : [];
563
648
  if (degraded !== null) {
564
649
  lines.push(` ${"wave".padEnd(LABEL_WIDTH)}${degraded}`);
565
650
  }
566
651
  else {
567
- const waves = BoardView.#waveLines(read, progress, ledger);
568
652
  if (waves.length === 0) {
569
653
  lines.push(` ${"wave".padEnd(LABEL_WIDTH)}(none)`);
570
654
  }
@@ -585,7 +669,7 @@ export class BoardView {
585
669
  // (`Ledger#lineStateAt`, identity document = the plan): a drifted plan reopens the
586
670
  // branch face, so the mark can never print `✔ closed` while `next:` names the
587
671
  // review the gate accepts — the reopened line renders as the CURRENT face (`▶`).
588
- const branchState = ledger?.lineStateAt("branch", "branch", sources.plan?.path ?? null) ?? "open";
672
+ const branchState = ledger?.lineStateAt("branch", "branch", planEntry?.path ?? null) ?? "open";
589
673
  const branchMark = branchState === "closed"
590
674
  ? `${PROGRESS_MARKERS.done} closed`
591
675
  : branchState === "reopened"
@@ -593,6 +677,23 @@ export class BoardView {
593
677
  : `${PROGRESS_MARKERS.pending} open`;
594
678
  const branchRounds = BoardView.summaryCell(branchLine.rounds, branchLine.carriers);
595
679
  lines.push(` ${"branch".padEnd(LABEL_WIDTH)}${branchMark}${branchRounds === "" ? "" : ` ${branchRounds}`}`.trimEnd());
680
+ // The `art:` fact block — the artifact inventory this node's rounds resolve to,
681
+ // rendered AFTER the line rows and BEFORE `next:` / `reason:` (the two last rows
682
+ // stay last, spec §2.6). A healthy tree adds zero bytes: only a `misplaced` /
683
+ // `invalid` judgment prints, and `--artifacts` alone opens the full inventory. The
684
+ // block never joins the tail counts — the findings axis and the artifact axis are
685
+ // two axes.
686
+ const artifactRows = BoardView.#artifactRows(BoardView.#artifactScopes({
687
+ docLines: docRows.map((row) => row.line),
688
+ waves,
689
+ branchLine,
690
+ nodeSeat,
691
+ overallSeat,
692
+ }), projection);
693
+ if (artifactRows.length > 0) {
694
+ lines.push("");
695
+ lines.push(...artifactRows);
696
+ }
596
697
  lines.push("");
597
698
  if (next === null) {
598
699
  lines.push(" next: (none)");
@@ -609,11 +710,21 @@ export class BoardView {
609
710
  * never participates in next, spec §6.5). The phase set derives from the ONE
610
711
  * index (`program:` grouping — no overall child-list array). A phase row's primary
611
712
  * key is its `slug:`, annotated with the truncated `title:`; any overall/phase
612
- * violation renders its marker and exits 2 (spec §3.1 — zero silent fallback). */
613
- static #programBoard(readTable, plan, lines, index, entry, root, words) {
713
+ * violation renders its marker and exits 2 (spec §3.1 — zero silent fallback).
714
+ *
715
+ * The `art:` projection is the SAME one the node board renders (spec §2.4 · §2.6):
716
+ * the overall line is dispatched from the program workspace, so its own review
717
+ * rounds are the rounds a docs-fix gate judges, and the board must show that
718
+ * judgment before the dispatch. The scope binds the overall line to the program
719
+ * seat — the seat this render already holds — and `--artifacts` therefore opens the
720
+ * same inventory view here as on a node board (never a silent no-op). */
721
+ static #programBoard(readTable, plan, lines, index, entry, root, words, projection) {
614
722
  const repoRoot = root.absolute;
615
723
  const overallSlug = BoardView.#validSlug(entry);
616
- const ledger = overallSlug === null ? null : BoardView.#ledgerOf(plan, overallSlug, repoRoot);
724
+ const seat = overallSlug === null
725
+ ? null
726
+ : BoardView.#ledgerOf(plan, overallSlug, repoRoot, projection.registry);
727
+ const ledger = seat?.ledger ?? null;
617
728
  const overallLine = BoardView.#lineOf("overall", "overall", entry, ledger?.readProgress() ?? null, ledger);
618
729
  const overallDoc = BoardView.#docCell(entry, overallLine, path.basename(entry.path).length, BoardView.#entryMark(index, entry, "identity"));
619
730
  lines.push(` ${"overall".padEnd(LABEL_WIDTH)}${overallDoc.text}`);
@@ -630,15 +741,18 @@ export class BoardView {
630
741
  throw new Error("cdd: the board's per-phase plan table is shorter than its phase list");
631
742
  const read = readTable[pos];
632
743
  const phaseSlug = BoardView.#validSlug(phase);
633
- const phaseLedger = phaseSlug === null ? null : BoardView.#ledgerOf(plan, phaseSlug, repoRoot);
744
+ const phaseLedger = phaseSlug === null
745
+ ? null
746
+ : BoardView.#ledgerOf(plan, phaseSlug, repoRoot, projection.registry).ledger;
634
747
  const phaseProgress = phaseLedger?.readProgress() ?? null;
635
748
  const specLine = BoardView.#lineOf("spec", "phase-spec", phase, phaseProgress, phaseLedger);
636
- const planEntry = phaseSlug === null ? null : index.planOf(phaseSlug);
749
+ const planSlot = phaseSlug === null ? NO_DOC : BoardView.#docSlotOf(index, phaseSlug, "plan");
750
+ const planEntry = BoardView.#slotEntry(planSlot);
637
751
  const planLine = BoardView.#lineOf("plan", "plan", planEntry, phaseProgress, phaseLedger);
638
752
  const branchLine = BoardView.#roundsLine("branch", "branch", phaseProgress, phaseLedger);
639
753
  const mark = BoardView.#entryMark(index, phase, "identity") ??
640
754
  (BoardView.#programMissing(index, phase) ? MARK_PROGRAM_MISSING : null);
641
- const planMark = BoardView.#entryMark(index, planEntry, "plan");
755
+ const planMark = BoardView.#slotMark(index, planSlot, "plan");
642
756
  blocked ||= mark !== null || planMark !== null;
643
757
  const status = mark ?? phase.status ?? "Pending";
644
758
  // The phase's wave summary token (spec §5.3): the wave segment's first wave
@@ -648,10 +762,15 @@ export class BoardView {
648
762
  // `""` only for a true undeclared phase, and null hands the healthy cell back
649
763
  // to today's derivation.
650
764
  const waveCell = read.cell(words) ?? BoardView.#waveCellOf(read, phaseProgress, phaseLedger);
765
+ // The plan cell of a phase whose slug names TWO plans: the marker plus both
766
+ // paths, never the first plan's summary (spec §2.3 — a set is answered by a set).
767
+ const planCell = planSlot.kind === "many"
768
+ ? [MARK_SLUG_DUPLICATED, planSlot.found.map((doc) => doc.rel).join(" · ")].join(" ")
769
+ : BoardView.summaryCell(planLine.rounds, planLine.carriers);
651
770
  const parts = [];
652
771
  const cells = [
653
772
  ["spec", BoardView.summaryCell(specLine.rounds, specLine.carriers)],
654
- ["plan", BoardView.summaryCell(planLine.rounds, planLine.carriers)],
773
+ ["plan", planCell],
655
774
  ["wave", waveCell],
656
775
  ["branch", BoardView.summaryCell(branchLine.rounds, branchLine.carriers)],
657
776
  ];
@@ -662,6 +781,15 @@ export class BoardView {
662
781
  const note = BoardView.#titleNote(phase.title);
663
782
  lines.push(` phase ${phase.slug ?? "(none)"} ${status}${tail === "" ? "" : ` ${tail}`}${note === "" ? "" : ` title: ${note}`}`);
664
783
  }
784
+ // The `art:` fact block, after the phase rows and before the rows that stay last
785
+ // (spec §2.6). One scope: the overall line, bound to the program seat — a phase's
786
+ // rounds belong to the phase's own board, exactly as a node board reads the
787
+ // program line through the program seat alone.
788
+ const artifactRows = BoardView.#artifactRows(seat === null ? [] : [{ lines: [overallLine], seat }], projection);
789
+ if (artifactRows.length > 0) {
790
+ lines.push("");
791
+ lines.push(...artifactRows);
792
+ }
665
793
  lines.push("");
666
794
  lines.push(" next: done");
667
795
  return blocked ? 2 : 0;
@@ -747,16 +875,146 @@ export class BoardView {
747
875
  cells.push(rounds);
748
876
  return { text: cells.join(" "), blocked: false };
749
877
  }
878
+ // -------------------------------------------------------------------------
879
+ // the artifact projection (spec §2.6) — the matrix's judgment as an `art:` fact row
880
+ // -------------------------------------------------------------------------
881
+ /** The `art:` projection's scopes — the node's own lines bound to the node seat and
882
+ * the program's overall line bound to the program seat. The board OBSERVES names;
883
+ * it never mints one: every observed round's carrier path comes from the ledger's
884
+ * ONE accessor and every judgment from `ArtifactReads`. One record in, one scope set
885
+ * out (the two seats are told apart by name, never by argument position). */
886
+ static #artifactScopes(input) {
887
+ const scopes = [];
888
+ const overall = input.docLines[0];
889
+ if (input.overallSeat !== null && overall !== undefined) {
890
+ scopes.push({ lines: [overall], seat: input.overallSeat });
891
+ }
892
+ if (input.nodeSeat !== null) {
893
+ scopes.push({
894
+ lines: [...input.docLines.slice(1), ...input.waves, input.branchLine],
895
+ seat: input.nodeSeat,
896
+ });
897
+ }
898
+ return scopes;
899
+ }
900
+ /** The `art:` fact rows — one observed REVIEW round per record of each scope's lines,
901
+ * in `(cycle, attempt)` order. The observed set is the record sequence, never the
902
+ * workspace's name list: a `*.rulings.json` no record claims stays an `orphan:`
903
+ * observation and never enters this block (one name, one face). The judgment is the
904
+ * dispatch gate's own kind — `rulings` — read through the frame-free seam, so the
905
+ * board composes nothing a gate would compose differently.
906
+ *
907
+ * Default (no `--artifacts`): only the anomalous rounds render, so a healthy tree
908
+ * adds zero bytes. `--artifacts` opens the whole inventory: one row per observed
909
+ * round, one column per kind. */
910
+ static #artifactRows(scopes, projection) {
911
+ const artifacts = projection.registry;
912
+ if (artifacts === null)
913
+ return [];
914
+ const reads = (seat) => new ArtifactReads(artifacts, seat.workspace);
915
+ const observed = scopes.flatMap((scope) => BoardView.#observedOf(scope, artifacts, reads(scope.seat)));
916
+ observed.sort((left, right) => left.cycle - right.cycle || left.attempt - right.attempt);
917
+ return observed.flatMap((entry) => BoardView.#artifactBlockOf(entry, projection.showAll));
918
+ }
919
+ /** One scope's observed review rounds — the round records carrying a resolvable
920
+ * carrier, each read through the seam. A tampered carrier (a digest mismatch) is the
921
+ * `invalid` arm carrying the integrity message, never a thrown board. */
922
+ static #observedOf(scope, artifacts, reads) {
923
+ const basis = scope.seat.workspace.root.basis;
924
+ const observed = [];
925
+ for (const line of scope.lines) {
926
+ for (const record of line.rounds) {
927
+ if (record.op !== "review")
928
+ continue;
929
+ const carrier = scope.seat.ledger.carrierPathOf(line.type, line.key, record);
930
+ if (carrier === "")
931
+ continue;
932
+ observed.push({
933
+ line: BoardView.#artifactLineOf(artifacts, carrier, line.type),
934
+ kind: "rulings",
935
+ cycle: record.cycle,
936
+ attempt: record.attempt,
937
+ read: BoardView.#artifactReadOf(reads, carrier, record.carrierDigest ?? null),
938
+ relName: (name) => basis.relativize(scope.seat.workspace.resolve(name)),
939
+ relPath: (value) => basis.relativize(value),
940
+ });
941
+ }
942
+ }
943
+ return observed;
944
+ }
945
+ /** The observed round's line word — the carrier's OWN attributed identity (the
946
+ * reviewed round), falling back to the rendering line's word for a name the matrix
947
+ * cannot place. */
948
+ static #artifactLineOf(artifacts, carrier, fallback) {
949
+ const attributed = artifacts.attribute(path.basename(carrier));
950
+ return attributed !== null && attributed.identity.domain === "round"
951
+ ? attributed.identity.line
952
+ : fallback;
953
+ }
954
+ /** One composed read, with the integrity refusal folded into the `invalid` arm: a
955
+ * tampered carrier is a fact the board reports, never a crash of the read face. */
956
+ static #artifactReadOf(reads, carrier, digest) {
957
+ try {
958
+ return reads.read("rulings", carrier, digest);
959
+ }
960
+ catch (raw) {
961
+ if (!(raw instanceof CarrierMismatchError))
962
+ throw raw;
963
+ return { read: { kind: "invalid", path: "", reason: raw.message }, rulings: [] };
964
+ }
965
+ }
966
+ /** One observed round's `art:` block — the fact row plus its continuation lines. The
967
+ * default face prints anomalies alone; `--artifacts` prints every observed round and
968
+ * names its coordinate, so a troubleshooting view is one row per round while the
969
+ * daily view keeps its bytes. */
970
+ static #artifactBlockOf(entry, showAll) {
971
+ const read = entry.read.read;
972
+ const anomalous = read.kind === "misplaced" || read.kind === "invalid";
973
+ if (!showAll && !anomalous)
974
+ return [];
975
+ const coordinate = showAll ? ` · c${entry.cycle}·a${entry.attempt}` : "";
976
+ const arm = anomalous ? `! ${read.kind}` : read.kind;
977
+ const header = ` ${"art:".padEnd(LABEL_WIDTH)}${entry.line} · ${entry.kind}${coordinate} ${arm}`;
978
+ return [header, ...BoardView.#artifactFactsOf(entry, read)];
979
+ }
980
+ /** One `art:` block's continuation lines — the same facts the dispatch gate's
981
+ * `derived:` / `found:` report prints, on the board's own 9-column continuation
982
+ * shape. A healthy round carries none.
983
+ *
984
+ * The labels come from `ARTIFACT_FACT_LABELS`, NOT from `Words#artifactIdentity`:
985
+ * the two faces are two pinned contracts with different bytes — §2.4 fixes the
986
+ * gate's rows as ` derived: <value>` (colon, two-space column) while §2.6 fixes
987
+ * the board's as ` derived <value>` (no colon, the board's own
988
+ * continuation column). Sharing a label source would force one contract's bytes
989
+ * into the other; the words are therefore deliberately re-declared here once and
990
+ * pinned by the board's byte assertions. */
991
+ static #artifactFactsOf(entry, read) {
992
+ const labels = ARTIFACT_FACT_LABELS;
993
+ const value = (key, fact) => ` ${key.padEnd(LABEL_WIDTH)}${fact}`;
994
+ if (read.kind === "misplaced") {
995
+ const found = read.found.map((name) => entry.relName(name)).join(" · ");
996
+ return [value(labels.derived, entry.relName(read.derived)), value(labels.found, found)];
997
+ }
998
+ if (read.kind === "invalid") {
999
+ const derived = read.path === "" ? [] : [value(labels.derived, entry.relPath(read.path))];
1000
+ return [...derived, value(labels.reason, read.reason)];
1001
+ }
1002
+ return [];
1003
+ }
750
1004
  /** The node's ledger — the progress.json read face the render's closure/next
751
1005
  * derivation consumes (each node reads its OWN workspace). The plan read seam is
752
1006
  * the caller's per-command instance, threaded down unchanged: the board never
753
1007
  * mints a second `PlanSource`. */
754
- static #ledgerOf(plan, nodeSlug, repoRoot) {
1008
+ static #ledgerOf(plan, nodeSlug, repoRoot, artifacts = null) {
755
1009
  const root = new WorkspaceRoot(repoRoot, ENGINE_RUNTIME.handoffNamespace.workspaceRoot);
756
- return new Ledger(new Workspace(root, nodeSlug), new ConfigLoader(), plan);
1010
+ // ONE workspace instance per node: the ledger resolves names inside it and the
1011
+ // `art:` projection's read seam takes the SAME instance (`ArtifactReads` binds its
1012
+ // base at construction), so a board never observes two spellings of one directory.
1013
+ const workspace = new Workspace(root, nodeSlug);
1014
+ return { ledger: new Ledger(workspace, new ConfigLoader(), plan, artifacts), workspace };
757
1015
  }
758
- /** pipelineFacts(read, plan, index, entry, root) — the board's FACTS about the
759
- * pipeline (spec §5.2): the node's ledger and the pipeline frontier's declared
1016
+ /** pipelineFacts(read, plan, index, entry, root, projection) — the board's FACTS
1017
+ * about the pipeline (spec §5.2): the node's ledger and the pipeline frontier's declared
760
1018
  * input (the spec word and path, the plan path, the plan read). The board reports
761
1019
  * facts only — the per-face observations and the four face-order rules live in the
762
1020
  * session plane's `PipelineFrontier`. Null when the node holds no legal slug (no
@@ -765,22 +1023,22 @@ export class BoardView {
765
1023
  * `read` is the caller's ONE plan read (the same `PlanSource` instance): the
766
1024
  * frontier's graph input is the value's own `graph()`, and the declared `planPath`
767
1025
  * is that same value's `stationPath()` — the document the board read and the path
768
- * the frontier receives are ONE fact, with no fallback to `index.planOf(slug)`.
1026
+ * the frontier receives are ONE fact, with no fallback to a second plan lookup.
769
1027
  * The wave segment reads the same value through `#waveLines`; the board has no
770
1028
  * second plan read point. */
771
- static pipelineFacts(read, plan, index, entry, root) {
1029
+ static pipelineFacts(read, plan, index, entry, root, projection = NO_ARTIFACTS) {
772
1030
  const nodeSlug = BoardView.#validSlug(entry);
773
1031
  if (nodeSlug === null)
774
1032
  return null;
775
- const ledger = BoardView.#ledgerOf(plan, nodeSlug, root.absolute);
1033
+ const ledger = BoardView.#ledgerOf(plan, nodeSlug, root.absolute, projection.registry).ledger;
776
1034
  const sources = BoardView.#nodeSources(index, entry);
777
- const specPath = sources.spec?.path ?? null;
1035
+ const specPath = BoardView.#slotEntry(sources.spec)?.path ?? null;
778
1036
  // The path the frontier receives IS the path of the document this read opened —
779
1037
  // never a second index-derived candidate that could name another file.
780
1038
  const planPath = read.stationPath();
781
1039
  // The identity line's OWN word — the document's DECLARED `doc-type:` — keys the
782
1040
  // line and names the pipeline station (`single-spec` closes onto its `done` row).
783
- const specType = BoardView.#lineWordOf(sources.spec);
1041
+ const specType = BoardView.#lineWordOf(BoardView.#slotEntry(sources.spec));
784
1042
  return {
785
1043
  ledger,
786
1044
  input: { specType, specPath, planPath, plan: read },
@@ -797,16 +1055,18 @@ export class BoardView {
797
1055
  rounds,
798
1056
  carriers: LineCarriers.ofLedger(ledger, key, key, rounds),
799
1057
  marker: null,
1058
+ type: key,
1059
+ key,
800
1060
  };
801
1061
  }
802
1062
  /** The node's round RECORDS for one key — read through the ledger's ONE row lookup
803
- * (`Ledger.rowFor`: the retired `spec` row reads as the line its workspace DECLARES)
804
- * and the ONE record normalizer (`RoundRecords.of`, legacy forms folded); the
1063
+ * (`Ledger.rowFor`, literal: a retired `spec` row answers no document word) and the
1064
+ * ONE record normalizer (`RoundRecords.of`, legacy COUNT forms folded); the
805
1065
  * aggregation and the judgement glyphs read these records, never a pre-grouped cycle
806
1066
  * map. Failed rounds stay on the board (they consumed an identity slot); an absent row
807
1067
  * yields an empty list. */
808
- static #rowRounds(progress, key, identity = null) {
809
- const row = progress === null ? undefined : Ledger.rowFor(progress, key, identity);
1068
+ static #rowRounds(progress, key) {
1069
+ const row = progress === null ? undefined : Ledger.rowFor(progress, key);
810
1070
  return RoundRecords.of(row);
811
1071
  }
812
1072
  /** The node's wave segment — one line per derived wave (its ✔/▶/○ marker rides the
@@ -841,6 +1101,8 @@ export class BoardView {
841
1101
  rounds,
842
1102
  carriers: LineCarriers.ofLedger(ledger, "wave", key, rounds),
843
1103
  marker,
1104
+ type: "wave",
1105
+ key,
844
1106
  };
845
1107
  });
846
1108
  }
@@ -859,16 +1121,22 @@ export class BoardNext {
859
1121
  /** The board's ONE `NextHop` — null when the entry holds no legal slug (no
860
1122
  * workspace to observe), when the board is the program board (cross-phase never
861
1123
  * participates in next, spec §6.5), or when the plan read carries no evidence to
862
- * route on (spec §2.3): an `unreadable` plan and a `spec-absent` orphan
863
- * short-circuit to the existing hop-less shape (` next: (none)`, no `reason:`
864
- * row). The predicate is the SAME pair §2.3 uses, never a third condition;
865
- * `undeclared` is NOT in it ("spec written, no plan yet" is the standing
866
- * `kairos:cdd-plan` route) and `slug-absent` is not either (the identity channel
867
- * owns its exit code). */
868
- static of(read, plan, index, entry, root) {
1124
+ * route on (spec §2.3): an `unreadable` plan, a `spec-absent` orphan and the
1125
+ * `duplicated` set short-circuit to the existing hop-less shape (` next:
1126
+ * (none)`, no `reason:` row). The predicate is the SAME pair §2.3 uses, never a
1127
+ * third condition; `undeclared` is NOT in it ("spec written, no plan yet" is the
1128
+ * standing `kairos:cdd-plan` route — and so is the undecided read, whose board
1129
+ * bytes are today's) and `slug-absent` is not either (the identity channel owns
1130
+ * its exit code). The duplicated set is not: two plans answer no single
1131
+ * document, so the plan route may not be printed (§2.7 (d)). */
1132
+ static of(read, plan, index, entry, root, projection = NO_ARTIFACTS) {
1133
+ if (read.kind === "duplicated")
1134
+ return null;
869
1135
  if (read.kind === "unreadable" || read.orphan()?.cause === "spec-absent")
870
1136
  return null;
871
- const facts = entry.docType === "overall" ? null : BoardView.pipelineFacts(read, plan, index, entry, root);
1137
+ const facts = entry.docType === "overall"
1138
+ ? null
1139
+ : BoardView.pipelineFacts(read, plan, index, entry, root, projection);
872
1140
  return facts === null ? null : BoardNext.#hopOf(facts, root);
873
1141
  }
874
1142
  /** The session plane's ONE assembly, called with the board's facts and the face