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

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 { 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"]}

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

@@ -0,0 +1,159 @@
+/**
+ * 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 { 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 { 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 { ArchiveFailure } from "../refusal.js";
+import {} from "../state.js";
+export async function planOpenapiContracts(config, gated, plan, say) {
+    const { featureDir, deltaServices } = gated;
+    const { writes, planWarns, 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 ArchiveFailure("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);
+            writes.push(planWrite(livingOpenapi, content));
+            say(`  openapi: ${svc} — created (${ops.join(", ")})`);
+        }
+        else {
+            let merge;
+            try {
+                merge = mergeOpenapiPaths(await readUtf8(livingOpenapi), featText, svc);
+            }
+            catch (err) {
+                if (err instanceof OpenapiMergeError)
+                    throw new ArchiveFailure("merge-failed", err.message);
+                throw err;
+            }
+            const { text, modified, 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(", ")})` : ""}`);
+            }
+            if (removed.length > 0) {
+                openapiRemovals.push({ service: svc, operations: removed });
+                for (const label of removed)
+                    say(`      - removes ${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. The path-level and
+            // component quotes get the same sentence for the same reason.
+            for (const label of quoted)
+                say(`      · quotes ${label} — unchanged since it was pinned, left as living has it`);
+            for (const label of pathItemQuoted) {
+                say(`      · quotes path-level ${label} — unchanged since it was pinned, left as living has it`);
+            }
+            for (const comp of componentsQuoted) {
+                say(`      · quotes component ${comp} — 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 — the plan still names what it cost.
+            for (const label of pathItemStale) {
+                say(`      ⚠ stale baseline on path-level ${label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
+            }
+            for (const comp of componentsStale) {
+                say(`      ⚠ stale baseline on component ${comp} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);
+            }
+            for (const label of modified) {
+                planWarns.push({
+                    severity: "warn",
+                    code: "openapi.op-modified",
+                    subject: svc,
+                    message: `${svc}: the delta redefines ${label}, which the living OpenAPI already has — the merge overwrites the living operation wholesale`,
+                });
+                say(`      ⚠ overwrites ${label} — the living definition differs`);
+            }
+            for (const label of pathItemModified) {
+                planWarns.push({
+                    severity: "warn",
+                    code: "openapi.path-item-modified",
+                    subject: svc,
+                    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`,
+                });
+                say(`      ⚠ overwrites path-level ${label} — the living definition differs`);
+            }
+            for (const comp of componentsModified) {
+                planWarns.push({
+                    severity: "warn",
+                    code: "openapi.component-modified",
+                    subject: svc,
+                    message: `${svc}: the delta declares component '${comp}', which the living OpenAPI already defines differently — the merge overwrites the living component wholesale`,
+                });
+                say(`      ⚠ overwrites component ${comp} — the living definition differs`);
+            }
+            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`,
+                });
+            }
+        }
+    }
+}
+//# 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 { 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 { 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 { ArchiveFailure } from \"../refusal.js\";\nimport { type Gated, type Plan } from \"../state.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 },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes, planWarns, 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 ArchiveFailure(\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      writes.push(planWrite(livingOpenapi, content));\n      say(`  openapi: ${svc} — created (${ops.join(\", \")})`);\n    } else {\n      let merge: OpenapiMergeResult;\n      try {\n        merge = mergeOpenapiPaths(await readUtf8(livingOpenapi), featText, svc);\n      } catch (err) {\n        if (err instanceof OpenapiMergeError) throw new ArchiveFailure(\"merge-failed\", err.message);\n        throw err;\n      }\n      const {\n        text, modified, 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      if (removed.length > 0) {\n        openapiRemovals.push({ service: svc, operations: removed });\n        for (const label of removed) say(`      - removes ${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. The path-level and\n      // component quotes get the same sentence for the same reason.\n      for (const label of quoted) say(`      · quotes ${label} — unchanged since it was pinned, left as living has it`);\n      for (const label of pathItemQuoted) {\n        say(`      · quotes path-level ${label} — unchanged since it was pinned, left as living has it`);\n      }\n      for (const comp of componentsQuoted) {\n        say(`      · quotes component ${comp} — 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 openapi.baseline-stale — the plan still names what it cost.\n      for (const label of pathItemStale) {\n        say(`      ⚠ stale baseline on path-level ${label} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);\n      }\n      for (const comp of componentsStale) {\n        say(`      ⚠ stale baseline on component ${comp} — the living value moved since this delta was pinned; the overwrite is what --approve chose`);\n      }\n      for (const label of modified) {\n        planWarns.push({\n          severity: \"warn\",\n          code: \"openapi.op-modified\",\n          subject: svc,\n          message: `${svc}: the delta redefines ${label}, which the living OpenAPI already has — the merge overwrites the living operation wholesale`,\n        });\n        say(`      ⚠ overwrites ${label} — the living definition differs`);\n      }\n      for (const label of pathItemModified) {\n        planWarns.push({\n          severity: \"warn\",\n          code: \"openapi.path-item-modified\",\n          subject: svc,\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        say(`      ⚠ overwrites path-level ${label} — the living definition differs`);\n      }\n      for (const comp of componentsModified) {\n        planWarns.push({\n          severity: \"warn\",\n          code: \"openapi.component-modified\",\n          subject: svc,\n          message: `${svc}: the delta declares component '${comp}', which the living OpenAPI already defines differently — the merge overwrites the living component wholesale`,\n        });\n        say(`      ⚠ overwrites component ${comp} — the living definition differs`);\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"]}

package/dist/commands/archive/plan/gate.js

@@ -0,0 +1,317 @@
+/**
+ * Every refusal that happens before a byte is planned.
+ *
+ * They are gathered here because they share one doctrine that is easy to lose:
+ * `--approve` overrides judgments about the FEATURE, and nothing else. A service
+ * directory whose name the id grammar refuses, a living document holding git
+ * conflict markers, a requirement outside `## Requirements` — those are
+ * mechanical facts about paths and files, so `--approve` does not reach them,
+ * and the dry run is gated too, since a plan built on one describes a merge loam
+ * must never perform.
+ *
+ * `null` means the refusal has already been printed and the exit code set.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fail, repoPath, sayExplain } from "../../../core/envelope/json.js";
+import { approveOverrides, gatesArchive } from "../../../core/vocabulary/issue.js";
+import { recoverInterruptedCommit } from "../../../core/staging/recovery/recover.js";
+import { readUtf8 } from "../../../core/staging/writes.js";
+import { loadFile } from "../../../core/c4/likec4.js";
+import { archiveDir as archiveRoot, featurePaths, featureSpecPaths, SPEC_AXES } from "../../../core/repo/paths.js";
+import { livingCapabilityPaths } from "../../../core/repo/authored/paths.js";
+import { featureCapabilityDeltas } from "../../../core/capabilities/delta/tree.js";
+import { locateServicePaths } from "../../../core/repo/service-target.js";
+import { featureSpecServices, missingFeatureMessage, resolveFeature } from "../../../core/repo/repo.js";
+import { featureCoherence } from "../../../core/coherence/coherence.js";
+import { invalidSpecServiceFindings, livingMergeConflicts, unknownDeltaServices, } from "../../../core/coherence/living.js";
+import { SEVERITY_MARK } from "../../../core/vocabulary/report.js";
+import { isRequirementsHeading, parseRequirements } from "../../../core/document/parse.js";
+import { refuseFindings, refuseJson, sayRecovery } from "./refusal.js";
+import {} from "./state.js";
+export async function gate(config, featureId, opts, say) {
+    const json = opts.json === true;
+    const dryRun = opts.dryRun === true;
+    // the living docs half-written, and every other command in loam would have
+    // planned against them as if they were the truth. Under the same lock, so the
+    // repair cannot race a writer. It refuses when the half-merged files have been
+    // edited since — that is a human's call, not a merge's.
+    const recovered = await recoverInterruptedCommit(config.docsDir);
+    if (recovered !== null && !json)
+        sayRecovery(recovered);
+    const feature = await resolveFeature(config.docsDir, featureId, "exclude");
+    if (!feature) {
+        fail(json, "unknown-target", await missingFeatureMessage(config.docsDir, featureId));
+        return null;
+    }
+    // The raw argument's last appearance: from here on the feature answers only to
+    // its canonical id — tags, coherence, and the self-exclusion scans all match
+    // on `id`, and `archive FEAT-5-slug` must plan exactly like `archive FEAT-5`.
+    const { id, dirName, dir: featureDir } = feature;
+    // Parse delta.likec4 ONCE for the whole run: the coherence gate and the
+    // architecture merge below read the same file, and loading it spins up a
+    // fresh Langium workspace each time. Nothing writes it in between.
+    const deltaLikec4 = featurePaths(featureDir).delta;
+    const deltaDoc = existsSync(deltaLikec4) ? await loadFile(deltaLikec4) : undefined;
+    const deltaServices = await featureSpecServices(featureDir);
+    // The business corpus's delta tree, walked once HERE and carried on `Gated`:
+    // the conflict-marker scan, the strayed-requirement scan and the merge itself
+    // all ask which capability documents this feature rewrites, and three walks
+    // are three chances to answer differently. `featureCoherence` below walks it
+    // again on its own — it is called without `config.fleet`, the same
+    // no-context path `core/coherence/declared.ts` already documents paying for
+    // the arch delta — so this is not the run's only walk, only the one every
+    // phase downstream of the gate shares.
+    const capabilityDeltas = (config.fleet === undefined
+        ? await featureCapabilityDeltas(featureDir)
+        : await config.fleet.featureCapabilityDeltas(featureDir)).docs;
+    // A `specs/<svc>/` whose NAME is not a legal service id, refused before
+    // anything joins that name into a path: the conflict scan below probes
+    // `services/<svc>/<axis>` with it, and the requirements merge would
+    // materialise `services/<svc>/` from it — a directory `service.id-invalid`
+    // then calls an error on the next `validate --all`, and one no loam command
+    // can address or re-create. The set comes from coherence/living.ts's
+    // `invalidSpecServiceFindings` — the same function validate reads — so the
+    // two gates cannot drift.
+    //
+    // --approve does not apply, exactly as with the conflict-marker refusal
+    // below: --approve overrides judgments about the FEATURE, and a name the id
+    // grammar refuses is a mechanical fact about the path it would become. The
+    // dry run is gated too: a plan built on that name describes a merge loam
+    // must never perform.
+    const illegalServices = await invalidSpecServiceFindings(featureDir);
+    if (illegalServices.length > 0) {
+        const msg = `archive ${id} — BLOCKED: ${illegalServices.length} per-service delta(s) named by an illegal service id; --approve does not override this`;
+        if (json) {
+            refuseFindings("not-coherent", msg, illegalServices, `features/${dirName}`);
+            return null;
+        }
+        console.error(`${msg}:`);
+        for (const f of illegalServices)
+            console.error(`  ✗ ${f.message}`);
+        console.error(`\n--approve does not override this — the directory the merge would create is one loam can never address, mechanically.`);
+        // Every arm in this file refuses by hand — it prints a headline, a list and
+        // a closing sentence rather than the one message `fail()` takes — so the
+        // code and its lookup have to be asked for explicitly. `sayExplain` is
+        // called rather than the format being copied six times, and the code passed
+        // is the SAME one the `--json` branch a few lines up emits: text and
+        // envelope must name one refusal, or a reader who switches modes to find
+        // the code is handed a different answer than the one they saw.
+        sayExplain("not-coherent");
+        process.exitCode = 1;
+        return null;
+    }
+    // Git conflict markers in a LIVING document this merge would rewrite, before
+    // anything else is asked of it. Both sides of somebody's merge are in the
+    // file, so nothing it says is anyone's text — and the requirements rewrite
+    // deletes whichever marker lines fall inside the section it owns, turning a
+    // conflict anyone can see into a file nobody can tell is wrong. Checked ahead
+    // of the coherence gate for `inspectLandscape`'s reason: a conflicted
+    // document parses, so every verdict downstream of it is an opinion about half
+    // of two people's work.
+    //
+    // --approve does not apply, exactly as with the strayed-requirement refusal
+    // below: --approve overrides judgments about the FEATURE, and this is a fact
+    // about the living document.
+    const conflicted = await livingMergeConflicts(config.docsDir, deltaServices, capabilityDeltas.map((d) => d.id));
+    if (conflicted.length > 0) {
+        const msg = `archive ${id} — BLOCKED: ${conflicted.length} living document(s) still hold git conflict markers`;
+        if (json) {
+            refuseFindings("merge-failed", msg, conflicted, `features/${dirName}`);
+            return null;
+        }
+        console.error(`${msg}:`);
+        for (const f of conflicted)
+            console.error(`  ✗ ${f.message}`);
+        console.error(`\n--approve does not override this — the loss is mechanical, not a judgment call.`);
+        sayExplain("merge-failed");
+        process.exitCode = 1;
+        return null;
+    }
+    // Gate: GATING issues block the archive. Severity and gating are two
+    // different questions (issue.ts): errors gate because the merge would write
+    // something wrong, and the rare warning marked `gates` blocks too — the
+    // document is legal but the merge would drop authored content. Advisory
+    // warnings are printed (and carried into --json) but never block, matching
+    // validate's own doctrine (report.ts: "warnings never gate"). --approve
+    // overrides the gating issues ONLY, and must say exactly which ones it is
+    // walking past. A dry run is gated too: a plan for a merge that would be
+    // refused describes nothing that will happen.
+    const issues = await featureCoherence({ docsDir: config.docsDir, featureDir, featureId: id, preloadedDelta: deltaDoc });
+    // The issues --approve cannot move, carved out before the gate below reads
+    // the rest. The register is issue.ts's `approveOverrides` — the same data
+    // the `overridable` key in the envelope is resolved from — never a code
+    // string spelled here, because two spellings of "what the flag moves" would
+    // drift. Today the register holds one code: a `metadata { service }` binding
+    // the id grammar refuses, anywhere in a tagged element's spliced block. The
+    // landscape merge would splice that name into the living map verbatim, and
+    // the new-service scan would probe `services/<binding>/` with it — a '../'
+    // collapses the probe out of services/ altogether — so the refusal is a
+    // mechanical fact about the path the name becomes, not a judgment about the
+    // feature. Same doctrine as the illegal-specs-name refusal above; the dry
+    // run is gated the same way, and the --json envelope stays not-coherent
+    // with every issue attached, exactly like the overridable branch below, so
+    // a consumer branches on the code and not on which refusal path fired.
+    const nonOverridable = issues.filter((i) => !approveOverrides(i));
+    if (nonOverridable.length > 0) {
+        const msg = `archive ${id} — BLOCKED: ${nonOverridable.length} element binding(s) name an illegal service id; --approve does not override this`;
+        if (json) {
+            refuseJson("not-coherent", msg, issues, `features/${dirName}`);
+            return null;
+        }
+        console.error(`${msg}:`);
+        // The whole list, not just the carve-out: the reader is about to fix the
+        // feature, and the issues --approve COULD have moved are work they still
+        // owe — hiding them here made the second refusal a surprise. The closing
+        // line says which of the marks the flag cannot move.
+        for (const i of issues)
+            console.error(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);
+        console.error(`\nOf these, --approve does not override the ${nonOverridable.length} illegal binding(s) — the merge would write a name loam can never resolve into services/, mechanically. Fix the binding(s); the other issues gate as usual.`);
+        sayExplain("not-coherent");
+        process.exitCode = 1;
+        return null;
+    }
+    const gating = issues.filter(gatesArchive);
+    const advisory = issues.filter((i) => !gatesArchive(i));
+    if (gating.length > 0 && !opts.approve) {
+        const msg = `archive ${id} — BLOCKED: not coherent (${gating.length} gating issue(s), ${advisory.length} advisory warning(s))`;
+        if (json) {
+            refuseJson("not-coherent", msg, issues, `features/${dirName}`);
+            return null;
+        }
+        console.error(`${msg}:`);
+        for (const i of issues)
+            console.error(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);
+        console.error(`\nFix the gating issues (advisory warnings never block), or re-run with --approve to override them (may corrupt the living docs).`);
+        sayExplain("not-coherent");
+        process.exitCode = 1;
+        return null;
+    }
+    if (gating.length > 0) {
+        say(`⚠ archiving despite ${gating.length} gating issue(s) (--approve):`);
+        for (const i of gating)
+            say(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);
+        say();
+    }
+    if (advisory.length > 0) {
+        say(`⚠ ${advisory.length} warning(s) (non-blocking):`);
+        for (const i of advisory)
+            say(`  ⚠ ${i.message}`);
+        say();
+    }
+    // A `specs/<svc>/` addressed to a service that exists nowhere. `validate`
+    // graded this and archive did not, which is the half that costs something:
+    // `specs/<svc>/` is what the merge MATERIALISES `services/<svc>/` from, so a
+    // one-character slip in `--touches` archived at exit 0 and left the fleet a
+    // living service nobody meant to adopt. The set comes from coherence/living.ts's
+    // `unknownDeltaServices` — the same function validate reads — so the two
+    // gates cannot drift into disagreeing about which ids are real.
+    //
+    // Gated exactly like a coherence error, --approve included: which service you
+    // meant is a judgment about the FEATURE. A feature that genuinely introduces
+    // one has a better escape hatch than --approve anyway — tag its element in
+    // delta.likec4, which is also what makes the fleet map true afterwards.
+    const unknownServices = await unknownDeltaServices(config.docsDir, featureDir, id, { preloadedDelta: deltaDoc });
+    if (unknownServices.length > 0 && !opts.approve) {
+        const msg = `archive ${id} — BLOCKED: ${unknownServices.length} per-service delta(s) address a service that does not exist`;
+        if (json) {
+            refuseFindings("not-coherent", msg, unknownServices, `features/${dirName}`);
+            return null;
+        }
+        console.error(`${msg}:`);
+        for (const f of unknownServices)
+            console.error(`  ✗ ${f.message}`);
+        console.error(`\nFix the id, or introduce the service in this feature's delta.likec4 — or re-run with --approve to create it anyway.`);
+        sayExplain("not-coherent");
+        process.exitCode = 1;
+        return null;
+    }
+    if (unknownServices.length > 0) {
+        say(`⚠ archiving despite ${unknownServices.length} unknown service(s) (--approve) — this merge creates them:`);
+        for (const f of unknownServices)
+            say(`  ✗ ${f.message}`);
+        say();
+    }
+    // A LIVING requirement outside `## Requirements` is a merge loam cannot do
+    // correctly: the rewrite replaces only the requirements RUN inside that
+    // section (rewriteRequirementsRun) while parseRequirements collects from
+    // every section — so the strayed requirement keeps its authored copy in the
+    // preserved prose AND lands again in the rewritten run, and the next
+    // archive's MODIFIED replaces only one of them. Refused rather than
+    // repaired: excising blocks from prose programmatically would be archive
+    // editing text it does not understand. --approve does not apply — it
+    // overrides judgments about the FEATURE, and this is neither.
+    const strayed = [];
+    const scanStrayed = async (livingPath, subject) => {
+        if (!existsSync(livingPath))
+            return;
+        for (const r of parseRequirements(await readUtf8(livingPath))) {
+            // The ONE definition of the heading (spec.ts): the guard and the rewrite
+            // boundary match the same way, so they cannot disagree about "outside".
+            if (r.section !== undefined && isRequirementsHeading(r.section))
+                continue;
+            const where = r.section === undefined ? "above every heading" : `under '${r.section}'`;
+            strayed.push({
+                severity: "error",
+                code: "living.requirement-outside-requirements",
+                subject,
+                message: `${subject}: living requirement '${r.name}' sits ${where} in ${repoPath(config.docsDir, livingPath)} — the merge rewrites only '## Requirements', so it would land in the file twice. Re-home it under '## Requirements' first, then re-run.`,
+            });
+        }
+    };
+    for (const svc of deltaServices) {
+        for (const axis of SPEC_AXES) {
+            if (!existsSync(featureSpecPaths(featureDir, svc)[axis.key]))
+                continue;
+            // The shared context, because this sits in a deltaServices × SPEC_AXES
+            // loop: without it every iteration re-walks and re-reads the fleet.
+            await scanStrayed((await locateServicePaths(config.docsDir, svc, config.fleet))[axis.key], svc);
+        }
+    }
+    // The business corpus, for the identical mechanical reason: a capability
+    // document is narrative ABOVE `## Requirements`, `rewriteRequirementsRun`
+    // rewrites only the run inside that heading, and a requirement filed under
+    // `## Notes` would keep its authored copy in the preserved prose AND land
+    // again in the rewritten run.
+    for (const doc of capabilityDeltas) {
+        await scanStrayed(livingCapabilityPaths(config.docsDir, doc.id).spec, doc.id);
+    }
+    if (strayed.length > 0) {
+        const msg = `archive ${id} — BLOCKED: ${strayed.length} living requirement(s) outside '## Requirements'`;
+        if (json) {
+            refuseJson("living-outside-requirements", msg, strayed, `features/${dirName}`);
+            return null;
+        }
+        console.error(`${msg}:`);
+        for (const i of strayed)
+            console.error(`  ✗ ${i.message}`);
+        console.error(`\n--approve does not override this — the duplication is mechanical, not a judgment call.`);
+        sayExplain("living-outside-requirements");
+        process.exitCode = 1;
+        return null;
+    }
+    // Pre-flight: the archive destination must be free, or the final move would fail
+    // after the living docs were already rewritten.
+    const archiveDir = archiveRoot(config.docsDir);
+    const archiveDest = join(archiveDir, dirName);
+    if (existsSync(archiveDest)) {
+        fail(json, "archive-exists", `archive ${id} — BLOCKED: features/archive/${dirName} already exists. Remove or rename it, then re-run.`);
+        return null;
+    }
+    say(`archive ${id}${dryRun ? "  (dry run)" : ""}\n`);
+    return {
+        id,
+        dirName,
+        featureDir,
+        deltaDoc,
+        deltaServices,
+        capabilityDeltas,
+        gating,
+        advisory,
+        archiveDir,
+        archiveDest,
+        recovered,
+        issues,
+    };
+}
+//# sourceMappingURL=gate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/gate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every refusal that happens before a byte is planned.\n *\n * They are gathered here because they share one doctrine that is easy to lose:\n * `--approve` overrides judgments about the FEATURE, and nothing else. A service\n * directory whose name the id grammar refuses, a living document holding git\n * conflict markers, a requirement outside `## Requirements` — those are\n * mechanical facts about paths and files, so `--approve` does not reach them,\n * and the dry run is gated too, since a plan built on one describes a merge loam\n * must never perform.\n *\n * `null` means the refusal has already been printed and the exit code set.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { fail, repoPath, sayExplain } from \"../../../core/envelope/json.js\";\nimport { approveOverrides, gatesArchive, type Issue } from \"../../../core/vocabulary/issue.js\";\nimport { recoverInterruptedCommit } from \"../../../core/staging/recovery/recover.js\";\nimport { readUtf8 } from \"../../../core/staging/writes.js\";\nimport { loadFile } from \"../../../core/c4/likec4.js\";\nimport { archiveDir as archiveRoot, featurePaths, featureSpecPaths, SPEC_AXES } from \"../../../core/repo/paths.js\";\nimport { livingCapabilityPaths } from \"../../../core/repo/authored/paths.js\";\nimport { featureCapabilityDeltas } from \"../../../core/capabilities/delta/tree.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport { featureSpecServices, missingFeatureMessage, resolveFeature } from \"../../../core/repo/repo.js\";\nimport { featureCoherence } from \"../../../core/coherence/coherence.js\";\nimport {\n  invalidSpecServiceFindings,\n  livingMergeConflicts,\n  unknownDeltaServices,\n} from \"../../../core/coherence/living.js\";\nimport { SEVERITY_MARK } from \"../../../core/vocabulary/report.js\";\nimport { isRequirementsHeading, parseRequirements } from \"../../../core/document/parse.js\";\nimport { refuseFindings, refuseJson, sayRecovery, type ArchiveOptions } from \"./refusal.js\";\nimport { type Gated } from \"./state.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\n\nexport async function gate(\n  config: { docsDir: DocsDir; fleet?: FleetContext },\n  featureId: string,\n  opts: ArchiveOptions,\n  say: (line?: string) => void,\n): Promise<Gated | null> {\n  const json = opts.json === true;\n  const dryRun = opts.dryRun === true;\n  // the living docs half-written, and every other command in loam would have\n  // planned against them as if they were the truth. Under the same lock, so the\n  // repair cannot race a writer. It refuses when the half-merged files have been\n  // edited since — that is a human's call, not a merge's.\n  const recovered = await recoverInterruptedCommit(config.docsDir);\n  if (recovered !== null && !json) sayRecovery(recovered);\n\n  const feature = await resolveFeature(config.docsDir, featureId, \"exclude\");\n  if (!feature) {\n    fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureId));\n    return null;\n  }\n  // The raw argument's last appearance: from here on the feature answers only to\n  // its canonical id — tags, coherence, and the self-exclusion scans all match\n  // on `id`, and `archive FEAT-5-slug` must plan exactly like `archive FEAT-5`.\n  const { id, dirName, dir: featureDir } = feature;\n\n  // Parse delta.likec4 ONCE for the whole run: the coherence gate and the\n  // architecture merge below read the same file, and loading it spins up a\n  // fresh Langium workspace each time. Nothing writes it in between.\n  const deltaLikec4 = featurePaths(featureDir).delta;\n  const deltaDoc = existsSync(deltaLikec4) ? await loadFile(deltaLikec4) : undefined;\n\n  const deltaServices = await featureSpecServices(featureDir);\n  // The business corpus's delta tree, walked once HERE and carried on `Gated`:\n  // the conflict-marker scan, the strayed-requirement scan and the merge itself\n  // all ask which capability documents this feature rewrites, and three walks\n  // are three chances to answer differently. `featureCoherence` below walks it\n  // again on its own — it is called without `config.fleet`, the same\n  // no-context path `core/coherence/declared.ts` already documents paying for\n  // the arch delta — so this is not the run's only walk, only the one every\n  // phase downstream of the gate shares.\n  const capabilityDeltas = (\n    config.fleet === undefined\n      ? await featureCapabilityDeltas(featureDir)\n      : await config.fleet.featureCapabilityDeltas(featureDir)\n  ).docs;\n\n  // A `specs/<svc>/` whose NAME is not a legal service id, refused before\n  // anything joins that name into a path: the conflict scan below probes\n  // `services/<svc>/<axis>` with it, and the requirements merge would\n  // materialise `services/<svc>/` from it — a directory `service.id-invalid`\n  // then calls an error on the next `validate --all`, and one no loam command\n  // can address or re-create. The set comes from coherence/living.ts's\n  // `invalidSpecServiceFindings` — the same function validate reads — so the\n  // two gates cannot drift.\n  //\n  // --approve does not apply, exactly as with the conflict-marker refusal\n  // below: --approve overrides judgments about the FEATURE, and a name the id\n  // grammar refuses is a mechanical fact about the path it would become. The\n  // dry run is gated too: a plan built on that name describes a merge loam\n  // must never perform.\n  const illegalServices = await invalidSpecServiceFindings(featureDir);\n  if (illegalServices.length > 0) {\n    const msg = `archive ${id} — BLOCKED: ${illegalServices.length} per-service delta(s) named by an illegal service id; --approve does not override this`;\n    if (json) {\n      refuseFindings(\"not-coherent\", msg, illegalServices, `features/${dirName}`);\n      return null;\n    }\n    console.error(`${msg}:`);\n    for (const f of illegalServices) console.error(`  ✗ ${f.message}`);\n    console.error(`\\n--approve does not override this — the directory the merge would create is one loam can never address, mechanically.`);\n    // Every arm in this file refuses by hand — it prints a headline, a list and\n    // a closing sentence rather than the one message `fail()` takes — so the\n    // code and its lookup have to be asked for explicitly. `sayExplain` is\n    // called rather than the format being copied six times, and the code passed\n    // is the SAME one the `--json` branch a few lines up emits: text and\n    // envelope must name one refusal, or a reader who switches modes to find\n    // the code is handed a different answer than the one they saw.\n    sayExplain(\"not-coherent\");\n    process.exitCode = 1;\n    return null;\n  }\n\n  // Git conflict markers in a LIVING document this merge would rewrite, before\n  // anything else is asked of it. Both sides of somebody's merge are in the\n  // file, so nothing it says is anyone's text — and the requirements rewrite\n  // deletes whichever marker lines fall inside the section it owns, turning a\n  // conflict anyone can see into a file nobody can tell is wrong. Checked ahead\n  // of the coherence gate for `inspectLandscape`'s reason: a conflicted\n  // document parses, so every verdict downstream of it is an opinion about half\n  // of two people's work.\n  //\n  // --approve does not apply, exactly as with the strayed-requirement refusal\n  // below: --approve overrides judgments about the FEATURE, and this is a fact\n  // about the living document.\n  const conflicted = await livingMergeConflicts(config.docsDir, deltaServices, capabilityDeltas.map((d) => d.id));\n  if (conflicted.length > 0) {\n    const msg = `archive ${id} — BLOCKED: ${conflicted.length} living document(s) still hold git conflict markers`;\n    if (json) {\n      refuseFindings(\"merge-failed\", msg, conflicted, `features/${dirName}`);\n      return null;\n    }\n    console.error(`${msg}:`);\n    for (const f of conflicted) console.error(`  ✗ ${f.message}`);\n    console.error(`\\n--approve does not override this — the loss is mechanical, not a judgment call.`);\n    sayExplain(\"merge-failed\");\n    process.exitCode = 1;\n    return null;\n  }\n\n  // Gate: GATING issues block the archive. Severity and gating are two\n  // different questions (issue.ts): errors gate because the merge would write\n  // something wrong, and the rare warning marked `gates` blocks too — the\n  // document is legal but the merge would drop authored content. Advisory\n  // warnings are printed (and carried into --json) but never block, matching\n  // validate's own doctrine (report.ts: \"warnings never gate\"). --approve\n  // overrides the gating issues ONLY, and must say exactly which ones it is\n  // walking past. A dry run is gated too: a plan for a merge that would be\n  // refused describes nothing that will happen.\n  const issues = await featureCoherence({ docsDir: config.docsDir, featureDir, featureId: id, preloadedDelta: deltaDoc });\n  // The issues --approve cannot move, carved out before the gate below reads\n  // the rest. The register is issue.ts's `approveOverrides` — the same data\n  // the `overridable` key in the envelope is resolved from — never a code\n  // string spelled here, because two spellings of \"what the flag moves\" would\n  // drift. Today the register holds one code: a `metadata { service }` binding\n  // the id grammar refuses, anywhere in a tagged element's spliced block. The\n  // landscape merge would splice that name into the living map verbatim, and\n  // the new-service scan would probe `services/<binding>/` with it — a '../'\n  // collapses the probe out of services/ altogether — so the refusal is a\n  // mechanical fact about the path the name becomes, not a judgment about the\n  // feature. Same doctrine as the illegal-specs-name refusal above; the dry\n  // run is gated the same way, and the --json envelope stays not-coherent\n  // with every issue attached, exactly like the overridable branch below, so\n  // a consumer branches on the code and not on which refusal path fired.\n  const nonOverridable = issues.filter((i) => !approveOverrides(i));\n  if (nonOverridable.length > 0) {\n    const msg = `archive ${id} — BLOCKED: ${nonOverridable.length} element binding(s) name an illegal service id; --approve does not override this`;\n    if (json) {\n      refuseJson(\"not-coherent\", msg, issues, `features/${dirName}`);\n      return null;\n    }\n    console.error(`${msg}:`);\n    // The whole list, not just the carve-out: the reader is about to fix the\n    // feature, and the issues --approve COULD have moved are work they still\n    // owe — hiding them here made the second refusal a surprise. The closing\n    // line says which of the marks the flag cannot move.\n    for (const i of issues) console.error(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);\n    console.error(\n      `\\nOf these, --approve does not override the ${nonOverridable.length} illegal binding(s) — the merge would write a name loam can never resolve into services/, mechanically. Fix the binding(s); the other issues gate as usual.`,\n    );\n    sayExplain(\"not-coherent\");\n    process.exitCode = 1;\n    return null;\n  }\n  const gating = issues.filter(gatesArchive);\n  const advisory = issues.filter((i) => !gatesArchive(i));\n  if (gating.length > 0 && !opts.approve) {\n    const msg = `archive ${id} — BLOCKED: not coherent (${gating.length} gating issue(s), ${advisory.length} advisory warning(s))`;\n    if (json) {\n      refuseJson(\"not-coherent\", msg, issues, `features/${dirName}`);\n      return null;\n    }\n    console.error(`${msg}:`);\n    for (const i of issues) console.error(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);\n    console.error(`\\nFix the gating issues (advisory warnings never block), or re-run with --approve to override them (may corrupt the living docs).`);\n    sayExplain(\"not-coherent\");\n    process.exitCode = 1;\n    return null;\n  }\n  if (gating.length > 0) {\n    say(`⚠ archiving despite ${gating.length} gating issue(s) (--approve):`);\n    for (const i of gating) say(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);\n    say();\n  }\n  if (advisory.length > 0) {\n    say(`⚠ ${advisory.length} warning(s) (non-blocking):`);\n    for (const i of advisory) say(`  ⚠ ${i.message}`);\n    say();\n  }\n\n  // A `specs/<svc>/` addressed to a service that exists nowhere. `validate`\n  // graded this and archive did not, which is the half that costs something:\n  // `specs/<svc>/` is what the merge MATERIALISES `services/<svc>/` from, so a\n  // one-character slip in `--touches` archived at exit 0 and left the fleet a\n  // living service nobody meant to adopt. The set comes from coherence/living.ts's\n  // `unknownDeltaServices` — the same function validate reads — so the two\n  // gates cannot drift into disagreeing about which ids are real.\n  //\n  // Gated exactly like a coherence error, --approve included: which service you\n  // meant is a judgment about the FEATURE. A feature that genuinely introduces\n  // one has a better escape hatch than --approve anyway — tag its element in\n  // delta.likec4, which is also what makes the fleet map true afterwards.\n  const unknownServices = await unknownDeltaServices(config.docsDir, featureDir, id, { preloadedDelta: deltaDoc });\n  if (unknownServices.length > 0 && !opts.approve) {\n    const msg = `archive ${id} — BLOCKED: ${unknownServices.length} per-service delta(s) address a service that does not exist`;\n    if (json) {\n      refuseFindings(\"not-coherent\", msg, unknownServices, `features/${dirName}`);\n      return null;\n    }\n    console.error(`${msg}:`);\n    for (const f of unknownServices) console.error(`  ✗ ${f.message}`);\n    console.error(`\\nFix the id, or introduce the service in this feature's delta.likec4 — or re-run with --approve to create it anyway.`);\n    sayExplain(\"not-coherent\");\n    process.exitCode = 1;\n    return null;\n  }\n  if (unknownServices.length > 0) {\n    say(`⚠ archiving despite ${unknownServices.length} unknown service(s) (--approve) — this merge creates them:`);\n    for (const f of unknownServices) say(`  ✗ ${f.message}`);\n    say();\n  }\n\n  // A LIVING requirement outside `## Requirements` is a merge loam cannot do\n  // correctly: the rewrite replaces only the requirements RUN inside that\n  // section (rewriteRequirementsRun) while parseRequirements collects from\n  // every section — so the strayed requirement keeps its authored copy in the\n  // preserved prose AND lands again in the rewritten run, and the next\n  // archive's MODIFIED replaces only one of them. Refused rather than\n  // repaired: excising blocks from prose programmatically would be archive\n  // editing text it does not understand. --approve does not apply — it\n  // overrides judgments about the FEATURE, and this is neither.\n  const strayed: Issue[] = [];\n  const scanStrayed = async (livingPath: string, subject: string): Promise<void> => {\n    if (!existsSync(livingPath)) return;\n    for (const r of parseRequirements(await readUtf8(livingPath))) {\n      // The ONE definition of the heading (spec.ts): the guard and the rewrite\n      // boundary match the same way, so they cannot disagree about \"outside\".\n      if (r.section !== undefined && isRequirementsHeading(r.section)) continue;\n      const where = r.section === undefined ? \"above every heading\" : `under '${r.section}'`;\n      strayed.push({\n        severity: \"error\",\n        code: \"living.requirement-outside-requirements\",\n        subject,\n        message: `${subject}: living requirement '${r.name}' sits ${where} in ${repoPath(config.docsDir, livingPath)} — the merge rewrites only '## Requirements', so it would land in the file twice. Re-home it under '## Requirements' first, then re-run.`,\n      });\n    }\n  };\n  for (const svc of deltaServices) {\n    for (const axis of SPEC_AXES) {\n      if (!existsSync(featureSpecPaths(featureDir, svc)[axis.key])) continue;\n      // The shared context, because this sits in a deltaServices × SPEC_AXES\n      // loop: without it every iteration re-walks and re-reads the fleet.\n      await scanStrayed((await locateServicePaths(config.docsDir, svc, config.fleet))[axis.key], svc);\n    }\n  }\n  // The business corpus, for the identical mechanical reason: a capability\n  // document is narrative ABOVE `## Requirements`, `rewriteRequirementsRun`\n  // rewrites only the run inside that heading, and a requirement filed under\n  // `## Notes` would keep its authored copy in the preserved prose AND land\n  // again in the rewritten run.\n  for (const doc of capabilityDeltas) {\n    await scanStrayed(livingCapabilityPaths(config.docsDir, doc.id).spec, doc.id);\n  }\n  if (strayed.length > 0) {\n    const msg = `archive ${id} — BLOCKED: ${strayed.length} living requirement(s) outside '## Requirements'`;\n    if (json) {\n      refuseJson(\"living-outside-requirements\", msg, strayed, `features/${dirName}`);\n      return null;\n    }\n    console.error(`${msg}:`);\n    for (const i of strayed) console.error(`  ✗ ${i.message}`);\n    console.error(`\\n--approve does not override this — the duplication is mechanical, not a judgment call.`);\n    sayExplain(\"living-outside-requirements\");\n    process.exitCode = 1;\n    return null;\n  }\n\n  // Pre-flight: the archive destination must be free, or the final move would fail\n  // after the living docs were already rewritten.\n  const archiveDir = archiveRoot(config.docsDir);\n  const archiveDest = join(archiveDir, dirName);\n  if (existsSync(archiveDest)) {\n    fail(json, \"archive-exists\", `archive ${id} — BLOCKED: features/archive/${dirName} already exists. Remove or rename it, then re-run.`);\n    return null;\n  }\n\n  say(`archive ${id}${dryRun ? \"  (dry run)\" : \"\"}\\n`);\n\n  return {\n    id,\n    dirName,\n    featureDir,\n    deltaDoc,\n    deltaServices,\n    capabilityDeltas,\n    gating,\n    advisory,\n    archiveDir,\n    archiveDest,\n    recovered,\n    issues,\n  };\n}\n"]}