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

package/dist/core/explore/explore.js

@@ -0,0 +1,204 @@
+/**
+ * The blast radius of a change nobody has written down yet.
+ *
+ * Everything else in loam answers a question about documents that exist. This
+ * module answers the one that comes BEFORE the first document: which services
+ * does this feature actually touch? On a fleet of a hundred that call is the
+ * hardest one in the cycle and the only one made with no tool in hand —
+ * `loam new FEAT-101 --touches a --touches b` takes the answer as an argument
+ * and scaffolds whatever it was told. A `--touches` list short by one service
+ * is not caught by anything: the feature validates, archives, and ships with a
+ * consumer nobody updated.
+ *
+ * So this states the work the same way `brief/brief.ts` does. It reads the fleet map
+ * and the living contracts, reports the ring of services around the seeds, the
+ * features already in flight over the same ground, and how far each service's
+ * documentation has got — and stops. Which of those neighbours the feature
+ * really touches is a judgement about intent, and loam does not make those.
+ *
+ * "The fleet map" here is the `architecture/` PROJECT — the landscape plus every
+ * other `.likec4` under it, minus the generated views file — and not the
+ * landscape FILE. See the read below for the disagreement that reading one file
+ * caused.
+ *
+ * It is parsed ONCE for the whole exploration. Per-service reads of it exist
+ * (`brief/landscape.ts`'s `landscapeContext`) and are correct for one service;
+ * calling one of those per seed is how `validate --all` came to cost 13 seconds
+ * on 120 services, and this command sits in front of authoring, where that is
+ * the difference between a habit and a thing people skip.
+ */
+import { existsSync } from "node:fs";
+import { FleetContext } from "../fleet-context.js";
+import { brokenDocumentPaths } from "../c4/likec4.js";
+import { serviceResolver } from "../c4/resolve/service.js";
+import {} from "../vocabulary/maturity.js";
+import { capabilityRollup, unresolvedCapabilities } from "../capabilities/rollup.js";
+import { compareIds, nearestIds } from "../repo/entries.js";
+import { landscapePath } from "../repo/paths.js";
+import { readUseCases } from "../usecases/fleet.js";
+import { servicesInFlowsClaiming } from "../usecases/capability.js";
+import { describe, newCommand, operationOwner } from "./describe.js";
+/**
+ * Read the fleet around a proposed change. Reads only; writes nothing, and
+ * refuses nothing — every miss is reported as a field.
+ */
+export async function explore(req) {
+    const { docsDir, featureId } = req;
+    const context = req.context ?? new FleetContext();
+    const entries = await context.listServices(docsDir);
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const known = new Set(byId.keys());
+    // The `architecture/` PROJECT, never `architecture/landscape.likec4` alone.
+    // The map is a project — the landscape merged with every use case, palette and
+    // second `model { }` block beside it — and reading one file of it made this
+    // command answer differently from `loam adopt` and `loam context` about the
+    // same tree (reproduced: with a broken `architecture/palette.likec4` beside a
+    // landscape that parses, `context checkout-web --json` reported
+    // `landscape.parses: false` while `explore checkout-web --json` reported
+    // `parses: true` and went on to describe every edge). `core/pack/living.ts`
+    // named this module as the last reader that disagreed. Whichever answer is
+    // right, an agent handed both has no way to tell — and the renderer's answer
+    // is the project's.
+    //
+    // `present` stays a fact about the FILE, because that file is the WRITE target:
+    // `loam new`'s scaffold and every brief ask for edits to
+    // `architecture/landscape.likec4` by name, and "the project is empty" is not
+    // the same instruction as "there is no map to edit".
+    const present = existsSync(landscapePath(docsDir));
+    const land = present ? await context.architecture(docsDir) : null;
+    const parses = land !== null && land.errors.length === 0;
+    const elements = parses ? land.elements : [];
+    const relationships = parses ? land.relationships : [];
+    // One resolver for the whole scan, built with the real service ids so an edge
+    // drawn into a modelled container (`paymentService.api`) counts for the
+    // service that owns it — the same resolution `list`, `show` and `validate`
+    // use, so no two commands can disagree about who calls whom.
+    const svcOf = serviceResolver(elements, known);
+    // Operation seeds resolve through the living contracts, not the map: the map
+    // says who CALLS an operation, and the question here is who DEFINES it.
+    const opSeeds = [];
+    const unresolvedOperations = [];
+    for (const op of req.operations) {
+        const owner = await operationOwner(entries, op, context);
+        if (owner === null)
+            unresolvedOperations.push(op);
+        else
+            opSeeds.push(owner);
+    }
+    // Capability seeds resolve through the vocabulary and the fleet rollup —
+    // one rollup pass for ALL requested ids, through this exploration's shared
+    // context cache, never a fresh walk per capability. A realizing service is
+    // by construction an enumerated one, so every seed it adds is `known`.
+    //
+    // And through the fleet's USE CASES, which answer the same question off a
+    // different document. The rollup finds services whose living requirements
+    // carry a `Capability:` line; a `dynamic view` tagged `#cap-<slug>` finds the
+    // services the flow actually runs through — including ones whose spec.md has
+    // never named the capability, which on a brownfield fleet is most of them.
+    // The two are unioned rather than ranked because neither is a subset of the
+    // other: a service can realize a capability without appearing in its drawn
+    // flow, and a flow can pass through a service that has written nothing down.
+    //
+    // The scan gates its own load — a fleet whose documents mention no reserved
+    // tag never starts LikeC4 for it — and this whole block is behind
+    // `--capability` being passed at all. What it is no longer behind is the
+    // project itself: the read above loads `architecture/` for every exploration,
+    // so a `--capability` run pays for a SECOND parse of the same documents
+    // (`readUseCases` takes a `DocsDir`, not this invocation's memo). Accepted
+    // rather than unnoticed: the alternative is a seam that hands the scan a
+    // pre-loaded project, which is a change to a module five callers share, and
+    // the cost lands only on the flag that already opts into the fleet rollup.
+    const capSeeds = [];
+    let unresolvedCaps = [];
+    if (req.capabilities.length > 0) {
+        const vocab = await context.capabilities(docsDir);
+        const rows = await capabilityRollup({ services: entries, vocab, read: (p) => context.readRequirements(p) });
+        const wanted = new Set(req.capabilities);
+        const realizing = new Set(rows.filter((r) => wanted.has(r.id)).flatMap((r) => r.services));
+        const scan = await readUseCases({ docsDir, known });
+        for (const id of servicesInFlowsClaiming(scan, req.capabilities))
+            realizing.add(id);
+        capSeeds.push(...entries.filter((e) => realizing.has(e.id)).map((e) => e.id));
+        // `unresolvedCapabilities` is unchanged on purpose: it grades the
+        // VOCABULARY — declared or not, realized by a living requirement or not —
+        // and a capability drawn in a flow but realized by nobody is still a
+        // capability nothing implements. Letting a tag silence that would hide the
+        // gap the field exists to name.
+        unresolvedCaps = unresolvedCapabilities(rows, req.capabilities);
+    }
+    const seeds = [...new Set([...req.services, ...opSeeds, ...capSeeds])];
+    const unknown = seeds
+        .filter((id) => !known.has(id))
+        .map((id) => ({ id, nearest: nearestIds(id, [...known]) }));
+    // The ring: one hop, both directions. A seed that is not modelled contributes
+    // nothing here and that is the honest answer — an invisible service has no
+    // neighbours anyone can derive, which is what `landscape.service-unmodelled`
+    // is about.
+    //
+    // The two directions are collected separately rather than written into one
+    // map as the loop goes, because a neighbour can be BOTH — it calls a seed and
+    // the seed calls it — and a single-map version answers whichever edge the
+    // parser happened to yield last. That is a field whose value depends on the
+    // order lines appear in a `.likec4` file, which is the kind of answer that
+    // reads as derived and is not.
+    const seedSet = new Set(seeds);
+    const callsSeed = new Set();
+    const calledBySeed = new Set();
+    for (const r of relationships) {
+        const from = svcOf(r.source);
+        const to = svcOf(r.target);
+        if (seedSet.has(from) && !seedSet.has(to))
+            calledBySeed.add(to);
+        if (seedSet.has(to) && !seedSet.has(from))
+            callsSeed.add(from);
+    }
+    // `calls-seed` wins the overlap, deterministically. Of the two directions it
+    // is the one that more often has to be touched: a consumer depends on the
+    // seed's contract, so a change to that contract is what breaks it, while a
+    // provider the seed merely calls is usually unaffected by the seed changing.
+    const ring = new Map([
+        ...[...calledBySeed].map((id) => [id, "called-by-seed"]),
+        ...[...callsSeed].map((id) => [id, "calls-seed"]),
+    ]);
+    const ordered = [
+        ...[...seeds].sort(compareIds).map((id) => ({ id, reason: "seed" })),
+        ...[...ring]
+            .sort(([a], [b]) => compareIds(a, b))
+            .map(([id, reason]) => ({ id, reason })),
+    ];
+    const services = [];
+    for (const { id, reason } of ordered) {
+        services.push(await describe({
+            id,
+            reason,
+            entry: byId.get(id),
+            relationships,
+            svcOf,
+            elements,
+            parses,
+            context,
+        }));
+    }
+    const covered = new Set(services.map((s) => s.id));
+    const features = await context.listFeatures(docsDir);
+    const overlaps = features
+        .map((f) => ({ feature: f.id, services: f.services.filter((s) => covered.has(s)) }))
+        .filter((o) => o.services.length > 0)
+        .sort((a, b) => compareIds(a.feature, b.feature));
+    return {
+        seeds,
+        unknown,
+        unresolvedOperations,
+        unresolvedCapabilities: unresolvedCaps,
+        services,
+        neighbours: [...ring.keys()].sort(compareIds),
+        overlaps,
+        landscape: {
+            present,
+            parses,
+            broken: land === null ? [] : brokenDocumentPaths(docsDir, land.errors),
+        },
+        scaffold: newCommand(featureId, seeds, known),
+    };
+}
+//# sourceMappingURL=explore.js.map

package/dist/core/explore/explore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../../src/core/explore/explore.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The blast radius of a change nobody has written down yet.\n *\n * Everything else in loam answers a question about documents that exist. This\n * module answers the one that comes BEFORE the first document: which services\n * does this feature actually touch? On a fleet of a hundred that call is the\n * hardest one in the cycle and the only one made with no tool in hand —\n * `loam new FEAT-101 --touches a --touches b` takes the answer as an argument\n * and scaffolds whatever it was told. A `--touches` list short by one service\n * is not caught by anything: the feature validates, archives, and ships with a\n * consumer nobody updated.\n *\n * So this states the work the same way `brief/brief.ts` does. It reads the fleet map\n * and the living contracts, reports the ring of services around the seeds, the\n * features already in flight over the same ground, and how far each service's\n * documentation has got — and stops. Which of those neighbours the feature\n * really touches is a judgement about intent, and loam does not make those.\n *\n * \"The fleet map\" here is the `architecture/` PROJECT — the landscape plus every\n * other `.likec4` under it, minus the generated views file — and not the\n * landscape FILE. See the read below for the disagreement that reading one file\n * caused.\n *\n * It is parsed ONCE for the whole exploration. Per-service reads of it exist\n * (`brief/landscape.ts`'s `landscapeContext`) and are correct for one service;\n * calling one of those per seed is how `validate --all` came to cost 13 seconds\n * on 120 services, and this command sits in front of authoring, where that is\n * the difference between a habit and a thing people skip.\n */\nimport { existsSync } from \"node:fs\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { brokenDocumentPaths, type Rel } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { type Maturity } from \"../vocabulary/maturity.js\";\nimport { capabilityRollup, unresolvedCapabilities } from \"../capabilities/rollup.js\";\nimport { compareIds, nearestIds, type ServiceEntry } from \"../repo/entries.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { readUseCases } from \"../usecases/fleet.js\";\nimport { servicesInFlowsClaiming } from \"../usecases/capability.js\";\nimport { describe, newCommand, operationOwner } from \"./describe.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/** One end of a call the fleet map already draws. */\nexport interface ExploreEdge {\n  /** The service at the other end. */\n  service: string;\n  /** The operationId the call uses, or null for an edge nobody tied to one. */\n  op: string | null;\n  title: string | null;\n}\n\n/**\n * Why a service is in the answer. Seeds were asked for; the rest were derived.\n *\n * A neighbour on both sides of a seed reports `calls-seed` — see the overlap\n * rule in `explore`. The field is a hint about where to look, not a complete\n * description of the edges; `inbound`/`outbound` are that.\n */\nexport type ExploreReason = \"seed\" | \"calls-seed\" | \"called-by-seed\";\n\nexport interface ExploreService {\n  id: string;\n  reason: ExploreReason;\n  /** Whether `services/<id>/` exists at all. */\n  known: boolean;\n  /**\n   * How far this service's documentation has got, or null when it does not\n   * exist yet. A `--touches` naming a service at `empty` or `partial` is a\n   * different job from one naming a vouched service, and the difference decides\n   * whether the feature starts with `loam adopt`.\n   */\n  maturity: Maturity | null;\n  /** What stands between it and `vouched` — `maturityGaps`, so it matches `list --needs-work`. */\n  missing: string[];\n  /** Whether anything in the fleet map resolves to it. */\n  modelled: boolean;\n  /** operationIds its living contract exposes today, `x-loam-remove` markers excluded. */\n  operations: string[];\n  /**\n   * Whether that contract could be read at all, beside the `error` the parser\n   * gave when it could not.\n   *\n   * It rides next to `operations` rather than inside it for the reason `delta`\n   * carries the same pair: an unreadable contract yields an EMPTY operation\n   * list, indistinguishable from a service with no endpoints — and this is the\n   * field the workflow tells an agent to read before deciding whether an\n   * operation it is about to add already exists. Answering `[]` over a YAML\n   * error is how a MODIFIED requirement gets authored as ADDED.\n   */\n  openapi: { unreadable: boolean; error?: string };\n  inbound: ExploreEdge[];\n  outbound: ExploreEdge[];\n}\n\n/** An active feature already working over ground the exploration covers. */\nexport interface ExploreOverlap {\n  feature: string;\n  /** The explored services it already carries a delta for. */\n  services: string[];\n}\n\nexport interface Exploration {\n  /** The seed ids, as asked for. */\n  seeds: string[];\n  /**\n   * Seeds that name no `services/<id>/`, each with the closest real ids. A seed\n   * may legitimately be a service the feature INTRODUCES, so this is reported\n   * rather than refused — but a typo produces exactly the same shape, and the\n   * near-miss list is what tells the two apart.\n   */\n  unknown: Array<{ id: string; nearest: string[] }>;\n  /** Operation seeds that resolved to no service's living contract. */\n  unresolvedOperations: string[];\n  /**\n   * Capability seeds that seeded nothing: not declared in\n   * architecture/capabilities.yaml (the file may not exist at all — explore\n   * refuses nothing, every miss is a field), or declared and realized by no\n   * living requirement. One list on purpose; splitting the two miss kinds\n   * waits for a consumer to ask.\n   */\n  unresolvedCapabilities: string[];\n  /** Seeds first, then the ring, each in id order. */\n  services: ExploreService[];\n  /** Ids the ring added that were not asked for — the candidates to weigh. */\n  neighbours: string[];\n  overlaps: ExploreOverlap[];\n  /**\n   * `broken` is the `architecture/` documents that failed, docs-relative POSIX,\n   * deduped and sorted — `[]` while `parses` is true. `parses` answers for the\n   * PROJECT, so the broken document is very often a SIBLING beside a landscape\n   * that reads perfectly, and naming the landscape file was a claim about bytes\n   * loam read fine (verification 2026-09-04). Spelled as `landscape.invalid`\n   * spells it (both through `c4/likec4.ts`'s `brokenDocumentPaths`), so the\n   * two surfaces name one file one way.\n   */\n  landscape: { present: boolean; parses: boolean; broken: string[] };\n  /**\n   * The literal `loam new` line the seeds imply — seeds only. The ring is\n   * deliberately NOT folded in: this module's whole claim is that it does not\n   * know which neighbours the feature touches, and a command line that quietly\n   * included them would make the guess on the reader's behalf and look derived\n   * while doing it.\n   *\n   * Named for what it does rather than `command`, which is the envelope's key\n   * for the command that RAN. The rename is not cosmetic: `emitJson` spreads\n   * the payload LAST, so a payload field called `command` would silently\n   * OVERRIDE the envelope's — `command` would come back as\n   * `\"loam new FEAT-000 …\"`, and every consumer branching on\n   * `command === \"explore\"` (the same key `status`, `doctor`, `dependencies`,\n   * `archive` and `unarchive` emit) would quietly stop matching, with tsc and\n   * the linter green throughout.\n   */\n  scaffold: string;\n}\n\nexport interface ExploreRequest {\n  docsDir: DocsDir;\n  /** Service ids to explore around. Checked at the command boundary. */\n  services: ServiceEntry[\"id\"][];\n  /** operationIds to explore around; each resolves to the service that defines it. */\n  operations: string[];\n  /** Declared capability ids to explore around; each seeds its realizing services. */\n  capabilities: string[];\n  /** Placeholder feature id for the suggested command line. */\n  featureId: string;\n  context?: FleetContext;\n}\n\n/**\n * Read the fleet around a proposed change. Reads only; writes nothing, and\n * refuses nothing — every miss is reported as a field.\n */\nexport async function explore(req: ExploreRequest): Promise<Exploration> {\n  const { docsDir, featureId } = req;\n  const context = req.context ?? new FleetContext();\n  const entries = await context.listServices(docsDir);\n  const byId = new Map<string, ServiceEntry>(entries.map((e) => [e.id, e]));\n  const known: ReadonlySet<string> = new Set(byId.keys());\n\n  // The `architecture/` PROJECT, never `architecture/landscape.likec4` alone.\n  // The map is a project — the landscape merged with every use case, palette and\n  // second `model { }` block beside it — and reading one file of it made this\n  // command answer differently from `loam adopt` and `loam context` about the\n  // same tree (reproduced: with a broken `architecture/palette.likec4` beside a\n  // landscape that parses, `context checkout-web --json` reported\n  // `landscape.parses: false` while `explore checkout-web --json` reported\n  // `parses: true` and went on to describe every edge). `core/pack/living.ts`\n  // named this module as the last reader that disagreed. Whichever answer is\n  // right, an agent handed both has no way to tell — and the renderer's answer\n  // is the project's.\n  //\n  // `present` stays a fact about the FILE, because that file is the WRITE target:\n  // `loam new`'s scaffold and every brief ask for edits to\n  // `architecture/landscape.likec4` by name, and \"the project is empty\" is not\n  // the same instruction as \"there is no map to edit\".\n  const present = existsSync(landscapePath(docsDir));\n  const land = present ? await context.architecture(docsDir) : null;\n  const parses = land !== null && land.errors.length === 0;\n  const elements = parses ? land.elements : [];\n  const relationships: Rel[] = parses ? land.relationships : [];\n  // One resolver for the whole scan, built with the real service ids so an edge\n  // drawn into a modelled container (`paymentService.api`) counts for the\n  // service that owns it — the same resolution `list`, `show` and `validate`\n  // use, so no two commands can disagree about who calls whom.\n  const svcOf = serviceResolver(elements, known);\n\n  // Operation seeds resolve through the living contracts, not the map: the map\n  // says who CALLS an operation, and the question here is who DEFINES it.\n  const opSeeds: ServiceEntry[\"id\"][] = [];\n  const unresolvedOperations: string[] = [];\n  for (const op of req.operations) {\n    const owner = await operationOwner(entries, op, context);\n    if (owner === null) unresolvedOperations.push(op);\n    else opSeeds.push(owner);\n  }\n\n  // Capability seeds resolve through the vocabulary and the fleet rollup —\n  // one rollup pass for ALL requested ids, through this exploration's shared\n  // context cache, never a fresh walk per capability. A realizing service is\n  // by construction an enumerated one, so every seed it adds is `known`.\n  //\n  // And through the fleet's USE CASES, which answer the same question off a\n  // different document. The rollup finds services whose living requirements\n  // carry a `Capability:` line; a `dynamic view` tagged `#cap-<slug>` finds the\n  // services the flow actually runs through — including ones whose spec.md has\n  // never named the capability, which on a brownfield fleet is most of them.\n  // The two are unioned rather than ranked because neither is a subset of the\n  // other: a service can realize a capability without appearing in its drawn\n  // flow, and a flow can pass through a service that has written nothing down.\n  //\n  // The scan gates its own load — a fleet whose documents mention no reserved\n  // tag never starts LikeC4 for it — and this whole block is behind\n  // `--capability` being passed at all. What it is no longer behind is the\n  // project itself: the read above loads `architecture/` for every exploration,\n  // so a `--capability` run pays for a SECOND parse of the same documents\n  // (`readUseCases` takes a `DocsDir`, not this invocation's memo). Accepted\n  // rather than unnoticed: the alternative is a seam that hands the scan a\n  // pre-loaded project, which is a change to a module five callers share, and\n  // the cost lands only on the flag that already opts into the fleet rollup.\n  const capSeeds: ServiceEntry[\"id\"][] = [];\n  let unresolvedCaps: string[] = [];\n  if (req.capabilities.length > 0) {\n    const vocab = await context.capabilities(docsDir);\n    const rows = await capabilityRollup({ services: entries, vocab, read: (p) => context.readRequirements(p) });\n    const wanted = new Set(req.capabilities);\n    const realizing = new Set(rows.filter((r) => wanted.has(r.id)).flatMap((r) => r.services));\n    const scan = await readUseCases({ docsDir, known });\n    for (const id of servicesInFlowsClaiming(scan, req.capabilities)) realizing.add(id);\n    capSeeds.push(...entries.filter((e) => realizing.has(e.id)).map((e) => e.id));\n    // `unresolvedCapabilities` is unchanged on purpose: it grades the\n    // VOCABULARY — declared or not, realized by a living requirement or not —\n    // and a capability drawn in a flow but realized by nobody is still a\n    // capability nothing implements. Letting a tag silence that would hide the\n    // gap the field exists to name.\n    unresolvedCaps = unresolvedCapabilities(rows, req.capabilities);\n  }\n\n  const seeds = [...new Set([...req.services, ...opSeeds, ...capSeeds])];\n  const unknown = seeds\n    .filter((id) => !known.has(id))\n    .map((id) => ({ id, nearest: nearestIds(id, [...known]) }));\n\n  // The ring: one hop, both directions. A seed that is not modelled contributes\n  // nothing here and that is the honest answer — an invisible service has no\n  // neighbours anyone can derive, which is what `landscape.service-unmodelled`\n  // is about.\n  //\n  // The two directions are collected separately rather than written into one\n  // map as the loop goes, because a neighbour can be BOTH — it calls a seed and\n  // the seed calls it — and a single-map version answers whichever edge the\n  // parser happened to yield last. That is a field whose value depends on the\n  // order lines appear in a `.likec4` file, which is the kind of answer that\n  // reads as derived and is not.\n  const seedSet = new Set<string>(seeds);\n  const callsSeed = new Set<string>();\n  const calledBySeed = new Set<string>();\n  for (const r of relationships) {\n    const from = svcOf(r.source);\n    const to = svcOf(r.target);\n    if (seedSet.has(from) && !seedSet.has(to)) calledBySeed.add(to);\n    if (seedSet.has(to) && !seedSet.has(from)) callsSeed.add(from);\n  }\n\n  // `calls-seed` wins the overlap, deterministically. Of the two directions it\n  // is the one that more often has to be touched: a consumer depends on the\n  // seed's contract, so a change to that contract is what breaks it, while a\n  // provider the seed merely calls is usually unaffected by the seed changing.\n  const ring = new Map<string, ExploreReason>([\n    ...[...calledBySeed].map((id) => [id, \"called-by-seed\" as const] as const),\n    ...[...callsSeed].map((id) => [id, \"calls-seed\" as const] as const),\n  ]);\n\n  const ordered: Array<{ id: string; reason: ExploreReason }> = [\n    ...[...seeds].sort(compareIds).map((id) => ({ id, reason: \"seed\" as const })),\n    ...[...ring]\n      .sort(([a], [b]) => compareIds(a, b))\n      .map(([id, reason]) => ({ id, reason })),\n  ];\n\n  const services: ExploreService[] = [];\n  for (const { id, reason } of ordered) {\n    services.push(\n      await describe({\n        id,\n        reason,\n        entry: byId.get(id),\n        relationships,\n        svcOf,\n        elements,\n        parses,\n        context,\n      }),\n    );\n  }\n\n  const covered = new Set(services.map((s) => s.id));\n  const features = await context.listFeatures(docsDir);\n  const overlaps: ExploreOverlap[] = features\n    .map((f) => ({ feature: f.id, services: f.services.filter((s) => covered.has(s)) }))\n    .filter((o) => o.services.length > 0)\n    .sort((a, b) => compareIds(a.feature, b.feature));\n\n  return {\n    seeds,\n    unknown,\n    unresolvedOperations,\n    unresolvedCapabilities: unresolvedCaps,\n    services,\n    neighbours: [...ring.keys()].sort(compareIds),\n    overlaps,\n    landscape: {\n      present,\n      parses,\n      broken: land === null ? [] : brokenDocumentPaths(docsDir, land.errors),\n    },\n    scaffold: newCommand(featureId, seeds, known),\n  };\n}\n"]}

package/dist/core/fleet-context.js

@@ -12,86 +12,33 @@
  * (which `readFile(path, "utf8")` silently turns into U+FFFD, so a UTF-16
  * spec.md parses as zero requirements and grades green), and git conflict
  * markers left in a living document (which parse as prose, and which the next
- * `loam archive` rewrites away). One place, so no reader can forget. The
- * decode itself lives in `document-bytes.ts`, a leaf: the parsers that read a
- * single file without an index owe the same rule, and must not have to import
- * this module — and the fleet it pulls in behind it — to obey it.
+ * `loam archive` rewrites away). One place, so no reader can forget. Both
+ * RULES live in leaves — the decode in `document-bytes.ts`, the marker scan
+ * and its findings in `conflict-markers.ts` — because the parsers and graders
+ * that touch a single file without an index owe the same rules, and must not
+ * have to import this module — and the fleet it pulls in behind it — to obey
+ * them.
  */
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { readAsyncapi } from "./asyncapi.js";
-import { decodeDocument } from "./document-bytes.js";
-import { loadFile } from "./likec4.js";
-import { readOpenapi, } from "./openapi.js";
-import { featureSpecServices, listFeatures, listServices, } from "./repo.js";
-import { parseRequirements } from "./spec.js";
-function key(path) {
-    return resolve(path);
-}
-/* ------------------------------------------------------------------ */
-/* What a read must never swallow                                      */
-/* ------------------------------------------------------------------ */
-/**
- * The three-way merge left its markers in the file — 1-based line numbers.
- *
- * The rule is `loam doctor`'s, verbatim, and it lives here now because doctor
- * checked exactly one file (`architecture/landscape.likec4`) from a command
- * that gates nothing. The same markers in a living `services/<svc>/spec.md`
- * parse as prose: `loam validate --all` reported `valid: true`, and the next
- * `loam archive` rewrote the requirements section and dropped the `=======`
- * line with it, turning a conflict anyone can see into a document nobody can
- * tell is wrong. For a shared docs repo where a fleet lands through PRs this is
- * the DEFAULT failure, not an edge.
- */
-const CONFLICT_MARKERS = ["<<<<<<<", "=======", ">>>>>>>"];
-export function conflictMarkerLines(source) {
-    const out = [];
-    source.split(/\r?\n/).forEach((line, i) => {
-        if (CONFLICT_MARKERS.some((m) => line.startsWith(m)))
-            out.push(i + 1);
-    });
-    return out;
-}
-/** One sentence for the breach, wherever it is found — doctor, validate, either axis. */
-function conflictMessage(label, lines) {
-    return (`${label} still contains git conflict markers (line${lines.length === 1 ? "" : "s"} ${lines.join(", ")}) — ` +
-        `both sides of somebody's merge are in the file, so nothing it says is anyone's text. ` +
-        `Resolve the conflict before anything else: loam rewrites this document on archive, and a rewrite deletes ` +
-        `whichever marker lines fall inside the section it owns — a visible conflict becomes a silently malformed file.`);
-}
-/**
- * The conflict-marker finding for a requirement document (living spec.md /
- * arch.spec.md, or a feature's delta of one). Null when the text is clean.
- *
- * An error because the document is not valid — nobody wrote what it now says —
- * and because the merge that would consume it is unsafe. It does not carry
- * `gates`: that field is coherence's (issue.ts), and the archive gate has to
- * ask this question itself.
- */
-export function documentConflictFinding(label, subject, text) {
-    const lines = conflictMarkerLines(text);
-    if (lines.length === 0)
-        return null;
-    return {
-        severity: "error",
-        code: "spec.merge-conflict",
-        subject,
-        message: conflictMessage(label, lines),
-    };
-}
-/** The same breach in the fleet map, where it costs every cross-service check at once. */
-export function landscapeConflictFinding(label, text) {
-    const lines = conflictMarkerLines(text);
-    if (lines.length === 0)
-        return null;
-    return {
-        severity: "error",
-        code: "landscape.merge-conflict",
-        message: conflictMessage(label, lines),
-    };
-}
+import { readAsyncapi } from "./asyncapi/read.js";
+import { readCapabilityVocabulary } from "./capabilities/capabilities.js";
+import { featureCapabilityDeltas } from "./capabilities/delta/tree.js";
+import { conflictMarkerLines } from "./conflict-markers.js";
+import { decodeDocument } from "./kernel/document-bytes.js";
+import { memo } from "./kernel/concurrency.js";
+import { loadFile } from "./c4/likec4.js";
+import { loadBatch } from "./c4/workspace.js";
+import { ServiceModels } from "./c4/prefetch/fleet.js";
+import { readOpenapi } from "./openapi/doc.js";
+import {} from "./repo/entries.js";
+import { featureSpecServices, listFeatures, listFleetTree, serviceEntries } from "./repo/repo.js";
+import { parseRequirements } from "./document/parse.js";
+import {} from "./document/spec.js";
+const key = (path) => resolve(path);
 /** One coherent filesystem snapshot for one command invocation. */
 export class FleetContext {
+    trees = new Map();
     services = new Map();
     features = new Map();
     featureServices = new Map();
@@ -99,7 +46,22 @@ export class FleetContext {
     requirements = new Map();
     openapis = new Map();
     asyncapis = new Map();
+    capabilityVocabularies = new Map();
+    featureCapabilities = new Map();
     likec4 = new Map();
+    /**
+     * The service-model axis's own memos, one object because the rules they
+     * encode are `c4/prefetch/fleet.ts`'s rather than this class's. It counts
+     * through this instance's counter, so `stats()` stays the one place a caller
+     * reads what an invocation cost.
+     */
+    models = new ServiceModels({
+        onProjectLoad: () => {
+            this.counts.projectLoads += 1;
+        },
+        known: async (docsDir) => new Set((await this.listServices(docsDir)).map((s) => s.id)),
+        standalone: (path) => this.loadLikeC4(path),
+    });
     counts = {
         serviceEnumerations: 0,
         featureEnumerations: 0,
@@ -108,65 +70,65 @@ export class FleetContext {
         requirementParses: 0,
         openapiParses: 0,
         asyncapiParses: 0,
+        capabilityParses: 0,
+        featureCapabilityWalks: 0,
         likec4Loads: 0,
+        projectLoads: 0,
     };
     /** A copy suitable for diagnostics/tests; callers cannot mutate the counters. */
     stats() {
         return { ...this.counts };
     }
+    /**
+     * `memo`, counting the miss under `counter` — every read below is this one
+     * call. The count is taken when the load STARTS, inside the miss, so a
+     * second asker of an in-flight read is a hit and is never counted: the
+     * counters mean "work this invocation paid for", which is what the stats
+     * tests pin per axis.
+     */
+    counted(store, k, counter, make) {
+        return memo(store, k, () => {
+            this.counts[counter] += 1;
+            return make();
+        });
+    }
+    /**
+     * The classified `services/` tree — the ONE enumeration this invocation
+     * performs. `listServices` below derives its entries from this memo, so a
+     * command that asks for both the fleet and the tree's findings (`validate
+     * --all` does) still walks the directories exactly once. The counter keeps
+     * its historical meaning — walks of `services/` — it just counts the walk
+     * where the walk now happens.
+     */
+    fleetTree(docsDir) {
+        return this.counted(this.trees, key(docsDir), "serviceEnumerations", () => listFleetTree(docsDir));
+    }
     listServices(docsDir) {
-        const k = key(docsDir);
-        let pending = this.services.get(k);
-        if (pending === undefined) {
-            this.counts.serviceEnumerations += 1;
-            pending = listServices(docsDir);
-            this.services.set(k, pending);
-        }
-        return pending;
+        return memo(this.services, key(docsDir), () => this.fleetTree(docsDir).then(serviceEntries));
     }
     listFeatures(docsDir, opts = {}) {
         const k = `${key(docsDir)}\0${opts.includeArchived === true ? "all" : "active"}`;
-        let pending = this.features.get(k);
-        if (pending === undefined) {
-            this.counts.featureEnumerations += 1;
-            pending = listFeatures(docsDir, opts).then((entries) => {
-                // listFeatures has already enumerated every feature's specs/ directory;
-                // seed the narrower lookup so validation/coherence do not read it again.
-                for (const entry of entries) {
-                    const featureKey = key(entry.dir);
-                    if (!this.featureServices.has(featureKey)) {
-                        this.featureServices.set(featureKey, Promise.resolve(entry.services));
-                    }
+        return this.counted(this.features, k, "featureEnumerations", () => listFeatures(docsDir, opts).then((entries) => {
+            // listFeatures has already enumerated every feature's specs/ directory;
+            // seed the narrower lookup so validation/coherence do not read it again.
+            for (const entry of entries) {
+                const featureKey = key(entry.dir);
+                if (!this.featureServices.has(featureKey)) {
+                    this.featureServices.set(featureKey, Promise.resolve(entry.services));
                 }
-                return entries;
-            });
-            this.features.set(k, pending);
-        }
-        return pending;
+            }
+            return entries;
+        }));
     }
     featureSpecServices(featureDir) {
-        const k = key(featureDir);
-        let pending = this.featureServices.get(k);
-        if (pending === undefined) {
-            this.counts.featureServiceEnumerations += 1;
-            pending = featureSpecServices(featureDir);
-            this.featureServices.set(k, pending);
-        }
-        return pending;
+        return this.counted(this.featureServices, key(featureDir), "featureServiceEnumerations", () => featureSpecServices(featureDir));
     }
     /**
      * A markdown artifact as text. Bytes in, decoded once, and refused rather
      * than degraded when they are not UTF-8 — see NotUtf8DocumentError.
      */
     readText(path) {
-        const k = key(path);
-        let pending = this.texts.get(k);
-        if (pending === undefined) {
-            this.counts.textReads += 1;
-            pending = readFile(path).then((bytes) => decodeDocument(bytes, path));
-            this.texts.set(k, pending);
-        }
-        return pending;
+        return this.counted(this.texts, key(path), "textReads", () => readFile(path).then((bytes) => decodeDocument(bytes, path)));
     }
     /**
      * Git conflict markers in an already-read document, by line. Free for any
@@ -178,34 +140,37 @@ export class FleetContext {
         return conflictMarkerLines(await this.readText(path));
     }
     readRequirements(path) {
-        const k = key(path);
-        let pending = this.requirements.get(k);
-        if (pending === undefined) {
-            this.counts.requirementParses += 1;
-            pending = this.readText(path).then(parseRequirements);
-            this.requirements.set(k, pending);
-        }
-        return pending;
+        return this.counted(this.requirements, key(path), "requirementParses", () => this.readText(path).then(parseRequirements));
     }
     readOpenapi(path) {
-        const k = key(path);
-        let pending = this.openapis.get(k);
-        if (pending === undefined) {
-            this.counts.openapiParses += 1;
-            pending = readOpenapi(path);
-            this.openapis.set(k, pending);
-        }
-        return pending;
+        return this.counted(this.openapis, key(path), "openapiParses", () => readOpenapi(path));
     }
     readAsyncapi(path) {
-        const k = key(path);
-        let pending = this.asyncapis.get(k);
-        if (pending === undefined) {
-            this.counts.asyncapiParses += 1;
-            pending = readAsyncapi(path);
-            this.asyncapis.set(k, pending);
-        }
-        return pending;
+        return this.counted(this.asyncapis, key(path), "asyncapiParses", () => readAsyncapi(path));
+    }
+    /**
+     * The capability vocabulary, read once per invocation. Direction rule,
+     * load-bearing: this file imports `capabilities/capabilities.js`, so nothing
+     * under src/core/capabilities/ may import this module back — that edge is a
+     * core-root↔capabilities package cycle `import/no-cycle` cannot see, which is
+     * why the functions there take plain data or a `read` function, never a FleetContext.
+     */
+    capabilities(docsDir) {
+        return this.counted(this.capabilityVocabularies, key(docsDir), "capabilityParses", () => readCapabilityVocabulary(docsDir));
+    }
+    /**
+     * One feature's `capabilities/` delta tree, walked once per invocation. Two
+     * readers ask for it in the same run — the delta-shape walk
+     * (`core/delta/delta.ts`) and the capability overlay
+     * (`core/coherence/declared.ts`) — and without the memo a feature carrying
+     * three capability deltas paid the readdirs twice.
+     *
+     * The direction rule stated on `capabilities()` above applies verbatim: the
+     * function this stands in front of takes a plain `FeatureDir`, never a
+     * FleetContext, so `src/core/capabilities/` never imports this module back.
+     */
+    featureCapabilityDeltas(featureDir) {
+        return this.counted(this.featureCapabilities, key(featureDir), "featureCapabilityWalks", () => featureCapabilityDeltas(featureDir));
     }
     async operations(path) {
         return (await this.readOpenapi(path)).ops;
@@ -220,19 +185,82 @@ export class FleetContext {
      * interleaved removals with upserts, so a relocated operation answered
      * "defined" through `archive` (no context) and "gone" through `validate` and
      * `status` (context), or the reverse, depending on the order the feature's
-     * YAML happened to spell the two slots in. `core/openapi.ts` owns the rule and
+     * YAML happened to spell the two slots in. `core/openapi/doc.ts` owns the rule and
      * threads a context through the reads underneath it, which is the only part
      * this class was ever needed for.
      */
     loadLikeC4(path) {
-        const k = key(path);
-        let pending = this.likec4.get(k);
-        if (pending === undefined) {
+        return this.counted(this.likec4, key(path), "likec4Loads", () => loadFile(path));
+    }
+    /**
+     * Parse many `.likec4` documents through ONE shared workspace (`loadBatch`)
+     * and seed the memo above, so every later `loadLikeC4` in this invocation is
+     * a hit. Purely an accelerator: the cache is still this instance's — one
+     * invocation, one snapshot, no module state — and the counter still means
+     * "documents parsed via LikeC4", incremented once per batch-parsed document.
+     *
+     * The failure story is the contract here. A batch-INFRASTRUCTURE failure —
+     * a sandboxed runner denying tmpdir writes is the environment class ROADMAP
+     * documents — degrades to today's per-path loads by seeding nothing: never
+     * an error, and never fewer findings, only the old speed. A path the batch
+     * could not stage (missing, unreadable) is simply absent from the result, so
+     * the later `loadLikeC4` reproduces today's per-path error exactly. And
+     * fewer than two misses returns without a workspace at all: one document
+     * gains nothing from batch isolation it already has.
+     */
+    async prefetchLikeC4(paths) {
+        const missing = [...new Set(paths.map(key))].filter((k) => !this.likec4.has(k));
+        if (missing.length < 2)
+            return;
+        let docs;
+        try {
+            docs = await loadBatch(missing);
+        }
+        catch {
+            return;
+        }
+        for (const [k, doc] of docs) {
+            // Keyed by the same `key()` as loadLikeC4 — loadBatch resolves paths the
+            // identical way, and `missing` was already resolved, so this holds by
+            // construction; the has() guard keeps a concurrent load's promise
+            // authoritative rather than double-counting the parse.
+            if (this.likec4.has(k))
+                continue;
             this.counts.likec4Loads += 1;
-            pending = loadFile(path);
-            this.likec4.set(k, pending);
+            this.likec4.set(k, Promise.resolve(doc));
         }
-        return pending;
+    }
+    /** The fleet map as the PROJECT it is — landscape plus use cases, minus the generated views file. */
+    architecture(docsDir) {
+        return this.models.architecture(docsDir);
+    }
+    /**
+     * Which shape each of these models has, keyed by resolved path — one read of
+     * each file's bytes per invocation. Ask over the FULL enumeration, never a
+     * narrowed run's subset: shapes decide which directories are owed a
+     * per-service `likec4.config.json`, and a partial map answers "not
+     * standalone" for every service outside it.
+     */
+    modelShapes(paths) {
+        return this.models.shapes(paths);
+    }
+    /**
+     * A service's C4 model, read the way its own SHAPE demands — the one entry
+     * point for every reader of `model.likec4`, standalone or extending
+     * (`c4/service-model/load.ts` states the four arms and why each exists).
+     */
+    serviceModel(docsDir, paths) {
+        return this.models.model(docsDir, paths);
+    }
+    /**
+     * Every service's model prepared in two workspaces whatever the fleet's mix:
+     * the extending ones as one project each in one of them, the standalone ones
+     * through the document batch above. An accelerator with `prefetchLikeC4`'s
+     * failure story exactly — a batch that could not be created seeds nothing, so
+     * findings never change because of a tmpdir, only the speed does.
+     */
+    async prefetchServiceModels(docsDir, paths) {
+        await this.prefetchLikeC4(await this.models.prefetch(docsDir, paths));
     }
 }
 //# sourceMappingURL=fleet-context.js.map