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

package/dist/core/coherence/calls/called.js

@@ -0,0 +1,52 @@
+/**
+ * The services a feature's delta CALLS an operation on — the target of every
+ * tagged edge carrying `metadata { op }`, resolved the way coherence's own
+ * edge checks resolve it.
+ *
+ * Read for `loam status` (`core/status/contracts.ts`), which has to know
+ * whether a service is owed an `openapi.yaml` and used to answer "always" for a
+ * service the living docs had never heard of. An op-linked edge into a service
+ * is one of the two things that make its contract owed: `c4-api.op-undefined`
+ * grades exactly these edges against that file, so a service called this way
+ * with no contract is a gate error, and a status that said "none owed" beside
+ * it would contradict its own payload.
+ *
+ * A second reading of the join `../coherence.ts`'s edge loop makes, not that
+ * loop itself: the loop grades each edge as it goes and keeps no list. It lives
+ * beside it so the two are read together — the same tagged edges, the same
+ * fleet set handed to the same resolver — and a change to which edges the gate
+ * grades has to be made in both.
+ *
+ * Through the context's memo: both status forms have already parsed the delta
+ * by the time they ask (the coherence pass, the dependency graph), so this is
+ * a lookup, never a second LikeC4 workspace.
+ */
+import { existsSync } from "node:fs";
+import { serviceResolver } from "../../c4/resolve/service.js";
+import { featurePaths } from "../../repo/paths.js";
+import { featureSpecServices } from "../../repo/repo.js";
+import { enumeratedServiceIds } from "../../repo/service-target.js";
+/**
+ * The called services, or `unreadable` when the delta does not parse — which
+ * is not "nobody is called": loam could not look, and `delta.invalid` already
+ * gates. A feature with no delta calls nobody.
+ */
+export async function calledServices(scope, context) {
+    const { docsDir, featureDir, featureId } = scope;
+    const deltaPath = featurePaths(featureDir).delta;
+    if (!existsSync(deltaPath))
+        return new Set();
+    const doc = await context.loadLikeC4(deltaPath);
+    if (doc.errors.length > 0)
+        return "unreadable";
+    // The same fleet set coherence hands its resolver — `services/` plus this
+    // feature's own `specs/` — so an edge into a modelled container names the
+    // service that owns it, never a service called after the container.
+    const known = new Set([
+        ...(await enumeratedServiceIds(docsDir, context)),
+        ...(await featureSpecServices(featureDir, context)),
+    ]);
+    const svcOf = serviceResolver(doc.elements, known);
+    return new Set(doc.relationships.filter((r) => r.op !== undefined && r.tags.includes(featureId)).map((r) => svcOf(r.target)));
+}
+//# sourceMappingURL=called.js.map

package/dist/core/coherence/calls/called.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"called.js","sourceRoot":"","sources":["../../../../src/core/coherence/calls/called.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGpE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAiB,EAAE,OAAqB;IAC3E,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IACjD,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC;IACjD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAC7C,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IAC/C,0EAA0E;IAC1E,0EAA0E;IAC1E,oEAAoE;IACpE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS;QAC5B,GAAG,CAAC,MAAM,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjD,GAAG,CAAC,MAAM,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;KACpD,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACnD,OAAO,IAAI,GAAG,CACZ,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAC9G,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The services a feature's delta CALLS an operation on — the target of every\n * tagged edge carrying `metadata { op }`, resolved the way coherence's own\n * edge checks resolve it.\n *\n * Read for `loam status` (`core/status/contracts.ts`), which has to know\n * whether a service is owed an `openapi.yaml` and used to answer \"always\" for a\n * service the living docs had never heard of. An op-linked edge into a service\n * is one of the two things that make its contract owed: `c4-api.op-undefined`\n * grades exactly these edges against that file, so a service called this way\n * with no contract is a gate error, and a status that said \"none owed\" beside\n * it would contradict its own payload.\n *\n * A second reading of the join `../coherence.ts`'s edge loop makes, not that\n * loop itself: the loop grades each edge as it goes and keeps no list. It lives\n * beside it so the two are read together — the same tagged edges, the same\n * fleet set handed to the same resolver — and a change to which edges the gate\n * grades has to be made in both.\n *\n * Through the context's memo: both status forms have already parsed the delta\n * by the time they ask (the coherence pass, the dependency graph), so this is\n * a lookup, never a second LikeC4 workspace.\n */\nimport { existsSync } from \"node:fs\";\nimport { serviceResolver } from \"../../c4/resolve/service.js\";\nimport type { FleetContext } from \"../../fleet-context.js\";\nimport { featurePaths } from \"../../repo/paths.js\";\nimport { featureSpecServices } from \"../../repo/repo.js\";\nimport { enumeratedServiceIds } from \"../../repo/service-target.js\";\nimport type { DeltaScope } from \"../declared.js\";\n\n/**\n * The called services, or `unreadable` when the delta does not parse — which\n * is not \"nobody is called\": loam could not look, and `delta.invalid` already\n * gates. A feature with no delta calls nobody.\n */\nexport async function calledServices(scope: DeltaScope, context: FleetContext): Promise<ReadonlySet<string> | \"unreadable\"> {\n  const { docsDir, featureDir, featureId } = scope;\n  const deltaPath = featurePaths(featureDir).delta;\n  if (!existsSync(deltaPath)) return new Set();\n  const doc = await context.loadLikeC4(deltaPath);\n  if (doc.errors.length > 0) return \"unreadable\";\n  // The same fleet set coherence hands its resolver — `services/` plus this\n  // feature's own `specs/` — so an edge into a modelled container names the\n  // service that owns it, never a service called after the container.\n  const known = new Set<string>([\n    ...(await enumeratedServiceIds(docsDir, context)),\n    ...(await featureSpecServices(featureDir, context)),\n  ]);\n  const svcOf = serviceResolver(doc.elements, known);\n  return new Set(\n    doc.relationships.filter((r) => r.op !== undefined && r.tags.includes(featureId)).map((r) => svcOf(r.target)),\n  );\n}\n"]}

package/dist/core/coherence/coherence.js

@@ -0,0 +1,332 @@
+import { existsSync } from "node:fs";
+import { loadFile } from "../c4/likec4.js";
+import { elementService, serviceResolver } from "../c4/resolve/service.js";
+import { infrastructureKind } from "../c4/direction/direction.js";
+import { livingMapOf, readDeltaSystem } from "../c4/resolve/systems.js";
+import { extendingModels } from "../c4/service-model/fleet/extending.js";
+import { serviceIdProblem } from "../kernel/ids/service.js";
+import { deltaShapeIssues } from "../delta/delta.js";
+import { featurePaths, landscapePath } from "../repo/paths.js";
+import { featureSpecServices } from "../repo/repo.js";
+import { enumeratedServiceIds, enumeratedServiceIndex } from "../repo/service-target.js";
+import { serviceOperationIds } from "../openapi/doc.js";
+import { declaredByService } from "./declared.js";
+import { retiredLookup } from "./retired/archived.js";
+import { revivedOperations } from "./retired/revival/revived.js";
+import { coherenceLookups } from "./lookups.js";
+import { consumerIndex } from "../consumers/consumers.js";
+import { consumedOperationIssues } from "./consumed/operations.js";
+import { eventCoherence } from "./events/events.js";
+import { authoringIssues } from "./authoring/scaffold.js";
+import { droppedHealthCoverage } from "./covers/health.js";
+import { glossaryDeltaIssues } from "../glossary/delta.js";
+import { flowDeltaIssues } from "../usecases/delta/flows.js";
+import { deploymentDeltaIssues, readFeatureDeployments } from "../deployment/delta.js";
+export async function featureCoherence(request) {
+    const { docsDir, featureDir, featureId, preloadedDelta, context } = request;
+    const scope = { docsDir, featureDir, featureId };
+    // Delta shape first: a diff that does not apply to the living spec explains
+    // everything downstream, and it is the one breach that is silent without a check.
+    const issues = await deltaShapeIssues(docsDir, featureDir, featureId, context);
+    // The vocabulary axis, and it is asked first because it is cheap and
+    // independent: one `existsSync` for a feature with no glossary/, and nothing
+    // downstream reads its answer. A term this feature introduces that the living
+    // glossary already defines is the one thing that can go wrong on a create-only
+    // merge, and it must be caught before the copy, not after.
+    issues.push(...(await glossaryDeltaIssues(docsDir, featureDir)));
+    // The use-case axis, and it is asked here for the vocabulary axis's reasons
+    // exactly: one walk over a directory that is usually absent, nothing
+    // downstream reads its answer, and a create-only merge has one thing that can
+    // go wrong. A flow this feature introduces that the living `architecture/`
+    // already holds must be caught before the copy, not after it has replaced an
+    // authored hop sequence.
+    issues.push(...(await flowDeltaIssues(docsDir, featureDir)));
+    issues.push(...(await deploymentDeltaIssues(docsDir, featureDir)));
+    // And the topology's second question, which the collision check above cannot
+    // ask: does the document READ against the map this feature's own merge would
+    // leave behind. It matters more literally here than one axis over — a feature
+    // that stands a service up in a new cluster declares that service in its
+    // `delta.likec4` and instances it in the topology, so the element the document
+    // names exists only post-merge — and without it the archive copies an
+    // unreadable document into `architecture/` for the next reader's
+    // `loam validate --all` to fail on, against a file they did not write.
+    const topology = await readFeatureDeployments({
+        docsDir,
+        featureDir,
+        featureId,
+        // A function rather than the context itself, for the reason the use-case
+        // overlay states: one memoised read does not justify an edge from
+        // `core/deployment/` to `fleet-context`.
+        ...(context === undefined ? {} : { load: (path) => context.loadLikeC4(path) }),
+        // The fleet's extending models, so the preview is the map the archive would
+        // really leave: a nested addition is routed into the service's own model,
+        // never onto the map. Read here for the same reason `load` is passed here —
+        // this module holds the context and `core/deployment/` does not — and as a
+        // thunk, so a feature with no `deployment/` directory pays nothing for it.
+        models: () => extendingModels(docsDir, context),
+    });
+    if (topology.kind === "unreadable") {
+        issues.push({
+            severity: "error",
+            code: "deployment.doc-invalid",
+            subject: featureId,
+            // The opening sentence does not say whose file is at fault, on the
+            // `usecase.flow-invalid` message's reasoning: the corpus is the feature's
+            // `deployment/` PLUS the living `architecture/` documents it extends, so
+            // the failing path can be a living one — a landscape that no longer
+            // parses, a topology somebody else wrote. Every message carries its own
+            // path, so a reader can place it.
+            message: `this feature's deployment document(s) could not be read against the map its own merge would leave behind, ` +
+                `so the archive would land an architecture/ nothing has checked. The corpus is the feature's deployment/ AND ` +
+                `the living architecture/ documents it extends, so the fault may be in either — each message names its file. ` +
+                `${topology.errors.length} problem(s): ${topology.errors.join("; ")}`,
+        });
+    }
+    // --- C4 delta ---
+    let elements = [];
+    let taggedEls = [];
+    let taggedRels = [];
+    const deltaPath = featurePaths(featureDir).delta;
+    if (existsSync(deltaPath)) {
+        const res = preloadedDelta ?? (context === undefined ? await loadFile(deltaPath) : await context.loadLikeC4(deltaPath));
+        if (res.errors.length > 0) {
+            // An unreadable architecture axis can prove nothing — it must never count as coherent.
+            issues.push({
+                severity: "error",
+                code: "delta.invalid",
+                message: `delta.likec4 has ${res.errors.length} parse error(s) — architecture axis unreadable (run \`loam validate --feature ${featureId}\`)`,
+            });
+        }
+        else {
+            elements = res.elements;
+            taggedEls = res.elements.filter((e) => e.tags.includes(featureId));
+            taggedRels = res.relationships.filter((r) => r.tags.includes(featureId));
+            // Every rule below filters by the feature tag, so a delta whose author
+            // forgot the tags entirely passes every check and archives while merging
+            // nothing. Whole-file only: once ANYTHING is tagged, deciding that an
+            // untagged edge "looks intended" would be guessing.
+            if ((res.elements.length > 0 || res.relationships.length > 0) &&
+                taggedEls.length === 0 &&
+                taggedRels.length === 0) {
+                issues.push({
+                    severity: "error",
+                    code: "delta.nothing-tagged",
+                    message: `delta.likec4 declares elements/relationships but none are tagged #${featureId}; loam cannot see untagged changes`,
+                });
+            }
+        }
+    }
+    // --- per-service specs (requirement operations) + openapi deltas ---
+    const svcNames = await featureSpecServices(featureDir, context);
+    // Every axis below joins on the service id, so endpoints resolve through the
+    // element's `metadata { service }` binding — never through what the box is
+    // called. The enumerated fleet — `services/` plus this feature's own
+    // `specs/` directories, the same union `enumeratedTarget` probes below —
+    // rides into the resolver so a delta that models CONTAINERS joins correctly:
+    // without it, an edge into `payment.api` resolves to a service called "api"
+    // that has never existed, and every check below grades the edge against an
+    // absent service instead of the one that owns the container. An unenumerable
+    // services/ falls back to the feature's own names — every living probe would
+    // have found nothing there anyway.
+    const fleetIds = await enumeratedServiceIds(docsDir, context);
+    const known = new Set([...fleetIds, ...svcNames]);
+    const svcOf = serviceResolver(elements, known);
+    // Which elements the landscape merge would SPLICE: the tagged ones and
+    // everything nested inside their blocks. Defined here because two checks
+    // share it — the scaffold gate just below, and the binding-grammar check
+    // near the end of this function — and the merge carries a tagged element's
+    // authored block over byte for byte, children included, so a scope narrower
+    // than the splice lets a nested child's text ride through unread.
+    const taggedIds = taggedEls.map((el) => el.id);
+    const ridesWithTag = (el) => el.tags.includes(featureId) || taggedIds.some((id) => el.id.startsWith(`${id}.`));
+    // The scaffold gate: placeholder text and an unwritten intent are legal
+    // documents whose merge would publish content nobody authored — the exact
+    // template strings `loam new` wrote (authoring/scaffold.ts owns the list).
+    issues.push(...(await authoringIssues({ featureDir, featureId, splicedEls: elements.filter(ridesWithTag), svcNames, context })));
+    const { reqOps, removingOps, featureApiOps, unreadableApis, revivalCandidates, displacedOps, } = await declaredByService(scope, svcNames, issues, context);
+    // A revival: an operation the merged contract would answer that the living
+    // contract no longer has because an ARCHIVED feature retired it — or would
+    // answer again at an address an archived feature took it out of, beside
+    // where it lives now — and the merge would read it as an addition and put
+    // it back (./retired/ says why the gate could not see this before). One
+    // lazy handle for both contract axes, so the walk of features/archive/ is
+    // paid once per call at most, and only when the merged contract answers
+    // something at an address the living one does not.
+    const retired = retiredLookup(docsDir, context);
+    for (const [svc, arrived] of revivalCandidates) {
+        if (arrived.length === 0)
+            continue;
+        issues.push(...revivedOperations(svc, arrived, await retired()));
+    }
+    const { governedByLivingSpec, definedElsewhere, deprecatedInLiving, undeprecatedByFeature } = coherenceLookups(scope, context);
+    // --- taking an operation out of the contract while the fleet still calls it ---
+    // ./consumed/operations.ts owns the gate; the index is built here because
+    // the event axis below asks the same one, so the fleet is read once.
+    const consumers = consumerIndex({ docsDir, context, afterFeature: featureDir });
+    issues.push(...(await consumedOperationIssues({ consumers, removingOps, displacedOps })));
+    // E1: Spec -> API — every operation a requirement governs must exist in that service's OpenAPI.
+    for (const [svc, ops] of reqOps) {
+        // The union below reads the feature's own contract; unreadable means the
+        // op may well be defined in the file nobody could open, and `op-undefined`
+        // would point the author at the requirement when the truth is the YAML.
+        // `openapi.invalid` (declared.ts) already gates; one breach, one finding.
+        if (unreadableApis.has(svc))
+            continue;
+        const available = await serviceOperationIds(docsDir, svc, featureDir, context);
+        for (const op of ops) {
+            if (available.includes(op))
+                continue;
+            const other = await definedElsewhere(svc, op);
+            if (other !== undefined) {
+                issues.push({ severity: "warn", code: "spec-api.op-pending", message: `requirement in ${svc} governs '${op}', defined by in-flight ${other} — archive it first` });
+                continue;
+            }
+            issues.push({ severity: "error", code: "spec-api.op-undefined", message: `requirement in ${svc} governs '${op}', not defined in ${svc}'s OpenAPI` });
+        }
+    }
+    // The declared→enumerated bridge for edge TARGETS. `svcOf` answers with
+    // whatever the document wrote — `metadata { service '../../x' }` parses in
+    // LikeC4 without one error — and every living lookup below joins its answer
+    // into `services/<target>/` or `specs/<target>/`. So a target resolves
+    // through the enumerations first (the fleet's `services/` plus this
+    // feature's own `specs/`, where a service it introduces lives), and a name
+    // neither knows skips the lookups — no ops, not governed, not deprecated —
+    // grading exactly as an absent service, spelled with the declared name.
+    const enumeratedTarget = enumeratedServiceIndex(docsDir, svcNames, context);
+    // E2 / W1 / W4: C4 edges vs API + requirements.
+    for (const r of taggedRels) {
+        if (r.op === undefined) {
+            if ((r.title ?? "").toLowerCase().startsWith("call")) {
+                issues.push({ severity: "warn", code: "c4.op-link-missing", message: `edge ${svcOf(r.source)} → ${svcOf(r.target)} ("${r.title}") has no operation link (metadata { op })` });
+            }
+            continue;
+        }
+        const target = svcOf(r.target);
+        const pathable = await enumeratedTarget(target);
+        // Same suspension as E1, but only for the verdicts that READ a contract:
+        // does the op exist, is it being removed, is it deprecated (whose
+        // un-deprecation escape reads the feature contract too). Each of those
+        // would be an opinion about a file nobody could open. The governance
+        // question below is deliberately NOT suspended — it joins the edge against
+        // requirement documents alone, so the broken YAML could never change its
+        // answer, and silencing it deferred a real warning for no reason.
+        const contractUnreadable = pathable !== undefined && unreadableApis.has(pathable);
+        const available = pathable === undefined || contractUnreadable
+            ? []
+            : await serviceOperationIds(docsDir, pathable, featureDir, context);
+        if (contractUnreadable) {
+            // openapi.invalid (declared.ts) already gates; one breach, one finding.
+        }
+        else if (pathable !== undefined &&
+            // An operation replaced at its address leaves as surely as a retired
+            // one; `available` below still lists it, because serviceOperationIds
+            // subtracts markers only, so without this a new edge onto it passed.
+            (removingOps.get(pathable)?.has(r.op) === true || displacedOps.get(pathable)?.some((d) => d.id === r.op) === true)) {
+            issues.push({ severity: "error", code: "c4-api.op-removing", message: `${svcOf(r.source)} builds new consumption on '${r.op}', which this feature removes from ${target}` });
+        }
+        else if (!available.includes(r.op)) {
+            const other = await definedElsewhere(target, r.op);
+            if (other !== undefined) {
+                issues.push({ severity: "warn", code: "c4-api.op-pending", message: `${svcOf(r.source)} calls '${r.op}' on ${target}, defined by in-flight ${other} — archive it first` });
+            }
+            else {
+                issues.push({ severity: "error", code: "c4-api.op-undefined", message: `${svcOf(r.source)} calls '${r.op}' on ${target}, but ${target}'s OpenAPI does not define it (contract broken)` });
+            }
+        }
+        // Governed by THIS target's requirements, not by anybody's. An operationId
+        // is unique only inside one contract, so the fleet-wide set this used to
+        // ask meant a `getStatus` governed in service A silenced the question for
+        // service B's entirely unrelated `getStatus` — the warning went quiet for
+        // the edge that needed it, and only in repos where some other service
+        // happened to reuse the name. The living half on the same line has always
+        // joined per service (`governedByLivingSpec(target, …)`); this is the delta
+        // half asking it the same way.
+        if (pathable === undefined || (!(reqOps.get(pathable) ?? []).includes(r.op) && !(await governedByLivingSpec(pathable, r.op)))) {
+            issues.push({ severity: "warn", code: "c4.op-ungoverned", message: `'${r.op}' is called by ${svcOf(r.source)} but no requirement governs it` });
+        }
+        // Lifecycle: this NEW tagged edge builds consumption on an operation the
+        // living provider contract already marks deprecated. Advisory, never an
+        // archive gate — the edge is legal and the contract holds — but new
+        // consumption of a dying op deserves an eye before it ships. Quiet when
+        // the feature's own openapi delta drops the flag: that state is the fix
+        // in progress, not new consumption of a dying op.
+        if (!contractUnreadable && pathable !== undefined && (await deprecatedInLiving(pathable, r.op)) && !(await undeprecatedByFeature(pathable, r.op))) {
+            issues.push({ severity: "warn", code: "c4-api.op-deprecated", message: `${svcOf(r.source)} builds new consumption on '${r.op}', which ${target}'s living OpenAPI marks deprecated — prefer the replacement operation` });
+        }
+    }
+    // W2: API -> C4 — every operation the feature adds should be consumed by some edge.
+    const consumed = new Set(taggedRels.map((r) => r.op).filter((o) => o !== undefined));
+    for (const op of featureApiOps) {
+        if (!consumed.has(op)) {
+            issues.push({ severity: "warn", code: "api.op-unconsumed", message: `operation '${op}' is added but no architecture edge consumes it (provider-only or unmodeled)` });
+        }
+    }
+    // W3: a new service should carry a requirement delta. "New service" is the
+    // fleet census's reading of the map this merge leaves (../c4/resolve/systems.ts):
+    // a tagged `#external` producer, a grouping and a container are no service of
+    // ours, and asking each for a `specs/` delta put a unit of work nobody owes
+    // on the board and a warning the archived fleet never repeats. Nor is a
+    // service the fleet already holds new — its own directory, or a box the
+    // living map draws — whatever the delta's tag says: re-declaring is not
+    // introducing.
+    // The living map is parsed only for a candidate no directory answers for.
+    const systems = {
+        elements,
+        known,
+        living: new Set(fleetIds),
+        livingMap: livingMapOf(landscapePath(docsDir), (path) => (context === undefined ? loadFile(path) : context.loadLikeC4(path))),
+    };
+    for (const e of taggedEls) {
+        const svc = elementService(e);
+        if (e.kind !== "softwareSystem" || svcNames.some((n) => n === svc))
+            continue;
+        if ((await readDeltaSystem(e, systems)) !== "service")
+            continue;
+        issues.push({ severity: "warn", code: "service.no-requirement-delta", message: `new service ${svc} has no requirement delta under specs/` });
+    }
+    // An explicit `metadata { service '<id>' }` binding, held to the same grammar
+    // every `--service` flag is — on the tagged elements AND everything nested
+    // inside their blocks. The scope is the splice's, not the tag's: the
+    // landscape merge carries a tagged element's authored block over byte for
+    // byte, children included (landscape-merge.ts's rides() exists exactly so a
+    // child travels inside its parent's text), so an untagged container's
+    // binding reaches the living map as surely as its tagged parent's — and
+    // checking only the tagged elements themselves let it ride through unread.
+    // The binding is the one name the archive TRUSTS: the merge splices it into
+    // the living map verbatim, and the new-service scan probes
+    // `services/<binding>/` with it — where `metadata { service '../outside-svc' }`,
+    // which LikeC4 parses without a murmur, collapses the probe right out of
+    // services/, and the spliced map fails the very next `validate --all`
+    // (`landscape.binding-unknown`). Explicit bindings only, on purpose: a prose
+    // title with no binding is legal C4, and a title becomes a path only through
+    // `specs/<svc>/`, whose own grammar check (`delta.service-id-invalid`)
+    // guards that route. `ridesWithTag` itself is defined up beside the scaffold
+    // gate, which shares the splice's scope for the same reason.
+    for (const e of elements.filter(ridesWithTag)) {
+        if (e.service === undefined)
+            continue;
+        const problem = serviceIdProblem(e.service, "metadata { service } binding");
+        if (problem === null)
+            continue;
+        issues.push({
+            severity: "error",
+            code: "c4.service-binding-invalid",
+            subject: e.service,
+            message: `'${e.title}' (${e.id}) — ${problem} ` +
+                `\`loam archive\` would splice '${e.service}' into the living landscape.likec4 exactly as written, ` +
+                `and probe services/${e.service}/ with it. Bind the element to the services/<id>/ directory it means.`,
+        });
+    }
+    // The event axis — the same three-way agreement the operation checks above
+    // grade, joined on the message name instead of the operationId: the
+    // feature's asyncapi deltas (pins, markers, justification), the tagged
+    // edges' publishes/consumes metadata, and the requirement deltas'
+    // Publishes:/Consumes: lines (./events/events.ts owns the walk).
+    const infraKindOf = infrastructureKind(elements);
+    issues.push(...(await eventCoherence({ scope, svcNames, taggedRels, svcOf, infraKindOf, context, retired, consumers, known })));
+    // The health axis's one merge question: an alert or SLI the living
+    // arch.spec.md covers that this delta would leave covered by nothing.
+    issues.push(...(await droppedHealthCoverage({ docsDir, featureDir, services: svcNames, ...(context === undefined ? {} : { context }) })));
+    return issues;
+}
+//# sourceMappingURL=coherence.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coherence.js","sourceRoot":"","sources":["../../../src/core/coherence/coherence.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"node:fs\";\nimport { loadFile, type Elem, type LoadedDoc, type Rel } from \"../c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../c4/resolve/service.js\";\nimport { infrastructureKind } from \"../c4/direction/direction.js\";\nimport { livingMapOf, readDeltaSystem } from \"../c4/resolve/systems.js\";\nimport { extendingModels } from \"../c4/service-model/fleet/extending.js\";\nimport { serviceIdProblem } from \"../kernel/ids/service.js\";\nimport { deltaShapeIssues } from \"../delta/delta.js\";\nimport type { Issue } from \"../vocabulary/issue.js\";\nimport { featurePaths, landscapePath } from \"../repo/paths.js\";\nimport { featureSpecServices } from \"../repo/repo.js\";\nimport { enumeratedServiceIds, enumeratedServiceIndex } from \"../repo/service-target.js\";\nimport { serviceOperationIds } from \"../openapi/doc.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { declaredByService, type DeltaScope } from \"./declared.js\";\nimport { retiredLookup } from \"./retired/archived.js\";\nimport { revivedOperations } from \"./retired/revival/revived.js\";\nimport { coherenceLookups } from \"./lookups.js\";\nimport { consumerIndex } from \"../consumers/consumers.js\";\nimport { consumedOperationIssues } from \"./consumed/operations.js\";\nimport { eventCoherence } from \"./events/events.js\";\nimport { authoringIssues } from \"./authoring/scaffold.js\";\nimport { droppedHealthCoverage } from \"./covers/health.js\";\nimport { glossaryDeltaIssues } from \"../glossary/delta.js\";\nimport { flowDeltaIssues } from \"../usecases/delta/flows.js\";\nimport { deploymentDeltaIssues, readFeatureDeployments } from \"../deployment/delta.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * Cross-axis consistency for a feature: do C4 (architecture), requirements (behaviour),\n * and OpenAPI (contract) agree? Errors are hard (would corrupt the living docs on archive);\n * warnings surface softer misalignments.\n *\n * `preloadedDelta` is the feature's already-parsed delta.likec4, when the caller\n * has it — loading a LikeC4 document spins up a fresh Langium workspace, the\n * dominant per-feature cost, and validate/archive have both parsed the same file\n * moments earlier. Standalone calls omit it and nothing changes: the file is\n * loaded here, exactly as before.\n */\n\n/** How a caller names the feature being graded, and what it already has in hand. */\nexport interface CoherenceRequest {\n  docsDir: DocsDir;\n  featureDir: FeatureDir;\n  featureId: string;\n  /** The delta LikeC4 document, when the caller already parsed it. */\n  preloadedDelta?: LoadedDoc;\n  context?: FleetContext;\n}\n\nexport async function featureCoherence(request: CoherenceRequest): Promise<Issue[]> {\n  const { docsDir, featureDir, featureId, preloadedDelta, context } = request;\n  const scope: DeltaScope = { docsDir, featureDir, featureId };\n  // Delta shape first: a diff that does not apply to the living spec explains\n  // everything downstream, and it is the one breach that is silent without a check.\n  const issues: Issue[] = await deltaShapeIssues(docsDir, featureDir, featureId, context);\n\n  // The vocabulary axis, and it is asked first because it is cheap and\n  // independent: one `existsSync` for a feature with no glossary/, and nothing\n  // downstream reads its answer. A term this feature introduces that the living\n  // glossary already defines is the one thing that can go wrong on a create-only\n  // merge, and it must be caught before the copy, not after.\n  issues.push(...(await glossaryDeltaIssues(docsDir, featureDir)));\n\n  // The use-case axis, and it is asked here for the vocabulary axis's reasons\n  // exactly: one walk over a directory that is usually absent, nothing\n  // downstream reads its answer, and a create-only merge has one thing that can\n  // go wrong. A flow this feature introduces that the living `architecture/`\n  // already holds must be caught before the copy, not after it has replaced an\n  // authored hop sequence.\n  issues.push(...(await flowDeltaIssues(docsDir, featureDir)));\n  issues.push(...(await deploymentDeltaIssues(docsDir, featureDir)));\n\n  // And the topology's second question, which the collision check above cannot\n  // ask: does the document READ against the map this feature's own merge would\n  // leave behind. It matters more literally here than one axis over — a feature\n  // that stands a service up in a new cluster declares that service in its\n  // `delta.likec4` and instances it in the topology, so the element the document\n  // names exists only post-merge — and without it the archive copies an\n  // unreadable document into `architecture/` for the next reader's\n  // `loam validate --all` to fail on, against a file they did not write.\n  const topology = await readFeatureDeployments({\n    docsDir,\n    featureDir,\n    featureId,\n    // A function rather than the context itself, for the reason the use-case\n    // overlay states: one memoised read does not justify an edge from\n    // `core/deployment/` to `fleet-context`.\n    ...(context === undefined ? {} : { load: (path: string) => context.loadLikeC4(path) }),\n    // The fleet's extending models, so the preview is the map the archive would\n    // really leave: a nested addition is routed into the service's own model,\n    // never onto the map. Read here for the same reason `load` is passed here —\n    // this module holds the context and `core/deployment/` does not — and as a\n    // thunk, so a feature with no `deployment/` directory pays nothing for it.\n    models: () => extendingModels(docsDir, context),\n  });\n  if (topology.kind === \"unreadable\") {\n    issues.push({\n      severity: \"error\",\n      code: \"deployment.doc-invalid\",\n      subject: featureId,\n      // The opening sentence does not say whose file is at fault, on the\n      // `usecase.flow-invalid` message's reasoning: the corpus is the feature's\n      // `deployment/` PLUS the living `architecture/` documents it extends, so\n      // the failing path can be a living one — a landscape that no longer\n      // parses, a topology somebody else wrote. Every message carries its own\n      // path, so a reader can place it.\n      message:\n        `this feature's deployment document(s) could not be read against the map its own merge would leave behind, ` +\n        `so the archive would land an architecture/ nothing has checked. The corpus is the feature's deployment/ AND ` +\n        `the living architecture/ documents it extends, so the fault may be in either — each message names its file. ` +\n        `${topology.errors.length} problem(s): ${topology.errors.join(\"; \")}`,\n    });\n  }\n\n  // --- C4 delta ---\n  let elements: Elem[] = [];\n  let taggedEls: Elem[] = [];\n  let taggedRels: Rel[] = [];\n  const deltaPath = featurePaths(featureDir).delta;\n  if (existsSync(deltaPath)) {\n    const res = preloadedDelta ?? (context === undefined ? await loadFile(deltaPath) : await context.loadLikeC4(deltaPath));\n    if (res.errors.length > 0) {\n      // An unreadable architecture axis can prove nothing — it must never count as coherent.\n      issues.push({\n        severity: \"error\",\n        code: \"delta.invalid\",\n        message: `delta.likec4 has ${res.errors.length} parse error(s) — architecture axis unreadable (run \\`loam validate --feature ${featureId}\\`)`,\n      });\n    } else {\n      elements = res.elements;\n      taggedEls = res.elements.filter((e) => e.tags.includes(featureId));\n      taggedRels = res.relationships.filter((r) => r.tags.includes(featureId));\n      // Every rule below filters by the feature tag, so a delta whose author\n      // forgot the tags entirely passes every check and archives while merging\n      // nothing. Whole-file only: once ANYTHING is tagged, deciding that an\n      // untagged edge \"looks intended\" would be guessing.\n      if (\n        (res.elements.length > 0 || res.relationships.length > 0) &&\n        taggedEls.length === 0 &&\n        taggedRels.length === 0\n      ) {\n        issues.push({\n          severity: \"error\",\n          code: \"delta.nothing-tagged\",\n          message: `delta.likec4 declares elements/relationships but none are tagged #${featureId}; loam cannot see untagged changes`,\n        });\n      }\n    }\n  }\n  // --- per-service specs (requirement operations) + openapi deltas ---\n  const svcNames = await featureSpecServices(featureDir, context);\n\n  // Every axis below joins on the service id, so endpoints resolve through the\n  // element's `metadata { service }` binding — never through what the box is\n  // called. The enumerated fleet — `services/` plus this feature's own\n  // `specs/` directories, the same union `enumeratedTarget` probes below —\n  // rides into the resolver so a delta that models CONTAINERS joins correctly:\n  // without it, an edge into `payment.api` resolves to a service called \"api\"\n  // that has never existed, and every check below grades the edge against an\n  // absent service instead of the one that owns the container. An unenumerable\n  // services/ falls back to the feature's own names — every living probe would\n  // have found nothing there anyway.\n  const fleetIds = await enumeratedServiceIds(docsDir, context);\n  const known = new Set([...fleetIds, ...svcNames]);\n  const svcOf = serviceResolver(elements, known);\n\n  // Which elements the landscape merge would SPLICE: the tagged ones and\n  // everything nested inside their blocks. Defined here because two checks\n  // share it — the scaffold gate just below, and the binding-grammar check\n  // near the end of this function — and the merge carries a tagged element's\n  // authored block over byte for byte, children included, so a scope narrower\n  // than the splice lets a nested child's text ride through unread.\n  const taggedIds = taggedEls.map((el) => el.id);\n  const ridesWithTag = (el: Elem): boolean =>\n    el.tags.includes(featureId) || taggedIds.some((id) => el.id.startsWith(`${id}.`));\n\n  // The scaffold gate: placeholder text and an unwritten intent are legal\n  // documents whose merge would publish content nobody authored — the exact\n  // template strings `loam new` wrote (authoring/scaffold.ts owns the list).\n  issues.push(\n    ...(await authoringIssues({ featureDir, featureId, splicedEls: elements.filter(ridesWithTag), svcNames, context })),\n  );\n  const {\n    reqOps, removingOps, featureApiOps, unreadableApis, revivalCandidates, displacedOps,\n  } = await declaredByService(scope, svcNames, issues, context);\n\n  // A revival: an operation the merged contract would answer that the living\n  // contract no longer has because an ARCHIVED feature retired it — or would\n  // answer again at an address an archived feature took it out of, beside\n  // where it lives now — and the merge would read it as an addition and put\n  // it back (./retired/ says why the gate could not see this before). One\n  // lazy handle for both contract axes, so the walk of features/archive/ is\n  // paid once per call at most, and only when the merged contract answers\n  // something at an address the living one does not.\n  const retired = retiredLookup(docsDir, context);\n  for (const [svc, arrived] of revivalCandidates) {\n    if (arrived.length === 0) continue;\n    issues.push(...revivedOperations(svc, arrived, await retired()));\n  }\n  const { governedByLivingSpec, definedElsewhere, deprecatedInLiving, undeprecatedByFeature } = coherenceLookups(scope, context);\n\n  // --- taking an operation out of the contract while the fleet still calls it ---\n  // ./consumed/operations.ts owns the gate; the index is built here because\n  // the event axis below asks the same one, so the fleet is read once.\n  const consumers = consumerIndex({ docsDir, context, afterFeature: featureDir });\n  issues.push(...(await consumedOperationIssues({ consumers, removingOps, displacedOps })));\n\n  // E1: Spec -> API — every operation a requirement governs must exist in that service's OpenAPI.\n  for (const [svc, ops] of reqOps) {\n    // The union below reads the feature's own contract; unreadable means the\n    // op may well be defined in the file nobody could open, and `op-undefined`\n    // would point the author at the requirement when the truth is the YAML.\n    // `openapi.invalid` (declared.ts) already gates; one breach, one finding.\n    if (unreadableApis.has(svc)) continue;\n    const available = await serviceOperationIds(docsDir, svc, featureDir, context);\n    for (const op of ops) {\n      if (available.includes(op)) continue;\n      const other = await definedElsewhere(svc, op);\n      if (other !== undefined) {\n        issues.push({ severity: \"warn\", code: \"spec-api.op-pending\", message: `requirement in ${svc} governs '${op}', defined by in-flight ${other} — archive it first` });\n        continue;\n      }\n      issues.push({ severity: \"error\", code: \"spec-api.op-undefined\", message: `requirement in ${svc} governs '${op}', not defined in ${svc}'s OpenAPI` });\n    }\n  }\n\n  // The declared→enumerated bridge for edge TARGETS. `svcOf` answers with\n  // whatever the document wrote — `metadata { service '../../x' }` parses in\n  // LikeC4 without one error — and every living lookup below joins its answer\n  // into `services/<target>/` or `specs/<target>/`. So a target resolves\n  // through the enumerations first (the fleet's `services/` plus this\n  // feature's own `specs/`, where a service it introduces lives), and a name\n  // neither knows skips the lookups — no ops, not governed, not deprecated —\n  // grading exactly as an absent service, spelled with the declared name.\n  const enumeratedTarget = enumeratedServiceIndex(docsDir, svcNames, context);\n\n  // E2 / W1 / W4: C4 edges vs API + requirements.\n  for (const r of taggedRels) {\n    if (r.op === undefined) {\n      if ((r.title ?? \"\").toLowerCase().startsWith(\"call\")) {\n        issues.push({ severity: \"warn\", code: \"c4.op-link-missing\", message: `edge ${svcOf(r.source)} → ${svcOf(r.target)} (\"${r.title}\") has no operation link (metadata { op })` });\n      }\n      continue;\n    }\n    const target = svcOf(r.target);\n    const pathable = await enumeratedTarget(target);\n    // Same suspension as E1, but only for the verdicts that READ a contract:\n    // does the op exist, is it being removed, is it deprecated (whose\n    // un-deprecation escape reads the feature contract too). Each of those\n    // would be an opinion about a file nobody could open. The governance\n    // question below is deliberately NOT suspended — it joins the edge against\n    // requirement documents alone, so the broken YAML could never change its\n    // answer, and silencing it deferred a real warning for no reason.\n    const contractUnreadable = pathable !== undefined && unreadableApis.has(pathable);\n    const available =\n      pathable === undefined || contractUnreadable\n        ? []\n        : await serviceOperationIds(docsDir, pathable, featureDir, context);\n    if (contractUnreadable) {\n      // openapi.invalid (declared.ts) already gates; one breach, one finding.\n    } else if (\n      pathable !== undefined &&\n      // An operation replaced at its address leaves as surely as a retired\n      // one; `available` below still lists it, because serviceOperationIds\n      // subtracts markers only, so without this a new edge onto it passed.\n      (removingOps.get(pathable)?.has(r.op) === true || displacedOps.get(pathable)?.some((d) => d.id === r.op) === true)\n    ) {\n      issues.push({ severity: \"error\", code: \"c4-api.op-removing\", message: `${svcOf(r.source)} builds new consumption on '${r.op}', which this feature removes from ${target}` });\n    } else if (!available.includes(r.op)) {\n      const other = await definedElsewhere(target, r.op);\n      if (other !== undefined) {\n        issues.push({ severity: \"warn\", code: \"c4-api.op-pending\", message: `${svcOf(r.source)} calls '${r.op}' on ${target}, defined by in-flight ${other} — archive it first` });\n      } else {\n        issues.push({ severity: \"error\", code: \"c4-api.op-undefined\", message: `${svcOf(r.source)} calls '${r.op}' on ${target}, but ${target}'s OpenAPI does not define it (contract broken)` });\n      }\n    }\n    // Governed by THIS target's requirements, not by anybody's. An operationId\n    // is unique only inside one contract, so the fleet-wide set this used to\n    // ask meant a `getStatus` governed in service A silenced the question for\n    // service B's entirely unrelated `getStatus` — the warning went quiet for\n    // the edge that needed it, and only in repos where some other service\n    // happened to reuse the name. The living half on the same line has always\n    // joined per service (`governedByLivingSpec(target, …)`); this is the delta\n    // half asking it the same way.\n    if (pathable === undefined || (!(reqOps.get(pathable) ?? []).includes(r.op) && !(await governedByLivingSpec(pathable, r.op)))) {\n      issues.push({ severity: \"warn\", code: \"c4.op-ungoverned\", message: `'${r.op}' is called by ${svcOf(r.source)} but no requirement governs it` });\n    }\n    // Lifecycle: this NEW tagged edge builds consumption on an operation the\n    // living provider contract already marks deprecated. Advisory, never an\n    // archive gate — the edge is legal and the contract holds — but new\n    // consumption of a dying op deserves an eye before it ships. Quiet when\n    // the feature's own openapi delta drops the flag: that state is the fix\n    // in progress, not new consumption of a dying op.\n    if (!contractUnreadable && pathable !== undefined && (await deprecatedInLiving(pathable, r.op)) && !(await undeprecatedByFeature(pathable, r.op))) {\n      issues.push({ severity: \"warn\", code: \"c4-api.op-deprecated\", message: `${svcOf(r.source)} builds new consumption on '${r.op}', which ${target}'s living OpenAPI marks deprecated — prefer the replacement operation` });\n    }\n  }\n\n  // W2: API -> C4 — every operation the feature adds should be consumed by some edge.\n  const consumed = new Set(taggedRels.map((r) => r.op).filter((o): o is string => o !== undefined));\n  for (const op of featureApiOps) {\n    if (!consumed.has(op)) {\n      issues.push({ severity: \"warn\", code: \"api.op-unconsumed\", message: `operation '${op}' is added but no architecture edge consumes it (provider-only or unmodeled)` });\n    }\n  }\n\n  // W3: a new service should carry a requirement delta. \"New service\" is the\n  // fleet census's reading of the map this merge leaves (../c4/resolve/systems.ts):\n  // a tagged `#external` producer, a grouping and a container are no service of\n  // ours, and asking each for a `specs/` delta put a unit of work nobody owes\n  // on the board and a warning the archived fleet never repeats. Nor is a\n  // service the fleet already holds new — its own directory, or a box the\n  // living map draws — whatever the delta's tag says: re-declaring is not\n  // introducing.\n  // The living map is parsed only for a candidate no directory answers for.\n  const systems = {\n    elements,\n    known,\n    living: new Set<string>(fleetIds),\n    livingMap: livingMapOf(landscapePath(docsDir), (path) => (context === undefined ? loadFile(path) : context.loadLikeC4(path))),\n  };\n  for (const e of taggedEls) {\n    const svc: string = elementService(e);\n    if (e.kind !== \"softwareSystem\" || svcNames.some((n) => n === svc)) continue;\n    if ((await readDeltaSystem(e, systems)) !== \"service\") continue;\n    issues.push({ severity: \"warn\", code: \"service.no-requirement-delta\", message: `new service ${svc} has no requirement delta under specs/` });\n  }\n\n  // An explicit `metadata { service '<id>' }` binding, held to the same grammar\n  // every `--service` flag is — on the tagged elements AND everything nested\n  // inside their blocks. The scope is the splice's, not the tag's: the\n  // landscape merge carries a tagged element's authored block over byte for\n  // byte, children included (landscape-merge.ts's rides() exists exactly so a\n  // child travels inside its parent's text), so an untagged container's\n  // binding reaches the living map as surely as its tagged parent's — and\n  // checking only the tagged elements themselves let it ride through unread.\n  // The binding is the one name the archive TRUSTS: the merge splices it into\n  // the living map verbatim, and the new-service scan probes\n  // `services/<binding>/` with it — where `metadata { service '../outside-svc' }`,\n  // which LikeC4 parses without a murmur, collapses the probe right out of\n  // services/, and the spliced map fails the very next `validate --all`\n  // (`landscape.binding-unknown`). Explicit bindings only, on purpose: a prose\n  // title with no binding is legal C4, and a title becomes a path only through\n  // `specs/<svc>/`, whose own grammar check (`delta.service-id-invalid`)\n  // guards that route. `ridesWithTag` itself is defined up beside the scaffold\n  // gate, which shares the splice's scope for the same reason.\n  for (const e of elements.filter(ridesWithTag)) {\n    if (e.service === undefined) continue;\n    const problem = serviceIdProblem(e.service, \"metadata { service } binding\");\n    if (problem === null) continue;\n    issues.push({\n      severity: \"error\",\n      code: \"c4.service-binding-invalid\",\n      subject: e.service,\n      message:\n        `'${e.title}' (${e.id}) — ${problem} ` +\n        `\\`loam archive\\` would splice '${e.service}' into the living landscape.likec4 exactly as written, ` +\n        `and probe services/${e.service}/ with it. Bind the element to the services/<id>/ directory it means.`,\n    });\n  }\n\n  // The event axis — the same three-way agreement the operation checks above\n  // grade, joined on the message name instead of the operationId: the\n  // feature's asyncapi deltas (pins, markers, justification), the tagged\n  // edges' publishes/consumes metadata, and the requirement deltas'\n  // Publishes:/Consumes: lines (./events/events.ts owns the walk).\n  const infraKindOf = infrastructureKind(elements);\n  issues.push(...(await eventCoherence({ scope, svcNames, taggedRels, svcOf, infraKindOf, context, retired, consumers, known })));\n\n  // The health axis's one merge question: an alert or SLI the living\n  // arch.spec.md covers that this delta would leave covered by nothing.\n  issues.push(...(await droppedHealthCoverage({ docsDir, featureDir, services: svcNames, ...(context === undefined ? {} : { context }) })));\n\n  return issues;\n}\n"]}

package/dist/core/coherence/consumed/operations.js

@@ -0,0 +1,70 @@
+import { nothingStill, refusalDetails, refusalMessage, stillNamed } from "./refusal.js";
+export async function consumedOperationIssues(request) {
+    const { consumers, removingOps, displacedOps } = request;
+    const issues = [];
+    // --- taking an operation out of the contract while the fleet still calls it ---
+    // Exactness and justification never ask what matters to the other
+    // ninety-nine repos: is anybody still calling it? The merge deletes the
+    // operation while the edge, the requirement and the use-case hop naming it
+    // stay, so the next `validate --all` breaks a repository whose author was
+    // never in this feature. Asked of the ONE consumer index, read after this
+    // feature's merge (core/consumers/ says what it reads and what a feature can
+    // retire). `own` counts too: for a marker the REMOVED requirement leaves with
+    // the merge, so what remains is a second one, or an internal edge. One index
+    // for both shapes and the event axis, so the fleet is read once. A consumer
+    // document the index could not read or place refuses too (./refusal.ts):
+    // "nobody could look" never let a removal through before the one index.
+    const still = async (svc, op) => stillNamed(await consumers.opConsumers(svc, op));
+    // The landscape merge only ADDS edges, so an edge is dropped or redrawn in the living map itself.
+    const route = `drop or redraw its edge in the architecture/ project, MODIFY or REMOVE the requirement that names it in this feature's specs/<service>/ delta`;
+    for (const [svc, retiring] of removingOps) {
+        for (const op of retiring) {
+            const found = await still(svc, op);
+            if (nothingStill(found))
+                continue;
+            issues.push({
+                severity: "error",
+                code: "openapi.remove-op-consumed",
+                subject: svc,
+                details: refusalDetails(found),
+                message: refusalMessage(found, {
+                    subject: svc,
+                    lost: `this feature retires '${op}'`,
+                    verb: "consume",
+                    named: (list) => `${svc}: this feature retires '${op}', but the fleet would still consume it after this merge — ${list}. Retire each consumer in the same change (${route}), or archive with --approve to break it deliberately.`,
+                }),
+            });
+        }
+    }
+    // The same loss with no marker to read: another operation defined where a
+    // consumed one lives replaces it there, and once the contract the merge
+    // would write defines it nowhere it has left the contract exactly as a
+    // retirement does. One code, because the breach and its override are the
+    // removal's — only `api.op-unconsumed` (advisory) said anything before, and
+    // the archive passed without `--approve`. With no marker there is no REMOVED
+    // requirement either, so the provider's own requirement naming the old id
+    // stays unless this feature restates it — `own` is what catches it.
+    for (const [svc, displaced] of displacedOps) {
+        for (const { id: op, at } of displaced) {
+            const found = await still(svc, op);
+            if (nothingStill(found))
+                continue;
+            const by = at.map(({ address, by: id }) => `${id === undefined ? "an operation with no operationId" : `'${id}'`} at ${address}`).join(" and ");
+            const lost = `this feature's openapi.yaml defines ${by}, where '${op}' lives now — the merge replaces it there and would leave '${op}' defined nowhere`;
+            issues.push({
+                severity: "error",
+                code: "openapi.remove-op-consumed",
+                subject: svc,
+                details: refusalDetails(found),
+                message: refusalMessage(found, {
+                    subject: svc,
+                    lost,
+                    verb: "consume",
+                    named: (list) => `${svc}: ${lost}, but it is still consumed — ${list}. Define '${op}' at another address in this delta if it is to stay. To take it out on purpose, update every consumer in the same change — ${route} (${svc}'s own restated to name the new operation, for a rename; a REMOVED one owes no x-loam-remove marker, since the overwrite already takes '${op}' out) — or archive with --approve to break it deliberately.`,
+                }),
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=operations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../../src/core/coherence/consumed/operations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The contract axis's removal gate, `openapi.remove-op-consumed`: does the\n * fleet still consume an operation this feature takes out of the contract —\n * by a removal marker, or by defining another operation where it lives?\n *\n * Moved out of `../coherence.ts`, which ran at its 400-line limit, along the\n * seam the gate already had there: everything below asks the consumer index\n * (core/consumers/) one question per operation the merge loses and phrases\n * the refusal, and nothing else in featureCoherence reads its answer. The\n * index itself is built there and handed in, because the event axis's twin\n * (`asyncapi.remove-message-consumed`, ../events/events.ts) asks the same one.\n */\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport type { ConsumerIndex } from \"../../consumers/consumers.js\";\nimport type { Declared } from \"../declared.js\";\nimport { nothingStill, refusalDetails, refusalMessage, stillNamed, type StillNamed } from \"./refusal.js\";\n\n/** What the gate is asked over: the shared index, and the two ways this feature's merge loses an operation. */\nexport interface ConsumedOperationsRequest {\n  /** The consumer index, read after this feature's merge — shared with the event axis so the fleet is read once. */\n  consumers: ConsumerIndex;\n  removingOps: Declared[\"removingOps\"];\n  displacedOps: Declared[\"displacedOps\"];\n}\n\nexport async function consumedOperationIssues(request: ConsumedOperationsRequest): Promise<Issue[]> {\n  const { consumers, removingOps, displacedOps } = request;\n  const issues: Issue[] = [];\n  // --- taking an operation out of the contract while the fleet still calls it ---\n  // Exactness and justification never ask what matters to the other\n  // ninety-nine repos: is anybody still calling it? The merge deletes the\n  // operation while the edge, the requirement and the use-case hop naming it\n  // stay, so the next `validate --all` breaks a repository whose author was\n  // never in this feature. Asked of the ONE consumer index, read after this\n  // feature's merge (core/consumers/ says what it reads and what a feature can\n  // retire). `own` counts too: for a marker the REMOVED requirement leaves with\n  // the merge, so what remains is a second one, or an internal edge. One index\n  // for both shapes and the event axis, so the fleet is read once. A consumer\n  // document the index could not read or place refuses too (./refusal.ts):\n  // \"nobody could look\" never let a removal through before the one index.\n  const still = async (svc: string, op: string): Promise<StillNamed> => stillNamed(await consumers.opConsumers(svc, op));\n  // The landscape merge only ADDS edges, so an edge is dropped or redrawn in the living map itself.\n  const route = `drop or redraw its edge in the architecture/ project, MODIFY or REMOVE the requirement that names it in this feature's specs/<service>/ delta`;\n  for (const [svc, retiring] of removingOps) {\n    for (const op of retiring) {\n      const found = await still(svc, op);\n      if (nothingStill(found)) continue;\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.remove-op-consumed\",\n        subject: svc,\n        details: refusalDetails(found),\n        message: refusalMessage(found, {\n          subject: svc,\n          lost: `this feature retires '${op}'`,\n          verb: \"consume\",\n          named: (list) => `${svc}: this feature retires '${op}', but the fleet would still consume it after this merge — ${list}. Retire each consumer in the same change (${route}), or archive with --approve to break it deliberately.`,\n        }),\n      });\n    }\n  }\n\n  // The same loss with no marker to read: another operation defined where a\n  // consumed one lives replaces it there, and once the contract the merge\n  // would write defines it nowhere it has left the contract exactly as a\n  // retirement does. One code, because the breach and its override are the\n  // removal's — only `api.op-unconsumed` (advisory) said anything before, and\n  // the archive passed without `--approve`. With no marker there is no REMOVED\n  // requirement either, so the provider's own requirement naming the old id\n  // stays unless this feature restates it — `own` is what catches it.\n  for (const [svc, displaced] of displacedOps) {\n    for (const { id: op, at } of displaced) {\n      const found = await still(svc, op);\n      if (nothingStill(found)) continue;\n      const by = at.map(({ address, by: id }) => `${id === undefined ? \"an operation with no operationId\" : `'${id}'`} at ${address}`).join(\" and \");\n      const lost = `this feature's openapi.yaml defines ${by}, where '${op}' lives now — the merge replaces it there and would leave '${op}' defined nowhere`;\n      issues.push({\n        severity: \"error\",\n        code: \"openapi.remove-op-consumed\",\n        subject: svc,\n        details: refusalDetails(found),\n        message: refusalMessage(found, {\n          subject: svc,\n          lost,\n          verb: \"consume\",\n          named: (list) => `${svc}: ${lost}, but it is still consumed — ${list}. Define '${op}' at another address in this delta if it is to stay. To take it out on purpose, update every consumer in the same change — ${route} (${svc}'s own restated to name the new operation, for a rename; a REMOVED one owes no x-loam-remove marker, since the overwrite already takes '${op}' out) — or archive with --approve to break it deliberately.`,\n        }),\n      });\n    }\n  }\n  return issues;\n}\n"]}

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

@@ -0,0 +1,38 @@
+import { documentDoubt } from "../../consumers/scan.js";
+/**
+ * The gate's reading of one answer: `victims` and `own` as evidence, and of the
+ * suspensions only the document doubts. A caller drawn with no op and a
+ * contested hop stay out — `documentDoubt` (core/consumers/scan.ts) says why
+ * they are a warning's worth in `loam diff` and nothing here.
+ */
+export function stillNamed(found) {
+    return {
+        named: [...found.victims, ...found.own],
+        unchecked: [...found.suspended, ...found.ownSuspended].filter(documentDoubt).map((s) => s.text),
+    };
+}
+/** Nothing named and nothing unchecked: the removal is the gate's to let through. */
+export function nothingStill(still) {
+    return still.named.length === 0 && still.unchecked.length === 0;
+}
+/** The one remedy every unchecked document shares, after "make". */
+const READABLE = "each document listed readable (re-save it as UTF-8, or leave one directory per service id) so the gate can answer";
+/**
+ * The message for one refusal. With named consumers it is the gate's own
+ * sentence, plus one more when documents went unchecked too; with only
+ * unchecked documents it never claims a consumer — "nobody could look" is not
+ * "somebody still calls it", any more than it is "nobody does".
+ */
+export function refusalMessage(still, wording) {
+    const unchecked = still.unchecked.join("; ");
+    if (still.named.length === 0) {
+        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.`;
+    }
+    const named = wording.named(still.named.join("; "));
+    return still.unchecked.length === 0 ? named : `${named} Whether anything else would still ${wording.verb} it could not be checked either — ${unchecked}: make ${READABLE}.`;
+}
+/** What a refusal's `details[]` lists: the named consumers, then the documents nobody could check. */
+export function refusalDetails(still) {
+    return [...still.named, ...still.unchecked];
+}
+//# sourceMappingURL=refusal.js.map