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

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

@@ -0,0 +1 @@
+{"version":3,"file":"living.js","sourceRoot":"","sources":["../../../src/core/coherence/living.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What the merge would do to the LIVING documents.\n *\n * The refusals `loam archive` makes about the world a feature is about to be\n * merged INTO — as opposed to the feature's own three axes agreeing, which is\n * coherence.ts's question: a per-service delta addressed to a service that\n * exists nowhere, a `specs/<svc>/` directory whose NAME could never be a\n * service id, and git conflict markers in a living document the merge would\n * rewrite. `validate` and `status` read the same functions, so the gates\n * cannot drift into disagreeing about what they refuse.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { loadFile, type LoadedDoc } from \"../c4/likec4.js\";\nimport { elementService } from \"../c4/resolve/service.js\";\nimport { closeIds } from \"../c4/arch.js\";\nimport { serviceIdProblem, type PathableService } from \"../kernel/ids/service.js\";\nimport { repoPath } from \"../envelope/json.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { featurePaths, landscapePath, SPEC_AXES } from \"../repo/paths.js\";\nimport { livingCapabilityPaths } from \"../repo/authored/paths.js\";\nimport { docsRepoState } from \"../repo/state.js\";\nimport { featureSpecServices, listServices } from \"../repo/repo.js\";\nimport { enumeratedServices, locateServicePaths } from \"../repo/service-target.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { documentConflictFinding, landscapeConflictFinding } from \"../conflict-markers.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\n\n\n/* ------------------------------------------------------------------ */\n/* What the merge would do to the LIVING documents                     */\n/* ------------------------------------------------------------------ */\n\n/**\n * Per-service deltas addressed to a service that exists nowhere: no\n * `services/<svc>/`, and nothing in this feature's own tagged delta introducing\n * one.\n *\n * `validate` grades this (`delta.service-unknown`); `archive` is where it costs\n * something, because `specs/<svc>/` is what the merge MATERIALISES\n * `services/<svc>/` from — one wrong character in `--touches` and the fleet\n * acquires a living service nobody meant to adopt, under a banner saying the\n * living docs are complete. Both gates read this function so they cannot drift\n * into disagreeing about which service ids are real; the `code:` literal lives\n * here, once, where the drift collector sees it.\n *\n * A delta that did not parse proves nothing either way — whether it introduces\n * the service is exactly what nobody can read — so the question is suspended\n * there rather than answered by guessing. `delta.invalid` is that file's\n * finding, and coherence already makes it.\n *\n * `services/<svc>/` is asked for directly rather than through the enumeration:\n * a feature may be graded in a docs repo with no `services/` at all (repo.ts\n * takes the same position), where enumerating is a refusal, not an answer.\n */\nexport async function unknownDeltaServices(\n  docsDir: DocsDir,\n  featureDir: FeatureDir,\n  featureId: string,\n  loaded: { preloadedDelta?: LoadedDoc; context?: FleetContext } = {},\n): Promise<Finding[]> {\n  const { preloadedDelta, context } = loaded;\n  const deltaPath = featurePaths(featureDir).delta;\n  let delta: LoadedDoc | undefined;\n  if (existsSync(deltaPath)) {\n    delta = preloadedDelta ?? (context === undefined ? await loadFile(deltaPath) : await context.loadLikeC4(deltaPath));\n  }\n  if (delta !== undefined && delta.errors.length > 0) return [];\n\n  const introduces: ReadonlySet<string> = new Set(\n    (delta?.elements ?? []).filter((e) => e.tags.includes(featureId)).map(elementService),\n  );\n  // Enumeration MEMBERSHIP, not an existsSync of services/<svc>/ at the root:\n  // a service filed into a subsystem exists wherever the tree walk found it,\n  // and the root probe would grade it unknown. `enumeratedServices` swallows\n  // an unenumerable services/ to [] on purpose — this also runs under archive\n  // in repos validate --feature tolerates (no services/ at all), where every\n  // probe would have found nothing there anyway.\n  const known: ReadonlySet<string> = new Set((await enumeratedServices(docsDir, context)).map((s) => s.id));\n  const unknown = (await featureSpecServices(featureDir, context)).filter(\n    (svc) => !known.has(svc) && !introduces.has(svc),\n  );\n  if (unknown.length === 0) return [];\n\n  // The near-miss hint, on the same rule `service.unknown` uses — a typo is\n  // only diagnosable against the ids that DO exist.\n  const closeTo =\n    docsRepoState(docsDir).kind === \"ok\" ? (await listServices(docsDir, context)).map((s) => s.id) : [];\n  return unknown.map((svc) => deltaServiceUnknownFinding(svc, closeTo));\n}\n\n/**\n * The finding itself, for the two gates that reach this conclusion by different\n * routes.\n *\n * `archive` gets there through `unknownDeltaServices` above; `validate` gets\n * there through its own enumeration, because it suspends the question on an\n * unreadable delta rather than returning early on it, and that difference is\n * deliberate. What must NOT differ is the sentence: the two were spelled out\n * word for word in two files, so a reworded hint in one of them would have made\n * `loam validate` and `loam archive` describe the same typo differently, on the\n * same code, in the same repo.\n *\n * `knownIds` is the fleet's real service ids — already enumerated by the caller,\n * which is also the caller's chance to skip the enumeration entirely when there\n * is nothing to diagnose.\n */\nexport function deltaServiceUnknownFinding(svc: string, knownIds: string[]): Finding {\n  const close = closeIds(svc, knownIds);\n  return {\n    severity: \"error\",\n    code: \"delta.service-unknown\",\n    subject: svc,\n    message:\n      `specs/${svc}/ addresses a service that does not exist: there is no services/${svc}/ and this feature's ` +\n      `delta.likec4 does not introduce one — archiving would create it out of the typo.` +\n      (close.length > 0 ? ` Did you mean: ${close.join(\", \")}?` : \" `loam list services` shows what exists.\"),\n  };\n}\n\n/**\n * Per-service deltas whose DIRECTORY NAME is not a legal service id at all.\n *\n * `specs/<svc>/` is caller-controlled path input exactly as `--service` is:\n * `featureSpecServices` returns whatever `readdir` found, and nothing between\n * that readdir and the archive merge ever asked the id grammar about it. So\n * `specs/Payment Service/` validated green — \"requirements covered\", even,\n * because a tagged element whose TITLE matched the directory counted as\n * introducing the service — and `loam archive` then materialised\n * `services/Payment Service/`: a directory `service.id-invalid` calls an error\n * on the very next `validate --all`, and one no loam command can address or\n * re-create. Both gates read this function for `unknownDeltaServices`' reason:\n * validate and archive must refuse the same directory with the same sentence.\n *\n * NOT suppressed by what the delta introduces, and NOT suspended on\n * `delta.invalid`: the name is illegal whatever the architecture axis says,\n * because the name itself is what becomes the path.\n */\nexport async function invalidSpecServiceFindings(\n  featureDir: FeatureDir,\n  context?: FleetContext,\n): Promise<Finding[]> {\n  const out: Finding[] = [];\n  for (const svc of await featureSpecServices(featureDir, context)) {\n    const problem = serviceIdProblem(svc, \"specs/ directory name\");\n    if (problem === null) continue;\n    out.push({\n      severity: \"error\",\n      code: \"delta.service-id-invalid\",\n      subject: svc,\n      message:\n        `specs/${svc}/ — ${problem} ` +\n        `\\`loam archive\\` materialises services/${svc}/ from this directory name, and that directory is one ` +\n        `no loam command can address afterwards (\\`service.id-invalid\\`). Rename the specs/ directory to a legal id.`,\n    });\n  }\n  return out;\n}\n\n/**\n * Git conflict markers in the LIVING documents a merge of this feature would\n * rewrite: each touched service's requirement files, and the fleet map.\n *\n * The rule and the sentence are conflict-markers's — one spelling of the breach,\n * wherever it is found. What this adds is the SET: the documents `archive`\n * rewrites. A conflicted `services/<svc>/spec.md` parses as prose, so every\n * check upstream of the merge reads it as a valid document with some odd\n * headings in it; the rewrite then drops whichever marker lines fall inside the\n * requirements run it owns, and a conflict anyone could see becomes a file\n * nobody can tell is wrong. For a shared docs repo that a fleet lands in\n * through PRs, that is the default failure and not an edge.\n *\n * `openapi.yaml` is deliberately absent: markers make it unparseable, so the\n * YAML reader already refuses it by name and a second finding would only say\n * the same thing later.\n *\n * `capabilities` is the same question on the business corpus, and it is not\n * optional politeness: a living `capabilities/<id>/spec.md` the feature's\n * capability delta merges into is rewritten by exactly the same\n * `rewriteRequirementsRun`, so a conflicted one loses its marker lines exactly\n * the same way. Passed in rather than walked here because the caller has\n * already read the feature's delta tree and this function must not decide which\n * documents a merge touches.\n *\n * IDS, not the `CapabilityDoc` records the caller holds, and that is a guard\n * rather than a preference: a `CapabilityDoc` from a feature's delta walk\n * carries `spec` and `dir` pointing at the FEATURE'S copy, and the document\n * this function is about is the LIVING one. Taking the whole record would leave\n * `doc.spec` in scope here — the wrong file, one property access away.\n */\nexport async function livingMergeConflicts(\n  docsDir: DocsDir,\n  services: readonly PathableService[],\n  capabilities: readonly string[],\n  context?: FleetContext,\n): Promise<Finding[]> {\n  const out: Finding[] = [];\n  const read = async (path: string): Promise<string> =>\n    context === undefined ? readFile(path, \"utf8\") : context.readText(path);\n\n  for (const svc of services) {\n    const paths = await locateServicePaths(docsDir, svc, context);\n    for (const axis of SPEC_AXES) {\n      const path = paths[axis.key];\n      if (!existsSync(path)) continue;\n      const finding = documentConflictFinding(repoPath(docsDir, path), svc, await read(path));\n      if (finding !== null) out.push(finding);\n    }\n  }\n\n  for (const id of capabilities) {\n    const path = livingCapabilityPaths(docsDir, id).spec;\n    if (!existsSync(path)) continue;\n    const finding = documentConflictFinding(repoPath(docsDir, path), id, await read(path));\n    if (finding !== null) out.push(finding);\n  }\n\n  const landscape = landscapePath(docsDir);\n  if (existsSync(landscape)) {\n    const finding = landscapeConflictFinding(repoPath(docsDir, landscape), await read(landscape));\n    if (finding !== null) out.push(finding);\n  }\n  return out;\n}\n"]}

package/dist/core/coherence/lookups.js

@@ -0,0 +1,155 @@
+/**
+ * The questions the coherence checks ask lazily, each behind a per-service or
+ * per-repo cache.
+ *
+ * All but one reach outside the delta — into a living spec, the fleet map, or
+ * another feature in flight — and those are expensive: the landscape is a full
+ * LikeC4 workspace spin-up, and the cross-feature scan is a walk of every
+ * active delta. The exception is `undeprecatedByFeature`, which reads the
+ * FEATURE's own openapi delta: it lives here anyway because it is the second
+ * half of the one question `deprecatedInLiving` opens — "is this op dying, and
+ * is this feature the resurrection?" — and splitting the pair across modules
+ * would leave each half's cache discipline unexplained by the other. A feature
+ * whose checks never need a lookup must not pay for it, which is why these are
+ * closures over a cache rather than arguments computed up front.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { loadFile } from "../c4/likec4.js";
+import { serviceResolver } from "../c4/resolve/service.js";
+import {} from "../kernel/ids/service.js";
+import { featureSpecPaths, landscapePath } from "../repo/paths.js";
+import { operations } from "../openapi/doc.js";
+import { enumeratedServiceIds, locateServicePaths } from "../repo/service-target.js";
+import { activeOpAdditions } from "./pending.js";
+import { parseRequirements } from "../document/parse.js";
+import {} from "../document/spec.js";
+import {} from "./declared.js";
+export function coherenceLookups(scope, context) {
+    const { docsDir, featureDir, featureId } = scope;
+    const livingReqs = new Map();
+    const livingRequirements = async (service) => {
+        let reqs = livingReqs.get(service);
+        if (reqs === undefined) {
+            const p = (await locateServicePaths(docsDir, service, context)).spec;
+            reqs = existsSync(p)
+                ? context === undefined
+                    ? parseRequirements(await readFile(p, "utf8"))
+                    : await context.readRequirements(p)
+                : [];
+            livingReqs.set(service, reqs);
+        }
+        return reqs;
+    };
+    const governedByLivingSpec = async (service, op) => {
+        return (await livingRequirements(service)).some((r) => r.operations.includes(op));
+    };
+    // The enumerated fleet, read once and shared by both consumer scans below.
+    let serviceIds;
+    const enumeratedServices = async () => (serviceIds ??= await enumeratedServiceIds(docsDir, context));
+    // --- retiring an operation the fleet still calls ---
+    //
+    // A removal marker is checked against the living CONTRACT (does the slot
+    // exist) and the feature's own requirements (is the retirement governed).
+    // Neither question asks the one that matters to the other ninety-nine repos:
+    // is anybody still calling it? The living landscape is the fleet's own answer
+    // — an edge with `metadata { op }` is a consumer somebody drew — and another
+    // service's living requirements naming the operation are a second. Both are
+    // gating: the merge deletes the operation from the contract while the edge
+    // and the requirement stay, so the very next `validate --all` reports a
+    // broken contract on a repository whose author was never in this feature.
+    //
+    // Lazy on purpose: the landscape is a full LikeC4 workspace spin-up and the
+    // requirement scan reads every service's living spec, and a feature that
+    // removes nothing must pay for neither.
+    //
+    // `core/diff/victims.ts` carries a second copy of this join (an index over
+    // an already-read fleet — these closures are scoped to a DeltaScope and
+    // cannot serve it). The victim strings and scan rules are kept in step by
+    // hand; changing either module owes the other the same change, and a THIRD
+    // copy forces the shared extraction (docs/DESIGN.md rule 13).
+    let livingLandscape;
+    const edgeConsumers = async (service, op) => {
+        if (livingLandscape === undefined) {
+            const path = landscapePath(docsDir);
+            livingLandscape = existsSync(path)
+                ? context === undefined
+                    ? await loadFile(path)
+                    : await context.loadLikeC4(path)
+                : null;
+        }
+        // An unreadable landscape proves nothing either way; `landscape.invalid`
+        // is validate's finding to make, and inventing a removal refusal out of a
+        // parse error would point the author at the wrong file.
+        if (livingLandscape === null || livingLandscape.errors.length > 0)
+            return [];
+        // The enumerated fleet rides along so a landscape that models CONTAINERS
+        // stays visible: without it, an edge into `payment.api` resolves to a
+        // service called "api" that has never existed, the `=== service` join
+        // below finds nothing, and the one check standing between a removal and
+        // its last consumer answers "nobody calls it".
+        const resolve = serviceResolver(livingLandscape.elements, new Set(await enumeratedServices()));
+        return livingLandscape.relationships
+            .filter((r) => r.op === op && resolve(r.target) === service)
+            .map((r) => `edge ${resolve(r.source)} → ${resolve(r.target)}${r.title === undefined ? "" : ` ("${r.title}")`}`);
+    };
+    const requirementConsumers = async (service, op) => {
+        const others = (await enumeratedServices()).filter((id) => id !== service);
+        const out = [];
+        for (const other of others) {
+            for (const r of await livingRequirements(other)) {
+                if (r.operations.includes(op))
+                    out.push(`${other}'s living requirement '${r.name}'`);
+            }
+        }
+        return out;
+    };
+    // What OTHER features in flight define, per (service, op). Cross-service work
+    // normally lands as feature A calling an op that in-flight feature B introduces;
+    // that is an ordering dependency, not a broken contract, and the requirements
+    // axis already grades the same shape as a warn (delta.modified-pending). Lazy
+    // like delta.ts's activeAdditions — the common case (op resolves) never pays
+    // for the fleet scan.
+    let inFlightOps = null;
+    const definedElsewhere = async (service, op) => {
+        inFlightOps ??= await activeOpAdditions(docsDir, featureId, context);
+        return inFlightOps.get(`${service} ${op}`);
+    };
+    // What the LIVING provider contracts mark `deprecated: true`, read lazily
+    // per service. Living only, on purpose: the feature's own openapi delta
+    // restates the full API, and the question here is whether the fleet as
+    // shipped is already retiring the op this feature starts leaning on.
+    const livingDeprecated = new Map();
+    const deprecatedInLiving = async (service, op) => {
+        let set = livingDeprecated.get(service);
+        if (!set) {
+            const list = await operations((await locateServicePaths(docsDir, service, context)).openapi, context);
+            set = new Set(list.filter((o) => o.deprecated).map((o) => o.id));
+            livingDeprecated.set(service, set);
+        }
+        return set.has(op);
+    };
+    // ...unless this feature IS the un-deprecation: an openapi delta that
+    // restates the op WITHOUT `deprecated: true` retires the flag on archive
+    // (the path-item overwrite is wholesale), so "prefer the replacement
+    // operation" would point the author away from the exact change they are
+    // shipping. A delta that restates the op still deprecated — or has no
+    // delta for the service at all — keeps the warning. The one lookup here
+    // that reads the delta's own files rather than the world outside it (the
+    // header says why it lives beside its living twin regardless).
+    const featureUndeprecated = new Map();
+    const undeprecatedByFeature = async (service, op) => {
+        let set = featureUndeprecated.get(service);
+        if (!set) {
+            const list = await operations(featureSpecPaths(featureDir, service).openapi, context);
+            set = new Set(list.filter((o) => !o.deprecated).map((o) => o.id));
+            featureUndeprecated.set(service, set);
+        }
+        return set.has(op);
+    };
+    return {
+        governedByLivingSpec, edgeConsumers, requirementConsumers, definedElsewhere,
+        deprecatedInLiving, undeprecatedByFeature,
+    };
+}
+//# sourceMappingURL=lookups.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lookups.js","sourceRoot":"","sources":["../../../src/core/coherence/lookups.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The questions the coherence checks ask lazily, each behind a per-service or\n * per-repo cache.\n *\n * All but one reach outside the delta — into a living spec, the fleet map, or\n * another feature in flight — and those are expensive: the landscape is a full\n * LikeC4 workspace spin-up, and the cross-feature scan is a walk of every\n * active delta. The exception is `undeprecatedByFeature`, which reads the\n * FEATURE's own openapi delta: it lives here anyway because it is the second\n * half of the one question `deprecatedInLiving` opens — \"is this op dying, and\n * is this feature the resurrection?\" — and splitting the pair across modules\n * would leave each half's cache discipline unexplained by the other. A feature\n * whose checks never need a lookup must not pay for it, which is why these are\n * closures over a cache rather than arguments computed up front.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { loadFile, type LoadedDoc } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { type PathableService } from \"../kernel/ids/service.js\";\nimport { featureSpecPaths, landscapePath } from \"../repo/paths.js\";\nimport { operations } from \"../openapi/doc.js\";\nimport { enumeratedServiceIds, locateServicePaths } from \"../repo/service-target.js\";\nimport { activeOpAdditions } from \"./pending.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport { type Requirement } from \"../document/spec.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { type DeltaScope } from \"./declared.js\";\n\n/** What the checks may ask lazily — fleet questions, plus the deprecation pair. */\nexport interface Lookups {\n  governedByLivingSpec(service: PathableService, op: string): Promise<boolean>;\n  edgeConsumers(service: string, op: string): Promise<string[]>;\n  requirementConsumers(service: string, op: string): Promise<string[]>;\n  definedElsewhere(service: string, op: string): Promise<string | undefined>;\n  deprecatedInLiving(service: PathableService, op: string): Promise<boolean>;\n  undeprecatedByFeature(service: PathableService, op: string): Promise<boolean>;\n}\n\nexport function coherenceLookups(scope: DeltaScope, context?: FleetContext): Lookups {\n  const { docsDir, featureDir, featureId } = scope;\n    const livingReqs = new Map<string, Requirement[]>();\n    const livingRequirements = async (service: PathableService): Promise<Requirement[]> => {\n      let reqs = livingReqs.get(service);\n      if (reqs === undefined) {\n        const p = (await locateServicePaths(docsDir, service, context)).spec;\n        reqs = existsSync(p)\n          ? context === undefined\n            ? parseRequirements(await readFile(p, \"utf8\"))\n            : await context.readRequirements(p)\n          : [];\n        livingReqs.set(service, reqs);\n      }\n      return reqs;\n    };\n    const governedByLivingSpec = async (service: PathableService, op: string): Promise<boolean> => {\n      return (await livingRequirements(service)).some((r) => r.operations.includes(op));\n    };\n\n    // The enumerated fleet, read once and shared by both consumer scans below.\n    let serviceIds: PathableService[] | undefined;\n    const enumeratedServices = async (): Promise<PathableService[]> =>\n      (serviceIds ??= await enumeratedServiceIds(docsDir, context));\n\n    // --- retiring an operation the fleet still calls ---\n    //\n    // A removal marker is checked against the living CONTRACT (does the slot\n    // exist) and the feature's own requirements (is the retirement governed).\n    // Neither question asks the one that matters to the other ninety-nine repos:\n    // is anybody still calling it? The living landscape is the fleet's own answer\n    // — an edge with `metadata { op }` is a consumer somebody drew — and another\n    // service's living requirements naming the operation are a second. Both are\n    // gating: the merge deletes the operation from the contract while the edge\n    // and the requirement stay, so the very next `validate --all` reports a\n    // broken contract on a repository whose author was never in this feature.\n    //\n    // Lazy on purpose: the landscape is a full LikeC4 workspace spin-up and the\n    // requirement scan reads every service's living spec, and a feature that\n    // removes nothing must pay for neither.\n    //\n    // `core/diff/victims.ts` carries a second copy of this join (an index over\n    // an already-read fleet — these closures are scoped to a DeltaScope and\n    // cannot serve it). The victim strings and scan rules are kept in step by\n    // hand; changing either module owes the other the same change, and a THIRD\n    // copy forces the shared extraction (docs/DESIGN.md rule 13).\n    let livingLandscape: LoadedDoc | null | undefined;\n    const edgeConsumers = async (service: string, op: string): Promise<string[]> => {\n      if (livingLandscape === undefined) {\n        const path = landscapePath(docsDir);\n        livingLandscape = existsSync(path)\n          ? context === undefined\n            ? await loadFile(path)\n            : await context.loadLikeC4(path)\n          : null;\n      }\n      // An unreadable landscape proves nothing either way; `landscape.invalid`\n      // is validate's finding to make, and inventing a removal refusal out of a\n      // parse error would point the author at the wrong file.\n      if (livingLandscape === null || livingLandscape.errors.length > 0) return [];\n      // The enumerated fleet rides along so a landscape that models CONTAINERS\n      // stays visible: without it, an edge into `payment.api` resolves to a\n      // service called \"api\" that has never existed, the `=== service` join\n      // below finds nothing, and the one check standing between a removal and\n      // its last consumer answers \"nobody calls it\".\n      const resolve = serviceResolver(livingLandscape.elements, new Set(await enumeratedServices()));\n      return livingLandscape.relationships\n        .filter((r) => r.op === op && resolve(r.target) === service)\n        .map((r) => `edge ${resolve(r.source)} → ${resolve(r.target)}${r.title === undefined ? \"\" : ` (\"${r.title}\")`}`);\n    };\n    const requirementConsumers = async (service: string, op: string): Promise<string[]> => {\n      const others = (await enumeratedServices()).filter((id) => id !== service);\n      const out: string[] = [];\n      for (const other of others) {\n        for (const r of await livingRequirements(other)) {\n          if (r.operations.includes(op)) out.push(`${other}'s living requirement '${r.name}'`);\n        }\n      }\n      return out;\n    };\n\n    // What OTHER features in flight define, per (service, op). Cross-service work\n    // normally lands as feature A calling an op that in-flight feature B introduces;\n    // that is an ordering dependency, not a broken contract, and the requirements\n    // axis already grades the same shape as a warn (delta.modified-pending). Lazy\n    // like delta.ts's activeAdditions — the common case (op resolves) never pays\n    // for the fleet scan.\n    let inFlightOps: Map<string, string> | null = null;\n    const definedElsewhere = async (service: string, op: string): Promise<string | undefined> => {\n      inFlightOps ??= await activeOpAdditions(docsDir, featureId, context);\n      return inFlightOps.get(`${service} ${op}`);\n    };\n\n    // What the LIVING provider contracts mark `deprecated: true`, read lazily\n    // per service. Living only, on purpose: the feature's own openapi delta\n    // restates the full API, and the question here is whether the fleet as\n    // shipped is already retiring the op this feature starts leaning on.\n    const livingDeprecated = new Map<string, Set<string>>();\n    const deprecatedInLiving = async (service: PathableService, op: string): Promise<boolean> => {\n      let set = livingDeprecated.get(service);\n      if (!set) {\n        const list = await operations((await locateServicePaths(docsDir, service, context)).openapi, context);\n        set = new Set(list.filter((o) => o.deprecated).map((o) => o.id));\n        livingDeprecated.set(service, set);\n      }\n      return set.has(op);\n    };\n\n    // ...unless this feature IS the un-deprecation: an openapi delta that\n    // restates the op WITHOUT `deprecated: true` retires the flag on archive\n    // (the path-item overwrite is wholesale), so \"prefer the replacement\n    // operation\" would point the author away from the exact change they are\n    // shipping. A delta that restates the op still deprecated — or has no\n    // delta for the service at all — keeps the warning. The one lookup here\n    // that reads the delta's own files rather than the world outside it (the\n    // header says why it lives beside its living twin regardless).\n    const featureUndeprecated = new Map<string, Set<string>>();\n    const undeprecatedByFeature = async (service: PathableService, op: string): Promise<boolean> => {\n      let set = featureUndeprecated.get(service);\n      if (!set) {\n        const list = await operations(featureSpecPaths(featureDir, service).openapi, context);\n        set = new Set(list.filter((o) => !o.deprecated).map((o) => o.id));\n        featureUndeprecated.set(service, set);\n      }\n      return set.has(op);\n    };\n  return {\n    governedByLivingSpec, edgeConsumers, requirementConsumers, definedElsewhere,\n    deprecatedInLiving, undeprecatedByFeature,\n  };\n}\n"]}

package/dist/core/coherence/pending.js

@@ -0,0 +1,39 @@
+/**
+ * What OTHER features in flight already define — the answer that turns "broken
+ * contract" into "ordering dependency".
+ *
+ * Cross-service work normally lands as feature A consuming an operation that
+ * in-flight feature B introduces; grading that as `op-undefined` tells the
+ * author to fix a contract that is merely queued. coherence.ts downgrades to
+ * the `*-pending` warnings on this module's answer. It is the openapi mirror
+ * of delta.ts's `activeAdditions`, and lives beside its caller rather than in
+ * delta.ts only because that module is at its size ceiling and the two
+ * mirrors never share code — each reads a different axis's documents.
+ */
+import { featureSpecPaths } from "../repo/paths.js";
+import { listFeatures } from "../repo/repo.js";
+import { operations } from "../openapi/doc.js";
+/**
+ * (service, operationId) pairs other ACTIVE features' openapi deltas define,
+ * mapped to the feature id. Archived features are excluded: their ops are in
+ * the living openapi already or gone for good, and neither is "pending". First
+ * feature wins a clash — one name to archive first is enough to make progress.
+ */
+export async function activeOpAdditions(docsDir, exclude, context) {
+    const map = new Map();
+    for (const feature of await listFeatures(docsDir, {}, context)) {
+        if (feature.id === exclude)
+            continue;
+        for (const service of feature.services) {
+            for (const op of await operations(featureSpecPaths(feature.dir, service).openapi, context)) {
+                if (op.remove)
+                    continue;
+                const k = `${service} ${op.id}`;
+                if (!map.has(k))
+                    map.set(k, feature.id);
+            }
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=pending.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../../src/core/coherence/pending.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI/C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAgB,EAChB,OAAe,EACf,OAAsB;IAEtB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,OAAO,IAAI,MAAM,YAAY,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;QAC/D,IAAI,OAAO,CAAC,EAAE,KAAK,OAAO;YAAE,SAAS;QACrC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACvC,KAAK,MAAM,EAAE,IAAI,MAAM,UAAU,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC3F,IAAI,EAAE,CAAC,MAAM;oBAAE,SAAS;gBACxB,MAAM,CAAC,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;oBAAE,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * What OTHER features in flight already define — the answer that turns \"broken\n * contract\" into \"ordering dependency\".\n *\n * Cross-service work normally lands as feature A consuming an operation that\n * in-flight feature B introduces; grading that as `op-undefined` tells the\n * author to fix a contract that is merely queued. coherence.ts downgrades to\n * the `*-pending` warnings on this module's answer. It is the openapi mirror\n * of delta.ts's `activeAdditions`, and lives beside its caller rather than in\n * delta.ts only because that module is at its size ceiling and the two\n * mirrors never share code — each reads a different axis's documents.\n */\nimport { featureSpecPaths } from \"../repo/paths.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport { operations } from \"../openapi/doc.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * (service, operationId) pairs other ACTIVE features' openapi deltas define,\n * mapped to the feature id. Archived features are excluded: their ops are in\n * the living openapi already or gone for good, and neither is \"pending\". First\n * feature wins a clash — one name to archive first is enough to make progress.\n */\nexport async function activeOpAdditions(\n  docsDir: DocsDir,\n  exclude: string,\n  context?: FleetContext,\n): Promise<Map<string, string>> {\n  const map = new Map<string, string>();\n  for (const feature of await listFeatures(docsDir, {}, context)) {\n    if (feature.id === exclude) continue;\n    for (const service of feature.services) {\n      for (const op of await operations(featureSpecPaths(feature.dir, service).openapi, context)) {\n        if (op.remove) continue;\n        const k = `${service} ${op.id}`;\n        if (!map.has(k)) map.set(k, feature.id);\n      }\n    }\n  }\n  return map;\n}\n"]}

package/dist/core/conflict-markers.js

@@ -0,0 +1,60 @@
+/**
+ * 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),
+    };
+}
+//# sourceMappingURL=conflict-markers.js.map

package/dist/core/conflict-markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-markers.js","sourceRoot":"","sources":["../../src/core/conflict-markers.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;GAWG;AACH,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAE3D,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACxC,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yFAAyF;AACzF,SAAS,eAAe,CAAC,KAAa,EAAE,KAAe;IACrD,OAAO,CACL,GAAG,KAAK,6CAA6C,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;QAC5G,uFAAuF;QACvF,2GAA2G;QAC3G,gHAAgH,CACjH,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,OAAe,EAAE,IAAY;IAClF,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,qBAAqB;QAC3B,OAAO;QACP,OAAO,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC;KACvC,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,wBAAwB,CAAC,KAAa,EAAE,IAAY;IAClE,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,0BAA0B;QAChC,OAAO,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC;KACvC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Git conflict markers left in a document, and the findings they become.\n *\n * Split out of `fleet-context.ts` — the module that owes every READER the\n * check — because the rule itself is a leaf: doctor, validate's three target\n * kinds and coherence all grade marker breaches on text they already hold, and\n * none of them should have to import the whole read index (and the fleet it\n * pulls in behind it) to spell one line rule. The context keeps its\n * `conflictMarkers()` convenience over `readText`; the rule lives here.\n */\nimport type { Finding } from \"./vocabulary/report.js\";\n\n/**\n * The three-way merge left its markers in the file — 1-based line numbers.\n *\n * The rule is `loam doctor`'s, verbatim, and it lives here now because doctor\n * checked exactly one file (`architecture/landscape.likec4`) from a command\n * that gates nothing. The same markers in a living `services/<svc>/spec.md`\n * parse as prose: `loam validate --all` reported `valid: true`, and the next\n * `loam archive` rewrote the requirements section and dropped the `=======`\n * line with it, turning a conflict anyone can see into a document nobody can\n * tell is wrong. For a shared docs repo where a fleet lands through PRs this is\n * the DEFAULT failure, not an edge.\n */\nconst CONFLICT_MARKERS = [\"<<<<<<<\", \"=======\", \">>>>>>>\"];\n\nexport function conflictMarkerLines(source: string): number[] {\n  const out: number[] = [];\n  source.split(/\\r?\\n/).forEach((line, i) => {\n    if (CONFLICT_MARKERS.some((m) => line.startsWith(m))) out.push(i + 1);\n  });\n  return out;\n}\n\n/** One sentence for the breach, wherever it is found — doctor, validate, either axis. */\nfunction conflictMessage(label: string, lines: number[]): string {\n  return (\n    `${label} still contains git conflict markers (line${lines.length === 1 ? \"\" : \"s\"} ${lines.join(\", \")}) — ` +\n    `both sides of somebody's merge are in the file, so nothing it says is anyone's text. ` +\n    `Resolve the conflict before anything else: loam rewrites this document on archive, and a rewrite deletes ` +\n    `whichever marker lines fall inside the section it owns — a visible conflict becomes a silently malformed file.`\n  );\n}\n\n/**\n * The conflict-marker finding for a requirement document (living spec.md /\n * arch.spec.md, or a feature's delta of one). Null when the text is clean.\n *\n * An error because the document is not valid — nobody wrote what it now says —\n * and because the merge that would consume it is unsafe. It does not carry\n * `gates`: that field is coherence's (issue.ts), and the archive gate has to\n * ask this question itself.\n */\nexport function documentConflictFinding(label: string, subject: string, text: string): Finding | null {\n  const lines = conflictMarkerLines(text);\n  if (lines.length === 0) return null;\n  return {\n    severity: \"error\",\n    code: \"spec.merge-conflict\",\n    subject,\n    message: conflictMessage(label, lines),\n  };\n}\n\n/** The same breach in the fleet map, where it costs every cross-service check at once. */\nexport function landscapeConflictFinding(label: string, text: string): Finding | null {\n  const lines = conflictMarkerLines(text);\n  if (lines.length === 0) return null;\n  return {\n    severity: \"error\",\n    code: \"landscape.merge-conflict\",\n    message: conflictMessage(label, lines),\n  };\n}\n"]}

package/dist/core/delta/claims.js

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

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

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