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

package/dist/core/consumers/current.js

@@ -0,0 +1,211 @@
+/**
+ * The living fleet as it stands on disk, read through the invocation's
+ * `FleetContext` into the SAME `ServiceState` shape `core/diff/base-state.ts`
+ * builds from git — one shape, so `core/diff/semantic.ts` joins the two sides
+ * without caring which one came from the object store.
+ *
+ * It was `loam diff`'s working-tree side (`core/diff/current-state.ts`) and
+ * still is; it moved here because the consumer index (`./consumers.ts`) reads
+ * the same fleet for every caller — the diff, the coherence gate and the
+ * archive planner — and a reader that only the diff could import was why the
+ * gate kept a copy of its own.
+ *
+ * Containment discipline, per subject and per axis: an artifact that EXISTS
+ * but cannot be read (non-UTF-8 spec bytes, a directory sitting where a file
+ * belongs, broken contract YAML) degrades that one axis to `unreadable` with
+ * its path, and the hash of its bytes when there are bytes to hash — never a
+ * thrown enumeration, never an empty list a diff would read as "everything
+ * was removed". Absence stays absence: a file deleted
+ * between the existence probe and the read is classified by its errno
+ * (ENOENT), the same TOCTOU discipline `loadConfig` documents.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { serviceResolver } from "../c4/resolve/service.js";
+import { externalProducerOf } from "../c4/resolve/external.js";
+import { readUseCases, useCasesIn } from "../usecases/fleet.js";
+import { repoPath } from "../envelope/json.js";
+import { landscapePath, servicePathsAt } from "../repo/paths.js";
+import { inOrder } from "../kernel/concurrency.js";
+import { bytesDigest, collisions } from "./state.js";
+/**
+ * The unreadable arm, carrying the hash of the bytes that would not read
+ * (`AxisState`'s `bytes`, which the base side's `axisFrom` fills the same
+ * way). The readers this module goes through hand back a parsed document and
+ * not its bytes, so this is a second read — paid only on this path, which a
+ * healthy fleet never takes.
+ */
+async function unreadableAt(abs, rel, error) {
+    try {
+        return { kind: "unreadable", path: rel, error, bytes: bytesDigest(await readFile(abs)) };
+    }
+    catch {
+        // No bytes to hash (a directory where the file belongs, a file deleted
+        // since the first read): an unhashed side proves no identity, so the axis
+        // suspends exactly as it always did.
+        return { kind: "unreadable", path: rel, error };
+    }
+}
+async function readFailure(e, file) {
+    const errno = e;
+    if (errno.code === "ENOENT")
+        return { kind: "absent" };
+    return unreadableAt(file.abs, file.rel, e instanceof Error ? e.message : String(e));
+}
+/** One spec-axis file (`spec.md` / `arch.spec.md`) as parsed requirements. */
+async function requirementsAxis(context, abs, rel) {
+    if (!existsSync(abs))
+        return { kind: "absent" };
+    try {
+        return { kind: "read", value: await context.readRequirements(abs) };
+    }
+    catch (e) {
+        // decodeDocument's non-UTF-8 refusal lands here too: bytes that would
+        // parse as zero requirements must suspend the axis, not empty it.
+        return readFailure(e, { abs, rel });
+    }
+}
+async function openapiAxis(context, abs, rel) {
+    if (!existsSync(abs))
+        return { kind: "absent" };
+    try {
+        const doc = await context.readOpenapi(abs);
+        return doc.unreadable
+            ? await unreadableAt(abs, rel, doc.error ?? "not a readable OpenAPI document")
+            : { kind: "read", value: doc.ops.filter((op) => !op.remove) };
+    }
+    catch (e) {
+        return readFailure(e, { abs, rel });
+    }
+}
+/** The event contract as its declarations, and the names it sends — `sent` empty unless it read. */
+async function asyncapiAxis(context, abs, rel) {
+    if (!existsSync(abs))
+        return { axis: { kind: "absent" }, sent: [] };
+    try {
+        const doc = await context.readAsyncapi(abs);
+        return doc.unreadable
+            ? { axis: await unreadableAt(abs, rel, doc.error ?? "not a readable AsyncAPI document"), sent: [] }
+            : { axis: { kind: "read", value: doc.messages.filter((m) => m.remove !== true) }, sent: doc.sent };
+    }
+    catch (e) {
+        return { axis: await readFailure(e, { abs, rel }), sent: [] };
+    }
+}
+/**
+ * The current fleet, one `ServiceState` per enumerated service. The
+ * enumeration itself (the tree walk) may throw `DocsRepoUnavailableError` —
+ * that is the whole-repo refusal `docsRepoReady` fronts, not a per-subject
+ * degradation, and it stays a throw for the command layer to map.
+ */
+async function readCurrentFleet(docsDir, context) {
+    const entries = await context.listServices(docsDir);
+    const states = await inOrder(entries, async (entry) => {
+        const paths = servicePathsAt(entry.dir);
+        const events = await asyncapiAxis(context, paths.asyncapi, repoPath(docsDir, paths.asyncapi));
+        return {
+            id: entry.id,
+            dir: repoPath(docsDir, entry.dir),
+            spec: await requirementsAxis(context, paths.spec, repoPath(docsDir, paths.spec)),
+            archSpec: await requirementsAxis(context, paths.archSpec, repoPath(docsDir, paths.archSpec)),
+            openapi: await openapiAxis(context, paths.openapi, repoPath(docsDir, paths.openapi)),
+            asyncapi: events.axis,
+            sent: events.sent,
+        };
+    });
+    const ambiguous = collisions(states);
+    return {
+        services: new Map(states.filter((s) => !ambiguous.has(s.id)).map((s) => [s.id, s])),
+        ambiguous,
+    };
+}
+/**
+ * One read per invocation, keyed by the invocation's own FleetContext — the
+ * `core/coherence/retired/archived.ts` exception to the no-module-cache rule,
+ * for its reason: the key IS the per-invocation object, so two runs can never
+ * see each other's answer and the entry dies with the context. `validate --all`
+ * grades every active feature with one context, and every one of them asks the
+ * same fleet who consumes what; without this each feature re-read it. Not a
+ * memo ON FleetContext for that module's reason too: the class sits below this
+ * package, and the import such a memo needs would point up the DAG.
+ */
+const PER_INVOCATION = new WeakMap();
+function memoFor(docsDir, context) {
+    let store = PER_INVOCATION.get(context);
+    if (store === undefined)
+        PER_INVOCATION.set(context, (store = new Map()));
+    const key = resolve(docsDir);
+    let memo = store.get(key);
+    if (memo === undefined)
+        store.set(key, (memo = {}));
+    return memo;
+}
+/** `readCurrentFleet`, read at most once per invocation. */
+export function livingFleet(docsDir, context) {
+    const memo = memoFor(docsDir, context);
+    return (memo.fleet ??= readCurrentFleet(docsDir, context));
+}
+/**
+ * The map, read at most once per invocation — and read as the PROJECT, never
+ * `architecture/landscape.likec4` alone.
+ *
+ * The spine grades every edge the `architecture/` project declares
+ * (`commands/validate/service/spine.ts` reads `fleet.architecture`), and a
+ * use-case hop is attributed against that same project. A consumer scan that
+ * read one file of it answered "nobody calls it" about an edge drawn in
+ * `architecture/calls.likec4`, the gate passed, and the next `validate --all`
+ * reported `spine.op-undefined` on that very edge (review 2026-10-12, finding
+ * 2) — `core/pack/living.ts` states the same rule for the same reason. One load
+ * serves the edges and the hops: two readers of one project are two chances to
+ * disagree about which documents it holds.
+ *
+ * An unreadable project proves nothing either way: `landscape.invalid` is
+ * validate's finding to make, and neither a victim nor a doubt invented out of
+ * a parse error may point the reader at a file their change never touched. ONE
+ * fallback, and it adds only positive evidence: when the project does not parse
+ * but `landscape.likec4` does on its own — a broken use-case file beside a good
+ * map — the map's own edges still count. They are true of the map either way,
+ * and losing them would have let a removal through the gate (and a `loam diff`
+ * call it unconsumed) because of a document that has nothing to do with the
+ * edge. The use cases stay unreadable: a flow is graded against the whole
+ * project or not at all. Whether there is a map at all stays a fact about the
+ * FILE, as the pack's `present` does: a repo with no `landscape.likec4` has no
+ * map, not an empty project.
+ */
+export function livingMap(docsDir, context) {
+    const memo = memoFor(docsDir, context);
+    return (memo.map ??= (async () => {
+        // Every directory id the walk found, the ones two directories claim
+        // included — the services and the `ambiguous` ids of `livingFleet` together,
+        // which is the set validate resolves the map against (`known` in
+        // `commands/validate/service/service.ts`), read off the same memoised
+        // enumeration. Directory names, so the producer rule's guard (a services/
+        // directory outranks a tag) is handed what it demands.
+        const known = new Set((await context.listServices(docsDir)).map((entry) => entry.id));
+        const none = () => () => null;
+        const mapPath = landscapePath(docsDir);
+        if (!existsSync(mapPath)) {
+            return { relationships: null, resolve: (id) => id, useCases: await readUseCases({ docsDir, known }), externalProducerRule: none };
+        }
+        const doc = await context.architecture(docsDir);
+        const useCases = useCasesIn(doc, known);
+        if (doc.errors.length === 0) {
+            const resolve = serviceResolver(doc.elements, known);
+            const externalProducerRule = (materialised) => {
+                // The living set and its resolver stand whenever the merge creates no
+                // directory the walk has not already found — `loam diff`'s read, and
+                // most features'.
+                const after = materialised.every((id) => known.has(id)) ? known : new Set([...known, ...materialised]);
+                const svcOf = after === known ? resolve : serviceResolver(doc.elements, after);
+                return (message) => externalProducerOf(message, doc, svcOf, after);
+            };
+            return { relationships: doc.relationships, resolve, useCases, externalProducerRule };
+        }
+        const alone = await context.loadLikeC4(mapPath);
+        return alone.errors.length > 0
+            ? { relationships: null, resolve: (id) => id, useCases, externalProducerRule: none }
+            : { relationships: alone.relationships, resolve: serviceResolver(alone.elements, known), useCases, externalProducerRule: none };
+    })());
+}
+//# sourceMappingURL=current.js.map

package/dist/core/consumers/current.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"current.js","sourceRoot":"","sources":["../../../src/core/consumers/current.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The living fleet as it stands on disk, read through the invocation's\n * `FleetContext` into the SAME `ServiceState` shape `core/diff/base-state.ts`\n * builds from git — one shape, so `core/diff/semantic.ts` joins the two sides\n * without caring which one came from the object store.\n *\n * It was `loam diff`'s working-tree side (`core/diff/current-state.ts`) and\n * still is; it moved here because the consumer index (`./consumers.ts`) reads\n * the same fleet for every caller — the diff, the coherence gate and the\n * archive planner — and a reader that only the diff could import was why the\n * gate kept a copy of its own.\n *\n * Containment discipline, per subject and per axis: an artifact that EXISTS\n * but cannot be read (non-UTF-8 spec bytes, a directory sitting where a file\n * belongs, broken contract YAML) degrades that one axis to `unreadable` with\n * its path, and the hash of its bytes when there are bytes to hash — never a\n * thrown enumeration, never an empty list a diff would read as \"everything\n * was removed\". Absence stays absence: a file deleted\n * between the existence probe and the read is classified by its errno\n * (ENOENT), the same TOCTOU discipline `loadConfig` documents.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport type { Rel } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { externalProducerOf } from \"../c4/resolve/external.js\";\nimport { readUseCases, useCasesIn, type UseCaseScan } from \"../usecases/fleet.js\";\nimport type { Requirement } from \"../document/spec.js\";\nimport type { Operation } from \"../openapi/doc.js\";\nimport type { EventMessage } from \"../asyncapi/model.js\";\nimport { repoPath } from \"../envelope/json.js\";\nimport { landscapePath, servicePathsAt } from \"../repo/paths.js\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { RawServiceId } from \"../kernel/ids/service.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { bytesDigest, collisions, type AxisState, type ServiceState } from \"./state.js\";\n\n/**\n * One living service as the consumer index reads it: the diff's four axes, plus\n * the one fact about its event contract the index asks and the diff never\n * compares — which messages it SENDS. Current side only: the base side is read\n * for what changed, and nothing asks who produced a message at the base ref.\n */\nexport interface LivingServiceState extends ServiceState {\n  /**\n   * The message names an `action: send` operation of the living asyncapi.yaml\n   * reaches (`AsyncapiDoc.sent`) — what this service PRODUCES. Empty unless the\n   * contract reads: an unreadable one never vouches for a producer.\n   */\n  sent: readonly string[];\n}\n\nexport interface CurrentFleet {\n  /** By service id, in the enumeration's (sorted-walk) order. Ids the `ambiguous` map claims are excluded. */\n  services: Map<string, LivingServiceState>;\n  /**\n   * Ids more than one working-tree directory claims — `subsystem.name-collision`'s\n   * live shape, which validate diagnoses. Diffing either claimant would pick a\n   * winner nobody chose (a `new Map` collapse here used to keep the LAST one and\n   * fabricate a whole change story about a service that never moved), so the\n   * subject is suspended exactly as the base side's `ambiguous` map suspends it.\n   */\n  ambiguous: Map<string, string[]>;\n}\n\n/**\n * The unreadable arm, carrying the hash of the bytes that would not read\n * (`AxisState`'s `bytes`, which the base side's `axisFrom` fills the same\n * way). The readers this module goes through hand back a parsed document and\n * not its bytes, so this is a second read — paid only on this path, which a\n * healthy fleet never takes.\n */\nasync function unreadableAt(abs: string, rel: string, error: string): Promise<AxisState<never>> {\n  try {\n    return { kind: \"unreadable\", path: rel, error, bytes: bytesDigest(await readFile(abs)) };\n  } catch {\n    // No bytes to hash (a directory where the file belongs, a file deleted\n    // since the first read): an unhashed side proves no identity, so the axis\n    // suspends exactly as it always did.\n    return { kind: \"unreadable\", path: rel, error };\n  }\n}\n\nasync function readFailure(e: unknown, file: { abs: string; rel: string }): Promise<AxisState<never>> {\n  const errno = e as NodeJS.ErrnoException;\n  if (errno.code === \"ENOENT\") return { kind: \"absent\" };\n  return unreadableAt(file.abs, file.rel, e instanceof Error ? e.message : String(e));\n}\n\n/** One spec-axis file (`spec.md` / `arch.spec.md`) as parsed requirements. */\nasync function requirementsAxis(context: FleetContext, abs: string, rel: string): Promise<AxisState<Requirement[]>> {\n  if (!existsSync(abs)) return { kind: \"absent\" };\n  try {\n    return { kind: \"read\", value: await context.readRequirements(abs) };\n  } catch (e) {\n    // decodeDocument's non-UTF-8 refusal lands here too: bytes that would\n    // parse as zero requirements must suspend the axis, not empty it.\n    return readFailure(e, { abs, rel });\n  }\n}\n\nasync function openapiAxis(context: FleetContext, abs: string, rel: string): Promise<AxisState<Operation[]>> {\n  if (!existsSync(abs)) return { kind: \"absent\" };\n  try {\n    const doc = await context.readOpenapi(abs);\n    return doc.unreadable\n      ? await unreadableAt(abs, rel, doc.error ?? \"not a readable OpenAPI document\")\n      : { kind: \"read\", value: doc.ops.filter((op) => !op.remove) };\n  } catch (e) {\n    return readFailure(e, { abs, rel });\n  }\n}\n\n/** The event contract as its declarations, and the names it sends — `sent` empty unless it read. */\nasync function asyncapiAxis(\n  context: FleetContext,\n  abs: string,\n  rel: string,\n): Promise<{ axis: AxisState<EventMessage[]>; sent: readonly string[] }> {\n  if (!existsSync(abs)) return { axis: { kind: \"absent\" }, sent: [] };\n  try {\n    const doc = await context.readAsyncapi(abs);\n    return doc.unreadable\n      ? { axis: await unreadableAt(abs, rel, doc.error ?? \"not a readable AsyncAPI document\"), sent: [] }\n      : { axis: { kind: \"read\", value: doc.messages.filter((m) => m.remove !== true) }, sent: doc.sent };\n  } catch (e) {\n    return { axis: await readFailure(e, { abs, rel }), sent: [] };\n  }\n}\n\n/**\n * The current fleet, one `ServiceState` per enumerated service. The\n * enumeration itself (the tree walk) may throw `DocsRepoUnavailableError` —\n * that is the whole-repo refusal `docsRepoReady` fronts, not a per-subject\n * degradation, and it stays a throw for the command layer to map.\n */\nasync function readCurrentFleet(docsDir: DocsDir, context: FleetContext): Promise<CurrentFleet> {\n  const entries = await context.listServices(docsDir);\n  const states = await inOrder(entries, async (entry): Promise<LivingServiceState> => {\n    const paths = servicePathsAt(entry.dir);\n    const events = await asyncapiAxis(context, paths.asyncapi, repoPath(docsDir, paths.asyncapi));\n    return {\n      id: entry.id,\n      dir: repoPath(docsDir, entry.dir),\n      spec: await requirementsAxis(context, paths.spec, repoPath(docsDir, paths.spec)),\n      archSpec: await requirementsAxis(context, paths.archSpec, repoPath(docsDir, paths.archSpec)),\n      openapi: await openapiAxis(context, paths.openapi, repoPath(docsDir, paths.openapi)),\n      asyncapi: events.axis,\n      sent: events.sent,\n    };\n  });\n  const ambiguous = collisions(states);\n  return {\n    services: new Map(states.filter((s) => !ambiguous.has(s.id)).map((s) => [s.id, s])),\n    ambiguous,\n  };\n}\n\n/**\n * The fleet map half of the living read: the `architecture/` PROJECT's edges,\n * the one resolver every join over them uses, and the use cases drawn on it.\n */\nexport interface LivingMap {\n  /** Every relationship the project declares, or `null` when the map proves nothing — absent, or it does not parse. */\n  relationships: readonly Rel[] | null;\n  /**\n   * Element → service, with the enumerated fleet riding in — the resolver the\n   * spine and the step graders use. Without the fleet, an edge into a modelled\n   * container `payment.api` resolves to a service called \"api\" that has never\n   * existed, the join on the provider finds nothing, and the one check\n   * standing between a removal and its last consumer answers \"nobody calls it\"\n   * (DESIGN's serviceResolver-known row).\n   */\n  resolve: (id: string) => string;\n  useCases: UseCaseScan;\n  /**\n   * The rule naming the #external element whose `publishes` edge sends a\n   * message, or null — validate's own (`externalProducerOf`,\n   * `core/c4/resolve/external.ts`), asked of the same project with the same\n   * directory ids and a resolver built over them, so the gate and `loam diff`\n   * call a message produced exactly where `spine.message-unproduced` stays\n   * quiet. Null wherever the PROJECT does not parse, the fallback below\n   * included: validate grades the producer against the project or not at all,\n   * and an outside producer found on a map it would not accept would pass a\n   * removal its next run then reports.\n   *\n   * `materialised` is the service ids whose `services/<id>/` a feature's merge\n   * would create — empty for a reader of the fleet as it stands. They join the\n   * directory ids, and the resolver is REBUILT over the union, because the\n   * rule's guard (a `services/<id>/` directory outranks the tag) is asked of\n   * the directories the next `validate` will see: a feature carrying\n   * `specs/legacy-gateway/` creates that directory, the #external element\n   * titled `legacy-gateway` — or a topic nested inside it — then resolves to\n   * it, and the producer is gone. Asked over the directories as they stood,\n   * the gate passed a retirement from the message's only fleet sender, and\n   * after the archive `loam diff` reported `diff.message-removed-consumed` and\n   * `validate --all` `spine.message-unproduced` (the verification of D1, X2).\n   */\n  externalProducerRule: (materialised: readonly RawServiceId[]) => (message: string) => string | null;\n}\n\n/** What one invocation has read, per docs root: each half paid for at its first question. */\ninterface Memo {\n  fleet?: Promise<CurrentFleet>;\n  map?: Promise<LivingMap>;\n}\n\n/**\n * One read per invocation, keyed by the invocation's own FleetContext — the\n * `core/coherence/retired/archived.ts` exception to the no-module-cache rule,\n * for its reason: the key IS the per-invocation object, so two runs can never\n * see each other's answer and the entry dies with the context. `validate --all`\n * grades every active feature with one context, and every one of them asks the\n * same fleet who consumes what; without this each feature re-read it. Not a\n * memo ON FleetContext for that module's reason too: the class sits below this\n * package, and the import such a memo needs would point up the DAG.\n */\nconst PER_INVOCATION = new WeakMap<FleetContext, Map<string, Memo>>();\n\nfunction memoFor(docsDir: DocsDir, context: FleetContext): Memo {\n  let store = PER_INVOCATION.get(context);\n  if (store === undefined) PER_INVOCATION.set(context, (store = new Map()));\n  const key = resolve(docsDir);\n  let memo = store.get(key);\n  if (memo === undefined) store.set(key, (memo = {}));\n  return memo;\n}\n\n/** `readCurrentFleet`, read at most once per invocation. */\nexport function livingFleet(docsDir: DocsDir, context: FleetContext): Promise<CurrentFleet> {\n  const memo = memoFor(docsDir, context);\n  return (memo.fleet ??= readCurrentFleet(docsDir, context));\n}\n\n/**\n * The map, read at most once per invocation — and read as the PROJECT, never\n * `architecture/landscape.likec4` alone.\n *\n * The spine grades every edge the `architecture/` project declares\n * (`commands/validate/service/spine.ts` reads `fleet.architecture`), and a\n * use-case hop is attributed against that same project. A consumer scan that\n * read one file of it answered \"nobody calls it\" about an edge drawn in\n * `architecture/calls.likec4`, the gate passed, and the next `validate --all`\n * reported `spine.op-undefined` on that very edge (review 2026-10-12, finding\n * 2) — `core/pack/living.ts` states the same rule for the same reason. One load\n * serves the edges and the hops: two readers of one project are two chances to\n * disagree about which documents it holds.\n *\n * An unreadable project proves nothing either way: `landscape.invalid` is\n * validate's finding to make, and neither a victim nor a doubt invented out of\n * a parse error may point the reader at a file their change never touched. ONE\n * fallback, and it adds only positive evidence: when the project does not parse\n * but `landscape.likec4` does on its own — a broken use-case file beside a good\n * map — the map's own edges still count. They are true of the map either way,\n * and losing them would have let a removal through the gate (and a `loam diff`\n * call it unconsumed) because of a document that has nothing to do with the\n * edge. The use cases stay unreadable: a flow is graded against the whole\n * project or not at all. Whether there is a map at all stays a fact about the\n * FILE, as the pack's `present` does: a repo with no `landscape.likec4` has no\n * map, not an empty project.\n */\nexport function livingMap(docsDir: DocsDir, context: FleetContext): Promise<LivingMap> {\n  const memo = memoFor(docsDir, context);\n  return (memo.map ??= (async (): Promise<LivingMap> => {\n    // Every directory id the walk found, the ones two directories claim\n    // included — the services and the `ambiguous` ids of `livingFleet` together,\n    // which is the set validate resolves the map against (`known` in\n    // `commands/validate/service/service.ts`), read off the same memoised\n    // enumeration. Directory names, so the producer rule's guard (a services/\n    // directory outranks a tag) is handed what it demands.\n    const known: ReadonlySet<RawServiceId> = new Set((await context.listServices(docsDir)).map((entry) => entry.id));\n    const none = (): ((message: string) => null) => () => null;\n    const mapPath = landscapePath(docsDir);\n    if (!existsSync(mapPath)) {\n      return { relationships: null, resolve: (id) => id, useCases: await readUseCases({ docsDir, known }), externalProducerRule: none };\n    }\n    const doc = await context.architecture(docsDir);\n    const useCases = useCasesIn(doc, known);\n    if (doc.errors.length === 0) {\n      const resolve = serviceResolver(doc.elements, known);\n      const externalProducerRule = (materialised: readonly RawServiceId[]): ((message: string) => string | null) => {\n        // The living set and its resolver stand whenever the merge creates no\n        // directory the walk has not already found — `loam diff`'s read, and\n        // most features'.\n        const after = materialised.every((id) => known.has(id)) ? known : new Set([...known, ...materialised]);\n        const svcOf = after === known ? resolve : serviceResolver(doc.elements, after);\n        return (message) => externalProducerOf(message, doc, svcOf, after);\n      };\n      return { relationships: doc.relationships, resolve, useCases, externalProducerRule };\n    }\n    const alone = await context.loadLikeC4(mapPath);\n    return alone.errors.length > 0\n      ? { relationships: null, resolve: (id) => id, useCases, externalProducerRule: none }\n      : { relationships: alone.relationships, resolve: serviceResolver(alone.elements, known), useCases, externalProducerRule: none };\n  })());\n}\n"]}

package/dist/core/consumers/scan.js

@@ -0,0 +1,46 @@
+/**
+ * What one consumer question answers, and the one sentence that phrases it.
+ *
+ * Moved out of `loam diff`'s victim index (`core/diff/victims.ts`, now
+ * `./consumers.ts`) as its own module because three readers phrase the same
+ * answer — `loam diff`'s findings, `loam archive`'s overwrite warnings and the
+ * coherence gate's refusals — and none of them should have to import the index
+ * to name its result type.
+ */
+/**
+ * Is this a doubt about a consumer DOCUMENT — one loam could not read, or could
+ * not tell whose it is? Those are what the removal gate refuses on, as the gate
+ * before the one index did: it read every consumer's spec itself, and a file it
+ * could not decode either stopped `validate` or was read leniently by `archive`
+ * and refused. Filing those as warnings let a removal archive at exit 0 over a
+ * Latin-1 spec.md that still named the operation (the one-index review, finding 1).
+ *
+ * The other two kinds are doubts about a DRAWING, and they stay out of the
+ * gate on purpose: `loam seed` draws every edge without an op, so refusing on
+ * an op-less caller would turn every removal on a seeded fleet red, and a
+ * contested hop is a flow the model cannot attribute (`./consumers.ts` and
+ * `core/usecases/operations.ts` say why each is a doubt and never a victim).
+ * `loam diff` needs no such split: an unreadable document carries its run to
+ * exit 1 through its own `unreadable[]` entry, the drawings do not.
+ */
+export function documentDoubt(s) {
+    return s.kind === "unreadable" || s.kind === "ambiguous";
+}
+/** What a reader's `details[]` lists for one scan: positive evidence first, then every doubt — the order `loam diff` lists them in. */
+export function scanDetails(scan) {
+    return [...scan.victims, ...scan.suspended.map((s) => s.text)];
+}
+/**
+ * Three honest phrasings of one consumer scan — never a confident negative
+ * over a scan that skipped something it could not check. Beside the type it
+ * phrases rather than inside `core/diff/semantic.ts`, because `loam diff` is no longer
+ * its only reader: `loam archive`'s overwrite warnings ask the same scan of
+ * the same fleet, and one sentence for one answer is what lets a reader meet
+ * one vocabulary in both.
+ */
+export function consumerStance(scan) {
+    return scan.victims.length > 0 ? `${scan.victims.length} current consumer(s) still name it`
+        : scan.suspended.length > 0 ? "whether current consumers name it could not be fully answered"
+            : "no current consumer names it";
+}
+//# sourceMappingURL=scan.js.map

package/dist/core/consumers/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../src/core/consumers/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqCH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,CAAa;IACzC,OAAO,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC;AAC3D,CAAC;AAED,uIAAuI;AACvI,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAkB;IAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,oCAAoC;QACzF,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,+DAA+D;YAC7F,CAAC,CAAC,8BAA8B,CAAC;AACrC,CAAC","sourcesContent":["/**\n * What one consumer question answers, and the one sentence that phrases it.\n *\n * Moved out of `loam diff`'s victim index (`core/diff/victims.ts`, now\n * `./consumers.ts`) as its own module because three readers phrase the same\n * answer — `loam diff`'s findings, `loam archive`'s overwrite warnings and the\n * coherence gate's refusals — and none of them should have to import the index\n * to name its result type.\n */\n\n/**\n * Why one possible consumer could not be checked. Typed, because the readers do\n * not weigh the kinds alike: a doubt about a DOCUMENT (`documentDoubt`) is one\n * the removal gate refuses on, and a doubt about a DRAWING is not.\n */\nexport type SuspensionKind =\n  /** A consumer's spec.md or arch.spec.md exists and loam refused to read it — non-UTF-8 bytes, a directory where the file belongs. */\n  | \"unreadable\"\n  /** Two directories claim the consumer's service id, so neither one's documents were scanned. */\n  | \"ambiguous\"\n  /** An edge into the provider drawn with no `metadata { op }`: it calls the provider, and nobody wrote down which operation. */\n  | \"unlinked\"\n  /** A use-case hop whose backing relationships name different operations, this one among them. */\n  | \"contested\";\n\n/** One possible consumer the scan could not check, and the sentence that says which and why. */\nexport interface Suspension {\n  kind: SuspensionKind;\n  /** What every reader shows — the document, the directories, the edge or the hop, by name. */\n  text: string;\n}\n\n/**\n * One consumer scan's answer, honest about its own coverage. `victims` is\n * positive evidence; `suspended` names the consumers whose relevant document\n * could not be read (or whose identity is ambiguous), and the callers drawn or\n * flowed too vaguely to attribute, because a scan that skipped a file loam\n * REFUSED to read must never let the caller assert \"nobody names it\" — the\n * fail-open shape this type exists to forbid.\n */\nexport interface ConsumerScan {\n  victims: string[];\n  suspended: Suspension[];\n}\n\n/**\n * Is this a doubt about a consumer DOCUMENT — one loam could not read, or could\n * not tell whose it is? Those are what the removal gate refuses on, as the gate\n * before the one index did: it read every consumer's spec itself, and a file it\n * could not decode either stopped `validate` or was read leniently by `archive`\n * and refused. Filing those as warnings let a removal archive at exit 0 over a\n * Latin-1 spec.md that still named the operation (the one-index review, finding 1).\n *\n * The other two kinds are doubts about a DRAWING, and they stay out of the\n * gate on purpose: `loam seed` draws every edge without an op, so refusing on\n * an op-less caller would turn every removal on a seeded fleet red, and a\n * contested hop is a flow the model cannot attribute (`./consumers.ts` and\n * `core/usecases/operations.ts` say why each is a doubt and never a victim).\n * `loam diff` needs no such split: an unreadable document carries its run to\n * exit 1 through its own `unreadable[]` entry, the drawings do not.\n */\nexport function documentDoubt(s: Suspension): boolean {\n  return s.kind === \"unreadable\" || s.kind === \"ambiguous\";\n}\n\n/** What a reader's `details[]` lists for one scan: positive evidence first, then every doubt — the order `loam diff` lists them in. */\nexport function scanDetails(scan: ConsumerScan): string[] {\n  return [...scan.victims, ...scan.suspended.map((s) => s.text)];\n}\n\n/**\n * Three honest phrasings of one consumer scan — never a confident negative\n * over a scan that skipped something it could not check. Beside the type it\n * phrases rather than inside `core/diff/semantic.ts`, because `loam diff` is no longer\n * its only reader: `loam archive`'s overwrite warnings ask the same scan of\n * the same fleet, and one sentence for one answer is what lets a reader meet\n * one vocabulary in both.\n */\nexport function consumerStance(scan: ConsumerScan): string {\n  return scan.victims.length > 0 ? `${scan.victims.length} current consumer(s) still name it`\n    : scan.suspended.length > 0 ? \"whether current consumers name it could not be fully answered\"\n    : \"no current consumer names it\";\n}\n"]}

package/dist/core/consumers/state.js

@@ -0,0 +1,27 @@
+/**
+ * One service's four documents, each read or honestly not — the shape every
+ * consumer question is asked of.
+ *
+ * It began as `loam diff`'s (`core/diff/base-state.ts` held it, because the
+ * diff was its only reader), and moved here when the consumer index became
+ * the one answer the diff, the coherence gate and the archive planner share:
+ * the index reads the living fleet in this shape, so the shape lives one level
+ * below everything that asks it.
+ */
+import { createHash } from "node:crypto";
+/** The `bytes` identity of an unreadable side — the same hash on both sides, so equal means byte-identical. */
+export function bytesDigest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Ids claimed by more than one enumerated directory, with every claimant named
+ * — the base side's grouping (`core/diff/base-state.ts`) and `./current.ts`'s,
+ * so the two sides of a diff refuse the same ambiguity the same way.
+ */
+export function collisions(dirs) {
+    const byId = new Map();
+    for (const d of dirs)
+        byId.set(d.id, [...(byId.get(d.id) ?? []), d.dir]);
+    return new Map([...byId].filter(([, claimants]) => claimants.length > 1));
+}
+//# sourceMappingURL=state.js.map

package/dist/core/consumers/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/core/consumers/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA0BzC,+GAA+G;AAC/G,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAuBD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAA4C;IACrE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzE,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC","sourcesContent":["/**\n * One service's four documents, each read or honestly not — the shape every\n * consumer question is asked of.\n *\n * It began as `loam diff`'s (`core/diff/base-state.ts` held it, because the\n * diff was its only reader), and moved here when the consumer index became\n * the one answer the diff, the coherence gate and the archive planner share:\n * the index reads the living fleet in this shape, so the shape lives one level\n * below everything that asks it.\n */\nimport { createHash } from \"node:crypto\";\nimport type { Requirement } from \"../document/spec.js\";\nimport type { Operation } from \"../openapi/doc.js\";\nimport type { EventMessage } from \"../asyncapi/model.js\";\nimport type { RawServiceId } from \"../kernel/ids/service.js\";\n\n/**\n * One artifact's state on one side of the diff. `unreadable` is the\n * containment arm: the file exists but could not be read as its kind, so\n * every finding on this axis for this subject is SUSPENDED — \"nobody could\n * look\" must never grade as \"nothing is there\", in either direction.\n *\n * `bytes` is the sha256 of the raw file when there WERE bytes and they refused\n * to parse — absent when the bytes themselves could not be had (a failed\n * `git show`, a directory where the file belongs). It is the one fact an\n * unreadable side can still prove: that it is the same file the other side\n * holds, which `core/diff/semantic.ts`'s `comparable` turns into \"the branch\n * did not touch this contract\" (an AsyncAPI 2.x document is unreadable by policy, and\n * suspending it on every run failed every `loam diff` over a fleet that holds\n * one, whatever the branch changed).\n */\nexport type AxisState<T> =\n  | { kind: \"absent\" }\n  | { kind: \"read\"; value: T }\n  | { kind: \"unreadable\"; path: string; error: string; bytes?: string };\n\n/** The `bytes` identity of an unreadable side — the same hash on both sides, so equal means byte-identical. */\nexport function bytesDigest(bytes: Buffer): string {\n  return createHash(\"sha256\").update(bytes).digest(\"hex\");\n}\n\n/**\n * One service on one side of the diff — the same shape for the base ref and\n * the working tree (`./current.ts` builds that one, `core/diff/base-state.ts`\n * the base ref's), which is what lets `core/diff/semantic.ts` join the two\n * without caring which side came from git — and what lets the consumer index\n * (`./consumers.ts`) read the living fleet in the shape the diff already does.\n */\nexport interface ServiceState {\n  /** The directory's leaf name — a name read off the tree, so the index may join it into a feature's `specs/<svc>/`. */\n  id: RawServiceId;\n  /** Docs-relative directory with forward slashes, e.g. `services/billing/payment-service`. */\n  dir: string;\n  spec: AxisState<Requirement[]>;\n  /** Read on both sides for every requirement join — the outbox requirement lives here as often as in spec.md (`./consumers.ts`'s `REQUIREMENT_AXES`). */\n  archSpec: AxisState<Requirement[]>;\n  /** Operations with `x-loam-remove` markers filtered out: a marker is bookkeeping, never a callable operation. */\n  openapi: AxisState<Operation[]>;\n  /** Messages with removal markers filtered out, for the same reason. */\n  asyncapi: AxisState<EventMessage[]>;\n}\n\n/**\n * Ids claimed by more than one enumerated directory, with every claimant named\n * — the base side's grouping (`core/diff/base-state.ts`) and `./current.ts`'s,\n * so the two sides of a diff refuse the same ambiguity the same way.\n */\nexport function collisions(dirs: readonly { id: string; dir: string }[]): Map<string, string[]> {\n  const byId = new Map<string, string[]>();\n  for (const d of dirs) byId.set(d.id, [...(byId.get(d.id) ?? []), d.dir]);\n  return new Map([...byId].filter(([, claimants]) => claimants.length > 1));\n}\n"]}

package/dist/core/delta/claims.js

@@ -0,0 +1,73 @@
+/**
+ * What OTHER features in flight claim, and the lazy lookup the checks use.
+ *
+ * The scan is built on first use and never twice: the common delta claims
+ * nothing another feature touches, and the fleet walk is the expensive part of
+ * this whole module. `ClaimLookup` is an interface rather than the maps
+ * themselves so `./select.ts` cannot see — and so cannot accidentally force —
+ * the scan it is deciding whether to need.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import {} from "../fleet-context.js";
+import { parseRequirements } from "../document/parse.js";
+import {} from "../document/spec.js";
+import { featureSpecPaths, SPEC_AXES } from "../repo/paths.js";
+import { listFeatures } from "../repo/repo.js";
+import { key, requirementKey } from "./scope.js";
+/**
+ * A lookup that runs the fleet scan at most once, on the first question asked.
+ * The common case never pays for it.
+ */
+export function claimLookup(docsDir, featureId, context) {
+    let inFlight = null;
+    const ask = async (which, scope, requirement) => {
+        // Asked and answered without the scan: the index below holds SERVICE
+        // claims only, so every key a capability scope could build begins with a
+        // kind no row carries. Without this line a capability-only feature — an
+        // analyst's first act, touching no service at all — paid a full fleet walk
+        // plus a parse of every active feature's every delta document to reach an
+        // answer that is `undefined` by construction. Delete it on the day
+        // `activeClaims` indexes the business corpus too, and not before.
+        if (scope.kind !== "service")
+            return undefined;
+        inFlight ??= await activeClaims(docsDir, featureId, context);
+        const map = inFlight[which];
+        return map.get(key(scope, requirementKey(requirement)))
+            ?? map.get(key(scope, `name:${requirement.name}`));
+    };
+    return {
+        added: (scope, requirement) => ask("added", scope, requirement),
+        changed: (scope, requirement) => ask("changed", scope, requirement),
+    };
+}
+async function activeClaims(docsDir, exclude, context) {
+    const added = new Map();
+    const changed = new Map();
+    for (const feature of await listFeatures(docsDir, {}, context)) {
+        if (feature.id === exclude)
+            continue;
+        for (const service of feature.services) {
+            for (const axis of SPEC_AXES) {
+                const path = featureSpecPaths(feature.dir, service)[axis.key];
+                if (!existsSync(path))
+                    continue;
+                const reqs = context === undefined
+                    ? parseRequirements(await readFile(path, "utf8"))
+                    : await context.readRequirements(path);
+                for (const r of reqs) {
+                    const map = r.kind === "ADDED" ? added : r.kind === "MODIFIED" || r.kind === "REMOVED" ? changed : null;
+                    if (map === null)
+                        continue;
+                    for (const identity of new Set([requirementKey(r), `name:${r.name}`])) {
+                        const k = key({ kind: "service", subject: service, axis }, identity);
+                        if (!map.has(k))
+                            map.set(k, feature.id);
+                    }
+                }
+            }
+        }
+    }
+    return { added, changed };
+}
+//# sourceMappingURL=claims.js.map

package/dist/core/delta/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../../../src/core/delta/claims.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What OTHER features in flight claim, and the lazy lookup the checks use.\n *\n * The scan is built on first use and never twice: the common delta claims\n * nothing another feature touches, and the fleet walk is the expensive part of\n * this whole module. `ClaimLookup` is an interface rather than the maps\n * themselves so `./select.ts` cannot see — and so cannot accidentally force —\n * the scan it is deciding whether to need.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { type FleetContext } from \"../fleet-context.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport { type Requirement } from \"../document/spec.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../repo/paths.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport { key, requirementKey, type DeltaScope } from \"./scope.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/** Which other feature claims this requirement, if any — one question per index. */\nexport interface ClaimLookup {\n  added(scope: DeltaScope, requirement: Pick<Requirement, \"id\" | \"name\">): Promise<string | undefined>;\n  changed(scope: DeltaScope, requirement: Pick<Requirement, \"id\" | \"name\">): Promise<string | undefined>;\n}\n\n/**\n * A lookup that runs the fleet scan at most once, on the first question asked.\n * The common case never pays for it.\n */\nexport function claimLookup(docsDir: DocsDir, featureId: string, context?: FleetContext): ClaimLookup {\n  let inFlight: ActiveClaims | null = null;\n  const ask = async (\n    which: keyof ActiveClaims,\n    scope: DeltaScope,\n    requirement: Pick<Requirement, \"id\" | \"name\">,\n  ): Promise<string | undefined> => {\n    // Asked and answered without the scan: the index below holds SERVICE\n    // claims only, so every key a capability scope could build begins with a\n    // kind no row carries. Without this line a capability-only feature — an\n    // analyst's first act, touching no service at all — paid a full fleet walk\n    // plus a parse of every active feature's every delta document to reach an\n    // answer that is `undefined` by construction. Delete it on the day\n    // `activeClaims` indexes the business corpus too, and not before.\n    if (scope.kind !== \"service\") return undefined;\n    inFlight ??= await activeClaims(docsDir, featureId, context);\n    const map = inFlight[which];\n    return map.get(key(scope, requirementKey(requirement)))\n      ?? map.get(key(scope, `name:${requirement.name}`));\n  };\n  return {\n    added: (scope, requirement) => ask(\"added\", scope, requirement),\n    changed: (scope, requirement) => ask(\"changed\", scope, requirement),\n  };\n}\n\n/**\n * What other ACTIVE features claim, per (kind, subject, axis, requirement):\n * what they ADD, and — separately — what they CHANGE or REMOVE. The two are\n * separate indexes because they mean opposite things to the reader: an addition\n * elsewhere explains why a MODIFIED target is missing today, a change elsewhere\n * warns that the target is contested. One scan builds both; scanning twice\n * would double the fleet walk for the same bytes.\n *\n * SERVICE CLAIMS ONLY, deliberately. A capability delta's questions therefore\n * always answer `undefined`, which suppresses four cross-feature warnings on\n * the business axis — `delta.added-conflict`, `delta.modified-conflict`,\n * `delta.modified-pending` and `delta.removed-pending`. Never a wrong answer,\n * only a missing warning, and the `kind` in the key is what keeps it missing\n * rather than wrong (a capability and a service sharing a name would otherwise\n * collide). `claimLookup` short-circuits on that kind rather than asking, so\n * the suppression costs nothing as well as saying nothing. Indexing the\n * capability axis too is one more walk in this same loop; it waits for the\n * fleet that reports the ordering, because a warning shipped speculatively is\n * a branch nobody needed.\n */\ninterface ActiveClaims {\n  added: Map<string, string>;\n  changed: Map<string, string>;\n}\n\nasync function activeClaims(\n  docsDir: DocsDir,\n  exclude: string,\n  context?: FleetContext,\n): Promise<ActiveClaims> {\n  const added = new Map<string, string>();\n  const changed = new Map<string, string>();\n  for (const feature of await listFeatures(docsDir, {}, context)) {\n    if (feature.id === exclude) continue;\n    for (const service of feature.services) {\n      for (const axis of SPEC_AXES) {\n        const path = featureSpecPaths(feature.dir, service)[axis.key];\n        if (!existsSync(path)) continue;\n        const reqs = context === undefined\n          ? parseRequirements(await readFile(path, \"utf8\"))\n          : await context.readRequirements(path);\n        for (const r of reqs) {\n          const map = r.kind === \"ADDED\" ? added : r.kind === \"MODIFIED\" || r.kind === \"REMOVED\" ? changed : null;\n          if (map === null) continue;\n          for (const identity of new Set([requirementKey(r), `name:${r.name}`])) {\n            const k = key({ kind: \"service\", subject: service, axis }, identity);\n            if (!map.has(k)) map.set(k, feature.id);\n          }\n        }\n      }\n    }\n  }\n  return { added, changed };\n}\n"]}