@ybotok/loam 0.2.0-alpha.5 → 0.2.0-alpha.6

package/dist/commands/validate/fleet/map/consumers.js

@@ -0,0 +1,298 @@
+/**
+ * Who consumes a drawn element — and the datastore grades that read the answer.
+ *
+ * The census used to walk the MAP's relationships alone, and under the extending
+ * shape that is a partial view of the fleet: a service draws the container-level
+ * call in its own `model.likec4` and the map carries the service-level twin, so a
+ * store whose consuming edges were all drawn in models had ZERO consumers and
+ * earned nothing at all, while a store reached by three models and one map edge
+ * was reported `landscape.datastore-private` naming the one service the map
+ * happened to draw (R1). A model is evidence about the fleet exactly as the map
+ * is, so both are counted here, once, by one derivation two checks share.
+ *
+ * WHERE A PRIVATE STORE LIVES, stated once because three surfaces used to answer
+ * it differently: a store one service owns is NESTED UNDER THAT SERVICE'S
+ * ELEMENT — in the service's extending model (`extend <fqn> { store = database
+ * … }`), or inside the service's element on the map when the map draws that
+ * service's containers. A second service reaching it later is drawn where that
+ * service draws every other call: a container-level edge in ITS model naming
+ * `<owner-fqn>.<store>`, carried up to the map as a service-level edge to the
+ * owning service. Nothing moves back, and nothing goes ungraded — a nested store
+ * two services reach is `landscape.datastore-shared` here (E3).
+ *
+ * WHICH OF THE TWO PLACEMENTS, and this is measured rather than assumed: a
+ * per-service project is `architecture/` plus that ONE model, so an edge naming
+ * `<owner-fqn>.<store>` resolves for the second service only when the MAP
+ * declares the store. Written in the owner's `extend` block instead, the same
+ * edge is two errors on the consumer's own model ("Could not resolve reference
+ * to Referenceable named 'store'"), so that store is private for good and its
+ * second consumer can only ever be drawn at service level. The message below
+ * says so; SCHEMA carries the same sentence.
+ *
+ * The choice is cheap, and both messages now say exactly HOW cheap, because
+ * "reversible" was false in the one state that used to assert it. The two
+ * placements do give the store the same id, `<owner-fqn>.<store>` — but the
+ * move is only free in ONE direction once a second service names it. Measured
+ * on `examples/docs`: moving `db` out of order-service's `extend` block into
+ * `orderService` on the map left the model at 12 elements · 8 relationships,
+ * left `Covers: marketplace.orderService.db` in its arch.spec.md resolving, and
+ * left checkout-web's container-level edge to it resolving too. Moving it BACK
+ * with that second edge drawn is two errors on checkout-web's own model
+ * ("Could not resolve reference to Referenceable named 'db'"), or
+ * `landscape.invalid` plus one `spine.landscape-invalid` per service when the
+ * second edge is drawn on the map — because an `extend` block is visible to its
+ * own service's project alone. `datastore-shared` printed the unconditional
+ * clause in 100% of the states it fires in, every one of which already has the
+ * second consumer that makes map→extend break (verification 2026-09-04). So the
+ * rule both messages now state is directional: extend→map is always safe;
+ * map→extend only while no other service's model or map edge names the store.
+ *
+ * And the remedy is named for the consumer's own model SHAPE rather than
+ * assumed: `extend <fqn>` in a STANDALONE model (one that declares its own
+ * `specification`) resolves nothing, because such a model is parsed alone — so
+ * prescribing it there turns a clean run into `c4.invalid`. The shape comes off
+ * the same `./attest.ts` record the consumer join reads.
+ *
+ * A sub-package of `fleet/` for `./isolation.ts`'s reason and with its rule: it
+ * imports NOTHING from `fleet/`, so the map facts it reads arrive on the input
+ * records the caller fills.
+ */
+import {} from "../../../../core/c4/likec4.js";
+import {} from "../../../../core/vocabulary/report.js";
+import {} from "./attest.js";
+/** The element kind read as a datastore, compared case-insensitively. */
+const DATASTORE_KIND = "database";
+/**
+ * Distinct consumer SERVICES of an element, its nested children included: an
+ * edge into `kafka.paymentEvents` is consumption of `kafka`.
+ *
+ * Two kinds of evidence, unioned. From the MAP: a relationship whose target is
+ * the element or a descendant and whose source the shared resolver files under a
+ * real `services/<id>/` — persons, other external systems and unresolved sources
+ * never count, and two edges from one service are one consumer. From the
+ * MODELS: a service whose own model attests an OUTBOUND call at the element or a
+ * descendant.
+ *
+ * The model half reads EXTENDING models only, and the reason is the id space. An
+ * extending model's ids are the map's fully-qualified ids — one project — so the
+ * join is exact. A standalone model's ids are its own file's, and
+ * `core/c4/resolve/attested.ts` says outright that a counterpart is never
+ * matched to a landscape element: joining one would file a coincidence of
+ * spelling as a coupling between two services.
+ */
+export function consumerCensus(input) {
+    const reaches = (elementId, id) => id === elementId || id.startsWith(`${elementId}.`);
+    return (elementId) => {
+        const out = new Set();
+        for (const r of input.relationships) {
+            if (!reaches(elementId, r.target))
+                continue;
+            const svc = input.resolve(r.source);
+            if (input.services.has(svc))
+                out.add(svc);
+        }
+        for (const model of input.attested) {
+            if (!model.extending)
+                continue;
+            if (model.calls.some((c) => c.direction === "out" && reaches(elementId, c.counterpartId))) {
+                out.add(model.service);
+            }
+        }
+        return [...out].sort();
+    };
+}
+/**
+ * A datastore drawn as a fleet-level peer makes a claim its consumer count
+ * either supports or refutes: one consumer means the drawing is false — the
+ * store is that service's internals, not a system in its own right — while two
+ * or more mean the strongest coupling two services can have, which deserves to
+ * be stated rather than inferred. A NESTED store is private by construction, so
+ * it is silent at one consumer and earns the same `datastore-shared` at two.
+ */
+export function datastoreFindings(input) {
+    const findings = [];
+    for (const e of input.drawn) {
+        // An element that stands for a real service is the fleet itself, not its
+        // shape; a datastore bound to a directory is graded by the binding checks.
+        if (input.standsForService(e))
+            continue;
+        if (e.kind.toLowerCase() !== DATASTORE_KIND)
+            continue;
+        const consumers = input.consumers(e.id);
+        if (consumers.length === 0)
+            continue;
+        findings.push(consumers.length === 1 ? privateFinding(e, consumers[0], input) : sharedFinding(e.title, consumers, "", ""));
+    }
+    for (const store of nestedStoresOf(input)) {
+        // The owner is a consumer by construction — the store sits inside the element
+        // that resolves to it — so silence at one consumer IS the fixed state, and
+        // the only question left is whether a second service reaches the same data.
+        const consumers = [...new Set([store.owner, ...input.consumers(store.fqn)])].sort();
+        if (consumers.length < 2)
+            continue;
+        findings.push(sharedFinding(store.title, consumers, 
+        // The store's own id, and said as such. The clause read "nested under
+        // '<fqn>'", which sends a reader looking for an element that HOLDS the
+        // store — when that id IS the store, and its container is its prefix.
+        ` — ${store.owner}'s own store, written as '${store.fqn}'`, reversibility(store, consumers.filter((c) => c !== store.owner))));
+    }
+    return findings;
+}
+/**
+ * Every store nested under the element that resolves to its owner, from both
+ * places the stance allows one to be written: inside the service's element ON
+ * THE MAP, and in the service's own extending model. Keyed by fqn, so a
+ * map-declared store — which the owner's model slice carries too, since a slice
+ * is everything resolving to the service — is one store and not two.
+ *
+ * Both sources are needed and neither is redundant. The map's covers a service
+ * whose model is standalone or absent (no slice to read); the model's covers a
+ * store the map never draws, which is the placement the adopt brief prescribes.
+ */
+function nestedStoresOf(input) {
+    const drawnIds = new Set(input.drawn.map((e) => e.id));
+    const byFqn = new Map();
+    for (const e of input.elements) {
+        if (e.kind.toLowerCase() !== DATASTORE_KIND || drawnIds.has(e.id))
+            continue;
+        // The peer branch's guard, which this half was missing: a `database` bound
+        // with `metadata { service '<id>' }` and drawn one level down became a store
+        // "owned" by its own binding, so a second reader made it a shared datastore
+        // and the fix offered was to give each service its own copy of a service.
+        if (input.standsForService(e))
+            continue;
+        const owner = input.resolve(e.id);
+        if (!input.services.has(owner))
+            continue;
+        byFqn.set(e.id, { owner, fqn: e.id, title: e.title });
+    }
+    for (const store of input.nestedStores)
+        if (!byFqn.has(store.fqn))
+            byFqn.set(store.fqn, store);
+    return [...byFqn.values()];
+}
+/**
+ * Which way the store may still be moved, now that a second service reaches it.
+ *
+ * The clause this replaces said the two placements were interchangeable — "the
+ * two placements give it the same id … so moving the declaration between them
+ * rewrites no edge" — and that is false in every state `datastore-shared` fires
+ * in, because the finding needs a second consumer and a second consumer's edge
+ * resolves only against a store the MAP declares (a per-service project is
+ * `architecture/` plus one model). Measured: performing the move the sentence
+ * called free turned a clean `examples/docs` into `c4.invalid` on the consumer's
+ * model, or into `landscape.invalid` + one `spine.landscape-invalid` per service
+ * when the second edge is on the map (verification 2026-09-04).
+ *
+ * The direction is stated rather than the current placement, and it holds
+ * either way round: out of the owner's `extend` block onto the map is always
+ * safe, back in is not while another service names the store. (In practice a
+ * store this finding reaches is one the MAP declares — a second consumer's edge
+ * cannot resolve against an `extend` block, so it could never have been drawn
+ * — which is the same fact said from the other side.)
+ */
+function reversibility(store, others) {
+    const named = others.length === 1 ? `${others[0]}'s edge` : `${others.join(", ")}'s edges`;
+    return (`. Both placements give it the same id, ${store.fqn}, but with a second consumer the move is ONE-WAY: ` +
+        `${named} resolves only against a declaration the MAP holds — a per-service project is \`architecture/\` ` +
+        `plus one model, so an \`extend\` block is visible to its own service's project alone. Out of ` +
+        `${store.owner}'s \`extend\` block onto ${store.owner}'s element on the map is always safe; moving it ` +
+        `back INTO the \`extend\` block breaks that edge — \`c4.invalid\` on the other service's model, or ` +
+        `\`landscape.invalid\` when the edge is drawn on the map`);
+}
+/**
+ * Where the store goes, named for the consumer's own model SHAPE — which this
+ * sentence used to assert instead of reading. It always prescribed the
+ * extending-shape remedy, and following it on a standalone consumer turns a
+ * clean run into `c4.invalid`: a model that declares its own `specification` is
+ * parsed alone, so `extend <fqn>` there resolves nothing at all (measured — one
+ * error, "Could not resolve reference to Element named '<fqn>'"). The two
+ * placements otherwise give the store the SAME id, which is the fact that makes
+ * the choice cheap: measured on examples/docs, moving `db` out of
+ * order-service's extend block into `orderService` on the map left the model at
+ * 12 elements · 8 relationships, left `Covers: marketplace.orderService.db` in
+ * its arch.spec.md resolving, and left checkout-web's edge to it resolving too.
+ */
+function placement(at) {
+    // Direction, not symmetry. The clause used to read "moving the declaration
+    // between them later rewrites no edge", which is true only while this store
+    // has ONE consumer — the state this finding is in — and false the moment the
+    // second consumer it goes on to promise arrives: that consumer's edge resolves
+    // against the map's declaration alone. Saying it unconditionally here is what
+    // made `datastore-shared` inherit a sentence that was false in every state it
+    // printed in (verification 2026-09-04).
+    const same = `the two placements give it the same id, ${at.fqn}.${at.local}, and with one consumer either move ` +
+        `is free — out of the \`extend\` block onto the map always is, and back into it while no other ` +
+        `service's model or map edge names the store, an \`extend\` block being visible to its own service's ` +
+        `project alone`;
+    if (at.shape === "extending") {
+        return (`A store one service owns is nested UNDER that service's element: write it in the ` +
+            `\`extend ${at.fqn} { … }\` block of ${at.path}, or inside '${at.fqn}' here when the map draws ` +
+            `that service's containers, and delete this peer — ${same}.`);
+    }
+    // The two absent-extending-model arms differ in what there is to do: a
+    // STANDALONE model exists and can be migrated; with no model at all there is
+    // nothing to migrate, and "migrate the model" sent a reader looking for a file
+    // loam had just said it could not find (verification 2026-09-04).
+    const otherwise = at.shape === "standalone"
+        ? `${at.path} declares its own \`specification\`, so it is parsed alone and \`extend ${at.fqn}\` ` +
+            `resolves nothing there`
+        : `loam read no extending model at ${at.path}`;
+    const migrate = at.shape === "standalone"
+        ? `migrate the model to the extending shape (SCHEMA.md, "Two shapes of a service model")`
+        : `write an extending model at ${at.path} (SCHEMA.md, "Two shapes of a service model")`;
+    return (`A store one service owns is nested UNDER that service's element, and this consumer has no ` +
+        `extending model to nest it in (${otherwise}): write it inside '${at.fqn}' here, where the map draws ` +
+        `that service's containers, and delete this peer — or ${migrate} and write it in an ` +
+        `\`extend ${at.fqn} { … }\` block there, where ${same}.`);
+}
+/**
+ * The one-consumer message, and it names the PLACEMENT rather than a directory:
+ * the remedy used to read "move it into services/<id>/model.likec4 as a nested
+ * container, or add the second consumer's edge", which offered two remedies as
+ * equals and left the second one impossible — an edge naming the moved store is
+ * `landscape.invalid` for loam, so an author who took the first remedy believed
+ * they had shut the second door (#01). They had not, and the sentence now says
+ * how: a later consumer is drawn in ITS OWN model, and loam counts that — as
+ * long as that model EXTENDS the map, which the caveat below is careful to say.
+ */
+function privateFinding(store, consumer, input) {
+    const fqn = input.drawn.find((e) => input.resolve(e.id) === consumer)?.id ?? consumer;
+    const local = store.id.split(".").at(-1) ?? store.id;
+    const model = input.attested.find((m) => m.service === consumer);
+    const shape = model === undefined ? null : model.extending ? "extending" : "standalone";
+    return {
+        severity: "warn",
+        code: "landscape.datastore-private",
+        subject: store.title,
+        message: `landscape: '${store.title}' is a datastore with a single consumer at fleet level ` +
+            `('${consumer}') — drawn as a peer it reads as a system in its own right, available to be ` +
+            `depended on. ${placement({ fqn, local, path: `${input.pathOf(consumer)}/model.likec4`, shape })} ` +
+            `Nesting closes no door: a second service reaching the same data later draws a container-level ` +
+            `edge to ${fqn}.${local} in ITS OWN model plus a service-level edge to '${fqn}' here, and loam ` +
+            `counts a consumer an EXTENDING model attests exactly as it counts one drawn here — so that ` +
+            `state is \`landscape.datastore-shared\`, never silence. A consumer whose model stands alone is ` +
+            `not counted (its ids are its own file's, never the map's), so its edge belongs on the map. ` +
+            `Which placement: that edge RESOLVES only against a store the map declares (a per-service ` +
+            `project is architecture/ plus one model), so ` +
+            (shape === "extending"
+                ? `nest it here when a second consumer is foreseeable and in the model when it is not. `
+                : `the map is the placement that keeps that door open. `) +
+            `If another service reaches the same data today, draw its edge and this becomes that warning now`,
+    };
+}
+/** The two-or-more message, shared by the peer and the nested store — one word about coupling, once. */
+function sharedFinding(title, consumers, where, tail) {
+    return {
+        severity: "warn",
+        code: "landscape.datastore-shared",
+        subject: title,
+        message: `landscape: '${title}' is a datastore shared by ${consumers.length} services ` +
+            `(${consumers.join(", ")})${where} — the strongest coupling two services can have, and the ` +
+            `hardest to undo. Shared means the same DATA: if they read the same tables or keys, keep it ` +
+            `where it is and let this warning state the coupling; if they only share a host or cluster ` +
+            `(two schemas, two lock paths), that is operational blast radius — a runbook fact — and the ` +
+            `honest model is one private store per service${tail}`,
+    };
+}
+//# sourceMappingURL=consumers.js.map

package/dist/commands/validate/fleet/map/consumers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumers.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/map/consumers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Who consumes a drawn element — and the datastore grades that read the answer.\n *\n * The census used to walk the MAP's relationships alone, and under the extending\n * shape that is a partial view of the fleet: a service draws the container-level\n * call in its own `model.likec4` and the map carries the service-level twin, so a\n * store whose consuming edges were all drawn in models had ZERO consumers and\n * earned nothing at all, while a store reached by three models and one map edge\n * was reported `landscape.datastore-private` naming the one service the map\n * happened to draw (R1). A model is evidence about the fleet exactly as the map\n * is, so both are counted here, once, by one derivation two checks share.\n *\n * WHERE A PRIVATE STORE LIVES, stated once because three surfaces used to answer\n * it differently: a store one service owns is NESTED UNDER THAT SERVICE'S\n * ELEMENT — in the service's extending model (`extend <fqn> { store = database\n * … }`), or inside the service's element on the map when the map draws that\n * service's containers. A second service reaching it later is drawn where that\n * service draws every other call: a container-level edge in ITS model naming\n * `<owner-fqn>.<store>`, carried up to the map as a service-level edge to the\n * owning service. Nothing moves back, and nothing goes ungraded — a nested store\n * two services reach is `landscape.datastore-shared` here (E3).\n *\n * WHICH OF THE TWO PLACEMENTS, and this is measured rather than assumed: a\n * per-service project is `architecture/` plus that ONE model, so an edge naming\n * `<owner-fqn>.<store>` resolves for the second service only when the MAP\n * declares the store. Written in the owner's `extend` block instead, the same\n * edge is two errors on the consumer's own model (\"Could not resolve reference\n * to Referenceable named 'store'\"), so that store is private for good and its\n * second consumer can only ever be drawn at service level. The message below\n * says so; SCHEMA carries the same sentence.\n *\n * The choice is cheap, and both messages now say exactly HOW cheap, because\n * \"reversible\" was false in the one state that used to assert it. The two\n * placements do give the store the same id, `<owner-fqn>.<store>` — but the\n * move is only free in ONE direction once a second service names it. Measured\n * on `examples/docs`: moving `db` out of order-service's `extend` block into\n * `orderService` on the map left the model at 12 elements · 8 relationships,\n * left `Covers: marketplace.orderService.db` in its arch.spec.md resolving, and\n * left checkout-web's container-level edge to it resolving too. Moving it BACK\n * with that second edge drawn is two errors on checkout-web's own model\n * (\"Could not resolve reference to Referenceable named 'db'\"), or\n * `landscape.invalid` plus one `spine.landscape-invalid` per service when the\n * second edge is drawn on the map — because an `extend` block is visible to its\n * own service's project alone. `datastore-shared` printed the unconditional\n * clause in 100% of the states it fires in, every one of which already has the\n * second consumer that makes map→extend break (verification 2026-09-04). So the\n * rule both messages now state is directional: extend→map is always safe;\n * map→extend only while no other service's model or map edge names the store.\n *\n * And the remedy is named for the consumer's own model SHAPE rather than\n * assumed: `extend <fqn>` in a STANDALONE model (one that declares its own\n * `specification`) resolves nothing, because such a model is parsed alone — so\n * prescribing it there turns a clean run into `c4.invalid`. The shape comes off\n * the same `./attest.ts` record the consumer join reads.\n *\n * A sub-package of `fleet/` for `./isolation.ts`'s reason and with its rule: it\n * imports NOTHING from `fleet/`, so the map facts it reads arrive on the input\n * records the caller fills.\n */\nimport { type Elem, type Rel } from \"../../../../core/c4/likec4.js\";\nimport { type Finding } from \"../../../../core/vocabulary/report.js\";\nimport { type AttestedModel, type NestedStore } from \"./attest.js\";\n\n/** The element kind read as a datastore, compared case-insensitively. */\nconst DATASTORE_KIND = \"database\";\n\nexport interface CensusInput {\n  /** The map's own edges — a service-level twin is what the map carries of a container-level call. */\n  relationships: Rel[];\n  /** The services/<id>/ directories that exist: a consumer is a source filed under a real one. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver every edge join uses. */\n  resolve: (id: string) => string;\n  /** What each service's own model attests (`./attest.ts`). */\n  attested: readonly AttestedModel[];\n}\n\n/**\n * Distinct consumer SERVICES of an element, its nested children included: an\n * edge into `kafka.paymentEvents` is consumption of `kafka`.\n *\n * Two kinds of evidence, unioned. From the MAP: a relationship whose target is\n * the element or a descendant and whose source the shared resolver files under a\n * real `services/<id>/` — persons, other external systems and unresolved sources\n * never count, and two edges from one service are one consumer. From the\n * MODELS: a service whose own model attests an OUTBOUND call at the element or a\n * descendant.\n *\n * The model half reads EXTENDING models only, and the reason is the id space. An\n * extending model's ids are the map's fully-qualified ids — one project — so the\n * join is exact. A standalone model's ids are its own file's, and\n * `core/c4/resolve/attested.ts` says outright that a counterpart is never\n * matched to a landscape element: joining one would file a coincidence of\n * spelling as a coupling between two services.\n */\nexport function consumerCensus(input: CensusInput): (elementId: string) => string[] {\n  const reaches = (elementId: string, id: string): boolean => id === elementId || id.startsWith(`${elementId}.`);\n  return (elementId: string): string[] => {\n    const out = new Set<string>();\n    for (const r of input.relationships) {\n      if (!reaches(elementId, r.target)) continue;\n      const svc = input.resolve(r.source);\n      if (input.services.has(svc)) out.add(svc);\n    }\n    for (const model of input.attested) {\n      if (!model.extending) continue;\n      if (model.calls.some((c) => c.direction === \"out\" && reaches(elementId, c.counterpartId))) {\n        out.add(model.service);\n      }\n    }\n    return [...out].sort();\n  };\n}\n\n/** What loam actually read at a consumer's own `model.likec4`, which decides where a store may be nested. */\nexport type ConsumerShape = \"extending\" | \"standalone\" | null;\n\nexport interface DatastoreInput {\n  /** Service-LEVEL elements — the fleet map's own boxes, where a store drawn as a peer is found. */\n  drawn: Elem[];\n  /** Every element the MAP declares, at any depth — the other place a nested store is written. */\n  elements: Elem[];\n  /** Stores an extending model declares inside its own element (`./attest.ts`). */\n  nestedStores: readonly NestedStore[];\n  /** The services/<id>/ directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver, for naming the consumer's own element on the map. */\n  resolve: (id: string) => string;\n  /**\n   * `census.ts`'s one predicate for \"this element stands for a `services/<id>/`\",\n   * injected because a `fleet/map/` module may not import `fleet/`. Both halves\n   * of the grade below skip such an element: it is the fleet itself, not its\n   * shape, and a store bound to a directory is the binding checks' subject.\n   * `./attest.ts` applies the same predicate to the stores a MODEL declares, so\n   * all three places answer it once.\n   */\n  standsForService: (e: Elem) => boolean;\n  /** What each service's own model attests (`./attest.ts`) — the consumer join AND the shape the remedy names. */\n  attested: readonly AttestedModel[];\n  /** The census above, built once and shared with the platform-candidate advisory. */\n  consumers: (elementId: string) => string[];\n  /** Where a service's directory sits, repo-relative — the enumeration's answer, never `services/<id>`. */\n  pathOf: (id: string) => string;\n}\n\n/**\n * A datastore drawn as a fleet-level peer makes a claim its consumer count\n * either supports or refutes: one consumer means the drawing is false — the\n * store is that service's internals, not a system in its own right — while two\n * or more mean the strongest coupling two services can have, which deserves to\n * be stated rather than inferred. A NESTED store is private by construction, so\n * it is silent at one consumer and earns the same `datastore-shared` at two.\n */\nexport function datastoreFindings(input: DatastoreInput): Finding[] {\n  const findings: Finding[] = [];\n  for (const e of input.drawn) {\n    // An element that stands for a real service is the fleet itself, not its\n    // shape; a datastore bound to a directory is graded by the binding checks.\n    if (input.standsForService(e)) continue;\n    if (e.kind.toLowerCase() !== DATASTORE_KIND) continue;\n    const consumers = input.consumers(e.id);\n    if (consumers.length === 0) continue;\n    findings.push(\n      consumers.length === 1 ? privateFinding(e, consumers[0]!, input) : sharedFinding(e.title, consumers, \"\", \"\"),\n    );\n  }\n  for (const store of nestedStoresOf(input)) {\n    // The owner is a consumer by construction — the store sits inside the element\n    // that resolves to it — so silence at one consumer IS the fixed state, and\n    // the only question left is whether a second service reaches the same data.\n    const consumers = [...new Set([store.owner, ...input.consumers(store.fqn)])].sort();\n    if (consumers.length < 2) continue;\n    findings.push(\n      sharedFinding(\n        store.title,\n        consumers,\n        // The store's own id, and said as such. The clause read \"nested under\n        // '<fqn>'\", which sends a reader looking for an element that HOLDS the\n        // store — when that id IS the store, and its container is its prefix.\n        ` — ${store.owner}'s own store, written as '${store.fqn}'`,\n        reversibility(store, consumers.filter((c) => c !== store.owner)),\n      ),\n    );\n  }\n\n  return findings;\n}\n\n/**\n * Every store nested under the element that resolves to its owner, from both\n * places the stance allows one to be written: inside the service's element ON\n * THE MAP, and in the service's own extending model. Keyed by fqn, so a\n * map-declared store — which the owner's model slice carries too, since a slice\n * is everything resolving to the service — is one store and not two.\n *\n * Both sources are needed and neither is redundant. The map's covers a service\n * whose model is standalone or absent (no slice to read); the model's covers a\n * store the map never draws, which is the placement the adopt brief prescribes.\n */\nfunction nestedStoresOf(input: DatastoreInput): NestedStore[] {\n  const drawnIds = new Set(input.drawn.map((e) => e.id));\n  const byFqn = new Map<string, NestedStore>();\n  for (const e of input.elements) {\n    if (e.kind.toLowerCase() !== DATASTORE_KIND || drawnIds.has(e.id)) continue;\n    // The peer branch's guard, which this half was missing: a `database` bound\n    // with `metadata { service '<id>' }` and drawn one level down became a store\n    // \"owned\" by its own binding, so a second reader made it a shared datastore\n    // and the fix offered was to give each service its own copy of a service.\n    if (input.standsForService(e)) continue;\n    const owner = input.resolve(e.id);\n    if (!input.services.has(owner)) continue;\n    byFqn.set(e.id, { owner, fqn: e.id, title: e.title });\n  }\n  for (const store of input.nestedStores) if (!byFqn.has(store.fqn)) byFqn.set(store.fqn, store);\n  return [...byFqn.values()];\n}\n\n/**\n * Which way the store may still be moved, now that a second service reaches it.\n *\n * The clause this replaces said the two placements were interchangeable — \"the\n * two placements give it the same id … so moving the declaration between them\n * rewrites no edge\" — and that is false in every state `datastore-shared` fires\n * in, because the finding needs a second consumer and a second consumer's edge\n * resolves only against a store the MAP declares (a per-service project is\n * `architecture/` plus one model). Measured: performing the move the sentence\n * called free turned a clean `examples/docs` into `c4.invalid` on the consumer's\n * model, or into `landscape.invalid` + one `spine.landscape-invalid` per service\n * when the second edge is on the map (verification 2026-09-04).\n *\n * The direction is stated rather than the current placement, and it holds\n * either way round: out of the owner's `extend` block onto the map is always\n * safe, back in is not while another service names the store. (In practice a\n * store this finding reaches is one the MAP declares — a second consumer's edge\n * cannot resolve against an `extend` block, so it could never have been drawn\n * — which is the same fact said from the other side.)\n */\nfunction reversibility(store: NestedStore, others: string[]): string {\n  const named = others.length === 1 ? `${others[0]!}'s edge` : `${others.join(\", \")}'s edges`;\n  return (\n    `. Both placements give it the same id, ${store.fqn}, but with a second consumer the move is ONE-WAY: ` +\n    `${named} resolves only against a declaration the MAP holds — a per-service project is \\`architecture/\\` ` +\n    `plus one model, so an \\`extend\\` block is visible to its own service's project alone. Out of ` +\n    `${store.owner}'s \\`extend\\` block onto ${store.owner}'s element on the map is always safe; moving it ` +\n    `back INTO the \\`extend\\` block breaks that edge — \\`c4.invalid\\` on the other service's model, or ` +\n    `\\`landscape.invalid\\` when the edge is drawn on the map`\n  );\n}\n\n/**\n * Where the store goes, named for the consumer's own model SHAPE — which this\n * sentence used to assert instead of reading. It always prescribed the\n * extending-shape remedy, and following it on a standalone consumer turns a\n * clean run into `c4.invalid`: a model that declares its own `specification` is\n * parsed alone, so `extend <fqn>` there resolves nothing at all (measured — one\n * error, \"Could not resolve reference to Element named '<fqn>'\"). The two\n * placements otherwise give the store the SAME id, which is the fact that makes\n * the choice cheap: measured on examples/docs, moving `db` out of\n * order-service's extend block into `orderService` on the map left the model at\n * 12 elements · 8 relationships, left `Covers: marketplace.orderService.db` in\n * its arch.spec.md resolving, and left checkout-web's edge to it resolving too.\n */\nfunction placement(at: { fqn: string; local: string; path: string; shape: ConsumerShape }): string {\n  // Direction, not symmetry. The clause used to read \"moving the declaration\n  // between them later rewrites no edge\", which is true only while this store\n  // has ONE consumer — the state this finding is in — and false the moment the\n  // second consumer it goes on to promise arrives: that consumer's edge resolves\n  // against the map's declaration alone. Saying it unconditionally here is what\n  // made `datastore-shared` inherit a sentence that was false in every state it\n  // printed in (verification 2026-09-04).\n  const same =\n    `the two placements give it the same id, ${at.fqn}.${at.local}, and with one consumer either move ` +\n    `is free — out of the \\`extend\\` block onto the map always is, and back into it while no other ` +\n    `service's model or map edge names the store, an \\`extend\\` block being visible to its own service's ` +\n    `project alone`;\n  if (at.shape === \"extending\") {\n    return (\n      `A store one service owns is nested UNDER that service's element: write it in the ` +\n      `\\`extend ${at.fqn} { … }\\` block of ${at.path}, or inside '${at.fqn}' here when the map draws ` +\n      `that service's containers, and delete this peer — ${same}.`\n    );\n  }\n  // The two absent-extending-model arms differ in what there is to do: a\n  // STANDALONE model exists and can be migrated; with no model at all there is\n  // nothing to migrate, and \"migrate the model\" sent a reader looking for a file\n  // loam had just said it could not find (verification 2026-09-04).\n  const otherwise =\n    at.shape === \"standalone\"\n      ? `${at.path} declares its own \\`specification\\`, so it is parsed alone and \\`extend ${at.fqn}\\` ` +\n        `resolves nothing there`\n      : `loam read no extending model at ${at.path}`;\n  const migrate =\n    at.shape === \"standalone\"\n      ? `migrate the model to the extending shape (SCHEMA.md, \"Two shapes of a service model\")`\n      : `write an extending model at ${at.path} (SCHEMA.md, \"Two shapes of a service model\")`;\n  return (\n    `A store one service owns is nested UNDER that service's element, and this consumer has no ` +\n    `extending model to nest it in (${otherwise}): write it inside '${at.fqn}' here, where the map draws ` +\n    `that service's containers, and delete this peer — or ${migrate} and write it in an ` +\n    `\\`extend ${at.fqn} { … }\\` block there, where ${same}.`\n  );\n}\n\n/**\n * The one-consumer message, and it names the PLACEMENT rather than a directory:\n * the remedy used to read \"move it into services/<id>/model.likec4 as a nested\n * container, or add the second consumer's edge\", which offered two remedies as\n * equals and left the second one impossible — an edge naming the moved store is\n * `landscape.invalid` for loam, so an author who took the first remedy believed\n * they had shut the second door (#01). They had not, and the sentence now says\n * how: a later consumer is drawn in ITS OWN model, and loam counts that — as\n * long as that model EXTENDS the map, which the caveat below is careful to say.\n */\nfunction privateFinding(store: Elem, consumer: string, input: DatastoreInput): Finding {\n  const fqn = input.drawn.find((e) => input.resolve(e.id) === consumer)?.id ?? consumer;\n  const local = store.id.split(\".\").at(-1) ?? store.id;\n  const model = input.attested.find((m) => m.service === consumer);\n  const shape: ConsumerShape = model === undefined ? null : model.extending ? \"extending\" : \"standalone\";\n  return {\n    severity: \"warn\",\n    code: \"landscape.datastore-private\",\n    subject: store.title,\n    message:\n      `landscape: '${store.title}' is a datastore with a single consumer at fleet level ` +\n      `('${consumer}') — drawn as a peer it reads as a system in its own right, available to be ` +\n      `depended on. ${placement({ fqn, local, path: `${input.pathOf(consumer)}/model.likec4`, shape })} ` +\n      `Nesting closes no door: a second service reaching the same data later draws a container-level ` +\n      `edge to ${fqn}.${local} in ITS OWN model plus a service-level edge to '${fqn}' here, and loam ` +\n      `counts a consumer an EXTENDING model attests exactly as it counts one drawn here — so that ` +\n      `state is \\`landscape.datastore-shared\\`, never silence. A consumer whose model stands alone is ` +\n      `not counted (its ids are its own file's, never the map's), so its edge belongs on the map. ` +\n      `Which placement: that edge RESOLVES only against a store the map declares (a per-service ` +\n      `project is architecture/ plus one model), so ` +\n      (shape === \"extending\"\n        ? `nest it here when a second consumer is foreseeable and in the model when it is not. `\n        : `the map is the placement that keeps that door open. `) +\n      `If another service reaches the same data today, draw its edge and this becomes that warning now`,\n  };\n}\n\n/** The two-or-more message, shared by the peer and the nested store — one word about coupling, once. */\nfunction sharedFinding(title: string, consumers: string[], where: string, tail: string): Finding {\n  return {\n    severity: \"warn\",\n    code: \"landscape.datastore-shared\",\n    subject: title,\n    message:\n      `landscape: '${title}' is a datastore shared by ${consumers.length} services ` +\n      `(${consumers.join(\", \")})${where} — the strongest coupling two services can have, and the ` +\n      `hardest to undo. Shared means the same DATA: if they read the same tables or keys, keep it ` +\n      `where it is and let this warning state the coupling; if they only share a host or cluster ` +\n      `(two schemas, two lock paths), that is operational blast radius — a runbook fact — and the ` +\n      `honest model is one private store per service${tail}`,\n  };\n}\n"]}

package/dist/commands/validate/fleet/map/isolation.js

@@ -0,0 +1,116 @@
+/**
+ * `landscape.service-isolated` — a service the fleet map draws and nothing
+ * reaches, graded on EVIDENCE rather than on the shape alone.
+ *
+ * The state is the one `loam seed --from fleet.yaml` leaves for every service
+ * nobody listed under `calls:`: a bound element with no edge. Nothing used to
+ * report it — `landscape.service-unmodelled` wants a missing element, and the
+ * element is present — so a service could be adopted with a full artifact set
+ * and stay invisible to every cross-service check while the run ended on
+ * `landscape.matched`.
+ *
+ * Why the evidence gate, and not "every edgeless bound element": a warning with
+ * no correct fix is the warning somebody silences. A worker or a cron that
+ * genuinely calls nothing has an edgeless element that is TRUE, and there is
+ * no tag loam reads for "deliberately isolated" (inventing one is the invented
+ * need the non-goals forbid). So this fires only when the service's own
+ * `model.likec4` parses and declares at least one call across its boundary —
+ * a JOIN between two authored documents: the model attests a call the map
+ * does not draw. The list comes from `attestedCalls`, the same derivation the
+ * adopt brief names those calls with, so the brief and this check can never
+ * disagree about which edges the map owes. Silent, on purpose, for a service
+ * with no model (seed's fleet), an unparseable model (`c4.invalid` owns it), a
+ * model reaching nothing, and an unmodelled service (`service-unmodelled` owns
+ * it).
+ *
+ * `#external` is never a SUBJECT, and that is now enforced rather than assumed.
+ * The claim used to rest on "an `#external` element is not an enumerated
+ * service" — true of the ordinary case and false of the reachable one: an
+ * element tagged `#external` and bound with `metadata { service '<id>' }` to a
+ * directory that exists resolved like any other, so a foreign box answered for
+ * one of our services (R4). The two neighbouring binding checks have always
+ * skipped the tag; the input set here does too, so "deliberately not ours"
+ * means the same thing in all three.
+ *
+ * The subject set ONLY, and that boundary is the whole of the rule. The filter
+ * also sat inside the `touched` walk for one round, which answers a different
+ * question — does the map draw any edge on this service — and got it wrong: a
+ * kind carrying the tag (`element topic { #external }`, the idiom
+ * `examples/docs/architecture/landscape.likec4` defends at length) puts
+ * `#external` on every element of that kind, so an edge drawn from a service's
+ * OWN topic stopped touching it and the warning fired on a service the map
+ * demonstrably reaches — while `loam adopt`, whose `landscape.touched` has no
+ * tag filter, said `touched: true` on the same tree. Two answers to one rule
+ * is the drift this file's banner promises there cannot be, so the walk below
+ * is the brief's predicate exactly, tag and all.
+ *
+ * A sub-package of its own because `fleet/` sits at the five-file cap, and it
+ * imports NOTHING from `fleet/`: a child reaching back into its parent while
+ * the parent calls the child is the package cycle `scripts/package-graph.mjs`
+ * refuses, which is why the input is one record the caller fills. The models
+ * are no longer read here either — `./attest.ts` reads each of them once for
+ * this check and the datastore census together.
+ */
+import {} from "../../../../core/c4/likec4.js";
+import { edgeTemplates, spellCall } from "../../../../core/c4/resolve/attested.js";
+import {} from "../../../../core/vocabulary/report.js";
+import {} from "./attest.js";
+/** How many attested calls the message spells out before "…" — three reads; thirty is a wall. */
+const NAMED_CALLS = 3;
+export function isolationFindings(input) {
+    const { land, resolve, pathOf } = input;
+    // One pass over the relationships: a service is touched when EITHER endpoint
+    // resolves to it. An intra-service edge (`svc.api -> svc.db`) therefore
+    // counts, which is the brief's `landscape.touched` predicate exactly, and
+    // what keeps a self-model drawn as one service of container edges silent.
+    // NO tag filter here, deliberately — see the banner: an `#external` endpoint
+    // is still an edge the map draws on whatever it resolves to, and skipping one
+    // made this check contradict `loam adopt` on a service whose own topic (a
+    // kind-tagged `#external` element) was the endpoint.
+    const touched = new Set();
+    for (const r of land.relationships) {
+        for (const endpoint of [r.source, r.target])
+            touched.add(resolve(endpoint));
+    }
+    const findings = [];
+    for (const model of input.attested) {
+        if (!input.modelled.has(model.service) || touched.has(model.service))
+            continue;
+        const calls = model.calls;
+        if (calls.length === 0)
+            continue;
+        // `modelled.has` proves a non-external element resolves; the find is the
+        // same predicate spelled on the elements, and an empty answer fails closed
+        // rather than naming an element that is not there.
+        const element = land.elements.find((e) => resolve(e.id) === model.service && !input.external.has(e.id));
+        if (element === undefined)
+            continue;
+        const named = calls.slice(0, NAMED_CALLS).map(spellCall).join(", ") + (calls.length > NAMED_CALLS ? ", …" : "");
+        // The repair form follows the calls' direction (`edgeTemplates`): the
+        // outbound form alone, spelled here until 2026-09-03, sent an inbound
+        // call backwards.
+        const forms = edgeTemplates(element.id, calls)
+            .map((t) => `\`${t}\``)
+            .join(" or ");
+        findings.push({
+            severity: "warn",
+            code: "landscape.service-isolated",
+            subject: model.service,
+            message: 
+            // "the fleet map (architecture/)", never the landscape FILE: the input
+            // is the whole PROJECT, so an edge added to `architecture/extra.likec4`
+            // and never to landscape.likec4 silences this finding — measured on both
+            // the seed lab and examples/docs. Naming one file told a reader the edge
+            // had to land there, which SCHEMA, `loam explain` and the brief all
+            // already contradicted (verification 2026-09-04).
+            `landscape: ${pathOf(model.service)}/ resolves to '${element.id}' and no edge in the fleet map ` +
+                `(architecture/) touches it, while ${pathOf(model.service)}/model.likec4 declares ${calls.length} ` +
+                `call(s) across its boundary ` +
+                `(${named}) — the service is drawn and invisible to every cross-service check. Draw each as one edge on ` +
+                `${element.id}: ${forms} for a call, ` +
+                `\`publishes\`/\`consumes\` for an event, naming the other party as the map already spells it`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=isolation.js.map

package/dist/commands/validate/fleet/map/isolation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolation.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/map/isolation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `landscape.service-isolated` — a service the fleet map draws and nothing\n * reaches, graded on EVIDENCE rather than on the shape alone.\n *\n * The state is the one `loam seed --from fleet.yaml` leaves for every service\n * nobody listed under `calls:`: a bound element with no edge. Nothing used to\n * report it — `landscape.service-unmodelled` wants a missing element, and the\n * element is present — so a service could be adopted with a full artifact set\n * and stay invisible to every cross-service check while the run ended on\n * `landscape.matched`.\n *\n * Why the evidence gate, and not \"every edgeless bound element\": a warning with\n * no correct fix is the warning somebody silences. A worker or a cron that\n * genuinely calls nothing has an edgeless element that is TRUE, and there is\n * no tag loam reads for \"deliberately isolated\" (inventing one is the invented\n * need the non-goals forbid). So this fires only when the service's own\n * `model.likec4` parses and declares at least one call across its boundary —\n * a JOIN between two authored documents: the model attests a call the map\n * does not draw. The list comes from `attestedCalls`, the same derivation the\n * adopt brief names those calls with, so the brief and this check can never\n * disagree about which edges the map owes. Silent, on purpose, for a service\n * with no model (seed's fleet), an unparseable model (`c4.invalid` owns it), a\n * model reaching nothing, and an unmodelled service (`service-unmodelled` owns\n * it).\n *\n * `#external` is never a SUBJECT, and that is now enforced rather than assumed.\n * The claim used to rest on \"an `#external` element is not an enumerated\n * service\" — true of the ordinary case and false of the reachable one: an\n * element tagged `#external` and bound with `metadata { service '<id>' }` to a\n * directory that exists resolved like any other, so a foreign box answered for\n * one of our services (R4). The two neighbouring binding checks have always\n * skipped the tag; the input set here does too, so \"deliberately not ours\"\n * means the same thing in all three.\n *\n * The subject set ONLY, and that boundary is the whole of the rule. The filter\n * also sat inside the `touched` walk for one round, which answers a different\n * question — does the map draw any edge on this service — and got it wrong: a\n * kind carrying the tag (`element topic { #external }`, the idiom\n * `examples/docs/architecture/landscape.likec4` defends at length) puts\n * `#external` on every element of that kind, so an edge drawn from a service's\n * OWN topic stopped touching it and the warning fired on a service the map\n * demonstrably reaches — while `loam adopt`, whose `landscape.touched` has no\n * tag filter, said `touched: true` on the same tree. Two answers to one rule\n * is the drift this file's banner promises there cannot be, so the walk below\n * is the brief's predicate exactly, tag and all.\n *\n * A sub-package of its own because `fleet/` sits at the five-file cap, and it\n * imports NOTHING from `fleet/`: a child reaching back into its parent while\n * the parent calls the child is the package cycle `scripts/package-graph.mjs`\n * refuses, which is why the input is one record the caller fills. The models\n * are no longer read here either — `./attest.ts` reads each of them once for\n * this check and the datastore census together.\n */\nimport { type LoadedDoc } from \"../../../../core/c4/likec4.js\";\nimport { edgeTemplates, spellCall } from \"../../../../core/c4/resolve/attested.js\";\nimport { type Finding } from \"../../../../core/vocabulary/report.js\";\nimport { type AttestedModel } from \"./attest.js\";\n\nexport interface IsolationInput {\n  /** The parsed landscape. */\n  land: LoadedDoc;\n  /**\n   * The services a NON-`#external` element resolves to — `service-unmodelled`'s\n   * set with the tag filter applied, which is what keeps a foreign box from\n   * answering for one of our directories.\n   */\n  modelled: ReadonlySet<string>;\n  /** The ids of the map's `#external` elements: never a subject — and never what the message names. */\n  external: ReadonlySet<string>;\n  /** What each service's own model attests, read once by `./attest.ts` for this check and the store census. */\n  attested: readonly AttestedModel[];\n  /** The shared element→service resolver every edge join uses. */\n  resolve: (id: string) => string;\n  /** Where a service's directory sits, repo-relative — the enumeration's answer, never `services/<id>`. */\n  pathOf: (id: string) => string;\n}\n\n/** How many attested calls the message spells out before \"…\" — three reads; thirty is a wall. */\nconst NAMED_CALLS = 3;\n\nexport function isolationFindings(input: IsolationInput): Finding[] {\n  const { land, resolve, pathOf } = input;\n  // One pass over the relationships: a service is touched when EITHER endpoint\n  // resolves to it. An intra-service edge (`svc.api -> svc.db`) therefore\n  // counts, which is the brief's `landscape.touched` predicate exactly, and\n  // what keeps a self-model drawn as one service of container edges silent.\n  // NO tag filter here, deliberately — see the banner: an `#external` endpoint\n  // is still an edge the map draws on whatever it resolves to, and skipping one\n  // made this check contradict `loam adopt` on a service whose own topic (a\n  // kind-tagged `#external` element) was the endpoint.\n  const touched = new Set<string>();\n  for (const r of land.relationships) {\n    for (const endpoint of [r.source, r.target]) touched.add(resolve(endpoint));\n  }\n\n  const findings: Finding[] = [];\n  for (const model of input.attested) {\n    if (!input.modelled.has(model.service) || touched.has(model.service)) continue;\n    const calls = model.calls;\n    if (calls.length === 0) continue;\n    // `modelled.has` proves a non-external element resolves; the find is the\n    // same predicate spelled on the elements, and an empty answer fails closed\n    // rather than naming an element that is not there.\n    const element = land.elements.find((e) => resolve(e.id) === model.service && !input.external.has(e.id));\n    if (element === undefined) continue;\n    const named = calls.slice(0, NAMED_CALLS).map(spellCall).join(\", \") + (calls.length > NAMED_CALLS ? \", …\" : \"\");\n    // The repair form follows the calls' direction (`edgeTemplates`): the\n    // outbound form alone, spelled here until 2026-09-03, sent an inbound\n    // call backwards.\n    const forms = edgeTemplates(element.id, calls)\n      .map((t) => `\\`${t}\\``)\n      .join(\" or \");\n    findings.push({\n      severity: \"warn\",\n      code: \"landscape.service-isolated\",\n      subject: model.service,\n      message:\n        // \"the fleet map (architecture/)\", never the landscape FILE: the input\n        // is the whole PROJECT, so an edge added to `architecture/extra.likec4`\n        // and never to landscape.likec4 silences this finding — measured on both\n        // the seed lab and examples/docs. Naming one file told a reader the edge\n        // had to land there, which SCHEMA, `loam explain` and the brief all\n        // already contradicted (verification 2026-09-04).\n        `landscape: ${pathOf(model.service)}/ resolves to '${element.id}' and no edge in the fleet map ` +\n        `(architecture/) touches it, while ${pathOf(model.service)}/model.likec4 declares ${calls.length} ` +\n        `call(s) across its boundary ` +\n        `(${named}) — the service is drawn and invisible to every cross-service check. Draw each as one edge on ` +\n        `${element.id}: ${forms} for a call, ` +\n        `\\`publishes\\`/\\`consumes\\` for an event, naming the other party as the map already spells it`,\n    });\n  }\n  return findings;\n}\n"]}

package/dist/commands/validate/fleet/map/usecases.js

@@ -0,0 +1,56 @@
+/**
+ * The fleet's use cases, graded — the CALL, with the two vocabulary reads it
+ * needs, lifted out of `../landscape.ts` when that module reached its line
+ * limit.
+ *
+ * The seam is a phase rather than a subject: everything here happens after the
+ * map has parsed and grades documents the map does not own — every
+ * `dynamic view` in `architecture/landscape.likec4` and in every
+ * `architecture/usecases/*.likec4`. `../usecases/usecases.ts` owns the opt-in and
+ * the grades; this owns which inputs they are handed, which is the part that has
+ * twice been got wrong and is worth stating in one place.
+ *
+ * A sub-package of `fleet/` for `map/isolation.ts`'s reason, and with its rule:
+ * it imports NOTHING from `fleet/` itself — a child reaching back into its
+ * parent while the parent calls the child is the package cycle
+ * `scripts/package-graph.mjs` refuses — so everything it needs arrives in one
+ * record the caller fills.
+ */
+import { readCapabilityVocabulary } from "../../../../core/capabilities/capabilities.js";
+import { capabilityRequirementIndex, gradableCapabilityIds } from "../../../../core/capabilities/findings.js";
+import { parseRequirements, readRequirementsDocument } from "../../../../core/document/parse.js";
+import { FleetContext } from "../../../../core/fleet-context.js";
+import { useCaseFindings } from "../usecases/usecases.js";
+/**
+ * The capability ladder is APPLIED BY ITS OWN FUNCTION rather than re-spelled
+ * here: an absent or unreadable capabilities.yaml means silence for the whole
+ * family, not a fleet full of unresolved tags, so `null` travels rather than an
+ * empty list — which the join would read as "the fleet declares no capabilities"
+ * and grade every tag against. `gradableCapabilityIds`
+ * (`core/capabilities/findings.ts`) is the one statement of that rule, and this
+ * is a caller of it precisely so a fourth un-gradable vocabulary state cannot be
+ * fixed in core while the command layer keeps handing the join a whole key set.
+ *
+ * Both reads are already paid for under `--all`: `capabilityFleetFindings` has
+ * asked for the vocabulary, and every requirement document behind the `#req-`
+ * tag was parsed by it, so the fleet memo answers from cache. The requirement
+ * index is built here rather than inside the use-case package so that package
+ * never learns what a capability document is.
+ */
+export async function fleetUseCaseFindings(input) {
+    const { docsDir, fleet } = input;
+    const vocabulary = fleet === undefined ? await readCapabilityVocabulary(docsDir) : await fleet.capabilities(docsDir);
+    const capabilityReqs = await capabilityRequirementIndex(vocabulary, fleet === undefined
+        ? async (p) => parseRequirements(await readRequirementsDocument(p))
+        : (p) => fleet.readRequirements(p));
+    return useCaseFindings({
+        views: input.views,
+        elements: input.elements,
+        relationships: input.relationships,
+        services: input.services,
+        resolve: input.resolve,
+        capabilities: gradableCapabilityIds(vocabulary),
+        requirementsOf: (capability) => capabilityReqs.byCapability.get(capability),
+    });
+}
+//# sourceMappingURL=usecases.js.map

package/dist/commands/validate/fleet/map/usecases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/map/usecases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AACzF,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAC9G,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAKjE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAsB1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAAoB;IAC7D,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACjC,MAAM,UAAU,GACd,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACpG,MAAM,cAAc,GAAG,MAAM,0BAA0B,CACrD,UAAU,EACV,KAAK,KAAK,SAAS;QACjB,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,MAAM,wBAAwB,CAAC,CAAC,CAAC,CAAC;QACnE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CACrC,CAAC;IACF,OAAO,eAAe,CAAC;QACrB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,YAAY,EAAE,qBAAqB,CAAC,UAAU,CAAC;QAC/C,cAAc,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC;KAC5E,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * The fleet's use cases, graded — the CALL, with the two vocabulary reads it\n * needs, lifted out of `../landscape.ts` when that module reached its line\n * limit.\n *\n * The seam is a phase rather than a subject: everything here happens after the\n * map has parsed and grades documents the map does not own — every\n * `dynamic view` in `architecture/landscape.likec4` and in every\n * `architecture/usecases/*.likec4`. `../usecases/usecases.ts` owns the opt-in and\n * the grades; this owns which inputs they are handed, which is the part that has\n * twice been got wrong and is worth stating in one place.\n *\n * A sub-package of `fleet/` for `map/isolation.ts`'s reason, and with its rule:\n * it imports NOTHING from `fleet/` itself — a child reaching back into its\n * parent while the parent calls the child is the package cycle\n * `scripts/package-graph.mjs` refuses — so everything it needs arrives in one\n * record the caller fills.\n */\nimport { readCapabilityVocabulary } from \"../../../../core/capabilities/capabilities.js\";\nimport { capabilityRequirementIndex, gradableCapabilityIds } from \"../../../../core/capabilities/findings.js\";\nimport { parseRequirements, readRequirementsDocument } from \"../../../../core/document/parse.js\";\nimport { FleetContext } from \"../../../../core/fleet-context.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { Elem, Rel } from \"../../../../core/c4/likec4.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { useCaseFindings } from \"../usecases/usecases.js\";\n\nexport interface FleetUseCases {\n  docsDir: DocsDir;\n  /**\n   * The views come from the PROJECT load, never from a single-file fallback,\n   * and that is the file-naming rule made mechanical instead of remembered:\n   * only the project load gives a view the `sourcePath` a finding has to name,\n   * while a single-file load calls every document `source.c4` — so a message\n   * built from that load would send its reader to `architecture/source.c4`, a\n   * file that has never existed. No project, no views, and nothing to get wrong.\n   */\n  views: readonly ParsedView[];\n  /** The map's model — what a hop is resolved against. */\n  elements: Elem[];\n  relationships: Rel[];\n  /** The enumerated fleet, and the resolver every other edge join in the target uses. */\n  services: ReadonlySet<string>;\n  resolve: (id: string) => string;\n  fleet?: FleetContext;\n}\n\n/**\n * The capability ladder is APPLIED BY ITS OWN FUNCTION rather than re-spelled\n * here: an absent or unreadable capabilities.yaml means silence for the whole\n * family, not a fleet full of unresolved tags, so `null` travels rather than an\n * empty list — which the join would read as \"the fleet declares no capabilities\"\n * and grade every tag against. `gradableCapabilityIds`\n * (`core/capabilities/findings.ts`) is the one statement of that rule, and this\n * is a caller of it precisely so a fourth un-gradable vocabulary state cannot be\n * fixed in core while the command layer keeps handing the join a whole key set.\n *\n * Both reads are already paid for under `--all`: `capabilityFleetFindings` has\n * asked for the vocabulary, and every requirement document behind the `#req-`\n * tag was parsed by it, so the fleet memo answers from cache. The requirement\n * index is built here rather than inside the use-case package so that package\n * never learns what a capability document is.\n */\nexport async function fleetUseCaseFindings(input: FleetUseCases): Promise<Finding[]> {\n  const { docsDir, fleet } = input;\n  const vocabulary =\n    fleet === undefined ? await readCapabilityVocabulary(docsDir) : await fleet.capabilities(docsDir);\n  const capabilityReqs = await capabilityRequirementIndex(\n    vocabulary,\n    fleet === undefined\n      ? async (p) => parseRequirements(await readRequirementsDocument(p))\n      : (p) => fleet.readRequirements(p),\n  );\n  return useCaseFindings({\n    views: input.views,\n    elements: input.elements,\n    relationships: input.relationships,\n    services: input.services,\n    resolve: input.resolve,\n    capabilities: gradableCapabilityIds(vocabulary),\n    requirementsOf: (capability) => capabilityReqs.byCapability.get(capability),\n  });\n}\n"]}