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

package/dist/commands/archive/plan/contracts/asyncapi.js

@@ -0,0 +1,172 @@
+/**
+ * The AsyncAPI contract merge: the feature's asyncapi deltas folded into each
+ * living event contract — the event axis's mirror of ./openapi.ts, slot-keyed
+ * where that one is path-keyed.
+ *
+ * Nothing is written. Everything lands in the `Plan`, so a failure on any axis
+ * leaves the living docs exactly as they were.
+ */
+import { existsSync } from "node:fs";
+import { parse } from "yaml";
+import { CodedFailure, repoPath } from "../../../../core/envelope/json.js";
+import { planWrite, readUtf8 } from "../../../../core/staging/writes.js";
+import { featureSpecPaths } from "../../../../core/repo/paths.js";
+import { locateServicePaths } from "../../../../core/repo/service-target.js";
+import { readAsyncapi } from "../../../../core/asyncapi/read.js";
+import { asyncapiSlots } from "../../../../core/asyncapi/digest.js";
+import { asyncapiSurfaces } from "../../../../core/asyncapi/baseline/surfaces.js";
+import { AsyncapiMergeError } from "../../../../core/asyncapi/merge/error.js";
+import { stripAsyncapiMarkers } from "../../../../core/asyncapi/merge/markers.js";
+import { mergeAsyncapiSlots } from "../../../../core/asyncapi/merge/merge.js";
+import {} from "../state.js";
+import { consumerClause } from "./consumers.js";
+import { infoDrift, sayQuoted, sayStale, warnInfoDrift, warnOverwrite } from "./verdict-lines.js";
+/** The per-section overwrite code — three codes, one per slot shape, mirroring the OpenAPI axis's. */
+function modifiedCode(section) {
+    if (section === "components.messages")
+        return "asyncapi.message-modified";
+    return section === "channels" ? "asyncapi.channel-modified" : "asyncapi.operation-modified";
+}
+export async function planAsyncapiContracts(config, gated, plan, say) {
+    const { featureDir, deltaServices } = gated;
+    const { writes, planGates, asyncapiRemovals } = plan;
+    for (const svc of deltaServices) {
+        const featAsyncapi = featureSpecPaths(featureDir, svc).asyncapi;
+        if (!existsSync(featAsyncapi))
+            continue;
+        const featText = await readUtf8(featAsyncapi);
+        const featDoc = await readAsyncapi(featAsyncapi);
+        // Coherence grades `asyncapi.invalid` and gates on it; the merge stays
+        // mechanical under --approve for the OpenAPI planner's reason: a document
+        // loam cannot read is one it cannot merge, and that is the same answer as
+        // any other merge it could not compute — nothing is written.
+        if (featDoc.unreadable) {
+            throw new CodedFailure("merge-failed", `feature asyncapi ${repoPath(config.docsDir, featAsyncapi)} for ${svc} does not read as an AsyncAPI document (${featDoc.error ?? "not a YAML mapping"}) — the event axis cannot be merged; fix the file, or delete it if this feature has no contract delta`);
+        }
+        const names = featDoc.messages.filter((m) => m.remove !== true).map((m) => m.name);
+        // An `x-loam-remove` NESTED on an inline channel message retires nothing:
+        // an inline message is channel-slot interior (SCHEMA.md's decision), so
+        // the marker is just channel content — and when the restated channel is
+        // otherwise identical to living, not even that: the merge deduplicates it
+        // away and the marker lands in no bucket at all. The merge is safe either
+        // way (the deep strip keeps the key out of living), but the author asked
+        // for a removal that will not happen, and silence there is how a retired
+        // message would stay on the wire — openapi.remove-marker-path-level's
+        // lesson at the nested depth. Gated like the other plan-visible breaches,
+        // --approve and all.
+        for (const m of featDoc.messages) {
+            if (m.remove !== true || !m.slot.startsWith("channels."))
+                continue;
+            const channel = m.slot.slice("channels.".length, m.slot.lastIndexOf(".messages."));
+            planGates.push({
+                severity: "error",
+                code: "asyncapi.remove-marker-inline",
+                subject: svc,
+                message: `${svc}: '${m.slot}' carries x-loam-remove nested on an inline channel message — inline messages are channel interior, not slots, so this retires nothing. Retire the whole channel (x-loam-remove: true at channels.${channel}), or declare the message under components.messages (the channel $ref-ing it) and put the marker there.`,
+            });
+        }
+        // The shared context, for the OpenAPI planner's reason: once per delta
+        // service must not mean one fleet walk per delta service.
+        const livingAsyncapi = (await locateServicePaths(config.docsDir, svc, config.fleet)).asyncapi;
+        try {
+            if (!existsSync(livingAsyncapi)) {
+                // A removal against a non-existent contract is gated by coherence;
+                // under --approve the strip drops the markers, so the one thing left
+                // to decide is whether a document remains. It must not when nothing
+                // survives: an asyncapi.yaml's very PRESENCE is graded on this axis
+                // (absence is `service.no-asyncapi`'s question, silence otherwise),
+                // so a slotless or all-markers delta creating an empty living
+                // contract would put a presence claim on a service that has none.
+                // SLOTS only, deliberately, now that component surfaces merge: a
+                // document holding schemas and no channel, operation or message
+                // declares no event at all, and creating it would make exactly the
+                // presence claim this branch exists to refuse.
+                const surviving = asyncapiSlots(parse(featText)).filter((slot) => !slot.remove);
+                if (surviving.length === 0) {
+                    say(`  asyncapi: ${svc} — nothing to merge (the delta declares no surviving slots), no living asyncapi.yaml created`);
+                    continue;
+                }
+                writes.push(planWrite(livingAsyncapi, stripAsyncapiMarkers(featText, svc)));
+                say(`  asyncapi: ${svc} — created (${names.join(", ")})`);
+                continue;
+            }
+            const livingText = await readUtf8(livingAsyncapi);
+            const merge = mergeAsyncapiSlots(livingText, featText, svc);
+            // What the delta declares OUTSIDE the three slot sections — the one
+            // question the merge result cannot answer for the silence below, because
+            // a merge that wrote nothing reports nothing to distinguish "the delta
+            // was all quotes" from "the delta was all schemas and I dropped them".
+            const surfaces = asyncapiSurfaces(parse(featText));
+            if (merge.text !== null) {
+                writes.push(planWrite(livingAsyncapi, merge.text));
+                // The parenthesised list names the MESSAGES the delta declares, and a
+                // delta whose whole change is a component surface has none — so this
+                // printed `merged ()`, the same empty-parenthesis lie the create
+                // branch above is commented for: it reads as "this merge wrote
+                // nothing" about a merge that just published a shared schema to every
+                // consumer of the fleet. Drop the parentheses when there is nothing to
+                // put in them; the surface lines below name what actually moved.
+                say(`  asyncapi: ${svc} — merged${names.length > 0 ? ` (${names.join(", ")})` : ""}`);
+            }
+            else if (surfaces.length > 0) {
+                // "The plan wrote less than my delta spells" is the sentence a reader
+                // cannot infer from an unchanged file — the quote line's own comment
+                // (./verdict-lines.ts) names it for slots, and a components-only
+                // delta is the shape where silence is indistinguishable from the
+                // defect that made it merge nothing at all. Not a warning: every
+                // surface being a quote is correct authoring and the correct merge.
+                say(`  asyncapi: ${svc} — nothing to write: every one of the ${surfaces.length} component surface(s) this delta declares already stands as living has it`);
+            }
+            // Asked whatever the merge wrote: a delta whose ONLY change is its `info`
+            // merges nothing at all, and that is exactly the shape that archived in
+            // silence (./verdict-lines.ts).
+            warnInfoDrift(plan, say, {
+                svc, code: "asyncapi.info-not-merged", file: "asyncapi.yaml", carries: "channels, operations and components",
+                labels: infoDrift(parse(livingText), parse(featText)),
+            });
+            if (merge.removed.length > 0) {
+                asyncapiRemovals.push({ service: svc, slots: merge.removed.map((slot) => slot.label) });
+                for (const slot of merge.removed)
+                    say(`      - removes ${slot.label}`);
+            }
+            // The quote and stale lines (./verdict-lines.ts says why each is said),
+            // the component surfaces' lines mirroring the slots' around them.
+            sayQuoted(say, merge.quoted.map((slot) => slot.label));
+            sayQuoted(say, merge.componentsQuoted.map((id) => `components.${id}`));
+            sayStale(say, merge.baselineStale.map((slot) => slot.label));
+            sayStale(say, merge.componentsStale.map((id) => `components.${id}`));
+            for (const id of merge.componentsModified) {
+                warnOverwrite(plan, say, {
+                    svc, code: "asyncapi.component-modified", label: `components.${id}`,
+                    message: `${svc}: the delta declares components.${id}, which the living AsyncAPI already has with different content — the merge overwrites the living component wholesale`,
+                });
+            }
+            for (const slot of merge.modified) {
+                // A message is the one slot a consumer names (`Consumes:` lines,
+                // `consumes` edges), so only `asyncapi.message-modified` says who the
+                // overwrite lands on — the OpenAPI planner's sentence, through the
+                // same scan (./consumers.ts). Channels and operations join by nothing.
+                const name = merge.modifiedMessageNames.get(slot.label);
+                const named = name === undefined ? null : consumerClause(await config.consumers.message(svc, name));
+                warnOverwrite(plan, say, {
+                    svc, code: modifiedCode(slot.section), label: slot.label, named,
+                    message: `${svc}: the delta redefines ${slot.label}, which the living AsyncAPI already has — the merge overwrites the living slot wholesale`,
+                });
+            }
+            for (const ref of merge.unresolved) {
+                planGates.push({
+                    severity: "error",
+                    code: "asyncapi.ref-unresolved",
+                    subject: svc,
+                    message: `${svc}: $ref '${ref}' resolves in neither the feature's asyncapi.yaml nor the living one — the merged document would carry a dangling reference`,
+                });
+            }
+        }
+        catch (err) {
+            if (err instanceof AsyncapiMergeError)
+                throw new CodedFailure("merge-failed", err.message);
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=asyncapi.js.map

package/dist/commands/archive/plan/contracts/asyncapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncapi.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/contracts/asyncapi.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The AsyncAPI contract merge: the feature's asyncapi deltas folded into each\n * living event contract — the event axis's mirror of ./openapi.ts, slot-keyed\n * where that one is path-keyed.\n *\n * Nothing is written. Everything lands in the `Plan`, so a failure on any axis\n * leaves the living docs exactly as they were.\n */\nimport { existsSync } from \"node:fs\";\nimport { parse } from \"yaml\";\nimport { CodedFailure, repoPath } from \"../../../../core/envelope/json.js\";\nimport { planWrite, readUtf8 } from \"../../../../core/staging/writes.js\";\nimport { featureSpecPaths } from \"../../../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../../../core/repo/service-target.js\";\nimport { readAsyncapi } from \"../../../../core/asyncapi/read.js\";\nimport { asyncapiSlots, type AsyncapiSection } from \"../../../../core/asyncapi/digest.js\";\nimport { asyncapiSurfaces } from \"../../../../core/asyncapi/baseline/surfaces.js\";\nimport { AsyncapiMergeError } from \"../../../../core/asyncapi/merge/error.js\";\nimport { stripAsyncapiMarkers } from \"../../../../core/asyncapi/merge/markers.js\";\nimport { mergeAsyncapiSlots, type AsyncapiMergeResult } from \"../../../../core/asyncapi/merge/merge.js\";\nimport { type Gated, type Plan } from \"../state.js\";\nimport { consumerClause, type ContractConsumers } from \"./consumers.js\";\nimport { infoDrift, sayQuoted, sayStale, warnInfoDrift, warnOverwrite } from \"./verdict-lines.js\";\nimport type { FleetContext } from \"../../../../core/fleet-context.js\";\nimport type { IssueCode } from \"../../../../core/vocabulary/issue.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\n\n/** The per-section overwrite code — three codes, one per slot shape, mirroring the OpenAPI axis's. */\nfunction modifiedCode(section: AsyncapiSection): IssueCode {\n  if (section === \"components.messages\") return \"asyncapi.message-modified\";\n  return section === \"channels\" ? \"asyncapi.channel-modified\" : \"asyncapi.operation-modified\";\n}\n\nexport async function planAsyncapiContracts(\n  config: { docsDir: DocsDir; fleet: FleetContext; consumers: ContractConsumers },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes, planGates, asyncapiRemovals } = plan;\n  for (const svc of deltaServices) {\n    const featAsyncapi = featureSpecPaths(featureDir, svc).asyncapi;\n    if (!existsSync(featAsyncapi)) continue;\n    const featText = await readUtf8(featAsyncapi);\n    const featDoc = await readAsyncapi(featAsyncapi);\n    // Coherence grades `asyncapi.invalid` and gates on it; the merge stays\n    // mechanical under --approve for the OpenAPI planner's reason: a document\n    // loam cannot read is one it cannot merge, and that is the same answer as\n    // any other merge it could not compute — nothing is written.\n    if (featDoc.unreadable) {\n      throw new CodedFailure(\n        \"merge-failed\",\n        `feature asyncapi ${repoPath(config.docsDir, featAsyncapi)} for ${svc} does not read as an AsyncAPI document (${featDoc.error ?? \"not a YAML mapping\"}) — the event axis cannot be merged; fix the file, or delete it if this feature has no contract delta`,\n      );\n    }\n    const names = featDoc.messages.filter((m) => m.remove !== true).map((m) => m.name);\n    // An `x-loam-remove` NESTED on an inline channel message retires nothing:\n    // an inline message is channel-slot interior (SCHEMA.md's decision), so\n    // the marker is just channel content — and when the restated channel is\n    // otherwise identical to living, not even that: the merge deduplicates it\n    // away and the marker lands in no bucket at all. The merge is safe either\n    // way (the deep strip keeps the key out of living), but the author asked\n    // for a removal that will not happen, and silence there is how a retired\n    // message would stay on the wire — openapi.remove-marker-path-level's\n    // lesson at the nested depth. Gated like the other plan-visible breaches,\n    // --approve and all.\n    for (const m of featDoc.messages) {\n      if (m.remove !== true || !m.slot.startsWith(\"channels.\")) continue;\n      const channel = m.slot.slice(\"channels.\".length, m.slot.lastIndexOf(\".messages.\"));\n      planGates.push({\n        severity: \"error\",\n        code: \"asyncapi.remove-marker-inline\",\n        subject: svc,\n        message: `${svc}: '${m.slot}' carries x-loam-remove nested on an inline channel message — inline messages are channel interior, not slots, so this retires nothing. Retire the whole channel (x-loam-remove: true at channels.${channel}), or declare the message under components.messages (the channel $ref-ing it) and put the marker there.`,\n      });\n    }\n    // The shared context, for the OpenAPI planner's reason: once per delta\n    // service must not mean one fleet walk per delta service.\n    const livingAsyncapi = (await locateServicePaths(config.docsDir, svc, config.fleet)).asyncapi;\n    try {\n      if (!existsSync(livingAsyncapi)) {\n        // A removal against a non-existent contract is gated by coherence;\n        // under --approve the strip drops the markers, so the one thing left\n        // to decide is whether a document remains. It must not when nothing\n        // survives: an asyncapi.yaml's very PRESENCE is graded on this axis\n        // (absence is `service.no-asyncapi`'s question, silence otherwise),\n        // so a slotless or all-markers delta creating an empty living\n        // contract would put a presence claim on a service that has none.\n        // SLOTS only, deliberately, now that component surfaces merge: a\n        // document holding schemas and no channel, operation or message\n        // declares no event at all, and creating it would make exactly the\n        // presence claim this branch exists to refuse.\n        const surviving = asyncapiSlots(parse(featText)).filter((slot) => !slot.remove);\n        if (surviving.length === 0) {\n          say(`  asyncapi: ${svc} — nothing to merge (the delta declares no surviving slots), no living asyncapi.yaml created`);\n          continue;\n        }\n        writes.push(planWrite(livingAsyncapi, stripAsyncapiMarkers(featText, svc)));\n        say(`  asyncapi: ${svc} — created (${names.join(\", \")})`);\n        continue;\n      }\n      const livingText = await readUtf8(livingAsyncapi);\n      const merge: AsyncapiMergeResult = mergeAsyncapiSlots(livingText, featText, svc);\n      // What the delta declares OUTSIDE the three slot sections — the one\n      // question the merge result cannot answer for the silence below, because\n      // a merge that wrote nothing reports nothing to distinguish \"the delta\n      // was all quotes\" from \"the delta was all schemas and I dropped them\".\n      const surfaces = asyncapiSurfaces(parse(featText));\n      if (merge.text !== null) {\n        writes.push(planWrite(livingAsyncapi, merge.text));\n        // The parenthesised list names the MESSAGES the delta declares, and a\n        // delta whose whole change is a component surface has none — so this\n        // printed `merged ()`, the same empty-parenthesis lie the create\n        // branch above is commented for: it reads as \"this merge wrote\n        // nothing\" about a merge that just published a shared schema to every\n        // consumer of the fleet. Drop the parentheses when there is nothing to\n        // put in them; the surface lines below name what actually moved.\n        say(`  asyncapi: ${svc} — merged${names.length > 0 ? ` (${names.join(\", \")})` : \"\"}`);\n      } else if (surfaces.length > 0) {\n        // \"The plan wrote less than my delta spells\" is the sentence a reader\n        // cannot infer from an unchanged file — the quote line's own comment\n        // (./verdict-lines.ts) names it for slots, and a components-only\n        // delta is the shape where silence is indistinguishable from the\n        // defect that made it merge nothing at all. Not a warning: every\n        // surface being a quote is correct authoring and the correct merge.\n        say(`  asyncapi: ${svc} — nothing to write: every one of the ${surfaces.length} component surface(s) this delta declares already stands as living has it`);\n      }\n      // Asked whatever the merge wrote: a delta whose ONLY change is its `info`\n      // merges nothing at all, and that is exactly the shape that archived in\n      // silence (./verdict-lines.ts).\n      warnInfoDrift(plan, say, {\n        svc, code: \"asyncapi.info-not-merged\", file: \"asyncapi.yaml\", carries: \"channels, operations and components\",\n        labels: infoDrift(parse(livingText), parse(featText)),\n      });\n      if (merge.removed.length > 0) {\n        asyncapiRemovals.push({ service: svc, slots: merge.removed.map((slot) => slot.label) });\n        for (const slot of merge.removed) say(`      - removes ${slot.label}`);\n      }\n      // The quote and stale lines (./verdict-lines.ts says why each is said),\n      // the component surfaces' lines mirroring the slots' around them.\n      sayQuoted(say, merge.quoted.map((slot) => slot.label));\n      sayQuoted(say, merge.componentsQuoted.map((id) => `components.${id}`));\n      sayStale(say, merge.baselineStale.map((slot) => slot.label));\n      sayStale(say, merge.componentsStale.map((id) => `components.${id}`));\n      for (const id of merge.componentsModified) {\n        warnOverwrite(plan, say, {\n          svc, code: \"asyncapi.component-modified\", label: `components.${id}`,\n          message: `${svc}: the delta declares components.${id}, which the living AsyncAPI already has with different content — the merge overwrites the living component wholesale`,\n        });\n      }\n      for (const slot of merge.modified) {\n        // A message is the one slot a consumer names (`Consumes:` lines,\n        // `consumes` edges), so only `asyncapi.message-modified` says who the\n        // overwrite lands on — the OpenAPI planner's sentence, through the\n        // same scan (./consumers.ts). Channels and operations join by nothing.\n        const name = merge.modifiedMessageNames.get(slot.label);\n        const named = name === undefined ? null : consumerClause(await config.consumers.message(svc, name));\n        warnOverwrite(plan, say, {\n          svc, code: modifiedCode(slot.section), label: slot.label, named,\n          message: `${svc}: the delta redefines ${slot.label}, which the living AsyncAPI already has — the merge overwrites the living slot wholesale`,\n        });\n      }\n      for (const ref of merge.unresolved) {\n        planGates.push({\n          severity: \"error\",\n          code: \"asyncapi.ref-unresolved\",\n          subject: svc,\n          message: `${svc}: $ref '${ref}' resolves in neither the feature's asyncapi.yaml nor the living one — the merged document would carry a dangling reference`,\n        });\n      }\n    } catch (err) {\n      if (err instanceof AsyncapiMergeError) throw new CodedFailure(\"merge-failed\", err.message);\n      throw err;\n    }\n  }\n}\n"]}

package/dist/commands/archive/plan/contracts/consumers.js

@@ -0,0 +1,56 @@
+/**
+ * Who in the CURRENT fleet consumes what an archive is about to overwrite — the
+ * consumers an `openapi.op-modified` / `asyncapi.message-modified` warning
+ * names, so "the merge overwrites the living operation wholesale" says whom
+ * that lands on instead of leaving the reader to go and find out.
+ *
+ * NOT A NEW JOIN. This is the one consumer index (core/consumers/consumers.ts)
+ * — the one `loam diff` names victims with and the coherence gate refuses on —
+ * asked over the living fleet as it stands before the merge: the same edges of
+ * the `architecture/` project, the same living requirements, the same use-case
+ * hops, the same suspensions for a consumer nobody could read or a caller
+ * drawn with no op, and the same sentence for the answer (`consumerStance`).
+ * Its `own` list (the provider's own documents) is the gate's to count and is
+ * not named here: a warning about whom an overwrite lands on is about OTHER
+ * services, as the diff's is.
+ *
+ * LAZY, AND PAID ONLY WHEN A WARNING FIRES. The index reads every service's
+ * four documents (`livingFleet`) and, at the first question, parses the
+ * `architecture/` project — through the run's read index, so a second question
+ * pays for neither again; the archive's own gate calls coherence without that
+ * index, so its read is not shared with this one. Measured 2026-10-10 on the
+ * 120-service benchmark fleet (scripts/bench-validate.ts's shape), with one
+ * feature overwriting one operation: `archive --dry-run --json` went from a
+ * 1216 ms to a 1346 ms median over five runs through tsx (~0.5 s of which is
+ * startup); taken apart, about 50 ms of document reads and about 120 ms of
+ * LikeC4. An archive that overwrites nothing never builds it.
+ *
+ * What it does NOT answer: `openapi.component-modified` and
+ * `asyncapi.component-modified`. A component's consumers are the operations or
+ * messages whose `$ref` closure reaches it, and then THEIR consumers; nothing
+ * indexes a contract by component today (an operation carries its closure's
+ * digest, not its members), and building that reverse index for a warning is
+ * the heavy new structure this reuse was allowed only without.
+ */
+import { consumerIndex } from "../../../../core/consumers/consumers.js";
+import { consumerStance, scanDetails } from "../../../../core/consumers/scan.js";
+import { FleetContext } from "../../../../core/fleet-context.js";
+export function contractConsumers(config) {
+    // The run's own read index: the planners have already read the delta
+    // services' living contracts through it, and the index memoises its fleet
+    // and its map on it. Constructing the index reads nothing.
+    const index = consumerIndex({ docsDir: config.docsDir, context: config.fleet });
+    return {
+        op: (provider, operationId) => index.opConsumers(provider, operationId),
+        message: (provider, name) => index.messageConsumers(provider, name),
+    };
+}
+/**
+ * The clause an overwrite warning's message ends with, and the lines its
+ * `details` carry: positive evidence first, then what could not be checked —
+ * the order `loam diff` lists them in.
+ */
+export function consumerClause(scan) {
+    return { clause: consumerStance(scan), details: scanDetails(scan) };
+}
+//# sourceMappingURL=consumers.js.map

package/dist/commands/archive/plan/contracts/consumers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumers.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/contracts/consumers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAqB,MAAM,oCAAoC,CAAC;AACpG,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAWjE,MAAM,UAAU,iBAAiB,CAAC,MAAiD;IACjF,qEAAqE;IACrE,0EAA0E;IAC1E,2DAA2D;IAC3D,MAAM,KAAK,GAAG,aAAa,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAChF,OAAO;QACL,EAAE,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC;QACvE,OAAO,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC;KACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAkB;IAC/C,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;AACtE,CAAC","sourcesContent":["/**\n * Who in the CURRENT fleet consumes what an archive is about to overwrite — the\n * consumers an `openapi.op-modified` / `asyncapi.message-modified` warning\n * names, so \"the merge overwrites the living operation wholesale\" says whom\n * that lands on instead of leaving the reader to go and find out.\n *\n * NOT A NEW JOIN. This is the one consumer index (core/consumers/consumers.ts)\n * — the one `loam diff` names victims with and the coherence gate refuses on —\n * asked over the living fleet as it stands before the merge: the same edges of\n * the `architecture/` project, the same living requirements, the same use-case\n * hops, the same suspensions for a consumer nobody could read or a caller\n * drawn with no op, and the same sentence for the answer (`consumerStance`).\n * Its `own` list (the provider's own documents) is the gate's to count and is\n * not named here: a warning about whom an overwrite lands on is about OTHER\n * services, as the diff's is.\n *\n * LAZY, AND PAID ONLY WHEN A WARNING FIRES. The index reads every service's\n * four documents (`livingFleet`) and, at the first question, parses the\n * `architecture/` project — through the run's read index, so a second question\n * pays for neither again; the archive's own gate calls coherence without that\n * index, so its read is not shared with this one. Measured 2026-10-10 on the\n * 120-service benchmark fleet (scripts/bench-validate.ts's shape), with one\n * feature overwriting one operation: `archive --dry-run --json` went from a\n * 1216 ms to a 1346 ms median over five runs through tsx (~0.5 s of which is\n * startup); taken apart, about 50 ms of document reads and about 120 ms of\n * LikeC4. An archive that overwrites nothing never builds it.\n *\n * What it does NOT answer: `openapi.component-modified` and\n * `asyncapi.component-modified`. A component's consumers are the operations or\n * messages whose `$ref` closure reaches it, and then THEIR consumers; nothing\n * indexes a contract by component today (an operation carries its closure's\n * digest, not its members), and building that reverse index for a warning is\n * the heavy new structure this reuse was allowed only without.\n */\nimport { consumerIndex } from \"../../../../core/consumers/consumers.js\";\nimport { consumerStance, scanDetails, type ConsumerScan } from \"../../../../core/consumers/scan.js\";\nimport { FleetContext } from \"../../../../core/fleet-context.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\n\n/** The two questions the contract planners ask, each answered at most once per run's index. */\nexport interface ContractConsumers {\n  /** Current consumers of `provider`'s operation `operationId`. */\n  op(provider: string, operationId: string): Promise<ConsumerScan>;\n  /** Current consumers of message `name` that `provider` declares. */\n  message(provider: string, name: string): Promise<ConsumerScan>;\n}\n\nexport function contractConsumers(config: { docsDir: DocsDir; fleet: FleetContext }): ContractConsumers {\n  // The run's own read index: the planners have already read the delta\n  // services' living contracts through it, and the index memoises its fleet\n  // and its map on it. Constructing the index reads nothing.\n  const index = consumerIndex({ docsDir: config.docsDir, context: config.fleet });\n  return {\n    op: (provider, operationId) => index.opConsumers(provider, operationId),\n    message: (provider, name) => index.messageConsumers(provider, name),\n  };\n}\n\n/**\n * The clause an overwrite warning's message ends with, and the lines its\n * `details` carry: positive evidence first, then what could not be checked —\n * the order `loam diff` lists them in.\n */\nexport function consumerClause(scan: ConsumerScan): { clause: string; details: string[] } {\n  return { clause: consumerStance(scan), details: scanDetails(scan) };\n}\n"]}

package/dist/commands/archive/plan/contracts/openapi.js

@@ -0,0 +1,193 @@
+/**
+ * The OpenAPI contract merge: the feature's openapi deltas folded into each
+ * living service API — the half of the archive plan that answers to the
+ * contract axis, split out of ../specs.ts so the requirements merge and the
+ * contract merges stop sharing one file.
+ *
+ * Nothing is written. Everything lands in the `Plan`, so a failure on any axis
+ * leaves the living docs exactly as they were.
+ */
+import { existsSync } from "node:fs";
+import { parse } from "yaml";
+import { CodedFailure, repoPath } from "../../../../core/envelope/json.js";
+import { isRecord } from "../../../../core/kernel/records.js";
+import { planWrite, readUtf8 } from "../../../../core/staging/writes.js";
+import { featureSpecPaths } from "../../../../core/repo/paths.js";
+import { locateServicePaths } from "../../../../core/repo/service-target.js";
+import { readOpenapi } from "../../../../core/openapi/doc.js";
+import { OpenapiMergeError } from "../../../../core/openapi/merge/error.js";
+import { stripOpenapiRemovalMarkers } from "../../../../core/openapi/merge/markers.js";
+import { mergeOpenapiPaths } from "../../../../core/openapi/merge/merge.js";
+import {} from "../state.js";
+import { consumerClause } from "./consumers.js";
+import { infoDrift, sayQuoted, sayStale, warnInfoDrift, warnOverwrite } from "./verdict-lines.js";
+export async function planOpenapiContracts(config, gated, plan, say) {
+    const { featureDir, deltaServices } = gated;
+    const { writes, planGates, openapiRemovals } = plan;
+    // OpenAPI merge — fold the feature's openapi deltas into the living service APIs.
+    for (const svc of deltaServices) {
+        const featOpenapi = featureSpecPaths(featureDir, svc).openapi;
+        if (!existsSync(featOpenapi))
+            continue;
+        const featText = await readUtf8(featOpenapi);
+        // The shared context: this planner runs once per delta service, and a
+        // context-less locate is a full fleet walk per service.
+        const livingOpenapi = (await locateServicePaths(config.docsDir, svc, config.fleet)).openapi;
+        const featDoc = await readOpenapi(featOpenapi);
+        // Every other reader of this flag suspends its own judgement when it is set
+        // — validate grades `openapi.invalid`, show and status print that the file
+        // does not parse. Archive was the only one that never looked, and it is the
+        // command that WRITES: a feature openapi.yaml holding a sequence instead of
+        // a mapping was planned verbatim into services/<svc>/openapi.yaml, `ok:
+        // true`, printing `created ()` because the reader saw no operations in it.
+        // A document loam cannot read is one it cannot merge, and that is the same
+        // answer as any other merge it could not compute: nothing is written.
+        if (featDoc.unreadable) {
+            throw new CodedFailure("merge-failed", `feature openapi ${repoPath(config.docsDir, featOpenapi)} for ${svc} does not read as an OpenAPI document (${featDoc.error ?? "not a YAML mapping"}) — the API axis cannot be merged; fix the file, or delete it if this feature has no contract delta`);
+        }
+        const ops = featDoc.ops.filter((op) => !op.remove).map((op) => op.id);
+        // An `x-loam-remove: true` written at PATH level retires nothing: the marker
+        // addresses one operation, and beside the methods there is no operation for
+        // it to address. The merge now strips it on every branch, so the living
+        // contract is safe either way — but the author asked for a removal that will
+        // not happen, and silence there is how a retired endpoint stayed live.
+        // Gated like the other plan-visible breaches, --approve and all.
+        for (const path of featDoc.pathLevelRemovals) {
+            planGates.push({
+                severity: "error",
+                code: "openapi.remove-marker-path-level",
+                subject: svc,
+                message: `${svc}: '${path}' carries x-loam-remove at PATH level, beside the methods — a removal marker names ONE operation, so this retires nothing and is not a contract key either. Move it inside the operation you are retiring (with its operationId), or delete it.`,
+            });
+        }
+        if (!existsSync(livingOpenapi)) {
+            // A removal against a non-existent contract is gated by coherence. Keep
+            // the feature-only marker out of living docs even under --approve — and
+            // ask the DOCUMENT, not the operation reader: a marker with no
+            // operationId is invisible to `operations()`, so gating the strip on
+            // "does the reader see a removal" let exactly that marker through into a
+            // living contract, published to every consumer of the fleet.
+            const content = stripOpenapiRemovalMarkers(featText, svc);
+            // A contract that describes nothing is not created, on the spec axis's
+            // rule for a delta that leaves no requirements (../specs.ts). A
+            // `paths: {}` stub is what an author wrote to quiet a status that used to
+            // demand a contract from every new service, and copying it in published
+            // "this service exposes nothing" as a living contract the fleet then
+            // joins against — announced as `created ()`. With no file, the service
+            // reads as one with no HTTP surface, which `service.no-openapi` already
+            // grades: silent while nothing calls it, an error once something does.
+            if (describesNothing(content)) {
+                say(`  openapi: ${svc} — nothing to merge (delta defines no paths or components), no living openapi.yaml created`);
+                continue;
+            }
+            writes.push(planWrite(livingOpenapi, content));
+            say(`  openapi: ${svc} — created (${ops.join(", ")})`);
+        }
+        else {
+            const livingText = await readUtf8(livingOpenapi);
+            let merge;
+            try {
+                merge = mergeOpenapiPaths(livingText, featText, svc);
+            }
+            catch (err) {
+                if (err instanceof OpenapiMergeError)
+                    throw new CodedFailure("merge-failed", err.message);
+                throw err;
+            }
+            const { text, modified, modifiedOperationIds, pathItemModified, removed, quoted, pathItemQuoted, pathItemStale, componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved, } = merge;
+            if (text !== null) {
+                writes.push(planWrite(livingOpenapi, text));
+                // The parenthesised list names the OPERATIONS the delta merged, and a
+                // delta whose whole change is a component has none — so this printed
+                // `merged ()`, the same empty-parenthesis lie the create branch above
+                // is commented for: it reads as "this merge wrote nothing" about a
+                // merge that just published a shared schema to every consumer of the
+                // fleet. Name the components it added instead, and drop the
+                // parentheses entirely when there is nothing to put in them — a delta
+                // that only EDITED existing surfaces is named by the lines below.
+                const mergedNames = ops.length > 0 ? ops : componentsAdded.map((comp) => `component ${comp}`);
+                say(`  openapi: ${svc} — merged${mergedNames.length > 0 ? ` (${mergedNames.join(", ")})` : ""}`);
+            }
+            // Asked whatever the merge wrote, for the event planner's reason: an
+            // `info`-only delta merges nothing, and archived in silence.
+            warnInfoDrift(plan, say, {
+                svc, code: "openapi.info-not-merged", file: "openapi.yaml", carries: "paths and components",
+                labels: infoDrift(parse(livingText), parse(featText)),
+            });
+            if (removed.length > 0) {
+                openapiRemovals.push({ service: svc, operations: removed });
+                for (const label of removed)
+                    say(`      - removes ${label}`);
+            }
+            // The quote and stale lines (./verdict-lines.ts says why each is said).
+            sayQuoted(say, quoted);
+            sayQuoted(say, pathItemQuoted.map((label) => `path-level ${label}`));
+            sayQuoted(say, componentsQuoted.map((comp) => `component ${comp}`));
+            sayStale(say, pathItemStale.map((label) => `path-level ${label}`));
+            sayStale(say, componentsStale.map((comp) => `component ${comp}`));
+            for (const label of modified) {
+                // Who the overwrite lands on: the living fleet's consumers of the
+                // operation, through `loam diff`'s own scan (./consumers.ts). An
+                // operation with no operationId on either side has nothing anyone can
+                // name it by, so the warning stays the sentence it always was.
+                const id = modifiedOperationIds.get(label);
+                const named = id === undefined ? null : consumerClause(await config.consumers.op(svc, id));
+                warnOverwrite(plan, say, {
+                    svc, code: "openapi.op-modified", label, named,
+                    message: `${svc}: the delta redefines ${label}, which the living OpenAPI already has — the merge overwrites the living operation wholesale`,
+                });
+            }
+            for (const label of pathItemModified) {
+                warnOverwrite(plan, say, {
+                    svc, code: "openapi.path-item-modified", label: `path-level ${label}`,
+                    message: `${svc}: the delta redefines the path-level key ${label}, which the living OpenAPI already has — the merge overwrites it wholesale, and it applies to EVERY operation on that path, including ones this feature never mentions`,
+                });
+            }
+            for (const comp of componentsModified) {
+                warnOverwrite(plan, say, {
+                    svc, code: "openapi.component-modified", label: `component ${comp}`,
+                    message: `${svc}: the delta declares component '${comp}', which the living OpenAPI already defines differently — the merge overwrites the living component wholesale`,
+                });
+            }
+            for (const u of unresolved) {
+                planGates.push({
+                    severity: "error",
+                    code: "openapi.ref-unresolved",
+                    subject: svc,
+                    message: `${svc}: $ref '${u.ref}' (referenced from ${u.from}) resolves in neither the feature's openapi.yaml nor the living one — the merged document would carry a dangling reference`,
+                });
+            }
+        }
+    }
+}
+/**
+ * Does this contract describe no surface at all — no path, no webhook, and no
+ * component in any section? Only the document's frame is left (`openapi`,
+ * `info`, `servers`, `tags`), which is a title and nothing anyone can call.
+ *
+ * Conservative in one direction: anything that is not an empty mapping where a
+ * mapping belongs counts as content, so a document this cannot classify is
+ * created exactly as before. The reader above has already refused one that
+ * does not parse.
+ */
+function describesNothing(text) {
+    let doc;
+    try {
+        doc = parse(text);
+    }
+    catch {
+        // Not a document this can classify, so it is content: created as before.
+        return false;
+    }
+    if (doc === null || doc === undefined)
+        return true;
+    if (!isRecord(doc))
+        return false;
+    const components = doc["components"];
+    const sections = components === undefined || components === null ? [] : isRecord(components) ? Object.values(components) : [components];
+    return [doc["paths"], doc["webhooks"], ...sections].every(isEmptyMapping);
+}
+function isEmptyMapping(value) {
+    return value === undefined || value === null || (isRecord(value) && Object.keys(value).length === 0);
+}
+//# sourceMappingURL=openapi.js.map

package/dist/commands/archive/plan/contracts/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../../../../src/commands/archive/plan/contracts/openapi.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The OpenAPI contract merge: the feature's openapi deltas folded into each\n * living service API — the half of the archive plan that answers to the\n * contract axis, split out of ../specs.ts so the requirements merge and the\n * contract merges stop sharing one file.\n *\n * Nothing is written. Everything lands in the `Plan`, so a failure on any axis\n * leaves the living docs exactly as they were.\n */\nimport { existsSync } from \"node:fs\";\nimport { parse } from \"yaml\";\nimport { CodedFailure, repoPath } from \"../../../../core/envelope/json.js\";\nimport { isRecord } from \"../../../../core/kernel/records.js\";\nimport { planWrite, readUtf8 } from \"../../../../core/staging/writes.js\";\nimport { featureSpecPaths } from \"../../../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../../../core/repo/service-target.js\";\nimport { readOpenapi } from \"../../../../core/openapi/doc.js\";\nimport { OpenapiMergeError } from \"../../../../core/openapi/merge/error.js\";\nimport { stripOpenapiRemovalMarkers } from \"../../../../core/openapi/merge/markers.js\";\nimport { mergeOpenapiPaths, type OpenapiMergeResult } from \"../../../../core/openapi/merge/merge.js\";\nimport { type Gated, type Plan } from \"../state.js\";\nimport { consumerClause, type ContractConsumers } from \"./consumers.js\";\nimport { infoDrift, sayQuoted, sayStale, warnInfoDrift, warnOverwrite } from \"./verdict-lines.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../../core/fleet-context.js\";\n\nexport async function planOpenapiContracts(\n  config: { docsDir: DocsDir; fleet: FleetContext; consumers: ContractConsumers },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes, planGates, openapiRemovals } = plan;\n  // OpenAPI merge — fold the feature's openapi deltas into the living service APIs.\n  for (const svc of deltaServices) {\n    const featOpenapi = featureSpecPaths(featureDir, svc).openapi;\n    if (!existsSync(featOpenapi)) continue;\n    const featText = await readUtf8(featOpenapi);\n    // The shared context: this planner runs once per delta service, and a\n    // context-less locate is a full fleet walk per service.\n    const livingOpenapi = (await locateServicePaths(config.docsDir, svc, config.fleet)).openapi;\n    const featDoc = await readOpenapi(featOpenapi);\n    // Every other reader of this flag suspends its own judgement when it is set\n    // — validate grades `openapi.invalid`, show and status print that the file\n    // does not parse. Archive was the only one that never looked, and it is the\n    // command that WRITES: a feature openapi.yaml holding a sequence instead of\n    // a mapping was planned verbatim into services/<svc>/openapi.yaml, `ok:\n    // true`, printing `created ()` because the reader saw no operations in it.\n    // A document loam cannot read is one it cannot merge, and that is the same\n    // answer as any other merge it could not compute: nothing is written.\n    if (featDoc.unreadable) {\n      throw new CodedFailure(\n        \"merge-failed\",\n        `feature openapi ${repoPath(config.docsDir, featOpenapi)} for ${svc} does not read as an OpenAPI document (${featDoc.error ?? \"not a YAML mapping\"}) — the API axis cannot be merged; fix the file, or delete it if this feature has no contract delta`,\n      );\n    }\n    const ops = featDoc.ops.filter((op) => !op.remove).map((op) => op.id);\n    // An `x-loam-remove: true` written at PATH level retires nothing: the marker\n    // addresses one operation, and beside the methods there is no operation for\n    // it to address. The merge now strips it on every branch, so the living\n    // contract is safe either way — but the author asked for a removal that will\n    // not happen, and silence there is how a retired endpoint stayed live.\n    // Gated like the other plan-visible breaches, --approve and all.\n    for (const path of featDoc.pathLevelRemovals) {\n      planGates.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-path-level\",\n        subject: svc,\n        message: `${svc}: '${path}' carries x-loam-remove at PATH level, beside the methods — a removal marker names ONE operation, so this retires nothing and is not a contract key either. Move it inside the operation you are retiring (with its operationId), or delete it.`,\n      });\n    }\n    if (!existsSync(livingOpenapi)) {\n      // A removal against a non-existent contract is gated by coherence. Keep\n      // the feature-only marker out of living docs even under --approve — and\n      // ask the DOCUMENT, not the operation reader: a marker with no\n      // operationId is invisible to `operations()`, so gating the strip on\n      // \"does the reader see a removal\" let exactly that marker through into a\n      // living contract, published to every consumer of the fleet.\n      const content = stripOpenapiRemovalMarkers(featText, svc);\n      // A contract that describes nothing is not created, on the spec axis's\n      // rule for a delta that leaves no requirements (../specs.ts). A\n      // `paths: {}` stub is what an author wrote to quiet a status that used to\n      // demand a contract from every new service, and copying it in published\n      // \"this service exposes nothing\" as a living contract the fleet then\n      // joins against — announced as `created ()`. With no file, the service\n      // reads as one with no HTTP surface, which `service.no-openapi` already\n      // grades: silent while nothing calls it, an error once something does.\n      if (describesNothing(content)) {\n        say(`  openapi: ${svc} — nothing to merge (delta defines no paths or components), no living openapi.yaml created`);\n        continue;\n      }\n      writes.push(planWrite(livingOpenapi, content));\n      say(`  openapi: ${svc} — created (${ops.join(\", \")})`);\n    } else {\n      const livingText = await readUtf8(livingOpenapi);\n      let merge: OpenapiMergeResult;\n      try {\n        merge = mergeOpenapiPaths(livingText, featText, svc);\n      } catch (err) {\n        if (err instanceof OpenapiMergeError) throw new CodedFailure(\"merge-failed\", err.message);\n        throw err;\n      }\n      const {\n        text, modified, modifiedOperationIds, pathItemModified, removed, quoted, pathItemQuoted, pathItemStale,\n        componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved,\n      } = merge;\n      if (text !== null) {\n        writes.push(planWrite(livingOpenapi, text));\n        // The parenthesised list names the OPERATIONS the delta merged, and a\n        // delta whose whole change is a component has none — so this printed\n        // `merged ()`, the same empty-parenthesis lie the create branch above\n        // is commented for: it reads as \"this merge wrote nothing\" about a\n        // merge that just published a shared schema to every consumer of the\n        // fleet. Name the components it added instead, and drop the\n        // parentheses entirely when there is nothing to put in them — a delta\n        // that only EDITED existing surfaces is named by the lines below.\n        const mergedNames = ops.length > 0 ? ops : componentsAdded.map((comp) => `component ${comp}`);\n        say(`  openapi: ${svc} — merged${mergedNames.length > 0 ? ` (${mergedNames.join(\", \")})` : \"\"}`);\n      }\n      // Asked whatever the merge wrote, for the event planner's reason: an\n      // `info`-only delta merges nothing, and archived in silence.\n      warnInfoDrift(plan, say, {\n        svc, code: \"openapi.info-not-merged\", file: \"openapi.yaml\", carries: \"paths and components\",\n        labels: infoDrift(parse(livingText), parse(featText)),\n      });\n      if (removed.length > 0) {\n        openapiRemovals.push({ service: svc, operations: removed });\n        for (const label of removed) say(`      - removes ${label}`);\n      }\n      // The quote and stale lines (./verdict-lines.ts says why each is said).\n      sayQuoted(say, quoted);\n      sayQuoted(say, pathItemQuoted.map((label) => `path-level ${label}`));\n      sayQuoted(say, componentsQuoted.map((comp) => `component ${comp}`));\n      sayStale(say, pathItemStale.map((label) => `path-level ${label}`));\n      sayStale(say, componentsStale.map((comp) => `component ${comp}`));\n      for (const label of modified) {\n        // Who the overwrite lands on: the living fleet's consumers of the\n        // operation, through `loam diff`'s own scan (./consumers.ts). An\n        // operation with no operationId on either side has nothing anyone can\n        // name it by, so the warning stays the sentence it always was.\n        const id = modifiedOperationIds.get(label);\n        const named = id === undefined ? null : consumerClause(await config.consumers.op(svc, id));\n        warnOverwrite(plan, say, {\n          svc, code: \"openapi.op-modified\", label, named,\n          message: `${svc}: the delta redefines ${label}, which the living OpenAPI already has — the merge overwrites the living operation wholesale`,\n        });\n      }\n      for (const label of pathItemModified) {\n        warnOverwrite(plan, say, {\n          svc, code: \"openapi.path-item-modified\", label: `path-level ${label}`,\n          message: `${svc}: the delta redefines the path-level key ${label}, which the living OpenAPI already has — the merge overwrites it wholesale, and it applies to EVERY operation on that path, including ones this feature never mentions`,\n        });\n      }\n      for (const comp of componentsModified) {\n        warnOverwrite(plan, say, {\n          svc, code: \"openapi.component-modified\", label: `component ${comp}`,\n          message: `${svc}: the delta declares component '${comp}', which the living OpenAPI already defines differently — the merge overwrites the living component wholesale`,\n        });\n      }\n      for (const u of unresolved) {\n        planGates.push({\n          severity: \"error\",\n          code: \"openapi.ref-unresolved\",\n          subject: svc,\n          message: `${svc}: $ref '${u.ref}' (referenced from ${u.from}) resolves in neither the feature's openapi.yaml nor the living one — the merged document would carry a dangling reference`,\n        });\n      }\n    }\n  }\n}\n\n/**\n * Does this contract describe no surface at all — no path, no webhook, and no\n * component in any section? Only the document's frame is left (`openapi`,\n * `info`, `servers`, `tags`), which is a title and nothing anyone can call.\n *\n * Conservative in one direction: anything that is not an empty mapping where a\n * mapping belongs counts as content, so a document this cannot classify is\n * created exactly as before. The reader above has already refused one that\n * does not parse.\n */\nfunction describesNothing(text: string): boolean {\n  let doc: unknown;\n  try {\n    doc = parse(text);\n  } catch {\n    // Not a document this can classify, so it is content: created as before.\n    return false;\n  }\n  if (doc === null || doc === undefined) return true;\n  if (!isRecord(doc)) return false;\n  const components = doc[\"components\"];\n  const sections = components === undefined || components === null ? [] : isRecord(components) ? Object.values(components) : [components];\n  return [doc[\"paths\"], doc[\"webhooks\"], ...sections].every(isEmptyMapping);\n}\n\nfunction isEmptyMapping(value: unknown): boolean {\n  return value === undefined || value === null || (isRecord(value) && Object.keys(value).length === 0);\n}\n"]}

package/dist/commands/archive/plan/contracts/verdict-lines.js

@@ -0,0 +1,103 @@
+/**
+ * The plan lines a contract merge's verdicts print — the quote, the stale
+ * baseline, the overwrite and the `info` the merge does not carry — spelled
+ * once for both planners
+ * (./openapi.ts, ./asyncapi.ts), which used to print them in fourteen parallel
+ * loops. Every surface reaches the reader by exactly the same sentence an
+ * operation or a slot does, because it is graded by exactly the same verdict;
+ * one spelling is what keeps the two axes from describing one verdict in two
+ * sentences. The label prefix (`path-level …`, `component …`, `components.…`)
+ * stays at the call site: it is the one part that differs.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { withoutFeatureKeysDeep } from "../../../../core/openapi/digest.js";
+import { isRecord } from "../../../../core/kernel/records.js";
+import { compareIds } from "../../../../core/repo/entries.js";
+/**
+ * Said out loud, because "the plan wrote less than my delta spells" is the one
+ * thing a reader cannot infer from a merged file. Not a warning: quoting the
+ * contract around your change is correct authoring, and leaving the quote
+ * alone is the correct merge. The path-level and component quotes get the
+ * same sentence for the same reason.
+ */
+export function sayQuoted(say, labels) {
+    for (const label of labels)
+        say(`      · quotes ${label} — unchanged since it was pinned, left as living has it`);
+}
+/**
+ * Stale surfaces reaching the merge at all means --approve pushed past the
+ * gate's `openapi.baseline-stale` / `asyncapi.baseline-stale` — the plan still
+ * names what it cost.
+ */
+export function sayStale(say, labels) {
+    for (const label of labels) {
+        say(`      ⚠ stale baseline on ${label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
+    }
+}
+/**
+ * Warn about one overwrite and print it. The consumer clause, when there is
+ * one, ends both the warning's message and the printed line, and its evidence
+ * rides as the warning's `details` and as indented lines under it.
+ */
+export function warnOverwrite(plan, say, overwrite) {
+    const named = overwrite.named ?? null;
+    const clause = named === null ? "" : `; ${named.clause}`;
+    plan.planWarns.push({
+        severity: "warn",
+        code: overwrite.code,
+        subject: overwrite.svc,
+        message: overwrite.message + clause,
+        ...(named === null ? {} : { details: named.details }),
+    });
+    say(`      ⚠ overwrites ${overwrite.label} — the living definition differs${clause}`);
+    for (const line of named?.details ?? [])
+        say(`          ${line}`);
+}
+/**
+ * The `info` keys a feature's contract spells differently from the living one,
+ * as `info.<key>` labels, sorted — empty when the delta writes no `info`, or
+ * writes exactly what living has.
+ *
+ * Neither merge carries `info` (nor any root key outside the sections it
+ * merges: `../../../../core/asyncapi/merge/markers.ts` names what those are),
+ * and that is a decision rather than a gap — a delta is a diff of operations
+ * and slots, and its `info` is most often the scaffold's or a copy. But a
+ * delta that DID move it — a new version, a rewritten description — lost the
+ * change with exit 0 and nothing in the plan, so the reader learned it from
+ * the living file weeks later. Only keys the delta declares are compared: a
+ * key living has and the delta leaves out is a key nobody asked to change.
+ * Feature bookkeeping is never compared: an `x-loam-*` key of `info` itself is
+ * skipped, and the merges' own markers are stripped from the values below it
+ * (`withoutFeatureKeysDeep`), so a pin can never read as drift.
+ */
+export function infoDrift(livingPlain, featurePlain) {
+    const feature = isRecord(featurePlain) ? featurePlain.info : undefined;
+    if (!isRecord(feature))
+        return [];
+    const living = isRecord(livingPlain) && isRecord(livingPlain.info) ? livingPlain.info : {};
+    return Object.keys(feature)
+        .filter((key) => !key.startsWith("x-loam-"))
+        .filter((key) => !isDeepStrictEqual(withoutFeatureKeysDeep(feature[key]), living[key]))
+        .map((key) => `info.${key}`)
+        .sort(compareIds);
+}
+/**
+ * Warn about one contract's `info` drift and print it. A warning, not a gate:
+ * keeping the living `info` is the merge working as designed, and the remedy —
+ * edit the living file in the same change — is the author's call. What must
+ * not happen is the silence.
+ */
+export function warnInfoDrift(plan, say, drift) {
+    if (drift.labels.length === 0)
+        return;
+    const which = drift.labels.join(", ");
+    plan.planWarns.push({
+        severity: "warn",
+        code: drift.code,
+        subject: drift.svc,
+        message: `${drift.svc}: the delta's ${which} differ(s) from the living ${drift.file} — the merge carries ${drift.carries} and never ` +
+            `info, so the living contract keeps its own. If it should move, edit the living ${drift.file} in this change.`,
+    });
+    say(`      ⚠ info not merged — the delta's ${which} differ(s) from the living ${drift.file}, which keeps its own`);
+}
+//# sourceMappingURL=verdict-lines.js.map