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

package/dist/core/openapi/merge/components.js

@@ -0,0 +1,199 @@
+/**
+ * The component closure the merge computes over `$ref`s. The two plain
+ * questions it asks — which refs does this tree contain, and what does one
+ * point at — moved to `../depth.ts` once the reader needed them too (that
+ * module's header says why the root, not here).
+ *
+ * The closure is verdict-driven, not reachability-driven: every component the
+ * feature DECLARES is classified against its `x-loam-baselines` entry exactly
+ * as an operation is classified against its pin, and reachability decides only
+ * one thing — whether a genuinely NEW component rides along — whenever the
+ * delta merges paths at all. The old rule, "copy everything reachable from any
+ * feature path item", let a QUOTED operation drag its authoring-time component
+ * copy over someone else's landed change; the walk now starts from what this
+ * merge actually WROTE, so a quote pulls nothing.
+ *
+ * Where the delta merges no path, that walk starts from nothing, and "is a new
+ * component reachable?" has no meaningful answer to give: a components-only
+ * delta declared every one of them on purpose and there is no operation for
+ * them to hide behind. Parking them forever is what made such a delta merge
+ * nothing at all, at exit 0 — `componentsAreTheDelta` is that case, and only
+ * that case.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { isMap, isScalar } from "yaml";
+import { classifyBaselineDigests, valueDigest, withoutFeatureKeysDeep } from "../digest.js";
+import { entryFor, restatedSurfaces, surfaceIn } from "../baseline/record.js";
+import { collectRefs, resolvePointer } from "../depth.js";
+/** One mapping node's pair for a key, matched AS A STRING — `setKeyed`'s find, reusable at any depth. */
+export function pairAt(node, key) {
+    return isMap(node) ? node.items.find((it) => isScalar(it.key) && String(it.key.value) === key) : undefined;
+}
+/**
+ * Write one value under the mapping at `parent`, matching the existing key AS A
+ * STRING: a living `404:` response is the YAML number 404, and a plain `setIn`
+ * with the string "404" misses it and APPENDS a second pair — the contract then
+ * declares the key twice, forever, with the pre-merge copy first in reading
+ * order. Path-agnostic on purpose, so it is the one upsert both contract axes
+ * write through: a component here and in the strip's twin write on the feature
+ * side, a component surface or a slot on the event axis
+ * (../../asyncapi/merge/{components,markers}.ts).
+ */
+export function setKeyed(doc, parent, key, value) {
+    const existing = pairAt(doc.getIn(parent), key);
+    if (existing !== undefined)
+        existing.value = doc.createNode(value);
+    else
+        doc.setIn([...parent, key], value);
+}
+/**
+ * Merge the feature's components into the living document by verdict:
+ *
+ *  - quote → skipped; the living copy stays, whatever landed on it since.
+ *  - edit, stale (under --approve), or unpinned-and-differing → copied; the
+ *    unpinned copy is the old upsert, kept for never-rebased deltas.
+ *  - unpinned and living-equal → skipped, as it always was: nothing to write.
+ *  - unfounded (pinned, living gone — the gate refused; --approve) → copied,
+ *    because a written operation may reference it and the merge must never
+ *    leave a dangling ref behind.
+ *  - NEW (unpinned, living-absent) → copied only when reachable from written
+ *    content or from another copied component's own refs. The visited-set
+ *    fixpoint is what keeps A↔B cycles terminating and unrelated namespaces
+ *    uncopied. When the components ARE the delta there is no written content
+ *    to be reachable from, so every one of them is copied outright.
+ *
+ * The unresolved sweep is unchanged in meaning: every local ref reachable from
+ * written content and copied components must resolve in the copy set or the
+ * living document.
+ */
+export function mergeComponentClosure(input) {
+    const { living, featPlain, livingPlain, record, written, componentsAreTheDelta } = input;
+    const componentsModified = [];
+    const componentsAdded = [];
+    const componentsQuoted = [];
+    const componentsStale = [];
+    const unresolved = [];
+    const copies = [];
+    const copied = new Set();
+    /** Genuinely new components, parked until something written reaches them. */
+    const parked = new Map();
+    /**
+     * Which declared surfaces the living contract does not have — recorded here,
+     * during classification, because this is the one place that asks. What was
+     * ADDED is decided at the write below instead: a parked component the
+     * fixpoint never reaches is absent from living and stays that way, and
+     * calling it added would name a component the merge did not write.
+     */
+    const absentFromLiving = new Set();
+    // ONE enumeration (baseline/record.ts) with the rebase plan and the gate —
+    // and ONE living lookup — so "which components does this delta declare, and
+    // do they exist" cannot drift between the command that pins, the gate that
+    // grades and this closure that writes.
+    for (const surface of restatedSurfaces(featPlain)) {
+        if (surface.kind !== "component")
+            continue;
+        const cut = surface.id.indexOf("/");
+        const entry = { kind: surface.id.slice(0, cut), name: surface.id.slice(cut + 1), value: surface.value };
+        const inLiving = surfaceIn(livingPlain, surface);
+        if (!inLiving.found)
+            absentFromLiving.add(surface.id);
+        const verdict = classifyBaselineDigests(entryFor(record, surface), valueDigest(surface.value), inLiving.found ? valueDigest(inLiving.value) : undefined);
+        if (verdict === "quote") {
+            componentsQuoted.push(surface.id);
+            continue;
+        }
+        if (verdict === "unpinned") {
+            if (!inLiving.found) {
+                parked.set(surface.id, entry);
+                continue;
+            }
+            if (isDeepStrictEqual(inLiving.value, surface.value))
+                continue;
+            componentsModified.push(surface.id);
+        }
+        else {
+            if (verdict === "stale")
+                componentsStale.push(surface.id);
+            if (inLiving.found && !isDeepStrictEqual(inLiving.value, surface.value))
+                componentsModified.push(surface.id);
+        }
+        copies.push(entry);
+        copied.add(surface.id);
+    }
+    // A components-only delta wrote no path, so the fixpoint below would start
+    // from an empty queue and every parked component would stay parked forever —
+    // the merge published a document byte-identical to the living one and archive
+    // said `ok`. The promotion happens HERE, before the queue is built, and that
+    // order is the whole point: a component promoted afterwards would carry its
+    // own `$ref`s past the sweep, and `openapi.ref-unresolved` would stop firing
+    // for exactly the deltas that most need it — a new schema pointing at a
+    // second one the author forgot to bring. Iterated as a SNAPSHOT: this loop
+    // empties `parked` as it goes and `visitRef` deletes from the same Map below,
+    // and neither may read it live while writing it.
+    if (componentsAreTheDelta) {
+        const promotions = [...parked.entries()];
+        for (const [id, entry] of promotions) {
+            parked.delete(id);
+            copies.push(entry);
+            copied.add(id);
+        }
+    }
+    // The reachability fixpoint: refs out of written content and out of every
+    // copy — classification copies and any promotions now, parked promotions as
+    // they join.
+    const queue = [
+        ...written.map((w) => ({ node: w.value, from: w.from })),
+        ...copies.map((c) => ({ node: c.value, from: `components/${c.kind}/${c.name}` })),
+    ];
+    const visited = new Set();
+    const visitRef = (ref, from) => {
+        if (!ref.startsWith("#/"))
+            return;
+        const match = /^#\/components\/([^/]+)\/([^/]+)(?:\/|$)/.exec(ref);
+        if (!match) {
+            if (!resolvePointer(featPlain, ref).found && !resolvePointer(livingPlain, ref).found) {
+                unresolved.push({ ref, from });
+            }
+            return;
+        }
+        const key = `${match[1]}/${match[2]}`;
+        if (visited.has(key))
+            return;
+        visited.add(key);
+        // Already copied by verdict: its own refs are in the queue from the start.
+        if (copied.has(key))
+            return;
+        const parkedEntry = parked.get(key);
+        if (parkedEntry !== undefined) {
+            parked.delete(key);
+            copies.push(parkedEntry);
+            copied.add(key);
+            queue.push({ node: parkedEntry.value, from: `components/${key}` });
+            return;
+        }
+        // Not copied and not new: a quoted or unchanged declaration, or something
+        // the feature never spells. Either way the LIVING document must have it.
+        if (!resolvePointer(livingPlain, `#/components/${key}`).found) {
+            unresolved.push({ ref, from });
+        }
+    };
+    while (queue.length > 0) {
+        const { node, from } = queue.pop();
+        for (const ref of collectRefs(node))
+            visitRef(ref, from);
+    }
+    for (const { kind, name, value } of copies) {
+        // Decided at the write, over the copies that actually happened: a promoted
+        // component is an addition, a parked one that nothing reached is not.
+        if (absentFromLiving.has(`${kind}/${name}`))
+            componentsAdded.push(`${kind}/${name}`);
+        // The value is deep-stripped of loam's bookkeeping keys — a component
+        // holding an operation shape nests them where the path-level strip never
+        // walks, and `--approve` once published `x-loam-remove: true` into a
+        // living component. Promoted copies go through this same write, so a
+        // components-only delta cannot be the one shape that publishes a marker.
+        setKeyed(living, ["components", kind], name, withoutFeatureKeysDeep(value));
+    }
+    return { componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved };
+}
+//# sourceMappingURL=components.js.map

package/dist/core/openapi/merge/components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../../../../src/core/openapi/merge/components.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The component closure the merge computes over `$ref`s. The two plain\n * questions it asks — which refs does this tree contain, and what does one\n * point at — moved to `../depth.ts` once the reader needed them too (that\n * module's header says why the root, not here).\n *\n * The closure is verdict-driven, not reachability-driven: every component the\n * feature DECLARES is classified against its `x-loam-baselines` entry exactly\n * as an operation is classified against its pin, and reachability decides only\n * one thing — whether a genuinely NEW component rides along — whenever the\n * delta merges paths at all. The old rule, \"copy everything reachable from any\n * feature path item\", let a QUOTED operation drag its authoring-time component\n * copy over someone else's landed change; the walk now starts from what this\n * merge actually WROTE, so a quote pulls nothing.\n *\n * Where the delta merges no path, that walk starts from nothing, and \"is a new\n * component reachable?\" has no meaningful answer to give: a components-only\n * delta declared every one of them on purpose and there is no operation for\n * them to hide behind. Parking them forever is what made such a delta merge\n * nothing at all, at exit 0 — `componentsAreTheDelta` is that case, and only\n * that case.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { isMap, isScalar, type Document, type Pair } from \"yaml\";\nimport { classifyBaselineDigests, valueDigest, withoutFeatureKeysDeep } from \"../digest.js\";\nimport { entryFor, restatedSurfaces, surfaceIn, type BaselineRecord } from \"../baseline/record.js\";\nimport { collectRefs, resolvePointer } from \"../depth.js\";\n\n/** Everything the closure needs; one object because the merge is its only caller. */\nexport interface ComponentClosureInput {\n  /** The living document the copies are written into. */\n  living: Document;\n  featPlain: unknown;\n  livingPlain: unknown;\n  /** The feature's `x-loam-baselines` record, read once by the merge. */\n  record: BaselineRecord;\n  /** The plain values the path merge actually wrote, labelled for the ref sweep. */\n  written: Array<{ from: string; value: unknown }>;\n  /**\n   * True only when the feature's `paths` holds no entry at all, so `written` is\n   * empty and nothing this merge wrote can reach a new component. The merge\n   * computes it from the path ENTRIES, not from what the path loop happened to\n   * write: one path entry, even an entirely quoted one, means the reachability\n   * question is real and this stays false. Widening it past that would copy the\n   * authoring-time component a quoted operation carries — the exact revert the\n   * verdict-driven closure exists to stop.\n   */\n  componentsAreTheDelta: boolean;\n}\n\n/** What the closure computed: components overwritten, added, quoted, stale, and refs nothing resolves. */\nexport interface ComponentClosureOutcome {\n  componentsModified: string[];\n  /** `<kind>/<name>` of components written where the living contract had none. */\n  componentsAdded: string[];\n  componentsQuoted: string[];\n  componentsStale: string[];\n  unresolved: Array<{ ref: string; from: string }>;\n}\n\n/** One mapping node's pair for a key, matched AS A STRING — `setKeyed`'s find, reusable at any depth. */\nexport function pairAt(node: unknown, key: string): Pair | undefined {\n  return isMap(node) ? node.items.find((it) => isScalar(it.key) && String(it.key.value) === key) : undefined;\n}\n\n/**\n * Write one value under the mapping at `parent`, matching the existing key AS A\n * STRING: a living `404:` response is the YAML number 404, and a plain `setIn`\n * with the string \"404\" misses it and APPENDS a second pair — the contract then\n * declares the key twice, forever, with the pre-merge copy first in reading\n * order. Path-agnostic on purpose, so it is the one upsert both contract axes\n * write through: a component here and in the strip's twin write on the feature\n * side, a component surface or a slot on the event axis\n * (../../asyncapi/merge/{components,markers}.ts).\n */\nexport function setKeyed(doc: Document, parent: string[], key: string, value: unknown): void {\n  const existing = pairAt(doc.getIn(parent), key);\n  if (existing !== undefined) existing.value = doc.createNode(value);\n  else doc.setIn([...parent, key], value);\n}\n\n/**\n * Merge the feature's components into the living document by verdict:\n *\n *  - quote → skipped; the living copy stays, whatever landed on it since.\n *  - edit, stale (under --approve), or unpinned-and-differing → copied; the\n *    unpinned copy is the old upsert, kept for never-rebased deltas.\n *  - unpinned and living-equal → skipped, as it always was: nothing to write.\n *  - unfounded (pinned, living gone — the gate refused; --approve) → copied,\n *    because a written operation may reference it and the merge must never\n *    leave a dangling ref behind.\n *  - NEW (unpinned, living-absent) → copied only when reachable from written\n *    content or from another copied component's own refs. The visited-set\n *    fixpoint is what keeps A↔B cycles terminating and unrelated namespaces\n *    uncopied. When the components ARE the delta there is no written content\n *    to be reachable from, so every one of them is copied outright.\n *\n * The unresolved sweep is unchanged in meaning: every local ref reachable from\n * written content and copied components must resolve in the copy set or the\n * living document.\n */\nexport function mergeComponentClosure(input: ComponentClosureInput): ComponentClosureOutcome {\n  const { living, featPlain, livingPlain, record, written, componentsAreTheDelta } = input;\n  const componentsModified: string[] = [];\n  const componentsAdded: string[] = [];\n  const componentsQuoted: string[] = [];\n  const componentsStale: string[] = [];\n  const unresolved: ComponentClosureOutcome[\"unresolved\"] = [];\n  const copies: Array<{ kind: string; name: string; value: unknown }> = [];\n  const copied = new Set<string>();\n  /** Genuinely new components, parked until something written reaches them. */\n  const parked = new Map<string, { kind: string; name: string; value: unknown }>();\n  /**\n   * Which declared surfaces the living contract does not have — recorded here,\n   * during classification, because this is the one place that asks. What was\n   * ADDED is decided at the write below instead: a parked component the\n   * fixpoint never reaches is absent from living and stays that way, and\n   * calling it added would name a component the merge did not write.\n   */\n  const absentFromLiving = new Set<string>();\n\n  // ONE enumeration (baseline/record.ts) with the rebase plan and the gate —\n  // and ONE living lookup — so \"which components does this delta declare, and\n  // do they exist\" cannot drift between the command that pins, the gate that\n  // grades and this closure that writes.\n  for (const surface of restatedSurfaces(featPlain)) {\n    if (surface.kind !== \"component\") continue;\n    const cut = surface.id.indexOf(\"/\");\n    const entry = { kind: surface.id.slice(0, cut), name: surface.id.slice(cut + 1), value: surface.value };\n    const inLiving = surfaceIn(livingPlain, surface);\n    if (!inLiving.found) absentFromLiving.add(surface.id);\n    const verdict = classifyBaselineDigests(\n      entryFor(record, surface),\n      valueDigest(surface.value),\n      inLiving.found ? valueDigest(inLiving.value) : undefined,\n    );\n    if (verdict === \"quote\") {\n      componentsQuoted.push(surface.id);\n      continue;\n    }\n    if (verdict === \"unpinned\") {\n      if (!inLiving.found) {\n        parked.set(surface.id, entry);\n        continue;\n      }\n      if (isDeepStrictEqual(inLiving.value, surface.value)) continue;\n      componentsModified.push(surface.id);\n    } else {\n      if (verdict === \"stale\") componentsStale.push(surface.id);\n      if (inLiving.found && !isDeepStrictEqual(inLiving.value, surface.value)) componentsModified.push(surface.id);\n    }\n    copies.push(entry);\n    copied.add(surface.id);\n  }\n\n  // A components-only delta wrote no path, so the fixpoint below would start\n  // from an empty queue and every parked component would stay parked forever —\n  // the merge published a document byte-identical to the living one and archive\n  // said `ok`. The promotion happens HERE, before the queue is built, and that\n  // order is the whole point: a component promoted afterwards would carry its\n  // own `$ref`s past the sweep, and `openapi.ref-unresolved` would stop firing\n  // for exactly the deltas that most need it — a new schema pointing at a\n  // second one the author forgot to bring. Iterated as a SNAPSHOT: this loop\n  // empties `parked` as it goes and `visitRef` deletes from the same Map below,\n  // and neither may read it live while writing it.\n  if (componentsAreTheDelta) {\n    const promotions = [...parked.entries()];\n    for (const [id, entry] of promotions) {\n      parked.delete(id);\n      copies.push(entry);\n      copied.add(id);\n    }\n  }\n\n  // The reachability fixpoint: refs out of written content and out of every\n  // copy — classification copies and any promotions now, parked promotions as\n  // they join.\n  const queue: Array<{ node: unknown; from: string }> = [\n    ...written.map((w) => ({ node: w.value, from: w.from })),\n    ...copies.map((c) => ({ node: c.value, from: `components/${c.kind}/${c.name}` })),\n  ];\n  const visited = new Set<string>();\n  const visitRef = (ref: string, from: string): void => {\n    if (!ref.startsWith(\"#/\")) return;\n    const match = /^#\\/components\\/([^/]+)\\/([^/]+)(?:\\/|$)/.exec(ref);\n    if (!match) {\n      if (!resolvePointer(featPlain, ref).found && !resolvePointer(livingPlain, ref).found) {\n        unresolved.push({ ref, from });\n      }\n      return;\n    }\n    const key = `${match[1]!}/${match[2]!}`;\n    if (visited.has(key)) return;\n    visited.add(key);\n    // Already copied by verdict: its own refs are in the queue from the start.\n    if (copied.has(key)) return;\n    const parkedEntry = parked.get(key);\n    if (parkedEntry !== undefined) {\n      parked.delete(key);\n      copies.push(parkedEntry);\n      copied.add(key);\n      queue.push({ node: parkedEntry.value, from: `components/${key}` });\n      return;\n    }\n    // Not copied and not new: a quoted or unchanged declaration, or something\n    // the feature never spells. Either way the LIVING document must have it.\n    if (!resolvePointer(livingPlain, `#/components/${key}`).found) {\n      unresolved.push({ ref, from });\n    }\n  };\n  while (queue.length > 0) {\n    const { node, from } = queue.pop()!;\n    for (const ref of collectRefs(node)) visitRef(ref, from);\n  }\n\n  for (const { kind, name, value } of copies) {\n    // Decided at the write, over the copies that actually happened: a promoted\n    // component is an addition, a parked one that nothing reached is not.\n    if (absentFromLiving.has(`${kind}/${name}`)) componentsAdded.push(`${kind}/${name}`);\n    // The value is deep-stripped of loam's bookkeeping keys — a component\n    // holding an operation shape nests them where the path-level strip never\n    // walks, and `--approve` once published `x-loam-remove: true` into a\n    // living component. Promoted copies go through this same write, so a\n    // components-only delta cannot be the one shape that publishes a marker.\n    setKeyed(living, [\"components\", kind], name, withoutFeatureKeysDeep(value));\n  }\n\n  return { componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved };\n}\n"]}

package/dist/core/openapi/merge/error.js

@@ -0,0 +1,16 @@
+/** A document the merge planner cannot read. Commands map this domain error to their own envelope. */
+export class OpenapiMergeError extends Error {
+    source;
+    service;
+    name = "OpenapiMergeError";
+    constructor(source, service, detail) {
+        super(`${source} openapi for ${service} is not valid YAML: ${detail}`);
+        this.source = source;
+        this.service = service;
+    }
+}
+/** The `fail` the tree helpers take, for one side of this axis. */
+export function openapiRefusal(source, service) {
+    return (detail) => new OpenapiMergeError(source, service, detail);
+}
+//# sourceMappingURL=error.js.map

package/dist/core/openapi/merge/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../../src/core/openapi/merge/error.ts"],"names":[],"mappings":"AAeA,sGAAsG;AACtG,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAI/B,MAAM;IACN,OAAO;IAJA,IAAI,GAAG,mBAAmB,CAAC;IAE7C,YACW,MAA0B,EAC1B,OAAe,EACxB,MAAc;QAEd,KAAK,CAAC,GAAG,MAAM,gBAAgB,OAAO,uBAAuB,MAAM,EAAE,CAAC,CAAC;sBAJ9D,MAAM;uBACN,OAAO;IAIlB,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,UAAU,cAAc,CAAC,MAA0B,EAAE,OAAe;IACxE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC","sourcesContent":["/**\n * The one refusal every stage of the contract delta path raises: a document the\n * planner cannot read, named by which side it came from.\n *\n * It is the package's leaf for the same reason the pin, the markers and the\n * merge each throw it: whichever of them fails, the command above has to map\n * one domain error onto its own envelope. A module that owned the error would\n * be imported by its two siblings for that reason alone.\n *\n * Every stage reads and writes its contract through ../contract-tree.ts, and\n * hands those helpers `openapiRefusal` as the error to raise — which is what\n * makes each of them fail with this one identically.\n */\nexport type OpenapiMergeSource = \"feature\" | \"living\";\n\n/** A document the merge planner cannot read. Commands map this domain error to their own envelope. */\nexport class OpenapiMergeError extends Error {\n  override readonly name = \"OpenapiMergeError\";\n\n  constructor(\n    readonly source: OpenapiMergeSource,\n    readonly service: string,\n    detail: string,\n  ) {\n    super(`${source} openapi for ${service} is not valid YAML: ${detail}`);\n  }\n}\n\n/** The `fail` the tree helpers take, for one side of this axis. */\nexport function openapiRefusal(source: OpenapiMergeSource, service: string): (detail: string) => OpenapiMergeError {\n  return (detail) => new OpenapiMergeError(source, service, detail);\n}\n"]}

package/dist/core/openapi/merge/markers.js

@@ -0,0 +1,204 @@
+/**
+ * The keys loam adds to a feature's contract that must never reach the living
+ * one: `x-loam-remove`, `x-loam-based-on`, and the root `x-loam-baselines`
+ * record.
+ *
+ * They are gathered here rather than spread through the merge because they are
+ * the vocabulary both ends of the delta path share — `stripOpenapiRemovalMarkers`
+ * takes them out for the projection a service repository sees, and the merge
+ * takes them out again on the way into the living document. Two spellings of
+ * "which keys are feature-only" is how one of the two starts leaking a marker.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { isMap, isScalar } from "yaml";
+// Every `isRecord` below asks one question of a resolved plain tree: is this a
+// node that can hold OpenAPI keys — an object, not an array?
+import { isRecord } from "../../kernel/records.js";
+import { HTTP_METHODS } from "../doc.js";
+import { FEATURE_ONLY_KEYS, isRemoval, operationBaselineOf, withoutFeatureKeysDeep, withoutOperationBaseline, OPENAPI_BASELINE_KEY, OPENAPI_BASELINES_KEY, } from "../digest.js";
+import { setKeyed } from "./components.js";
+import { openapiRefusal } from "./error.js";
+import { readTree, writeTreeOver } from "../contract-tree.js";
+/**
+ * Remove feature-only operation-removal markers — and the root
+ * `x-loam-baselines` record — before a feature contract is used to create a
+ * brand-new living document. Normally coherence refuses the removal shape
+ * because there cannot be a removal target; this guard also keeps `--approve`
+ * from ever persisting a marker into living docs. The record needs the strip
+ * on THIS path even more than the pins do: archive's create branch publishes
+ * this function's output verbatim, and a components-only delta has nothing
+ * strippable inside `paths` at all — the root key must not ride out on the
+ * early returns below.
+ */
+export function stripOpenapiRemovalMarkers(featureText, service) {
+    // One refusal for every branch below, so each fails the same way.
+    const fail = openapiRefusal("feature", service);
+    const { doc: feature, plain } = readTree(featureText, fail);
+    const hasRecord = isRecord(plain) && OPENAPI_BASELINES_KEY in plain;
+    // Shape from the RESOLVED tree, for the same reason the merge reads it there:
+    // an aliased `paths` or path item is not a map node, and treating it as
+    // "nothing to strip" is how a feature-only marker reached a living contract.
+    const paths = plainChild(plain, "paths");
+    if (!isRecord(paths)) {
+        if (!hasRecord)
+            return featureText;
+        feature.deleteIn([OPENAPI_BASELINES_KEY]);
+        return writeTreeOver(feature, featureText, fail);
+    }
+    const cleaned = {};
+    let stripped = false;
+    for (const [path, item] of Object.entries(paths)) {
+        const kept = withoutFeatureMarkers(item);
+        if (!isDeepStrictEqual(kept, item))
+            stripped = true;
+        // A path the strip emptied goes with its last operation: `\/x: {}` is a
+        // path the contract advertises and nothing answers.
+        if (kept !== undefined)
+            cleaned[path] = kept;
+    }
+    // Component values get the same discipline as path items: a component
+    // holding an operation shape (a `pathItems` component, a callback) nests
+    // the feature-only keys where the paths walk never looks, and the create
+    // branch publishes this function's output verbatim. The write is
+    // string-key-matched (setKeyed) so a numeric component name is
+    // replaced, never duplicated.
+    const comps = plainChild(plain, "components");
+    if (isRecord(comps)) {
+        for (const [kind, names] of Object.entries(comps)) {
+            if (!isRecord(names))
+                continue;
+            for (const [name, value] of Object.entries(names)) {
+                const kept = withoutFeatureKeysDeep(value);
+                if (kept !== value) {
+                    setKeyed(feature, ["components", kind], name, kept);
+                    stripped = true;
+                }
+            }
+        }
+    }
+    if (!stripped) {
+        if (!hasRecord)
+            return featureText;
+        feature.deleteIn([OPENAPI_BASELINES_KEY]);
+        return writeTreeOver(feature, featureText, fail);
+    }
+    // Edit the AST in place when every node the strip touches IS a node — the
+    // author's comments, key order and formatting are theirs to keep. An alias
+    // cannot be edited in place (there is one shared value behind it, and
+    // deleting a key through it would change every use), so those documents get
+    // their `paths` rewritten from the resolved tree instead: losing formatting
+    // is a cost, shipping the marker is a corruption.
+    //
+    // The test has to reach the OPERATION nodes too, not just the path items. The
+    // in-place branch strips a surviving operation's pin through
+    // `["paths", p, m, x-loam-based-on]`, and an aliased operation is exactly one
+    // level below where the check used to look — so `deleteIn` walked into a node
+    // that is not a collection and threw out of archive as `internal`, on a
+    // document whose only fault was writing one operation twice.
+    //
+    // What disqualifies a method is "there is something here to strip and I cannot
+    // reach it", not "this is not a map node". Only a resolved MAPPING can be a
+    // removal marker or carry a pin, so a method spelled as a scalar — `get: ~`,
+    // or a string — is nothing the in-place branch would have touched; demanding a
+    // map node of it too demoted whole documents to the rewrite branch and cost
+    // their author every comment, anchor and hand-chosen key order inside `paths`,
+    // in the bytes archive installs as the living contract. What is left is the
+    // real hazard: a mapping the AST does not hand back as a map. An alias is the
+    // one node kind that resolves to a mapping without being one, and a method
+    // whose KEY is an alias is not findable by name at all, so `deleteIn` reports
+    // nothing deleted and the marker ships in silence. Both answer `undefined` or
+    // a non-map here, and both belong on the safe branch.
+    const editable = isMap(feature.get("paths")) &&
+        Object.entries(paths).every(([p, item]) => isMap(feature.getIn(["paths", p])) &&
+            (!isRecord(item) ||
+                Object.entries(item).every(([m, op]) => !HTTP_METHODS.has(m) || !isRecord(op) || isMap(feature.getIn(["paths", p, m])))));
+    if (!editable) {
+        feature.setIn(["paths"], cleaned);
+    }
+    else {
+        for (const [path, item] of Object.entries(paths)) {
+            if (!isRecord(item))
+                continue;
+            for (const [m, value] of Object.entries(item)) {
+                // A loam marker at PATH level, deleted here for the same reason the
+                // resolved-tree branch drops it: the two branches must agree exactly
+                // about what a living contract may carry.
+                if (FEATURE_ONLY_KEYS.has(m))
+                    feature.deleteIn(["paths", path, m]);
+                if (!HTTP_METHODS.has(m))
+                    continue;
+                if (isRemoval(value))
+                    feature.deleteIn(["paths", path, m]);
+                // The surviving operations keep their formatting but lose their pin:
+                // the in-place branch must strip everything the resolved-tree branch
+                // does, or the two disagree about what a living contract may carry.
+                else if (operationBaselineOf(value) !== undefined) {
+                    feature.deleteIn(["paths", path, m, OPENAPI_BASELINE_KEY]);
+                }
+            }
+            // The merge's twin: no OPERATIONS left means the path goes, surviving
+            // path-level keys included — `{}` was only the easy shape of dead.
+            dropPathIfNoOperations(feature, path);
+        }
+    }
+    // The root record goes on BOTH serialization branches: it is feature
+    // bookkeeping exactly like the pins, and the rewrite branch above replaced
+    // only `paths`, so the root key survives either way without this.
+    if (hasRecord)
+        feature.deleteIn([OPENAPI_BASELINES_KEY]);
+    return writeTreeOver(feature, featureText, fail);
+}
+/**
+ * Removing the last method leaves a path the contract still advertises and
+ * nothing answers — and `{}` is only the easy shape of that state: a surviving
+ * path-LEVEL key (`parameters`, `summary`) kept the path alive with zero
+ * operations just as misleadingly. No methods left means the path goes,
+ * whatever else survived beside them. One cleanup for both sides of the delta
+ * path, so they cannot disagree about it: the merge runs it on the living
+ * document, the strip on the feature's.
+ */
+export function dropPathIfNoOperations(doc, path) {
+    const remaining = doc.getIn(["paths", path]);
+    if (isMap(remaining) && !remaining.items.some((it) => isScalar(it.key) && HTTP_METHODS.has(String(it.key.value)))) {
+        doc.deleteIn(["paths", path]);
+    }
+}
+export function opLabel(before, after, method, path) {
+    const operation = operationIdOf(after) ?? operationIdOf(before);
+    return operation !== undefined ? `'${operation}' (${method} ${path})` : `${method} ${path}`;
+}
+/** Read an operationId from a YAML or plain operation node. */
+export function operationIdOf(node) {
+    const value = isMap(node)
+        ? node.get("operationId")
+        : node !== null && typeof node === "object"
+            ? node["operationId"]
+            : undefined;
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Copy a path item without anything that belongs to the FEATURE rather than to
+ * the contract: removal-marker operations, the `x-loam-based-on` pins on the
+ * operations that survive, and a loam marker written at PATH level. All three
+ * are instructions to loam, and a living contract that carries any of them is
+ * lying to the next reader — and, for the pin, to the next feature's baseline.
+ *
+ * The path-level case used to fall through: the filter guarded only HTTP
+ * methods, so `x-loam-remove: true` beside the methods was copied verbatim into
+ * the fleet's living contract, where it also kept the empty-path cleanup from
+ * ever seeing an empty path.
+ */
+export function withoutFeatureMarkers(node) {
+    if (node === null || typeof node !== "object" || Array.isArray(node))
+        return node;
+    const entries = Object.entries(node)
+        .filter(([key, value]) => !FEATURE_ONLY_KEYS.has(key) && !(HTTP_METHODS.has(key) && isRemoval(value)))
+        .map(([key, value]) => [key, HTTP_METHODS.has(key) ? withoutOperationBaseline(value) : value]);
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
+export function plainChild(parent, key) {
+    return parent !== null && typeof parent === "object"
+        ? parent[key]
+        : undefined;
+}
+//# sourceMappingURL=markers.js.map

package/dist/core/openapi/merge/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../../../src/core/openapi/merge/markers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The keys loam adds to a feature's contract that must never reach the living\n * one: `x-loam-remove`, `x-loam-based-on`, and the root `x-loam-baselines`\n * record.\n *\n * They are gathered here rather than spread through the merge because they are\n * the vocabulary both ends of the delta path share — `stripOpenapiRemovalMarkers`\n * takes them out for the projection a service repository sees, and the merge\n * takes them out again on the way into the living document. Two spellings of\n * \"which keys are feature-only\" is how one of the two starts leaking a marker.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { isMap, isScalar, type Document } from \"yaml\";\n// Every `isRecord` below asks one question of a resolved plain tree: is this a\n// node that can hold OpenAPI keys — an object, not an array?\nimport { isRecord } from \"../../kernel/records.js\";\nimport { HTTP_METHODS } from \"../doc.js\";\nimport {\n  FEATURE_ONLY_KEYS,\n  isRemoval,\n  operationBaselineOf,\n  withoutFeatureKeysDeep,\n  withoutOperationBaseline,\n  OPENAPI_BASELINE_KEY,\n  OPENAPI_BASELINES_KEY,\n} from \"../digest.js\";\nimport { setKeyed } from \"./components.js\";\nimport { openapiRefusal } from \"./error.js\";\nimport { readTree, writeTreeOver } from \"../contract-tree.js\";\n\n/**\n * Remove feature-only operation-removal markers — and the root\n * `x-loam-baselines` record — before a feature contract is used to create a\n * brand-new living document. Normally coherence refuses the removal shape\n * because there cannot be a removal target; this guard also keeps `--approve`\n * from ever persisting a marker into living docs. The record needs the strip\n * on THIS path even more than the pins do: archive's create branch publishes\n * this function's output verbatim, and a components-only delta has nothing\n * strippable inside `paths` at all — the root key must not ride out on the\n * early returns below.\n */\nexport function stripOpenapiRemovalMarkers(featureText: string, service: string): string {\n  // One refusal for every branch below, so each fails the same way.\n  const fail = openapiRefusal(\"feature\", service);\n  const { doc: feature, plain } = readTree(featureText, fail);\n  const hasRecord = isRecord(plain) && OPENAPI_BASELINES_KEY in plain;\n  // Shape from the RESOLVED tree, for the same reason the merge reads it there:\n  // an aliased `paths` or path item is not a map node, and treating it as\n  // \"nothing to strip\" is how a feature-only marker reached a living contract.\n  const paths = plainChild(plain, \"paths\");\n  if (!isRecord(paths)) {\n    if (!hasRecord) return featureText;\n    feature.deleteIn([OPENAPI_BASELINES_KEY]);\n    return writeTreeOver(feature, featureText, fail);\n  }\n\n  const cleaned: Record<string, unknown> = {};\n  let stripped = false;\n  for (const [path, item] of Object.entries(paths)) {\n    const kept = withoutFeatureMarkers(item);\n    if (!isDeepStrictEqual(kept, item)) stripped = true;\n    // A path the strip emptied goes with its last operation: `\\/x: {}` is a\n    // path the contract advertises and nothing answers.\n    if (kept !== undefined) cleaned[path] = kept;\n  }\n  // Component values get the same discipline as path items: a component\n  // holding an operation shape (a `pathItems` component, a callback) nests\n  // the feature-only keys where the paths walk never looks, and the create\n  // branch publishes this function's output verbatim. The write is\n  // string-key-matched (setKeyed) so a numeric component name is\n  // replaced, never duplicated.\n  const comps = plainChild(plain, \"components\");\n  if (isRecord(comps)) {\n    for (const [kind, names] of Object.entries(comps)) {\n      if (!isRecord(names)) continue;\n      for (const [name, value] of Object.entries(names)) {\n        const kept = withoutFeatureKeysDeep(value);\n        if (kept !== value) {\n          setKeyed(feature, [\"components\", kind], name, kept);\n          stripped = true;\n        }\n      }\n    }\n  }\n\n  if (!stripped) {\n    if (!hasRecord) return featureText;\n    feature.deleteIn([OPENAPI_BASELINES_KEY]);\n    return writeTreeOver(feature, featureText, fail);\n  }\n\n  // Edit the AST in place when every node the strip touches IS a node — the\n  // author's comments, key order and formatting are theirs to keep. An alias\n  // cannot be edited in place (there is one shared value behind it, and\n  // deleting a key through it would change every use), so those documents get\n  // their `paths` rewritten from the resolved tree instead: losing formatting\n  // is a cost, shipping the marker is a corruption.\n  //\n  // The test has to reach the OPERATION nodes too, not just the path items. The\n  // in-place branch strips a surviving operation's pin through\n  // `[\"paths\", p, m, x-loam-based-on]`, and an aliased operation is exactly one\n  // level below where the check used to look — so `deleteIn` walked into a node\n  // that is not a collection and threw out of archive as `internal`, on a\n  // document whose only fault was writing one operation twice.\n  //\n  // What disqualifies a method is \"there is something here to strip and I cannot\n  // reach it\", not \"this is not a map node\". Only a resolved MAPPING can be a\n  // removal marker or carry a pin, so a method spelled as a scalar — `get: ~`,\n  // or a string — is nothing the in-place branch would have touched; demanding a\n  // map node of it too demoted whole documents to the rewrite branch and cost\n  // their author every comment, anchor and hand-chosen key order inside `paths`,\n  // in the bytes archive installs as the living contract. What is left is the\n  // real hazard: a mapping the AST does not hand back as a map. An alias is the\n  // one node kind that resolves to a mapping without being one, and a method\n  // whose KEY is an alias is not findable by name at all, so `deleteIn` reports\n  // nothing deleted and the marker ships in silence. Both answer `undefined` or\n  // a non-map here, and both belong on the safe branch.\n  const editable =\n    isMap(feature.get(\"paths\")) &&\n    Object.entries(paths).every(\n      ([p, item]) =>\n        isMap(feature.getIn([\"paths\", p])) &&\n        (!isRecord(item) ||\n          Object.entries(item).every(\n            ([m, op]) => !HTTP_METHODS.has(m) || !isRecord(op) || isMap(feature.getIn([\"paths\", p, m])),\n          )),\n    );\n  if (!editable) {\n    feature.setIn([\"paths\"], cleaned);\n  } else {\n    for (const [path, item] of Object.entries(paths)) {\n      if (!isRecord(item)) continue;\n      for (const [m, value] of Object.entries(item)) {\n        // A loam marker at PATH level, deleted here for the same reason the\n        // resolved-tree branch drops it: the two branches must agree exactly\n        // about what a living contract may carry.\n        if (FEATURE_ONLY_KEYS.has(m)) feature.deleteIn([\"paths\", path, m]);\n        if (!HTTP_METHODS.has(m)) continue;\n        if (isRemoval(value)) feature.deleteIn([\"paths\", path, m]);\n        // The surviving operations keep their formatting but lose their pin:\n        // the in-place branch must strip everything the resolved-tree branch\n        // does, or the two disagree about what a living contract may carry.\n        else if (operationBaselineOf(value) !== undefined) {\n          feature.deleteIn([\"paths\", path, m, OPENAPI_BASELINE_KEY]);\n        }\n      }\n      // The merge's twin: no OPERATIONS left means the path goes, surviving\n      // path-level keys included — `{}` was only the easy shape of dead.\n      dropPathIfNoOperations(feature, path);\n    }\n  }\n  // The root record goes on BOTH serialization branches: it is feature\n  // bookkeeping exactly like the pins, and the rewrite branch above replaced\n  // only `paths`, so the root key survives either way without this.\n  if (hasRecord) feature.deleteIn([OPENAPI_BASELINES_KEY]);\n  return writeTreeOver(feature, featureText, fail);\n}\n\n/**\n * Removing the last method leaves a path the contract still advertises and\n * nothing answers — and `{}` is only the easy shape of that state: a surviving\n * path-LEVEL key (`parameters`, `summary`) kept the path alive with zero\n * operations just as misleadingly. No methods left means the path goes,\n * whatever else survived beside them. One cleanup for both sides of the delta\n * path, so they cannot disagree about it: the merge runs it on the living\n * document, the strip on the feature's.\n */\nexport function dropPathIfNoOperations(doc: Document, path: string): void {\n  const remaining = doc.getIn([\"paths\", path]);\n  if (isMap(remaining) && !remaining.items.some((it) => isScalar(it.key) && HTTP_METHODS.has(String(it.key.value)))) {\n    doc.deleteIn([\"paths\", path]);\n  }\n}\n\nexport function opLabel(before: unknown, after: unknown, method: string, path: string): string {\n  const operation = operationIdOf(after) ?? operationIdOf(before);\n  return operation !== undefined ? `'${operation}' (${method} ${path})` : `${method} ${path}`;\n}\n\n/** Read an operationId from a YAML or plain operation node. */\nexport function operationIdOf(node: unknown): string | undefined {\n  const value = isMap(node)\n    ? node.get(\"operationId\")\n    : node !== null && typeof node === \"object\"\n      ? (node as Record<string, unknown>)[\"operationId\"]\n      : undefined;\n  return typeof value === \"string\" && value.length > 0 ? value : undefined;\n}\n\n\n\n/**\n * Copy a path item without anything that belongs to the FEATURE rather than to\n * the contract: removal-marker operations, the `x-loam-based-on` pins on the\n * operations that survive, and a loam marker written at PATH level. All three\n * are instructions to loam, and a living contract that carries any of them is\n * lying to the next reader — and, for the pin, to the next feature's baseline.\n *\n * The path-level case used to fall through: the filter guarded only HTTP\n * methods, so `x-loam-remove: true` beside the methods was copied verbatim into\n * the fleet's living contract, where it also kept the empty-path cleanup from\n * ever seeing an empty path.\n */\nexport function withoutFeatureMarkers(node: unknown): unknown {\n  if (node === null || typeof node !== \"object\" || Array.isArray(node)) return node;\n  const entries = Object.entries(node as Record<string, unknown>)\n    .filter(([key, value]) => !FEATURE_ONLY_KEYS.has(key) && !(HTTP_METHODS.has(key) && isRemoval(value)))\n    .map(([key, value]) => [key, HTTP_METHODS.has(key) ? withoutOperationBaseline(value) : value] as const);\n  return entries.length === 0 ? undefined : Object.fromEntries(entries);\n}\n\nexport function plainChild(parent: unknown, key: string): unknown {\n  return parent !== null && typeof parent === \"object\"\n    ? (parent as Record<string, unknown>)[key]\n    : undefined;\n}\n"]}