mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/dead-exports-knip.js

@@ -75,11 +75,80 @@ export function readKnipOutput(filePath) {
   }
 }
 
+/**
+ * Sentinel `symbol` recorded for a **whole-file death** row.
+ *
+ * Knip's `files` category names a module nothing in the graph imports. There
+ * is no per-export identity to record — the whole file is the finding — so the
+ * ratchet encodes exactly one row per dead file carrying this symbol. `*` is
+ * not a legal JavaScript identifier, so a whole-file row can never collide
+ * with a real export row for the same path.
+ */
+const WHOLE_FILE_SYMBOL = '*';
+
+/**
+ * Pull the dead-file paths out of one knip issue's `files` category.
+ *
+ * Knip emits `files: [{ name: '<path>' }]`, but tolerate a bare string and
+ * fall back to the issue's own `file` so a reporter-shape change degrades to
+ * "one row for this path" rather than to silence.
+ *
+ * @param {{ files?: unknown }} issue
+ * @param {string} fallbackFile The issue's own `file` path.
+ * @returns {string[]}
+ */
+function extractDeadFileNames(issue, fallbackFile) {
+  const entries = Array.isArray(issue.files) ? issue.files : [];
+  const names = [];
+  for (const entry of entries) {
+    const name =
+      (typeof entry === 'string' && entry) ||
+      (entry && typeof entry.name === 'string' && entry.name) ||
+      fallbackFile;
+    if (typeof name === 'string' && name.length > 0) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * Pull the dead-export symbol names out of one knip issue's `exports`
+ * category. Knip emits `exports: [{ name, ... }]`; older shapes used `symbol`.
+ *
+ * @param {{ exports?: unknown }} issue
+ * @returns {string[]}
+ */
+function extractDeadExportSymbols(issue) {
+  const entries = Array.isArray(issue.exports) ? issue.exports : [];
+  const symbols = [];
+  for (const e of entries) {
+    const symbol =
+      (e && typeof e.name === 'string' && e.name) ||
+      (e && typeof e.symbol === 'string' && e.symbol) ||
+      null;
+    if (symbol) symbols.push(symbol);
+  }
+  return symbols;
+}
+
 /**
  * Flatten knip's `--reporter json` output into `{ file, symbol }` rows. Knip
- * emits `{ issues: [{ file, exports: [{ name, ... }], ... }, ...] }`. Only
- * `exports` rows are mapped — the ratchet ignores file-, dependency- and
- * duplicate-level issues, which knip surfaces under separate `rules` keys.
+ * emits `{ issues: [{ file, files: [...], exports: [{ name, ... }], ... }] }`.
+ *
+ * Two categories are mapped, and the ratchet treats their rows identically:
+ *
+ * - **`exports`** → one row per unused export, `{ file, symbol: '<name>' }`.
+ * - **`files`** → one row per module nothing imports,
+ *   `{ file, symbol: '*' }`. Story #5001 added this leg: mapping only
+ *   `exports` made the ratchet structurally blind to *whole-file* death, so a
+ *   module could lose its last caller and every one of its exports go unused
+ *   without a single row changing. Knip reports such a module once, under
+ *   `files`, and suppresses its per-export rows — which is exactly why the
+ *   export-only reading saw nothing.
+ *
+ * Whole-file rows are de-duplicated by path so the row set is stable across
+ * runs regardless of how many issue records mention the same file. Dependency-
+ * and duplicate-level issues stay ignored; knip surfaces those under their own
+ * `rules` keys and they are not a code-death signal.
  *
  * @param {unknown} knipEnvelope The parsed knip JSON report.
  * @returns {Array<{ file: string, symbol: string }>}
@@ -88,16 +157,16 @@ export function extractRowsFromKnip(knipEnvelope) {
   const rows = [];
   if (!knipEnvelope || typeof knipEnvelope !== 'object') return rows;
   const issues = Array.isArray(knipEnvelope.issues) ? knipEnvelope.issues : [];
+  const seenDeadFiles = new Set();
   for (const issue of issues) {
     const file = issue?.file;
     if (typeof file !== 'string' || file.length === 0) continue;
-    const exports_ = Array.isArray(issue.exports) ? issue.exports : [];
-    for (const e of exports_) {
-      const symbol =
-        (e && typeof e.name === 'string' && e.name) ||
-        (e && typeof e.symbol === 'string' && e.symbol) ||
-        null;
-      if (!symbol) continue;
+    for (const name of extractDeadFileNames(issue, file)) {
+      if (seenDeadFiles.has(name)) continue;
+      seenDeadFiles.add(name);
+      rows.push({ file: name, symbol: WHOLE_FILE_SYMBOL });
+    }
+    for (const symbol of extractDeadExportSymbols(issue)) {
       rows.push({ file, symbol });
     }
   }

package/.agents/scripts/lib/degraded-mode.js

@@ -3,8 +3,8 @@
  *
  * Tech Spec #819 §"Degraded-mode contract (Story 3)" — three soft-fail sites
  * (audit-suite selector diff-timeout, lint-baseline JSON-parse, baseline-refresh
- * guardrail git-diff) historically returned a silent zero/empty result. The
- * new contract is:
+ * guardrail git-diff) historically returned a silent zero/empty result. Two
+ * remain; the lint-baseline site left with its CLI. The contract is:
  *
  *   { ok: false, degraded: true, reason: <code>, detail: <human> }
  *

package/.agents/scripts/lib/dependency-parser.js

@@ -7,18 +7,31 @@
  * lib/story-adjacency.js, lib/branch-name-guard.js).
  */
 
+import { parseFooterBlockedByIds } from './story-body/footer-block.js';
+
 /**
- * Parse `blocked by #NNN` and `depends on #NNN` references from text.
- * Handles case-insensitive variations.
+ * Parse a body's declared blocker issue numbers — **footer-scoped and
+ * strict**.
+ *
+ * Only a `blocked by #N` line standing alone inside the `---` footer block
+ * declares an edge. The unanchored predecessor scanned the whole body for
+ * `blocked by|depends on #N` anywhere, so a Story whose prose merely mentioned
+ * a blocker — an example, a changelog note, an acceptance criterion describing
+ * this very defect — minted a real dispatch gate that withheld the Story until
+ * an unrelated issue closed.
+ *
+ * The behaviour change is deliberate and user-visible: prose-only mentions
+ * outside the footer no longer gate. Every machine-authored body already
+ * carries the canonical footer form (`plan-persist` has always serialized it),
+ * so only hand-written prose edges are affected — those must be moved into the
+ * footer block to keep gating. The grammar itself lives in
+ * `lib/story-body/footer-block.js`, shared with the body parser.
  *
  * @param {string} body - Issue body or freeform text.
- * @returns {number[]} Array of issue numbers this text declares as blockers.
+ * @returns {number[]} Array of issue numbers this body declares as blockers.
  */
 export function parseBlockedBy(body) {
-  if (!body) return [];
-  const re = /(?:blocked\s+by|depends\s+on):?\s+#(\d+)/gi;
-  const ids = [...body.matchAll(re)].map((m) => Number.parseInt(m[1], 10));
-  return [...new Set(ids)];
+  return parseFooterBlockedByIds(body);
 }
 
 /**

package/.agents/scripts/lib/doc-tiers.js

@@ -201,9 +201,9 @@ export function resolveAlwaysLoadedClosure(root, { fs = nodeFs } = {}) {
 
 /**
  * Read the resolved `project.docsContextFiles` list from a config object,
- * prefixed by `project.paths.docsRoot`. Mirrors the `contextDocs` half of
- * `resolveDocList` in `validate-docs-freshness.js` (new-shape first, legacy
- * top-level fallback).
+ * prefixed by `project.paths.docsRoot`. Resolves new-shape
+ * `project.docsContextFiles` first and falls back to the legacy top-level
+ * key, so a config written against either shape yields the same list.
  *
  * @param {object} config resolved config (`resolveConfig()` output)
  * @returns {string[]} repo-relative posix doc paths (existence not yet checked)

package/.agents/scripts/lib/feedback-loop/graduator-core.js

@@ -1,15 +1,19 @@
 /**
  * graduator-core.js — shared mechanism for the feedback-loop graduators.
  *
- * Story #3845 / Epic #3823. The audit-results graduator
- * (`audit-results-graduator.js`) and the code-review graduator
- * (the since-retired `code-review-graduator.js`) duplicated ~90% of their mechanism: a
+ * Story #3845 / Epic #3823. The since-retired audit-results and code-review
+ * graduators duplicated ~90% of their mechanism: a
  * `spawn`-based child runner, the `git cat-file` path probe, the
  * `gh search issues` idempotency probe, the `gh issue create` filer, the
  * `isAutoFileEnabled` toggle reader, and the route → probe → file
- * envelope walk. This module folds all of that into one place so the two
- * graduators become thin shells that inject the bits that genuinely
- * differ (the finding parser and the body/title/label builders).
+ * envelope walk. This module folds all of that into one place so a
+ * graduator becomes a thin shell that injects the bits that genuinely
+ * differ (the body/title/label builders).
+ *
+ * Story #5003 removed the structured-comment read limb. Both comment-reading
+ * graduators were Epic-era — they walked an Epic's `verification-results`
+ * comment, and v2 has no Epics — leaving `retro-proposals-graduator.js` and
+ * its pre-parsed `findings[]` as the one live caller.
  *
  * The third `runGh` spawn copy in `prior-feedback-fetcher.js` is also
  * collapsed onto the single `runChild` helper here.
@@ -34,11 +38,10 @@
  *   - **Per-run filing cap.** `graduate()` stops filing once
  *     `maxFilingsPerRun` issues are created and records the excess as
  *     skipped `cap-reached`.
- *   - **Pre-parsed / path-less seam.** `graduate()` accepts a pre-parsed
- *     `findings` array (bypassing structured-comment parsing), and a
- *     path-less finding skips the path-exists gate instead of being
- *     misclassified `file-removed` — the seam the retro auto-filer
- *     consumes.
+ *   - **Pre-parsed / path-less seam.** `graduate()` takes its findings as a
+ *     pre-parsed array, and a path-less finding skips the path-exists gate
+ *     instead of being misclassified `file-removed` — the seam the retro
+ *     auto-filer consumes.
  *   - **Durable cross-repo deferral.** Cross-repo-deferred findings are
  *     upserted into a structured comment on the Epic instead of only a
  *     log line.
@@ -50,34 +53,7 @@ import { createHash } from 'node:crypto';
 import { inNodeTestContext } from '../config/temp-paths.js';
 import { LABEL_COLORS } from '../label-constants.js';
 import { classifyPathSource as defaultClassifier } from '../observability/source-classifier.js';
-import {
-  structuredCommentMarker,
-  upsertStructuredComment,
-} from '../orchestration/ticketing.js';
-
-/**
- * The single structured-comment marker for the unified `verification-results`
- * findings contract (Story #4411, Epic #4405). It replaces the two retired
- * per-graduator markers (the former code-review and audit-results
- * structured-comment markers). Both feedback-loop graduators
- * search the Epic's comments for this one marker so they file follow-ups
- * from the same unified source comment that `runCodeReview` upserts (comment
- * type `verification-results`). Derived from the canonical
- * `structuredCommentMarker` builder so the read-side marker stays byte-stable
- * with the write side rather than being hand-copied.
- */
-export const VERIFICATION_RESULTS_MARKER = structuredCommentMarker(
-  'verification-results',
-);
-
-/**
- * The single "no source comment" skip reason for the unified contract. Both
- * graduators surface this reason when the Epic carries no
- * `verification-results` comment, replacing the two retired
- * `no-code-review-comment` / `no-audit-results-comment` reasons.
- */
-export const NO_VERIFICATION_RESULTS_COMMENT_REASON =
-  'no-verification-results-comment';
+import { upsertStructuredComment } from '../orchestration/ticketing.js';
 
 /**
  * Default child-process timeout. A hung `gh`/`git` spawn previously blocked
@@ -814,28 +790,24 @@ export async function createFollowUpIssue({
 }
 
 /**
- * Validate the `graduate` preconditions (toggle, epicId, provider shape,
- * currentRepo shape). Returns `null` when all preconditions pass, or a
- * `{ skipped?, errors? }` partial-envelope the caller short-circuits on.
- * Story #4075 — extracted from `graduate` so the orchestrating body holds
- * no guard-chain branching.
+ * Validate the `graduate` preconditions (toggle, epicId, currentRepo shape).
+ * Returns `null` when all preconditions pass, or a `{ skipped?, errors? }`
+ * partial-envelope the caller short-circuits on. Story #4075 — extracted from
+ * `graduate` so the orchestrating body holds no guard-chain branching.
+ *
+ * Story #5003 dropped the `provider.getTicketComments` gate with the
+ * structured-comment read limb. The provider is now consulted only by the
+ * best-effort cross-repo-deferred upsert, which reports its own faults into
+ * `errors[]` — gating the whole walk on a shape only that path needs would
+ * refuse work the walk can complete.
  */
-function checkGraduatePreconditions({
-  epicId,
-  provider,
-  currentRepo,
-  config,
-  spec,
-}) {
+function checkGraduatePreconditions({ epicId, currentRepo, config, spec }) {
   if (!spec.isAutoFileEnabled(config)) {
     return { skipped: [{ reason: 'toggle-disabled' }] };
   }
   if (!Number.isInteger(epicId) || epicId < 1) {
     return { errors: [`${spec.fnName}: missing or invalid epicId`] };
   }
-  if (!provider || typeof provider.getTicketComments !== 'function') {
-    return { errors: [`${spec.fnName}: provider lacks getTicketComments`] };
-  }
   if (
     !currentRepo ||
     typeof currentRepo.owner !== 'string' ||
@@ -846,36 +818,6 @@ function checkGraduatePreconditions({
   return null;
 }
 
-/**
- * Read the source structured comment off the Epic and parse its findings.
- * Returns `{ findings }` on success, or `{ skipped?, errors? }` for the
- * no-comment / parse-empty / fetch-error short-circuits. Story #4075 —
- * extracted from `graduate`.
- */
-async function loadGraduateFindings({ epicId, provider, spec }) {
-  let comments;
-  try {
-    comments = await provider.getTicketComments(epicId);
-  } catch (err) {
-    return {
-      errors: [
-        `getTicketComments failed for epic #${epicId}: ${err?.message ?? err}`,
-      ],
-    };
-  }
-  const matched = (Array.isArray(comments) ? comments : []).filter(
-    (c) => typeof c?.body === 'string' && c.body.includes(spec.commentMarker),
-  );
-  if (matched.length === 0) {
-    return { skipped: [{ reason: spec.noCommentReason }] };
-  }
-  const findings = spec.parseFindings(matched[matched.length - 1].body);
-  if (findings.length === 0) {
-    return { skipped: [{ reason: 'no-non-blocking-findings' }] };
-  }
-  return { findings };
-}
-
 /**
  * Probe whether a finding was already filed, checking both the current
  * content-hash marker AND the legacy `(epicId, parse-index)` marker so
@@ -1267,17 +1209,16 @@ async function persistCrossRepoDeferred({
 }
 
 /**
- * Parametrized graduator walk. Parses non-blocking findings (from the
- * Epic's structured comment, or a pre-parsed `findings` array), then for
- * each finding runs the shared route → path probe → idempotency probe →
+ * Parametrized graduator walk. Takes a pre-parsed `findings` array and, for
+ * each finding, runs the shared route → path probe → idempotency probe →
  * cap → file sequence. Never throws — every failure path is captured in
  * `errors[]`.
  *
+ * Each finding MUST carry `{ severity, path, summary, index }` and MAY carry
+ * additional fields (e.g. `category`) that the builders use.
+ *
  * The per-graduator variation lives entirely in the injected callbacks:
  *
- *   - `parseFindings(body)` — turns the rendered comment into findings.
- *     Each finding MUST carry `{ severity, path, summary, index }` and
- *     MAY carry additional fields (e.g. `lens`) that the builder uses.
  *   - `buildContentMarker(epicId, finding)` — the content-hash HTML-comment
  *     marker embedded in (and searched for in) follow-up bodies.
  *   - `buildLegacyMarker(epicId, index)` — the pre-cutover ordinal marker,
@@ -1299,7 +1240,8 @@ async function persistCrossRepoDeferred({
  *
  * @param {object} opts
  * @param {number} opts.epicId
- * @param {object} opts.provider — exposes `getTicketComments(ticketId)`
+ * @param {object} opts.provider — exposes `postComment(ticketId, body)` for
+ *   the durable cross-repo-deferred persistence
  * @param {object} [opts.config]
  * @param {{owner: string, repo: string}} opts.currentRepo
  * @param {{owner: string, repo: string}} [opts.frameworkRepo]
@@ -1310,9 +1252,9 @@ async function persistCrossRepoDeferred({
  * @param {string} [opts.cwd]
  * @param {number} [opts.timeoutMs] — per-spawn watchdog bound
  * @param {number} [opts.maxFilingsPerRun] — per-run filing cap
- * @param {Array<object>} [opts.findings] — pre-parsed findings; when
- *   provided, the structured-comment read/parse is bypassed (the retro
- *   auto-filer seam).
+ * @param {Array<object>} opts.findings — the pre-parsed findings to file.
+ *   Required: a non-array is an `errors[]` short-circuit, never a silent
+ *   no-op.
  * @param {Set<string>} [opts.filedMarkers] — in-process memo of content
  *   markers filed so far. Pass a shared Set across multiple `graduate()`
  *   calls in one logical invocation (e.g. the retro graduator's two source
@@ -1360,23 +1302,23 @@ export async function graduate({
 
   const precondition = checkGraduatePreconditions({
     epicId,
-    provider,
     currentRepo,
     config,
     spec,
   });
   if (precondition) return { ...envelope, ...precondition };
 
-  let findings;
-  if (Array.isArray(preParsedFindings)) {
-    // Pre-parsed seam (retro auto-filer): bypass the structured-comment
-    // read + parse entirely and file the supplied findings directly.
-    findings = preParsedFindings;
-  } else {
-    const loaded = await loadGraduateFindings({ epicId, provider, spec });
-    if (!loaded.findings) return { ...envelope, ...loaded };
-    findings = loaded.findings;
+  // Pre-parsed findings are the only source (Story #5003). The
+  // structured-comment read/parse limb went with the audit-results
+  // graduator: it walked an Epic's `verification-results` comment, and v2
+  // has no Epics, so it could only ever resolve zero findings.
+  if (!Array.isArray(preParsedFindings)) {
+    return {
+      ...envelope,
+      errors: [`${spec.fnName}: findings[] is required and must be an array`],
+    };
   }
+  const findings = preParsedFindings;
 
   // Blast-radius guard (Story #4837): decided ONCE per walk, before the
   // first spawn, so a refused context costs no child process at all.

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -138,6 +138,14 @@ function metaSourceLabel(source) {
  * a single source so the constant classifier routes every finding in the
  * bucket to the correct repo (and the label reflects that source).
  *
+ * The bundle carries **only** builders. It used to declare a
+ * `commentMarker` / `noCommentReason` / `parseFindings` trio purely to satisfy
+ * the shared walk's shape — this graduator supplies its findings pre-parsed,
+ * so the walk never consulted any of the three. Story #5003 deleted that limb
+ * from `graduate()` along with the Epic-era graduator that was its only real
+ * consumer, and the placeholder fields went with it: a declared-but-unread
+ * field is a standing invitation to write a parser nothing will call.
+ *
  * @param {'framework'|'consumer'} source
  * @returns {object}
  */
@@ -145,12 +153,6 @@ function makeSpec(source) {
   return {
     fnName: 'graduateRetroProposals',
     isAutoFileEnabled,
-    // Pre-parsed seam: the comment marker / parser are never consulted
-    // (findings are supplied directly), but the fields are declared for the
-    // shared walk's shape.
-    commentMarker: '<!-- structured-comment: retro -->',
-    noCommentReason: 'no-retro-comment',
-    parseFindings: () => [],
     buildContentMarker,
     buildMatchTokens,
     crossRepoCommentAttrs: { graduator: 'retro-proposals' },
@@ -210,8 +212,8 @@ function toFinding(item, source, index) {
  *
  * @param {object} opts
  * @param {number} opts.epicId
- * @param {object} opts.provider — ticketing provider (getTicketComments;
- *   postComment for the cross-repo-deferred persistence).
+ * @param {object} opts.provider — ticketing provider (`postComment`, for the
+ *   cross-repo-deferred persistence).
  * @param {object} [opts.config] — resolved agentrc.
  * @param {{owner: string, repo: string}} opts.currentRepo — the repo the
  *   retro is running inside (the consumer's own repo); the cross-repo guard's

package/.agents/scripts/lib/findings/provenance-field.js

@@ -0,0 +1,135 @@
+/**
+ * lib/findings/provenance-field.js — the per-Story `provenance` field.
+ *
+ * An audit-seeded plan carries dedup identities forward so the next sweep
+ * recognises what it already planned. The optional top-level `provenance`
+ * field on a `stories.json` entry says **which of them that Story owns**:
+ *
+ * ```jsonc
+ * { "fingerprints": ["<40-char sha1>"], "semanticKeys": ["architecture␟lib/a.js"] }
+ * ```
+ *
+ * Two callers, deliberately split from
+ * [`route-finding.js`](route-finding.js): the ticket validator shape-checks
+ * the authored field, and plan-persist's assembly renders the owned identities
+ * into the footer source it stamps. Neither is dedup *routing*, which is what
+ * `route-finding.js` is for — this module reads its identity vocabulary
+ * (`SHA1_RE`, `SEMANTIC_KEY_RE`, and the two footer renderers) from there so
+ * there is exactly one definition of what a fingerprint or a semantic key
+ * looks like.
+ *
+ * @module lib/findings/provenance-field
+ */
+
+import {
+  fingerprintFooter,
+  SEMANTIC_KEY_RE,
+  SHA1_RE,
+  semanticKeyFooter,
+} from './route-finding.js';
+
+/** Human-readable rendering of the `provenance` field's two lists. */
+const PROVENANCE_SHAPE = 'fingerprints[] / semanticKeys[]';
+
+/** What each `provenance` list accepts, and how to say so when it does not. */
+const PROVENANCE_FIELDS = Object.freeze({
+  fingerprints: { pattern: SHA1_RE, expected: 'a 40-char sha1 hex string' },
+  semanticKeys: {
+    pattern: SEMANTIC_KEY_RE,
+    expected: 'a non-empty key carrying no comma or ">"',
+  },
+});
+
+/**
+ * Validate one authored `provenance` list into its normalized form.
+ *
+ * @param {unknown} list
+ * @param {{ where: string, field: string, pattern: RegExp, expected: string }} spec
+ * @returns {string[]} Trimmed, de-duplicated, first-seen order.
+ */
+function normalizeList(list, { where, field, pattern, expected }) {
+  if (list === null || list === undefined) return [];
+  if (!Array.isArray(list)) {
+    throw new Error(`${where}: ${field} must be an array of strings`);
+  }
+  const out = [];
+  for (const entry of list) {
+    const value = typeof entry === 'string' ? entry.trim() : '';
+    if (!pattern.test(value)) {
+      throw new Error(
+        `${where}: ${field} entry ${JSON.stringify(entry)} is not ${expected}`,
+      );
+    }
+    if (!out.includes(value)) out.push(value);
+  }
+  return out;
+}
+
+/**
+ * Normalize the optional per-Story `provenance` field a plan may author —
+ * the identities of the findings **that Story owns**.
+ *
+ * Absence is meaningful and must stay cheap: `undefined` / `null` returns
+ * `null`, which is the caller's signal to fall back to the whole-seed union
+ * carry. That fallback is not vestigial — leaving the authoring agent to
+ * hand-carry provenance out of the seed's HTML comments was measured to fail,
+ * and the mechanical union is what closed it. Attribution is **additive**: a
+ * plan that attributes gets exact stamping, a plan that does not keeps recall.
+ *
+ * An empty object is therefore *not* the same as an absent field: it means
+ * "this Story owns nothing", and stamps nothing.
+ *
+ * Present-but-malformed is a hard error rather than a silent drop, because a
+ * dropped identity is invisible until the next sweep re-files work that was
+ * already planned.
+ *
+ * @param {unknown} raw
+ * @param {string} [label] Identifier for the error message (a Story slug).
+ * @returns {{ fingerprints: string[], semanticKeys: string[] }|null}
+ * @throws {Error} On any shape the stamper cannot honour exactly.
+ */
+export function normalizeOwnedProvenance(raw, label = 'story') {
+  if (raw === undefined || raw === null) return null;
+  const where = `provenance on "${label}"`;
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${where} must be an object of ${PROVENANCE_SHAPE}`);
+  }
+  const out = { fingerprints: [], semanticKeys: [] };
+  for (const [field, list] of Object.entries(raw)) {
+    const spec = PROVENANCE_FIELDS[field];
+    if (!spec) {
+      throw new Error(
+        `${where} carries an unknown field: ${field} — only ${PROVENANCE_SHAPE} are stamped`,
+      );
+    }
+    out[field] = normalizeList(list, { where, field, ...spec });
+  }
+  return out;
+}
+
+/**
+ * Render the provenance **source document** for a set of owned identities, in
+ * the same footer vocabulary `carryProvenanceFooters` harvests from an audit
+ * seed. That reuse is the point: attribution changes *which* identities reach
+ * a Story body, never how they are stamped, so the carry stays additive,
+ * union-preserving and idempotent for an attributed plan exactly as it is for
+ * an un-attributed one.
+ *
+ * An empty (or absent) set renders the empty string, which the carry treats as
+ * nothing-to-do — so a Story that owns no findings is stamped with none rather
+ * than inheriting its siblings'.
+ *
+ * Expects the normalized shape {@link normalizeOwnedProvenance} returns; the
+ * validator runs first on every production path.
+ *
+ * @param {{ fingerprints?: string[], semanticKeys?: string[] }|null} [provenance]
+ * @returns {string}
+ */
+export function ownedProvenanceSource(provenance) {
+  const shas = provenance?.fingerprints ?? [];
+  const keys = provenance?.semanticKeys ?? [];
+  const parts = [];
+  if (shas.length > 0) parts.push(fingerprintFooter(shas));
+  if (keys.length > 0) parts.push(semanticKeyFooter(keys));
+  return parts.join('\n');
+}