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

package/dist/core/coherence/consumed/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../../../src/core/coherence/consumed/refusal.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAUxD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB;IACzC,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC;QACvC,SAAS,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,EAAE,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;KAChG,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC;AAClE,CAAC;AAaD,oEAAoE;AACpE,MAAM,QAAQ,GAAG,mHAAmH,CAAC;AAErI;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAiB,EAAE,OAAuB;IACvE,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,GAAG,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,uCAAuC,OAAO,CAAC,IAAI,+CAA+C,SAAS,UAAU,QAAQ,uDAAuD,CAAC;IACjO,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,sCAAsC,OAAO,CAAC,IAAI,qCAAqC,SAAS,UAAU,QAAQ,GAAG,CAAC;AAC9K,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,cAAc,CAAC,KAAiB;IAC9C,OAAO,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["/**\n * What a removal refusal counts of one consumer-index answer, and how it says\n * so — shared by the operation gate (./operations.ts) and its event twin\n * (../events/events.ts), so a consumer nobody could read refuses the same way,\n * in the same sentence, on both axes.\n *\n * Two lists, because they are two different claims. `named` is positive\n * evidence — the merge would strand these — and its sentence is each gate's\n * own, with the remedy that fits the shape. `unchecked` is a document nobody\n * could read or place, so the refusal must not say the fleet still consumes\n * anything: it says the gate could not tell, names the documents, and gives the\n * one remedy they share. Both land in `details[]`, the named ones first — the\n * order `loam diff` lists victims and doubts in.\n */\nimport type { Consumers } from \"../../consumers/consumers.js\";\nimport { documentDoubt } from \"../../consumers/scan.js\";\n\n/** What the gate counts of one index answer. */\nexport interface StillNamed {\n  /** The consumers the merge would strand, then the provider's own documents still naming it. */\n  named: string[];\n  /** The documents — a consumer's, or the provider's own — the scan could not read or place (`documentDoubt`). */\n  unchecked: string[];\n}\n\n/**\n * The gate's reading of one answer: `victims` and `own` as evidence, and of the\n * suspensions only the document doubts. A caller drawn with no op and a\n * contested hop stay out — `documentDoubt` (core/consumers/scan.ts) says why\n * they are a warning's worth in `loam diff` and nothing here.\n */\nexport function stillNamed(found: Consumers): StillNamed {\n  return {\n    named: [...found.victims, ...found.own],\n    unchecked: [...found.suspended, ...found.ownSuspended].filter(documentDoubt).map((s) => s.text),\n  };\n}\n\n/** Nothing named and nothing unchecked: the removal is the gate's to let through. */\nexport function nothingStill(still: StillNamed): boolean {\n  return still.named.length === 0 && still.unchecked.length === 0;\n}\n\n/** One refusal's sentence, as the gate that raises it phrases it. */\nexport interface RefusalWording {\n  subject: string;\n  /** How this feature's merge takes it out — the opening clause, e.g. \"this feature retires 'capturePayment'\". */\n  lost: string;\n  /** What a consumer does with it: \"consume\" for an operation, \"name\" for a message. */\n  verb: string;\n  /** The gate's own sentence over its named consumers, given them joined. */\n  named: (list: string) => string;\n}\n\n/** The one remedy every unchecked document shares, after \"make\". */\nconst READABLE = \"each document listed readable (re-save it as UTF-8, or leave one directory per service id) so the gate can answer\";\n\n/**\n * The message for one refusal. With named consumers it is the gate's own\n * sentence, plus one more when documents went unchecked too; with only\n * unchecked documents it never claims a consumer — \"nobody could look\" is not\n * \"somebody still calls it\", any more than it is \"nobody does\".\n */\nexport function refusalMessage(still: StillNamed, wording: RefusalWording): string {\n  const unchecked = still.unchecked.join(\"; \");\n  if (still.named.length === 0) {\n    return `${wording.subject}: ${wording.lost}, but whether the fleet would still ${wording.verb} it after this merge could not be checked — ${unchecked}. Make ${READABLE}, or archive with --approve to break it deliberately.`;\n  }\n  const named = wording.named(still.named.join(\"; \"));\n  return still.unchecked.length === 0 ? named : `${named} Whether anything else would still ${wording.verb} it could not be checked either — ${unchecked}: make ${READABLE}.`;\n}\n\n/** What a refusal's `details[]` lists: the named consumers, then the documents nobody could check. */\nexport function refusalDetails(still: StillNamed): string[] {\n  return [...still.named, ...still.unchecked];\n}\n"]}

package/dist/core/coherence/covers/health.js

@@ -0,0 +1,85 @@
+/**
+ * `health.uncovered`, predicted: the alert or SLI a living `arch.spec.md`
+ * requirement covers today that this feature's arch delta would leave covered
+ * by nothing.
+ *
+ * Validate's service target grades `health.yaml` against the LIVING
+ * `arch.spec.md` (`commands/validate/service/specs.ts`), and nothing graded the
+ * delta that rewrites it. A MODIFIED requirement restates its whole block, so
+ * a `Covers:` line the author did not carry over is a line the merge deletes:
+ * the feature gate called the delta clean, the archive printed "living spec +
+ * landscape are now complete + current.", and the next `validate --all` warned
+ * that the signal now ships with nothing testing it (the real-fleet review,
+ * 2026-10-21).
+ *
+ * ONLY WHAT THIS MERGE TAKES AWAY. A signal the living spec already leaves
+ * uncovered is the service target's warning today and stays its warning; this
+ * gate reporting it too would file somebody else's debt against a feature
+ * that never touched it. And a service this feature creates has no living
+ * `health.yaml` — a feature cannot carry one — so it has nothing to lose.
+ *
+ * A WARNING, the grade validate gives the same fact: the documents are legal
+ * and the merge is correct, so it advises and never gates. The merge is the
+ * archive's own (`afterMerge` over `applyRequirementDelta`), so the
+ * requirements this reads are the ones the archive would write; a delta the
+ * merge refuses is read as living ∪ ADDED ∪ MODIFIED, which can only find MORE
+ * coverage — the quiet direction for an advisory.
+ */
+import { existsSync } from "node:fs";
+import { parseCoversEntry } from "../../c4/arch.js";
+import { afterMerge } from "../../consumers/after.js";
+import { parseRequirements, readRequirementsDocument } from "../../document/parse.js";
+import { featureSpecPaths } from "../../repo/paths.js";
+import { locateServicePaths } from "../../repo/service-target.js";
+import { readHealth } from "../../vocabulary/health.js";
+/** The requirements naming `form:id` in a `Covers:` line — the rule `coversEntries` applies, REMOVED governing nothing. */
+function covering(reqs, form, id) {
+    return reqs.filter((r) => r.kind !== "REMOVED" &&
+        r.covers.some((raw) => {
+            const entry = parseCoversEntry(raw);
+            return entry.form === form && entry.id === id;
+        }));
+}
+export async function droppedHealthCoverage(scope) {
+    const { docsDir, featureDir, context } = scope;
+    const read = async (path) => context === undefined ? parseRequirements(await readRequirementsDocument(path)) : await context.readRequirements(path);
+    const issues = [];
+    for (const service of scope.services) {
+        const deltaPath = featureSpecPaths(featureDir, service).archSpec;
+        if (!existsSync(deltaPath))
+            continue;
+        const paths = await locateServicePaths(docsDir, service, context);
+        if (!existsSync(paths.archSpec) || !existsSync(paths.health))
+            continue;
+        // An unreadable health.yaml is `health.invalid`, the service target's
+        // finding; there are no ids here to grade either way.
+        const health = await readHealth(paths.health);
+        if (health.unreadable)
+            continue;
+        const living = await read(paths.archSpec);
+        const after = afterMerge(living, await read(deltaPath)).map((m) => m.requirement);
+        for (const { form, ids } of [
+            { form: "alert", ids: health.ids.alerts },
+            { form: "sli", ids: health.ids.slis },
+        ]) {
+            for (const id of ids) {
+                const before = covering(living, form, id);
+                if (before.length === 0 || covering(after, form, id).length > 0)
+                    continue;
+                const signal = form === "alert" ? "alert" : "SLI";
+                issues.push({
+                    severity: "warn",
+                    code: "health.uncovered",
+                    subject: service,
+                    message: `${service}: health.yaml declares ${signal} '${id}', which the living arch.spec.md covers today ` +
+                        `(${before.map((r) => `'${r.name}'`).join(", ")}) and nothing would after this feature's merge — its ` +
+                        `arch.spec.md delta rewrites or removes every requirement carrying 'Covers: ${form}:${id}', so the next ` +
+                        `\`loam validate --all\` reports health.uncovered. Keep the entry on the MODIFIED requirement, or cover ` +
+                        `the signal from another requirement in the delta`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=health.js.map

package/dist/core/coherence/covers/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../../../src/core/coherence/covers/health.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `health.uncovered`, predicted: the alert or SLI a living `arch.spec.md`\n * requirement covers today that this feature's arch delta would leave covered\n * by nothing.\n *\n * Validate's service target grades `health.yaml` against the LIVING\n * `arch.spec.md` (`commands/validate/service/specs.ts`), and nothing graded the\n * delta that rewrites it. A MODIFIED requirement restates its whole block, so\n * a `Covers:` line the author did not carry over is a line the merge deletes:\n * the feature gate called the delta clean, the archive printed \"living spec +\n * landscape are now complete + current.\", and the next `validate --all` warned\n * that the signal now ships with nothing testing it (the real-fleet review,\n * 2026-10-21).\n *\n * ONLY WHAT THIS MERGE TAKES AWAY. A signal the living spec already leaves\n * uncovered is the service target's warning today and stays its warning; this\n * gate reporting it too would file somebody else's debt against a feature\n * that never touched it. And a service this feature creates has no living\n * `health.yaml` — a feature cannot carry one — so it has nothing to lose.\n *\n * A WARNING, the grade validate gives the same fact: the documents are legal\n * and the merge is correct, so it advises and never gates. The merge is the\n * archive's own (`afterMerge` over `applyRequirementDelta`), so the\n * requirements this reads are the ones the archive would write; a delta the\n * merge refuses is read as living ∪ ADDED ∪ MODIFIED, which can only find MORE\n * coverage — the quiet direction for an advisory.\n */\nimport { existsSync } from \"node:fs\";\nimport { parseCoversEntry } from \"../../c4/arch.js\";\nimport { afterMerge } from \"../../consumers/after.js\";\nimport { parseRequirements, readRequirementsDocument } from \"../../document/parse.js\";\nimport type { Requirement } from \"../../document/spec.js\";\nimport type { FleetContext } from \"../../fleet-context.js\";\nimport type { DocsDir, FeatureDir } from \"../../kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../kernel/ids/service.js\";\nimport { featureSpecPaths } from \"../../repo/paths.js\";\nimport { locateServicePaths } from \"../../repo/service-target.js\";\nimport { readHealth } from \"../../vocabulary/health.js\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\n\n/** The feature being graded, and the services its `specs/` touch. */\nexport interface HealthCoverageScope {\n  docsDir: DocsDir;\n  featureDir: FeatureDir;\n  services: readonly PathableService[];\n  context?: FleetContext;\n}\n\n/** The requirements naming `form:id` in a `Covers:` line — the rule `coversEntries` applies, REMOVED governing nothing. */\nfunction covering(reqs: readonly Requirement[], form: \"alert\" | \"sli\", id: string): Requirement[] {\n  return reqs.filter(\n    (r) =>\n      r.kind !== \"REMOVED\" &&\n      r.covers.some((raw) => {\n        const entry = parseCoversEntry(raw);\n        return entry.form === form && entry.id === id;\n      }),\n  );\n}\n\nexport async function droppedHealthCoverage(scope: HealthCoverageScope): Promise<Issue[]> {\n  const { docsDir, featureDir, context } = scope;\n  const read = async (path: string): Promise<Requirement[]> =>\n    context === undefined ? parseRequirements(await readRequirementsDocument(path)) : await context.readRequirements(path);\n  const issues: Issue[] = [];\n  for (const service of scope.services) {\n    const deltaPath = featureSpecPaths(featureDir, service).archSpec;\n    if (!existsSync(deltaPath)) continue;\n    const paths = await locateServicePaths(docsDir, service, context);\n    if (!existsSync(paths.archSpec) || !existsSync(paths.health)) continue;\n    // An unreadable health.yaml is `health.invalid`, the service target's\n    // finding; there are no ids here to grade either way.\n    const health = await readHealth(paths.health);\n    if (health.unreadable) continue;\n    const living = await read(paths.archSpec);\n    const after = afterMerge(living, await read(deltaPath)).map((m) => m.requirement);\n    for (const { form, ids } of [\n      { form: \"alert\" as const, ids: health.ids.alerts },\n      { form: \"sli\" as const, ids: health.ids.slis },\n    ]) {\n      for (const id of ids) {\n        const before = covering(living, form, id);\n        if (before.length === 0 || covering(after, form, id).length > 0) continue;\n        const signal = form === \"alert\" ? \"alert\" : \"SLI\";\n        issues.push({\n          severity: \"warn\",\n          code: \"health.uncovered\",\n          subject: service,\n          message:\n            `${service}: health.yaml declares ${signal} '${id}', which the living arch.spec.md covers today ` +\n            `(${before.map((r) => `'${r.name}'`).join(\", \")}) and nothing would after this feature's merge — its ` +\n            `arch.spec.md delta rewrites or removes every requirement carrying 'Covers: ${form}:${id}', so the next ` +\n            `\\`loam validate --all\\` reports health.uncovered. Keep the entry on the MODIFIED requirement, or cover ` +\n            `the signal from another requirement in the delta`,\n        });\n      }\n    }\n  }\n  return issues;\n}\n"]}

package/dist/core/coherence/declared.js

@@ -0,0 +1,295 @@
+/**
+ * What a feature's own delta DECLARES, per service, indexed once.
+ *
+ * Nine indexes over the same four files (the delta spec.md, arch.spec.md,
+ * openapi.yaml, and the living contract they are graded against), built in one
+ * walk because every check downstream joins on the service id and would
+ * otherwise re-read the delta per question. The distinctions here are the ones
+ * the checks cannot make for themselves: an operation a REMOVED requirement
+ * governs is being retired, so it neither claims the contract nor governs
+ * anything after the merge; a removal marker that names an id also defined
+ * elsewhere in the delta is a RELOCATION, not a retirement; a living operation
+ * another one replaces at its address, with no marker naming it, leaves the
+ * contract all the same; and a marker with
+ * no `operationId` at all is a shape only this walk can see. The capability
+ * gate rides the same loop: both delta spec documents are graded against the
+ * fleet vocabulary here, because coherence.ts and this package's file count
+ * are both at their limits and the walk already holds the parsed documents.
+ */
+import { existsSync } from "node:fs";
+import { readOr } from "../openapi/contract-text.js";
+import { readFile } from "node:fs/promises";
+import {} from "../kernel/ids/service.js";
+import { featureSpecPaths } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { parseRequirements } from "../document/parse.js";
+import { readCapabilityVocabulary } from "../capabilities/capabilities.js";
+import { capabilityRequirementIndex } from "../capabilities/findings.js";
+import { withFeatureCapabilities, withFeatureRequirements } from "../capabilities/delta/overlay.js";
+import { featureCapabilityDeltas } from "../capabilities/delta/tree.js";
+import { realizesUnknownIssues } from "../capabilities/realizes/findings.js";
+import { capabilityUnknownIssues } from "../capabilities/findings.js";
+import { openapiBaselineIssues } from "../openapi/baseline/gate.js";
+import { readOpenapi } from "../openapi/doc.js";
+import { operationRetirements } from "./retired/retirement.js";
+import { operationArrivals } from "./retired/revival/arrivals.js";
+export async function declaredByService(scope, svcNames, issues, context) {
+    const { docsDir, featureDir, featureId } = scope;
+    const reqOps = new Map();
+    const removedReqOps = new Map();
+    /** Per service: operations this feature genuinely retires (markers minus relocations). */
+    const removingOps = new Map();
+    /** Per service: every id a removal marker names, relocations included. */
+    const allMarkerIds = new Map();
+    /** Per service: does the feature contract carry a marker with no operationId? */
+    const anonymousMarkers = new Map();
+    const featureApiOps = new Set();
+    const unreadableApis = new Set();
+    const revivalCandidates = new Map();
+    const displacedOps = new Map();
+    /** Per service read here: the operationIds its living contract holds, or null when it does not read. */
+    const livingIds = new Map();
+    // The capability gate's vocabulary, once per call. Absent or invalid stays
+    // SILENT here — capability.invalid is validate --all's one finding about a
+    // broken file, and an absent file means the fleet never opted in — so with
+    // either, nothing new gates archive (the roadmap's own trade; the
+    // /loam-check row tells agents to fix the YAML first). `grading` is that
+    // silence hoisted into a guard, so a silent axis also skips the reads that
+    // exist only to feed it.
+    //
+    // The vocabulary is the one this feature's MERGE would leave behind, not
+    // the one on disk: a feature that adds a capability requirement in its own
+    // capability delta and `Realizes:` it from its own service delta is the
+    // flow the whole axis exists for, and graded against the living tree alone
+    // it is refused with `capability.realizes-unknown` — an error, gating
+    // archive, for a target the same archive creates. `capabilities/delta/
+    // overlay.ts` states the whole judgement. One `existsSync` for a feature
+    // that carries no capability delta, which is every feature in a fleet that
+    // has not adopted the axis.
+    const capabilityDeltas = context === undefined ? await featureCapabilityDeltas(featureDir) : await context.featureCapabilityDeltas(featureDir);
+    const capabilityVocab = withFeatureCapabilities(context === undefined ? await readCapabilityVocabulary(docsDir) : await context.capabilities(docsDir), capabilityDeltas.docs.map((d) => d.id));
+    const grading = capabilityVocab.present && capabilityVocab.invalid === undefined;
+    // The `Realizes:` index, built at most ONCE per feature and only if some
+    // delta document actually reaches the grading branch. Lazy rather than
+    // eager because it reads every capability document in the fleet, and a
+    // feature whose deltas carry no requirement file at all must not pay for
+    // that — the same "a silent axis skips the reads that feed it" rule
+    // `grading` above states, one level deeper.
+    let pendingIndex = null;
+    const capabilityReqs = () => {
+        const read = context === undefined
+            ? async (p) => parseRequirements(await readFile(p, "utf8"))
+            : (p) => context.readRequirements(p);
+        // The living index first, then widened by what this feature's capability
+        // deltas ADD or MODIFY. Both halves are inside the lazy thunk, so a
+        // feature whose deltas carry no requirement file at all pays for neither.
+        pendingIndex ??= capabilityRequirementIndex(capabilityVocab, read).then(async (index) => withFeatureRequirements(index, await Promise.all(capabilityDeltas.docs.map(async (d) => ({ id: d.id, reqs: await read(d.spec) })))));
+        return pendingIndex;
+    };
+    for (const svc of svcNames) {
+        const paths = featureSpecPaths(featureDir, svc);
+        if (existsSync(paths.spec)) {
+            const reqs = context === undefined
+                ? parseRequirements(await readFile(paths.spec, "utf8"))
+                : await context.readRequirements(paths.spec);
+            // REMOVED requirements are being retired along with their operations — their
+            // ops neither claim the contract (E1) nor govern anything after the merge.
+            reqOps.set(svc, reqs.filter((r) => r.kind !== "REMOVED").flatMap((r) => r.operations));
+            removedReqOps.set(svc, new Set(reqs.filter((r) => r.kind === "REMOVED").flatMap((r) => r.operations)));
+            if (grading) {
+                const target = { where: `${svc}: spec.md`, subject: svc };
+                issues.push(...capabilityUnknownIssues(reqs, target, capabilityVocab));
+                issues.push(...realizesUnknownIssues(reqs, target, await capabilityReqs()));
+            }
+        }
+        // The delta arch.spec.md carries the same grammar and merges the same
+        // way, so an undeclared capability in it gates identically. Nothing else
+        // in this walk needs the arch delta, so the read itself sits behind
+        // `grading` — and it is NOT always cached: `validate --feature` passes a
+        // context, but archive's plan gate (commands/archive/plan/gate.ts) calls
+        // featureCoherence without one, so this parse is paid fresh there.
+        if (grading && existsSync(paths.archSpec)) {
+            const archReqs = context === undefined
+                ? parseRequirements(await readFile(paths.archSpec, "utf8"))
+                : await context.readRequirements(paths.archSpec);
+            const archTarget = { where: `${svc}: arch.spec.md`, subject: svc };
+            issues.push(...capabilityUnknownIssues(archReqs, archTarget, capabilityVocab));
+            issues.push(...realizesUnknownIssues(archReqs, archTarget, await capabilityReqs()));
+        }
+        // Only operations the living contract does not hold count as feature-added:
+        // a delta may restate living operations it does not change (a quote), and
+        // a quote adds nothing. "Not in living" is not quite "new", though — an
+        // operation an archived feature RETIRED is absent too, and adding it back
+        // is `openapi.op-revived`'s question (./retired/revival/revived.ts), asked of the
+        // `revivalCandidates` collected below.
+        const featDoc = await readOpenapi(paths.openapi, context);
+        // A feature contract that EXISTS but does not read is a broken document,
+        // not an empty one — the living-side `openapi.invalid` discipline
+        // (validate/service/api.ts), applied to the delta. Before this check,
+        // `validate --feature` said nothing about the file at all: the empty
+        // parse silently skipped every baseline pin and removal marker in it,
+        // and E1 graded requirements against a contract that was never read.
+        // The rest of this service's contract-axis checks are suspended — every
+        // one of them would be an opinion about a document nobody could open.
+        if (featDoc.unreadable) {
+            unreadableApis.add(svc);
+            issues.push({
+                severity: "error",
+                code: "openapi.invalid",
+                subject: svc,
+                message: `${svc}: this feature's openapi.yaml does not parse${featDoc.error === undefined ? "" : ` (${featDoc.error})`} — the contract axis is unchecked and the merge would have nothing true to write. Fix the YAML first.`,
+            });
+            continue;
+        }
+        const featOps = featDoc.ops;
+        const removals = featOps.filter((op) => op.remove);
+        // The raw marker set and the NET one (markers minus relocations) —
+        // ./retired/retirement.ts owns the rule and says why the two differ; the
+        // retired index reads every archived feature through the same function.
+        const { markerIds, net: netRemoved } = operationRetirements(featOps);
+        removingOps.set(svc, netRemoved);
+        allMarkerIds.set(svc, markerIds);
+        anonymousMarkers.set(svc, featDoc.anonymousRemovals.length > 0);
+        // A marker with no operationId names a slot but no operation. Every
+        // id-keyed check is blind to it, so it used to travel all the way into the
+        // living contract as a literal `x-loam-remove: true` — the one feature-only
+        // key that must never be published.
+        for (const marker of featDoc.anonymousRemovals) {
+            issues.push({
+                severity: "error",
+                code: "openapi.remove-marker-anonymous",
+                subject: svc,
+                message: `${svc}: ${marker.method} ${marker.path} carries x-loam-remove: true but declares no operationId — loam cannot tell which operation it retires; name the operation the living contract has at that slot`,
+            });
+        }
+        const livingOpenapiPath = (await locateServicePaths(docsDir, svc, context)).openapi;
+        const livingDoc = await readOpenapi(livingOpenapiPath, context);
+        const livingOps = livingDoc.ops;
+        livingIds.set(svc, livingDoc.unreadable ? null : new Set(livingOps.filter((op) => !op.remove).map((op) => op.id)));
+        const sides = { featPath: paths.openapi, featDoc, livingPath: livingOpenapiPath, livingDoc, service: svc };
+        const moved = await operationArrivals(sides, context);
+        revivalCandidates.set(svc, moved.operations);
+        if (moved.displaced.length > 0)
+            displacedOps.set(svc, moved.displaced);
+        for (const id of livingDoc.duplicateIds) {
+            const slots = livingOps.filter((op) => op.id === id).map((op) => `${op.method} ${op.path}`);
+            issues.push({
+                severity: "warn",
+                code: "openapi.duplicate-operationid",
+                subject: svc,
+                message: `${svc}: the living OpenAPI defines operationId '${id}' at ${slots.join(" and ")} — every join on the id (a requirement's Operations: line, an edge's metadata { op }, a removal marker) picks one of those slots arbitrarily`,
+            });
+        }
+        // The baseline axis — operation pins, path-item keys and components —
+        // graded in its own package (openapi/baseline/gate.ts), slot-keyed
+        // exactly as the merge writes. Texts come through the context's memoized
+        // read when there is one, mirroring the readRequirements pattern above;
+        // the gate itself never touches the filesystem.
+        if (existsSync(paths.openapi)) {
+            // `readOr` (../openapi/contract-text.ts, which says why): `context.readText`
+            // throws on non-UTF-8 bytes where the no-context `readFile` lets
+            // `readOpenapi` flag the document unreadable — the exact
+            // context/no-context divergence doc.ts documents as paid for once.
+            // Either text failing to decode gets the same answer the gate gives
+            // an unreadable parse: that side's surface checks are skipped.
+            const featureText = await readOr(paths.openapi, context);
+            const livingText = !existsSync(livingOpenapiPath) ? undefined : await readOr(livingOpenapiPath, context);
+            if (featureText !== undefined) {
+                issues.push(...openapiBaselineIssues({ featDoc, livingDoc, featureText, livingText, service: svc, featureId }));
+            }
+        }
+        if (featOps.length > 0) {
+            const living = new Set(livingOps.filter((op) => !op.remove).map((op) => op.id));
+            for (const op of featOps) {
+                if (!op.remove && !living.has(op.id))
+                    featureApiOps.add(op.id);
+            }
+            // Removal is exact: the feature names both an operationId and the
+            // path+method slot it expects to delete. That catches stale deltas whose
+            // target moved or was already retired before the archive planner runs.
+            const justified = removedReqOps.get(svc) ?? new Set();
+            for (const marker of removals) {
+                const target = livingOps.find((op) => op.path === marker.path && op.method === marker.method);
+                if (target === undefined) {
+                    issues.push({
+                        severity: "error",
+                        code: "openapi.remove-target-missing",
+                        subject: svc,
+                        message: `${svc}: removal marker for '${marker.id}' addresses ${marker.method} ${marker.path}, but no living operation exists there`,
+                    });
+                }
+                else if (target.id !== marker.id) {
+                    issues.push({
+                        severity: "error",
+                        code: "openapi.remove-target-mismatch",
+                        subject: svc,
+                        message: `${svc}: removal marker names '${marker.id}' at ${marker.method} ${marker.path}, but the living operation there is '${target.id}'`,
+                    });
+                }
+                // A relocation needs no REMOVED requirement: the requirement governing
+                // the operation stays, the operation only changes address.
+                if (!netRemoved.has(marker.id))
+                    continue;
+                if (!justified.has(marker.id)) {
+                    issues.push({
+                        severity: "error",
+                        code: "openapi.remove-marker-unjustified",
+                        subject: svc,
+                        message: `${svc}: removal marker for '${marker.id}' is not governed by a REMOVED requirement's Operations: line`,
+                    });
+                }
+            }
+        }
+    }
+    for (const [svc, required] of removedReqOps) {
+        // The markers live in the unreadable file — "no matching marker" would
+        // be a claim about a document nobody could open.
+        if (unreadableApis.has(svc))
+            continue;
+        const marked = allMarkerIds.get(svc) ?? new Set();
+        const replaced = new Set((displacedOps.get(svc) ?? []).map((d) => d.id));
+        const living = livingIds.get(svc);
+        for (const op of required) {
+            if (marked.has(op))
+                continue;
+            // A marker is owed only while there is a living operation for it to
+            // retire — the event axis's rule (events/declared.ts) on the contract
+            // axis. An operation this delta already REPLACES at its address leaves
+            // the contract without one, and the marker could not even be written:
+            // the slot holds the replacement. So the route the overwrite's
+            // `openapi.remove-op-consumed` names — REMOVE the requirement governing
+            // the old id — ended in this error, followable only by deleting the
+            // requirement's Operations: line, which nothing said (review
+            // 2026-10-12, finding 4). And an id the service's living contract does
+            // not define is not this service's to mark at all: a REMOVED consumer
+            // requirement naming ANOTHER service's operation was told to retire it
+            // from its own contract. Both exemptions are facts about a contract
+            // loam READ: a living openapi.yaml that does not parse proves neither,
+            // so the marker stays owed — the closed direction, and the answer this
+            // check gave before either exemption existed. Skipping it there let a
+            // REMOVED requirement with no marker pass at exit 0 (the contract
+            // review, finding 3); `openapi.invalid` is still validate's finding
+            // about the file itself.
+            if (replaced.has(op) || (living !== undefined && living !== null && !living.has(op)))
+                continue;
+            // Distinguish "no marker at all" from "a marker is there but loam cannot
+            // read which operation it names" — the first asks the author to write the
+            // marker, the second to write the operationId, and telling somebody who
+            // already wrote the marker that there is none sends them looking for a
+            // file they are staring at.
+            issues.push({
+                severity: "error",
+                code: "openapi.remove-marker-missing",
+                subject: svc,
+                message: anonymousMarkers.get(svc) === true
+                    ? `${svc}: REMOVED requirement governs '${op}', and its feature openapi.yaml carries an x-loam-remove: true marker with no operationId — name '${op}' on that marker`
+                    : `${svc}: REMOVED requirement governs '${op}', but its feature openapi.yaml has no matching x-loam-remove: true marker`,
+            });
+        }
+    }
+    return {
+        reqOps, removedReqOps, removingOps, allMarkerIds, anonymousMarkers, featureApiOps, unreadableApis, revivalCandidates,
+        displacedOps,
+    };
+}
+//# sourceMappingURL=declared.js.map

package/dist/core/coherence/declared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared.js","sourceRoot":"","sources":["../../../src/core/coherence/declared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAwB,MAAM,0BAA0B,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AACpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAmC,MAAM,+BAA+B,CAAC;AAmDnG,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAiB,EACjB,QAA2B,EAC3B,MAAe,EACf,OAAsB;IAEtB,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;IACpD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAgC,CAAC;IAC9D,0FAA0F;IAC1F,MAAM,WAAW,GAAG,IAAI,GAAG,EAAuB,CAAC;IACnD,0EAA0E;IAC1E,MAAM,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;IACpD,iFAAiF;IACjF,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAmB,CAAC;IACpD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IACzC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA8B,CAAC;IAChE,MAAM,YAAY,GAAG,IAAI,GAAG,EAAmC,CAAC;IAChE,wGAAwG;IACxG,MAAM,SAAS,GAAG,IAAI,GAAG,EAAsC,CAAC;IAChE,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,kEAAkE;IAClE,yEAAyE;IACzE,2EAA2E;IAC3E,yBAAyB;IACzB,EAAE;IACF,yEAAyE;IACzE,2EAA2E;IAC3E,wEAAwE;IACxE,2EAA2E;IAC3E,sEAAsE;IACtE,uEAAuE;IACvE,yEAAyE;IACzE,2EAA2E;IAC3E,4BAA4B;IAC5B,MAAM,gBAAgB,GACpB,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;IACxH,MAAM,eAAe,GAAG,uBAAuB,CAC7C,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,EACrG,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACvC,CAAC;IACF,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,IAAI,eAAe,CAAC,OAAO,KAAK,SAAS,CAAC;IACjF,yEAAyE;IACzE,uEAAuE;IACvE,uEAAuE;IACvE,yEAAyE;IACzE,oEAAoE;IACpE,4CAA4C;IAC5C,IAAI,YAAY,GAA+C,IAAI,CAAC;IACpE,MAAM,cAAc,GAAG,GAAwC,EAAE;QAC/D,MAAM,IAAI,GAAG,OAAO,KAAK,SAAS;YAChC,CAAC,CAAC,KAAK,EAAE,CAAS,EAA0B,EAAE,CAAC,iBAAiB,CAAC,MAAM,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAC3F,CAAC,CAAC,CAAC,CAAS,EAA0B,EAAE,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;QACvE,yEAAyE;QACzE,oEAAoE;QACpE,0EAA0E;QAC1E,YAAY,KAAK,0BAA0B,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CACtF,uBAAuB,CACrB,KAAK,EACL,MAAM,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CACpG,CACF,CAAC;QACF,OAAO,YAAY,CAAC;IACtB,CAAC,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,gBAAgB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAChD,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,OAAO,KAAK,SAAS;gBAChC,CAAC,CAAC,iBAAiB,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACvD,CAAC,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/C,6EAA6E;YAC7E,2EAA2E;YAC3E,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;YACvF,aAAa,CAAC,GAAG,CACf,GAAG,EACH,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAC/E,CAAC;YACF,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,MAAM,GAAG,EAAE,KAAK,EAAE,GAAG,GAAG,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;gBAC1D,MAAM,CAAC,IAAI,CAAC,GAAG,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;gBACvE,MAAM,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,EAAE,CAAC,CAAC,CAAC;YAC9E,CAAC;QACH,CAAC;QACD,sEAAsE;QACtE,yEAAyE;QACzE,oEAAoE;QACpE,yEAAyE;QACzE,yEAAyE;QACzE,mEAAmE;QACnE,IAAI,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1C,MAAM,QAAQ,GAAG,OAAO,KAAK,SAAS;gBACpC,CAAC,CAAC,iBAAiB,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAC3D,CAAC,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACnD,MAAM,UAAU,GAAG,EAAE,KAAK,EAAE,GAAG,GAAG,gBAAgB,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;YACnE,MAAM,CAAC,IAAI,CAAC,GAAG,uBAAuB,CAAC,QAAQ,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC;YAC/E,MAAM,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,EAAE,CAAC,CAAC,CAAC;QACtF,CAAC;QACD,4EAA4E;QAC5E,0EAA0E;QAC1E,wEAAwE;QACxE,0EAA0E;QAC1E,kFAAkF;QAClF,uCAAuC;QACvC,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1D,yEAAyE;QACzE,kEAAkE;QAClE,sEAAsE;QACtE,qEAAqE;QACrE,sEAAsE;QACtE,qEAAqE;QACrE,wEAAwE;QACxE,sEAAsE;QACtE,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,iBAAiB;gBACvB,OAAO,EAAE,GAAG;gBACZ,OAAO,EAAE,GAAG,GAAG,+CAA+C,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,KAAK,GAAG,uGAAuG;aAC9N,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;QAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QACnD,mEAAmE;QACnE,yEAAyE;QACzE,wEAAwE;QACxE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QACrE,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACjC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACjC,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAEhE,oEAAoE;QACpE,2EAA2E;QAC3E,4EAA4E;QAC5E,oCAAoC;QACpC,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,iCAAiC;gBACvC,OAAO,EAAE,GAAG;gBACZ,OAAO,EAAE,GAAG,GAAG,KAAK,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,iKAAiK;aAClN,CAAC,CAAC;QACL,CAAC;QAED,MAAM,iBAAiB,GAAG,CAAC,MAAM,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QACpF,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;QAChE,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC;QAChC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACnH,MAAM,KAAK,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QAC3G,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACtD,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;QACvE,KAAK,MAAM,EAAE,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;YAC5F,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,+BAA+B;gBACrC,OAAO,EAAE,GAAG;gBACZ,OAAO,EAAE,GAAG,GAAG,6CAA6C,EAAE,QAAQ,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,8IAA8I;aACxO,CAAC,CAAC;QACL,CAAC;QACD,sEAAsE;QACtE,mEAAmE;QACnE,yEAAyE;QACzE,wEAAwE;QACxE,gDAAgD;QAChD,IAAI,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,6EAA6E;YAC7E,iEAAiE;YACjE,yDAAyD;YACzD,mEAAmE;YACnE,oEAAoE;YACpE,+DAA+D;YAC/D,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzD,MAAM,UAAU,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;YACzG,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,CAAC,IAAI,CACT,GAAG,qBAAqB,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CACnG,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAChF,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;gBACzB,IAAI,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;oBAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACjE,CAAC;YAED,kEAAkE;YAClE,yEAAyE;YACzE,uEAAuE;YACvE,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,EAAU,CAAC;YAC9D,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC9F,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,MAAM,CAAC,IAAI,CAAC;wBACV,QAAQ,EAAE,OAAO;wBACjB,IAAI,EAAE,+BAA+B;wBACrC,OAAO,EAAE,GAAG;wBACZ,OAAO,EAAE,GAAG,GAAG,yBAAyB,MAAM,CAAC,EAAE,eAAe,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,wCAAwC;qBACrI,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,MAAM,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC;oBACnC,MAAM,CAAC,IAAI,CAAC;wBACV,QAAQ,EAAE,OAAO;wBACjB,IAAI,EAAE,gCAAgC;wBACtC,OAAO,EAAE,GAAG;wBACZ,OAAO,EAAE,GAAG,GAAG,2BAA2B,MAAM,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,wCAAwC,MAAM,CAAC,EAAE,GAAG;qBAC5I,CAAC,CAAC;gBACL,CAAC;gBACD,uEAAuE;gBACvE,2DAA2D;gBAC3D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBAAE,SAAS;gBACzC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;oBAC9B,MAAM,CAAC,IAAI,CAAC;wBACV,QAAQ,EAAE,OAAO;wBACjB,IAAI,EAAE,mCAAmC;wBACzC,OAAO,EAAE,GAAG;wBACZ,OAAO,EAAE,GAAG,GAAG,yBAAyB,MAAM,CAAC,EAAE,+DAA+D;qBACjH,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,aAAa,EAAE,CAAC;QAC5C,uEAAuE;QACvE,iDAAiD;QACjD,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QACtC,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,EAAU,CAAC;QAC1D,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACzE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;YAC1B,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC7B,oEAAoE;YACpE,sEAAsE;YACtE,uEAAuE;YACvE,sEAAsE;YACtE,+DAA+D;YAC/D,wEAAwE;YACxE,oEAAoE;YACpE,6DAA6D;YAC7D,uEAAuE;YACvE,sEAAsE;YACtE,uEAAuE;YACvE,oEAAoE;YACpE,uEAAuE;YACvE,uEAAuE;YACvE,sEAAsE;YACtE,kEAAkE;YAClE,oEAAoE;YACpE,yBAAyB;YACzB,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAAE,SAAS;YAC/F,yEAAyE;YACzE,0EAA0E;YAC1E,wEAAwE;YACxE,uEAAuE;YACvE,4BAA4B;YAC5B,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,+BAA+B;gBACrC,OAAO,EAAE,GAAG;gBACZ,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI;oBACzC,CAAC,CAAC,GAAG,GAAG,kCAAkC,EAAE,qGAAqG,EAAE,kBAAkB;oBACrK,CAAC,CAAC,GAAG,GAAG,kCAAkC,EAAE,4EAA4E;aAC3H,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACH,OAAO;QACL,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,iBAAiB;QACpH,YAAY;KACb,CAAC;AACJ,CAAC","sourcesContent":["/**\n * What a feature's own delta DECLARES, per service, indexed once.\n *\n * Nine indexes over the same four files (the delta spec.md, arch.spec.md,\n * openapi.yaml, and the living contract they are graded against), built in one\n * walk because every check downstream joins on the service id and would\n * otherwise re-read the delta per question. The distinctions here are the ones\n * the checks cannot make for themselves: an operation a REMOVED requirement\n * governs is being retired, so it neither claims the contract nor governs\n * anything after the merge; a removal marker that names an id also defined\n * elsewhere in the delta is a RELOCATION, not a retirement; a living operation\n * another one replaces at its address, with no marker naming it, leaves the\n * contract all the same; and a marker with\n * no `operationId` at all is a shape only this walk can see. The capability\n * gate rides the same loop: both delta spec documents are graded against the\n * fleet vocabulary here, because coherence.ts and this package's file count\n * are both at their limits and the walk already holds the parsed documents.\n */\nimport { existsSync } from \"node:fs\";\nimport { readOr } from \"../openapi/contract-text.js\";\nimport { readFile } from \"node:fs/promises\";\nimport { type PathableService } from \"../kernel/ids/service.js\";\nimport type { Issue } from \"../vocabulary/issue.js\";\nimport { featureSpecPaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport { readCapabilityVocabulary } from \"../capabilities/capabilities.js\";\nimport { capabilityRequirementIndex } from \"../capabilities/findings.js\";\nimport { withFeatureCapabilities, withFeatureRequirements } from \"../capabilities/delta/overlay.js\";\nimport { featureCapabilityDeltas } from \"../capabilities/delta/tree.js\";\nimport { realizesUnknownIssues } from \"../capabilities/realizes/findings.js\";\nimport type { CapabilityRequirementIndex } from \"../capabilities/realizes/join.js\";\nimport { capabilityUnknownIssues } from \"../capabilities/findings.js\";\nimport type { Requirement } from \"../document/spec.js\";\nimport { openapiBaselineIssues } from \"../openapi/baseline/gate.js\";\nimport { readOpenapi } from \"../openapi/doc.js\";\nimport { operationRetirements } from \"./retired/retirement.js\";\nimport { operationArrivals, type Arrival, type Displacement } from \"./retired/revival/arrivals.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\n\n/** Everything one feature's delta says about its own services. */\nexport interface Declared {\n  /** Per service: the operations its non-REMOVED requirements govern. */\n  reqOps: Map<PathableService, string[]>;\n  /** Per service: the operations its REMOVED requirements governed. */\n  removedReqOps: Map<PathableService, Set<string>>;\n  /** Per service: operations this feature genuinely retires (markers minus relocations). */\n  removingOps: Map<string, Set<string>>;\n  /** Per service: every id a removal marker names, relocations included. */\n  allMarkerIds: Map<string, Set<string>>;\n  /** Per service: does the feature contract carry a marker with no operationId? */\n  anonymousMarkers: Map<string, boolean>;\n  /** The operationIds the living contract of their service does not hold, across the whole feature — new, or revived (see `revivalCandidates`). */\n  featureApiOps: Set<string>;\n  /**\n   * Services whose FEATURE openapi.yaml exists but does not parse. Every check\n   * that joins on the feature contract must suspend itself for these — an\n   * unreadable document yields the same empty op set as an absent one, and\n   * grading against that emptiness produced false errors pointing everywhere\n   * but at the broken file.\n   */\n  unreadableApis: Set<string>;\n  /**\n   * Per service: every (operationId, address) the contract the archive would\n   * write has and the living one lacks — an addition, or a revival of what an\n   * archived feature retired or moved away, which the living contract alone\n   * cannot tell apart. coherence.ts asks the retired index (./retired/) only\n   * when one of these lists is non-empty.\n   */\n  revivalCandidates: Map<PathableService, Arrival[]>;\n  /**\n   * Per service: every living operationId the contract the archive would\n   * write answers nowhere while no removal marker names it — replaced at its\n   * address by another operation (./retired/revival/arrivals.ts). The\n   * removal gate's consumers are asked of these too: the loss is the same,\n   * only the spelling differs.\n   */\n  displacedOps: Map<PathableService, Displacement[]>;\n}\n\n/** The three facts this walk needs about the feature it is reading. */\nexport interface DeltaScope {\n  docsDir: DocsDir;\n  featureDir: FeatureDir;\n  featureId: string;\n}\n\nexport async function declaredByService(\n  scope: DeltaScope,\n  svcNames: PathableService[],\n  issues: Issue[],\n  context?: FleetContext,\n): Promise<Declared> {\n  const { docsDir, featureDir, featureId } = scope;\n    const reqOps = new Map<PathableService, string[]>();\n    const removedReqOps = new Map<PathableService, Set<string>>();\n    /** Per service: operations this feature genuinely retires (markers minus relocations). */\n    const removingOps = new Map<string, Set<string>>();\n    /** Per service: every id a removal marker names, relocations included. */\n    const allMarkerIds = new Map<string, Set<string>>();\n    /** Per service: does the feature contract carry a marker with no operationId? */\n    const anonymousMarkers = new Map<string, boolean>();\n    const featureApiOps = new Set<string>();\n    const unreadableApis = new Set<string>();\n    const revivalCandidates = new Map<PathableService, Arrival[]>();\n    const displacedOps = new Map<PathableService, Displacement[]>();\n    /** Per service read here: the operationIds its living contract holds, or null when it does not read. */\n    const livingIds = new Map<string, ReadonlySet<string> | null>();\n    // The capability gate's vocabulary, once per call. Absent or invalid stays\n    // SILENT here — capability.invalid is validate --all's one finding about a\n    // broken file, and an absent file means the fleet never opted in — so with\n    // either, nothing new gates archive (the roadmap's own trade; the\n    // /loam-check row tells agents to fix the YAML first). `grading` is that\n    // silence hoisted into a guard, so a silent axis also skips the reads that\n    // exist only to feed it.\n    //\n    // The vocabulary is the one this feature's MERGE would leave behind, not\n    // the one on disk: a feature that adds a capability requirement in its own\n    // capability delta and `Realizes:` it from its own service delta is the\n    // flow the whole axis exists for, and graded against the living tree alone\n    // it is refused with `capability.realizes-unknown` — an error, gating\n    // archive, for a target the same archive creates. `capabilities/delta/\n    // overlay.ts` states the whole judgement. One `existsSync` for a feature\n    // that carries no capability delta, which is every feature in a fleet that\n    // has not adopted the axis.\n    const capabilityDeltas =\n      context === undefined ? await featureCapabilityDeltas(featureDir) : await context.featureCapabilityDeltas(featureDir);\n    const capabilityVocab = withFeatureCapabilities(\n      context === undefined ? await readCapabilityVocabulary(docsDir) : await context.capabilities(docsDir),\n      capabilityDeltas.docs.map((d) => d.id),\n    );\n    const grading = capabilityVocab.present && capabilityVocab.invalid === undefined;\n    // The `Realizes:` index, built at most ONCE per feature and only if some\n    // delta document actually reaches the grading branch. Lazy rather than\n    // eager because it reads every capability document in the fleet, and a\n    // feature whose deltas carry no requirement file at all must not pay for\n    // that — the same \"a silent axis skips the reads that feed it\" rule\n    // `grading` above states, one level deeper.\n    let pendingIndex: Promise<CapabilityRequirementIndex> | null = null;\n    const capabilityReqs = (): Promise<CapabilityRequirementIndex> => {\n      const read = context === undefined\n        ? async (p: string): Promise<Requirement[]> => parseRequirements(await readFile(p, \"utf8\"))\n        : (p: string): Promise<Requirement[]> => context.readRequirements(p);\n      // The living index first, then widened by what this feature's capability\n      // deltas ADD or MODIFY. Both halves are inside the lazy thunk, so a\n      // feature whose deltas carry no requirement file at all pays for neither.\n      pendingIndex ??= capabilityRequirementIndex(capabilityVocab, read).then(async (index) =>\n        withFeatureRequirements(\n          index,\n          await Promise.all(capabilityDeltas.docs.map(async (d) => ({ id: d.id, reqs: await read(d.spec) }))),\n        ),\n      );\n      return pendingIndex;\n    };\n    for (const svc of svcNames) {\n      const paths = featureSpecPaths(featureDir, svc);\n      if (existsSync(paths.spec)) {\n        const reqs = context === undefined\n          ? parseRequirements(await readFile(paths.spec, \"utf8\"))\n          : await context.readRequirements(paths.spec);\n        // REMOVED requirements are being retired along with their operations — their\n        // ops neither claim the contract (E1) nor govern anything after the merge.\n        reqOps.set(svc, reqs.filter((r) => r.kind !== \"REMOVED\").flatMap((r) => r.operations));\n        removedReqOps.set(\n          svc,\n          new Set(reqs.filter((r) => r.kind === \"REMOVED\").flatMap((r) => r.operations)),\n        );\n        if (grading) {\n          const target = { where: `${svc}: spec.md`, subject: svc };\n          issues.push(...capabilityUnknownIssues(reqs, target, capabilityVocab));\n          issues.push(...realizesUnknownIssues(reqs, target, await capabilityReqs()));\n        }\n      }\n      // The delta arch.spec.md carries the same grammar and merges the same\n      // way, so an undeclared capability in it gates identically. Nothing else\n      // in this walk needs the arch delta, so the read itself sits behind\n      // `grading` — and it is NOT always cached: `validate --feature` passes a\n      // context, but archive's plan gate (commands/archive/plan/gate.ts) calls\n      // featureCoherence without one, so this parse is paid fresh there.\n      if (grading && existsSync(paths.archSpec)) {\n        const archReqs = context === undefined\n          ? parseRequirements(await readFile(paths.archSpec, \"utf8\"))\n          : await context.readRequirements(paths.archSpec);\n        const archTarget = { where: `${svc}: arch.spec.md`, subject: svc };\n        issues.push(...capabilityUnknownIssues(archReqs, archTarget, capabilityVocab));\n        issues.push(...realizesUnknownIssues(archReqs, archTarget, await capabilityReqs()));\n      }\n      // Only operations the living contract does not hold count as feature-added:\n      // a delta may restate living operations it does not change (a quote), and\n      // a quote adds nothing. \"Not in living\" is not quite \"new\", though — an\n      // operation an archived feature RETIRED is absent too, and adding it back\n      // is `openapi.op-revived`'s question (./retired/revival/revived.ts), asked of the\n      // `revivalCandidates` collected below.\n      const featDoc = await readOpenapi(paths.openapi, context);\n      // A feature contract that EXISTS but does not read is a broken document,\n      // not an empty one — the living-side `openapi.invalid` discipline\n      // (validate/service/api.ts), applied to the delta. Before this check,\n      // `validate --feature` said nothing about the file at all: the empty\n      // parse silently skipped every baseline pin and removal marker in it,\n      // and E1 graded requirements against a contract that was never read.\n      // The rest of this service's contract-axis checks are suspended — every\n      // one of them would be an opinion about a document nobody could open.\n      if (featDoc.unreadable) {\n        unreadableApis.add(svc);\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.invalid\",\n          subject: svc,\n          message: `${svc}: this feature's openapi.yaml does not parse${featDoc.error === undefined ? \"\" : ` (${featDoc.error})`} — the contract axis is unchecked and the merge would have nothing true to write. Fix the YAML first.`,\n        });\n        continue;\n      }\n      const featOps = featDoc.ops;\n      const removals = featOps.filter((op) => op.remove);\n      // The raw marker set and the NET one (markers minus relocations) —\n      // ./retired/retirement.ts owns the rule and says why the two differ; the\n      // retired index reads every archived feature through the same function.\n      const { markerIds, net: netRemoved } = operationRetirements(featOps);\n      removingOps.set(svc, netRemoved);\n      allMarkerIds.set(svc, markerIds);\n      anonymousMarkers.set(svc, featDoc.anonymousRemovals.length > 0);\n\n      // A marker with no operationId names a slot but no operation. Every\n      // id-keyed check is blind to it, so it used to travel all the way into the\n      // living contract as a literal `x-loam-remove: true` — the one feature-only\n      // key that must never be published.\n      for (const marker of featDoc.anonymousRemovals) {\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.remove-marker-anonymous\",\n          subject: svc,\n          message: `${svc}: ${marker.method} ${marker.path} carries x-loam-remove: true but declares no operationId — loam cannot tell which operation it retires; name the operation the living contract has at that slot`,\n        });\n      }\n\n      const livingOpenapiPath = (await locateServicePaths(docsDir, svc, context)).openapi;\n      const livingDoc = await readOpenapi(livingOpenapiPath, context);\n      const livingOps = livingDoc.ops;\n      livingIds.set(svc, livingDoc.unreadable ? null : new Set(livingOps.filter((op) => !op.remove).map((op) => op.id)));\n      const sides = { featPath: paths.openapi, featDoc, livingPath: livingOpenapiPath, livingDoc, service: svc };\n      const moved = await operationArrivals(sides, context);\n      revivalCandidates.set(svc, moved.operations);\n      if (moved.displaced.length > 0) displacedOps.set(svc, moved.displaced);\n      for (const id of livingDoc.duplicateIds) {\n        const slots = livingOps.filter((op) => op.id === id).map((op) => `${op.method} ${op.path}`);\n        issues.push({\n          severity: \"warn\",\n          code: \"openapi.duplicate-operationid\",\n          subject: svc,\n          message: `${svc}: the living OpenAPI defines operationId '${id}' at ${slots.join(\" and \")} — every join on the id (a requirement's Operations: line, an edge's metadata { op }, a removal marker) picks one of those slots arbitrarily`,\n        });\n      }\n      // The baseline axis — operation pins, path-item keys and components —\n      // graded in its own package (openapi/baseline/gate.ts), slot-keyed\n      // exactly as the merge writes. Texts come through the context's memoized\n      // read when there is one, mirroring the readRequirements pattern above;\n      // the gate itself never touches the filesystem.\n      if (existsSync(paths.openapi)) {\n        // `readOr` (../openapi/contract-text.ts, which says why): `context.readText`\n        // throws on non-UTF-8 bytes where the no-context `readFile` lets\n        // `readOpenapi` flag the document unreadable — the exact\n        // context/no-context divergence doc.ts documents as paid for once.\n        // Either text failing to decode gets the same answer the gate gives\n        // an unreadable parse: that side's surface checks are skipped.\n        const featureText = await readOr(paths.openapi, context);\n        const livingText = !existsSync(livingOpenapiPath) ? undefined : await readOr(livingOpenapiPath, context);\n        if (featureText !== undefined) {\n          issues.push(\n            ...openapiBaselineIssues({ featDoc, livingDoc, featureText, livingText, service: svc, featureId }),\n          );\n        }\n      }\n\n      if (featOps.length > 0) {\n        const living = new Set(livingOps.filter((op) => !op.remove).map((op) => op.id));\n        for (const op of featOps) {\n          if (!op.remove && !living.has(op.id)) featureApiOps.add(op.id);\n        }\n\n        // Removal is exact: the feature names both an operationId and the\n        // path+method slot it expects to delete. That catches stale deltas whose\n        // target moved or was already retired before the archive planner runs.\n        const justified = removedReqOps.get(svc) ?? new Set<string>();\n        for (const marker of removals) {\n          const target = livingOps.find((op) => op.path === marker.path && op.method === marker.method);\n          if (target === undefined) {\n            issues.push({\n              severity: \"error\",\n              code: \"openapi.remove-target-missing\",\n              subject: svc,\n              message: `${svc}: removal marker for '${marker.id}' addresses ${marker.method} ${marker.path}, but no living operation exists there`,\n            });\n          } else if (target.id !== marker.id) {\n            issues.push({\n              severity: \"error\",\n              code: \"openapi.remove-target-mismatch\",\n              subject: svc,\n              message: `${svc}: removal marker names '${marker.id}' at ${marker.method} ${marker.path}, but the living operation there is '${target.id}'`,\n            });\n          }\n          // A relocation needs no REMOVED requirement: the requirement governing\n          // the operation stays, the operation only changes address.\n          if (!netRemoved.has(marker.id)) continue;\n          if (!justified.has(marker.id)) {\n            issues.push({\n              severity: \"error\",\n              code: \"openapi.remove-marker-unjustified\",\n              subject: svc,\n              message: `${svc}: removal marker for '${marker.id}' is not governed by a REMOVED requirement's Operations: line`,\n            });\n          }\n        }\n      }\n    }\n    for (const [svc, required] of removedReqOps) {\n      // The markers live in the unreadable file — \"no matching marker\" would\n      // be a claim about a document nobody could open.\n      if (unreadableApis.has(svc)) continue;\n      const marked = allMarkerIds.get(svc) ?? new Set<string>();\n      const replaced = new Set((displacedOps.get(svc) ?? []).map((d) => d.id));\n      const living = livingIds.get(svc);\n      for (const op of required) {\n        if (marked.has(op)) continue;\n        // A marker is owed only while there is a living operation for it to\n        // retire — the event axis's rule (events/declared.ts) on the contract\n        // axis. An operation this delta already REPLACES at its address leaves\n        // the contract without one, and the marker could not even be written:\n        // the slot holds the replacement. So the route the overwrite's\n        // `openapi.remove-op-consumed` names — REMOVE the requirement governing\n        // the old id — ended in this error, followable only by deleting the\n        // requirement's Operations: line, which nothing said (review\n        // 2026-10-12, finding 4). And an id the service's living contract does\n        // not define is not this service's to mark at all: a REMOVED consumer\n        // requirement naming ANOTHER service's operation was told to retire it\n        // from its own contract. Both exemptions are facts about a contract\n        // loam READ: a living openapi.yaml that does not parse proves neither,\n        // so the marker stays owed — the closed direction, and the answer this\n        // check gave before either exemption existed. Skipping it there let a\n        // REMOVED requirement with no marker pass at exit 0 (the contract\n        // review, finding 3); `openapi.invalid` is still validate's finding\n        // about the file itself.\n        if (replaced.has(op) || (living !== undefined && living !== null && !living.has(op))) continue;\n        // Distinguish \"no marker at all\" from \"a marker is there but loam cannot\n        // read which operation it names\" — the first asks the author to write the\n        // marker, the second to write the operationId, and telling somebody who\n        // already wrote the marker that there is none sends them looking for a\n        // file they are staring at.\n        issues.push({\n          severity: \"error\",\n          code: \"openapi.remove-marker-missing\",\n          subject: svc,\n          message: anonymousMarkers.get(svc) === true\n            ? `${svc}: REMOVED requirement governs '${op}', and its feature openapi.yaml carries an x-loam-remove: true marker with no operationId — name '${op}' on that marker`\n            : `${svc}: REMOVED requirement governs '${op}', but its feature openapi.yaml has no matching x-loam-remove: true marker`,\n        });\n      }\n    }\n  return {\n    reqOps, removedReqOps, removingOps, allMarkerIds, anonymousMarkers, featureApiOps, unreadableApis, revivalCandidates,\n    displacedOps,\n  };\n}\n"]}