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

package/dist/commands/policy/format.js

@@ -0,0 +1,152 @@
+/**
+ * Small shaping helpers for the renderers.
+ *
+ * They live in `commands/` and not in `core/`: nothing here computes an answer,
+ * it only decides how an answer READS. That was for a long time true of people
+ * only — the header used to say "the `--json` payloads never touch this file",
+ * and `fixesFor` below is the exception that retired the sentence. It is here
+ * for the same reason the rest is: a fix string is not a verdict, it is the
+ * shaping of one that has already been decided, and the module that owns the
+ * text pointer to `loam explain` should own its machine form too, or the two
+ * drift the way every second copy in this codebase eventually has.
+ */
+import { explainSubject } from "../../core/explain/lookup.js";
+import {} from "../../core/verify/build.js";
+/**
+ * "1 service", "2 services". The regular English plural, spelled once because
+ * five renderers had drifted into five copies of the same ternary and a sixth
+ * would have been written the next time somebody counted something. A noun with
+ * an irregular plural does not belong here — say both forms at the call site.
+ */
+/**
+ * The one spelling of "this run first recovered a predecessor's commit" — it
+ * existed in three copies (rebase, gherkin, verify --record) before vouch and
+ * new needed a fourth and fifth, which is the extraction rule's third strike
+ * twice over. Reported at all because docs changing beyond the command's own
+ * writes would otherwise read as its doing.
+ */
+export function sayRecovered(r) {
+    return (`recovered an interrupted \`loam ${r.command}\` first (${r.outcome}` +
+        `${r.repaired.length === 0 ? "" : `: ${r.repaired.join(", ")}`}).`);
+}
+export function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+/**
+ * The one spelling of the vocabulary pointer `validate` and `verify` append to
+ * a TEXT report that printed findings — one string here rather than one per
+ * renderer, because a hand-written second copy is exactly the drift the
+ * pointer's target exists to prevent.
+ *
+ * It used to open with "codes ride in `--json`", and that clause existed for
+ * one reason only: validate's text lines carried messages and no code strings,
+ * so a footer asking the reader to explain "a code above" would have asked for
+ * something never on their screen. That is no longer true — validate appends
+ * the code to every non-`ok` finding and verify's notices have always led with
+ * theirs (validate/report.ts, verify/report.ts) — so the clause has been
+ * dropped rather than reworded: telling a reader to go re-run the command with
+ * `--json` to find what is already two words to the left is worse than saying
+ * nothing.
+ *
+ * Text mode only, and still: this SENTENCE never enters a payload. What
+ * `--json` carries instead is the answer the sentence points at — `fixesFor`
+ * below — because a machine reader has no use for being told a second command
+ * exists, only for what it would have said.
+ */
+export const EXPLAIN_FOOTER = "→ `loam explain <code>` says what a code means and how to fix it";
+/**
+ * The machine form of the footer above: the codes a run actually raised,
+ * resolved to what their fix tables say to do about them.
+ *
+ * The footer tells a PERSON that `loam explain <code>` exists. A `--json`
+ * consumer got no such sentence — the payload is codes and prose messages, and
+ * nothing in a finding says a fix is a lookup away — so an agent holding
+ * `validate --all --json` either had the (now narrowable) /loam-check fix
+ * tables in context already or spawned one `loam explain` process per code,
+ * having first guessed that it could. This closes the gap by answering the
+ * lookup in the same envelope.
+ *
+ * Resolved through `explainSubject` — the very function `loam explain <code>`
+ * calls — and NOT through a second table, so the two surfaces cannot disagree
+ * about what to do about a code. The cost is one walk of the shipped workflow
+ * bodies per DISTINCT code (measured: 0.43ms each, so ~4ms for the nine codes
+ * a fleet run typically raises). `listCodes()` would do one walk for all of
+ * them, and was not used: it builds 227 answers to spend nine, and it would
+ * only start paying off on a run that raised most of the vocabulary — which
+ * is a repo with worse problems than the cost of its report.
+ *
+ * A code the tables do not grade is simply ABSENT from the result. There is no
+ * placeholder string and there must not be one: the named backlog in
+ * test/explain.test.ts is the record of which code families still have no row,
+ * and a fabricated "no fix recorded" here would satisfy the eye at exactly the
+ * place that record is supposed to itch.
+ *
+ * Two shaping rules, both forced by the tables rather than chosen:
+ * - Keys are sorted and deduplicated, so two runs over the same findings
+ *   produce byte-identical maps and a diff of two reports shows only what
+ *   moved.
+ * - Ten of the 227 finding codes are graded by more than one table, and nine
+ *   of those ten say something DIFFERENT to do depending on the scope
+ *   (`openapi.ref-unresolved` is one thing under `--service` and another at
+ *   archive plan time). A single-fix code is emitted verbatim; a code whose
+ *   tables disagree is emitted as its scope-labelled blocks, in table order,
+ *   the same way `loam explain` prints it. Picking the first table's fix would
+ *   be shorter and would sometimes be the wrong instruction, which is the one
+ *   thing a fix string may not be.
+ */
+export function fixesFor(codes) {
+    const fixes = {};
+    for (const code of [...new Set(codes)].sort()) {
+        const explanation = explainSubject(code);
+        // Only the finding arm contributes. A refusal code is an `error.code` and
+        // never appears in a findings array, and a concept term is not a code at
+        // all — the three key sets are pinned pairwise disjoint by
+        // test/explain.test.ts, so this narrowing is a type guard, not a policy.
+        if (explanation === null || explanation.kind !== "finding")
+            continue;
+        // Keyed by the fix so a code graded identically by two tables says it
+        // once, and valued by the FIRST scope that gave it so the labelled form
+        // reads in table order.
+        const byFix = new Map();
+        for (const entry of explanation.entries) {
+            // A row whose "what to do" cell is empty states a consequence, not an
+            // action; it contributes nothing a caller could act on.
+            if (entry.fix !== "" && !byFix.has(entry.fix))
+                byFix.set(entry.fix, entry.scope);
+        }
+        const distinct = [...byFix];
+        if (distinct.length === 0)
+            continue;
+        fixes[code] =
+            distinct.length === 1
+                ? distinct[0][0]
+                : distinct.map(([fix, scope]) => `[${scope}] ${fix}`).join(" ");
+    }
+    return fixes;
+}
+/**
+ * What the previous record answered and the new one does not — printed, never
+ * decided here (`buildFederatedVerification` decides; `verify --record`
+ * reports). A federated write is a partial write, so the first one over an
+ * all-at-once record drops every answer it cannot attribute to a commit —
+ * correct, but silence there reads as loam having lost the answers, and nobody
+ * goes looking for what to re-record. It lives beside `sayRecovered` because
+ * it is the same kind of helper: one spelling of an account the command owes a
+ * person about something the run did beyond its own answer.
+ */
+export function sayDiscarded(discarded, recordPath, feature) {
+    if (discarded.length === 0)
+        return;
+    const off = discarded.filter((d) => d.reason === "off-checklist").length;
+    console.log(`\n  ${plural(discarded.length, "earlier answer")} from ${recordPath} ${discarded.length === 1 ? "is" : "are"} not carried into this record:`);
+    for (const d of discarded) {
+        console.log(`    - ${d.id}${d.subject === undefined ? "" : ` [${d.subject}]`}  ${d.claim}` +
+            (d.reason === "off-checklist"
+                ? "  (the feature changed; nothing asks this any more)"
+                : "  (no commit attestation binds it — its service must record it again)"));
+    }
+    if (discarded.length > off) {
+        console.log(`    Each owning service records its own with \`loam verify ${feature} --record answers.json --service <svc>\` in its repo.`);
+    }
+}
+//# sourceMappingURL=format.js.map

package/dist/commands/policy/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../src/commands/policy/format.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Small shaping helpers for the renderers.\n *\n * They live in `commands/` and not in `core/`: nothing here computes an answer,\n * it only decides how an answer READS. That was for a long time true of people\n * only — the header used to say \"the `--json` payloads never touch this file\",\n * and `fixesFor` below is the exception that retired the sentence. It is here\n * for the same reason the rest is: a fix string is not a verdict, it is the\n * shaping of one that has already been decided, and the module that owns the\n * text pointer to `loam explain` should own its machine form too, or the two\n * drift the way every second copy in this codebase eventually has.\n */\nimport { explainSubject } from \"../../core/explain/lookup.js\";\nimport { type DiscardedAnswer } from \"../../core/verify/build.js\";\n\n/**\n * \"1 service\", \"2 services\". The regular English plural, spelled once because\n * five renderers had drifted into five copies of the same ternary and a sixth\n * would have been written the next time somebody counted something. A noun with\n * an irregular plural does not belong here — say both forms at the call site.\n */\n/**\n * The one spelling of \"this run first recovered a predecessor's commit\" — it\n * existed in three copies (rebase, gherkin, verify --record) before vouch and\n * new needed a fourth and fifth, which is the extraction rule's third strike\n * twice over. Reported at all because docs changing beyond the command's own\n * writes would otherwise read as its doing.\n */\nexport function sayRecovered(r: { command: string; outcome: string; repaired: string[] }): string {\n  return (\n    `recovered an interrupted \\`loam ${r.command}\\` first (${r.outcome}` +\n    `${r.repaired.length === 0 ? \"\" : `: ${r.repaired.join(\", \")}`}).`\n  );\n}\n\nexport function plural(n: number, noun: string): string {\n  return `${n} ${noun}${n === 1 ? \"\" : \"s\"}`;\n}\n\n/**\n * The one spelling of the vocabulary pointer `validate` and `verify` append to\n * a TEXT report that printed findings — one string here rather than one per\n * renderer, because a hand-written second copy is exactly the drift the\n * pointer's target exists to prevent.\n *\n * It used to open with \"codes ride in `--json`\", and that clause existed for\n * one reason only: validate's text lines carried messages and no code strings,\n * so a footer asking the reader to explain \"a code above\" would have asked for\n * something never on their screen. That is no longer true — validate appends\n * the code to every non-`ok` finding and verify's notices have always led with\n * theirs (validate/report.ts, verify/report.ts) — so the clause has been\n * dropped rather than reworded: telling a reader to go re-run the command with\n * `--json` to find what is already two words to the left is worse than saying\n * nothing.\n *\n * Text mode only, and still: this SENTENCE never enters a payload. What\n * `--json` carries instead is the answer the sentence points at — `fixesFor`\n * below — because a machine reader has no use for being told a second command\n * exists, only for what it would have said.\n */\nexport const EXPLAIN_FOOTER =\n  \"→ `loam explain <code>` says what a code means and how to fix it\";\n\n/**\n * The machine form of the footer above: the codes a run actually raised,\n * resolved to what their fix tables say to do about them.\n *\n * The footer tells a PERSON that `loam explain <code>` exists. A `--json`\n * consumer got no such sentence — the payload is codes and prose messages, and\n * nothing in a finding says a fix is a lookup away — so an agent holding\n * `validate --all --json` either had the (now narrowable) /loam-check fix\n * tables in context already or spawned one `loam explain` process per code,\n * having first guessed that it could. This closes the gap by answering the\n * lookup in the same envelope.\n *\n * Resolved through `explainSubject` — the very function `loam explain <code>`\n * calls — and NOT through a second table, so the two surfaces cannot disagree\n * about what to do about a code. The cost is one walk of the shipped workflow\n * bodies per DISTINCT code (measured: 0.43ms each, so ~4ms for the nine codes\n * a fleet run typically raises). `listCodes()` would do one walk for all of\n * them, and was not used: it builds 227 answers to spend nine, and it would\n * only start paying off on a run that raised most of the vocabulary — which\n * is a repo with worse problems than the cost of its report.\n *\n * A code the tables do not grade is simply ABSENT from the result. There is no\n * placeholder string and there must not be one: the named backlog in\n * test/explain.test.ts is the record of which code families still have no row,\n * and a fabricated \"no fix recorded\" here would satisfy the eye at exactly the\n * place that record is supposed to itch.\n *\n * Two shaping rules, both forced by the tables rather than chosen:\n * - Keys are sorted and deduplicated, so two runs over the same findings\n *   produce byte-identical maps and a diff of two reports shows only what\n *   moved.\n * - Ten of the 227 finding codes are graded by more than one table, and nine\n *   of those ten say something DIFFERENT to do depending on the scope\n *   (`openapi.ref-unresolved` is one thing under `--service` and another at\n *   archive plan time). A single-fix code is emitted verbatim; a code whose\n *   tables disagree is emitted as its scope-labelled blocks, in table order,\n *   the same way `loam explain` prints it. Picking the first table's fix would\n *   be shorter and would sometimes be the wrong instruction, which is the one\n *   thing a fix string may not be.\n */\nexport function fixesFor(codes: readonly string[]): Record<string, string> {\n  const fixes: Record<string, string> = {};\n  for (const code of [...new Set(codes)].sort()) {\n    const explanation = explainSubject(code);\n    // Only the finding arm contributes. A refusal code is an `error.code` and\n    // never appears in a findings array, and a concept term is not a code at\n    // all — the three key sets are pinned pairwise disjoint by\n    // test/explain.test.ts, so this narrowing is a type guard, not a policy.\n    if (explanation === null || explanation.kind !== \"finding\") continue;\n    // Keyed by the fix so a code graded identically by two tables says it\n    // once, and valued by the FIRST scope that gave it so the labelled form\n    // reads in table order.\n    const byFix = new Map<string, string>();\n    for (const entry of explanation.entries) {\n      // A row whose \"what to do\" cell is empty states a consequence, not an\n      // action; it contributes nothing a caller could act on.\n      if (entry.fix !== \"\" && !byFix.has(entry.fix)) byFix.set(entry.fix, entry.scope);\n    }\n    const distinct = [...byFix];\n    if (distinct.length === 0) continue;\n    fixes[code] =\n      distinct.length === 1\n        ? distinct[0]![0]\n        : distinct.map(([fix, scope]) => `[${scope}] ${fix}`).join(\" \");\n  }\n  return fixes;\n}\n\n/**\n * What the previous record answered and the new one does not — printed, never\n * decided here (`buildFederatedVerification` decides; `verify --record`\n * reports). A federated write is a partial write, so the first one over an\n * all-at-once record drops every answer it cannot attribute to a commit —\n * correct, but silence there reads as loam having lost the answers, and nobody\n * goes looking for what to re-record. It lives beside `sayRecovered` because\n * it is the same kind of helper: one spelling of an account the command owes a\n * person about something the run did beyond its own answer.\n */\nexport function sayDiscarded(discarded: DiscardedAnswer[], recordPath: string, feature: string): void {\n  if (discarded.length === 0) return;\n  const off = discarded.filter((d) => d.reason === \"off-checklist\").length;\n  console.log(\n    `\\n  ${plural(discarded.length, \"earlier answer\")} from ${recordPath} ${discarded.length === 1 ? \"is\" : \"are\"} not carried into this record:`,\n  );\n  for (const d of discarded) {\n    console.log(\n      `    - ${d.id}${d.subject === undefined ? \"\" : ` [${d.subject}]`}  ${d.claim}` +\n        (d.reason === \"off-checklist\"\n          ? \"  (the feature changed; nothing asks this any more)\"\n          : \"  (no commit attestation binds it — its service must record it again)\"),\n    );\n  }\n  if (discarded.length > off) {\n    console.log(\n      `    Each owning service records its own with \\`loam verify ${feature} --record answers.json --service <svc>\\` in its repo.`,\n    );\n  }\n}\n"]}

package/dist/commands/{docs-repo-gate.js → policy/gate.js}

@@ -4,17 +4,18 @@
  * One doctrine, three ways of reaching it: the gate a command passes before it
  * enumerates anything, the error the enumeration throws when the repo goes away
  * underneath it, and the errno that comes back when the repo is real but one
- * file under it will not open. Six commands reach for one or another of them
- * (`adopt`, `list`, `new`, `show`, `status`, `validate`), and the whole point of
- * collecting them is that all six answer with the same sentences.
+ * file under it will not open. Every command that reads a docs repo reaches
+ * for one or another of them (`rg docsRepoReady` is the always-current list),
+ * and the whole point of collecting them is that they all answer with the same
+ * sentences.
  *
  * They live in `commands/` rather than in `core/`: each one calls `fail`, which
  * writes to stdout or stderr and sets the exit code. That is a decision about
  * how this process ends, and core modules compute answers rather than end
  * processes.
  */
-import { fail } from "../core/json.js";
-import { docsRepoState } from "../core/repo.js";
+import { fail } from "../../core/envelope/json.js";
+import { docsRepoState } from "../../core/repo/state.js";
 /**
  * The refusal every READ command owes a `docsDir` that is not a docs repo.
  *
@@ -37,11 +38,10 @@ import { docsRepoState } from "../core/repo.js";
  * the directory that IS the list of services.
  *
  * It used to live in validate.ts, on the reasoning that validate is the fleet
- * gate this doctrine is about. Six commands import it now (`adopt`, `list`,
- * `new`, `show`, `status`, `validate`), so the doctrine outgrew its host: `loam
- * show` was structurally depending on the whole validate implementation for
- * twenty lines of policy. The rule is the module now, and validate is one of
- * its callers like the rest.
+ * gate this doctrine is about. Enough commands import it now that the doctrine
+ * outgrew its host: `loam show` was structurally depending on the whole
+ * validate implementation for twenty lines of policy. The rule is the module
+ * now, and validate is one of its callers like the rest.
  */
 export function docsRepoReady(json, docsDir, need) {
     const state = docsRepoState(docsDir);
@@ -101,4 +101,4 @@ export function reportRepositoryUnavailable(json, err, consequence, docsDir) {
             `A file under ${docsDir} could not be read, so ${consequence}. ${why}. ` +
                 `The failure named no path — that is how Node reports a directory sitting where a file belongs.`);
 }
-//# sourceMappingURL=docs-repo-gate.js.map
+//# sourceMappingURL=gate.js.map

package/dist/commands/policy/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/commands/policy/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACnD,OAAO,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,OAAe,EAAE,IAAyB;IACrF,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1F,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CACF,IAAI,EACJ,cAAc,EACd,4CAA4C,KAAK,CAAC,IAAI,IAAI;YACxD,yDAAyD;YACzD,6DAA6D,CAChE,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CACF,IAAI,EACJ,kBAAkB,EAClB,GAAG,KAAK,CAAC,IAAI,uDAAuD;QAClE,wDAAwD;QACxD,uDAAuD,CAC1D,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa,EAAE,GAA6B;IAC9E,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,kBAAkB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;AAC9F,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAa,EACb,GAAY,EACZ,WAAmB,EACnB,OAAe;IAEf,MAAM,CAAC,GAAG,GAA4B,CAAC;IACvC,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,MAAM,GAAG,CAAC;IACnE,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,CACF,IAAI,EACJ,wBAAwB,EACxB,CAAC,CAAC,IAAI,KAAK,SAAS;QAClB,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,0BAA0B,WAAW,KAAK,GAAG,EAAE;QAC1D,CAAC,CAAC,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,wCAAwC;YACxC,gBAAgB,OAAO,0BAA0B,WAAW,KAAK,GAAG,IAAI;gBACxE,gGAAgG,CACrG,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The three refusals every command owes a docs repo it cannot read.\n *\n * One doctrine, three ways of reaching it: the gate a command passes before it\n * enumerates anything, the error the enumeration throws when the repo goes away\n * underneath it, and the errno that comes back when the repo is real but one\n * file under it will not open. Every command that reads a docs repo reaches\n * for one or another of them (`rg docsRepoReady` is the always-current list),\n * and the whole point of collecting them is that they all answer with the same\n * sentences.\n *\n * They live in `commands/` rather than in `core/`: each one calls `fail`, which\n * writes to stdout or stderr and sets the exit code. That is a decision about\n * how this process ends, and core modules compute answers rather than end\n * processes.\n */\nimport { fail } from \"../../core/envelope/json.js\";\nimport { docsRepoState, type DocsRepoUnavailableError } from \"../../core/repo/state.js\";\n\n/**\n * The refusal every READ command owes a `docsDir` that is not a docs repo.\n *\n * It is not a formality. `validate --all` and `list` used to answer a docsDir\n * that does not exist with a green report over zero services, which is the one\n * output a fleet gate must never produce: \"nothing is wrong\" and \"I could not\n * look\" are opposite facts, and in CI the first one merges. The two codes are\n * kept apart because the fixes point in different directions — a wrong path in\n * loam.json versus a docs repo that was never cloned or scaffolded — exactly\n * the way `no-config` and `config-invalid` are kept apart.\n *\n * \"Zero services\" stays reachable, and only from a REAL docs repo whose\n * `services/` is empty: that is a legitimate state (before the first\n * `loam adopt`) and it must keep exiting 0.\n *\n * `need` says how much of a docs repo this particular run has to have. A run\n * that only reads features genuinely does not need `services/` — repo.ts takes\n * the same position for `listFeatures` — and refusing there would turn one\n * diagnosis into two contradictory ones. A run that enumerates services needs\n * the directory that IS the list of services.\n *\n * It used to live in validate.ts, on the reasoning that validate is the fleet\n * gate this doctrine is about. Enough commands import it now that the doctrine\n * outgrew its host: `loam show` was structurally depending on the whole\n * validate implementation for twenty lines of policy. The rule is the module\n * now, and validate is one of its callers like the rest.\n */\nexport function docsRepoReady(json: boolean, docsDir: string, need: \"docs\" | \"services\"): boolean {\n  const state = docsRepoState(docsDir);\n  if (state.kind === \"ok\" || (state.kind === \"no-services\" && need === \"docs\")) return true;\n  if (state.kind === \"missing\") {\n    fail(\n      json,\n      \"docs-missing\",\n      `The configured docs repo does not exist: ${state.path}. ` +\n        \"Fix `docsDir` in loam.json, clone the docs repo there, \" +\n        \"or run `loam init --docs <dir> --create` to make a new one.\",\n    );\n    return false;\n  }\n  fail(\n    json,\n    \"services-missing\",\n    `${state.path} is not a docs repo — it has no services/ directory. ` +\n      \"Point `docsDir` in loam.json at the shared docs repo, \" +\n      \"or run `loam init --docs <dir> --create` to make one.\",\n  );\n  return false;\n}\n\n/**\n * The same refusal, reached the other way: `listServices`/`listFeatures` throw\n * `DocsRepoUnavailableError` when the repo goes away mid-run (or when a caller\n * reaches enumeration without passing the gate above). Mapping it back onto the\n * same two codes keeps one breach spelled one way, instead of surfacing as the\n * `internal` catch-all in cli.ts.\n */\nexport function reportDocsRepoError(json: boolean, err: DocsRepoUnavailableError): void {\n  fail(json, err.state.kind === \"missing\" ? \"docs-missing\" : \"services-missing\", err.message);\n}\n\n/**\n * The third refusal a reading command owes: the docs repo IS a docs repo, but\n * one file under it cannot be read. `list`, `show`, `status` and `validate` all\n * walk a directory tree to answer, so all four owe the same sentence — and all\n * four kept their own copy of it, which is exactly how three of them ended up\n * wrong. Sharing it here, beside `reportDocsRepoError`, is the same trade: one\n * breach spelled one way instead of four that drift.\n *\n * A filesystem failure is recognised by its errno, NOT by carrying a `path`.\n * Node reports EISDIR from `read()` with no path at all — the directory opened,\n * the read failed — so a guard that looked only for `path` was defeated by the\n * commonest way a malformed docs repo breaks: one directory sitting where a\n * file belongs escaped as a bare `internal: EISDIR`, naming neither the file\n * nor the target. Anything carrying no errno at all is a real bug, and still\n * escapes untouched.\n *\n * `consequence` is the clause after \"so\" — what the caller could not answer\n * because of this. It is the only part that differs between the four.\n */\nexport function reportRepositoryUnavailable(\n  json: boolean,\n  err: unknown,\n  consequence: string,\n  docsDir: string,\n): void {\n  const e = err as NodeJS.ErrnoException;\n  if (e.path === undefined && typeof e.errno !== \"number\") throw err;\n  const why = err instanceof Error ? err.message : String(err);\n  fail(\n    json,\n    \"repository-unavailable\",\n    e.path !== undefined\n      ? `${e.path} could not be read, so ${consequence}. ${why}`\n      : // Naming the target's own directory here would be a guess, and a guess\n        // that is wrong precisely when it matters: one malformed artifact makes\n        // every OTHER target's answer fail too, and each would have accused its\n        // own files. Say what is known instead.\n        `A file under ${docsDir} could not be read, so ${consequence}. ${why}. ` +\n        `The failure named no path — that is how Node reports a directory sitting where a file belongs.`,\n  );\n}\n"]}

package/dist/commands/rebase/edit.js

@@ -0,0 +1,106 @@
+/**
+ * Line surgery: insert one `Based-On:` line without touching anything else.
+ *
+ * `loam rebase` rewrites a pin inside a document a person wrote. Reserializing
+ * through `serializeRequirements` would be simpler and would flatten every
+ * section heading and paragraph the author put between requirements — so the
+ * parser records the heading LINE of each requirement and this module edits
+ * exactly there, leaving every other byte as found.
+ */
+import { REALIZES_LINE_RE } from "../../core/document/spec.js";
+/**
+ * Where this requirement's `Based-On:` line goes, and whether it replaces one.
+ *
+ * `headingLine` is 1-based and `text` captures every body line after it
+ * contiguously (core/document/parse.ts), so body line `i` is the 0-based document line
+ * `headingLine + i` — no rescan of the document, and no second opinion about
+ * where a requirement begins. A new pin lands directly under `Requirement-ID:`
+ * when there is one, matching what `serializeRequirements` writes, and
+ * otherwise as the first body line: the two identity lines are read together,
+ * so they are kept together.
+ */
+export function pinEdit(r, headingLine, digest) {
+    const text = `Based-On: ${digest}`;
+    const existing = r.text.findIndex((line) => /^\s*Based-On:/i.test(line));
+    if (existing >= 0)
+        return { at: headingLine + existing, mode: "replace", text };
+    const afterId = r.text.findIndex((line) => /^\s*Requirement-ID:/i.test(line));
+    return { at: headingLine + afterId + 1, mode: "insert", text };
+}
+/**
+ * Rewrite one requirement's `Realizes:` line so every entry carries the pin
+ * `pinned` supplies for it, or `null` when the line already reads that way.
+ *
+ * ALWAYS A REPLACE, never an insert, and that is the difference from `pinEdit`
+ * above: a `Based-On:` line is bookkeeping loam may add to a requirement that
+ * has none, while a `Realizes:` line is a claim a human made. loam re-spells
+ * the claim it finds and never invents one — a requirement that realizes
+ * nothing has nothing to pin, and writing a line there would be loam asserting
+ * a join on somebody's behalf.
+ *
+ * Entry order, spacing after the colon and the author's own separator run are
+ * preserved by rebuilding from the captured text rather than from the parsed
+ * array: this is line surgery inside a document somebody wrote, and a
+ * normalization nobody asked for would land in every diff.
+ */
+export function realizesPinEdit(r, headingLine, pinned) {
+    const at = r.text.findIndex((line) => REALIZES_LINE_RE.test(line));
+    if (at < 0)
+        return null;
+    const line = r.text[at];
+    const match = REALIZES_LINE_RE.exec(line);
+    const rewritten = match[1]
+        .split(",")
+        .map((entry) => {
+        const trimmed = entry.trim();
+        return entry.replace(trimmed, pinned(trimmed));
+    })
+        .join(",");
+    if (rewritten === match[1])
+        return null;
+    return { at: headingLine + at, mode: "replace", text: line.replace(match[1], rewritten) };
+}
+/**
+ * Split into lines that remember their own terminator, indexed exactly as
+ * `parseRequirements` counts them.
+ */
+export function toLines(raw) {
+    // split with a captured separator yields [content, sep, content, sep, …, content].
+    const parts = raw.split(/(\r?\n)/);
+    const lines = [];
+    for (let i = 0; i < parts.length; i += 2)
+        lines.push({ text: parts[i], eol: parts[i + 1] ?? "" });
+    return lines;
+}
+/**
+ * Apply line edits to a document, preserving every byte they do not name.
+ *
+ * Each line keeps its own terminator, so a CRLF document stays CRLF and a file
+ * that ends without a newline does not grow one — rejoining on a single
+ * "detected" newline would rewrite the line endings of a whole file whose
+ * author asked for one line to change. Edits are applied bottom-up so an
+ * insertion never shifts the index of one still to come.
+ */
+export function applyEdits(raw, edits) {
+    const lines = toLines(raw);
+    const eol = lines.find((line) => line.eol !== "")?.eol ?? "\n";
+    for (const edit of [...edits].sort((a, b) => b.at - a.at)) {
+        if (edit.mode === "replace") {
+            lines[edit.at].text = edit.text;
+            continue;
+        }
+        const before = edit.at > 0 ? lines[edit.at - 1] : undefined;
+        if (before !== undefined && before.eol === "") {
+            // Inserting past a file that ends without a newline: the old last line
+            // needs a terminator, and the new line inherits its unterminated end so
+            // the file keeps the shape its author gave it.
+            before.eol = eol;
+            lines.splice(edit.at, 0, { text: edit.text, eol: "" });
+        }
+        else {
+            lines.splice(edit.at, 0, { text: edit.text, eol: before?.eol ?? eol });
+        }
+    }
+    return lines.map((line) => line.text + line.eol).join("");
+}
+//# sourceMappingURL=edit.js.map

package/dist/commands/rebase/edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../../src/commands/rebase/edit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Line surgery: insert one `Based-On:` line without touching anything else.\n *\n * `loam rebase` rewrites a pin inside a document a person wrote. Reserializing\n * through `serializeRequirements` would be simpler and would flatten every\n * section heading and paragraph the author put between requirements — so the\n * parser records the heading LINE of each requirement and this module edits\n * exactly there, leaving every other byte as found.\n */\nimport { REALIZES_LINE_RE, type Requirement } from \"../../core/document/spec.js\";\n\nexport interface LineEdit {\n  /** 0-based line index, as `parseRequirements` counts lines. */\n  at: number;\n  /** Replace that line, or insert a new one before it. */\n  mode: \"replace\" | \"insert\";\n  text: string;\n}\n\n/**\n * Where this requirement's `Based-On:` line goes, and whether it replaces one.\n *\n * `headingLine` is 1-based and `text` captures every body line after it\n * contiguously (core/document/parse.ts), so body line `i` is the 0-based document line\n * `headingLine + i` — no rescan of the document, and no second opinion about\n * where a requirement begins. A new pin lands directly under `Requirement-ID:`\n * when there is one, matching what `serializeRequirements` writes, and\n * otherwise as the first body line: the two identity lines are read together,\n * so they are kept together.\n */\nexport function pinEdit(r: Requirement, headingLine: number, digest: string): LineEdit {\n  const text = `Based-On: ${digest}`;\n  const existing = r.text.findIndex((line) => /^\\s*Based-On:/i.test(line));\n  if (existing >= 0) return { at: headingLine + existing, mode: \"replace\", text };\n  const afterId = r.text.findIndex((line) => /^\\s*Requirement-ID:/i.test(line));\n  return { at: headingLine + afterId + 1, mode: \"insert\", text };\n}\n\n/**\n * Rewrite one requirement's `Realizes:` line so every entry carries the pin\n * `pinned` supplies for it, or `null` when the line already reads that way.\n *\n * ALWAYS A REPLACE, never an insert, and that is the difference from `pinEdit`\n * above: a `Based-On:` line is bookkeeping loam may add to a requirement that\n * has none, while a `Realizes:` line is a claim a human made. loam re-spells\n * the claim it finds and never invents one — a requirement that realizes\n * nothing has nothing to pin, and writing a line there would be loam asserting\n * a join on somebody's behalf.\n *\n * Entry order, spacing after the colon and the author's own separator run are\n * preserved by rebuilding from the captured text rather than from the parsed\n * array: this is line surgery inside a document somebody wrote, and a\n * normalization nobody asked for would land in every diff.\n */\nexport function realizesPinEdit(\n  r: Requirement,\n  headingLine: number,\n  pinned: (entry: string) => string,\n): LineEdit | null {\n  const at = r.text.findIndex((line) => REALIZES_LINE_RE.test(line));\n  if (at < 0) return null;\n  const line = r.text[at]!;\n  const match = REALIZES_LINE_RE.exec(line)!;\n  const rewritten = match[1]!\n    .split(\",\")\n    .map((entry) => {\n      const trimmed = entry.trim();\n      return entry.replace(trimmed, pinned(trimmed));\n    })\n    .join(\",\");\n  if (rewritten === match[1]!) return null;\n  return { at: headingLine + at, mode: \"replace\", text: line.replace(match[1]!, rewritten) };\n}\n\n/** One line of the document with the terminator it was written with. */\nexport interface Line {\n  text: string;\n  /** \"\\n\", \"\\r\\n\", or \"\" for a last line the file does not terminate. */\n  eol: string;\n}\n\n/**\n * Split into lines that remember their own terminator, indexed exactly as\n * `parseRequirements` counts them.\n */\nexport function toLines(raw: string): Line[] {\n  // split with a captured separator yields [content, sep, content, sep, …, content].\n  const parts = raw.split(/(\\r?\\n)/);\n  const lines: Line[] = [];\n  for (let i = 0; i < parts.length; i += 2) lines.push({ text: parts[i]!, eol: parts[i + 1] ?? \"\" });\n  return lines;\n}\n\n/**\n * Apply line edits to a document, preserving every byte they do not name.\n *\n * Each line keeps its own terminator, so a CRLF document stays CRLF and a file\n * that ends without a newline does not grow one — rejoining on a single\n * \"detected\" newline would rewrite the line endings of a whole file whose\n * author asked for one line to change. Edits are applied bottom-up so an\n * insertion never shifts the index of one still to come.\n */\nexport function applyEdits(raw: string, edits: LineEdit[]): string {\n  const lines = toLines(raw);\n  const eol = lines.find((line) => line.eol !== \"\")?.eol ?? \"\\n\";\n  for (const edit of [...edits].sort((a, b) => b.at - a.at)) {\n    if (edit.mode === \"replace\") {\n      lines[edit.at]!.text = edit.text;\n      continue;\n    }\n    const before = edit.at > 0 ? lines[edit.at - 1] : undefined;\n    if (before !== undefined && before.eol === \"\") {\n      // Inserting past a file that ends without a newline: the old last line\n      // needs a terminator, and the new line inherits its unterminated end so\n      // the file keeps the shape its author gave it.\n      before.eol = eol;\n      lines.splice(edit.at, 0, { text: edit.text, eol: \"\" });\n    } else {\n      lines.splice(edit.at, 0, { text: edit.text, eol: before?.eol ?? eol });\n    }\n  }\n  return lines.map((line) => line.text + line.eol).join(\"\");\n}\n"]}

package/dist/commands/rebase/living.js

@@ -0,0 +1,185 @@
+/**
+ * `loam rebase --living` — re-pin the LIVING corpus's `Realizes:` entries to the
+ * capability requirements they currently name.
+ *
+ * The other half of `capability.realizes-stale`. That finding says a promise
+ * moved under a claim; this is the act that records having re-read it. The two
+ * are deliberately separate commands and not one self-healing pass, for the
+ * reason the finding's own comment gives: a stale pin has three legitimate
+ * outcomes and only one of them is "the requirement was right as it stands".
+ * loam cannot tell which, so it reports, and a human runs this when they have
+ * decided.
+ *
+ * WHY IT IS NOT PART OF `rebase <FEAT>`. That command pins a FEATURE's deltas
+ * against living text — bookkeeping inside a change window, thrown away when
+ * the feature archives. This pins the living documents themselves, against the
+ * living business tree, with no feature involved at all. Same verb because the
+ * act is the same one (record which version I read), different scope because
+ * the documents are.
+ *
+ * IT WRITES NOTHING ELSE. No `Based-On:`, no contract pins, no reserialize —
+ * one `Realizes:` line per requirement that has one, through the same line
+ * surgery `./edit.ts` performs for every other pin, so a living spec's headings,
+ * prose and ordering survive byte for byte.
+ */
+import { existsSync } from "node:fs";
+import { parseRequirements, readRequirementsDocument } from "../../core/document/parse.js";
+import { NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
+import { splitRealizesPin } from "../../core/document/spec.js";
+import { resolveRealizes, splitRealizesEntry, } from "../../core/capabilities/realizes/join.js";
+import { capabilityRequirementIndex } from "../../core/capabilities/findings.js";
+import { emitJson, fail } from "../../core/envelope/json.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { listServices } from "../../core/repo/repo.js";
+import { servicePathsAt, SPEC_AXES } from "../../core/repo/paths.js";
+import { stageWrites } from "../../core/staging/commit.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import { plural } from "../policy/format.js";
+import { applyEdits, realizesPinEdit } from "./edit.js";
+/**
+ * Plan one living requirements document's pins against the capability index.
+ *
+ * The index is the caller's, built once for the whole run: it is the same
+ * fleet-wide read `validate --all` takes, and rebuilding it per service would
+ * re-parse every capability document once per service in the fleet.
+ */
+export async function planLivingRealizes(service, file, specPath, index) {
+    if (!existsSync(specPath))
+        return { outcomes: [], content: null };
+    // The decoding read, for `planRequirementPins`'s reason one module over: line
+    // surgery over bytes loam mis-decoded would write text nobody authored.
+    const raw = await readRequirementsDocument(specPath);
+    const reqs = parseRequirements(raw);
+    const outcomes = [];
+    const edits = [];
+    for (const r of reqs) {
+        // REMOVED is skipped wherever `Realizes:` is read; a requirement built in
+        // memory has no document line to write into, so there is nothing truthful
+        // to report about pinning it.
+        if (r.kind === "REMOVED" || r.line === undefined)
+            continue;
+        if (r.realizes.length === 0)
+            continue;
+        // The resolution and the rewrite must agree entry for entry, so both read
+        // the SAME claim list rather than each splitting the strings again.
+        const wanted = new Map();
+        for (const claim of resolveRealizes(r.realizes, index)) {
+            const base = { service, file, target: r.name, entry: claim.entry };
+            if (claim.kind !== "resolved") {
+                outcomes.push({ ...base, status: "unresolved", from: splitRealizesPin(claim.entry).pin, to: null });
+                continue;
+            }
+            const { pin, current } = claim;
+            if (current === null) {
+                // Resolved against an index that carries no digest for it — the feature
+                // overlay's shape, and not a state a living run reaches. Reported as
+                // unresolved rather than silently skipped: a pin loam declined to write
+                // must never look like a pin it wrote.
+                outcomes.push({ ...base, status: "unresolved", from: pin, to: null });
+                continue;
+            }
+            if (pin === current) {
+                outcomes.push({ ...base, status: "unchanged", from: pin, to: pin });
+                continue;
+            }
+            wanted.set(claim.entry, `${splitRealizesPin(claim.entry).target}@${current}`);
+            outcomes.push({
+                ...base,
+                status: pin === null ? "pinned" : "repinned",
+                from: pin,
+                to: current,
+            });
+        }
+        if (wanted.size === 0)
+            continue;
+        const edit = realizesPinEdit(r, r.line, (entry) => wanted.get(entry) ?? entry);
+        if (edit !== null)
+            edits.push(edit);
+    }
+    return { outcomes, content: edits.length === 0 ? null : applyEdits(raw, edits) };
+}
+/** Entries that would change — what the human view counts and `--dry-run` prints. */
+export function changedPins(outcomes) {
+    return outcomes.filter((o) => o.status === "pinned" || o.status === "repinned");
+}
+/**
+ * The bare target of an entry — exported so a caller can report what an
+ * unresolved entry pointed at without re-deriving the separator rule.
+ */
+export function entryTarget(entry) {
+    const target = splitRealizesEntry(entry);
+    return target === null ? entry : `${target.capability}#${target.requirement}`;
+}
+/**
+ * The whole `--living` run, under the lock the caller already holds.
+ *
+ * Order of operations mirrors `rebaseLocked`: read everything, plan everything,
+ * then commit once. A fleet's `Realizes:` corpus is one claim about one version
+ * of the business tree, so pinning four services against a tree that moved
+ * between the second and the third is exactly the split reading the pin exists
+ * to make impossible.
+ */
+export async function rebaseLivingLocked(docsDir, opts) {
+    const json = opts.json === true;
+    const dryRun = opts.dryRun === true;
+    const fleet = new FleetContext();
+    const capabilities = await fleet.capabilities(docsDir);
+    const index = await capabilityRequirementIndex(capabilities, (p) => fleet.readRequirements(p));
+    if (index.declared === null) {
+        // The ladder, one command over from where `../validate` applies it: a fleet
+        // with no gradable capability vocabulary has no versions to pin against,
+        // and stamping digests from a file loam could not read would be the false
+        // claim the whole pin mechanism exists to refuse.
+        return fail(json, "unknown-target", "this docs repo declares no readable capability vocabulary, so no `Realizes:` entry has a version to pin — " +
+            "write `architecture/capabilities.yaml` or a `capabilities/<id>/spec.md` first, or fix the one that does not parse (`loam validate --all`).");
+    }
+    const all = await listServices(docsDir, fleet);
+    const services = opts.service === undefined ? all : all.filter((s) => s.id === opts.service);
+    if (opts.service !== undefined && services.length === 0) {
+        return fail(json, "unknown-target", `no service '${opts.service}' in this docs repo` +
+            (all.length === 0 ? " — it holds none." : ` — it holds: ${all.map((s) => s.id).join(", ")}.`));
+    }
+    const outcomes = [];
+    const writes = [];
+    try {
+        for (const entry of services) {
+            const paths = servicePathsAt(entry.dir);
+            for (const axis of SPEC_AXES) {
+                const planned = await planLivingRealizes(entry.id, axis.file, paths[axis.key], index);
+                outcomes.push(...planned.outcomes);
+                if (planned.content !== null)
+                    writes.push({ path: paths[axis.key], content: planned.content });
+            }
+        }
+    }
+    catch (err) {
+        if (!(err instanceof NotUtf8DocumentError))
+            throw err;
+        return fail(json, "merge-failed", `rebase --living failed — nothing was pinned: ${err.message}`);
+    }
+    const changed = changedPins(outcomes);
+    if (!dryRun && writes.length > 0) {
+        const staged = await stageWrites(writes);
+        const committed = await commitStaged({ root: docsDir, command: "rebase", rerun: "loam rebase --living", target: "living" }, staged, "pinned");
+        if (!committed.ok) {
+            return fail(json, "merge-failed", `rebase --living failed — ${committed.message}`);
+        }
+    }
+    if (json) {
+        return emitJson({ command: "rebase", ok: true, mode: "living", dryRun, pinned: changed.length, outcomes });
+    }
+    const unresolved = outcomes.filter((o) => o.status === "unresolved");
+    console.log(changed.length === 0
+        ? `Nothing to pin — every \`Realizes:\` entry in ${plural(services.length, "service")} already names the version it points at.`
+        : `${dryRun ? "Would pin" : "Pinned"} ${changed.length} entr${changed.length === 1 ? "y" : "ies"} across ${plural(writes.length, "document")}.`);
+    for (const o of changed) {
+        console.log(`  ${o.status === "pinned" ? "+" : "~"} ${o.service}/${o.file}: '${o.target}' → ${entryTarget(o.entry)}@${o.to}`);
+    }
+    for (const o of unresolved) {
+        console.log(`  ? ${o.service}/${o.file}: '${o.target}' realizes ${entryTarget(o.entry)}, which nothing declares — not pinned`);
+    }
+    if (changed.length > 0 && !dryRun) {
+        console.log("\nA pin says you re-read the promise. Restamping without reading it is the one way to make this a lie with a digest on it.");
+    }
+}
+//# sourceMappingURL=living.js.map

package/dist/commands/rebase/living.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"living.js","sourceRoot":"","sources":["../../../src/commands/rebase/living.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam rebase --living` — re-pin the LIVING corpus's `Realizes:` entries to the\n * capability requirements they currently name.\n *\n * The other half of `capability.realizes-stale`. That finding says a promise\n * moved under a claim; this is the act that records having re-read it. The two\n * are deliberately separate commands and not one self-healing pass, for the\n * reason the finding's own comment gives: a stale pin has three legitimate\n * outcomes and only one of them is \"the requirement was right as it stands\".\n * loam cannot tell which, so it reports, and a human runs this when they have\n * decided.\n *\n * WHY IT IS NOT PART OF `rebase <FEAT>`. That command pins a FEATURE's deltas\n * against living text — bookkeeping inside a change window, thrown away when\n * the feature archives. This pins the living documents themselves, against the\n * living business tree, with no feature involved at all. Same verb because the\n * act is the same one (record which version I read), different scope because\n * the documents are.\n *\n * IT WRITES NOTHING ELSE. No `Based-On:`, no contract pins, no reserialize —\n * one `Realizes:` line per requirement that has one, through the same line\n * surgery `./edit.ts` performs for every other pin, so a living spec's headings,\n * prose and ordering survive byte for byte.\n */\nimport { existsSync } from \"node:fs\";\nimport { parseRequirements, readRequirementsDocument } from \"../../core/document/parse.js\";\nimport { NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport { splitRealizesPin } from \"../../core/document/spec.js\";\nimport {\n  resolveRealizes,\n  splitRealizesEntry,\n  type CapabilityRequirementIndex,\n} from \"../../core/capabilities/realizes/join.js\";\nimport { capabilityRequirementIndex } from \"../../core/capabilities/findings.js\";\nimport { emitJson, fail } from \"../../core/envelope/json.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { listServices } from \"../../core/repo/repo.js\";\nimport { servicePathsAt, SPEC_AXES } from \"../../core/repo/paths.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport type { PlannedWrite } from \"../../core/staging/writes.js\";\nimport { plural } from \"../policy/format.js\";\nimport { applyEdits, realizesPinEdit, type LineEdit } from \"./edit.js\";\n\n/** What happened to one living `Realizes:` entry. */\nexport interface LivingPinOutcome {\n  service: string;\n  /** `spec.md` or `arch.spec.md` — which axis carried the line. */\n  file: string;\n  /** The requirement's `### Requirement:` heading. */\n  target: string;\n  /** The entry as authored, pin and all. */\n  entry: string;\n  /**\n   * `pinned` — it carried none and now does. `repinned` — the promise moved and\n   * this records the re-read. `unchanged` — already correct, no write.\n   * `unresolved` — the entry names nothing the tree declares, so there is no\n   * version to pin; `capability.realizes-unknown` is that entry's finding and\n   * inventing a digest for it would put loam's stamp on a broken join.\n   */\n  status: \"pinned\" | \"repinned\" | \"unchanged\" | \"unresolved\";\n  from: string | null;\n  to: string | null;\n}\n\nexport interface LivingAxisPlan {\n  outcomes: LivingPinOutcome[];\n  /** The rewritten document, or `null` when nothing changed. */\n  content: string | null;\n}\n\n/**\n * Plan one living requirements document's pins against the capability index.\n *\n * The index is the caller's, built once for the whole run: it is the same\n * fleet-wide read `validate --all` takes, and rebuilding it per service would\n * re-parse every capability document once per service in the fleet.\n */\nexport async function planLivingRealizes(\n  service: string,\n  file: string,\n  specPath: string,\n  index: CapabilityRequirementIndex,\n): Promise<LivingAxisPlan> {\n  if (!existsSync(specPath)) return { outcomes: [], content: null };\n  // The decoding read, for `planRequirementPins`'s reason one module over: line\n  // surgery over bytes loam mis-decoded would write text nobody authored.\n  const raw = await readRequirementsDocument(specPath);\n  const reqs = parseRequirements(raw);\n\n  const outcomes: LivingPinOutcome[] = [];\n  const edits: LineEdit[] = [];\n  for (const r of reqs) {\n    // REMOVED is skipped wherever `Realizes:` is read; a requirement built in\n    // memory has no document line to write into, so there is nothing truthful\n    // to report about pinning it.\n    if (r.kind === \"REMOVED\" || r.line === undefined) continue;\n    if (r.realizes.length === 0) continue;\n\n    // The resolution and the rewrite must agree entry for entry, so both read\n    // the SAME claim list rather than each splitting the strings again.\n    const wanted = new Map<string, string>();\n    for (const claim of resolveRealizes(r.realizes, index)) {\n      const base = { service, file, target: r.name, entry: claim.entry };\n      if (claim.kind !== \"resolved\") {\n        outcomes.push({ ...base, status: \"unresolved\", from: splitRealizesPin(claim.entry).pin, to: null });\n        continue;\n      }\n      const { pin, current } = claim;\n      if (current === null) {\n        // Resolved against an index that carries no digest for it — the feature\n        // overlay's shape, and not a state a living run reaches. Reported as\n        // unresolved rather than silently skipped: a pin loam declined to write\n        // must never look like a pin it wrote.\n        outcomes.push({ ...base, status: \"unresolved\", from: pin, to: null });\n        continue;\n      }\n      if (pin === current) {\n        outcomes.push({ ...base, status: \"unchanged\", from: pin, to: pin });\n        continue;\n      }\n      wanted.set(claim.entry, `${splitRealizesPin(claim.entry).target}@${current}`);\n      outcomes.push({\n        ...base,\n        status: pin === null ? \"pinned\" : \"repinned\",\n        from: pin,\n        to: current,\n      });\n    }\n    if (wanted.size === 0) continue;\n    const edit = realizesPinEdit(r, r.line, (entry) => wanted.get(entry) ?? entry);\n    if (edit !== null) edits.push(edit);\n  }\n\n  return { outcomes, content: edits.length === 0 ? null : applyEdits(raw, edits) };\n}\n\n/** Entries that would change — what the human view counts and `--dry-run` prints. */\nexport function changedPins(outcomes: readonly LivingPinOutcome[]): LivingPinOutcome[] {\n  return outcomes.filter((o) => o.status === \"pinned\" || o.status === \"repinned\");\n}\n\n/**\n * The bare target of an entry — exported so a caller can report what an\n * unresolved entry pointed at without re-deriving the separator rule.\n */\nexport function entryTarget(entry: string): string {\n  const target = splitRealizesEntry(entry);\n  return target === null ? entry : `${target.capability}#${target.requirement}`;\n}\n\n/**\n * The whole `--living` run, under the lock the caller already holds.\n *\n * Order of operations mirrors `rebaseLocked`: read everything, plan everything,\n * then commit once. A fleet's `Realizes:` corpus is one claim about one version\n * of the business tree, so pinning four services against a tree that moved\n * between the second and the third is exactly the split reading the pin exists\n * to make impossible.\n */\nexport async function rebaseLivingLocked(\n  docsDir: DocsDir,\n  opts: { service?: string; json?: boolean; dryRun?: boolean },\n): Promise<void> {\n  const json = opts.json === true;\n  const dryRun = opts.dryRun === true;\n  const fleet = new FleetContext();\n\n  const capabilities = await fleet.capabilities(docsDir);\n  const index = await capabilityRequirementIndex(capabilities, (p) => fleet.readRequirements(p));\n  if (index.declared === null) {\n    // The ladder, one command over from where `../validate` applies it: a fleet\n    // with no gradable capability vocabulary has no versions to pin against,\n    // and stamping digests from a file loam could not read would be the false\n    // claim the whole pin mechanism exists to refuse.\n    return fail(\n      json,\n      \"unknown-target\",\n      \"this docs repo declares no readable capability vocabulary, so no `Realizes:` entry has a version to pin — \" +\n        \"write `architecture/capabilities.yaml` or a `capabilities/<id>/spec.md` first, or fix the one that does not parse (`loam validate --all`).\",\n    );\n  }\n\n  const all = await listServices(docsDir, fleet);\n  const services = opts.service === undefined ? all : all.filter((s) => s.id === opts.service);\n  if (opts.service !== undefined && services.length === 0) {\n    return fail(\n      json,\n      \"unknown-target\",\n      `no service '${opts.service}' in this docs repo` +\n        (all.length === 0 ? \" — it holds none.\" : ` — it holds: ${all.map((s) => s.id).join(\", \")}.`),\n    );\n  }\n\n  const outcomes: LivingPinOutcome[] = [];\n  const writes: PlannedWrite[] = [];\n  try {\n    for (const entry of services) {\n      const paths = servicePathsAt(entry.dir);\n      for (const axis of SPEC_AXES) {\n        const planned = await planLivingRealizes(entry.id, axis.file, paths[axis.key], index);\n        outcomes.push(...planned.outcomes);\n        if (planned.content !== null) writes.push({ path: paths[axis.key], content: planned.content });\n      }\n    }\n  } catch (err) {\n    if (!(err instanceof NotUtf8DocumentError)) throw err;\n    return fail(json, \"merge-failed\", `rebase --living failed — nothing was pinned: ${err.message}`);\n  }\n\n  const changed = changedPins(outcomes);\n  if (!dryRun && writes.length > 0) {\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"rebase\", rerun: \"loam rebase --living\", target: \"living\" },\n      staged,\n      \"pinned\",\n    );\n    if (!committed.ok) {\n      return fail(json, \"merge-failed\", `rebase --living failed — ${committed.message}`);\n    }\n  }\n\n  if (json) {\n    return emitJson({ command: \"rebase\", ok: true, mode: \"living\", dryRun, pinned: changed.length, outcomes });\n  }\n  const unresolved = outcomes.filter((o) => o.status === \"unresolved\");\n  console.log(\n    changed.length === 0\n      ? `Nothing to pin — every \\`Realizes:\\` entry in ${plural(services.length, \"service\")} already names the version it points at.`\n      : `${dryRun ? \"Would pin\" : \"Pinned\"} ${changed.length} entr${changed.length === 1 ? \"y\" : \"ies\"} across ${plural(writes.length, \"document\")}.`,\n  );\n  for (const o of changed) {\n    console.log(`  ${o.status === \"pinned\" ? \"+\" : \"~\"} ${o.service}/${o.file}: '${o.target}' → ${entryTarget(o.entry)}@${o.to}`);\n  }\n  for (const o of unresolved) {\n    console.log(`  ? ${o.service}/${o.file}: '${o.target}' realizes ${entryTarget(o.entry)}, which nothing declares — not pinned`);\n  }\n  if (changed.length > 0 && !dryRun) {\n    console.log(\n      \"\\nA pin says you re-read the promise. Restamping without reading it is the one way to make this a lie with a digest on it.\",\n    );\n  }\n}\n"]}