@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/commands/archive/archive.js

@@ -1,16 +1,24 @@
-import { loadConfig } from "../../core/envelope/config.js";
-import { fail, reportNoConfig } from "../../core/envelope/json.js";
+import { CodedFailure, configOrRefuse, fail } from "../../core/envelope/json.js";
 import { message } from "../../core/staging/commit.js";
 import { acquireDocsLock, DocsBusyError } from "../../core/staging/lock.js";
-import { ArchiveFailure } from "./plan/refusal.js";
+import {} from "./plan/refusal.js";
 import { archiveLocked } from "./run.js";
 import { LandscapeSpliceError } from "../../core/c4/splice/contract.js";
 import { NotUtf8Error } from "../../core/staging/writes.js";
 import { OpenapiMergeError } from "../../core/openapi/merge/error.js";
 import { InterruptedCommitError } from "../../core/staging/interrupted.js";
+/**
+ * The code a failed archive answers with. A `CodedFailure` is thrown from the
+ * plan phase (nothing written yet) and from the commit's rollback path (whose
+ * message says whether the rollback held). Anything that escapes runArchive and
+ * matches no arm below is a bug, and reports as `internal`.
+ */
 function archiveErrorCode(err) {
-    if (err instanceof ArchiveFailure)
+    if (err instanceof CodedFailure)
         return err.code;
+    // Another writer holds the docs repo — the lock is taken refuse-fast below.
+    if (err instanceof DocsBusyError)
+        return "docs-busy";
     // Every splice refusal is the mechanical merge answer — see the class.
     if (err instanceof LandscapeSpliceError)
         return "merge-failed";
@@ -32,7 +40,7 @@ export function registerArchive(program) {
     program
         .command("archive")
         .argument("<featureId>", "feature id, e.g. FEAT-101")
-        .description("Merge a shipped feature's deltas into the living specs + model, then archive it")
+        .description("Merge a finished feature's deltas into the living specs + model, then archive it (checks the documents, not the code)")
         .option("--approve", "archive despite GATING coherence issues (may corrupt the living docs); advisory warnings never block")
         .option("--dry-run", "print the whole merge plan and write nothing")
         .option("--json", "emit the machine contract instead of the human view")
@@ -52,21 +60,10 @@ export function registerArchive(program) {
 }
 async function runArchive(featureId, opts) {
     const json = opts.json === true;
-    const loaded = await loadConfig();
-    if (loaded.kind !== "loaded") {
-        reportNoConfig(json, loaded);
+    const config = await configOrRefuse(json);
+    if (config === null)
         return;
-    }
-    const config = loaded.config;
-    let release;
-    try {
-        release = await acquireDocsLock(config.docsDir);
-    }
-    catch (err) {
-        if (err instanceof DocsBusyError)
-            throw new ArchiveFailure("docs-busy", err.message);
-        throw err;
-    }
+    const release = await acquireDocsLock(config.docsDir);
     try {
         await archiveLocked(config, featureId, opts);
     }

package/dist/commands/archive/archive.js.map

@@ -1 +1 @@
-{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../src/commands/archive/archive.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam archive`: fold a finished feature's three axes into the living docs.\n *\n * Registration and the lock, nothing else. Everything the command actually does\n * is under `./plan/` and `./run.ts`, in that order — the gate refuses, the plan\n * computes, the commit swaps.\n */\nimport type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { fail, reportNoConfig, type ErrorCode } from \"../../core/envelope/json.js\";\nimport { message } from \"../../core/staging/commit.js\";\nimport { acquireDocsLock, DocsBusyError } from \"../../core/staging/lock.js\";\nimport { ArchiveFailure, type ArchiveOptions } from \"./plan/refusal.js\";\nimport { archiveLocked } from \"./run.js\";\nimport { LandscapeSpliceError } from \"../../core/c4/splice/contract.js\";\nimport { NotUtf8Error } from \"../../core/staging/writes.js\";\nimport { OpenapiMergeError } from \"../../core/openapi/merge/error.js\";\nimport { InterruptedCommitError } from \"../../core/staging/interrupted.js\";\n\n\nfunction archiveErrorCode(err: unknown): ErrorCode {\n  if (err instanceof ArchiveFailure) return err.code;\n  // Every splice refusal is the mechanical merge answer — see the class.\n  if (err instanceof LandscapeSpliceError) return \"merge-failed\";\n  if (err instanceof NotUtf8Error) return \"merge-failed\";\n  // The merge branch wraps its own call and re-throws as merge-failed; the\n  // create branch (`stripOpenapiRemovalMarkers`) does not, so one unreadable\n  // feature contract answered merge-failed or `internal` depending on whether\n  // the service already had a living openapi.yaml. The code answers \"can I\n  // trust the repo?\", and that answer does not turn on which side of the merge\n  // the document sat on.\n  if (err instanceof OpenapiMergeError) return \"merge-failed\";\n  if (err instanceof InterruptedCommitError) return \"commit-interrupted\";\n  return \"internal\";\n}\n\n\nexport function registerArchive(program: Command): void {\n  program\n    .command(\"archive\")\n    .argument(\"<featureId>\", \"feature id, e.g. FEAT-101\")\n    .description(\"Merge a shipped feature's deltas into the living specs + model, then archive it\")\n    .option(\"--approve\", \"archive despite GATING coherence issues (may corrupt the living docs); advisory warnings never block\")\n    .option(\"--dry-run\", \"print the whole merge plan and write nothing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureId: string, opts: ArchiveOptions) => {\n      const json = opts.json === true;\n      try {\n        await runArchive(featureId, opts);\n      } catch (err) {\n        // Plan-phase failures happen before any write; commit-phase failures are\n        // rolled back by runArchive, which says so in the message it throws.\n        // A file loam cannot decode is one it cannot merge, and that is the same\n        // answer as any other merge it could not compute: nothing was written.\n        fail(json, archiveErrorCode(err), `archive ${featureId} failed: ${message(err)}`);\n      }\n    });\n}\n\nasync function runArchive(featureId: string, opts: ArchiveOptions): Promise<void> {\n  const json = opts.json === true;\n  const loaded = await loadConfig();\n  if (loaded.kind !== \"loaded\") {\n    reportNoConfig(json, loaded);\n    return;\n  }\n  const config = loaded.config;\n  let release: () => Promise<void>;\n  try {\n    release = await acquireDocsLock(config.docsDir);\n  } catch (err) {\n    if (err instanceof DocsBusyError) throw new ArchiveFailure(\"docs-busy\", err.message);\n    throw err;\n  }\n  try {\n    await archiveLocked(config, featureId, opts);\n  } finally {\n    await release();\n  }\n}\n"]}
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../src/commands/archive/archive.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,IAAI,EAAkB,MAAM,6BAA6B,CAAC;AACjG,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAuB,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAE3E;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,GAAY;IACpC,IAAI,GAAG,YAAY,YAAY;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC;IACjD,4EAA4E;IAC5E,IAAI,GAAG,YAAY,aAAa;QAAE,OAAO,WAAW,CAAC;IACrD,uEAAuE;IACvE,IAAI,GAAG,YAAY,oBAAoB;QAAE,OAAO,cAAc,CAAC;IAC/D,IAAI,GAAG,YAAY,YAAY;QAAE,OAAO,cAAc,CAAC;IACvD,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,6EAA6E;IAC7E,uBAAuB;IACvB,IAAI,GAAG,YAAY,iBAAiB;QAAE,OAAO,cAAc,CAAC;IAC5D,IAAI,GAAG,YAAY,sBAAsB;QAAE,OAAO,oBAAoB,CAAC;IACvE,OAAO,UAAU,CAAC;AACpB,CAAC;AAGD,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,QAAQ,CAAC,aAAa,EAAE,2BAA2B,CAAC;SACpD,WAAW,CAAC,uHAAuH,CAAC;SACpI,MAAM,CAAC,WAAW,EAAE,sGAAsG,CAAC;SAC3H,MAAM,CAAC,WAAW,EAAE,8CAA8C,CAAC;SACnE,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,SAAiB,EAAE,IAAoB,EAAE,EAAE;QACxD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,yEAAyE;YACzE,qEAAqE;YACrE,yEAAyE;YACzE,uEAAuE;YACvE,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAAE,WAAW,SAAS,YAAY,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,SAAiB,EAAE,IAAoB;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO;IAC5B,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC","sourcesContent":["/**\n * `loam archive`: fold a finished feature's three axes into the living docs.\n *\n * Registration and the lock, nothing else. Everything the command actually does\n * is under `./plan/` and `./run.ts`, in that order — the gate refuses, the plan\n * computes, the commit swaps.\n */\nimport type { Command } from \"commander\";\nimport { CodedFailure, configOrRefuse, fail, type ErrorCode } from \"../../core/envelope/json.js\";\nimport { message } from \"../../core/staging/commit.js\";\nimport { acquireDocsLock, DocsBusyError } from \"../../core/staging/lock.js\";\nimport { type ArchiveOptions } from \"./plan/refusal.js\";\nimport { archiveLocked } from \"./run.js\";\nimport { LandscapeSpliceError } from \"../../core/c4/splice/contract.js\";\nimport { NotUtf8Error } from \"../../core/staging/writes.js\";\nimport { OpenapiMergeError } from \"../../core/openapi/merge/error.js\";\nimport { InterruptedCommitError } from \"../../core/staging/interrupted.js\";\n\n/**\n * The code a failed archive answers with. A `CodedFailure` is thrown from the\n * plan phase (nothing written yet) and from the commit's rollback path (whose\n * message says whether the rollback held). Anything that escapes runArchive and\n * matches no arm below is a bug, and reports as `internal`.\n */\nfunction archiveErrorCode(err: unknown): ErrorCode {\n  if (err instanceof CodedFailure) return err.code;\n  // Another writer holds the docs repo — the lock is taken refuse-fast below.\n  if (err instanceof DocsBusyError) return \"docs-busy\";\n  // Every splice refusal is the mechanical merge answer — see the class.\n  if (err instanceof LandscapeSpliceError) return \"merge-failed\";\n  if (err instanceof NotUtf8Error) return \"merge-failed\";\n  // The merge branch wraps its own call and re-throws as merge-failed; the\n  // create branch (`stripOpenapiRemovalMarkers`) does not, so one unreadable\n  // feature contract answered merge-failed or `internal` depending on whether\n  // the service already had a living openapi.yaml. The code answers \"can I\n  // trust the repo?\", and that answer does not turn on which side of the merge\n  // the document sat on.\n  if (err instanceof OpenapiMergeError) return \"merge-failed\";\n  if (err instanceof InterruptedCommitError) return \"commit-interrupted\";\n  return \"internal\";\n}\n\n\nexport function registerArchive(program: Command): void {\n  program\n    .command(\"archive\")\n    .argument(\"<featureId>\", \"feature id, e.g. FEAT-101\")\n    .description(\"Merge a finished feature's deltas into the living specs + model, then archive it (checks the documents, not the code)\")\n    .option(\"--approve\", \"archive despite GATING coherence issues (may corrupt the living docs); advisory warnings never block\")\n    .option(\"--dry-run\", \"print the whole merge plan and write nothing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureId: string, opts: ArchiveOptions) => {\n      const json = opts.json === true;\n      try {\n        await runArchive(featureId, opts);\n      } catch (err) {\n        // Plan-phase failures happen before any write; commit-phase failures are\n        // rolled back by runArchive, which says so in the message it throws.\n        // A file loam cannot decode is one it cannot merge, and that is the same\n        // answer as any other merge it could not compute: nothing was written.\n        fail(json, archiveErrorCode(err), `archive ${featureId} failed: ${message(err)}`);\n      }\n    });\n}\n\nasync function runArchive(featureId: string, opts: ArchiveOptions): Promise<void> {\n  const json = opts.json === true;\n  const config = await configOrRefuse(json);\n  if (config === null) return;\n  const release = await acquireDocsLock(config.docsDir);\n  try {\n    await archiveLocked(config, featureId, opts);\n  } finally {\n    await release();\n  }\n}\n"]}

package/dist/commands/archive/closing.js

@@ -0,0 +1,42 @@
+/**
+ * The advisories that mean "archive the other feature first" AND name an error
+ * the fleet gate reports once this one lands alone — `spec-api.op-undefined`,
+ * `spine.op-undefined`, `spec-event.message-undefined`,
+ * `spine.message-unproduced`. The delta pair (`delta.modified-pending`,
+ * `delta.removed-pending`) is NOT here, because the line below would be false
+ * for it: the merge appends a MODIFIED it cannot find and drops a REMOVED one,
+ * so `validate --all` reports nothing — the cost lands on the OTHER feature's
+ * archive (`delta.added-duplicate`) or nowhere, which is that warning's own
+ * sentence to say.
+ */
+const ORDERING = new Set([
+    "spec-api.op-pending",
+    "c4-api.op-pending",
+    "spec-event.message-pending",
+    "c4-event.message-pending",
+]);
+/** The `⚠` lines owed in place of the closing claim — empty when the claim is true. */
+export function outstandingLines(state) {
+    const lines = [];
+    // One line per stale file rather than one line listing them: each names a file
+    // a reader opens, and a comma-joined series would have to choose a verb that
+    // reads wrong for one of the two counts.
+    for (const path of state.staleViews) {
+        lines.push(`  ⚠ ${path} no longer matches the tree and this map — run \`loam subsystem sync\`.`);
+    }
+    for (const w of state.planWarns)
+        if (w.severity === "error")
+            lines.push(`  ⚠ ${w.message}`);
+    const ordering = state.advisory.filter((i) => ORDERING.has(i.code));
+    if (ordering.length > 0) {
+        lines.push(`  ⚠ ${state.dryRun ? "archiving this now lands" : "this archive landed"} ahead of ${ordering.length} change(s) still in flight ` +
+            "that it waits on (the pending warnings above) — `loam validate --all` reports each as an error until that feature archives too.");
+    }
+    if (state.overridden.length > 0) {
+        lines.push(state.dryRun
+            ? `  ⚠ --approve would merge past ${state.overridden.length} gating issue(s) — the living docs would carry them; \`loam validate --all\` says what they cost.`
+            : `  ⚠ merged past ${state.overridden.length} gating issue(s) with --approve — the living docs carry them now; \`loam validate --all\` says what they cost.`);
+    }
+    return lines;
+}
+//# sourceMappingURL=closing.js.map

package/dist/commands/archive/closing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closing.js","sourceRoot":"","sources":["../../../src/commands/archive/closing.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;;GAUG;AACH,MAAM,QAAQ,GAA2B,IAAI,GAAG,CAAY;IAC1D,qBAAqB;IACrB,mBAAmB;IACnB,4BAA4B;IAC5B,0BAA0B;CAC3B,CAAC,CAAC;AAgBH,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,6EAA6E;IAC7E,yCAAyC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,yEAAyE,CAAC,CAAC;IACnG,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS;QAAE,IAAI,CAAC,CAAC,QAAQ,KAAK,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CACR,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,qBAAqB,aAAa,QAAQ,CAAC,MAAM,6BAA6B;YAC/H,iIAAiI,CACpI,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CACR,KAAK,CAAC,MAAM;YACV,CAAC,CAAC,kCAAkC,KAAK,CAAC,UAAU,CAAC,MAAM,mGAAmG;YAC9J,CAAC,CAAC,mBAAmB,KAAK,CAAC,UAAU,CAAC,MAAM,gHAAgH,CAC/J,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["/**\n * What the archive still owes the fleet after its merge — the lines that stand\n * in for \"living spec + landscape are now complete + current.\".\n *\n * That closing line is a claim about the whole docs repo, and it is the line a\n * reader stops at. It may be printed only when this archive leaves nothing the\n * next `validate --all` will fail on, so every reason it cannot be is listed\n * here, once, for the real run and the dry run alike. The dry run used to print\n * none of them: `--json` carried `service.no-model` in `warnings`, the real run\n * printed it after the commit, and the text dry run — the one a person reads\n * before deciding — said nothing (the real-fleet review, 2026-10-21).\n *\n * FOUR REASONS, each a breach the next `validate --all` reports:\n *\n *  - a plan finding of ERROR severity that does not gate — `service.no-model`,\n *    a service this archive brings in without writing its model (a binding the\n *    map gains with no directory; one whose directory the archive creates and\n *    the merged map draws gets an empty model, `plan/landscape.ts`). Read off the\n *    severity, not a code list: the plan files an error exactly when it knows\n *    validate will, and a second list here is the copy that drifts;\n *  - an advisory that orders this feature behind another one still in flight\n *    and softens a fleet-gate error (four of the `*-pending` family): archived\n *    first, the merge lands a reference the other feature's merge has not made\n *    true yet;\n *  - gating issues the caller merged past with `--approve`;\n *  - a generated views file the new map no longer matches — known only once\n *    the commit has happened, so the dry run cannot name it.\n */\nimport type { Issue, IssueCode } from \"../../core/vocabulary/issue.js\";\n\n/**\n * The advisories that mean \"archive the other feature first\" AND name an error\n * the fleet gate reports once this one lands alone — `spec-api.op-undefined`,\n * `spine.op-undefined`, `spec-event.message-undefined`,\n * `spine.message-unproduced`. The delta pair (`delta.modified-pending`,\n * `delta.removed-pending`) is NOT here, because the line below would be false\n * for it: the merge appends a MODIFIED it cannot find and drops a REMOVED one,\n * so `validate --all` reports nothing — the cost lands on the OTHER feature's\n * archive (`delta.added-duplicate`) or nowhere, which is that warning's own\n * sentence to say.\n */\nconst ORDERING: ReadonlySet<IssueCode> = new Set<IssueCode>([\n  \"spec-api.op-pending\",\n  \"c4-api.op-pending\",\n  \"spec-event.message-pending\",\n  \"c4-event.message-pending\",\n]);\n\n/** Everything the archive knows about what it leaves behind. */\nexport interface Outstanding {\n  /** The coherence gate's advisory warnings. */\n  advisory: readonly Issue[];\n  /** The plan's own findings — overwrites, and the services it creates with no model. */\n  planWarns: readonly Issue[];\n  /** Gating issues `--approve` walked past. */\n  overridden: readonly Issue[];\n  /** Generated views the committed map no longer matches; empty before a commit. */\n  staleViews: readonly string[];\n  /** Phrase it as what WOULD remain — the dry run's tense. */\n  dryRun: boolean;\n}\n\n/** The `⚠` lines owed in place of the closing claim — empty when the claim is true. */\nexport function outstandingLines(state: Outstanding): string[] {\n  const lines: string[] = [];\n  // One line per stale file rather than one line listing them: each names a file\n  // a reader opens, and a comma-joined series would have to choose a verb that\n  // reads wrong for one of the two counts.\n  for (const path of state.staleViews) {\n    lines.push(`  ⚠ ${path} no longer matches the tree and this map — run \\`loam subsystem sync\\`.`);\n  }\n  for (const w of state.planWarns) if (w.severity === \"error\") lines.push(`  ⚠ ${w.message}`);\n  const ordering = state.advisory.filter((i) => ORDERING.has(i.code));\n  if (ordering.length > 0) {\n    lines.push(\n      `  ⚠ ${state.dryRun ? \"archiving this now lands\" : \"this archive landed\"} ahead of ${ordering.length} change(s) still in flight ` +\n        \"that it waits on (the pending warnings above) — `loam validate --all` reports each as an error until that feature archives too.\",\n    );\n  }\n  if (state.overridden.length > 0) {\n    lines.push(\n      state.dryRun\n        ? `  ⚠ --approve would merge past ${state.overridden.length} gating issue(s) — the living docs would carry them; \\`loam validate --all\\` says what they cost.`\n        : `  ⚠ merged past ${state.overridden.length} gating issue(s) with --approve — the living docs carry them now; \\`loam validate --all\\` says what they cost.`,\n    );\n  }\n  return lines;\n}\n"]}

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

@@ -8,7 +8,7 @@
  */
 import { existsSync } from "node:fs";
 import { parse } from "yaml";
-import { repoPath } from "../../../../core/envelope/json.js";
+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";
@@ -18,8 +18,9 @@ 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 { ArchiveFailure } from "../refusal.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")
@@ -28,7 +29,7 @@ function modifiedCode(section) {
 }
 export async function planAsyncapiContracts(config, gated, plan, say) {
     const { featureDir, deltaServices } = gated;
-    const { writes, planWarns, planGates, asyncapiRemovals } = plan;
+    const { writes, planGates, asyncapiRemovals } = plan;
     for (const svc of deltaServices) {
         const featAsyncapi = featureSpecPaths(featureDir, svc).asyncapi;
         if (!existsSync(featAsyncapi))
@@ -40,7 +41,7 @@ export async function planAsyncapiContracts(config, gated, plan, say) {
         // 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 ArchiveFailure("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`);
+            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:
@@ -89,7 +90,8 @@ export async function planAsyncapiContracts(config, gated, plan, say) {
                 say(`  asyncapi: ${svc} — created (${names.join(", ")})`);
                 continue;
             }
-            const merge = mergeAsyncapiSlots(await readUtf8(livingAsyncapi), featText, svc);
+            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
@@ -108,56 +110,48 @@ export async function planAsyncapiContracts(config, gated, plan, say) {
             }
             else if (surfaces.length > 0) {
                 // "The plan wrote less than my delta spells" is the sentence a reader
-                // cannot infer from an unchanged file — this file's own comment below
-                // 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.
+                // 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}`);
             }
-            // 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.
-            for (const slot of merge.quoted) {
-                say(`      · quotes ${slot.label} — unchanged since it was pinned, left as living has it`);
-            }
-            // The surface half's mirrors of the three lines around them. A component
-            // surface reaches the reader by exactly the same three sentences a slot
-            // does, because it is graded by exactly the same verdict.
-            for (const id of merge.componentsQuoted) {
-                say(`      · quotes components.${id} — unchanged since it was pinned, left as living has it`);
-            }
-            // Stale surfaces reaching the merge at all means --approve pushed past
-            // the gate's asyncapi.baseline-stale — the plan still names what it cost.
-            for (const slot of merge.baselineStale) {
-                say(`      ⚠ stale baseline on ${slot.label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
-            }
-            for (const id of merge.componentsStale) {
-                say(`      ⚠ stale baseline on components.${id} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
-            }
+            // 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) {
-                planWarns.push({
-                    severity: "warn",
-                    code: "asyncapi.component-modified",
-                    subject: svc,
+                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`,
                 });
-                say(`      ⚠ overwrites components.${id} — the living definition differs`);
             }
             for (const slot of merge.modified) {
-                planWarns.push({
-                    severity: "warn",
-                    code: modifiedCode(slot.section),
-                    subject: svc,
+                // 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`,
                 });
-                say(`      ⚠ overwrites ${slot.label} — the living definition differs`);
             }
             for (const ref of merge.unresolved) {
                 planGates.push({
@@ -170,7 +164,7 @@ export async function planAsyncapiContracts(config, gated, plan, say) {
         }
         catch (err) {
             if (err instanceof AsyncapiMergeError)
-                throw new ArchiveFailure("merge-failed", err.message);
+                throw new CodedFailure("merge-failed", err.message);
             throw err;
         }
     }

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

@@ -1 +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 { 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 { ArchiveFailure } from \"../refusal.js\";\nimport { type Gated, type Plan } from \"../state.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 },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes, planWarns, 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 ArchiveFailure(\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 merge: AsyncapiMergeResult = mergeAsyncapiSlots(await readUtf8(livingAsyncapi), 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 — this file's own comment below\n        // names it for slots, and a components-only delta is the shape where\n        // silence is indistinguishable from the defect that made it merge\n        // nothing at all. Not a warning: every surface being a quote is\n        // 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      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      // Said out loud, because \"the plan wrote less than my delta spells\" is\n      // the one thing a reader cannot infer from a merged file. Not a warning:\n      // quoting the contract around your change is correct authoring, and\n      // leaving the quote alone is the correct merge.\n      for (const slot of merge.quoted) {\n        say(`      · quotes ${slot.label} — unchanged since it was pinned, left as living has it`);\n      }\n      // The surface half's mirrors of the three lines around them. A component\n      // surface reaches the reader by exactly the same three sentences a slot\n      // does, because it is graded by exactly the same verdict.\n      for (const id of merge.componentsQuoted) {\n        say(`      · quotes components.${id} — unchanged since it was pinned, left as living has it`);\n      }\n      // Stale surfaces reaching the merge at all means --approve pushed past\n      // the gate's asyncapi.baseline-stale — the plan still names what it cost.\n      for (const slot of merge.baselineStale) {\n        say(`      ⚠ stale baseline on ${slot.label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);\n      }\n      for (const id of merge.componentsStale) {\n        say(`      ⚠ stale baseline on components.${id} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);\n      }\n      for (const id of merge.componentsModified) {\n        planWarns.push({\n          severity: \"warn\",\n          code: \"asyncapi.component-modified\",\n          subject: svc,\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        say(`      ⚠ overwrites components.${id} — the living definition differs`);\n      }\n      for (const slot of merge.modified) {\n        planWarns.push({\n          severity: \"warn\",\n          code: modifiedCode(slot.section),\n          subject: svc,\n          message: `${svc}: the delta redefines ${slot.label}, which the living AsyncAPI already has — the merge overwrites the living slot wholesale`,\n        });\n        say(`      ⚠ overwrites ${slot.label} — the living definition differs`);\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 ArchiveFailure(\"merge-failed\", err.message);\n      throw err;\n    }\n  }\n}\n"]}
+{"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"]}