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

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

@@ -0,0 +1 @@
+{"version":3,"file":"living.js","sourceRoot":"","sources":["../../../src/commands/rebase/living.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EACL,eAAe,EACf,kBAAkB,GAEnB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAErE,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAiB,MAAM,WAAW,CAAC;AA6BvE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAe,EACf,IAAY,EACZ,QAAgB,EAChB,KAAiC;IAEjC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAClE,8EAA8E;IAC9E,wEAAwE;IACxE,MAAM,GAAG,GAAG,MAAM,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAEpC,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,0EAA0E;QAC1E,0EAA0E;QAC1E,8BAA8B;QAC9B,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QAC3D,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAEtC,0EAA0E;QAC1E,oEAAoE;QACpE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,KAAK,IAAI,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YACnE,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBACpG,SAAS;YACX,CAAC;YACD,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;YAC/B,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,wEAAwE;gBACxE,qEAAqE;gBACrE,wEAAwE;gBACxE,uCAAuC;gBACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBACtE,SAAS;YACX,CAAC;YACD,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;gBACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;gBACpE,SAAS;YACX,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,IAAI,OAAO,EAAE,CAAC,CAAC;YAC9E,QAAQ,CAAC,IAAI,CAAC;gBACZ,GAAG,IAAI;gBACP,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU;gBAC5C,IAAI,EAAE,GAAG;gBACT,EAAE,EAAE,OAAO;aACZ,CAAC,CAAC;QACL,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;YAAE,SAAS;QAChC,MAAM,IAAI,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC;QAC/E,IAAI,IAAI,KAAK,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;AACnF,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,WAAW,CAAC,QAAqC;IAC/D,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;AAClF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACzC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;AAChF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAgB,EAChB,IAA4D;IAE5D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAC;IAEjC,MAAM,YAAY,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,MAAM,0BAA0B,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/F,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC5B,4EAA4E;QAC5E,yEAAyE;QACzE,0EAA0E;QAC1E,kDAAkD;QAClD,OAAO,IAAI,CACT,IAAI,EACJ,gBAAgB,EAChB,4GAA4G;YAC1G,4IAA4I,CAC/I,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7F,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO,IAAI,CACT,IAAI,EACJ,gBAAgB,EAChB,eAAe,IAAI,CAAC,OAAO,qBAAqB;YAC9C,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,gBAAgB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAChG,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,IAAI,CAAC;QACH,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC7B,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;gBACtF,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACnC,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI;oBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACjG,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,GAAG,YAAY,oBAAoB,CAAC;YAAE,MAAM,GAAG,CAAC;QACtD,OAAO,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,gDAAgD,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;IAED,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,MAAM,YAAY,CAClC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,sBAAsB,EAAE,MAAM,EAAE,QAAQ,EAAE,EACrF,MAAM,EACN,QAAQ,CACT,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,4BAA4B,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IAED,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,QAAQ,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC7G,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,YAAY,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,CACT,OAAO,CAAC,MAAM,KAAK,CAAC;QAClB,CAAC,CAAC,iDAAiD,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,0CAA0C;QAC/H,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,QAAQ,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,WAAW,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAClJ,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChI,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,MAAM,cAAc,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACjI,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CACT,4HAA4H,CAC7H,CAAC;IACJ,CAAC;AACH,CAAC","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"]}

package/dist/commands/rebase/plan.js

@@ -0,0 +1,245 @@
+/**
+ * What each axis is missing a pin for, computed before anything is written.
+ *
+ * The requirement axis and the contract axis are planned by the same shape and
+ * separately on purpose: a requirement is pinned by a `Based-On:` line inserted
+ * by surgery, and an operation by an `x-loam-based-on` key the YAML writer
+ * emits. Only the first has to preserve the author's sections and prose, which
+ * is why it edits lines rather than reserializing.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { decodeDocument } from "../../core/kernel/document-bytes.js";
+import {} from "../../core/kernel/ids/service.js";
+import {} from "../../core/repo/paths.js";
+import { livingCapabilityPaths } from "../../core/repo/authored/paths.js";
+import { locateServicePaths } from "../../core/repo/service-target.js";
+import { parseRequirements, readRequirementsDocument } from "../../core/document/parse.js";
+import { requirementDigest } from "../../core/document/spec.js";
+import { OpenapiMergeError } from "../../core/openapi/merge/error.js";
+import { pinOpenapiOperations } from "../../core/openapi/merge/pin.js";
+import { planOpenapiBaselines } from "../../core/openapi/baseline/plan.js";
+import { AsyncapiMergeError } from "../../core/asyncapi/merge/error.js";
+import { pinAsyncapiSlots } from "../../core/asyncapi/merge/pin.js";
+import { planAsyncapiBaselines } from "../../core/asyncapi/baseline/plan.js";
+import { applyEdits, pinEdit } from "./edit.js";
+/** Pin every MODIFIED/REMOVED requirement in one delta file against one living document. */
+export async function planAxis(repo, service, axis, specPath) {
+    const livingPath = (await locateServicePaths(repo.docsDir, service, repo.fleet))[axis.key];
+    const planned = await planRequirementPins(specPath, livingPath, axis.file);
+    return { outcomes: planned.pins.map((pin) => ({ service, ...pin })), content: planned.content };
+}
+/**
+ * The same, for one capability delta against its living document.
+ *
+ * NOT OPTIONAL, and not symmetry for its own sake: `delta.baseline-missing` is
+ * a warning that GATES archive, and its message ends "Run `loam rebase <FEAT>`
+ * to pin it". A capability delta graded by that rule while `rebase` skipped the
+ * axis would have loam send an author to a command that does not pin the file
+ * loam just named — a refusal with no exit, which is the one thing a gating
+ * message may never be.
+ *
+ * The living path resolves through `livingCapabilityPaths` for the reason that
+ * function states: the id's nesting is spelled by directories, so an unsplit
+ * join reads an empty living document and every pin comes out `unresolved`
+ * over a promise the fleet already made.
+ */
+export async function planCapabilityAxis(repo, capability, specPath) {
+    const planned = await planRequirementPins(specPath, livingCapabilityPaths(repo.docsDir, capability).spec, "spec.md");
+    return { outcomes: planned.pins.map((pin) => ({ capability, ...pin })), content: planned.content };
+}
+/**
+ * The pin rule itself: every MODIFIED/REMOVED requirement in one delta document,
+ * against one living document. Whose documents they are is the caller's
+ * business — this is the part that must not fork, because a second copy is a
+ * second answer to "was this delta written against what is there now".
+ */
+async function planRequirementPins(specPath, livingPath, file) {
+    // Both sides through the decoding read: the delta because line surgery over a
+    // document loam mis-decoded would write bytes nobody authored, the living
+    // because it is what every digest below is taken over.
+    const raw = await readRequirementsDocument(specPath);
+    const reqs = parseRequirements(raw);
+    const living = existsSync(livingPath)
+        ? parseRequirements(await readRequirementsDocument(livingPath))
+        : [];
+    const pins = [];
+    const edits = [];
+    for (const r of reqs) {
+        if (r.kind !== "MODIFIED" && r.kind !== "REMOVED")
+            continue;
+        // Every requirement parsed from a document carries its heading line
+        // (core/document/parse.ts). One built in memory has no document to write into, and
+        // there is nothing truthful to report about pinning it.
+        const line = r.line;
+        if (line === undefined)
+            continue;
+        const base = { file, kind: r.kind, target: r.name };
+        const selected = selectLiving(living, r);
+        if (selected === undefined) {
+            pins.push({ ...base, status: "unresolved", from: r.basedOn ?? null, to: null });
+            continue;
+        }
+        const digest = requirementDigest(selected);
+        if (r.basedOn === digest) {
+            pins.push({ ...base, status: "unchanged", from: digest, to: digest });
+            continue;
+        }
+        pins.push({
+            ...base,
+            status: r.basedOn === undefined ? "pinned" : "repinned",
+            from: r.basedOn ?? null,
+            to: digest,
+        });
+        edits.push(pinEdit(r, line, digest));
+    }
+    return { pins, content: edits.length === 0 ? null : applyEdits(raw, edits) };
+}
+/**
+ * Pin every operation in one feature contract against the living contract.
+ *
+ * The pin is always `operationDigest` of the LIVING operation, never of the
+ * delta's own. That single rule produces both merge verdicts on its own: an
+ * operation the author only QUOTED is byte-equal to living, so its pin equals
+ * its own content and the merge skips it; one the author EDITED differs from
+ * its pin, so the merge writes it. Nothing here has to guess at intent — the
+ * document already records it, and the pin makes it legible.
+ *
+ * Slot-keyed (path + method), exactly as the merge upserts. An operationId that
+ * moved to another slot is a new slot with nothing living behind it, which is
+ * `unresolved` and correct: there is no living version of an operation at a
+ * path the contract does not serve yet.
+ */
+export async function planOpenapi(repo, service, openapiPath) {
+    const livingPath = (await locateServicePaths(repo.docsDir, service, repo.fleet)).openapi;
+    // Decoded, not `readFile(…, "utf8")`, for the requirement axes' reason: a
+    // contract read with U+FFFD substituted in defines no operation loam can
+    // match, so every pin would come out `unresolved` — "this feature adds them
+    // all" — over a living contract that already serves them. Read outside the
+    // try below, whose job is the merge's own diagnosis and not this one.
+    const living = existsSync(livingPath) ? decodeDocument(await readFile(livingPath), livingPath) : "";
+    const delta = decodeDocument(await readFile(openapiPath), openapiPath);
+    let plan;
+    let baselines;
+    try {
+        plan = pinOpenapiOperations(delta, living, service);
+        // The surface record, planned over the OPERATION pass's output so one run
+        // writes one file once. Order is safe: a surface digest never includes an
+        // operation pin (`restatedSurfaces` skips the methods entirely), and the
+        // root record never enters an operation digest.
+        baselines = planOpenapiBaselines(plan.text ?? delta, living);
+    }
+    catch (err) {
+        // A document loam cannot read is validate's diagnosis to make
+        // (`openapi.invalid`), not this command's to guess at — and stamping into a
+        // broken parse would write a file nobody asked for.
+        if (!(err instanceof OpenapiMergeError))
+            throw err;
+        return { outcomes: [], content: null };
+    }
+    return {
+        outcomes: [
+            ...plan.pins.map((pin) => ({
+                service,
+                file: "openapi.yaml",
+                kind: pin.method.toUpperCase(),
+                target: pin.operationId.length === 0 ? pin.path : `${pin.path} ('${pin.operationId}')`,
+                status: pin.status,
+                from: pin.from,
+                to: pin.to,
+            })),
+            ...baselines.pins.map((pin) => ({
+                service,
+                file: "openapi.yaml",
+                kind: pin.kind === "component" ? "COMPONENT" : "PATH-ITEM",
+                target: pin.target,
+                status: pin.status,
+                from: pin.from,
+                to: pin.to,
+            })),
+        ],
+        content: baselines.text ?? plan.text,
+    };
+}
+/**
+ * Pin every slot AND every component surface in one feature event contract
+ * against the living contract — `planOpenapi`'s mirror on the event axis, in
+ * both of its halves.
+ *
+ * The in-value `x-loam-based-on` reaches every SLOT, because a slot value is
+ * always a mapping (core/asyncapi/digest.ts owns the slot model; inline
+ * channel messages are channel interior and never pinned on their own). It
+ * reaches nothing else: a `components/schemas/<name>` value is a JSON Schema,
+ * where an in-value loam key would be a schema keyword — so the surfaces are
+ * pinned by the same root `x-loam-baselines` record the OpenAPI axis uses, and
+ * this function writes both. (This comment used to say the event pin has no
+ * root record. It did not, and that is why a `components.schemas`-only delta
+ * merged nothing at all.)
+ */
+export async function planAsyncapi(repo, service, asyncapiPath) {
+    const livingPath = (await locateServicePaths(repo.docsDir, service, repo.fleet)).asyncapi;
+    // Decoded, not `readFile(…, "utf8")`, for planOpenapi's reason: a contract
+    // read with U+FFFD substituted in defines no slot loam can match, so every
+    // pin would come out `unresolved` over a living contract that already
+    // carries them.
+    const living = existsSync(livingPath) ? decodeDocument(await readFile(livingPath), livingPath) : "";
+    const delta = decodeDocument(await readFile(asyncapiPath), asyncapiPath);
+    let plan;
+    let baselines;
+    try {
+        plan = pinAsyncapiSlots(delta, living, service);
+        // The surface record, planned over the SLOT pass's output so one run
+        // writes one file once. Order is safe, and load-bearing in both
+        // directions: a surface digest never includes a slot pin (`asyncapiSurfaces`
+        // skips `components.messages` entirely, and no other section is a
+        // surface), and the root record never enters a slot digest.
+        baselines = planAsyncapiBaselines(plan.text ?? delta, living);
+    }
+    catch (err) {
+        // A document loam cannot read is validate's diagnosis to make
+        // (`asyncapi.invalid`), not this command's to guess at — and stamping
+        // into a broken parse would write a file nobody asked for.
+        if (!(err instanceof AsyncapiMergeError))
+            throw err;
+        return { outcomes: [], content: null };
+    }
+    return {
+        outcomes: [
+            ...plan.pins.map((pin) => ({
+                service,
+                file: "asyncapi.yaml",
+                kind: pin.section,
+                target: pin.key,
+                status: pin.status,
+                from: pin.from,
+                to: pin.to,
+            })),
+            ...baselines.pins.map((pin) => ({
+                service,
+                file: "asyncapi.yaml",
+                kind: "COMPONENT",
+                target: pin.target,
+                status: pin.status,
+                from: pin.from,
+                to: pin.to,
+            })),
+        ],
+        content: baselines.text ?? plan.text,
+    };
+}
+/**
+ * The living requirement a delta requirement addresses — the merge's own
+ * resolution order (core/document/apply.ts `applyRequirementDelta`), so a pin is taken
+ * over exactly the requirement archive would rewrite: the stable ID when the
+ * delta carries one, the exact heading otherwise, and the FIRST match either
+ * way (duplicates are refused upstream by `delta.living-duplicate-requirement`).
+ */
+export function selectLiving(living, r) {
+    if (r.id !== undefined)
+        return living.find((candidate) => candidate.id === r.id);
+    return living.find((candidate) => candidate.name === r.name);
+}
+/* ------------------------------------------------------------------ */
+/* Line surgery                                                        */
+/* ------------------------------------------------------------------ */
+//# sourceMappingURL=plan.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../src/commands/rebase/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAwB,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAiB,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAoB,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,iCAAiC,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAA4B,MAAM,qCAAqC,CAAC;AACrG,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAwB,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,OAAO,EAAiB,MAAM,WAAW,CAAC;AAwF/D,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAc,EACd,OAAwB,EACxB,IAAc,EACd,QAAgB;IAEhB,MAAM,UAAU,GAAG,CAAC,MAAM,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3F,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;AAClG,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAc,EACd,UAAkB,EAClB,QAAgB;IAEhB,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,QAAQ,EAAE,qBAAqB,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACrH,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;AACrG,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,mBAAmB,CAChC,QAAgB,EAChB,UAAkB,EAClB,IAAY;IAEZ,8EAA8E;IAC9E,0EAA0E;IAC1E,uDAAuD;IACvD,MAAM,GAAG,GAAG,MAAM,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC;QACnC,CAAC,CAAC,iBAAiB,CAAC,MAAM,wBAAwB,CAAC,UAAU,CAAC,CAAC;QAC/D,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,IAAI,GAAgB,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QAC5D,oEAAoE;QACpE,mFAAmF;QACnF,wDAAwD;QACxD,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QACpB,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS;QACjC,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACpD,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACzC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAChF,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,CAAC,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;YACtE,SAAS;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC;YACR,GAAG,IAAI;YACP,MAAM,EAAE,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU;YACvD,IAAI,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI;YACvB,EAAE,EAAE,MAAM;SACX,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAc,EAAE,OAAwB,EAAE,WAAmB;IAC7F,MAAM,UAAU,GAAG,CAAC,MAAM,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;IACzF,0EAA0E;IAC1E,yEAAyE;IACzE,4EAA4E;IAC5E,2EAA2E;IAC3E,sEAAsE;IACtE,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpG,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC;IACvE,IAAI,IAAoB,CAAC;IACzB,IAAI,SAA8B,CAAC;IACnC,IAAI,CAAC;QACH,IAAI,GAAG,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACpD,0EAA0E;QAC1E,0EAA0E;QAC1E,yEAAyE;QACzE,gDAAgD;QAChD,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,8DAA8D;QAC9D,4EAA4E;QAC5E,oDAAoD;QACpD,IAAI,CAAC,CAAC,GAAG,YAAY,iBAAiB,CAAC;YAAE,MAAM,GAAG,CAAC;QACnD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC;IACD,OAAO;QACL,QAAQ,EAAE;YACR,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBACzB,OAAO;gBACP,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE;gBAC9B,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,WAAW,IAAI;gBACtF,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,EAAE,EAAE,GAAG,CAAC,EAAE;aACX,CAAC,CAAC;YACH,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBAC9B,OAAO;gBACP,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW;gBAC1D,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,EAAE,EAAE,GAAG,CAAC,EAAE;aACX,CAAC,CAAC;SACJ;QACD,OAAO,EAAE,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;KACrC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAc,EACd,OAAwB,EACxB,YAAoB;IAEpB,MAAM,UAAU,GAAG,CAAC,MAAM,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1F,2EAA2E;IAC3E,2EAA2E;IAC3E,sEAAsE;IACtE,gBAAgB;IAChB,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpG,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,CAAC;IACzE,IAAI,IAAqB,CAAC;IAC1B,IAAI,SAA8B,CAAC;IACnC,IAAI,CAAC;QACH,IAAI,GAAG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAChD,qEAAqE;QACrE,gEAAgE;QAChE,6EAA6E;QAC7E,kEAAkE;QAClE,4DAA4D;QAC5D,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,EAAE,MAAM,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,8DAA8D;QAC9D,sEAAsE;QACtE,2DAA2D;QAC3D,IAAI,CAAC,CAAC,GAAG,YAAY,kBAAkB,CAAC;YAAE,MAAM,GAAG,CAAC;QACpD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC;IACD,OAAO;QACL,QAAQ,EAAE;YACR,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBACzB,OAAO;gBACP,IAAI,EAAE,eAAe;gBACrB,IAAI,EAAE,GAAG,CAAC,OAAO;gBACjB,MAAM,EAAE,GAAG,CAAC,GAAG;gBACf,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,EAAE,EAAE,GAAG,CAAC,EAAE;aACX,CAAC,CAAC;YACH,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBAC9B,OAAO;gBACP,IAAI,EAAE,eAAe;gBACrB,IAAI,EAAE,WAAW;gBACjB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,EAAE,EAAE,GAAG,CAAC,EAAE;aACX,CAAC,CAAC;SACJ;QACD,OAAO,EAAE,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;KACrC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB,EAAE,CAAc;IAChE,IAAI,CAAC,CAAC,EAAE,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IACjF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE","sourcesContent":["/**\n * What each axis is missing a pin for, computed before anything is written.\n *\n * The requirement axis and the contract axis are planned by the same shape and\n * separately on purpose: a requirement is pinned by a `Based-On:` line inserted\n * by surgery, and an operation by an `x-loam-based-on` key the YAML writer\n * emits. Only the first has to preserve the author's sections and prose, which\n * is why it edits lines rather than reserializing.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { decodeDocument } from \"../../core/kernel/document-bytes.js\";\nimport { type PathableService } from \"../../core/kernel/ids/service.js\";\nimport { type SpecAxis } from \"../../core/repo/paths.js\";\nimport { livingCapabilityPaths } from \"../../core/repo/authored/paths.js\";\nimport { locateServicePaths } from \"../../core/repo/service-target.js\";\nimport { parseRequirements, readRequirementsDocument } from \"../../core/document/parse.js\";\nimport { requirementDigest, type Requirement } from \"../../core/document/spec.js\";\nimport { OpenapiMergeError } from \"../../core/openapi/merge/error.js\";\nimport { pinOpenapiOperations, type OpenapiPinPlan } from \"../../core/openapi/merge/pin.js\";\nimport { planOpenapiBaselines, type OpenapiBaselinePlan } from \"../../core/openapi/baseline/plan.js\";\nimport { AsyncapiMergeError } from \"../../core/asyncapi/merge/error.js\";\nimport { pinAsyncapiSlots, type AsyncapiPinPlan } from \"../../core/asyncapi/merge/pin.js\";\nimport { planAsyncapiBaselines } from \"../../core/asyncapi/baseline/plan.js\";\nimport { applyEdits, pinEdit, type LineEdit } from \"./edit.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../core/fleet-context.js\";\n\n/**\n * How a planner reaches the living documents: the repo root plus the\n * command's shared read index. One record on purpose — `rebase` calls these\n * planners in a services × axes loop, and each `locateServicePaths` without\n * a context is a FULL fleet walk (readdir + a frontmatter read per service),\n * so a 20-service feature paid ~80 re-enumerations of a fleet that did not\n * change between them. The context makes that one walk per invocation.\n */\nexport interface RepoRead {\n  docsDir: DocsDir;\n  fleet?: FleetContext;\n}\n\nexport type PinStatus =\n  /** It had none and now has one. */\n  | \"pinned\"\n  /** It had a pin for an older living version; it now names the current one. */\n  | \"repinned\"\n  /** It already named the current living version — no write. */\n  | \"unchanged\"\n  /**\n   * It addresses nothing living — a MODIFIED of a requirement another feature\n   * in flight still introduces, or an operation this feature is adding. There\n   * is no version to be based on, so inventing a pin would be inventing a\n   * baseline; `loam validate` already reports the ordering where there is one\n   * (`delta.modified-pending`).\n   */\n  | \"unresolved\"\n  /**\n   * The operation is written as a YAML alias. One shared value backs every use\n   * of an anchor, so stamping \"through\" it would pin every other use too —\n   * the same reason the merge refuses to edit aliases in place. Rare, legal,\n   * and named rather than silently skipped.\n   */\n  | \"unwritable\";\n\n/**\n * What happened to ONE pin, minus whose document it was in.\n *\n * Split from `PinOutcome` when the business corpus arrived: a capability delta\n * is pinned by the identical rule against an identical document, but it names\n * no service, and putting a capability id into a published field called\n * `service` would bend the `--json` contract into a lie. Everything a reader\n * acts on lives here; the two wrappers below add only the identity.\n */\nexport interface PinRecord {\n  /** The axis's filename — \"spec.md\", \"arch.spec.md\", \"openapi.yaml\" or \"asyncapi.yaml\". */\n  file: string;\n  /**\n   * MODIFIED/REMOVED for a requirement; the upper-case HTTP method for an\n   * operation; COMPONENT for a `components/<kind>/<name>`; PATH-ITEM for a\n   * path-item non-method key; the AsyncAPI section name (`channels`,\n   * `operations`, `components.messages`) for an event slot.\n   */\n  kind: string;\n  /** The requirement heading, `/path ('operationId')`, `<kind>/<name>`, `/path '<key>'`, or the asyncapi slot key. */\n  target: string;\n  status: PinStatus;\n  /** The pin as it was, or null when there was none. */\n  from: string | null;\n  /** The pin as it now stands, or null when nothing living could be hashed. */\n  to: string | null;\n}\n\nexport interface PinOutcome extends PinRecord {\n  service: string;\n}\n\n/** The same record on the business corpus, keyed by the promise instead of the service. */\nexport interface CapabilityPinOutcome extends PinRecord {\n  capability: string;\n}\n\nexport interface AxisPlan {\n  outcomes: PinOutcome[];\n  /** The rewritten document, or null when nothing about it changes. */\n  content: string | null;\n}\n\nexport interface CapabilityAxisPlan {\n  outcomes: CapabilityPinOutcome[];\n  content: string | null;\n}\n\n/** Pin every MODIFIED/REMOVED requirement in one delta file against one living document. */\nexport async function planAxis(\n  repo: RepoRead,\n  service: PathableService,\n  axis: SpecAxis,\n  specPath: string,\n): Promise<AxisPlan> {\n  const livingPath = (await locateServicePaths(repo.docsDir, service, repo.fleet))[axis.key];\n  const planned = await planRequirementPins(specPath, livingPath, axis.file);\n  return { outcomes: planned.pins.map((pin) => ({ service, ...pin })), content: planned.content };\n}\n\n/**\n * The same, for one capability delta against its living document.\n *\n * NOT OPTIONAL, and not symmetry for its own sake: `delta.baseline-missing` is\n * a warning that GATES archive, and its message ends \"Run `loam rebase <FEAT>`\n * to pin it\". A capability delta graded by that rule while `rebase` skipped the\n * axis would have loam send an author to a command that does not pin the file\n * loam just named — a refusal with no exit, which is the one thing a gating\n * message may never be.\n *\n * The living path resolves through `livingCapabilityPaths` for the reason that\n * function states: the id's nesting is spelled by directories, so an unsplit\n * join reads an empty living document and every pin comes out `unresolved`\n * over a promise the fleet already made.\n */\nexport async function planCapabilityAxis(\n  repo: RepoRead,\n  capability: string,\n  specPath: string,\n): Promise<CapabilityAxisPlan> {\n  const planned = await planRequirementPins(specPath, livingCapabilityPaths(repo.docsDir, capability).spec, \"spec.md\");\n  return { outcomes: planned.pins.map((pin) => ({ capability, ...pin })), content: planned.content };\n}\n\n/**\n * The pin rule itself: every MODIFIED/REMOVED requirement in one delta document,\n * against one living document. Whose documents they are is the caller's\n * business — this is the part that must not fork, because a second copy is a\n * second answer to \"was this delta written against what is there now\".\n */\nasync function planRequirementPins(\n  specPath: string,\n  livingPath: string,\n  file: string,\n): Promise<{ pins: PinRecord[]; content: string | null }> {\n  // Both sides through the decoding read: the delta because line surgery over a\n  // document loam mis-decoded would write bytes nobody authored, the living\n  // because it is what every digest below is taken over.\n  const raw = await readRequirementsDocument(specPath);\n  const reqs = parseRequirements(raw);\n  const living = existsSync(livingPath)\n    ? parseRequirements(await readRequirementsDocument(livingPath))\n    : [];\n\n  const pins: PinRecord[] = [];\n  const edits: LineEdit[] = [];\n  for (const r of reqs) {\n    if (r.kind !== \"MODIFIED\" && r.kind !== \"REMOVED\") continue;\n    // Every requirement parsed from a document carries its heading line\n    // (core/document/parse.ts). One built in memory has no document to write into, and\n    // there is nothing truthful to report about pinning it.\n    const line = r.line;\n    if (line === undefined) continue;\n    const base = { file, kind: r.kind, target: r.name };\n    const selected = selectLiving(living, r);\n    if (selected === undefined) {\n      pins.push({ ...base, status: \"unresolved\", from: r.basedOn ?? null, to: null });\n      continue;\n    }\n    const digest = requirementDigest(selected);\n    if (r.basedOn === digest) {\n      pins.push({ ...base, status: \"unchanged\", from: digest, to: digest });\n      continue;\n    }\n    pins.push({\n      ...base,\n      status: r.basedOn === undefined ? \"pinned\" : \"repinned\",\n      from: r.basedOn ?? null,\n      to: digest,\n    });\n    edits.push(pinEdit(r, line, digest));\n  }\n\n  return { pins, content: edits.length === 0 ? null : applyEdits(raw, edits) };\n}\n\n/**\n * Pin every operation in one feature contract against the living contract.\n *\n * The pin is always `operationDigest` of the LIVING operation, never of the\n * delta's own. That single rule produces both merge verdicts on its own: an\n * operation the author only QUOTED is byte-equal to living, so its pin equals\n * its own content and the merge skips it; one the author EDITED differs from\n * its pin, so the merge writes it. Nothing here has to guess at intent — the\n * document already records it, and the pin makes it legible.\n *\n * Slot-keyed (path + method), exactly as the merge upserts. An operationId that\n * moved to another slot is a new slot with nothing living behind it, which is\n * `unresolved` and correct: there is no living version of an operation at a\n * path the contract does not serve yet.\n */\nexport async function planOpenapi(repo: RepoRead, service: PathableService, openapiPath: string): Promise<AxisPlan> {\n  const livingPath = (await locateServicePaths(repo.docsDir, service, repo.fleet)).openapi;\n  // Decoded, not `readFile(…, \"utf8\")`, for the requirement axes' reason: a\n  // contract read with U+FFFD substituted in defines no operation loam can\n  // match, so every pin would come out `unresolved` — \"this feature adds them\n  // all\" — over a living contract that already serves them. Read outside the\n  // try below, whose job is the merge's own diagnosis and not this one.\n  const living = existsSync(livingPath) ? decodeDocument(await readFile(livingPath), livingPath) : \"\";\n  const delta = decodeDocument(await readFile(openapiPath), openapiPath);\n  let plan: OpenapiPinPlan;\n  let baselines: OpenapiBaselinePlan;\n  try {\n    plan = pinOpenapiOperations(delta, living, service);\n    // The surface record, planned over the OPERATION pass's output so one run\n    // writes one file once. Order is safe: a surface digest never includes an\n    // operation pin (`restatedSurfaces` skips the methods entirely), and the\n    // root record never enters an operation digest.\n    baselines = planOpenapiBaselines(plan.text ?? delta, living);\n  } catch (err) {\n    // A document loam cannot read is validate's diagnosis to make\n    // (`openapi.invalid`), not this command's to guess at — and stamping into a\n    // broken parse would write a file nobody asked for.\n    if (!(err instanceof OpenapiMergeError)) throw err;\n    return { outcomes: [], content: null };\n  }\n  return {\n    outcomes: [\n      ...plan.pins.map((pin) => ({\n        service,\n        file: \"openapi.yaml\",\n        kind: pin.method.toUpperCase(),\n        target: pin.operationId.length === 0 ? pin.path : `${pin.path} ('${pin.operationId}')`,\n        status: pin.status,\n        from: pin.from,\n        to: pin.to,\n      })),\n      ...baselines.pins.map((pin) => ({\n        service,\n        file: \"openapi.yaml\",\n        kind: pin.kind === \"component\" ? \"COMPONENT\" : \"PATH-ITEM\",\n        target: pin.target,\n        status: pin.status,\n        from: pin.from,\n        to: pin.to,\n      })),\n    ],\n    content: baselines.text ?? plan.text,\n  };\n}\n\n/**\n * Pin every slot AND every component surface in one feature event contract\n * against the living contract — `planOpenapi`'s mirror on the event axis, in\n * both of its halves.\n *\n * The in-value `x-loam-based-on` reaches every SLOT, because a slot value is\n * always a mapping (core/asyncapi/digest.ts owns the slot model; inline\n * channel messages are channel interior and never pinned on their own). It\n * reaches nothing else: a `components/schemas/<name>` value is a JSON Schema,\n * where an in-value loam key would be a schema keyword — so the surfaces are\n * pinned by the same root `x-loam-baselines` record the OpenAPI axis uses, and\n * this function writes both. (This comment used to say the event pin has no\n * root record. It did not, and that is why a `components.schemas`-only delta\n * merged nothing at all.)\n */\nexport async function planAsyncapi(\n  repo: RepoRead,\n  service: PathableService,\n  asyncapiPath: string,\n): Promise<AxisPlan> {\n  const livingPath = (await locateServicePaths(repo.docsDir, service, repo.fleet)).asyncapi;\n  // Decoded, not `readFile(…, \"utf8\")`, for planOpenapi's reason: a contract\n  // read with U+FFFD substituted in defines no slot loam can match, so every\n  // pin would come out `unresolved` over a living contract that already\n  // carries them.\n  const living = existsSync(livingPath) ? decodeDocument(await readFile(livingPath), livingPath) : \"\";\n  const delta = decodeDocument(await readFile(asyncapiPath), asyncapiPath);\n  let plan: AsyncapiPinPlan;\n  let baselines: OpenapiBaselinePlan;\n  try {\n    plan = pinAsyncapiSlots(delta, living, service);\n    // The surface record, planned over the SLOT pass's output so one run\n    // writes one file once. Order is safe, and load-bearing in both\n    // directions: a surface digest never includes a slot pin (`asyncapiSurfaces`\n    // skips `components.messages` entirely, and no other section is a\n    // surface), and the root record never enters a slot digest.\n    baselines = planAsyncapiBaselines(plan.text ?? delta, living);\n  } catch (err) {\n    // A document loam cannot read is validate's diagnosis to make\n    // (`asyncapi.invalid`), not this command's to guess at — and stamping\n    // into a broken parse would write a file nobody asked for.\n    if (!(err instanceof AsyncapiMergeError)) throw err;\n    return { outcomes: [], content: null };\n  }\n  return {\n    outcomes: [\n      ...plan.pins.map((pin) => ({\n        service,\n        file: \"asyncapi.yaml\",\n        kind: pin.section,\n        target: pin.key,\n        status: pin.status,\n        from: pin.from,\n        to: pin.to,\n      })),\n      ...baselines.pins.map((pin) => ({\n        service,\n        file: \"asyncapi.yaml\",\n        kind: \"COMPONENT\",\n        target: pin.target,\n        status: pin.status,\n        from: pin.from,\n        to: pin.to,\n      })),\n    ],\n    content: baselines.text ?? plan.text,\n  };\n}\n\n/**\n * The living requirement a delta requirement addresses — the merge's own\n * resolution order (core/document/apply.ts `applyRequirementDelta`), so a pin is taken\n * over exactly the requirement archive would rewrite: the stable ID when the\n * delta carries one, the exact heading otherwise, and the FIRST match either\n * way (duplicates are refused upstream by `delta.living-duplicate-requirement`).\n */\nexport function selectLiving(living: Requirement[], r: Requirement): Requirement | undefined {\n  if (r.id !== undefined) return living.find((candidate) => candidate.id === r.id);\n  return living.find((candidate) => candidate.name === r.name);\n}\n\n/* ------------------------------------------------------------------ */\n/* Line surgery                                                        */\n/* ------------------------------------------------------------------ */\n"]}

package/dist/commands/rebase/rebase.js

@@ -0,0 +1,300 @@
+import { existsSync } from "node:fs";
+import { NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
+import { InvalidIdError, assertServiceId } from "../../core/kernel/ids/service.js";
+import { configOrRefuse, emitJson, fail, repoPath } from "../../core/envelope/json.js";
+import { compareIds } from "../../core/repo/entries.js";
+import { featureSpecPaths, SPEC_AXES } from "../../core/repo/paths.js";
+import { missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
+import { stageWrites } from "../../core/staging/commit.js";
+import {} from "../../core/staging/interrupted.js";
+import { openCommitWindow } from "../../core/staging/recovery/recover.js";
+import { commitStaged } from "../../core/staging/txn/transaction.js";
+import {} from "../../core/staging/writes.js";
+import { plural, sayRecovered } from "../policy/format.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { planAsyncapi, planAxis, planCapabilityAxis, planOpenapi, } from "./plan.js";
+import { issueFinding } from "../../core/vocabulary/issue.js";
+import { retiredLookup } from "../../core/coherence/retired/archived.js";
+import { serviceRevivals } from "../../core/coherence/retired/revival/revived.js";
+import { rebaseLivingLocked } from "./living.js";
+/** What happened to one pin. */
+export function registerRebase(program) {
+    program
+        .command("rebase")
+        // Optional ONLY because `--living` names no feature: that mode pins the
+        // living corpus itself. Every existing invocation still parses, which is
+        // what makes the relaxation additive rather than a contract change.
+        .argument("[featureId]", "feature id, e.g. FEAT-101 — omitted with --living")
+        .description("Pin a feature's MODIFIED/REMOVED requirements to the living text they are written against")
+        .option("--service <id>", "restrict to one service (default: every service the feature touches)")
+        .option("--living", "pin the LIVING corpus's `Realizes:` entries to the capability requirements they name, instead of a feature's deltas")
+        .option("--dry-run", "print what would be pinned and write nothing — beyond first finishing a predecessor's interrupted commit, exactly as a real run would")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (featureId, opts) => {
+        const json = opts.json === true;
+        const config = await configOrRefuse(json);
+        if (config === null)
+            return;
+        // The id grammar on the RAW argument, before it reaches a path join —
+        // one grammar for the whole tool (core/kernel/ids/service.ts).
+        if (opts.service !== undefined) {
+            try {
+                assertServiceId(opts.service, "--service");
+            }
+            catch (err) {
+                if (!(err instanceof InvalidIdError))
+                    throw err;
+                return fail(json, "invalid-option", err.message);
+            }
+        }
+        // The living specs must not move between the read that computes a pin and
+        // the write that records it: a digest taken over a document an archive
+        // replaced a millisecond later is precisely the false "I read this" the
+        // pin exists to make impossible. One writer per docs repo, refusing
+        // rather than queueing, exactly as archive takes it.
+        //
+        // A journal in the repo means the LAST write never finished — reading
+        // living documents to compute pins over a half-commit would digest
+        // bytes no run ever produced. Recover (or refuse) first, under the
+        // same lock the commit will hold.
+        const opened = await openCommitWindow(config.docsDir, 0);
+        if (!opened.ok)
+            return fail(json, opened.code, opened.message);
+        try {
+            if (opts.living === true) {
+                await rebaseLivingLocked(config.docsDir, opts);
+                return;
+            }
+            if (featureId === undefined) {
+                // The argument is optional only for the mode that names no feature.
+                // Refusing here rather than making the whole command feature-less
+                // keeps one rule: every pin says which documents it read.
+                return fail(json, "invalid-option", "loam rebase needs a feature id — e.g. `loam rebase FEAT-101`. To pin the living corpus's `Realizes:` entries instead, run `loam rebase --living`.");
+            }
+            await rebaseLocked(config.docsDir, featureId, { ...opts, recovered: opened.recovered });
+        }
+        finally {
+            await opened.release();
+        }
+    });
+}
+async function rebaseLocked(docsDir, featureId, opts) {
+    const json = opts.json === true;
+    const dryRun = opts.dryRun === true;
+    const feature = await resolveFeature(docsDir, featureId, "exclude");
+    if (!feature) {
+        return fail(json, "unknown-target", await missingFeatureMessage(docsDir, featureId));
+    }
+    const { id } = feature;
+    // The enumeration's own id is what travels on when --service names one
+    // (`entry.id` rather than the argument — repo/service-target.ts's rule):
+    // equal as strings, and only one of them was produced by a readdir.
+    const chosen = opts.service === undefined ? undefined : feature.services.find((s) => s === opts.service);
+    if (opts.service !== undefined && chosen === undefined) {
+        // The refusal names the choices, the way `loam delta`'s does: a typo must
+        // never be indistinguishable from a feature with nothing to pin.
+        return fail(json, "unknown-target", `${id} carries no requirement delta for '${opts.service}'` +
+            (feature.services.length === 0
+                ? " — it touches no service at all."
+                : ` — it touches: ${[...feature.services].sort(compareIds).join(", ")}.`));
+    }
+    const services = (chosen === undefined ? [...feature.services] : [chosen]).sort(compareIds);
+    // One read index for the whole loop below: every planner resolves its
+    // living document through `locateServicePaths`, and without a shared
+    // context each of those calls is a fresh fleet walk — services × axes of
+    // them per run, on a tree that cannot change under the lock this holds.
+    const repo = { docsDir, fleet: new FleetContext() };
+    const outcomes = [];
+    const capabilityOutcomes = [];
+    const writes = [];
+    const revived = [];
+    // The business corpus this feature changes. Skipped entirely under `--service`:
+    // that flag means "restrict to one service", and a capability names none — so
+    // pinning capability deltas under it would write files the caller narrowed the
+    // command to exclude. One `existsSync` when the feature carries no capability
+    // delta, which is every feature in a fleet that has not adopted the axis.
+    const capabilities = chosen === undefined ? (await repo.fleet.featureCapabilityDeltas(feature.dir)).docs : [];
+    try {
+        for (const service of services) {
+            for (const axis of SPEC_AXES) {
+                const specPath = featureSpecPaths(feature.dir, service)[axis.key];
+                if (!existsSync(specPath))
+                    continue;
+                const planned = await planAxis(repo, service, axis, specPath);
+                outcomes.push(...planned.outcomes);
+                if (planned.content !== null)
+                    writes.push({ path: specPath, content: planned.content });
+            }
+            // The contract axis. It needs the pin more than the requirement axes do:
+            // a requirement delta spells only the requirements it changes, while an
+            // openapi delta is a COMPLETE document and spells the whole contract.
+            const openapiPath = featureSpecPaths(feature.dir, service).openapi;
+            if (existsSync(openapiPath)) {
+                const planned = await planOpenapi(repo, service, openapiPath);
+                outcomes.push(...planned.outcomes);
+                if (planned.content !== null)
+                    writes.push({ path: openapiPath, content: planned.content });
+            }
+            // The event axis, for the openapi reason: a feature's asyncapi.yaml is
+            // a complete document too, so its quotes need pins or the merge cannot
+            // tell them from edits.
+            const asyncapiPath = featureSpecPaths(feature.dir, service).asyncapi;
+            if (existsSync(asyncapiPath)) {
+                const planned = await planAsyncapi(repo, service, asyncapiPath);
+                outcomes.push(...planned.outcomes);
+                if (planned.content !== null)
+                    writes.push({ path: asyncapiPath, content: planned.content });
+            }
+        }
+        // The business axis, after the services and in the same transaction: a
+        // feature that changes a promise and the services keeping it is ONE act,
+        // and half of it pinned is the state the journal exists to prevent.
+        for (const doc of capabilities) {
+            const planned = await planCapabilityAxis(repo, doc.id, doc.spec);
+            capabilityOutcomes.push(...planned.outcomes);
+            if (planned.content !== null)
+                writes.push({ path: doc.spec, content: planned.content });
+        }
+        // An operation or event slot the living docs do not hold reads `unresolved`
+        // above — "this feature is adding it". For one an ARCHIVED feature retired,
+        // that is the false sentence that put retired operations back: unpinned, the
+        // merge upserts it as an addition. Rebase pins nothing for it, so what it
+        // owes is the same finding the gate raises, said here before the archive
+        // refuses it, and the decision left to the human. Asked of the documents
+        // as this run leaves them (`planned`): a repin over whatever lives at an
+        // address now turns a quote the merge skipped into an edit it writes, and
+        // a revival that edit makes is this run's to report — the next validate
+        // reports it, and a dry run must say what the real one would leave.
+        const retired = retiredLookup(docsDir, repo.fleet);
+        const planned = new Map(writes.flatMap((w) => (typeof w.content === "string" ? [[w.path, w.content]] : [])));
+        for (const service of services) {
+            revived.push(...(await serviceRevivals({ docsDir, featureDir: feature.dir, service, retired, context: repo.fleet, planned })));
+        }
+    }
+    catch (err) {
+        if (!(err instanceof NotUtf8DocumentError))
+            throw err;
+        // A pin is a claim about text somebody read. Over a document loam could not
+        // decode it would be a digest of mojibake with loam's name on it — the
+        // precise false claim this command exists to prevent — and the next archive
+        // would land a stale delta over living text on the strength of it. So it
+        // refuses by name and writes nothing, exactly as `loam archive` refuses a
+        // merge it could not read, under archive's code. The refusal is here, in
+        // the PLAN, so it lands before stageWrites: no file is touched, and a
+        // feature spanning four services does not get two of them pinned.
+        return fail(json, "merge-failed", `rebase ${id} failed — nothing was pinned: ${err.message}`);
+    }
+    if (!dryRun && writes.length > 0) {
+        // Staged and committed through the journaled transaction: a feature
+        // spanning four services is one act, and neither a full disk between its
+        // second and third file NOR a kill between two renames may leave two of
+        // them pinned to a reading the other two never saw — the journal makes
+        // the second case recoverable where rollback alone could not see it.
+        const staged = await stageWrites(writes);
+        const committed = await commitStaged({ root: docsDir, command: "rebase", rerun: `loam rebase ${id}`, target: id }, staged, "pinned");
+        if (!committed.ok) {
+            return fail(json, committed.code, committed.code === "merge-failed" ? `rebase ${id} failed — nothing was pinned: ${committed.message}` : committed.message);
+        }
+    }
+    // One line per pin, whichever corpus it came from: what to call the document,
+    // and the record itself. The two lists are reported separately in `--json`
+    // (the published `pins[]`/`services[]` keys keep meaning exactly what they
+    // meant) and together here, because a human rebasing one feature wants one
+    // list in one order.
+    const lines = [
+        ...outcomes.map((o) => ({ where: `${o.service}/${o.file}`, pin: o })),
+        ...capabilityOutcomes.map((o) => ({ where: `capabilities/${o.capability}/${o.file}`, pin: o })),
+    ];
+    const changed = lines.filter((l) => l.pin.status === "pinned" || l.pin.status === "repinned");
+    const unresolved = lines.filter((l) => l.pin.status === "unresolved");
+    if (json) {
+        emitJson({
+            command: "rebase",
+            feature: id,
+            services,
+            dryRun,
+            pins: outcomes,
+            // Additive, and separate from `pins[]` on purpose: `PinOutcome.service`
+            // is a published field, and a capability id written into it would say
+            // something false to every consumer that already reads it.
+            capabilities: capabilities.map((c) => c.id),
+            capabilityPins: capabilityOutcomes,
+            // Additive: the `openapi.op-revived` / `asyncapi.slot-revived` findings
+            // for what this feature spells that an archived feature retired. Their
+            // `pins[]` rows still say `unresolved` — true, and published — and this
+            // key is what says those rows are not additions.
+            revived: revived.map(issueFinding),
+            written: dryRun ? [] : writes.map((w) => repoPath(docsDir, w.path)),
+            ...(opts.recovered === null ? {} : { recovered: opts.recovered }),
+        });
+        return;
+    }
+    if (lines.length === 0) {
+        console.log(`${id}: nothing to pin — a baseline only means something for a requirement, an operation, a path-level key, a component or an event slot that already exists in the living docs.`);
+        sayRevived(revived);
+        return;
+    }
+    if (opts.recovered !== null)
+        console.log(`${sayRecovered(opts.recovered)}\n`);
+    console.log(`${id}${dryRun ? " (dry run)" : ""}\n`);
+    for (const { where, pin: o } of lines) {
+        const what = `${where}  ${o.kind} ${o.target}`;
+        if (o.status === "unresolved") {
+            console.log(`  · ${what} — not in the living docs yet, nothing to pin`);
+        }
+        else if (o.status === "unwritable") {
+            console.log(`  ! ${what} — a YAML alias (or a key loam cannot address by name); loam will not stamp through it`);
+        }
+        else if (o.status === "unchanged") {
+            console.log(`  = ${what} — already ${o.to}`);
+        }
+        else if (o.status === "pinned") {
+            console.log(`  + ${what} — pinned ${o.to}`);
+        }
+        else {
+            console.log(`  ~ ${what} — ${o.from} → ${o.to}`);
+        }
+    }
+    if (changed.length === 0) {
+        console.log(`\nNothing to write: every pin already names the living version.`);
+    }
+    else if (dryRun) {
+        console.log(`\n${plural(changed.length, "pin")} would be written. Nothing was written.`);
+    }
+    else {
+        console.log(`\n${plural(changed.length, "pin")} written across ${plural(writes.length, "file")}.`);
+        // The one sentence that keeps this command honest. A pin is a claim about
+        // what its author read, and a `repinned` line means the living text moved
+        // under a delta that still says what it said before — restamping does not
+        // fold in the change it just stopped reporting.
+        const repinned = changed.filter((l) => l.pin.status === "repinned");
+        if (repinned.length > 0) {
+            console.log(`\n⚠ ${plural(repinned.length, "pin")} moved since this delta was written. A pin records what you read — ` +
+                `re-read those living requirements and operations and fold in what you still mean, or the next archive lands your version over theirs with loam's blessing.`);
+        }
+    }
+    if (unresolved.length > 0) {
+        console.log(`\n${plural(unresolved.length, "item")} could not be pinned because the living docs do not have them yet — ` +
+            `for a requirement, \`loam dependencies ${id}\` says which feature introduces it first; for an operation, this feature is adding it` +
+            (revived.length === 0 ? "." : ", unless an archived feature retired it or moved it away — those are listed below, and they are not new."));
+    }
+    sayRevived(revived);
+}
+/**
+ * The revival findings, in the gate's own words. Printed rather than acted on:
+ * deleting a quote and re-adding a retired operation on purpose are both
+ * legitimate, and which one this is is the author's call. The sentence once
+ * said "nothing was pinned" for them — true of a retired entry, which has no
+ * living version, and false of a quote this run repinned over whatever lives
+ * at its address now, the very pin that made it a revival.
+ */
+function sayRevived(revived) {
+    if (revived.length === 0)
+        return;
+    const one = revived.length === 1;
+    console.log(`\n⚠ ${plural(revived.length, "item")} this feature spells ${one ? "was" : "were"} RETIRED by an archived feature, or moved to another address by one — ` +
+        `${one ? "it is" : "they are"} not new, pinned or not, and \`loam archive\` refuses ${one ? "it" : "them"} until you decide:`);
+    for (const issue of revived)
+        console.log(`  ⚠ ${issue.message}`);
+}
+//# sourceMappingURL=rebase.js.map