@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/commands/archive/plan/contracts/verdict-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-lines.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/contracts/verdict-lines.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The plan lines a contract merge's verdicts print — the quote, the stale\n * baseline, the overwrite and the `info` the merge does not carry — spelled\n * once for both planners\n * (./openapi.ts, ./asyncapi.ts), which used to print them in fourteen parallel\n * loops. Every surface reaches the reader by exactly the same sentence an\n * operation or a slot does, because it is graded by exactly the same verdict;\n * one spelling is what keeps the two axes from describing one verdict in two\n * sentences. The label prefix (`path-level …`, `component …`, `components.…`)\n * stays at the call site: it is the one part that differs.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { withoutFeatureKeysDeep } from \"../../../../core/openapi/digest.js\";\nimport { isRecord } from \"../../../../core/kernel/records.js\";\nimport { compareIds } from \"../../../../core/repo/entries.js\";\nimport type { IssueCode } from \"../../../../core/vocabulary/issue.js\";\nimport type { Plan } from \"../state.js\";\n\ntype Say = (line?: string) => void;\n\n/**\n * Said out loud, because \"the plan wrote less than my delta spells\" is the one\n * thing a reader cannot infer from a merged file. Not a warning: quoting the\n * contract around your change is correct authoring, and leaving the quote\n * alone is the correct merge. The path-level and component quotes get the\n * same sentence for the same reason.\n */\nexport function sayQuoted(say: Say, labels: readonly string[]): void {\n  for (const label of labels) say(`      · quotes ${label} — unchanged since it was pinned, left as living has it`);\n}\n\n/**\n * Stale surfaces reaching the merge at all means --approve pushed past the\n * gate's `openapi.baseline-stale` / `asyncapi.baseline-stale` — the plan still\n * names what it cost.\n */\nexport function sayStale(say: Say, labels: readonly string[]): void {\n  for (const label of labels) {\n    say(`      ⚠ stale baseline on ${label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);\n  }\n}\n\n/** One overwrite the plan warns about. The code is spelled literally at each call site. */\nexport interface Overwrite {\n  svc: string;\n  code: IssueCode;\n  /** What the printed line names: the label with its prefix. */\n  label: string;\n  /** The warning's sentence, before any consumer clause. */\n  message: string;\n  /** Who the overwrite lands on (./consumers.ts), or absent where nothing can name it. */\n  named?: { clause: string; details: string[] } | null;\n}\n\n/**\n * Warn about one overwrite and print it. The consumer clause, when there is\n * one, ends both the warning's message and the printed line, and its evidence\n * rides as the warning's `details` and as indented lines under it.\n */\nexport function warnOverwrite(plan: Pick<Plan, \"planWarns\">, say: Say, overwrite: Overwrite): void {\n  const named = overwrite.named ?? null;\n  const clause = named === null ? \"\" : `; ${named.clause}`;\n  plan.planWarns.push({\n    severity: \"warn\",\n    code: overwrite.code,\n    subject: overwrite.svc,\n    message: overwrite.message + clause,\n    ...(named === null ? {} : { details: named.details }),\n  });\n  say(`      ⚠ overwrites ${overwrite.label} — the living definition differs${clause}`);\n  for (const line of named?.details ?? []) say(`          ${line}`);\n}\n\n/**\n * The `info` keys a feature's contract spells differently from the living one,\n * as `info.<key>` labels, sorted — empty when the delta writes no `info`, or\n * writes exactly what living has.\n *\n * Neither merge carries `info` (nor any root key outside the sections it\n * merges: `../../../../core/asyncapi/merge/markers.ts` names what those are),\n * and that is a decision rather than a gap — a delta is a diff of operations\n * and slots, and its `info` is most often the scaffold's or a copy. But a\n * delta that DID move it — a new version, a rewritten description — lost the\n * change with exit 0 and nothing in the plan, so the reader learned it from\n * the living file weeks later. Only keys the delta declares are compared: a\n * key living has and the delta leaves out is a key nobody asked to change.\n * Feature bookkeeping is never compared: an `x-loam-*` key of `info` itself is\n * skipped, and the merges' own markers are stripped from the values below it\n * (`withoutFeatureKeysDeep`), so a pin can never read as drift.\n */\nexport function infoDrift(livingPlain: unknown, featurePlain: unknown): string[] {\n  const feature = isRecord(featurePlain) ? featurePlain.info : undefined;\n  if (!isRecord(feature)) return [];\n  const living = isRecord(livingPlain) && isRecord(livingPlain.info) ? livingPlain.info : {};\n  return Object.keys(feature)\n    .filter((key) => !key.startsWith(\"x-loam-\"))\n    .filter((key) => !isDeepStrictEqual(withoutFeatureKeysDeep(feature[key]), living[key]))\n    .map((key) => `info.${key}`)\n    .sort(compareIds);\n}\n\n/** Which contract the drift is about, the code it is reported under, and what the merge carries instead. */\nexport interface InfoDrift {\n  svc: string;\n  code: IssueCode;\n  /** `openapi.yaml` or `asyncapi.yaml` — the living file the author edits instead. */\n  file: string;\n  /** What the merge DOES carry, in the words the warning prints. */\n  carries: string;\n  labels: readonly string[];\n}\n\n/**\n * Warn about one contract's `info` drift and print it. A warning, not a gate:\n * keeping the living `info` is the merge working as designed, and the remedy —\n * edit the living file in the same change — is the author's call. What must\n * not happen is the silence.\n */\nexport function warnInfoDrift(plan: Pick<Plan, \"planWarns\">, say: Say, drift: InfoDrift): void {\n  if (drift.labels.length === 0) return;\n  const which = drift.labels.join(\", \");\n  plan.planWarns.push({\n    severity: \"warn\",\n    code: drift.code,\n    subject: drift.svc,\n    message:\n      `${drift.svc}: the delta's ${which} differ(s) from the living ${drift.file} — the merge carries ${drift.carries} and never ` +\n      `info, so the living contract keeps its own. If it should move, edit the living ${drift.file} in this change.`,\n  });\n  say(`      ⚠ info not merged — the delta's ${which} differ(s) from the living ${drift.file}, which keeps its own`);\n}\n"]}

package/dist/commands/archive/plan/document/head.js

@@ -0,0 +1,151 @@
+/**
+ * What a living document that `loam archive` CREATES says above
+ * `## Requirements` — the part of a new service spec, architecture spec or
+ * capability document that the requirement algebra has nothing to say about.
+ *
+ * THE DEFECT THIS CLOSES. A created document used to be a fixed header —
+ * `service`, `status: draft`, `# <id>` — and the requirements. Everything else
+ * the delta said was dropped in silence: its title, the narrative a reader
+ * needs before the first requirement, the frontmatter `owner`, any section
+ * written after the last delta section. The requirements arrived byte for byte
+ * and the document arrived unreadable to anyone who had not read the delta.
+ *
+ * WHY NOT CARRY THE WHOLE PREAMBLE. "loam merges requirements, never prose"
+ * (SCHEMA) is not an aversion to prose; it is the observation that a delta's
+ * prose is ABOUT THE CHANGE. The scaffold's own H1 is "<svc> — requirement
+ * delta for <FEAT>" and its intro tells the reviewer what a delta is; carrying
+ * either into the living document would make it describe a pull request that
+ * merged months ago. A machine cannot tell narrative about the service from
+ * narrative about the change, so loam carries only what the author MARKED as
+ * the document's own, and says where the rest is:
+ *
+ * - `owner` from the delta's frontmatter — the one field that describes the
+ *   service rather than the change or a vouch (copying `vouched_by` or a digest
+ *   would forge a review nobody performed). A capability document carries no
+ *   frontmatter by decision (`planCapabilities` says why), so it gets none.
+ * - the delta's H1, unless it is about the change — it names the feature or
+ *   calls itself a delta, which is exactly what the scaffold writes.
+ * - the delta's `## Purpose` section, verbatim — the explicit marker, and the
+ *   one OpenSpec's living specs already use for the document's own narrative.
+ * - a back-link to the archived delta, always, so nothing the merge left behind
+ *   is unreachable from the document it created.
+ *
+ * Only on CREATION. A living document that already exists keeps its own
+ * narrative, edited in place; a `## Purpose` in a delta against it merges as
+ * nothing, and `planSpecs` says so rather than letting it vanish.
+ */
+import { dirname, relative, sep } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { parseFrontmatter, stringField } from "../../../../core/document/frontmatter.js";
+import { serializeRequirements } from "../../../../core/document/spec.js";
+import { repoPath } from "../../../../core/envelope/json.js";
+import { fenceTracker } from "../../../../core/kernel/fences.js";
+/** A level-1 heading line. */
+const H1_RE = /^#\s+(.+?)\s*$/;
+/** The marked section — matched on the whole trimmed line, case-insensitively, like `## Requirements`. */
+const PURPOSE_RE = /^##\s+Purpose\s*$/i;
+/** Where a section ends: the next H1 or H2. Deeper headings are the section's own. */
+const SECTION_END_RE = /^#{1,2}\s/;
+/**
+ * The created document's whole text, and the one line that tells the person
+ * reading the plan what came across from the delta and where the rest is.
+ */
+export function createdDocument(request) {
+    const archived = request.retarget(request.deltaPath);
+    // Percent-escaped spaces, as `rebaseLinks` writes a route it computed: a bare
+    // space would end the link target at the first word.
+    const backLink = relative(dirname(request.livingPath), archived).split(sep).join("/").split(" ").join("%20");
+    const head = createdHead({ ...request, backLink });
+    const where = repoPath(request.docsDir, archived);
+    const note = head.carried.length > 0
+        ? `carried from the delta: ${head.carried.join(", ")} — the rest of its prose stays in ${where}, linked from the new document`
+        : `the delta's prose stays in ${where}, linked from the new document — mark what belongs here '## Purpose' and archive carries it`;
+    return { text: `${head.text}## Requirements\n\n${serializeRequirements(request.requirements)}`, note };
+}
+/** The head of a document archive creates — see the module comment for what goes in it and why. */
+function createdHead(request) {
+    const fm = parseFrontmatter(request.delta);
+    const marked = markedParts(fm.body, request.featureId);
+    const owner = request.service === null ? undefined : stringField(fm, "owner");
+    const carried = [];
+    let text = "";
+    if (request.service !== null) {
+        const fields = {
+            service: request.service,
+            status: "draft",
+            ...(request.adoption === undefined ? {} : { adoption: request.adoption }),
+            ...(owner === undefined ? {} : { owner }),
+        };
+        text += `---\n${stringifyYaml(fields, { lineWidth: 0 })}---\n\n`;
+        if (owner !== undefined)
+            carried.push("owner");
+    }
+    text += `# ${marked.title ?? request.fallbackTitle}\n\n`;
+    if (marked.title !== undefined)
+        carried.push("its title");
+    text += `Created when ${request.featureId} was archived; [its delta](${request.backLink}) keeps the prose written for that change.\n\n`;
+    if (marked.purpose !== undefined) {
+        text += `## Purpose\n\n${marked.purpose}\n\n`;
+        carried.push("its ## Purpose");
+    }
+    return { text, carried };
+}
+/** Does the delta carry a `## Purpose` section at all — the question a merge into an EXISTING document asks. */
+export function hasPurpose(delta) {
+    return markedParts(parseFrontmatter(delta).body, "").purpose !== undefined;
+}
+/**
+ * Is this H1 the CHANGE's title rather than the document's? Two mechanical
+ * signals, both in words loam owns: it names the feature, or it calls itself a
+ * delta — which no living document does, and which every delta title loam
+ * scaffolds does both of ("<svc> — requirement delta for <FEAT>"). Anything
+ * else is a title an author chose for the thing itself, the shape a domain
+ * written into a feature in one go arrives in.
+ */
+function namesTheChange(title, featureId) {
+    const lower = title.toLowerCase();
+    return (featureId !== "" && lower.includes(featureId.toLowerCase())) || /\bdelta\b/.test(lower);
+}
+/**
+ * The delta's title and `## Purpose` body, each only when the author wrote one
+ * that belongs to the living document. Fence-aware, like every heading walk in
+ * loam: a heading inside a fenced block is quoted text, and a fenced block
+ * inside the Purpose is part of it.
+ */
+function markedParts(body, featureId) {
+    const fenced = fenceTracker();
+    let title;
+    let seenSection = false;
+    let purpose = null;
+    let purposeEnded = false;
+    for (const line of body.split(/\r?\n/)) {
+        const quoted = fenced(line);
+        if (purpose !== null && !purposeEnded) {
+            if (quoted || !SECTION_END_RE.test(line)) {
+                purpose.push(line);
+                continue;
+            }
+            purposeEnded = true;
+        }
+        if (quoted)
+            continue;
+        const h1 = H1_RE.exec(line);
+        // The document's title is an H1 above its first section; one further down
+        // is a heading inside the text, not the name of the document.
+        if (h1 !== null && !seenSection && title === undefined)
+            title = h1[1];
+        if (/^##\s/.test(line)) {
+            seenSection = true;
+            if (purpose === null && PURPOSE_RE.test(line.trim()))
+                purpose = [];
+        }
+    }
+    // Blank LINES trimmed, never leading spaces: an indented code block opening
+    // the section is the author's text.
+    const purposeText = purpose?.join("\n").replace(/^(?:[ \t]*\n)+/, "").trimEnd();
+    return {
+        ...(title === undefined || namesTheChange(title, featureId) ? {} : { title }),
+        ...(purposeText === undefined || purposeText === "" ? {} : { purpose: purposeText }),
+    };
+}
+//# sourceMappingURL=head.js.map

package/dist/commands/archive/plan/document/head.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"head.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/document/head.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a living document that `loam archive` CREATES says above\n * `## Requirements` — the part of a new service spec, architecture spec or\n * capability document that the requirement algebra has nothing to say about.\n *\n * THE DEFECT THIS CLOSES. A created document used to be a fixed header —\n * `service`, `status: draft`, `# <id>` — and the requirements. Everything else\n * the delta said was dropped in silence: its title, the narrative a reader\n * needs before the first requirement, the frontmatter `owner`, any section\n * written after the last delta section. The requirements arrived byte for byte\n * and the document arrived unreadable to anyone who had not read the delta.\n *\n * WHY NOT CARRY THE WHOLE PREAMBLE. \"loam merges requirements, never prose\"\n * (SCHEMA) is not an aversion to prose; it is the observation that a delta's\n * prose is ABOUT THE CHANGE. The scaffold's own H1 is \"<svc> — requirement\n * delta for <FEAT>\" and its intro tells the reviewer what a delta is; carrying\n * either into the living document would make it describe a pull request that\n * merged months ago. A machine cannot tell narrative about the service from\n * narrative about the change, so loam carries only what the author MARKED as\n * the document's own, and says where the rest is:\n *\n * - `owner` from the delta's frontmatter — the one field that describes the\n *   service rather than the change or a vouch (copying `vouched_by` or a digest\n *   would forge a review nobody performed). A capability document carries no\n *   frontmatter by decision (`planCapabilities` says why), so it gets none.\n * - the delta's H1, unless it is about the change — it names the feature or\n *   calls itself a delta, which is exactly what the scaffold writes.\n * - the delta's `## Purpose` section, verbatim — the explicit marker, and the\n *   one OpenSpec's living specs already use for the document's own narrative.\n * - a back-link to the archived delta, always, so nothing the merge left behind\n *   is unreachable from the document it created.\n *\n * Only on CREATION. A living document that already exists keeps its own\n * narrative, edited in place; a `## Purpose` in a delta against it merges as\n * nothing, and `planSpecs` says so rather than letting it vanish.\n */\nimport { dirname, relative, sep } from \"node:path\";\nimport { stringify as stringifyYaml } from \"yaml\";\nimport { parseFrontmatter, stringField } from \"../../../../core/document/frontmatter.js\";\nimport { serializeRequirements, type Requirement } from \"../../../../core/document/spec.js\";\nimport { repoPath } from \"../../../../core/envelope/json.js\";\nimport { fenceTracker } from \"../../../../core/kernel/fences.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { Retarget } from \"./links.js\";\n\n/** A level-1 heading line. */\nconst H1_RE = /^#\\s+(.+?)\\s*$/;\n/** The marked section — matched on the whole trimmed line, case-insensitively, like `## Requirements`. */\nconst PURPOSE_RE = /^##\\s+Purpose\\s*$/i;\n/** Where a section ends: the next H1 or H2. Deeper headings are the section's own. */\nconst SECTION_END_RE = /^#{1,2}\\s/;\n\n/** One living document this archive creates, and the delta it is created from. */\nexport interface CreatedRequest {\n  docsDir: DocsDir;\n  featureId: string;\n  /** The delta's path, where it sits BEFORE the archive moves the feature. */\n  deltaPath: string;\n  /** The delta's text, its links already re-expressed for `livingPath`'s directory. */\n  delta: string;\n  livingPath: string;\n  /** Where each feature file will be after the archive — the back-link's target comes from it. */\n  retarget: Retarget;\n  /** The heading written when the delta carries no title of its own. */\n  fallbackTitle: string;\n  /** The `service:` the created frontmatter names; null for a document that carries no frontmatter. */\n  service: string | null;\n  /**\n   * `partial` when the document is a service's FIRST spec.md and the service\n   * existed before this feature — so what lands is the feature's slice and\n   * not the service. Written to the frontmatter as `adoption: partial`\n   * (SCHEMA.md), which the maturity ladder and `loam status` read as \"not\n   * adopted yet\" until a person deletes the line.\n   */\n  adoption?: \"partial\";\n  requirements: Requirement[];\n}\n\n/**\n * The created document's whole text, and the one line that tells the person\n * reading the plan what came across from the delta and where the rest is.\n */\nexport function createdDocument(request: CreatedRequest): { text: string; note: string } {\n  const archived = request.retarget(request.deltaPath);\n  // Percent-escaped spaces, as `rebaseLinks` writes a route it computed: a bare\n  // space would end the link target at the first word.\n  const backLink = relative(dirname(request.livingPath), archived).split(sep).join(\"/\").split(\" \").join(\"%20\");\n  const head = createdHead({ ...request, backLink });\n  const where = repoPath(request.docsDir, archived);\n  const note =\n    head.carried.length > 0\n      ? `carried from the delta: ${head.carried.join(\", \")} — the rest of its prose stays in ${where}, linked from the new document`\n      : `the delta's prose stays in ${where}, linked from the new document — mark what belongs here '## Purpose' and archive carries it`;\n  return { text: `${head.text}## Requirements\\n\\n${serializeRequirements(request.requirements)}`, note };\n}\n\ninterface HeadRequest {\n  delta: string;\n  featureId: string;\n  fallbackTitle: string;\n  service: string | null;\n  adoption?: \"partial\";\n  /** The created document's relative link to the archived delta. */\n  backLink: string;\n}\n\ninterface CreatedHead {\n  /** Everything above `## Requirements`, ending in a blank line. */\n  text: string;\n  /** What the delta contributed, in the words the per-file note prints. */\n  carried: string[];\n}\n\n/** The head of a document archive creates — see the module comment for what goes in it and why. */\nfunction createdHead(request: HeadRequest): CreatedHead {\n  const fm = parseFrontmatter(request.delta);\n  const marked = markedParts(fm.body, request.featureId);\n  const owner = request.service === null ? undefined : stringField(fm, \"owner\");\n  const carried: string[] = [];\n  let text = \"\";\n  if (request.service !== null) {\n    const fields = {\n      service: request.service,\n      status: \"draft\",\n      ...(request.adoption === undefined ? {} : { adoption: request.adoption }),\n      ...(owner === undefined ? {} : { owner }),\n    };\n    text += `---\\n${stringifyYaml(fields, { lineWidth: 0 })}---\\n\\n`;\n    if (owner !== undefined) carried.push(\"owner\");\n  }\n  text += `# ${marked.title ?? request.fallbackTitle}\\n\\n`;\n  if (marked.title !== undefined) carried.push(\"its title\");\n  text += `Created when ${request.featureId} was archived; [its delta](${request.backLink}) keeps the prose written for that change.\\n\\n`;\n  if (marked.purpose !== undefined) {\n    text += `## Purpose\\n\\n${marked.purpose}\\n\\n`;\n    carried.push(\"its ## Purpose\");\n  }\n  return { text, carried };\n}\n\n/** Does the delta carry a `## Purpose` section at all — the question a merge into an EXISTING document asks. */\nexport function hasPurpose(delta: string): boolean {\n  return markedParts(parseFrontmatter(delta).body, \"\").purpose !== undefined;\n}\n\n/**\n * Is this H1 the CHANGE's title rather than the document's? Two mechanical\n * signals, both in words loam owns: it names the feature, or it calls itself a\n * delta — which no living document does, and which every delta title loam\n * scaffolds does both of (\"<svc> — requirement delta for <FEAT>\"). Anything\n * else is a title an author chose for the thing itself, the shape a domain\n * written into a feature in one go arrives in.\n */\nfunction namesTheChange(title: string, featureId: string): boolean {\n  const lower = title.toLowerCase();\n  return (featureId !== \"\" && lower.includes(featureId.toLowerCase())) || /\\bdelta\\b/.test(lower);\n}\n\n/**\n * The delta's title and `## Purpose` body, each only when the author wrote one\n * that belongs to the living document. Fence-aware, like every heading walk in\n * loam: a heading inside a fenced block is quoted text, and a fenced block\n * inside the Purpose is part of it.\n */\nfunction markedParts(body: string, featureId: string): { title?: string; purpose?: string } {\n  const fenced = fenceTracker();\n  let title: string | undefined;\n  let seenSection = false;\n  let purpose: string[] | null = null;\n  let purposeEnded = false;\n  for (const line of body.split(/\\r?\\n/)) {\n    const quoted = fenced(line);\n    if (purpose !== null && !purposeEnded) {\n      if (quoted || !SECTION_END_RE.test(line)) {\n        purpose.push(line);\n        continue;\n      }\n      purposeEnded = true;\n    }\n    if (quoted) continue;\n    const h1 = H1_RE.exec(line);\n    // The document's title is an H1 above its first section; one further down\n    // is a heading inside the text, not the name of the document.\n    if (h1 !== null && !seenSection && title === undefined) title = h1[1]!;\n    if (/^##\\s/.test(line)) {\n      seenSection = true;\n      if (purpose === null && PURPOSE_RE.test(line.trim())) purpose = [];\n    }\n  }\n  // Blank LINES trimmed, never leading spaces: an indented code block opening\n  // the section is the author's text.\n  const purposeText = purpose?.join(\"\\n\").replace(/^(?:[ \\t]*\\n)+/, \"\").trimEnd();\n  return {\n    ...(title === undefined || namesTheChange(title, featureId) ? {} : { title }),\n    ...(purposeText === undefined || purposeText === \"\" ? {} : { purpose: purposeText }),\n  };\n}\n"]}

package/dist/commands/archive/plan/document/links.js

@@ -0,0 +1,284 @@
+/**
+ * Where every file of the feature will be once this archive lands — the half of
+ * the link rewrite that `core/links/parse.ts`'s `rebaseLinks` cannot know.
+ *
+ * THE DEFECT THIS CLOSES. The requirement merge has re-expressed a delta's
+ * relative links from the directory they were written in to the one they land
+ * in since the glossary axis shipped. But it re-expressed them against the
+ * target's OLD place, and the same archive moves the targets that sit inside
+ * the feature: a link from a delta to `features/<FEAT>/glossary/order.md` was
+ * rewritten faithfully into the living spec and resolved to nothing one rename
+ * later, when the term had been copied to `glossary/order.md` and the feature
+ * directory had gone to `features/archive/<FEAT>/`. Every such link was
+ * `link.unresolved` on the first `validate --all` after a clean archive — an
+ * error the feature gate could not see, because before the archive the link
+ * was correct.
+ *
+ * TWO RULES, and they are the archive's own moves rather than a guess:
+ *
+ * - A file the archive COPIES into the living tree — a glossary term, a flow,
+ *   a topology document — is cited at its living copy. That is the document
+ *   readers are meant to find, and the one `glossary.unlinked` counts a
+ *   citation of: a link left on the archived copy would resolve and still
+ *   leave the living term reading as a word nobody uses.
+ * - Every other file under the feature directory — its ADRs above all, the
+ *   intent, the deltas themselves — is cited where the feature now lives,
+ *   `features/archive/<FEAT>/`. Nothing else copies a feature ADR anywhere: it
+ *   records a decision taken for this change, and it stays with the change
+ *   (SCHEMA "Layout" says so beside the slot).
+ *
+ * Built per call from three directory walks — the glossary, the flows and the
+ * topology documents, the same walks `../specs.ts` and `../landscape.ts` make
+ * to copy them; a `Gated` field would be one more value the gate computes for
+ * a phase it does not own.
+ *
+ * THE OTHER TWO HALVES ARE THE LINKS NO MERGE CARRIES. The feature's own
+ * documents (`planFeatureLinks` below) stay in the feature and ride the rename,
+ * so their links out of it are one directory short the moment it lands. Every
+ * other document in the corpus (`planInboundLinks` below) stays where it is
+ * while the files it cites inside the feature move away from under it.
+ */
+import { dirname, resolve } from "node:path";
+import { repoPath } from "../../../../core/envelope/json.js";
+import { movedUnderVouch, parseFrontmatter, stringField } from "../../../../core/document/frontmatter.js";
+import { parseRequirements } from "../../../../core/document/parse.js";
+import { requirementDigest } from "../../../../core/document/spec.js";
+import { featureGlossary, livingTermPath } from "../../../../core/glossary/delta.js";
+import { allAuthoredDocuments, movedMarkdown } from "../../../../core/links/corpus.js";
+import { rebaseLinks } from "../../../../core/links/parse.js";
+import { inOrder } from "../../../../core/kernel/concurrency.js";
+import { acrossRename, isPathInside } from "../../../../core/kernel/path-safety.js";
+import { featuresDir, servicePathsAt } from "../../../../core/repo/paths.js";
+import { listServices } from "../../../../core/repo/repo.js";
+import { featureFlows, livingFlowPath } from "../../../../core/usecases/delta/flows.js";
+import { featureDeployments, livingDeploymentPath } from "../../../../core/deployment/delta.js";
+import { NotUtf8Error, planWrite, readUtf8 } from "../../../../core/staging/writes.js";
+export async function featureRetarget(docsDir, gated) {
+    const copies = new Map();
+    for (const term of (await featureGlossary(gated.featureDir)).terms) {
+        copies.set(resolve(term.path), resolve(livingTermPath(docsDir, term.id)));
+    }
+    for (const flow of await featureFlows(gated.featureDir)) {
+        copies.set(resolve(flow.path), resolve(livingFlowPath(docsDir, flow.rel)));
+    }
+    for (const doc of await featureDeployments(gated.featureDir)) {
+        copies.set(resolve(doc.path), resolve(livingDeploymentPath(docsDir, doc.rel)));
+    }
+    return (target) => copies.get(resolve(target)) ?? followsFeature(gated, target);
+}
+/**
+ * The feature's own markdown documents with their relative links re-expressed
+ * for `features/archive/<FEAT>/`, planned at their CURRENT paths so the swap
+ * lands before the rename carries them (`../../run.ts`).
+ *
+ * THE DEFECT THIS CLOSES. The archive is a directory rename, and every document
+ * that stays in the feature — the intent, its ADRs, the deltas, a capability
+ * delta, the archived copy of a term — kept links written one directory
+ * shallower than where they now sit: `../../services/x/spec.md` from
+ * `features/<FEAT>/intent.md` names `features/services/x/spec.md` once the
+ * intent is `features/archive/<FEAT>/intent.md`. Nothing grades an archived
+ * feature (`core/links/corpus.ts` says why), so nothing said so — but the
+ * living documents link INTO the archived feature's ADRs (`featureRetarget`
+ * above), and a reader who followed one landed on a decision whose own links
+ * were all off by one.
+ *
+ * ONE RULE, the rename's: a target inside the feature moves with it and every
+ * other target stays put — `subsystem move`'s rule for its own renames
+ * (`commands/subsystem/txn/links.ts`). So a link from the intent to its own
+ * ADR or its own glossary term is left exactly as written: the archived
+ * record keeps citing the archived copy, which is the text the feature was
+ * reviewed against, rather than being redirected to a living copy that will go
+ * on changing without it. Only the routes the rename broke are touched, and a
+ * link whose text still reaches its target keeps its spelling
+ * (`rebaseLinks`).
+ *
+ * The undo is the snapshot's, like every other write here: each rewritten
+ * document is a staged write, so its pre-image is parked and `loam unarchive`
+ * puts the authored bytes back (`core/staging/snapshot/snapshot.ts` says where
+ * it records them).
+ *
+ * A document that is not UTF-8 is left exactly as written, and the text
+ * output says so — `--json` has no key for it, and minting one for a document
+ * nothing grades was not worth a contract change. Every other read here would
+ * refuse it, but this one only corrects links, and refusing the archive over
+ * such a document would be the larger harm.
+ *
+ * Read with bounded concurrency and applied in input order (`inOrder`), as
+ * `subsystem move`'s rewrite reads its own: a large feature — one
+ * `loam migrate-openspec` filled with its legacy documents — is read in full
+ * under the lock.
+ */
+export async function planFeatureLinks(config, gated, planned, say) {
+    const { docsDir } = config;
+    const retarget = (target) => followsFeature(gated, target);
+    const read = await inOrder(await movedMarkdown(gated.featureDir), async (path) => {
+        try {
+            return { path, text: await readUtf8(path) };
+        }
+        catch (err) {
+            if (!(err instanceof NotUtf8Error))
+                throw err;
+            return { path, text: null };
+        }
+    });
+    const relinked = [];
+    for (const { path, text } of read) {
+        const lands = followsFeature(gated, path);
+        if (text === null) {
+            say(`  ⚠ ${repoPath(docsDir, lands)} is not UTF-8 — its links were left as written`);
+            continue;
+        }
+        const next = rebaseLinks(text, { from: dirname(path), to: dirname(lands), retarget });
+        if (next === text)
+            continue;
+        planned.writes.push(planWrite(path, next));
+        relinked.push(repoPath(docsDir, lands));
+    }
+    if (relinked.length === 0)
+        return;
+    say(`  feature documents: ${relinked.length} relinked for ${repoPath(docsDir, gated.archiveDest)}/`);
+    for (const path of relinked)
+        say(`      ${path}`);
+}
+/**
+ * Every other document in the link corpus whose links reach INTO the feature,
+ * re-expressed for where this archive leaves what they cite.
+ *
+ * THE DEFECT THIS CLOSES. Another change in flight builds on this one's
+ * decision (`../FEAT/adrs/0001-x.md` from its intent), or a living ADR cites
+ * the decision taken for it while the change is still open. Correct the moment
+ * before the archive, so no gate could say otherwise; `link.unresolved` the
+ * moment after, because the rename took the directory away from under the
+ * link. And no edit the author could make in advance would have helped: the
+ * archived path does not exist until the archive does. `subsystem move`
+ * rewrites the links into the directories it renames
+ * (`commands/subsystem/txn/links.ts`); this is the archive's rename owing the
+ * same correction.
+ *
+ * THE RULE IS `featureRetarget`'s, not the rename's. These documents are not
+ * the record of the change; they are the living corpus and the other changes
+ * in flight, read against the tree as it is. So a term the archive copies into
+ * `glossary/` is cited at the living copy — the one a reader is meant to find
+ * and the one `glossary.unlinked` counts — and everything that stays with the
+ * change, its ADRs and intent above all, is cited where the feature now lives.
+ * Only the routes into the feature change; every other link keeps its
+ * spelling (`rebaseLinks`).
+ *
+ * COMPOSED ONTO THE MERGE. A living spec the merge rewrites can cite the
+ * feature in its own narrative, and relinking the bytes on disk would plan a
+ * second write of its PRE-merge text — swapped after the merge's, it would
+ * undo the merge. So a document this plan already writes is relinked from the
+ * text the merge composed, and that one write is replaced in place.
+ *
+ * THE COSTS ARE SAID THE WAY THE MERGE SAYS ITS OWN. A rewritten route is still
+ * a changed byte. Under a vouch stamp it is `content.stale` until the owner
+ * re-vouches, so a vouched spec this moves joins `revouchOwed` exactly as one
+ * the merge moves does. Inside a living requirement it moves the digest a
+ * `Based-On:` pin holds, and the plan names the document. No git refusal of the
+ * kind `subsystem move` holds (`move-uncommitted`): archive never stages in
+ * git, and its undo is the snapshot — every write here is one of its rows, so
+ * `loam unarchive` puts the authored bytes back, a document edited since is
+ * `snapshot-stale` like any other, and one whose feature has been archived or
+ * removed since is left as it is (`commands/unarchive/restore.ts`).
+ *
+ * The two notes are the text output's alone — the walk that could not be made
+ * and the `Based-On:` cost. `--json` has no key for either: its `warnings` are
+ * coherence issues with codes, and a new key for an advisory the next
+ * `validate --all` grades in full was not worth a contract change. What an
+ * agent acts on is in the payload already: every relinked document is a `plan`
+ * row and every re-vouch it owes is on `revouchOwed`.
+ */
+export async function planInboundLinks(config, gated, planned, say) {
+    const { docsDir, fleet } = config;
+    let corpus;
+    try {
+        corpus = await allAuthoredDocuments(docsDir, fleet);
+    }
+    catch (err) {
+        // The gate enumerated this fleet already, so a walk that fails here is a
+        // tree `validate` will diagnose. The archive is not refused over a question
+        // it asks to keep the corpus readable — `subsystem move` decides the same —
+        // but it does not pretend the question was answered either.
+        say(`  ⚠ links INTO ${repoPath(docsDir, gated.featureDir)}/ were not checked — the fleet's documents could not be walked ` +
+            `(${err instanceof Error ? err.message : String(err)}); \`loam validate --all\` names any that broke.`);
+        return;
+    }
+    const retarget = await featureRetarget(docsDir, gated);
+    const vouchable = new Map();
+    for (const service of await listServices(docsDir, fleet)) {
+        const paths = servicePathsAt(service.dir);
+        vouchable.set(resolve(paths.spec), service.id);
+        vouchable.set(resolve(paths.archSpec), service.id);
+    }
+    const plannedAt = new Map(planned.writes.map((write, at) => [resolve(write.path), { at, write }]));
+    const seen = new Set();
+    const candidates = corpus.filter((path) => {
+        const key = resolve(path);
+        if (seen.has(key) || isPathInside(gated.featureDir, path))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const documents = await inOrder(candidates, async (path) => {
+        const composed = plannedAt.get(resolve(path));
+        if (composed !== undefined) {
+            // A delete or a Buffer is not text this rewrite may compose onto; no
+            // markdown planner hands over either.
+            const { content } = composed.write;
+            return { path, composed, text: typeof content === "string" ? content : null };
+        }
+        try {
+            return { path, composed, text: await readUtf8(path) };
+        }
+        catch {
+            // Absent (the corpus names every slot a service MAY fill) or not UTF-8,
+            // which `link.unreadable` already names: nothing loam could write back.
+            return { path, composed, text: null };
+        }
+    });
+    const pinned = (md) => parseRequirements(md).map(requirementDigest).join(",");
+    const relinked = [];
+    const notes = [];
+    for (const { path, composed, text } of documents) {
+        if (text === null)
+            continue;
+        const next = rebaseLinks(text, { from: dirname(path), to: dirname(path), retarget });
+        if (next === text)
+            continue;
+        // In place, at the index the merge's write already holds: nothing between
+        // here and the map above adds, removes or reorders a planned write.
+        if (composed === undefined)
+            planned.writes.push(planWrite(path, next));
+        else
+            planned.writes[composed.at] = { ...composed.write, content: next };
+        const where = repoPath(docsDir, path);
+        relinked.push(where);
+        // The merge's own question (`../specs.ts`), asked of the bytes about to be
+        // written — and once per document: a spec the merge already named is not
+        // owed a second re-vouch for the same commit.
+        const service = vouchable.get(resolve(path));
+        const fm = parseFrontmatter(next);
+        const named = planned.revouchOwed.some((owed) => resolve(owed.path) === resolve(path));
+        if (service !== undefined && !named && movedUnderVouch(fm, next)) {
+            planned.revouchOwed.push({ service, path, owner: stringField(fm, "owner") ?? null });
+        }
+        // Living documents only: a pin holds the digest of a LIVING requirement,
+        // so another feature's own delta text moving pins nothing.
+        if (!isPathInside(featuresDir(docsDir), path) && pinned(next) !== pinned(text)) {
+            notes.push(`${where}: links this archive rewrote sit inside requirements, so a feature in flight that pins one with Based-On: ` +
+                "reports delta.baseline-stale until `loam rebase` re-pins it.");
+        }
+    }
+    if (relinked.length === 0)
+        return;
+    say(`  links into the feature: ${relinked.length} document(s) relinked for ${repoPath(docsDir, gated.archiveDest)}/`);
+    for (const path of relinked)
+        say(`      ${path}`);
+    for (const note of notes)
+        say(`      note: ${note}`);
+}
+/** Where `target` will be once the feature directory has moved: its image under the archive when it is inside the feature, itself otherwise. */
+function followsFeature(gated, target) {
+    return acrossRename(target, gated.featureDir, gated.archiveDest);
+}
+//# sourceMappingURL=links.js.map

package/dist/commands/archive/plan/document/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/document/links.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Where every file of the feature will be once this archive lands — the half of\n * the link rewrite that `core/links/parse.ts`'s `rebaseLinks` cannot know.\n *\n * THE DEFECT THIS CLOSES. The requirement merge has re-expressed a delta's\n * relative links from the directory they were written in to the one they land\n * in since the glossary axis shipped. But it re-expressed them against the\n * target's OLD place, and the same archive moves the targets that sit inside\n * the feature: a link from a delta to `features/<FEAT>/glossary/order.md` was\n * rewritten faithfully into the living spec and resolved to nothing one rename\n * later, when the term had been copied to `glossary/order.md` and the feature\n * directory had gone to `features/archive/<FEAT>/`. Every such link was\n * `link.unresolved` on the first `validate --all` after a clean archive — an\n * error the feature gate could not see, because before the archive the link\n * was correct.\n *\n * TWO RULES, and they are the archive's own moves rather than a guess:\n *\n * - A file the archive COPIES into the living tree — a glossary term, a flow,\n *   a topology document — is cited at its living copy. That is the document\n *   readers are meant to find, and the one `glossary.unlinked` counts a\n *   citation of: a link left on the archived copy would resolve and still\n *   leave the living term reading as a word nobody uses.\n * - Every other file under the feature directory — its ADRs above all, the\n *   intent, the deltas themselves — is cited where the feature now lives,\n *   `features/archive/<FEAT>/`. Nothing else copies a feature ADR anywhere: it\n *   records a decision taken for this change, and it stays with the change\n *   (SCHEMA \"Layout\" says so beside the slot).\n *\n * Built per call from three directory walks — the glossary, the flows and the\n * topology documents, the same walks `../specs.ts` and `../landscape.ts` make\n * to copy them; a `Gated` field would be one more value the gate computes for\n * a phase it does not own.\n *\n * THE OTHER TWO HALVES ARE THE LINKS NO MERGE CARRIES. The feature's own\n * documents (`planFeatureLinks` below) stay in the feature and ride the rename,\n * so their links out of it are one directory short the moment it lands. Every\n * other document in the corpus (`planInboundLinks` below) stays where it is\n * while the files it cites inside the feature move away from under it.\n */\nimport { dirname, resolve } from \"node:path\";\nimport { repoPath } from \"../../../../core/envelope/json.js\";\nimport { movedUnderVouch, parseFrontmatter, stringField } from \"../../../../core/document/frontmatter.js\";\nimport { parseRequirements } from \"../../../../core/document/parse.js\";\nimport { requirementDigest } from \"../../../../core/document/spec.js\";\nimport { featureGlossary, livingTermPath } from \"../../../../core/glossary/delta.js\";\nimport { allAuthoredDocuments, movedMarkdown } from \"../../../../core/links/corpus.js\";\nimport { rebaseLinks } from \"../../../../core/links/parse.js\";\nimport { inOrder } from \"../../../../core/kernel/concurrency.js\";\nimport { acrossRename, isPathInside } from \"../../../../core/kernel/path-safety.js\";\nimport { featuresDir, servicePathsAt } from \"../../../../core/repo/paths.js\";\nimport { listServices } from \"../../../../core/repo/repo.js\";\nimport { featureFlows, livingFlowPath } from \"../../../../core/usecases/delta/flows.js\";\nimport { featureDeployments, livingDeploymentPath } from \"../../../../core/deployment/delta.js\";\nimport { NotUtf8Error, planWrite, readUtf8 } from \"../../../../core/staging/writes.js\";\nimport type { FleetContext } from \"../../../../core/fleet-context.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { Gated, Plan } from \"../state.js\";\n\n/** Absolute path in, the absolute path the same file will have after this archive out. */\nexport type Retarget = (target: string) => string;\n\nexport async function featureRetarget(docsDir: DocsDir, gated: Pick<Gated, \"featureDir\" | \"archiveDest\">): Promise<Retarget> {\n  const copies = new Map<string, string>();\n  for (const term of (await featureGlossary(gated.featureDir)).terms) {\n    copies.set(resolve(term.path), resolve(livingTermPath(docsDir, term.id)));\n  }\n  for (const flow of await featureFlows(gated.featureDir)) {\n    copies.set(resolve(flow.path), resolve(livingFlowPath(docsDir, flow.rel)));\n  }\n  for (const doc of await featureDeployments(gated.featureDir)) {\n    copies.set(resolve(doc.path), resolve(livingDeploymentPath(docsDir, doc.rel)));\n  }\n  return (target: string): string => copies.get(resolve(target)) ?? followsFeature(gated, target);\n}\n\n/**\n * The feature's own markdown documents with their relative links re-expressed\n * for `features/archive/<FEAT>/`, planned at their CURRENT paths so the swap\n * lands before the rename carries them (`../../run.ts`).\n *\n * THE DEFECT THIS CLOSES. The archive is a directory rename, and every document\n * that stays in the feature — the intent, its ADRs, the deltas, a capability\n * delta, the archived copy of a term — kept links written one directory\n * shallower than where they now sit: `../../services/x/spec.md` from\n * `features/<FEAT>/intent.md` names `features/services/x/spec.md` once the\n * intent is `features/archive/<FEAT>/intent.md`. Nothing grades an archived\n * feature (`core/links/corpus.ts` says why), so nothing said so — but the\n * living documents link INTO the archived feature's ADRs (`featureRetarget`\n * above), and a reader who followed one landed on a decision whose own links\n * were all off by one.\n *\n * ONE RULE, the rename's: a target inside the feature moves with it and every\n * other target stays put — `subsystem move`'s rule for its own renames\n * (`commands/subsystem/txn/links.ts`). So a link from the intent to its own\n * ADR or its own glossary term is left exactly as written: the archived\n * record keeps citing the archived copy, which is the text the feature was\n * reviewed against, rather than being redirected to a living copy that will go\n * on changing without it. Only the routes the rename broke are touched, and a\n * link whose text still reaches its target keeps its spelling\n * (`rebaseLinks`).\n *\n * The undo is the snapshot's, like every other write here: each rewritten\n * document is a staged write, so its pre-image is parked and `loam unarchive`\n * puts the authored bytes back (`core/staging/snapshot/snapshot.ts` says where\n * it records them).\n *\n * A document that is not UTF-8 is left exactly as written, and the text\n * output says so — `--json` has no key for it, and minting one for a document\n * nothing grades was not worth a contract change. Every other read here would\n * refuse it, but this one only corrects links, and refusing the archive over\n * such a document would be the larger harm.\n *\n * Read with bounded concurrency and applied in input order (`inOrder`), as\n * `subsystem move`'s rewrite reads its own: a large feature — one\n * `loam migrate-openspec` filled with its legacy documents — is read in full\n * under the lock.\n */\nexport async function planFeatureLinks(\n  config: { docsDir: DocsDir },\n  gated: Pick<Gated, \"featureDir\" | \"archiveDest\">,\n  planned: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { docsDir } = config;\n  const retarget = (target: string): string => followsFeature(gated, target);\n  const read = await inOrder(await movedMarkdown(gated.featureDir), async (path) => {\n    try {\n      return { path, text: await readUtf8(path) };\n    } catch (err) {\n      if (!(err instanceof NotUtf8Error)) throw err;\n      return { path, text: null };\n    }\n  });\n  const relinked: string[] = [];\n  for (const { path, text } of read) {\n    const lands = followsFeature(gated, path);\n    if (text === null) {\n      say(`  ⚠ ${repoPath(docsDir, lands)} is not UTF-8 — its links were left as written`);\n      continue;\n    }\n    const next = rebaseLinks(text, { from: dirname(path), to: dirname(lands), retarget });\n    if (next === text) continue;\n    planned.writes.push(planWrite(path, next));\n    relinked.push(repoPath(docsDir, lands));\n  }\n  if (relinked.length === 0) return;\n  say(`  feature documents: ${relinked.length} relinked for ${repoPath(docsDir, gated.archiveDest)}/`);\n  for (const path of relinked) say(`      ${path}`);\n}\n\n/**\n * Every other document in the link corpus whose links reach INTO the feature,\n * re-expressed for where this archive leaves what they cite.\n *\n * THE DEFECT THIS CLOSES. Another change in flight builds on this one's\n * decision (`../FEAT/adrs/0001-x.md` from its intent), or a living ADR cites\n * the decision taken for it while the change is still open. Correct the moment\n * before the archive, so no gate could say otherwise; `link.unresolved` the\n * moment after, because the rename took the directory away from under the\n * link. And no edit the author could make in advance would have helped: the\n * archived path does not exist until the archive does. `subsystem move`\n * rewrites the links into the directories it renames\n * (`commands/subsystem/txn/links.ts`); this is the archive's rename owing the\n * same correction.\n *\n * THE RULE IS `featureRetarget`'s, not the rename's. These documents are not\n * the record of the change; they are the living corpus and the other changes\n * in flight, read against the tree as it is. So a term the archive copies into\n * `glossary/` is cited at the living copy — the one a reader is meant to find\n * and the one `glossary.unlinked` counts — and everything that stays with the\n * change, its ADRs and intent above all, is cited where the feature now lives.\n * Only the routes into the feature change; every other link keeps its\n * spelling (`rebaseLinks`).\n *\n * COMPOSED ONTO THE MERGE. A living spec the merge rewrites can cite the\n * feature in its own narrative, and relinking the bytes on disk would plan a\n * second write of its PRE-merge text — swapped after the merge's, it would\n * undo the merge. So a document this plan already writes is relinked from the\n * text the merge composed, and that one write is replaced in place.\n *\n * THE COSTS ARE SAID THE WAY THE MERGE SAYS ITS OWN. A rewritten route is still\n * a changed byte. Under a vouch stamp it is `content.stale` until the owner\n * re-vouches, so a vouched spec this moves joins `revouchOwed` exactly as one\n * the merge moves does. Inside a living requirement it moves the digest a\n * `Based-On:` pin holds, and the plan names the document. No git refusal of the\n * kind `subsystem move` holds (`move-uncommitted`): archive never stages in\n * git, and its undo is the snapshot — every write here is one of its rows, so\n * `loam unarchive` puts the authored bytes back, a document edited since is\n * `snapshot-stale` like any other, and one whose feature has been archived or\n * removed since is left as it is (`commands/unarchive/restore.ts`).\n *\n * The two notes are the text output's alone — the walk that could not be made\n * and the `Based-On:` cost. `--json` has no key for either: its `warnings` are\n * coherence issues with codes, and a new key for an advisory the next\n * `validate --all` grades in full was not worth a contract change. What an\n * agent acts on is in the payload already: every relinked document is a `plan`\n * row and every re-vouch it owes is on `revouchOwed`.\n */\nexport async function planInboundLinks(\n  config: { docsDir: DocsDir; fleet: FleetContext },\n  gated: Pick<Gated, \"featureDir\" | \"archiveDest\">,\n  planned: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { docsDir, fleet } = config;\n  let corpus: string[];\n  try {\n    corpus = await allAuthoredDocuments(docsDir, fleet);\n  } catch (err) {\n    // The gate enumerated this fleet already, so a walk that fails here is a\n    // tree `validate` will diagnose. The archive is not refused over a question\n    // it asks to keep the corpus readable — `subsystem move` decides the same —\n    // but it does not pretend the question was answered either.\n    say(\n      `  ⚠ links INTO ${repoPath(docsDir, gated.featureDir)}/ were not checked — the fleet's documents could not be walked ` +\n        `(${err instanceof Error ? err.message : String(err)}); \\`loam validate --all\\` names any that broke.`,\n    );\n    return;\n  }\n  const retarget = await featureRetarget(docsDir, gated);\n  const vouchable = new Map<string, string>();\n  for (const service of await listServices(docsDir, fleet)) {\n    const paths = servicePathsAt(service.dir);\n    vouchable.set(resolve(paths.spec), service.id);\n    vouchable.set(resolve(paths.archSpec), service.id);\n  }\n  const plannedAt = new Map(planned.writes.map((write, at) => [resolve(write.path), { at, write }]));\n  const seen = new Set<string>();\n  const candidates = corpus.filter((path) => {\n    const key = resolve(path);\n    if (seen.has(key) || isPathInside(gated.featureDir, path)) return false;\n    seen.add(key);\n    return true;\n  });\n  const documents = await inOrder(candidates, async (path) => {\n    const composed = plannedAt.get(resolve(path));\n    if (composed !== undefined) {\n      // A delete or a Buffer is not text this rewrite may compose onto; no\n      // markdown planner hands over either.\n      const { content } = composed.write;\n      return { path, composed, text: typeof content === \"string\" ? content : null };\n    }\n    try {\n      return { path, composed, text: await readUtf8(path) };\n    } catch {\n      // Absent (the corpus names every slot a service MAY fill) or not UTF-8,\n      // which `link.unreadable` already names: nothing loam could write back.\n      return { path, composed, text: null };\n    }\n  });\n  const pinned = (md: string): string => parseRequirements(md).map(requirementDigest).join(\",\");\n  const relinked: string[] = [];\n  const notes: string[] = [];\n  for (const { path, composed, text } of documents) {\n    if (text === null) continue;\n    const next = rebaseLinks(text, { from: dirname(path), to: dirname(path), retarget });\n    if (next === text) continue;\n    // In place, at the index the merge's write already holds: nothing between\n    // here and the map above adds, removes or reorders a planned write.\n    if (composed === undefined) planned.writes.push(planWrite(path, next));\n    else planned.writes[composed.at] = { ...composed.write, content: next };\n    const where = repoPath(docsDir, path);\n    relinked.push(where);\n    // The merge's own question (`../specs.ts`), asked of the bytes about to be\n    // written — and once per document: a spec the merge already named is not\n    // owed a second re-vouch for the same commit.\n    const service = vouchable.get(resolve(path));\n    const fm = parseFrontmatter(next);\n    const named = planned.revouchOwed.some((owed) => resolve(owed.path) === resolve(path));\n    if (service !== undefined && !named && movedUnderVouch(fm, next)) {\n      planned.revouchOwed.push({ service, path, owner: stringField(fm, \"owner\") ?? null });\n    }\n    // Living documents only: a pin holds the digest of a LIVING requirement,\n    // so another feature's own delta text moving pins nothing.\n    if (!isPathInside(featuresDir(docsDir), path) && pinned(next) !== pinned(text)) {\n      notes.push(\n        `${where}: links this archive rewrote sit inside requirements, so a feature in flight that pins one with Based-On: ` +\n          \"reports delta.baseline-stale until `loam rebase` re-pins it.\",\n      );\n    }\n  }\n  if (relinked.length === 0) return;\n  say(`  links into the feature: ${relinked.length} document(s) relinked for ${repoPath(docsDir, gated.archiveDest)}/`);\n  for (const path of relinked) say(`      ${path}`);\n  for (const note of notes) say(`      note: ${note}`);\n}\n\n/** Where `target` will be once the feature directory has moved: its image under the archive when it is inside the feature, itself otherwise. */\nfunction followsFeature(gated: Pick<Gated, \"featureDir\" | \"archiveDest\">, target: string): string {\n  return acrossRename(target, gated.featureDir, gated.archiveDest);\n}\n"]}