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

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

@@ -0,0 +1 @@
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../../../../src/core/asyncapi/merge/components.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The SURFACE half of the event merge: every `components/<kind>/<name>` the\n * feature declares outside `messages`, folded into the living contract by the\n * same verdict the slot loop takes.\n *\n * Verdict-driven and nothing else. A surface is classified against its\n * `x-loam-baselines` entry exactly as a slot is classified against its\n * in-value pin, so a QUOTE is skipped whatever landed on the living value\n * since, and an EDIT is written. There is deliberately no reachability\n * machinery here — the OpenAPI closure parks a genuinely new component until\n * something written reaches it, because on that axis a quoted OPERATION can\n * drag its authoring-time component copy along. This axis has no such carrier:\n * a surface is only ever copied because the delta declares it, and the ref\n * discipline is the post-hoc `danglingRefs` diff the merge runs over the whole\n * merged tree (../depth.ts) rather than the closure's queued `{ref, from}`.\n * Borrowing the parked set would mean a schema the author wrote on purpose\n * silently not merging, which is the defect this module closes.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport type { Document } from \"yaml\";\nimport { entryFor, surfaceIn, type BaselineRecord } from \"../../openapi/baseline/record.js\";\nimport { classifyBaselineDigests, valueDigest, withoutFeatureKeysDeep } from \"../../openapi/digest.js\";\n// The OpenAPI axis's component writer, imported rather than respelled: it is\n// path-agnostic and string-key-matched, so a numeric component name (`404:` is\n// the YAML number) is REPLACED rather than appended a second time — the same\n// hazard every slot writer on this axis goes through `slotPair` for.\nimport { setComponentValue } from \"../../openapi/merge/components.js\";\nimport { asyncapiSurfaces } from \"../baseline/surfaces.js\";\nimport { writableSection } from \"./markers.js\";\n\n/** Everything the surface merge needs; one object because the merge is its only caller. */\nexport interface AsyncapiComponentsInput {\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  service: string;\n}\n\n/** What the surface merge computed. */\nexport interface AsyncapiComponentsOutcome {\n  /** `<kind>/<name>` of living surfaces overwritten with different content. */\n  componentsModified: string[];\n  /** Surfaces the delta QUOTED — not copied, living's copy kept. */\n  componentsQuoted: string[];\n  /** Surfaces written on a stale record entry — under `--approve`, like the slots. */\n  componentsStale: string[];\n  /**\n   * Whether anything was actually written. The merge turns this into `edited`:\n   * without it the surface verdicts would be computed, reported, and then\n   * dropped on the floor by the `!edited` early return that keeps an all-quote\n   * delta byte-identical — the defect surviving in a new shape, with the plan\n   * naming components it never wrote.\n   */\n  copied: boolean;\n}\n\n/**\n * Merge the feature's component surfaces into the living document by verdict:\n *\n *  - quote → skipped; the living copy stays, whatever landed on it since.\n *  - edit, or stale (under `--approve`) → copied, and reported.\n *  - unpinned and living-equal → skipped: there is nothing to write, and a\n *    never-rebased delta that merely restates the contract must not churn its\n *    bytes (the slot loop's rule, at surface depth).\n *  - unpinned and differing → copied, the old upsert kept for never-rebased\n *    deltas, and reported as a modification like any other overwrite.\n *  - unfounded (pinned, living gone — the gate refused; `--approve`) and NEW\n *    (unpinned, living-absent) → copied. Both write a surface the living\n *    contract does not have, which is the ordinary shape of a delta that adds\n *    a schema.\n *\n * Every write goes through the deep strip first: a component's value can nest\n * loam's keys anywhere (a schema `properties` entry, a `$ref` sibling), and\n * publishing one into a living contract is the failure `--approve` already\n * caused once on the OpenAPI axis.\n */\nexport function mergeAsyncapiComponents(input: AsyncapiComponentsInput): AsyncapiComponentsOutcome {\n  const { living, featPlain, livingPlain, record, service } = input;\n  const componentsModified: string[] = [];\n  const componentsQuoted: string[] = [];\n  const componentsStale: string[] = [];\n  const copies: Array<{ kind: string; name: string; value: unknown }> = [];\n\n  // ONE enumeration (../baseline/surfaces.ts) with the rebase plan and the\n  // gate, and ONE living lookup (surfaceIn), so \"which surfaces does this\n  // delta declare, and does living have this one\" cannot have two answers.\n  for (const surface of asyncapiSurfaces(featPlain)) {\n    // The first `/` is the kind boundary, exactly as `surfaceIn` reads it back\n    // — a component name cannot legally contain one.\n    const cut = surface.id.indexOf(\"/\");\n    const inLiving = surfaceIn(livingPlain, surface);\n    const verdict = classifyBaselineDigests(\n      entryFor(record, surface),\n      valueDigest(surface.value),\n      inLiving.found ? valueDigest(inLiving.value) : undefined,\n    );\n    // A QUOTE is not a merge input, on this axis for the slot loop's reason:\n    // the author wrote the surface down because an AsyncAPI delta is a\n    // COMPLETE document, not because they changed it. Mechanical, not a\n    // judgement — `--approve` does not turn it back on.\n    if (verdict === \"quote\") {\n      componentsQuoted.push(surface.id);\n      continue;\n    }\n    if (verdict === \"stale\") componentsStale.push(surface.id);\n    const publish = withoutFeatureKeysDeep(surface.value);\n    if (inLiving.found && isDeepStrictEqual(inLiving.value, publish)) continue;\n    if (inLiving.found) componentsModified.push(surface.id);\n    copies.push({ kind: surface.id.slice(0, cut), name: surface.id.slice(cut + 1), value: publish });\n  }\n\n  for (const { kind, name, value } of copies) {\n    // Guarded at the write, like every slot write: a living `components:\n    // *alias` (or an aliased `components.schemas`) is one shared value behind\n    // every use of the anchor, so writing a surface through it would rewrite\n    // every other node that aliases it.\n    writableSection(living, livingPlain, [\"components\", kind], service);\n    setComponentValue(living, kind, name, value);\n  }\n\n  return { componentsModified, componentsQuoted, componentsStale, copied: copies.length > 0 };\n}\n"]}

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

@@ -0,0 +1,33 @@
+/**
+ * The one refusal every stage of the event-contract delta path raises: a
+ * document the planner cannot read, named by which side it came from.
+ *
+ * The mirror of ../../openapi/merge/error.ts, and the package's leaf for the
+ * same reason: whichever sibling fails — the pin, the markers or the merge —
+ * the command above has to map one domain error onto its own envelope, and a
+ * module that owned the error would be imported by its siblings for that
+ * reason alone.
+ */
+/**
+ * A document the merge machinery cannot use. Commands map this domain error
+ * to their own envelope. `problem` is the verb phrase between the document's
+ * name and the detail — "is not valid YAML" for the parse failures that are
+ * the common case, overridden where the document parses fine and the refusal
+ * is about what it says (a section spelling one slot key twice is legal YAML,
+ * and calling it invalid would send the author to a linter that agrees with
+ * the file).
+ */
+export class AsyncapiMergeError extends Error {
+    source;
+    service;
+    name = "AsyncapiMergeError";
+    constructor(source, service, detail, problem = "is not valid YAML") {
+        super(`${source} asyncapi for ${service} ${problem}: ${detail}`);
+        this.source = source;
+        this.service = service;
+    }
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=error.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../../src/core/asyncapi/merge/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAIhC,MAAM;IACN,OAAO;IAJA,IAAI,GAAG,oBAAoB,CAAC;IAE9C,YACW,MAA2B,EAC3B,OAAe,EACxB,MAAc,EACd,OAAO,GAAW,mBAAmB;QAErC,KAAK,CAAC,GAAG,MAAM,iBAAiB,OAAO,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC,CAAC;sBALxD,MAAM;uBACN,OAAO;IAKlB,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC","sourcesContent":["/**\n * The one refusal every stage of the event-contract delta path raises: a\n * document the planner cannot read, named by which side it came from.\n *\n * The mirror of ../../openapi/merge/error.ts, and the package's leaf for the\n * same reason: whichever sibling fails — the pin, the markers or the merge —\n * the command above has to map one domain error onto its own envelope, and a\n * module that owned the error would be imported by its siblings for that\n * reason alone.\n */\n\nexport type AsyncapiMergeSource = \"feature\" | \"living\";\n\n/**\n * A document the merge machinery cannot use. Commands map this domain error\n * to their own envelope. `problem` is the verb phrase between the document's\n * name and the detail — \"is not valid YAML\" for the parse failures that are\n * the common case, overridden where the document parses fine and the refusal\n * is about what it says (a section spelling one slot key twice is legal YAML,\n * and calling it invalid would send the author to a linter that agrees with\n * the file).\n */\nexport class AsyncapiMergeError extends Error {\n  override readonly name = \"AsyncapiMergeError\";\n\n  constructor(\n    readonly source: AsyncapiMergeSource,\n    readonly service: string,\n    detail: string,\n    problem: string = \"is not valid YAML\",\n  ) {\n    super(`${source} asyncapi for ${service} ${problem}: ${detail}`);\n  }\n}\n\nexport function errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"]}

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

@@ -0,0 +1,308 @@
+/**
+ * The keys loam adds to a feature's event contract that must never reach the
+ * living one: `x-loam-based-on`, `x-loam-remove`, and the root
+ * `x-loam-baselines` record — the same three spellings the OpenAPI axis
+ * strips, gathered here for the same reason its markers
+ * module exists: `stripAsyncapiMarkers` takes them out for the create branch
+ * that publishes a feature document verbatim, and the merge takes them out
+ * again on the way into a living document. Two spellings of "which keys are
+ * feature-only" is how one of the two starts leaking a marker.
+ *
+ * The strip is DEEP, and it covers the WHOLE document. Deep by the format
+ * spec's own decision: an inline channel message (`channels.<ck>.messages.<mk>`)
+ * is channel-slot interior, so a pin or marker nested on it is part of the
+ * channel's VALUE — the slot walker never visits it, and a slot-level strip
+ * would publish it into the fleet's living contract exactly the way
+ * `--approve` once published `x-loam-remove: true` inside a living OpenAPI
+ * component. Whole-document because the create branch publishes this text
+ * VERBATIM: a marker at the document root or a pin under `info` sits outside
+ * every section, and a strip that walked only the three sections shipped
+ * both into a living contract, unseen even by validate's marker sweep.
+ */
+import { isMap, isScalar, parseDocument } from "yaml";
+// Every `isRecord` below asks one question of a resolved plain tree: is this a
+// node that can hold AsyncAPI keys — an object, not an array?
+import { isRecord } from "../../kernel/records.js";
+// One spelling of the deep strip for both axes: the feature-only keys are the
+// SAME two strings on either (core/asyncapi/digest.ts aliases the constants
+// outright), so a drift between the strips would be two definitions of one
+// rule (the openapi digest module's own failure mode).
+import { FEATURE_ONLY_KEYS, withoutFeatureKeysDeep } from "../../openapi/digest.js";
+import { ASYNCAPI_BASELINES_KEY, isSlotRemoval } from "../digest.js";
+import { errorMessage, AsyncapiMergeError } from "./error.js";
+/** The three slot sections, in document order — every whole-document walk here goes over them. */
+const SECTIONS = ["channels", "operations", "components.messages"];
+/**
+ * A slot's PUBLISHABLE value: every feature-only key removed, at any depth —
+ * the top-level pin, a nested pin or marker on an inline channel message, and
+ * anything an author buried deeper. What the merge writes and what the create
+ * branch keeps; a removal-marker slot is never published at all (the merge
+ * deletes its target, the strip drops it), so this is only ever asked of a
+ * slot that survives.
+ */
+export function withoutFeatureMarkers(node) {
+    return withoutFeatureKeysDeep(node);
+}
+/**
+ * The AST path of a section's own mapping — `slotPath` (../digest.ts) minus
+ * the slot key, spelled beside the writers so the strip and the merge cannot
+ * disagree about which node a section name addresses.
+ */
+export function sectionAstPath(section) {
+    return section === "components.messages" ? ["components", "messages"] : [section];
+}
+/** One mapping node's pair for a key, matched AS A STRING — `slotPair`'s find, reusable at any depth. */
+function pairAt(node, key) {
+    return isMap(node) ? node.items.find((it) => isScalar(it.key) && String(it.key.value) === key) : undefined;
+}
+/** Delete one pair from a mapping node, string-key-matched. Returns whether a pair actually went. */
+function deleteKeyIn(node, key) {
+    if (!isMap(node))
+        return false;
+    const at = node.items.findIndex((it) => isScalar(it.key) && String(it.key.value) === key);
+    if (at < 0)
+        return false;
+    node.items.splice(at, 1);
+    return true;
+}
+/**
+ * Find one slot's key/value pair, matching the existing key AS A STRING: a
+ * channel named `404:` is the YAML number 404, and a plain `getIn`/`setIn`
+ * with the string "404" misses it and APPENDS a second pair — the living
+ * contract then declares the slot twice, forever, with the pre-merge copy
+ * first in reading order. The openapi component write's lesson, applied to
+ * every slot access on this axis: the merge's writers below go through it,
+ * and so does the pin (./pin.ts), whose raw `getIn` used to grade every
+ * non-string-keyed slot `unwritable` with an alias diagnosis nothing in the
+ * document backed.
+ */
+export function slotPair(doc, section, key) {
+    return pairAt(doc.getIn(sectionAstPath(section)), key);
+}
+/** Write one slot's value, string-key-matched — the merge's one upsert door. */
+export function setSlotValue(doc, section, key, value) {
+    const existing = slotPair(doc, section, key);
+    if (existing !== undefined)
+        existing.value = doc.createNode(value);
+    else
+        doc.setIn([...sectionAstPath(section), key], value);
+}
+/**
+ * Delete one slot's pair, string-key-matched for the numeric-key reason above
+ * (`deleteIn` with "404" reports nothing deleted and the slot survives in
+ * silence). Returns whether a pair actually went.
+ */
+export function deleteSlot(doc, section, key) {
+    return deleteKeyIn(doc.getIn(sectionAstPath(section)), key);
+}
+/**
+ * Refuse a living container the merge cannot write into: a container spelled
+ * as something other than a mapping is a document loam cannot merge, and one
+ * spelled as a YAML alias would take the write into every node that shares
+ * the anchor. Asked at the WRITE, because reading is safe and writing is not
+ * — an absent container is fine, the writers above create it.
+ *
+ * Takes a raw path rather than an `AsyncapiSection`, because the merge writes
+ * outside the three slot sections too: a component surface lands at
+ * `["components", <kind>]`, and a section-typed guard simply could not be
+ * asked about it. Skipping the question there would let a living
+ * `components: *alias` take a surface write into every node sharing the
+ * anchor — the exact corruption this function exists to refuse, at the one
+ * depth it could not see. Lives beside the writers rather than in the merge
+ * so the guard and the write cannot disagree about which node a path names.
+ */
+export function writableSection(living, livingPlain, path, service) {
+    for (let depth = 1; depth <= path.length; depth += 1) {
+        const prefix = path.slice(0, depth);
+        const plain = prefix.reduce((node, step) => (isRecord(node) ? node[step] : undefined), livingPlain);
+        if (plain === undefined || plain === null)
+            return;
+        const label = prefix.join(".");
+        if (!isRecord(plain)) {
+            throw new AsyncapiMergeError("living", service, `'${label}' is not a mapping`);
+        }
+        if (!isMap(living.getIn(prefix))) {
+            throw new AsyncapiMergeError("living", service, `'${label}' is written as a YAML alias — one shared value backs every use, so merging into it would rewrite every other node that aliases it. Expand it before archiving.`);
+        }
+    }
+}
+/** One slot's human label: `channels.<key>` — with the message's join name where it has one. */
+export function slotLabel(section, key, name) {
+    const at = `${section}.${key}`;
+    return name !== undefined && name !== key ? `'${name}' (${at})` : at;
+}
+/**
+ * Refuse a document whose section spells one slot key twice — `channels:
+ * {404: …, "404": …}` is legal YAML (a number and a string are distinct
+ * keys), but the resolved walk (`asyncapiSlots` reads `Object.entries` of
+ * `toJS()`) keeps the LAST pair while every string-matched AST access above
+ * finds the FIRST: the walker would grade one pair and the writer replace
+ * the other, and no single read discipline can make the two agree about
+ * which node the (section, key) names. Every entry point that walks slots —
+ * the pin, the strip, the merge — refuses it by name instead of writing
+ * through the wrong pair.
+ */
+export function refuseAmbiguousSlotKeys(doc, source, service) {
+    for (const section of SECTIONS) {
+        const node = doc.getIn(sectionAstPath(section));
+        if (!isMap(node))
+            continue;
+        const seen = new Set();
+        for (const it of node.items) {
+            if (!isScalar(it.key))
+                continue;
+            const key = String(it.key.value);
+            if (seen.has(key)) {
+                throw new AsyncapiMergeError(source, service, `'${section}' spells the key '${key}' in two pairs (two YAML scalars that stringify identically, e.g. 404 and "404") — loam cannot tell which pair a slot access should read or write; merge them into one entry`, "is ambiguous");
+            }
+            seen.add(key);
+        }
+    }
+}
+/**
+ * Remove feature-only markers — removal-marker slots, the pins on the slots
+ * that survive, and both loam keys at every nested depth of the whole
+ * document — 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.
+ *
+ * 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 editing
+ * a slot through it would change every use), and a slot whose KEY is not a
+ * scalar is not findable by name at all — so a section holding either gets
+ * rewritten from the resolved tree instead: losing formatting is a cost,
+ * shipping the marker is a corruption. The openapi strip's two-branch
+ * discipline, per section.
+ */
+export function stripAsyncapiMarkers(featureText, service) {
+    const feature = parseDocument(featureText);
+    if (feature.errors.length > 0) {
+        throw new AsyncapiMergeError("feature", service, feature.errors[0].message);
+    }
+    refuseAmbiguousSlotKeys(feature, "feature", service);
+    let plain;
+    try {
+        // Resolve aliases once with the document's own anchor context — an
+        // individual node's toJSON() loses it (the openapi merge's lesson).
+        plain = feature.toJS() ?? {};
+    }
+    catch (error) {
+        throw new AsyncapiMergeError("feature", service, errorMessage(error));
+    }
+    let stripped = false;
+    for (const section of SECTIONS) {
+        // Shape from the RESOLVED tree, for the same reason the merge reads it
+        // there: an aliased section is not a map node, and treating it as
+        // "nothing to strip" is how a feature-only marker reached a living
+        // contract on the OpenAPI axis.
+        const sectionPlain = sectionAstPath(section).reduce((node, step) => (isRecord(node) ? node[step] : undefined), plain);
+        if (!isRecord(sectionPlain))
+            continue;
+        const cleaned = {};
+        // `kept: undefined` means the slot goes — a resolved YAML value is never
+        // undefined itself (`~` reads as null), so the sentinel is unambiguous.
+        const edits = [];
+        for (const [key, value] of Object.entries(sectionPlain)) {
+            // A removal marker asserts a slot rather than declaring content; the
+            // create branch has no target to delete, so the slot itself goes.
+            const kept = isSlotRemoval(value) ? undefined : withoutFeatureKeysDeep(value);
+            if (kept !== value)
+                edits.push({ key, kept });
+            if (kept !== undefined)
+                cleaned[key] = kept;
+        }
+        if (edits.length === 0)
+            continue;
+        stripped = true;
+        // In place only when every touched node is reachable: the section is a
+        // real map and each edited slot's pair is findable by string key.
+        const editable = isMap(feature.getIn(sectionAstPath(section))) &&
+            edits.every(({ key }) => slotPair(feature, section, key) !== undefined);
+        if (!editable) {
+            feature.setIn(sectionAstPath(section), cleaned);
+            continue;
+        }
+        for (const { key, kept } of edits) {
+            if (kept === undefined)
+                deleteSlot(feature, section, key);
+            // The surviving slot's value is replaced wholesale with the deep-strip:
+            // a pin at slot depth could be deleted key-by-key, but a marker nested
+            // on an inline channel message sits where no fixed path reaches — the
+            // resolved copy is the one branch both depths share.
+            else
+                setSlotValue(feature, section, key, kept);
+        }
+    }
+    if (isRecord(plain))
+        stripped = stripBeyondSections(feature, plain) || stripped;
+    // The root `x-loam-baselines` record, on EVERY branch — including the
+    // verbatim early return below. `stripBeyondSections` cannot do it: it
+    // filters on FEATURE_ONLY_KEYS, which holds the two IN-VALUE keys and not
+    // this one, so the record's own subtree (16-hex digests) carries no loam key
+    // for the deep strip to find and the whole entry rides out untouched. That
+    // is the create branch publishing loam's bookkeeping into a living
+    // asyncapi.yaml, where nothing catches it: `removalMarkerPaths` — validate's
+    // marker sweep on this axis — only ever looks for `x-loam-remove`.
+    if (isRecord(plain) && ASYNCAPI_BASELINES_KEY in plain) {
+        feature.deleteIn([ASYNCAPI_BASELINES_KEY]);
+        stripped = true;
+    }
+    if (!stripped)
+        return featureText;
+    try {
+        return feature.toString();
+    }
+    catch (error) {
+        throw new AsyncapiMergeError("feature", service, errorMessage(error));
+    }
+}
+/**
+ * The strip's reach OUTSIDE the three sections: the document root's own
+ * keys, `info`, `servers`, and the `components` siblings of `messages` —
+ * everything the section loop above deliberately does not touch. A loam key
+ * here is feature-only exactly as it is inside a slot, and the create branch
+ * used to publish it (an `x-loam-remove: true` at the root reached a living
+ * contract with zero diagnosis). A loam key at this depth is deleted; any
+ * other entry whose subtree carries one is replaced with its deep-strip,
+ * through the same string-matched pair access the slot writers use.
+ */
+function stripBeyondSections(feature, plain) {
+    let stripped = false;
+    const strip = (path, key, value) => {
+        const parent = path.length === 0 ? feature.contents : feature.getIn(path);
+        if (FEATURE_ONLY_KEYS.has(key)) {
+            stripped = deleteKeyIn(parent, key) || stripped;
+            return;
+        }
+        const kept = withoutFeatureKeysDeep(value);
+        if (kept === value)
+            return;
+        stripped = true;
+        const pair = pairAt(parent, key);
+        // The section loop's fallback, one entry wide: a pair no string can find
+        // is rewritten from the resolved tree rather than left carrying markers.
+        if (pair !== undefined)
+            pair.value = feature.createNode(kept);
+        else
+            feature.setIn([...path, key], kept);
+    };
+    for (const [key, value] of Object.entries(plain)) {
+        if (key === "channels" || key === "operations")
+            continue;
+        if (key === "components") {
+            // `components.messages` is the section loop's; the siblings are ours.
+            if (!isRecord(value))
+                continue;
+            for (const [ck, cv] of Object.entries(value)) {
+                if (ck !== "messages")
+                    strip(["components"], ck, cv);
+            }
+            continue;
+        }
+        strip([], key, value);
+    }
+    return stripped;
+}
+//# sourceMappingURL=markers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../../../src/core/asyncapi/merge/markers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The keys loam adds to a feature's event contract that must never reach the\n * living one: `x-loam-based-on`, `x-loam-remove`, and the root\n * `x-loam-baselines` record — the same three spellings the OpenAPI axis\n * strips, gathered here for the same reason its markers\n * module exists: `stripAsyncapiMarkers` takes them out for the create branch\n * that publishes a feature document verbatim, and the merge takes them out\n * again on the way into a living document. Two spellings of \"which keys are\n * feature-only\" is how one of the two starts leaking a marker.\n *\n * The strip is DEEP, and it covers the WHOLE document. Deep by the format\n * spec's own decision: an inline channel message (`channels.<ck>.messages.<mk>`)\n * is channel-slot interior, so a pin or marker nested on it is part of the\n * channel's VALUE — the slot walker never visits it, and a slot-level strip\n * would publish it into the fleet's living contract exactly the way\n * `--approve` once published `x-loam-remove: true` inside a living OpenAPI\n * component. Whole-document because the create branch publishes this text\n * VERBATIM: a marker at the document root or a pin under `info` sits outside\n * every section, and a strip that walked only the three sections shipped\n * both into a living contract, unseen even by validate's marker sweep.\n */\nimport { isMap, isScalar, parseDocument, type Document, type Pair } from \"yaml\";\n// Every `isRecord` below asks one question of a resolved plain tree: is this a\n// node that can hold AsyncAPI keys — an object, not an array?\nimport { isRecord } from \"../../kernel/records.js\";\n// One spelling of the deep strip for both axes: the feature-only keys are the\n// SAME two strings on either (core/asyncapi/digest.ts aliases the constants\n// outright), so a drift between the strips would be two definitions of one\n// rule (the openapi digest module's own failure mode).\nimport { FEATURE_ONLY_KEYS, withoutFeatureKeysDeep } from \"../../openapi/digest.js\";\nimport { ASYNCAPI_BASELINES_KEY, isSlotRemoval, type AsyncapiSection } from \"../digest.js\";\nimport { errorMessage, AsyncapiMergeError, type AsyncapiMergeSource } from \"./error.js\";\n\n/** The three slot sections, in document order — every whole-document walk here goes over them. */\nconst SECTIONS: AsyncapiSection[] = [\"channels\", \"operations\", \"components.messages\"];\n\n/**\n * A slot's PUBLISHABLE value: every feature-only key removed, at any depth —\n * the top-level pin, a nested pin or marker on an inline channel message, and\n * anything an author buried deeper. What the merge writes and what the create\n * branch keeps; a removal-marker slot is never published at all (the merge\n * deletes its target, the strip drops it), so this is only ever asked of a\n * slot that survives.\n */\nexport function withoutFeatureMarkers(node: unknown): unknown {\n  return withoutFeatureKeysDeep(node);\n}\n\n/**\n * The AST path of a section's own mapping — `slotPath` (../digest.ts) minus\n * the slot key, spelled beside the writers so the strip and the merge cannot\n * disagree about which node a section name addresses.\n */\nexport function sectionAstPath(section: AsyncapiSection): string[] {\n  return section === \"components.messages\" ? [\"components\", \"messages\"] : [section];\n}\n\n/** One mapping node's pair for a key, matched AS A STRING — `slotPair`'s find, reusable at any depth. */\nfunction 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/** Delete one pair from a mapping node, string-key-matched. Returns whether a pair actually went. */\nfunction deleteKeyIn(node: unknown, key: string): boolean {\n  if (!isMap(node)) return false;\n  const at = node.items.findIndex((it) => isScalar(it.key) && String(it.key.value) === key);\n  if (at < 0) return false;\n  node.items.splice(at, 1);\n  return true;\n}\n\n/**\n * Find one slot's key/value pair, matching the existing key AS A STRING: a\n * channel named `404:` is the YAML number 404, and a plain `getIn`/`setIn`\n * with the string \"404\" misses it and APPENDS a second pair — the living\n * contract then declares the slot twice, forever, with the pre-merge copy\n * first in reading order. The openapi component write's lesson, applied to\n * every slot access on this axis: the merge's writers below go through it,\n * and so does the pin (./pin.ts), whose raw `getIn` used to grade every\n * non-string-keyed slot `unwritable` with an alias diagnosis nothing in the\n * document backed.\n */\nexport function slotPair(doc: Document, section: AsyncapiSection, key: string): Pair | undefined {\n  return pairAt(doc.getIn(sectionAstPath(section)), key);\n}\n\n/** Write one slot's value, string-key-matched — the merge's one upsert door. */\nexport function setSlotValue(doc: Document, section: AsyncapiSection, key: string, value: unknown): void {\n  const existing = slotPair(doc, section, key);\n  if (existing !== undefined) existing.value = doc.createNode(value);\n  else doc.setIn([...sectionAstPath(section), key], value);\n}\n\n/**\n * Delete one slot's pair, string-key-matched for the numeric-key reason above\n * (`deleteIn` with \"404\" reports nothing deleted and the slot survives in\n * silence). Returns whether a pair actually went.\n */\nexport function deleteSlot(doc: Document, section: AsyncapiSection, key: string): boolean {\n  return deleteKeyIn(doc.getIn(sectionAstPath(section)), key);\n}\n\n/**\n * Refuse a living container the merge cannot write into: a container spelled\n * as something other than a mapping is a document loam cannot merge, and one\n * spelled as a YAML alias would take the write into every node that shares\n * the anchor. Asked at the WRITE, because reading is safe and writing is not\n * — an absent container is fine, the writers above create it.\n *\n * Takes a raw path rather than an `AsyncapiSection`, because the merge writes\n * outside the three slot sections too: a component surface lands at\n * `[\"components\", <kind>]`, and a section-typed guard simply could not be\n * asked about it. Skipping the question there would let a living\n * `components: *alias` take a surface write into every node sharing the\n * anchor — the exact corruption this function exists to refuse, at the one\n * depth it could not see. Lives beside the writers rather than in the merge\n * so the guard and the write cannot disagree about which node a path names.\n */\nexport function writableSection(\n  living: Document,\n  livingPlain: unknown,\n  path: string[],\n  service: string,\n): void {\n  for (let depth = 1; depth <= path.length; depth += 1) {\n    const prefix = path.slice(0, depth);\n    const plain = prefix.reduce<unknown>((node, step) => (isRecord(node) ? node[step] : undefined), livingPlain);\n    if (plain === undefined || plain === null) return;\n    const label = prefix.join(\".\");\n    if (!isRecord(plain)) {\n      throw new AsyncapiMergeError(\"living\", service, `'${label}' is not a mapping`);\n    }\n    if (!isMap(living.getIn(prefix))) {\n      throw new AsyncapiMergeError(\n        \"living\",\n        service,\n        `'${label}' is written as a YAML alias — one shared value backs every use, so merging into it would rewrite every other node that aliases it. Expand it before archiving.`,\n      );\n    }\n  }\n}\n\n/** One slot's human label: `channels.<key>` — with the message's join name where it has one. */\nexport function slotLabel(section: AsyncapiSection, key: string, name?: string): string {\n  const at = `${section}.${key}`;\n  return name !== undefined && name !== key ? `'${name}' (${at})` : at;\n}\n\n/**\n * Refuse a document whose section spells one slot key twice — `channels:\n * {404: …, \"404\": …}` is legal YAML (a number and a string are distinct\n * keys), but the resolved walk (`asyncapiSlots` reads `Object.entries` of\n * `toJS()`) keeps the LAST pair while every string-matched AST access above\n * finds the FIRST: the walker would grade one pair and the writer replace\n * the other, and no single read discipline can make the two agree about\n * which node the (section, key) names. Every entry point that walks slots —\n * the pin, the strip, the merge — refuses it by name instead of writing\n * through the wrong pair.\n */\nexport function refuseAmbiguousSlotKeys(doc: Document, source: AsyncapiMergeSource, service: string): void {\n  for (const section of SECTIONS) {\n    const node = doc.getIn(sectionAstPath(section));\n    if (!isMap(node)) continue;\n    const seen = new Set<string>();\n    for (const it of node.items) {\n      if (!isScalar(it.key)) continue;\n      const key = String(it.key.value);\n      if (seen.has(key)) {\n        throw new AsyncapiMergeError(\n          source,\n          service,\n          `'${section}' spells the key '${key}' in two pairs (two YAML scalars that stringify identically, e.g. 404 and \"404\") — loam cannot tell which pair a slot access should read or write; merge them into one entry`,\n          \"is ambiguous\",\n        );\n      }\n      seen.add(key);\n    }\n  }\n}\n\n/**\n * Remove feature-only markers — removal-marker slots, the pins on the slots\n * that survive, and both loam keys at every nested depth of the whole\n * document — before a feature contract is used to create a brand-new living\n * document. Normally coherence refuses the removal shape because there cannot\n * be a removal target; this guard also keeps `--approve` from ever persisting\n * a marker into living docs.\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 editing\n * a slot through it would change every use), and a slot whose KEY is not a\n * scalar is not findable by name at all — so a section holding either gets\n * rewritten from the resolved tree instead: losing formatting is a cost,\n * shipping the marker is a corruption. The openapi strip's two-branch\n * discipline, per section.\n */\nexport function stripAsyncapiMarkers(featureText: string, service: string): string {\n  const feature = parseDocument(featureText);\n  if (feature.errors.length > 0) {\n    throw new AsyncapiMergeError(\"feature\", service, feature.errors[0]!.message);\n  }\n  refuseAmbiguousSlotKeys(feature, \"feature\", service);\n  let plain: unknown;\n  try {\n    // Resolve aliases once with the document's own anchor context — an\n    // individual node's toJSON() loses it (the openapi merge's lesson).\n    plain = feature.toJS() ?? {};\n  } catch (error) {\n    throw new AsyncapiMergeError(\"feature\", service, errorMessage(error));\n  }\n\n  let stripped = false;\n  for (const section of SECTIONS) {\n    // Shape from the RESOLVED tree, for the same reason the merge reads it\n    // there: an aliased section is not a map node, and treating it as\n    // \"nothing to strip\" is how a feature-only marker reached a living\n    // contract on the OpenAPI axis.\n    const sectionPlain = sectionAstPath(section).reduce<unknown>(\n      (node, step) => (isRecord(node) ? node[step] : undefined),\n      plain,\n    );\n    if (!isRecord(sectionPlain)) continue;\n\n    const cleaned: Record<string, unknown> = {};\n    // `kept: undefined` means the slot goes — a resolved YAML value is never\n    // undefined itself (`~` reads as null), so the sentinel is unambiguous.\n    const edits: Array<{ key: string; kept: unknown }> = [];\n    for (const [key, value] of Object.entries(sectionPlain)) {\n      // A removal marker asserts a slot rather than declaring content; the\n      // create branch has no target to delete, so the slot itself goes.\n      const kept = isSlotRemoval(value) ? undefined : withoutFeatureKeysDeep(value);\n      if (kept !== value) edits.push({ key, kept });\n      if (kept !== undefined) cleaned[key] = kept;\n    }\n    if (edits.length === 0) continue;\n    stripped = true;\n\n    // In place only when every touched node is reachable: the section is a\n    // real map and each edited slot's pair is findable by string key.\n    const editable =\n      isMap(feature.getIn(sectionAstPath(section))) &&\n      edits.every(({ key }) => slotPair(feature, section, key) !== undefined);\n    if (!editable) {\n      feature.setIn(sectionAstPath(section), cleaned);\n      continue;\n    }\n    for (const { key, kept } of edits) {\n      if (kept === undefined) deleteSlot(feature, section, key);\n      // The surviving slot's value is replaced wholesale with the deep-strip:\n      // a pin at slot depth could be deleted key-by-key, but a marker nested\n      // on an inline channel message sits where no fixed path reaches — the\n      // resolved copy is the one branch both depths share.\n      else setSlotValue(feature, section, key, kept);\n    }\n  }\n\n  if (isRecord(plain)) stripped = stripBeyondSections(feature, plain) || stripped;\n\n  // The root `x-loam-baselines` record, on EVERY branch — including the\n  // verbatim early return below. `stripBeyondSections` cannot do it: it\n  // filters on FEATURE_ONLY_KEYS, which holds the two IN-VALUE keys and not\n  // this one, so the record's own subtree (16-hex digests) carries no loam key\n  // for the deep strip to find and the whole entry rides out untouched. That\n  // is the create branch publishing loam's bookkeeping into a living\n  // asyncapi.yaml, where nothing catches it: `removalMarkerPaths` — validate's\n  // marker sweep on this axis — only ever looks for `x-loam-remove`.\n  if (isRecord(plain) && ASYNCAPI_BASELINES_KEY in plain) {\n    feature.deleteIn([ASYNCAPI_BASELINES_KEY]);\n    stripped = true;\n  }\n\n  if (!stripped) return featureText;\n  try {\n    return feature.toString();\n  } catch (error) {\n    throw new AsyncapiMergeError(\"feature\", service, errorMessage(error));\n  }\n}\n\n/**\n * The strip's reach OUTSIDE the three sections: the document root's own\n * keys, `info`, `servers`, and the `components` siblings of `messages` —\n * everything the section loop above deliberately does not touch. A loam key\n * here is feature-only exactly as it is inside a slot, and the create branch\n * used to publish it (an `x-loam-remove: true` at the root reached a living\n * contract with zero diagnosis). A loam key at this depth is deleted; any\n * other entry whose subtree carries one is replaced with its deep-strip,\n * through the same string-matched pair access the slot writers use.\n */\nfunction stripBeyondSections(feature: Document, plain: Record<string, unknown>): boolean {\n  let stripped = false;\n  const strip = (path: string[], key: string, value: unknown): void => {\n    const parent = path.length === 0 ? feature.contents : feature.getIn(path);\n    if (FEATURE_ONLY_KEYS.has(key)) {\n      stripped = deleteKeyIn(parent, key) || stripped;\n      return;\n    }\n    const kept = withoutFeatureKeysDeep(value);\n    if (kept === value) return;\n    stripped = true;\n    const pair = pairAt(parent, key);\n    // The section loop's fallback, one entry wide: a pair no string can find\n    // is rewritten from the resolved tree rather than left carrying markers.\n    if (pair !== undefined) pair.value = feature.createNode(kept);\n    else feature.setIn([...path, key], kept);\n  };\n  for (const [key, value] of Object.entries(plain)) {\n    if (key === \"channels\" || key === \"operations\") continue;\n    if (key === \"components\") {\n      // `components.messages` is the section loop's; the siblings are ours.\n      if (!isRecord(value)) continue;\n      for (const [ck, cv] of Object.entries(value)) {\n        if (ck !== \"messages\") strip([\"components\"], ck, cv);\n      }\n      continue;\n    }\n    strip([], key, value);\n  }\n  return stripped;\n}\n"]}

package/dist/core/asyncapi/merge/merge.js

@@ -0,0 +1,215 @@
+/**
+ * The archive-time merge on the event axis: a feature's asyncapi delta folded
+ * into the living contract, and every condition the caller has to surface
+ * afterwards — the OpenAPI merge's shape, slot-keyed instead of path-keyed.
+ *
+ * The result type carries far more than the merged text on purpose. A merge
+ * that quietly overwrote a slot, deleted a message, or ran against a stale
+ * baseline is not an error — it is a fact the archiving human has to be told,
+ * and a return value nobody can forget to read is the only place that
+ * survives a refactor.
+ *
+ * Every SHAPE question — which slots does the feature declare, what does the
+ * living contract hold at a (section, key) — is answered from the RESOLVED
+ * plain trees, never from the AST node: an alias node is not a map even when
+ * it resolves to one, and reading it as absent is how the OpenAPI merge once
+ * dropped whole contract deltas. The WRITES walk the AST, string-key-matched,
+ * and refuse aliases — one shared value backs every use of an anchor, so
+ * writing through one would rewrite every other node that aliases it.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { isMap, parseDocument } from "yaml";
+import { classifyBaselineDigests } from "../../openapi/digest.js";
+import { asyncapiSlots, slotDigest } from "../digest.js";
+import { danglingRefs } from "../depth.js";
+import { messageName } from "../read.js";
+import { readBaselineRecord } from "../../openapi/baseline/record.js";
+import { asyncapiSurfaces } from "../baseline/surfaces.js";
+import { errorMessage, AsyncapiMergeError } from "./error.js";
+import { mergeAsyncapiComponents } from "./components.js";
+import { deleteSlot, refuseAmbiguousSlotKeys, sectionAstPath, setSlotValue, slotLabel, withoutFeatureMarkers, writableSection, } from "./markers.js";
+/**
+ * Merge the feature's slots into the living AsyncAPI structurally (YAML AST,
+ * not text splicing). A feature document restating NOTHING — neither a slot
+ * nor a component surface — is a successful no-op; one whose whole delta is a
+ * `components.schemas` entry is merged like any other, through
+ * `mergeAsyncapiComponents` at the end of this function. Per slot, the pin
+ * decides: a QUOTE is never a merge input — not even
+ * under `--approve`, because overriding a gate is a decision and reverting a
+ * slot nobody edited is a bug — while `stale` still writes, since reaching
+ * the merge at all means `--approve` said to. A removal marker deletes its
+ * exact target and the section key when the section empties; everything
+ * published goes through the deep marker strip.
+ */
+export function mergeAsyncapiSlots(livingText, featureText, service) {
+    const feature = parseDocument(featureText);
+    if (feature.errors.length > 0) {
+        throw new AsyncapiMergeError("feature", service, feature.errors[0].message);
+    }
+    // Two pairs whose keys stringify identically (404 and "404") would make
+    // the resolved walk and the string-matched writers disagree about which
+    // node a slot names — refused on either side, before any verdict is taken.
+    refuseAmbiguousSlotKeys(feature, "feature", service);
+    let featPlain;
+    try {
+        // Resolve aliases once with the document's own anchor context. Calling an
+        // individual AST node's toJSON() loses that context and can silently turn
+        // an aliased slot into the wrong value.
+        featPlain = feature.toJS() ?? {};
+    }
+    catch (error) {
+        throw new AsyncapiMergeError("feature", service, errorMessage(error));
+    }
+    const featSlots = asyncapiSlots(featPlain);
+    // "Is there anything to merge?" is a question about the WHOLE delta, and it
+    // was asked of the three slot sections alone — an absence test standing in
+    // for the decision. It returned before the living document was even parsed,
+    // so `mergeAsyncapiComponents` (the last thing this function does, and the
+    // only thing that writes a component surface) never ran: a feature whose
+    // entire change was a `components.schemas` entry passed the gate and
+    // archived at exit 0 having merged NOTHING. The surfaces answer it too now,
+    // over the ONE enumeration the gate and the rebase plan already grade the
+    // delta with. Deleting the early return alone would have changed nothing:
+    // there was no writer outside the slot loop to fall through to.
+    if (featSlots.length === 0 && asyncapiSurfaces(featPlain).length === 0)
+        return noop();
+    const living = parseDocument(livingText);
+    if (living.errors.length > 0) {
+        throw new AsyncapiMergeError("living", service, living.errors[0].message);
+    }
+    refuseAmbiguousSlotKeys(living, "living", service);
+    let livingPlain;
+    try {
+        livingPlain = living.toJS() ?? {};
+    }
+    catch (error) {
+        throw new AsyncapiMergeError("living", service, errorMessage(error));
+    }
+    const livingBySlot = new Map(asyncapiSlots(livingPlain).map((slot) => [`${slot.section}\0${slot.key}`, slot]));
+    // Read ONCE here, not per surface: `problems` are deliberately ignored — a
+    // malformed record is the gate's diagnosis (`asyncapi.baseline-invalid`) and
+    // a parser never prints, so what reaches the surface merge is whatever read
+    // back cleanly, and an entry that did not is simply absent (= unpinned).
+    const { record } = readBaselineRecord(featPlain);
+    const modified = [];
+    const removed = [];
+    const quoted = [];
+    const baselineStale = [];
+    const touched = new Set();
+    let edited = false;
+    for (const slot of featSlots) {
+        const before = livingBySlot.get(`${slot.section}\0${slot.key}`);
+        const name = slot.section === "components.messages" ? messageName(slot.node, slot.key) : undefined;
+        const at = { section: slot.section, label: slotLabel(slot.section, slot.key, name) };
+        if (slot.remove) {
+            // Coherence validates the marker and gates absent/mismatched targets.
+            // The merge remains defensive under --approve: never delete a different
+            // message merely because it occupies the requested slot. Channel and
+            // operation identity IS the key, so presence is the whole match there.
+            if (before === undefined)
+                continue;
+            if (slot.section === "components.messages" && messageName(before.node, slot.key) !== name)
+                continue;
+            writableSection(living, livingPlain, sectionAstPath(slot.section), service);
+            if (deleteSlot(living, slot.section, slot.key)) {
+                removed.push(at);
+                touched.add(slot.section);
+                edited = true;
+            }
+            continue;
+        }
+        const verdict = classifyBaselineDigests(slot.basedOn, slot.digest, before === undefined ? undefined : slotDigest(before.node));
+        // A QUOTE is not a merge input. The author wrote this slot down because
+        // the document is complete, not because they changed it, so the living
+        // contract keeps whatever it holds — including a change that landed after
+        // this delta was written. Mechanical, not a judgement: `--approve` does
+        // not turn it back on.
+        if (verdict === "quote") {
+            quoted.push(at);
+            continue;
+        }
+        if (verdict === "stale")
+            baselineStale.push(at);
+        const publish = withoutFeatureMarkers(slot.node);
+        // An unpinned restatement equal to the living slot has nothing to write —
+        // the component closure's rule, kept here so a never-rebased delta that
+        // merely restates the contract does not churn its bytes.
+        if (before !== undefined && isDeepStrictEqual(before.node, publish))
+            continue;
+        if (before !== undefined)
+            modified.push(at);
+        writableSection(living, livingPlain, sectionAstPath(slot.section), service);
+        // Without the strip the living contract would grow a pin to a version of
+        // itself — and, on this axis, a marker nested on an inline channel
+        // message, invisible to the slot walker (SCHEMA.md's channel-interior
+        // decision: the strip works at that nested depth exactly as at slot depth).
+        setSlotValue(living, slot.section, slot.key, publish);
+        edited = true;
+    }
+    // Removing the last slot leaves a section the contract still spells and
+    // nothing declares — delete the emptied mapping, and `components` too when
+    // the messages were all it held. After the whole loop, so a removal and an
+    // upsert into one section never race the cleanup.
+    for (const section of touched) {
+        const node = living.getIn(sectionAstPath(section));
+        if (!isMap(node) || node.items.length > 0)
+            continue;
+        living.deleteIn(sectionAstPath(section));
+        if (section === "components.messages") {
+            const components = living.getIn(["components"]);
+            if (isMap(components) && components.items.length === 0)
+                living.deleteIn(["components"]);
+        }
+    }
+    // The surface half, after the slot loop and its section cleanup so a write
+    // outside the three sections can never race them. `edited` has to take the
+    // closure's answer: without it the verdicts below would be computed and
+    // reported while the `!edited` return discarded the document they were
+    // computed over — the defect surviving in a new shape, with the plan naming
+    // a schema that never reached the living contract.
+    const surfaces = mergeAsyncapiComponents({ living, featPlain, livingPlain, record, service });
+    const { componentsModified, componentsQuoted, componentsStale } = surfaces;
+    if (surfaces.copied)
+        edited = true;
+    // Nothing written: the living document must not even be re-serialized —
+    // byte-identity under an all-quote delta is the whole point of the pin.
+    if (!edited) {
+        return {
+            text: null, modified, removed, quoted, baselineStale,
+            componentsModified, componentsQuoted, componentsStale, unresolved: [],
+        };
+    }
+    let mergedPlain;
+    let text;
+    try {
+        mergedPlain = living.toJS() ?? {};
+        text = living.toString();
+    }
+    catch (error) {
+        throw new AsyncapiMergeError("living", service, errorMessage(error));
+    }
+    // The ref sweep grades what the MERGE would leave dangling: a merged slot
+    // pointing at something neither document defines, or a removal that took a
+    // target the living document still references. Refs already dangling in the
+    // living contract are validate's finding (asyncapi.ref-unresolved, warn),
+    // not this feature's doing — gating the archive on pre-existing rot would
+    // block every delta over an already-rotten contract.
+    const preexisting = new Set(danglingRefs(livingPlain));
+    const unresolved = danglingRefs(mergedPlain).filter((ref) => !preexisting.has(ref));
+    return {
+        text, modified, removed, quoted, baselineStale,
+        componentsModified, componentsQuoted, componentsStale, unresolved,
+    };
+}
+/**
+ * The successful "the feature document restates nothing at all" answer. Every
+ * key of the result is spelled here, empty, rather than left off — the reason
+ * `AsyncapiMergeResult` gives for the three surface fields.
+ */
+function noop() {
+    return {
+        text: null, modified: [], removed: [], quoted: [], baselineStale: [],
+        componentsModified: [], componentsQuoted: [], componentsStale: [], unresolved: [],
+    };
+}
+//# sourceMappingURL=merge.js.map