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

package/dist/core/asyncapi/baseline/plan.js

@@ -0,0 +1,110 @@
+/**
+ * What `loam rebase` writes on the event axis's SURFACE half: the
+ * `x-loam-baselines` record, rebuilt wholesale from what is on disk right now
+ * — `core/openapi/baseline/plan.ts`'s mirror, over component surfaces instead
+ * of path items and components.
+ *
+ * A ROOT record rather than an in-value pin, and that is not symmetry for its
+ * own sake: a slot value is always a mapping, so `x-loam-based-on` has
+ * somewhere to live inside it, but a `components/schemas/<name>` value is a
+ * JSON Schema — where an in-value loam key would be a schema keyword, and
+ * where JSON Schema's own `true` is a legal component that no in-value key
+ * survives at all.
+ *
+ * Rebuilt rather than patched for the reason the OpenAPI plan states: a pin is
+ * a claim about what its author read, and an entry left behind for a surface
+ * the delta no longer declares — or one whose living counterpart is gone — is
+ * a claim nobody is making any more. The sorted serialization (`buildRecord`)
+ * is what makes a second run byte-identical.
+ *
+ * This module must not import from `../merge/`: the merge reads this package,
+ * so a value edge back would be a package cycle. That is also why an
+ * unreadable document is answered with "nothing to pin" rather than an
+ * `AsyncapiMergeError` — every caller chains this AFTER `pinAsyncapiSlots`,
+ * which has already thrown that error for a document either side cannot parse.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { parseDocument } from "yaml";
+import { isRecord } from "../../kernel/records.js";
+import { buildRecord, entryFor, readBaselineRecord, surfaceIn } from "../../openapi/baseline/record.js";
+import { valueDigest } from "../../openapi/digest.js";
+import { ASYNCAPI_BASELINES_KEY } from "../digest.js";
+import { asyncapiSurfaces } from "./surfaces.js";
+/**
+ * Pin every component surface of a feature event contract against the living
+ * one. The entry is always `valueDigest` of the LIVING value, never of the
+ * delta's own — the one rule that yields both merge verdicts: a surface the
+ * author only QUOTED equals its own entry, one they EDITED differs from it.
+ *
+ * A surface with no living counterpart is `unresolved` and deliberately absent
+ * from the record. Stamping a pin against nothing is not a harmless extra key:
+ * `classifyBaselineDigests` calls a pin with no living side `unfounded`, and
+ * the gate then refuses the delta as `asyncapi.baseline-invalid` — rebase
+ * would be writing the file the gate sends its author back to rebase.
+ */
+export function planAsyncapiBaselines(featureText, livingText, _service) {
+    const doc = parseDocument(featureText);
+    if (doc.errors.length > 0)
+        return { text: null, pins: [] };
+    let featPlain;
+    let livingPlain;
+    try {
+        featPlain = doc.toJS() ?? {};
+        const living = parseDocument(livingText);
+        if (living.errors.length > 0)
+            return { text: null, pins: [] };
+        livingPlain = living.toJS() ?? {};
+    }
+    catch {
+        return { text: null, pins: [] };
+    }
+    const current = readBaselineRecord(featPlain).record;
+    const components = new Map();
+    const pins = [];
+    for (const surface of asyncapiSurfaces(featPlain)) {
+        // A malformed current entry reads back as absent (readBaselineRecord drops
+        // it into `problems`), so this run reports `pinned` and overwrites it —
+        // rebase is the command `asyncapi.baseline-invalid` sends people to, and
+        // it must repair what it names.
+        const from = entryFor(current, surface);
+        const livingValue = surfaceIn(livingPlain, surface);
+        if (!livingValue.found) {
+            pins.push({ target: surface.id, status: "unresolved", from: from ?? null, to: null });
+            continue;
+        }
+        const digest = valueDigest(livingValue.value);
+        components.set(surface.id, digest);
+        pins.push({
+            target: surface.id,
+            status: from === digest ? "unchanged" : from === undefined ? "pinned" : "repinned",
+            from: from ?? null,
+            to: digest,
+        });
+    }
+    // The whole key goes when no section survives — a bare `x-loam-baselines:
+    // {}` would be bookkeeping about nothing, in every delta whose surfaces are
+    // all new. `buildRecord` is the OpenAPI axis's sorted writer, given an empty
+    // `pathItems`: an AsyncAPI document has no path items, and the section it
+    // would write is dropped below with every other empty one.
+    const rebuilt = buildRecord({ pathItems: new Map(), components });
+    const written = {};
+    if (Object.keys(rebuilt.components).length > 0)
+        written["components"] = rebuilt.components;
+    const raw = isRecord(featPlain) ? featPlain[ASYNCAPI_BASELINES_KEY] : undefined;
+    if (Object.keys(written).length === 0) {
+        if (raw === undefined)
+            return { text: null, pins };
+        doc.deleteIn([ASYNCAPI_BASELINES_KEY]);
+        return { text: doc.toString(), pins };
+    }
+    // Deep-equal, not byte-equal: the comparison must ignore key order exactly
+    // as the digests do, so a record an author reordered by hand is left in
+    // their order — and a second run over this function's own sorted output
+    // finds the parse equal and writes nothing, which is the byte-for-byte
+    // idempotence `loam rebase` promises.
+    if (isDeepStrictEqual(raw, written))
+        return { text: null, pins };
+    doc.setIn([ASYNCAPI_BASELINES_KEY], written);
+    return { text: doc.toString(), pins };
+}
+//# sourceMappingURL=plan.js.map

package/dist/core/asyncapi/baseline/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../src/core/asyncapi/baseline/plan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `loam rebase` writes on the event axis's SURFACE half: the\n * `x-loam-baselines` record, rebuilt wholesale from what is on disk right now\n * — `core/openapi/baseline/plan.ts`'s mirror, over component surfaces instead\n * of path items and components.\n *\n * A ROOT record rather than an in-value pin, and that is not symmetry for its\n * own sake: a slot value is always a mapping, so `x-loam-based-on` has\n * somewhere to live inside it, but a `components/schemas/<name>` value is a\n * JSON Schema — where an in-value loam key would be a schema keyword, and\n * where JSON Schema's own `true` is a legal component that no in-value key\n * survives at all.\n *\n * Rebuilt rather than patched for the reason the OpenAPI plan states: a pin is\n * a claim about what its author read, and an entry left behind for a surface\n * the delta no longer declares — or one whose living counterpart is gone — is\n * a claim nobody is making any more. The sorted serialization (`buildRecord`)\n * is what makes a second run byte-identical.\n *\n * This module must not import from `../merge/`: the merge reads this package,\n * so a value edge back would be a package cycle. That is also why an\n * unreadable document is answered with \"nothing to pin\" rather than an\n * `AsyncapiMergeError` — every caller chains this AFTER `pinAsyncapiSlots`,\n * which has already thrown that error for a document either side cannot parse.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { parseDocument } from \"yaml\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport { buildRecord, entryFor, readBaselineRecord, surfaceIn } from \"../../openapi/baseline/record.js\";\nimport { valueDigest } from \"../../openapi/digest.js\";\nimport { ASYNCAPI_BASELINES_KEY } from \"../digest.js\";\nimport { asyncapiSurfaces } from \"./surfaces.js\";\n\n/** What happened to one declared surface's baseline entry. */\nexport interface AsyncapiSurfacePin {\n  /** `<kind>/<name>` — the component surface the entry pins. */\n  target: string;\n  status:\n    /** It had no entry and now has one. */\n    | \"pinned\"\n    /** It named an older living version; it now names the current one. */\n    | \"repinned\"\n    /** It already named the current living version — no write. */\n    | \"unchanged\"\n    /** The living contract has no such surface: this feature is adding it, and it gets NO entry. */\n    | \"unresolved\";\n  from: string | null;\n  to: string | null;\n}\n\nexport interface AsyncapiBaselinePlan {\n  /** The rewritten contract, or null when the record already says what this run would write. */\n  text: string | null;\n  pins: AsyncapiSurfacePin[];\n}\n\n/**\n * Pin every component surface of a feature event contract against the living\n * one. The entry is always `valueDigest` of the LIVING value, never of the\n * delta's own — the one rule that yields both merge verdicts: a surface the\n * author only QUOTED equals its own entry, one they EDITED differs from it.\n *\n * A surface with no living counterpart is `unresolved` and deliberately absent\n * from the record. Stamping a pin against nothing is not a harmless extra key:\n * `classifyBaselineDigests` calls a pin with no living side `unfounded`, and\n * the gate then refuses the delta as `asyncapi.baseline-invalid` — rebase\n * would be writing the file the gate sends its author back to rebase.\n */\nexport function planAsyncapiBaselines(\n  featureText: string,\n  livingText: string,\n  _service: string,\n): AsyncapiBaselinePlan {\n  const doc = parseDocument(featureText);\n  if (doc.errors.length > 0) return { text: null, pins: [] };\n  let featPlain: unknown;\n  let livingPlain: unknown;\n  try {\n    featPlain = doc.toJS() ?? {};\n    const living = parseDocument(livingText);\n    if (living.errors.length > 0) return { text: null, pins: [] };\n    livingPlain = living.toJS() ?? {};\n  } catch {\n    return { text: null, pins: [] };\n  }\n\n  const current = readBaselineRecord(featPlain).record;\n  const components = new Map<string, string>();\n  const pins: AsyncapiSurfacePin[] = [];\n  for (const surface of asyncapiSurfaces(featPlain)) {\n    // A malformed current entry reads back as absent (readBaselineRecord drops\n    // it into `problems`), so this run reports `pinned` and overwrites it —\n    // rebase is the command `asyncapi.baseline-invalid` sends people to, and\n    // it must repair what it names.\n    const from = entryFor(current, surface);\n    const livingValue = surfaceIn(livingPlain, surface);\n    if (!livingValue.found) {\n      pins.push({ target: surface.id, status: \"unresolved\", from: from ?? null, to: null });\n      continue;\n    }\n    const digest = valueDigest(livingValue.value);\n    components.set(surface.id, digest);\n    pins.push({\n      target: surface.id,\n      status: from === digest ? \"unchanged\" : from === undefined ? \"pinned\" : \"repinned\",\n      from: from ?? null,\n      to: digest,\n    });\n  }\n\n  // The whole key goes when no section survives — a bare `x-loam-baselines:\n  // {}` would be bookkeeping about nothing, in every delta whose surfaces are\n  // all new. `buildRecord` is the OpenAPI axis's sorted writer, given an empty\n  // `pathItems`: an AsyncAPI document has no path items, and the section it\n  // would write is dropped below with every other empty one.\n  const rebuilt = buildRecord({ pathItems: new Map(), components });\n  const written: Record<string, unknown> = {};\n  if (Object.keys(rebuilt.components).length > 0) written[\"components\"] = rebuilt.components;\n  const raw = isRecord(featPlain) ? featPlain[ASYNCAPI_BASELINES_KEY] : undefined;\n  if (Object.keys(written).length === 0) {\n    if (raw === undefined) return { text: null, pins };\n    doc.deleteIn([ASYNCAPI_BASELINES_KEY]);\n    return { text: doc.toString(), pins };\n  }\n  // Deep-equal, not byte-equal: the comparison must ignore key order exactly\n  // as the digests do, so a record an author reordered by hand is left in\n  // their order — and a second run over this function's own sorted output\n  // finds the parse equal and writes nothing, which is the byte-for-byte\n  // idempotence `loam rebase` promises.\n  if (isDeepStrictEqual(raw, written)) return { text: null, pins };\n  doc.setIn([ASYNCAPI_BASELINES_KEY], written);\n  return { text: doc.toString(), pins };\n}\n"]}

package/dist/core/asyncapi/baseline/surfaces.js

@@ -0,0 +1,54 @@
+/**
+ * The values a feature event contract restates that the SLOT pin cannot reach:
+ * every `components/<kind>/<name>` outside `messages`.
+ *
+ * A package of its own rather than a sixth file in `core/asyncapi/` — that
+ * directory is exactly at the five-file limit — and a separate ENUMERATION
+ * from the OpenAPI axis's `restatedSurfaces` rather than an import of it,
+ * although the two are the same shape. `restatedSurfaces` walks `paths` (a key
+ * an AsyncAPI document does not have) and includes `components/messages`,
+ * which on this axis is a SLOT: a message pinned both in-value by
+ * `x-loam-based-on` and by a root record entry would have two identities, and
+ * the merge would classify it twice — once as a slot, once as a surface — with
+ * verdicts that need not agree. What IS shared is everything downstream of the
+ * enumeration: `readBaselineRecord`, `entryFor`, `surfaceIn` and the record's
+ * `components` half are axis-neutral, so the record means the same thing on
+ * both axes and only the walk that fills it differs.
+ *
+ * Import direction is asyncapi → openapi, as core/asyncapi/digest.ts's header
+ * states; nothing under core/openapi/ imports this package.
+ */
+import { isRecord } from "../../kernel/records.js";
+import { FEATURE_ONLY_KEYS } from "../../openapi/digest.js";
+/**
+ * Every component surface a plain-parsed feature document declares, in
+ * document order.
+ *
+ * `messages` is skipped because it is the third slot section (core/asyncapi/
+ * digest.ts): a message carries its own in-value pin, and giving it a root
+ * record entry as well would be two pins on one value. The feature-only keys
+ * are skipped in the KIND position because `components: {x-loam-remove: true,
+ * schemas: {…}}` is bookkeeping sitting where a component kind goes — the
+ * strip already treats it that way, and a surface named after a marker would
+ * be pinned by `loam rebase` and then graded as an orphan the moment the strip
+ * took it out.
+ */
+export function asyncapiSurfaces(plain) {
+    const out = [];
+    if (!isRecord(plain))
+        return out;
+    const comps = plain["components"];
+    if (!isRecord(comps))
+        return out;
+    for (const [kind, names] of Object.entries(comps)) {
+        if (kind === "messages" || FEATURE_ONLY_KEYS.has(kind))
+            continue;
+        if (!isRecord(names))
+            continue;
+        for (const [name, value] of Object.entries(names)) {
+            out.push({ kind: "component", id: `${kind}/${name}`, value });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=surfaces.js.map

package/dist/core/asyncapi/baseline/surfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaces.js","sourceRoot":"","sources":["../../../../src/core/asyncapi/baseline/surfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAW5D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACjC,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;IAClC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,IAAI,IAAI,KAAK,UAAU,IAAI,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACjE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;QAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,GAAG,IAAI,IAAI,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * The values a feature event contract restates that the SLOT pin cannot reach:\n * every `components/<kind>/<name>` outside `messages`.\n *\n * A package of its own rather than a sixth file in `core/asyncapi/` — that\n * directory is exactly at the five-file limit — and a separate ENUMERATION\n * from the OpenAPI axis's `restatedSurfaces` rather than an import of it,\n * although the two are the same shape. `restatedSurfaces` walks `paths` (a key\n * an AsyncAPI document does not have) and includes `components/messages`,\n * which on this axis is a SLOT: a message pinned both in-value by\n * `x-loam-based-on` and by a root record entry would have two identities, and\n * the merge would classify it twice — once as a slot, once as a surface — with\n * verdicts that need not agree. What IS shared is everything downstream of the\n * enumeration: `readBaselineRecord`, `entryFor`, `surfaceIn` and the record's\n * `components` half are axis-neutral, so the record means the same thing on\n * both axes and only the walk that fills it differs.\n *\n * Import direction is asyncapi → openapi, as core/asyncapi/digest.ts's header\n * states; nothing under core/openapi/ imports this package.\n */\nimport { isRecord } from \"../../kernel/records.js\";\nimport { FEATURE_ONLY_KEYS } from \"../../openapi/digest.js\";\nimport type { RestatedSurface } from \"../../openapi/baseline/record.js\";\n\n/**\n * One surface of an event contract. Structurally the OpenAPI record's\n * component branch, on purpose: `entryFor` and `surfaceIn` take that union, so\n * a separate shape here would mean a second spelling of \"the record's entry\n * for this value\" — the drift both axes' digest modules exist to prevent.\n */\nexport type AsyncapiSurface = Extract<RestatedSurface, { kind: \"component\" }>;\n\n/**\n * Every component surface a plain-parsed feature document declares, in\n * document order.\n *\n * `messages` is skipped because it is the third slot section (core/asyncapi/\n * digest.ts): a message carries its own in-value pin, and giving it a root\n * record entry as well would be two pins on one value. The feature-only keys\n * are skipped in the KIND position because `components: {x-loam-remove: true,\n * schemas: {…}}` is bookkeeping sitting where a component kind goes — the\n * strip already treats it that way, and a surface named after a marker would\n * be pinned by `loam rebase` and then graded as an orphan the moment the strip\n * took it out.\n */\nexport function asyncapiSurfaces(plain: unknown): AsyncapiSurface[] {\n  const out: AsyncapiSurface[] = [];\n  if (!isRecord(plain)) return out;\n  const comps = plain[\"components\"];\n  if (!isRecord(comps)) return out;\n  for (const [kind, names] of Object.entries(comps)) {\n    if (kind === \"messages\" || FEATURE_ONLY_KEYS.has(kind)) continue;\n    if (!isRecord(names)) continue;\n    for (const [name, value] of Object.entries(names)) {\n      out.push({ kind: \"component\", id: `${kind}/${name}`, value });\n    }\n  }\n  return out;\n}\n"]}

package/dist/core/asyncapi/depth.js

@@ -0,0 +1,164 @@
+/**
+ * Pointer resolution and the contract-depth probes for the async axis: does a
+ * message's payload declare any shape at all, and does every internal `$ref`
+ * point at something.
+ *
+ * `resolvePointer` and `deref` moved here verbatim from read.ts when the
+ * probes arrived — they are what the probes and the reader both walk with,
+ * and read.ts was nine lines under the file limit.
+ *
+ * The probes are PRESENCE probes, never field joins: nothing here contributes
+ * a name to the spine, nothing reads what a schema says — only whether one
+ * was declared — and a payload declaring a non-JSON `schemaFormat` is skipped
+ * outright, so the Avro migration stays a document change (read.ts's header
+ * states the full stance).
+ */
+/** How deep a `$ref` chain is followed before the reader gives up. */
+const MAX_REF_DEPTH = 8;
+/**
+ * Resolve an internal JSON Pointer (`#/a/b/c`) against the document root.
+ *
+ * Internal only, matching the OpenAPI axis's documented stance: external
+ * references — URLs, file paths, anything not starting `#/` — are out of scope,
+ * left untouched and never graded. That is also why authors are told to keep
+ * payloads inside the document rather than `$ref`-ing an external `.avsc`: the
+ * merge cannot carry what this reader cannot see.
+ */
+export function resolvePointer(root, ref) {
+    if (typeof ref !== "string" || !ref.startsWith("#/"))
+        return undefined;
+    let node = root;
+    for (const raw of ref.slice(2).split("/")) {
+        // JSON Pointer escaping, `~1` before `~0` so an encoded `~1` survives.
+        const seg = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (node === null || typeof node !== "object")
+            return undefined;
+        node = node[seg];
+    }
+    return node;
+}
+/**
+ * Follow `$ref` hops until a node that is not a reference, or the depth budget
+ * runs out. The budget is the cycle guard: a document whose `$ref` points at
+ * itself is legal YAML, and an unbounded walk would hang the whole validate run
+ * rather than reporting a contract nobody can read.
+ *
+ * Returns the resolved node and the last pointer segment that reached it — the
+ * segment is the declaration key, which is the message-name fallback, and it is
+ * lost by the time a caller holds only the node.
+ */
+export function deref(root, node, key) {
+    let current = node;
+    let currentKey = key;
+    for (let hop = 0; hop < MAX_REF_DEPTH; hop += 1) {
+        if (current === null || typeof current !== "object" || Array.isArray(current))
+            break;
+        const ref = current["$ref"];
+        if (typeof ref !== "string")
+            break;
+        const resolved = resolvePointer(root, ref);
+        if (resolved === undefined)
+            return { node: undefined, key: currentKey };
+        const seg = ref.slice(ref.lastIndexOf("/") + 1);
+        current = resolved;
+        // An alias keeps the TARGET's key, not the local one it was filed under: a
+        // channel may list `#/components/messages/PaymentAuthorized` under any alias
+        // it likes, and the fallback name has to be the declaration's own identity
+        // or two services aliasing one message differently would stop joining.
+        currentKey = seg.length > 0 ? seg : currentKey;
+    }
+    return { node: current, key: currentKey };
+}
+/**
+ * The JSON-schema keys that say anything about shape. Presence is all that is
+ * checked — a schema carrying any of these declared SOMETHING a consumer can
+ * code against, however incompletely.
+ */
+const SHAPE_KEYS = [
+    "properties",
+    "$ref",
+    "items",
+    "enum",
+    "const",
+    "oneOf",
+    "anyOf",
+    "allOf",
+    "not",
+    "patternProperties",
+    "additionalProperties",
+    "required",
+];
+/**
+ * True when a message declaration's payload defines no shape at all: no
+ * `payload`, or a schema with none of the keys that say anything and a `type`
+ * of `object` or none — `type: object` and not one word more validates as
+ * cleanly as a full schema even though it carries no usable shape.
+ *
+ * Deliberately NOT empty: a payload behind a dangling `$ref` (that is the ref
+ * probe's finding), a non-mapping payload (`payload: true` is a declared
+ * decision), a primitive `type`, and any payload declaring a non-JSON
+ * `schemaFormat` — Avro's shape is not ours to judge.
+ */
+export function payloadUndeclared(root, msg) {
+    if (msg === null || typeof msg !== "object" || Array.isArray(msg))
+        return false;
+    const raw = msg["payload"];
+    if (raw === undefined || raw === null)
+        return true;
+    const payload = deref(root, raw, "").node;
+    if (payload === undefined)
+        return false;
+    if (payload === null)
+        return true;
+    if (typeof payload !== "object" || Array.isArray(payload))
+        return false;
+    let schema = payload;
+    const format = schema["schemaFormat"];
+    if (typeof format === "string") {
+        if (!/json/i.test(format))
+            return false;
+        // Multi-format shape: the actual schema sits one level down.
+        const inner = deref(root, schema["schema"], "").node;
+        if (inner === undefined)
+            return false;
+        if (inner === null)
+            return true;
+        if (typeof inner !== "object" || Array.isArray(inner))
+            return false;
+        schema = inner;
+    }
+    if (SHAPE_KEYS.some((k) => k in schema))
+        return false;
+    const type = schema["type"];
+    return type === undefined || type === "object";
+}
+/**
+ * Every internal `#/` reference in the document that resolves to nothing —
+ * deduped, document order. This is the probe that catches BOTH silent-skip
+ * sites in the reader: an operation's message-list entry that derefs to
+ * nothing (it "contributes no name" and vanishes from sent/received), and a
+ * channel alias whose dangling target leaves a phantom local key behind.
+ */
+export function danglingRefs(root) {
+    const out = new Set();
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const value of node)
+                walk(value);
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "$ref" && typeof value === "string") {
+                if (value.startsWith("#/") && resolvePointer(root, value) === undefined)
+                    out.add(value);
+                continue;
+            }
+            walk(value);
+        }
+    };
+    walk(root);
+    return [...out];
+}
+//# sourceMappingURL=depth.js.map

package/dist/core/asyncapi/depth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth.js","sourceRoot":"","sources":["../../../src/core/asyncapi/depth.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pointer resolution and the contract-depth probes for the async axis: does a\n * message's payload declare any shape at all, and does every internal `$ref`\n * point at something.\n *\n * `resolvePointer` and `deref` moved here verbatim from read.ts when the\n * probes arrived — they are what the probes and the reader both walk with,\n * and read.ts was nine lines under the file limit.\n *\n * The probes are PRESENCE probes, never field joins: nothing here contributes\n * a name to the spine, nothing reads what a schema says — only whether one\n * was declared — and a payload declaring a non-JSON `schemaFormat` is skipped\n * outright, so the Avro migration stays a document change (read.ts's header\n * states the full stance).\n */\n\n/** How deep a `$ref` chain is followed before the reader gives up. */\nconst MAX_REF_DEPTH = 8;\n\n/**\n * Resolve an internal JSON Pointer (`#/a/b/c`) against the document root.\n *\n * Internal only, matching the OpenAPI axis's documented stance: external\n * references — URLs, file paths, anything not starting `#/` — are out of scope,\n * left untouched and never graded. That is also why authors are told to keep\n * payloads inside the document rather than `$ref`-ing an external `.avsc`: the\n * merge cannot carry what this reader cannot see.\n */\nexport function resolvePointer(root: unknown, ref: unknown): unknown {\n  if (typeof ref !== \"string\" || !ref.startsWith(\"#/\")) return undefined;\n  let node = root;\n  for (const raw of ref.slice(2).split(\"/\")) {\n    // JSON Pointer escaping, `~1` before `~0` so an encoded `~1` survives.\n    const seg = raw.replace(/~1/g, \"/\").replace(/~0/g, \"~\");\n    if (node === null || typeof node !== \"object\") return undefined;\n    node = (node as Record<string, unknown>)[seg];\n  }\n  return node;\n}\n\n/**\n * Follow `$ref` hops until a node that is not a reference, or the depth budget\n * runs out. The budget is the cycle guard: a document whose `$ref` points at\n * itself is legal YAML, and an unbounded walk would hang the whole validate run\n * rather than reporting a contract nobody can read.\n *\n * Returns the resolved node and the last pointer segment that reached it — the\n * segment is the declaration key, which is the message-name fallback, and it is\n * lost by the time a caller holds only the node.\n */\nexport function deref(root: unknown, node: unknown, key: string): { node: unknown; key: string } {\n  let current = node;\n  let currentKey = key;\n  for (let hop = 0; hop < MAX_REF_DEPTH; hop += 1) {\n    if (current === null || typeof current !== \"object\" || Array.isArray(current)) break;\n    const ref = (current as Record<string, unknown>)[\"$ref\"];\n    if (typeof ref !== \"string\") break;\n    const resolved = resolvePointer(root, ref);\n    if (resolved === undefined) return { node: undefined, key: currentKey };\n    const seg = ref.slice(ref.lastIndexOf(\"/\") + 1);\n    current = resolved;\n    // An alias keeps the TARGET's key, not the local one it was filed under: a\n    // channel may list `#/components/messages/PaymentAuthorized` under any alias\n    // it likes, and the fallback name has to be the declaration's own identity\n    // or two services aliasing one message differently would stop joining.\n    currentKey = seg.length > 0 ? seg : currentKey;\n  }\n  return { node: current, key: currentKey };\n}\n\n/**\n * The JSON-schema keys that say anything about shape. Presence is all that is\n * checked — a schema carrying any of these declared SOMETHING a consumer can\n * code against, however incompletely.\n */\nconst SHAPE_KEYS = [\n  \"properties\",\n  \"$ref\",\n  \"items\",\n  \"enum\",\n  \"const\",\n  \"oneOf\",\n  \"anyOf\",\n  \"allOf\",\n  \"not\",\n  \"patternProperties\",\n  \"additionalProperties\",\n  \"required\",\n];\n\n/**\n * True when a message declaration's payload defines no shape at all: no\n * `payload`, or a schema with none of the keys that say anything and a `type`\n * of `object` or none — `type: object` and not one word more validates as\n * cleanly as a full schema even though it carries no usable shape.\n *\n * Deliberately NOT empty: a payload behind a dangling `$ref` (that is the ref\n * probe's finding), a non-mapping payload (`payload: true` is a declared\n * decision), a primitive `type`, and any payload declaring a non-JSON\n * `schemaFormat` — Avro's shape is not ours to judge.\n */\nexport function payloadUndeclared(root: unknown, msg: unknown): boolean {\n  if (msg === null || typeof msg !== \"object\" || Array.isArray(msg)) return false;\n  const raw = (msg as Record<string, unknown>)[\"payload\"];\n  if (raw === undefined || raw === null) return true;\n  const payload = deref(root, raw, \"\").node;\n  if (payload === undefined) return false;\n  if (payload === null) return true;\n  if (typeof payload !== \"object\" || Array.isArray(payload)) return false;\n  let schema = payload as Record<string, unknown>;\n  const format = schema[\"schemaFormat\"];\n  if (typeof format === \"string\") {\n    if (!/json/i.test(format)) return false;\n    // Multi-format shape: the actual schema sits one level down.\n    const inner = deref(root, schema[\"schema\"], \"\").node;\n    if (inner === undefined) return false;\n    if (inner === null) return true;\n    if (typeof inner !== \"object\" || Array.isArray(inner)) return false;\n    schema = inner as Record<string, unknown>;\n  }\n  if (SHAPE_KEYS.some((k) => k in schema)) return false;\n  const type = schema[\"type\"];\n  return type === undefined || type === \"object\";\n}\n\n/**\n * Every internal `#/` reference in the document that resolves to nothing —\n * deduped, document order. This is the probe that catches BOTH silent-skip\n * sites in the reader: an operation's message-list entry that derefs to\n * nothing (it \"contributes no name\" and vanishes from sent/received), and a\n * channel alias whose dangling target leaves a phantom local key behind.\n */\nexport function danglingRefs(root: unknown): string[] {\n  const out = new Set<string>();\n  const walk = (node: unknown): void => {\n    if (Array.isArray(node)) {\n      for (const value of node) walk(value);\n      return;\n    }\n    if (node === null || typeof node !== \"object\") return;\n    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {\n      if (key === \"$ref\" && typeof value === \"string\") {\n        if (value.startsWith(\"#/\") && resolvePointer(root, value) === undefined) out.add(value);\n        continue;\n      }\n      walk(value);\n    }\n  };\n  walk(root);\n  return [...out];\n}\n"]}

package/dist/core/asyncapi/digest.js

@@ -0,0 +1,141 @@
+/**
+ * Slot identity for the event axis: what a feature-local asyncapi.yaml's
+ * slots hash to, and the markers `loam rebase` and the merge read from them.
+ *
+ * The digest RULE is imported from the OpenAPI axis (../openapi/digest.js)
+ * rather than respelled: the marker keys, the removal test, the baseline
+ * accessors and the digest itself are ALIASES of that module's — one
+ * definition each, renamed to this axis's vocabulary. Two spellings of the
+ * one rule is the exact drift that module's own header names as the failure
+ * mode, and it is not hypothetical here: the deep strip filters on the
+ * OpenAPI key constants, so a second spelling of either key would be two
+ * definitions of "which keys are feature-only" — the marker leak the strip
+ * exists to close. The import direction is asyncapi → openapi only,
+ * verified cycle-free — no openapi module imports asyncapi
+ * (openapi/depth.ts names it in a comment alone).
+ *
+ * Identity is the SLOT: the pair (section, key) over the three named
+ * sections `channels.<key>`, `operations.<key>` and
+ * `components.messages.<key>` — SCHEMA.md's format spec for this axis. An
+ * inline channel message (`channels.<ck>.messages.<mk>`) is deliberately
+ * NOT a slot: its identity is interior content of its channel's slot, so
+ * the walker below never visits it, it cannot carry its own pin, and a
+ * removal marker nested on it grades as part of the channel's content —
+ * a feature declares or retires an INDIVIDUAL message under
+ * `components.messages`, with the channel aliasing it by `$ref`.
+ *
+ * Nothing here reads inside `payload` as anything but bytes: a slot digest
+ * is content identity (a changed payload moves it), never a join on payload
+ * fields — read.ts's header carries the full doctrine.
+ */
+import { isRemoval, OPENAPI_BASELINE_KEY, OPENAPI_BASELINES_KEY, OPENAPI_REMOVE_KEY, operationBaselineOf, operationDigest, withoutOperationBaseline, } from "../openapi/digest.js";
+/**
+ * The baseline marker: which living version of a slot a FEATURE delta was
+ * written against. The OpenAPI axis's key, not a restatement of its
+ * spelling, because a feature's asyncapi.yaml is a complete document for
+ * the same reason its openapi.yaml is: authors restate the living contract
+ * around the slot they change, and the pin is what lets the merge tell a
+ * QUOTE from an EDIT.
+ */
+export const ASYNCAPI_BASELINE_KEY = OPENAPI_BASELINE_KEY;
+/**
+ * The feature-only ROOT record that pins what the SLOT pin cannot reach: every
+ * `components/<kind>/<name>` outside `messages`. The OpenAPI axis's key and
+ * the OpenAPI axis's reader (core/openapi/baseline/record.ts) — one record
+ * shape for both axes, because a second spelling of "which living version was
+ * this written against" is the drift this module's header names.
+ *
+ * A root record rather than an in-value pin here for the reason it is one
+ * there: a slot value is always a mapping, so `x-loam-based-on` has somewhere
+ * to live inside it, but a `components/schemas/<name>` value is a JSON Schema
+ * — an in-value loam key there would be a schema keyword, and JSON Schema's
+ * own `true` is a legal component that no in-value key survives at all.
+ */
+export const ASYNCAPI_BASELINES_KEY = OPENAPI_BASELINES_KEY;
+/** The feature-only explicit removal marker's key — the OpenAPI axis's, aliased. */
+export const ASYNCAPI_REMOVE_KEY = OPENAPI_REMOVE_KEY;
+/** Is this slot value a feature-only explicit removal marker? One test for both axes. */
+export const isSlotRemoval = isRemoval;
+/** The `x-loam-based-on` a slot declares, or undefined — `operationBaselineOf`, aliased. */
+export const slotBaselineOf = operationBaselineOf;
+/**
+ * The slot without its own baseline marker — what a digest is taken over. A
+ * pin is a statement ABOUT a delta, never part of the slot it describes:
+ * inside the digest input, no baseline could ever be self-consistent. The
+ * OpenAPI rule, aliased — the key is the same key.
+ */
+export const withoutSlotBaseline = withoutOperationBaseline;
+/**
+ * The identity of a slot's CONTENT: sha256 of its canonical form, pin
+ * excluded. `operationDigest` under this axis's name — the same canonical
+ * JSON, the same cut, so a pin either axis writes means the same thing.
+ */
+export const slotDigest = operationDigest;
+/** Entries of a mapping node, or nothing — the walker's one structural read. */
+function entriesOf(node) {
+    if (node === null || typeof node !== "object" || Array.isArray(node))
+        return [];
+    return Object.entries(node);
+}
+/**
+ * The document path of one slot — where the pin and the merge write. Spelled
+ * here so `rebase`'s stamp and the merge's upsert cannot disagree about which
+ * node a (section, key) pair addresses.
+ */
+export function slotPath(section, key) {
+    return section === "components.messages" ? ["components", "messages", key] : [section, key];
+}
+/**
+ * Every path whose node carries `x-loam-remove: true`, at ANY depth — the
+ * three slot depths the format spec gives the key meaning at, inline channel
+ * messages, and every place the key means nothing at all: the document root,
+ * `info`, a `components` sibling, the inside of a payload. The reader's
+ * `markers` field is built from this walk so `asyncapi.remove-marker-living`
+ * can NAME a marker wherever one leaked: the strip removes the loam keys at
+ * document depth, and a sweep narrower than the strip is how the OpenAPI
+ * axis once published a marker invisible even to validate.
+ */
+export function removalMarkerPaths(node, at) {
+    if (node === null || typeof node !== "object")
+        return [];
+    const out = [];
+    if (isSlotRemoval(node))
+        out.push(at === "" ? "(document root)" : at);
+    const children = Array.isArray(node)
+        ? node.map((value, i) => [String(i), value])
+        : Object.entries(node);
+    for (const [key, value] of children) {
+        out.push(...removalMarkerPaths(value, at === "" ? key : `${at}.${key}`));
+    }
+    return out;
+}
+/**
+ * Every slot a parsed document declares, in document order across the three
+ * sections. Inline channel messages are NOT visited: they are interior
+ * content of their channel's slot (the header carries the decision), so a
+ * pin or marker nested on one is part of the `channels.<ck>` value this
+ * walker already returns — never a slot of its own.
+ */
+export function asyncapiSlots(root) {
+    if (root === null || typeof root !== "object" || Array.isArray(root))
+        return [];
+    const doc = root;
+    const slots = [];
+    const walk = (section, mapping) => {
+        for (const [key, node] of entriesOf(mapping)) {
+            slots.push({
+                section,
+                key,
+                node,
+                remove: isSlotRemoval(node),
+                digest: slotDigest(node),
+                ...(slotBaselineOf(node) === undefined ? {} : { basedOn: slotBaselineOf(node) }),
+            });
+        }
+    };
+    walk("channels", doc["channels"]);
+    walk("operations", doc["operations"]);
+    walk("components.messages", doc["components"]?.["messages"]);
+    return slots;
+}
+//# sourceMappingURL=digest.js.map

package/dist/core/asyncapi/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../../src/core/asyncapi/digest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Slot identity for the event axis: what a feature-local asyncapi.yaml's\n * slots hash to, and the markers `loam rebase` and the merge read from them.\n *\n * The digest RULE is imported from the OpenAPI axis (../openapi/digest.js)\n * rather than respelled: the marker keys, the removal test, the baseline\n * accessors and the digest itself are ALIASES of that module's — one\n * definition each, renamed to this axis's vocabulary. Two spellings of the\n * one rule is the exact drift that module's own header names as the failure\n * mode, and it is not hypothetical here: the deep strip filters on the\n * OpenAPI key constants, so a second spelling of either key would be two\n * definitions of \"which keys are feature-only\" — the marker leak the strip\n * exists to close. The import direction is asyncapi → openapi only,\n * verified cycle-free — no openapi module imports asyncapi\n * (openapi/depth.ts names it in a comment alone).\n *\n * Identity is the SLOT: the pair (section, key) over the three named\n * sections `channels.<key>`, `operations.<key>` and\n * `components.messages.<key>` — SCHEMA.md's format spec for this axis. An\n * inline channel message (`channels.<ck>.messages.<mk>`) is deliberately\n * NOT a slot: its identity is interior content of its channel's slot, so\n * the walker below never visits it, it cannot carry its own pin, and a\n * removal marker nested on it grades as part of the channel's content —\n * a feature declares or retires an INDIVIDUAL message under\n * `components.messages`, with the channel aliasing it by `$ref`.\n *\n * Nothing here reads inside `payload` as anything but bytes: a slot digest\n * is content identity (a changed payload moves it), never a join on payload\n * fields — read.ts's header carries the full doctrine.\n */\nimport {\n  isRemoval,\n  OPENAPI_BASELINE_KEY,\n  OPENAPI_BASELINES_KEY,\n  OPENAPI_REMOVE_KEY,\n  operationBaselineOf,\n  operationDigest,\n  withoutOperationBaseline,\n} from \"../openapi/digest.js\";\n\n/**\n * The baseline marker: which living version of a slot a FEATURE delta was\n * written against. The OpenAPI axis's key, not a restatement of its\n * spelling, because a feature's asyncapi.yaml is a complete document for\n * the same reason its openapi.yaml is: authors restate the living contract\n * around the slot they change, and the pin is what lets the merge tell a\n * QUOTE from an EDIT.\n */\nexport const ASYNCAPI_BASELINE_KEY = OPENAPI_BASELINE_KEY;\n\n/**\n * The feature-only ROOT record that pins what the SLOT pin cannot reach: every\n * `components/<kind>/<name>` outside `messages`. The OpenAPI axis's key and\n * the OpenAPI axis's reader (core/openapi/baseline/record.ts) — one record\n * shape for both axes, because a second spelling of \"which living version was\n * this written against\" is the drift this module's header names.\n *\n * A root record rather than an in-value pin here for the reason it is one\n * there: a slot value is always a mapping, so `x-loam-based-on` has somewhere\n * to live inside it, but a `components/schemas/<name>` value is a JSON Schema\n * — an in-value loam key there would be a schema keyword, and JSON Schema's\n * own `true` is a legal component that no in-value key survives at all.\n */\nexport const ASYNCAPI_BASELINES_KEY = OPENAPI_BASELINES_KEY;\n\n/** The feature-only explicit removal marker's key — the OpenAPI axis's, aliased. */\nexport const ASYNCAPI_REMOVE_KEY = OPENAPI_REMOVE_KEY;\n\n/** The three sections whose entries are slots. */\nexport type AsyncapiSection = \"channels\" | \"operations\" | \"components.messages\";\n\n/** One slot of an AsyncAPI document, as the identity layer sees it. */\nexport interface AsyncapiSlot {\n  section: AsyncapiSection;\n  /** The entry's key under its section — the slot half of the identity pair. */\n  key: string;\n  /** The slot's resolved value, pin and marker still in place. */\n  node: unknown;\n  /** True when the value carries `x-loam-remove: true` — a feature retiring the slot. */\n  remove: boolean;\n  /** The `x-loam-based-on` the value declares, or undefined — non-strings stringified, so the gate can refuse them. */\n  basedOn?: string;\n  /** `slotDigest` of the value as it stands in ITS OWN document. */\n  digest: string;\n}\n\n/** Is this slot value a feature-only explicit removal marker? One test for both axes. */\nexport const isSlotRemoval = isRemoval;\n\n/** The `x-loam-based-on` a slot declares, or undefined — `operationBaselineOf`, aliased. */\nexport const slotBaselineOf = operationBaselineOf;\n\n/**\n * The slot without its own baseline marker — what a digest is taken over. A\n * pin is a statement ABOUT a delta, never part of the slot it describes:\n * inside the digest input, no baseline could ever be self-consistent. The\n * OpenAPI rule, aliased — the key is the same key.\n */\nexport const withoutSlotBaseline = withoutOperationBaseline;\n\n/**\n * The identity of a slot's CONTENT: sha256 of its canonical form, pin\n * excluded. `operationDigest` under this axis's name — the same canonical\n * JSON, the same cut, so a pin either axis writes means the same thing.\n */\nexport const slotDigest = operationDigest;\n\n/** Entries of a mapping node, or nothing — the walker's one structural read. */\nfunction entriesOf(node: unknown): [string, unknown][] {\n  if (node === null || typeof node !== \"object\" || Array.isArray(node)) return [];\n  return Object.entries(node as Record<string, unknown>);\n}\n\n/**\n * The document path of one slot — where the pin and the merge write. Spelled\n * here so `rebase`'s stamp and the merge's upsert cannot disagree about which\n * node a (section, key) pair addresses.\n */\nexport function slotPath(section: AsyncapiSection, key: string): string[] {\n  return section === \"components.messages\" ? [\"components\", \"messages\", key] : [section, key];\n}\n\n/**\n * Every path whose node carries `x-loam-remove: true`, at ANY depth — the\n * three slot depths the format spec gives the key meaning at, inline channel\n * messages, and every place the key means nothing at all: the document root,\n * `info`, a `components` sibling, the inside of a payload. The reader's\n * `markers` field is built from this walk so `asyncapi.remove-marker-living`\n * can NAME a marker wherever one leaked: the strip removes the loam keys at\n * document depth, and a sweep narrower than the strip is how the OpenAPI\n * axis once published a marker invisible even to validate.\n */\nexport function removalMarkerPaths(node: unknown, at: string): string[] {\n  if (node === null || typeof node !== \"object\") return [];\n  const out: string[] = [];\n  if (isSlotRemoval(node)) out.push(at === \"\" ? \"(document root)\" : at);\n  const children = Array.isArray(node)\n    ? node.map((value, i) => [String(i), value] as const)\n    : Object.entries(node as Record<string, unknown>);\n  for (const [key, value] of children) {\n    out.push(...removalMarkerPaths(value, at === \"\" ? key : `${at}.${key}`));\n  }\n  return out;\n}\n\n/**\n * Every slot a parsed document declares, in document order across the three\n * sections. Inline channel messages are NOT visited: they are interior\n * content of their channel's slot (the header carries the decision), so a\n * pin or marker nested on one is part of the `channels.<ck>` value this\n * walker already returns — never a slot of its own.\n */\nexport function asyncapiSlots(root: unknown): AsyncapiSlot[] {\n  if (root === null || typeof root !== \"object\" || Array.isArray(root)) return [];\n  const doc = root as Record<string, unknown>;\n  const slots: AsyncapiSlot[] = [];\n  const walk = (section: AsyncapiSection, mapping: unknown): void => {\n    for (const [key, node] of entriesOf(mapping)) {\n      slots.push({\n        section,\n        key,\n        node,\n        remove: isSlotRemoval(node),\n        digest: slotDigest(node),\n        ...(slotBaselineOf(node) === undefined ? {} : { basedOn: slotBaselineOf(node) }),\n      });\n    }\n  };\n  walk(\"channels\", doc[\"channels\"]);\n  walk(\"operations\", doc[\"operations\"]);\n  walk(\"components.messages\", (doc[\"components\"] as Record<string, unknown> | undefined)?.[\"messages\"]);\n  return slots;\n}\n"]}

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

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