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

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, service);
+    }
+    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, service);
+    }
+    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,EAA6B,MAAM,sCAAsC,CAAC;AACxG,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,EAAE,OAAO,CAAC,CAAC;IACxE,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,SAA+B,CAAC;IACpC,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,EAAE,OAAO,CAAC,CAAC;IACzE,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, type AsyncapiBaselinePlan } 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, service);\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: AsyncapiBaselinePlan;\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, service);\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,275 @@
+import { existsSync } from "node:fs";
+import { loadConfig } from "../../core/envelope/config.js";
+import { NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
+import { InvalidIdError, assertServiceId } from "../../core/kernel/ids/service.js";
+import { emitJson, fail, repoPath, reportNoConfig } 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 { InterruptedCommitError } from "../../core/staging/interrupted.js";
+import { acquireDocsLock, DocsBusyError } from "../../core/staging/lock.js";
+import { recoverInterruptedCommit } 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 { 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 loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            return;
+        }
+        const config = loaded.config;
+        // 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.
+        let release;
+        try {
+            release = await acquireDocsLock(config.docsDir);
+        }
+        catch (err) {
+            if (!(err instanceof DocsBusyError))
+                throw err;
+            return fail(json, "docs-busy", err.message);
+        }
+        try {
+            // 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.
+            let recovered;
+            try {
+                recovered = await recoverInterruptedCommit(config.docsDir);
+            }
+            catch (err) {
+                if (!(err instanceof InterruptedCommitError))
+                    throw err;
+                return fail(json, "commit-interrupted", err.message);
+            }
+            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 });
+        }
+        finally {
+            await 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 = [];
+    // 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 });
+        }
+    }
+    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,
+            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.`);
+        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.`);
+    }
+}
+//# sourceMappingURL=rebase.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rebase.js","sourceRoot":"","sources":["../../../src/commands/rebase/rebase.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport { InvalidIdError, assertServiceId } from \"../../core/kernel/ids/service.js\";\nimport { emitJson, fail, repoPath, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { compareIds } from \"../../core/repo/entries.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../../core/repo/paths.js\";\nimport { missingFeatureMessage, resolveFeature } from \"../../core/repo/repo.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLock, DocsBusyError } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { plural, sayRecovered } from \"../policy/format.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport {\n  planAsyncapi,\n  planAxis,\n  planCapabilityAxis,\n  planOpenapi,\n  type CapabilityPinOutcome,\n  type PinOutcome,\n} from \"./plan.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { rebaseLivingLocked } from \"./living.js\";\n\n/**\n * `loam rebase` — pin a feature's MODIFIED/REMOVED requirements to the living\n * text they are written against.\n *\n * The counterpart to `loam vouch`: vouch stamps a digest of the CODE a living\n * spec was written from, this stamps a digest of the LIVING REQUIREMENT a delta\n * was written from. Both exist so a later `loam validate` can tell \"still true\"\n * from \"something moved underneath\", and both are worth exactly what they claim\n * — so this command computes every pin from what is on disk right now and never\n * invents one for a requirement that addresses nothing living.\n *\n * It is the fix `delta.baseline-stale` sends people to, which is why the\n * rewrite is line SURGERY rather than a reserialize: a delta document is\n * authored prose — section headings, comments, the order the author chose — and\n * `serializeRequirements` would flatten all of it into a bare requirement run.\n * One line changes per requirement; every other byte is copied.\n *\n * Restamping is the LAST step of resolving a collision, never the resolution\n * itself: a pin says \"I read this version\", so running it without re-reading\n * makes it a lie with a digest on it. The output says so on the way out.\n */\n\ninterface RebaseOptions {\n  service?: string;\n  json?: boolean;\n  dryRun?: boolean;\n  living?: boolean;\n}\n\n/** What happened to one pin. */\n\nexport function registerRebase(program: Command): void {\n  program\n    .command(\"rebase\")\n    // Optional ONLY because `--living` names no feature: that mode pins the\n    // living corpus itself. Every existing invocation still parses, which is\n    // what makes the relaxation additive rather than a contract change.\n    .argument(\"[featureId]\", \"feature id, e.g. FEAT-101 — omitted with --living\")\n    .description(\"Pin a feature's MODIFIED/REMOVED requirements to the living text they are written against\")\n    .option(\"--service <id>\", \"restrict to one service (default: every service the feature touches)\")\n    .option(\n      \"--living\",\n      \"pin the LIVING corpus's `Realizes:` entries to the capability requirements they name, instead of a feature's deltas\",\n    )\n    .option(\n      \"--dry-run\",\n      \"print what would be pinned and write nothing — beyond first finishing a predecessor's interrupted commit, exactly as a real run would\",\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureId: string | undefined, opts: RebaseOptions) => {\n      const json = opts.json === true;\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n\n      // The id grammar on the RAW argument, before it reaches a path join —\n      // one grammar for the whole tool (core/kernel/ids/service.ts).\n      if (opts.service !== undefined) {\n        try {\n          assertServiceId(opts.service, \"--service\");\n        } catch (err) {\n          if (!(err instanceof InvalidIdError)) throw err;\n          return fail(json, \"invalid-option\", err.message);\n        }\n      }\n\n      // The living specs must not move between the read that computes a pin and\n      // the write that records it: a digest taken over a document an archive\n      // replaced a millisecond later is precisely the false \"I read this\" the\n      // pin exists to make impossible. One writer per docs repo, refusing\n      // rather than queueing, exactly as archive takes it.\n      let release: () => Promise<void>;\n      try {\n        release = await acquireDocsLock(config.docsDir);\n      } catch (err) {\n        if (!(err instanceof DocsBusyError)) throw err;\n        return fail(json, \"docs-busy\", err.message);\n      }\n      try {\n        // A journal in the repo means the LAST write never finished — reading\n        // living documents to compute pins over a half-commit would digest\n        // bytes no run ever produced. Recover (or refuse) first, under the\n        // same lock the commit will hold.\n        let recovered: CommitRecovery | null;\n        try {\n          recovered = await recoverInterruptedCommit(config.docsDir);\n        } catch (err) {\n          if (!(err instanceof InterruptedCommitError)) throw err;\n          return fail(json, \"commit-interrupted\", err.message);\n        }\n        if (opts.living === true) {\n          await rebaseLivingLocked(config.docsDir, opts);\n          return;\n        }\n        if (featureId === undefined) {\n          // The argument is optional only for the mode that names no feature.\n          // Refusing here rather than making the whole command feature-less\n          // keeps one rule: every pin says which documents it read.\n          return fail(\n            json,\n            \"invalid-option\",\n            \"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`.\",\n          );\n        }\n        await rebaseLocked(config.docsDir, featureId, { ...opts, recovered });\n      } finally {\n        await release();\n      }\n    });\n}\n\nasync function rebaseLocked(\n  docsDir: DocsDir,\n  featureId: string,\n  opts: RebaseOptions & { recovered: CommitRecovery | null },\n): Promise<void> {\n  const json = opts.json === true;\n  const dryRun = opts.dryRun === true;\n\n  const feature = await resolveFeature(docsDir, featureId, \"exclude\");\n  if (!feature) {\n    return fail(json, \"unknown-target\", await missingFeatureMessage(docsDir, featureId));\n  }\n  const { id } = feature;\n\n  // The enumeration's own id is what travels on when --service names one\n  // (`entry.id` rather than the argument — repo/service-target.ts's rule):\n  // equal as strings, and only one of them was produced by a readdir.\n  const chosen = opts.service === undefined ? undefined : feature.services.find((s) => s === opts.service);\n  if (opts.service !== undefined && chosen === undefined) {\n    // The refusal names the choices, the way `loam delta`'s does: a typo must\n    // never be indistinguishable from a feature with nothing to pin.\n    return fail(\n      json,\n      \"unknown-target\",\n      `${id} carries no requirement delta for '${opts.service}'` +\n        (feature.services.length === 0\n          ? \" — it touches no service at all.\"\n          : ` — it touches: ${[...feature.services].sort(compareIds).join(\", \")}.`),\n    );\n  }\n  const services = (chosen === undefined ? [...feature.services] : [chosen]).sort(compareIds);\n\n  // One read index for the whole loop below: every planner resolves its\n  // living document through `locateServicePaths`, and without a shared\n  // context each of those calls is a fresh fleet walk — services × axes of\n  // them per run, on a tree that cannot change under the lock this holds.\n  const repo = { docsDir, fleet: new FleetContext() };\n  const outcomes: PinOutcome[] = [];\n  const capabilityOutcomes: CapabilityPinOutcome[] = [];\n  const writes: PlannedWrite[] = [];\n  // The business corpus this feature changes. Skipped entirely under `--service`:\n  // that flag means \"restrict to one service\", and a capability names none — so\n  // pinning capability deltas under it would write files the caller narrowed the\n  // command to exclude. One `existsSync` when the feature carries no capability\n  // delta, which is every feature in a fleet that has not adopted the axis.\n  const capabilities =\n    chosen === undefined ? (await repo.fleet.featureCapabilityDeltas(feature.dir)).docs : [];\n  try {\n    for (const service of services) {\n      for (const axis of SPEC_AXES) {\n        const specPath = featureSpecPaths(feature.dir, service)[axis.key];\n        if (!existsSync(specPath)) continue;\n        const planned = await planAxis(repo, service, axis, specPath);\n        outcomes.push(...planned.outcomes);\n        if (planned.content !== null) writes.push({ path: specPath, content: planned.content });\n      }\n      // The contract axis. It needs the pin more than the requirement axes do:\n      // a requirement delta spells only the requirements it changes, while an\n      // openapi delta is a COMPLETE document and spells the whole contract.\n      const openapiPath = featureSpecPaths(feature.dir, service).openapi;\n      if (existsSync(openapiPath)) {\n        const planned = await planOpenapi(repo, service, openapiPath);\n        outcomes.push(...planned.outcomes);\n        if (planned.content !== null) writes.push({ path: openapiPath, content: planned.content });\n      }\n      // The event axis, for the openapi reason: a feature's asyncapi.yaml is\n      // a complete document too, so its quotes need pins or the merge cannot\n      // tell them from edits.\n      const asyncapiPath = featureSpecPaths(feature.dir, service).asyncapi;\n      if (existsSync(asyncapiPath)) {\n        const planned = await planAsyncapi(repo, service, asyncapiPath);\n        outcomes.push(...planned.outcomes);\n        if (planned.content !== null) writes.push({ path: asyncapiPath, content: planned.content });\n      }\n    }\n    // The business axis, after the services and in the same transaction: a\n    // feature that changes a promise and the services keeping it is ONE act,\n    // and half of it pinned is the state the journal exists to prevent.\n    for (const doc of capabilities) {\n      const planned = await planCapabilityAxis(repo, doc.id, doc.spec);\n      capabilityOutcomes.push(...planned.outcomes);\n      if (planned.content !== null) writes.push({ path: doc.spec, content: planned.content });\n    }\n  } catch (err) {\n    if (!(err instanceof NotUtf8DocumentError)) throw err;\n    // A pin is a claim about text somebody read. Over a document loam could not\n    // decode it would be a digest of mojibake with loam's name on it — the\n    // precise false claim this command exists to prevent — and the next archive\n    // would land a stale delta over living text on the strength of it. So it\n    // refuses by name and writes nothing, exactly as `loam archive` refuses a\n    // merge it could not read, under archive's code. The refusal is here, in\n    // the PLAN, so it lands before stageWrites: no file is touched, and a\n    // feature spanning four services does not get two of them pinned.\n    return fail(json, \"merge-failed\", `rebase ${id} failed — nothing was pinned: ${err.message}`);\n  }\n\n  if (!dryRun && writes.length > 0) {\n    // Staged and committed through the journaled transaction: a feature\n    // spanning four services is one act, and neither a full disk between its\n    // second and third file NOR a kill between two renames may leave two of\n    // them pinned to a reading the other two never saw — the journal makes\n    // the second case recoverable where rollback alone could not see it.\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"rebase\", rerun: `loam rebase ${id}`, target: id },\n      staged,\n      \"pinned\",\n    );\n    if (!committed.ok) {\n      return fail(\n        json,\n        committed.code,\n        committed.code === \"merge-failed\" ? `rebase ${id} failed — nothing was pinned: ${committed.message}` : committed.message,\n      );\n    }\n  }\n\n  // One line per pin, whichever corpus it came from: what to call the document,\n  // and the record itself. The two lists are reported separately in `--json`\n  // (the published `pins[]`/`services[]` keys keep meaning exactly what they\n  // meant) and together here, because a human rebasing one feature wants one\n  // list in one order.\n  const lines = [\n    ...outcomes.map((o) => ({ where: `${o.service}/${o.file}`, pin: o })),\n    ...capabilityOutcomes.map((o) => ({ where: `capabilities/${o.capability}/${o.file}`, pin: o })),\n  ];\n  const changed = lines.filter((l) => l.pin.status === \"pinned\" || l.pin.status === \"repinned\");\n  const unresolved = lines.filter((l) => l.pin.status === \"unresolved\");\n\n  if (json) {\n    emitJson({\n      command: \"rebase\",\n      feature: id,\n      services,\n      dryRun,\n      pins: outcomes,\n      // Additive, and separate from `pins[]` on purpose: `PinOutcome.service`\n      // is a published field, and a capability id written into it would say\n      // something false to every consumer that already reads it.\n      capabilities: capabilities.map((c) => c.id),\n      capabilityPins: capabilityOutcomes,\n      written: dryRun ? [] : writes.map((w) => repoPath(docsDir, w.path)),\n      ...(opts.recovered === null ? {} : { recovered: opts.recovered }),\n    });\n    return;\n  }\n\n  if (lines.length === 0) {\n    console.log(\n      `${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.`,\n    );\n    return;\n  }\n\n  if (opts.recovered !== null) console.log(`${sayRecovered(opts.recovered)}\\n`);\n  console.log(`${id}${dryRun ? \" (dry run)\" : \"\"}\\n`);\n  for (const { where, pin: o } of lines) {\n    const what = `${where}  ${o.kind} ${o.target}`;\n    if (o.status === \"unresolved\") {\n      console.log(`  · ${what} — not in the living docs yet, nothing to pin`);\n    } else if (o.status === \"unwritable\") {\n      console.log(`  ! ${what} — a YAML alias (or a key loam cannot address by name); loam will not stamp through it`);\n    } else if (o.status === \"unchanged\") {\n      console.log(`  = ${what} — already ${o.to}`);\n    } else if (o.status === \"pinned\") {\n      console.log(`  + ${what} — pinned ${o.to}`);\n    } else {\n      console.log(`  ~ ${what} — ${o.from} → ${o.to}`);\n    }\n  }\n\n  if (changed.length === 0) {\n    console.log(`\\nNothing to write: every pin already names the living version.`);\n  } else if (dryRun) {\n    console.log(`\\n${plural(changed.length, \"pin\")} would be written. Nothing was written.`);\n  } else {\n    console.log(`\\n${plural(changed.length, \"pin\")} written across ${plural(writes.length, \"file\")}.`);\n    // The one sentence that keeps this command honest. A pin is a claim about\n    // what its author read, and a `repinned` line means the living text moved\n    // under a delta that still says what it said before — restamping does not\n    // fold in the change it just stopped reporting.\n    const repinned = changed.filter((l) => l.pin.status === \"repinned\");\n    if (repinned.length > 0) {\n      console.log(\n        `\\n⚠ ${plural(repinned.length, \"pin\")} moved since this delta was written. A pin records what you read — ` +\n          `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.`,\n      );\n    }\n  }\n  if (unresolved.length > 0) {\n    console.log(\n      `\\n${plural(unresolved.length, \"item\")} could not be pinned because the living docs do not have them yet — ` +\n        `for a requirement, \\`loam dependencies ${id}\\` says which feature introduces it first; for an operation, this feature is adding it.`,\n    );\n  }\n}\n"]}