@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/core/fleet-context.js

@@ -26,8 +26,10 @@ 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";
@@ -47,6 +49,19 @@ export class FleetContext {
     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,
@@ -58,11 +73,25 @@ export class FleetContext {
         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
@@ -72,67 +101,34 @@ export class FleetContext {
      * where the walk now happens.
      */
     fleetTree(docsDir) {
-        const k = key(docsDir);
-        let pending = this.trees.get(k);
-        if (pending === undefined) {
-            this.counts.serviceEnumerations += 1;
-            pending = listFleetTree(docsDir);
-            this.trees.set(k, pending);
-        }
-        return pending;
+        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) {
-            pending = this.fleetTree(docsDir).then(serviceEntries);
-            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
@@ -144,34 +140,13 @@ 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,
@@ -181,14 +156,7 @@ export class FleetContext {
      * why the functions there take plain data or a `read` function, never a FleetContext.
      */
     capabilities(docsDir) {
-        const k = key(docsDir);
-        let pending = this.capabilityVocabularies.get(k);
-        if (pending === undefined) {
-            this.counts.capabilityParses += 1;
-            pending = readCapabilityVocabulary(docsDir);
-            this.capabilityVocabularies.set(k, pending);
-        }
-        return pending;
+        return this.counted(this.capabilityVocabularies, key(docsDir), "capabilityParses", () => readCapabilityVocabulary(docsDir));
     }
     /**
      * One feature's `capabilities/` delta tree, walked once per invocation. Two
@@ -202,14 +170,7 @@ export class FleetContext {
      * FleetContext, so `src/core/capabilities/` never imports this module back.
      */
     featureCapabilityDeltas(featureDir) {
-        const k = key(featureDir);
-        let pending = this.featureCapabilities.get(k);
-        if (pending === undefined) {
-            this.counts.featureCapabilityWalks += 1;
-            pending = featureCapabilityDeltas(featureDir);
-            this.featureCapabilities.set(k, pending);
-        }
-        return pending;
+        return this.counted(this.featureCapabilities, key(featureDir), "featureCapabilityWalks", () => featureCapabilityDeltas(featureDir));
     }
     async operations(path) {
         return (await this.readOpenapi(path)).ops;
@@ -229,14 +190,7 @@ export class FleetContext {
      * this class was ever needed for.
      */
     loadLikeC4(path) {
-        const k = key(path);
-        let pending = this.likec4.get(k);
-        if (pending === undefined) {
-            this.counts.likec4Loads += 1;
-            pending = loadFile(path);
-            this.likec4.set(k, pending);
-        }
-        return pending;
+        return this.counted(this.likec4, key(path), "likec4Loads", () => loadFile(path));
     }
     /**
      * Parse many `.likec4` documents through ONE shared workspace (`loadBatch`)
@@ -276,5 +230,37 @@ export class FleetContext {
             this.likec4.set(k, Promise.resolve(doc));
         }
     }
+    /** 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

package/dist/core/fleet-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"fleet-context.js","sourceRoot":"","sources":["../../src/core/fleet-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Request-scoped read index for commands that walk a whole loam repository.\n *\n * The filesystem remains the source of truth.  This class deliberately has no\n * singleton/global instance: a command creates one after loading loam.json and\n * drops it when that invocation finishes.  Within that lifetime identical\n * reads share their in-flight Promise, which removes both duplicate I/O and\n * duplicate parsing without making a later CLI invocation observe stale data.\n *\n * Because every markdown artifact is read HERE, this is also where the two\n * failures a read must never swallow are answered: bytes that are not UTF-8\n * (which `readFile(path, \"utf8\")` silently turns into U+FFFD, so a UTF-16\n * spec.md parses as zero requirements and grades green), and git conflict\n * markers left in a living document (which parse as prose, and which the next\n * `loam archive` rewrites away). One place, so no reader can forget. Both\n * RULES live in leaves — the decode in `document-bytes.ts`, the marker scan\n * and its findings in `conflict-markers.ts` — because the parsers and graders\n * that touch a single file without an index owe the same rules, and must not\n * have to import this module — and the fleet it pulls in behind it — to obey\n * them.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { readAsyncapi } from \"./asyncapi/read.js\";\nimport type { AsyncapiDoc } from \"./asyncapi/model.js\";\nimport { readCapabilityVocabulary, type CapabilityVocabulary } from \"./capabilities/capabilities.js\";\nimport { featureCapabilityDeltas } from \"./capabilities/delta/tree.js\";\nimport type { CapabilityTree } from \"./capabilities/tree.js\";\nimport { conflictMarkerLines } from \"./conflict-markers.js\";\nimport { decodeDocument } from \"./kernel/document-bytes.js\";\nimport { loadFile, type LoadedDoc } from \"./c4/likec4.js\";\nimport { loadBatch } from \"./c4/workspace.js\";\nimport { readOpenapi, type OpenapiDoc, type Operation } from \"./openapi/doc.js\";\nimport type { RawServiceId } from \"./kernel/ids/service.js\";\nimport { type FeatureEntry, type ServiceEntry } from \"./repo/entries.js\";\nimport { featureSpecServices, listFeatures, listFleetTree, serviceEntries } from \"./repo/repo.js\";\nimport type { FleetTree } from \"./repo/tree/walk.js\";\nimport { parseRequirements } from \"./document/parse.js\";\nimport { type Requirement } from \"./document/spec.js\";\nimport type { DocsDir, FeatureDir } from \"./kernel/ids/dirs.js\";\n\nexport interface FleetContextStats {\n  serviceEnumerations: number;\n  featureEnumerations: number;\n  featureServiceEnumerations: number;\n  textReads: number;\n  requirementParses: number;\n  openapiParses: number;\n  /**\n   * Reads of a service's `asyncapi.yaml`. Counted separately because this axis\n   * is the one that makes a per-service run read the whole fleet: \"does anybody\n   * publish this message\" has no local answer, so `spine.message-unproduced`\n   * walks every service's contract. The memo is what keeps that one walk per\n   * command instead of one per consuming edge.\n   */\n  asyncapiParses: number;\n  /**\n   * Reads of the capability vocabulary — `architecture/capabilities.yaml` AND\n   * the `capabilities/` walk, which are one vocabulary and so one read. One per\n   * invocation is the capability axis's exit criterion, and this counter is how\n   * a test pins it. (Permissions predates the memo and re-parses per service —\n   * do not copy that.)\n   */\n  capabilityParses: number;\n  /**\n   * Walks of ONE feature's `capabilities/` delta tree. Counted apart from\n   * `capabilityParses` because it answers a different question about a\n   * different directory, and because a fleet that has not adopted the business\n   * axis must be able to prove it pays nothing: every feature's walk is a\n   * single `existsSync` that finds no directory, so this counter rises while\n   * `textReads` and `requirementParses` do not.\n   */\n  featureCapabilityWalks: number;\n  likec4Loads: number;\n}\n\nconst key = (path: string): string => resolve(path);\n\n/** One coherent filesystem snapshot for one command invocation. */\nexport class FleetContext {\n  private readonly trees = new Map<string, Promise<FleetTree>>();\n  private readonly services = new Map<string, Promise<ServiceEntry[]>>();\n  private readonly features = new Map<string, Promise<FeatureEntry[]>>();\n  private readonly featureServices = new Map<string, Promise<RawServiceId[]>>();\n  private readonly texts = new Map<string, Promise<string>>();\n  private readonly requirements = new Map<string, Promise<Requirement[]>>();\n  private readonly openapis = new Map<string, Promise<OpenapiDoc>>();\n  private readonly asyncapis = new Map<string, Promise<AsyncapiDoc>>();\n  private readonly capabilityVocabularies = new Map<string, Promise<CapabilityVocabulary>>();\n  private readonly featureCapabilities = new Map<string, Promise<CapabilityTree>>();\n  private readonly likec4 = new Map<string, Promise<LoadedDoc>>();\n\n  private readonly counts: FleetContextStats = {\n    serviceEnumerations: 0,\n    featureEnumerations: 0,\n    featureServiceEnumerations: 0,\n    textReads: 0,\n    requirementParses: 0,\n    openapiParses: 0,\n    asyncapiParses: 0,\n    capabilityParses: 0,\n    featureCapabilityWalks: 0,\n    likec4Loads: 0,\n  };\n\n  /** A copy suitable for diagnostics/tests; callers cannot mutate the counters. */\n  stats(): Readonly<FleetContextStats> {\n    return { ...this.counts };\n  }\n\n  /**\n   * The classified `services/` tree — the ONE enumeration this invocation\n   * performs. `listServices` below derives its entries from this memo, so a\n   * command that asks for both the fleet and the tree's findings (`validate\n   * --all` does) still walks the directories exactly once. The counter keeps\n   * its historical meaning — walks of `services/` — it just counts the walk\n   * where the walk now happens.\n   */\n  fleetTree(docsDir: DocsDir): Promise<FleetTree> {\n    const k = key(docsDir);\n    let pending = this.trees.get(k);\n    if (pending === undefined) {\n      this.counts.serviceEnumerations += 1;\n      pending = listFleetTree(docsDir);\n      this.trees.set(k, pending);\n    }\n    return pending;\n  }\n\n  listServices(docsDir: DocsDir): Promise<ServiceEntry[]> {\n    const k = key(docsDir);\n    let pending = this.services.get(k);\n    if (pending === undefined) {\n      pending = this.fleetTree(docsDir).then(serviceEntries);\n      this.services.set(k, pending);\n    }\n    return pending;\n  }\n\n  listFeatures(docsDir: DocsDir, opts: { includeArchived?: boolean } = {}): Promise<FeatureEntry[]> {\n    const k = `${key(docsDir)}\\0${opts.includeArchived === true ? \"all\" : \"active\"}`;\n    let pending = this.features.get(k);\n    if (pending === undefined) {\n      this.counts.featureEnumerations += 1;\n      pending = listFeatures(docsDir, opts).then((entries) => {\n        // listFeatures has already enumerated every feature's specs/ directory;\n        // seed the narrower lookup so validation/coherence do not read it again.\n        for (const entry of entries) {\n          const featureKey = key(entry.dir);\n          if (!this.featureServices.has(featureKey)) {\n            this.featureServices.set(featureKey, Promise.resolve(entry.services));\n          }\n        }\n        return entries;\n      });\n      this.features.set(k, pending);\n    }\n    return pending;\n  }\n\n  featureSpecServices(featureDir: FeatureDir): Promise<RawServiceId[]> {\n    const k = key(featureDir);\n    let pending = this.featureServices.get(k);\n    if (pending === undefined) {\n      this.counts.featureServiceEnumerations += 1;\n      pending = featureSpecServices(featureDir);\n      this.featureServices.set(k, pending);\n    }\n    return pending;\n  }\n\n  /**\n   * A markdown artifact as text. Bytes in, decoded once, and refused rather\n   * than degraded when they are not UTF-8 — see NotUtf8DocumentError.\n   */\n  readText(path: string): Promise<string> {\n    const k = key(path);\n    let pending = this.texts.get(k);\n    if (pending === undefined) {\n      this.counts.textReads += 1;\n      pending = readFile(path).then((bytes) => decodeDocument(bytes, path));\n      this.texts.set(k, pending);\n    }\n    return pending;\n  }\n\n  /**\n   * Git conflict markers in an already-read document, by line. Free for any\n   * caller that was going to read the file anyway — which is every caller,\n   * which is the point: the marker check used to cost a whole extra read of one\n   * hand-picked file, so it was done for one hand-picked file.\n   */\n  async conflictMarkers(path: string): Promise<number[]> {\n    return conflictMarkerLines(await this.readText(path));\n  }\n\n  readRequirements(path: string): Promise<Requirement[]> {\n    const k = key(path);\n    let pending = this.requirements.get(k);\n    if (pending === undefined) {\n      this.counts.requirementParses += 1;\n      pending = this.readText(path).then(parseRequirements);\n      this.requirements.set(k, pending);\n    }\n    return pending;\n  }\n\n  readOpenapi(path: string): Promise<OpenapiDoc> {\n    const k = key(path);\n    let pending = this.openapis.get(k);\n    if (pending === undefined) {\n      this.counts.openapiParses += 1;\n      pending = readOpenapi(path);\n      this.openapis.set(k, pending);\n    }\n    return pending;\n  }\n\n  readAsyncapi(path: string): Promise<AsyncapiDoc> {\n    const k = key(path);\n    let pending = this.asyncapis.get(k);\n    if (pending === undefined) {\n      this.counts.asyncapiParses += 1;\n      pending = readAsyncapi(path);\n      this.asyncapis.set(k, pending);\n    }\n    return pending;\n  }\n\n  /**\n   * The capability vocabulary, read once per invocation. Direction rule,\n   * load-bearing: this file imports `capabilities/capabilities.js`, so nothing\n   * under src/core/capabilities/ may import this module back — that edge is a\n   * core-root↔capabilities package cycle `import/no-cycle` cannot see, which is\n   * why the functions there take plain data or a `read` function, never a FleetContext.\n   */\n  capabilities(docsDir: DocsDir): Promise<CapabilityVocabulary> {\n    const k = key(docsDir);\n    let pending = this.capabilityVocabularies.get(k);\n    if (pending === undefined) {\n      this.counts.capabilityParses += 1;\n      pending = readCapabilityVocabulary(docsDir);\n      this.capabilityVocabularies.set(k, pending);\n    }\n    return pending;\n  }\n\n  /**\n   * One feature's `capabilities/` delta tree, walked once per invocation. Two\n   * readers ask for it in the same run — the delta-shape walk\n   * (`core/delta/delta.ts`) and the capability overlay\n   * (`core/coherence/declared.ts`) — and without the memo a feature carrying\n   * three capability deltas paid the readdirs twice.\n   *\n   * The direction rule stated on `capabilities()` above applies verbatim: the\n   * function this stands in front of takes a plain `FeatureDir`, never a\n   * FleetContext, so `src/core/capabilities/` never imports this module back.\n   */\n  featureCapabilityDeltas(featureDir: FeatureDir): Promise<CapabilityTree> {\n    const k = key(featureDir);\n    let pending = this.featureCapabilities.get(k);\n    if (pending === undefined) {\n      this.counts.featureCapabilityWalks += 1;\n      pending = featureCapabilityDeltas(featureDir);\n      this.featureCapabilities.set(k, pending);\n    }\n    return pending;\n  }\n\n  async operations(path: string): Promise<Operation[]> {\n    return (await this.readOpenapi(path)).ops;\n  }\n\n  async operationIds(path: string): Promise<string[]> {\n    return (await this.readOpenapi(path)).ops.map((op) => op.id);\n  }\n\n  /*\n   * Deliberately no `serviceOperationIds` here. The living-plus-feature union is\n   * a RULE — every removal applied before any upsert — not a read, and a second\n   * copy of a rule is a second chance to spell it differently. This one did: it\n   * interleaved removals with upserts, so a relocated operation answered\n   * \"defined\" through `archive` (no context) and \"gone\" through `validate` and\n   * `status` (context), or the reverse, depending on the order the feature's\n   * YAML happened to spell the two slots in. `core/openapi/doc.ts` owns the rule and\n   * threads a context through the reads underneath it, which is the only part\n   * this class was ever needed for.\n   */\n\n  loadLikeC4(path: string): Promise<LoadedDoc> {\n    const k = key(path);\n    let pending = this.likec4.get(k);\n    if (pending === undefined) {\n      this.counts.likec4Loads += 1;\n      pending = loadFile(path);\n      this.likec4.set(k, pending);\n    }\n    return pending;\n  }\n\n  /**\n   * Parse many `.likec4` documents through ONE shared workspace (`loadBatch`)\n   * and seed the memo above, so every later `loadLikeC4` in this invocation is\n   * a hit. Purely an accelerator: the cache is still this instance's — one\n   * invocation, one snapshot, no module state — and the counter still means\n   * \"documents parsed via LikeC4\", incremented once per batch-parsed document.\n   *\n   * The failure story is the contract here. A batch-INFRASTRUCTURE failure —\n   * a sandboxed runner denying tmpdir writes is the environment class ROADMAP\n   * documents — degrades to today's per-path loads by seeding nothing: never\n   * an error, and never fewer findings, only the old speed. A path the batch\n   * could not stage (missing, unreadable) is simply absent from the result, so\n   * the later `loadLikeC4` reproduces today's per-path error exactly. And\n   * fewer than two misses returns without a workspace at all: one document\n   * gains nothing from batch isolation it already has.\n   */\n  async prefetchLikeC4(paths: string[]): Promise<void> {\n    const missing = [...new Set(paths.map(key))].filter((k) => !this.likec4.has(k));\n    if (missing.length < 2) return;\n    let docs: Map<string, LoadedDoc>;\n    try {\n      docs = await loadBatch(missing);\n    } catch {\n      return;\n    }\n    for (const [k, doc] of docs) {\n      // Keyed by the same `key()` as loadLikeC4 — loadBatch resolves paths the\n      // identical way, and `missing` was already resolved, so this holds by\n      // construction; the has() guard keeps a concurrent load's promise\n      // authoritative rather than double-counting the parse.\n      if (this.likec4.has(k)) continue;\n      this.counts.likec4Loads += 1;\n      this.likec4.set(k, Promise.resolve(doc));\n    }\n  }\n}\n"]}
+{"version":3,"file":"fleet-context.js","sourceRoot":"","sources":["../../src/core/fleet-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Request-scoped read index for commands that walk a whole loam repository.\n *\n * The filesystem remains the source of truth.  This class deliberately has no\n * singleton/global instance: a command creates one after loading loam.json and\n * drops it when that invocation finishes.  Within that lifetime identical\n * reads share their in-flight Promise, which removes both duplicate I/O and\n * duplicate parsing without making a later CLI invocation observe stale data.\n *\n * Because every markdown artifact is read HERE, this is also where the two\n * failures a read must never swallow are answered: bytes that are not UTF-8\n * (which `readFile(path, \"utf8\")` silently turns into U+FFFD, so a UTF-16\n * spec.md parses as zero requirements and grades green), and git conflict\n * markers left in a living document (which parse as prose, and which the next\n * `loam archive` rewrites away). One place, so no reader can forget. Both\n * RULES live in leaves — the decode in `document-bytes.ts`, the marker scan\n * and its findings in `conflict-markers.ts` — because the parsers and graders\n * that touch a single file without an index owe the same rules, and must not\n * have to import this module — and the fleet it pulls in behind it — to obey\n * them.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { readAsyncapi } from \"./asyncapi/read.js\";\nimport type { AsyncapiDoc } from \"./asyncapi/model.js\";\nimport { readCapabilityVocabulary, type CapabilityVocabulary } from \"./capabilities/capabilities.js\";\nimport { featureCapabilityDeltas } from \"./capabilities/delta/tree.js\";\nimport type { CapabilityTree } from \"./capabilities/tree.js\";\nimport { conflictMarkerLines } from \"./conflict-markers.js\";\nimport { decodeDocument } from \"./kernel/document-bytes.js\";\nimport { memo } from \"./kernel/concurrency.js\";\nimport { loadFile, type LoadedDoc } from \"./c4/likec4.js\";\nimport { loadBatch } from \"./c4/workspace.js\";\nimport { ServiceModels } from \"./c4/prefetch/fleet.js\";\nimport type { ServiceModel } from \"./c4/service-model/load.js\";\nimport type { ModelShape } from \"./c4/service-model/shape.js\";\nimport type { ServicePaths } from \"./repo/paths.js\";\nimport { readOpenapi, type OpenapiDoc, type Operation } from \"./openapi/doc.js\";\nimport type { RawServiceId } from \"./kernel/ids/service.js\";\nimport { type FeatureEntry, type ServiceEntry } from \"./repo/entries.js\";\nimport { featureSpecServices, listFeatures, listFleetTree, serviceEntries } from \"./repo/repo.js\";\nimport type { FleetTree } from \"./repo/tree/walk.js\";\nimport { parseRequirements } from \"./document/parse.js\";\nimport { type Requirement } from \"./document/spec.js\";\nimport type { DocsDir, FeatureDir } from \"./kernel/ids/dirs.js\";\n\nexport interface FleetContextStats {\n  serviceEnumerations: number;\n  featureEnumerations: number;\n  featureServiceEnumerations: number;\n  textReads: number;\n  requirementParses: number;\n  openapiParses: number;\n  /**\n   * Reads of a service's `asyncapi.yaml`. Counted separately because this axis\n   * is the one that makes a per-service run read the whole fleet: \"does anybody\n   * publish this message\" has no local answer, so `spine.message-unproduced`\n   * walks every service's contract. The memo is what keeps that one walk per\n   * command instead of one per consuming edge.\n   */\n  asyncapiParses: number;\n  /**\n   * Reads of the capability vocabulary — `architecture/capabilities.yaml` AND\n   * the `capabilities/` walk, which are one vocabulary and so one read. One per\n   * invocation is the capability axis's exit criterion, and this counter is how\n   * a test pins it. (Permissions predates the memo and re-parses per service —\n   * do not copy that.)\n   */\n  capabilityParses: number;\n  /**\n   * Walks of ONE feature's `capabilities/` delta tree. Counted apart from\n   * `capabilityParses` because it answers a different question about a\n   * different directory, and because a fleet that has not adopted the business\n   * axis must be able to prove it pays nothing: every feature's walk is a\n   * single `existsSync` that finds no directory, so this counter rises while\n   * `textReads` and `requirementParses` do not.\n   */\n  featureCapabilityWalks: number;\n  likec4Loads: number;\n  /**\n   * PER-SERVICE PROJECTS parsed — the map plus one extending model, staged\n   * together (`c4/service-model/`). Apart from `likec4Loads` because they are\n   * different units: that counter means documents parsed alone, and a fleet\n   * whose models all extend the map moves every unit to this one. One project\n   * per service is the axis's exit criterion, and this is how a test pins it.\n   */\n  projectLoads: number;\n}\n\nconst key = (path: string): string => resolve(path);\n\n/** One coherent filesystem snapshot for one command invocation. */\nexport class FleetContext {\n  private readonly trees = new Map<string, Promise<FleetTree>>();\n  private readonly services = new Map<string, Promise<ServiceEntry[]>>();\n  private readonly features = new Map<string, Promise<FeatureEntry[]>>();\n  private readonly featureServices = new Map<string, Promise<RawServiceId[]>>();\n  private readonly texts = new Map<string, Promise<string>>();\n  private readonly requirements = new Map<string, Promise<Requirement[]>>();\n  private readonly openapis = new Map<string, Promise<OpenapiDoc>>();\n  private readonly asyncapis = new Map<string, Promise<AsyncapiDoc>>();\n  private readonly capabilityVocabularies = new Map<string, Promise<CapabilityVocabulary>>();\n  private readonly featureCapabilities = new Map<string, Promise<CapabilityTree>>();\n  private readonly likec4 = new Map<string, Promise<LoadedDoc>>();\n  /**\n   * The service-model axis's own memos, one object because the rules they\n   * encode are `c4/prefetch/fleet.ts`'s rather than this class's. It counts\n   * through this instance's counter, so `stats()` stays the one place a caller\n   * reads what an invocation cost.\n   */\n  private readonly models = new ServiceModels({\n    onProjectLoad: () => {\n      this.counts.projectLoads += 1;\n    },\n    known: async (docsDir) => new Set((await this.listServices(docsDir)).map((s) => s.id)),\n    standalone: (path) => this.loadLikeC4(path),\n  });\n\n  private readonly counts: FleetContextStats = {\n    serviceEnumerations: 0,\n    featureEnumerations: 0,\n    featureServiceEnumerations: 0,\n    textReads: 0,\n    requirementParses: 0,\n    openapiParses: 0,\n    asyncapiParses: 0,\n    capabilityParses: 0,\n    featureCapabilityWalks: 0,\n    likec4Loads: 0,\n    projectLoads: 0,\n  };\n\n  /** A copy suitable for diagnostics/tests; callers cannot mutate the counters. */\n  stats(): Readonly<FleetContextStats> {\n    return { ...this.counts };\n  }\n\n  /**\n   * `memo`, counting the miss under `counter` — every read below is this one\n   * call. The count is taken when the load STARTS, inside the miss, so a\n   * second asker of an in-flight read is a hit and is never counted: the\n   * counters mean \"work this invocation paid for\", which is what the stats\n   * tests pin per axis.\n   */\n  private counted<T>(\n    store: Map<string, Promise<T>>,\n    k: string,\n    counter: keyof FleetContextStats,\n    make: () => Promise<T>,\n  ): Promise<T> {\n    return memo(store, k, () => {\n      this.counts[counter] += 1;\n      return make();\n    });\n  }\n\n  /**\n   * The classified `services/` tree — the ONE enumeration this invocation\n   * performs. `listServices` below derives its entries from this memo, so a\n   * command that asks for both the fleet and the tree's findings (`validate\n   * --all` does) still walks the directories exactly once. The counter keeps\n   * its historical meaning — walks of `services/` — it just counts the walk\n   * where the walk now happens.\n   */\n  fleetTree(docsDir: DocsDir): Promise<FleetTree> {\n    return this.counted(this.trees, key(docsDir), \"serviceEnumerations\", () => listFleetTree(docsDir));\n  }\n\n  listServices(docsDir: DocsDir): Promise<ServiceEntry[]> {\n    return memo(this.services, key(docsDir), () => this.fleetTree(docsDir).then(serviceEntries));\n  }\n\n  listFeatures(docsDir: DocsDir, opts: { includeArchived?: boolean } = {}): Promise<FeatureEntry[]> {\n    const k = `${key(docsDir)}\\0${opts.includeArchived === true ? \"all\" : \"active\"}`;\n    return this.counted(this.features, k, \"featureEnumerations\", () =>\n      listFeatures(docsDir, opts).then((entries) => {\n        // listFeatures has already enumerated every feature's specs/ directory;\n        // seed the narrower lookup so validation/coherence do not read it again.\n        for (const entry of entries) {\n          const featureKey = key(entry.dir);\n          if (!this.featureServices.has(featureKey)) {\n            this.featureServices.set(featureKey, Promise.resolve(entry.services));\n          }\n        }\n        return entries;\n      }),\n    );\n  }\n\n  featureSpecServices(featureDir: FeatureDir): Promise<RawServiceId[]> {\n    return this.counted(this.featureServices, key(featureDir), \"featureServiceEnumerations\", () =>\n      featureSpecServices(featureDir),\n    );\n  }\n\n  /**\n   * A markdown artifact as text. Bytes in, decoded once, and refused rather\n   * than degraded when they are not UTF-8 — see NotUtf8DocumentError.\n   */\n  readText(path: string): Promise<string> {\n    return this.counted(this.texts, key(path), \"textReads\", () =>\n      readFile(path).then((bytes) => decodeDocument(bytes, path)),\n    );\n  }\n\n  /**\n   * Git conflict markers in an already-read document, by line. Free for any\n   * caller that was going to read the file anyway — which is every caller,\n   * which is the point: the marker check used to cost a whole extra read of one\n   * hand-picked file, so it was done for one hand-picked file.\n   */\n  async conflictMarkers(path: string): Promise<number[]> {\n    return conflictMarkerLines(await this.readText(path));\n  }\n\n  readRequirements(path: string): Promise<Requirement[]> {\n    return this.counted(this.requirements, key(path), \"requirementParses\", () =>\n      this.readText(path).then(parseRequirements),\n    );\n  }\n\n  readOpenapi(path: string): Promise<OpenapiDoc> {\n    return this.counted(this.openapis, key(path), \"openapiParses\", () => readOpenapi(path));\n  }\n\n  readAsyncapi(path: string): Promise<AsyncapiDoc> {\n    return this.counted(this.asyncapis, key(path), \"asyncapiParses\", () => readAsyncapi(path));\n  }\n\n  /**\n   * The capability vocabulary, read once per invocation. Direction rule,\n   * load-bearing: this file imports `capabilities/capabilities.js`, so nothing\n   * under src/core/capabilities/ may import this module back — that edge is a\n   * core-root↔capabilities package cycle `import/no-cycle` cannot see, which is\n   * why the functions there take plain data or a `read` function, never a FleetContext.\n   */\n  capabilities(docsDir: DocsDir): Promise<CapabilityVocabulary> {\n    return this.counted(this.capabilityVocabularies, key(docsDir), \"capabilityParses\", () =>\n      readCapabilityVocabulary(docsDir),\n    );\n  }\n\n  /**\n   * One feature's `capabilities/` delta tree, walked once per invocation. Two\n   * readers ask for it in the same run — the delta-shape walk\n   * (`core/delta/delta.ts`) and the capability overlay\n   * (`core/coherence/declared.ts`) — and without the memo a feature carrying\n   * three capability deltas paid the readdirs twice.\n   *\n   * The direction rule stated on `capabilities()` above applies verbatim: the\n   * function this stands in front of takes a plain `FeatureDir`, never a\n   * FleetContext, so `src/core/capabilities/` never imports this module back.\n   */\n  featureCapabilityDeltas(featureDir: FeatureDir): Promise<CapabilityTree> {\n    return this.counted(this.featureCapabilities, key(featureDir), \"featureCapabilityWalks\", () =>\n      featureCapabilityDeltas(featureDir),\n    );\n  }\n\n  async operations(path: string): Promise<Operation[]> {\n    return (await this.readOpenapi(path)).ops;\n  }\n\n  async operationIds(path: string): Promise<string[]> {\n    return (await this.readOpenapi(path)).ops.map((op) => op.id);\n  }\n\n  /*\n   * Deliberately no `serviceOperationIds` here. The living-plus-feature union is\n   * a RULE — every removal applied before any upsert — not a read, and a second\n   * copy of a rule is a second chance to spell it differently. This one did: it\n   * interleaved removals with upserts, so a relocated operation answered\n   * \"defined\" through `archive` (no context) and \"gone\" through `validate` and\n   * `status` (context), or the reverse, depending on the order the feature's\n   * YAML happened to spell the two slots in. `core/openapi/doc.ts` owns the rule and\n   * threads a context through the reads underneath it, which is the only part\n   * this class was ever needed for.\n   */\n\n  loadLikeC4(path: string): Promise<LoadedDoc> {\n    return this.counted(this.likec4, key(path), \"likec4Loads\", () => loadFile(path));\n  }\n\n  /**\n   * Parse many `.likec4` documents through ONE shared workspace (`loadBatch`)\n   * and seed the memo above, so every later `loadLikeC4` in this invocation is\n   * a hit. Purely an accelerator: the cache is still this instance's — one\n   * invocation, one snapshot, no module state — and the counter still means\n   * \"documents parsed via LikeC4\", incremented once per batch-parsed document.\n   *\n   * The failure story is the contract here. A batch-INFRASTRUCTURE failure —\n   * a sandboxed runner denying tmpdir writes is the environment class ROADMAP\n   * documents — degrades to today's per-path loads by seeding nothing: never\n   * an error, and never fewer findings, only the old speed. A path the batch\n   * could not stage (missing, unreadable) is simply absent from the result, so\n   * the later `loadLikeC4` reproduces today's per-path error exactly. And\n   * fewer than two misses returns without a workspace at all: one document\n   * gains nothing from batch isolation it already has.\n   */\n  async prefetchLikeC4(paths: string[]): Promise<void> {\n    const missing = [...new Set(paths.map(key))].filter((k) => !this.likec4.has(k));\n    if (missing.length < 2) return;\n    let docs: Map<string, LoadedDoc>;\n    try {\n      docs = await loadBatch(missing);\n    } catch {\n      return;\n    }\n    for (const [k, doc] of docs) {\n      // Keyed by the same `key()` as loadLikeC4 — loadBatch resolves paths the\n      // identical way, and `missing` was already resolved, so this holds by\n      // construction; the has() guard keeps a concurrent load's promise\n      // authoritative rather than double-counting the parse.\n      if (this.likec4.has(k)) continue;\n      this.counts.likec4Loads += 1;\n      this.likec4.set(k, Promise.resolve(doc));\n    }\n  }\n\n  /** The fleet map as the PROJECT it is — landscape plus use cases, minus the generated views file. */\n  architecture(docsDir: DocsDir): Promise<LoadedDoc> {\n    return this.models.architecture(docsDir);\n  }\n\n  /**\n   * Which shape each of these models has, keyed by resolved path — one read of\n   * each file's bytes per invocation. Ask over the FULL enumeration, never a\n   * narrowed run's subset: shapes decide which directories are owed a\n   * per-service `likec4.config.json`, and a partial map answers \"not\n   * standalone\" for every service outside it.\n   */\n  modelShapes(paths: readonly string[]): Promise<Map<string, ModelShape>> {\n    return this.models.shapes(paths);\n  }\n\n  /**\n   * A service's C4 model, read the way its own SHAPE demands — the one entry\n   * point for every reader of `model.likec4`, standalone or extending\n   * (`c4/service-model/load.ts` states the four arms and why each exists).\n   */\n  serviceModel(docsDir: DocsDir, paths: ServicePaths): Promise<ServiceModel> {\n    return this.models.model(docsDir, paths);\n  }\n\n  /**\n   * Every service's model prepared in two workspaces whatever the fleet's mix:\n   * the extending ones as one project each in one of them, the standalone ones\n   * through the document batch above. An accelerator with `prefetchLikeC4`'s\n   * failure story exactly — a batch that could not be created seeds nothing, so\n   * findings never change because of a tmpdir, only the speed does.\n   */\n  async prefetchServiceModels(docsDir: DocsDir, paths: readonly ServicePaths[]): Promise<void> {\n    await this.prefetchLikeC4(await this.models.prefetch(docsDir, paths));\n  }\n}\n"]}

package/dist/core/gate/checks.js

@@ -10,7 +10,9 @@
  *                 plus the one integrity error that makes freshness
  *                 unjudgeable (frontmatter.malformed) and a refusing decode
  *                 of the spec bytes themselves
- *   verification  verificationState per active feature touching the service
+ *   verification  verificationState per feature touching the service — the
+ *                 active ones, plus those archived after `--since <ref>` when
+ *                 a pipeline names the docs commit it last deployed from
  *                 (its own module, `./verification.ts`)
  *   interrupted   the `.loam-commit` journal — the one repo state that poisons
  *                 every other answer above
@@ -38,7 +40,7 @@ export async function gateReport(req) {
     const scan = await partnerScan({ docsDir: req.docsDir, service: req.service, fleet: req.fleet });
     const [freshness, verification, interrupted] = await Promise.all([
         freshnessFindings(req, scan),
-        verificationCheck({ docsDir: req.docsDir, service: req.service, fleet: req.fleet }),
+        verificationCheck(req),
         interruptedCommitFinding(req.docsDir),
     ]);
     const checks = [
@@ -49,6 +51,7 @@ export async function gateReport(req) {
     ];
     return {
         service: req.service,
+        since: req.since === undefined ? null : { ref: req.since.ref, commit: req.since.commit },
         landscape: scan.landscape,
         partners: scan.partners,
         features: verification.features,
@@ -98,7 +101,7 @@ function partnersFindings(scan, service) {
             code: "gate.service-undocumented",
             subject: service,
             message: `${serviceTreePath(scan.targetEntry)}/ sits at '${target.maturity}' on the adoption ladder — below 'documented', the docs cannot say what its joins even are, so no recorded evidence can answer the deploy question. ` +
-                `Author the baseline (\`loam adopt --service ${service}\` briefs it); this check passes once the required artifact set exists.`,
+                `Author the baseline (\`loam adopt --service ${service}\` briefs it); this check passes once the required artifact set exists and its spec.md no longer says \`adoption: partial\`.`,
             details: target.gaps,
             text: { detailPrefix: "- " },
         });
@@ -111,7 +114,11 @@ function partnersFindings(scan, service) {
     for (const p of scan.partners) {
         // An `#external` partner is somebody else's system: its side of the join
         // is unrecorded ON PURPOSE, the same exemption the landscape census grants
-        // (`landscape.service-undocumented` skips #external too).
+        // (`landscape.service-undocumented` skips #external too). The fleet's own
+        // infrastructure — a `database`, `queue`, `topic`, `cache` or `bucket` — is
+        // not a partner at all and never reaches this loop: `./partners.ts` drops it
+        // from the SET, beside the actors, because the three remedies below are all
+        // false of a store the fleet runs.
         if (p.external)
             continue;
         if (p.maturity === null) {

package/dist/core/gate/checks.js.map

@@ -1 +1 @@
-{"version":3,"file":"checks.js","sourceRoot":"","sources":["../../../src/core/gate/checks.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The four checks behind `loam gate` — a can-i-deploy-shaped PURE QUERY over\n * evidence other commands already recorded. Nothing here executes anything,\n * writes anything, takes the docs lock, or re-derives a coherence plan: every\n * answer is either already on disk (verification.yaml, vouch stamps, the\n * commit journal) or a presence/landscape fact the enumeration carries.\n *\n *   partners      the landscape's direct joins, both ends graded on the ladder\n *   freshness     content.stale / sources.stale over the target and partners,\n *                 plus the one integrity error that makes freshness\n *                 unjudgeable (frontmatter.malformed) and a refusing decode\n *                 of the spec bytes themselves\n *   verification  verificationState per active feature touching the service\n *                 (its own module, `./verification.ts`)\n *   interrupted   the `.loam-commit` journal — the one repo state that poisons\n *                 every other answer above\n *\n * Every `gate.*` code is spelled as a literal `code:` property at its emit\n * site, never through a code-taking factory parameter — verifyStep\n * (core/status/verification.ts) records that test/codes-drift.test.ts's\n * collector is blind to the parameter form, and a refactor toward a factory\n * would silently undocument the family.\n */\nimport { existsSync } from \"node:fs\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport { serviceProvenance } from \"../provenance/findings.js\";\nimport { interruptedCommitFinding } from \"../staging/recovery/finding.js\";\nimport { servicePathsAt, SPEC_AXES, type ServicePaths } from \"../repo/paths.js\";\nimport { serviceTreePath } from \"../kernel/ids/dirs.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { RawServiceId } from \"../kernel/ids/service.js\";\nimport { atLeastDocumented, partnerScan, type PartnerScan } from \"./partners.js\";\nimport { verificationCheck } from \"./verification.js\";\nimport { unreadableSubject, type GateCheck, type GateReport } from \"./report.js\";\n\nexport interface GateRequest {\n  docsDir: DocsDir;\n  /** The service being deployed — a name the enumeration approved. */\n  service: RawServiceId;\n  /**\n   * The repository loam is standing in, passed ONLY when the gated service is\n   * this repo's own binding — validate's `repoOf` rule: `sources` are paths\n   * into a service's own repository, so `sources.stale` is honestly checkable\n   * only there, while `content.stale` needs nothing but the document.\n   */\n  repoDir?: string;\n  fleet: FleetContext;\n}\n\nexport async function gateReport(req: GateRequest): Promise<GateReport> {\n  // The scan first, alone: freshness walks the partner set it derives. The\n  // three remaining checks are independent of each other — different files,\n  // memoized reads — so they run concurrently; only the scan must be ordered.\n  const scan = await partnerScan({ docsDir: req.docsDir, service: req.service, fleet: req.fleet });\n  const [freshness, verification, interrupted] = await Promise.all([\n    freshnessFindings(req, scan),\n    verificationCheck({ docsDir: req.docsDir, service: req.service, fleet: req.fleet }),\n    interruptedCommitFinding(req.docsDir),\n  ]);\n  const checks: GateCheck[] = [\n    { check: \"partners\", findings: partnersFindings(scan, req.service) },\n    { check: \"freshness\", findings: freshness },\n    { check: \"verification\", findings: verification.findings },\n    { check: \"interrupted\", findings: interrupted === null ? [] : [interrupted] },\n  ];\n  return {\n    service: req.service,\n    landscape: scan.landscape,\n    partners: scan.partners,\n    features: verification.features,\n    checks,\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Check 1: partners                                                   */\n/* ------------------------------------------------------------------ */\n\nfunction partnersFindings(scan: PartnerScan, service: string): Finding[] {\n  const findings: Finding[] = [];\n  // \"Could not look\" must never read as \"no partners\" — the docsRepoReady\n  // doctrine one level down. `validate --all` owns the diagnosis of the\n  // landscape itself; this code only refuses the false silence. The two ways\n  // of not looking are graded apart, the way `landscape.missing` and\n  // `landscape.invalid` are: ABSENT is a warning — a repo before its first\n  // adopt legitimately has no map yet — but a map that EXISTS and cannot be\n  // parsed or read is an ERROR, because `validate --all` fails that repo\n  // (`landscape.invalid`) and a deploy gate that passed where the fleet gate\n  // fails would be the quieter of two contradictory verdicts.\n  if (scan.landscape === \"absent\") {\n    findings.push({\n      severity: \"warn\",\n      code: \"gate.partners-unknown\",\n      message: `architecture/landscape.likec4 does not exist, so the partner set for '${service}' could not be derived — an absent map means nobody could look, not that nothing joins this service. \\`loam validate --all\\` diagnoses the landscape itself.`,\n    });\n  } else if (scan.landscape === \"invalid\") {\n    findings.push({\n      severity: \"error\",\n      code: \"gate.partners-unknown\",\n      message:\n        `architecture/landscape.likec4 exists but cannot be used — ${scan.landscapeProblem ?? \"it did not parse\"} — so the partner set for '${service}' could not be derived. ` +\n        `A broken map means nobody could look, not that nothing joins this service, and \\`loam validate --all\\` fails this repo for the same file. Fix the landscape, then re-run.`,\n    });\n  }\n  // The rung depends on the landscape only through the api question (does\n  // anything call this service?). With no readable map that question is\n  // unanswerable, and the fail-closed grading — `landscapeEvidence`: no proof\n  // means an API is expected — would convict a worker or UI for a contract\n  // nobody may be owed. One unanswerable fact yields ONE finding (the\n  // landscape's own, above), so under an unreadable map this error fires only\n  // when the service is below `documented` REGARDLESS of the api question.\n  const target = scan.landscape === \"read\" ? scan.target : scan.targetWithoutApi;\n  if (!atLeastDocumented(target.maturity)) {\n    findings.push({\n      severity: \"error\",\n      code: \"gate.service-undocumented\",\n      subject: service,\n      message:\n        `${serviceTreePath(scan.targetEntry)}/ sits at '${target.maturity}' on the adoption ladder — below 'documented', the docs cannot say what its joins even are, so no recorded evidence can answer the deploy question. ` +\n        `Author the baseline (\\`loam adopt --service ${service}\\` briefs it); this check passes once the required artifact set exists.`,\n      details: target.gaps,\n      text: { detailPrefix: \"- \" },\n    });\n  }\n  // The partners that HAVE a directory, by id: their findings name it, and it\n  // is `services/<subsystem>/<id>/` for a filed one. The no-directory branch\n  // below keeps the bare `services/<id>/` spelling deliberately — there is no\n  // directory to name, and the unfiled form is what the fix would create.\n  const partnerPath = new Map(scan.partnerEntries.map((e) => [e.id as string, serviceTreePath(e)]));\n  for (const p of scan.partners) {\n    // An `#external` partner is somebody else's system: its side of the join\n    // is unrecorded ON PURPOSE, the same exemption the landscape census grants\n    // (`landscape.service-undocumented` skips #external too).\n    if (p.external) continue;\n    if (p.maturity === null) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gate.partner-undocumented\",\n        subject: p.service,\n        message:\n          `'${p.service}' joins '${service}' (${p.via.join(\", \")}) but has no services/${p.service}/ directory — its side of the join is unrecorded. ` +\n          `Adopt it, bind its landscape element to the right service with metadata { service '<id>' }, or tag it #external if it is not ours.`,\n        details: p.via,\n      });\n    } else if (!atLeastDocumented(p.maturity)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gate.partner-undocumented\",\n        subject: p.service,\n        message:\n          `${partnerPath.get(p.service) ?? `services/${p.service}`}/ sits at '${p.maturity}' — below 'documented' — while it joins '${service}' (${p.via.join(\", \")}): its side of the join is not fully recorded. \\`loam adopt --service ${p.service}\\` briefs what is missing.`,\n        details: p.via,\n      });\n    }\n  }\n  return findings;\n}\n\n/* ------------------------------------------------------------------ */\n/* Check 2: freshness                                                  */\n/* ------------------------------------------------------------------ */\n\n/**\n * `serviceProvenance` filtered to the two staleness codes plus the ONE\n * integrity error that makes freshness unjudgeable: `frontmatter.malformed`.\n * A header YAML refuses to parse cannot certify a `content_digest`, and\n * dropping that error read \"cannot judge\" as \"nothing stale\" — the exact\n * fail-open a deploy gate must not have. Everything else provenance grades\n * (missing owners, unstamped sources, absent frontmatter) is `validate`'s\n * report to make — a deploy gate that repeated it would drown the findings a\n * pipeline can actually act on at deploy time.\n */\nasync function freshnessFindings(req: GateRequest, scan: PartnerScan): Promise<Finding[]> {\n  const subjects: { id: RawServiceId; repoDir: string | undefined; paths: ServicePaths }[] = [\n    {\n      id: req.service,\n      repoDir: req.repoDir,\n      paths: await locateServicePaths(req.docsDir, req.service, req.fleet),\n    },\n    // Only the DOCUMENTED partners: a partner with no directory has nothing to\n    // grade, and already carries gate.partner-undocumented from check 1.\n    ...scan.partnerEntries.map((e) => ({\n      id: e.id,\n      repoDir: undefined,\n      paths: servicePathsAt(e.dir),\n    })),\n  ];\n  // Independent per-subject reads through the shared memo; inOrder keeps the\n  // findings in subject order (target first, partners sorted) so identical\n  // state yields identical bytes.\n  const graded = await inOrder(subjects, async (s) => {\n    try {\n      // The integrity gate serviceProvenance cannot give: its own reads decode\n      // with 'utf8', which silently turns UTF-16 bytes into replacement\n      // characters — the file then grades as having no frontmatter at all (a\n      // warning this check does not retain), and mangled bytes read as\n      // \"nothing stale\". So both spec axes are decoded FIRST through the\n      // invocation's read index, whose decoder refuses non-UTF-8 naming the\n      // file (NotUtf8DocumentError spells `path` the way Node does, so the\n      // containment below names it without knowing the type).\n      for (const axis of SPEC_AXES) {\n        const path = s.paths[axis.key];\n        if (existsSync(path)) await req.fleet.readText(path);\n      }\n      const all = await serviceProvenance(req.docsDir, s.id, { repoDir: s.repoDir, fleet: req.fleet });\n      return all\n        .filter(\n          (f) =>\n            f.code === \"content.stale\" ||\n            f.code === \"sources.stale\" ||\n            f.code === \"frontmatter.malformed\",\n        )\n        // The staleness emitters name the file in the message but set no\n        // subject; the payload's per-service attribution should not make a\n        // caller parse it back out of prose.\n        .map((f) => (f.subject === undefined ? { ...f, subject: s.id } : f));\n    } catch (err) {\n      return [unreadableSubject(\"service\", s.id, err)];\n    }\n  });\n  return graded.flat();\n}\n"]}
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../../../src/core/gate/checks.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The four checks behind `loam gate` — a can-i-deploy-shaped PURE QUERY over\n * evidence other commands already recorded. Nothing here executes anything,\n * writes anything, takes the docs lock, or re-derives a coherence plan: every\n * answer is either already on disk (verification.yaml, vouch stamps, the\n * commit journal) or a presence/landscape fact the enumeration carries.\n *\n *   partners      the landscape's direct joins, both ends graded on the ladder\n *   freshness     content.stale / sources.stale over the target and partners,\n *                 plus the one integrity error that makes freshness\n *                 unjudgeable (frontmatter.malformed) and a refusing decode\n *                 of the spec bytes themselves\n *   verification  verificationState per feature touching the service — the\n *                 active ones, plus those archived after `--since <ref>` when\n *                 a pipeline names the docs commit it last deployed from\n *                 (its own module, `./verification.ts`)\n *   interrupted   the `.loam-commit` journal — the one repo state that poisons\n *                 every other answer above\n *\n * Every `gate.*` code is spelled as a literal `code:` property at its emit\n * site, never through a code-taking factory parameter — verifyStep\n * (core/status/verification.ts) records that test/codes-drift.test.ts's\n * collector is blind to the parameter form, and a refactor toward a factory\n * would silently undocument the family.\n */\nimport { existsSync } from \"node:fs\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport { serviceProvenance } from \"../provenance/findings.js\";\nimport { interruptedCommitFinding } from \"../staging/recovery/finding.js\";\nimport { servicePathsAt, SPEC_AXES, type ServicePaths } from \"../repo/paths.js\";\nimport { serviceTreePath } from \"../kernel/ids/dirs.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { RawServiceId } from \"../kernel/ids/service.js\";\nimport { atLeastDocumented, partnerScan, type PartnerScan } from \"./partners.js\";\nimport { verificationCheck } from \"./verification.js\";\nimport { unreadableSubject, type GateCheck, type GateReport, type GateSince } from \"./report.js\";\n\nexport interface GateRequest {\n  docsDir: DocsDir;\n  /** The service being deployed — a name the enumeration approved. */\n  service: RawServiceId;\n  /**\n   * The repository loam is standing in, passed ONLY when the gated service is\n   * this repo's own binding — validate's `repoOf` rule: `sources` are paths\n   * into a service's own repository, so `sources.stale` is honestly checkable\n   * only there, while `content.stale` needs nothing but the document.\n   */\n  repoDir?: string;\n  fleet: FleetContext;\n  /** `--since <ref>`, resolved by the command; absent means in-flight features only. */\n  since?: GateSince;\n}\n\nexport async function gateReport(req: GateRequest): Promise<GateReport> {\n  // The scan first, alone: freshness walks the partner set it derives. The\n  // three remaining checks are independent of each other — different files,\n  // memoized reads — so they run concurrently; only the scan must be ordered.\n  const scan = await partnerScan({ docsDir: req.docsDir, service: req.service, fleet: req.fleet });\n  const [freshness, verification, interrupted] = await Promise.all([\n    freshnessFindings(req, scan),\n    verificationCheck(req),\n    interruptedCommitFinding(req.docsDir),\n  ]);\n  const checks: GateCheck[] = [\n    { check: \"partners\", findings: partnersFindings(scan, req.service) },\n    { check: \"freshness\", findings: freshness },\n    { check: \"verification\", findings: verification.findings },\n    { check: \"interrupted\", findings: interrupted === null ? [] : [interrupted] },\n  ];\n  return {\n    service: req.service,\n    since: req.since === undefined ? null : { ref: req.since.ref, commit: req.since.commit },\n    landscape: scan.landscape,\n    partners: scan.partners,\n    features: verification.features,\n    checks,\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Check 1: partners                                                   */\n/* ------------------------------------------------------------------ */\n\nfunction partnersFindings(scan: PartnerScan, service: string): Finding[] {\n  const findings: Finding[] = [];\n  // \"Could not look\" must never read as \"no partners\" — the docsRepoReady\n  // doctrine one level down. `validate --all` owns the diagnosis of the\n  // landscape itself; this code only refuses the false silence. The two ways\n  // of not looking are graded apart, the way `landscape.missing` and\n  // `landscape.invalid` are: ABSENT is a warning — a repo before its first\n  // adopt legitimately has no map yet — but a map that EXISTS and cannot be\n  // parsed or read is an ERROR, because `validate --all` fails that repo\n  // (`landscape.invalid`) and a deploy gate that passed where the fleet gate\n  // fails would be the quieter of two contradictory verdicts.\n  if (scan.landscape === \"absent\") {\n    findings.push({\n      severity: \"warn\",\n      code: \"gate.partners-unknown\",\n      message: `architecture/landscape.likec4 does not exist, so the partner set for '${service}' could not be derived — an absent map means nobody could look, not that nothing joins this service. \\`loam validate --all\\` diagnoses the landscape itself.`,\n    });\n  } else if (scan.landscape === \"invalid\") {\n    findings.push({\n      severity: \"error\",\n      code: \"gate.partners-unknown\",\n      message:\n        `architecture/landscape.likec4 exists but cannot be used — ${scan.landscapeProblem ?? \"it did not parse\"} — so the partner set for '${service}' could not be derived. ` +\n        `A broken map means nobody could look, not that nothing joins this service, and \\`loam validate --all\\` fails this repo for the same file. Fix the landscape, then re-run.`,\n    });\n  }\n  // The rung depends on the landscape only through the api question (does\n  // anything call this service?). With no readable map that question is\n  // unanswerable, and the fail-closed grading — `landscapeEvidence`: no proof\n  // means an API is expected — would convict a worker or UI for a contract\n  // nobody may be owed. One unanswerable fact yields ONE finding (the\n  // landscape's own, above), so under an unreadable map this error fires only\n  // when the service is below `documented` REGARDLESS of the api question.\n  const target = scan.landscape === \"read\" ? scan.target : scan.targetWithoutApi;\n  if (!atLeastDocumented(target.maturity)) {\n    findings.push({\n      severity: \"error\",\n      code: \"gate.service-undocumented\",\n      subject: service,\n      message:\n        `${serviceTreePath(scan.targetEntry)}/ sits at '${target.maturity}' on the adoption ladder — below 'documented', the docs cannot say what its joins even are, so no recorded evidence can answer the deploy question. ` +\n        `Author the baseline (\\`loam adopt --service ${service}\\` briefs it); this check passes once the required artifact set exists and its spec.md no longer says \\`adoption: partial\\`.`,\n      details: target.gaps,\n      text: { detailPrefix: \"- \" },\n    });\n  }\n  // The partners that HAVE a directory, by id: their findings name it, and it\n  // is `services/<subsystem>/<id>/` for a filed one. The no-directory branch\n  // below keeps the bare `services/<id>/` spelling deliberately — there is no\n  // directory to name, and the unfiled form is what the fix would create.\n  const partnerPath = new Map(scan.partnerEntries.map((e) => [e.id as string, serviceTreePath(e)]));\n  for (const p of scan.partners) {\n    // An `#external` partner is somebody else's system: its side of the join\n    // is unrecorded ON PURPOSE, the same exemption the landscape census grants\n    // (`landscape.service-undocumented` skips #external too). The fleet's own\n    // infrastructure — a `database`, `queue`, `topic`, `cache` or `bucket` — is\n    // not a partner at all and never reaches this loop: `./partners.ts` drops it\n    // from the SET, beside the actors, because the three remedies below are all\n    // false of a store the fleet runs.\n    if (p.external) continue;\n    if (p.maturity === null) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gate.partner-undocumented\",\n        subject: p.service,\n        message:\n          `'${p.service}' joins '${service}' (${p.via.join(\", \")}) but has no services/${p.service}/ directory — its side of the join is unrecorded. ` +\n          `Adopt it, bind its landscape element to the right service with metadata { service '<id>' }, or tag it #external if it is not ours.`,\n        details: p.via,\n      });\n    } else if (!atLeastDocumented(p.maturity)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gate.partner-undocumented\",\n        subject: p.service,\n        message:\n          `${partnerPath.get(p.service) ?? `services/${p.service}`}/ sits at '${p.maturity}' — below 'documented' — while it joins '${service}' (${p.via.join(\", \")}): its side of the join is not fully recorded. \\`loam adopt --service ${p.service}\\` briefs what is missing.`,\n        details: p.via,\n      });\n    }\n  }\n  return findings;\n}\n\n/* ------------------------------------------------------------------ */\n/* Check 2: freshness                                                  */\n/* ------------------------------------------------------------------ */\n\n/**\n * `serviceProvenance` filtered to the two staleness codes plus the ONE\n * integrity error that makes freshness unjudgeable: `frontmatter.malformed`.\n * A header YAML refuses to parse cannot certify a `content_digest`, and\n * dropping that error read \"cannot judge\" as \"nothing stale\" — the exact\n * fail-open a deploy gate must not have. Everything else provenance grades\n * (missing owners, unstamped sources, absent frontmatter) is `validate`'s\n * report to make — a deploy gate that repeated it would drown the findings a\n * pipeline can actually act on at deploy time.\n */\nasync function freshnessFindings(req: GateRequest, scan: PartnerScan): Promise<Finding[]> {\n  const subjects: { id: RawServiceId; repoDir: string | undefined; paths: ServicePaths }[] = [\n    {\n      id: req.service,\n      repoDir: req.repoDir,\n      paths: await locateServicePaths(req.docsDir, req.service, req.fleet),\n    },\n    // Only the DOCUMENTED partners: a partner with no directory has nothing to\n    // grade, and already carries gate.partner-undocumented from check 1.\n    ...scan.partnerEntries.map((e) => ({\n      id: e.id,\n      repoDir: undefined,\n      paths: servicePathsAt(e.dir),\n    })),\n  ];\n  // Independent per-subject reads through the shared memo; inOrder keeps the\n  // findings in subject order (target first, partners sorted) so identical\n  // state yields identical bytes.\n  const graded = await inOrder(subjects, async (s) => {\n    try {\n      // The integrity gate serviceProvenance cannot give: its own reads decode\n      // with 'utf8', which silently turns UTF-16 bytes into replacement\n      // characters — the file then grades as having no frontmatter at all (a\n      // warning this check does not retain), and mangled bytes read as\n      // \"nothing stale\". So both spec axes are decoded FIRST through the\n      // invocation's read index, whose decoder refuses non-UTF-8 naming the\n      // file (NotUtf8DocumentError spells `path` the way Node does, so the\n      // containment below names it without knowing the type).\n      for (const axis of SPEC_AXES) {\n        const path = s.paths[axis.key];\n        if (existsSync(path)) await req.fleet.readText(path);\n      }\n      const all = await serviceProvenance(req.docsDir, s.id, { repoDir: s.repoDir, fleet: req.fleet });\n      return all\n        .filter(\n          (f) =>\n            f.code === \"content.stale\" ||\n            f.code === \"sources.stale\" ||\n            f.code === \"frontmatter.malformed\",\n        )\n        // The staleness emitters name the file in the message but set no\n        // subject; the payload's per-service attribution should not make a\n        // caller parse it back out of prose.\n        .map((f) => (f.subject === undefined ? { ...f, subject: s.id } : f));\n    } catch (err) {\n      return [unreadableSubject(\"service\", s.id, err)];\n    }\n  });\n  return graded.flat();\n}\n"]}