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

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

@@ -0,0 +1,140 @@
+import { withFeatureCapabilities } from "../../capabilities/delta/overlay.js";
+import { capabilityRequirementIndex, gradableCapabilityIds } from "../../capabilities/findings.js";
+import { resolveCapabilityTags, resolveRequirementTags } from "../../capabilities/usecase-join.js";
+import { compareIds } from "../../repo/entries.js";
+import { featureFlowIssues } from "../grade/feature.js";
+import { readFeatureFlows } from "./overlay.js";
+/**
+ * The promises this feature's own flows keep, read over the post-merge map.
+ *
+ * A feature with no flow is `read` with nothing kept, which is the ordinary
+ * answer and costs one walk over a directory that is not there. The scan is
+ * read by the caller (`flowCoverage`), which grades the same flows too — one
+ * staged parse for both questions, because it is a Langium workspace spin.
+ */
+export function featureFlowPromises(scan, req) {
+    if (scan.kind === "unreadable")
+        return { kind: "unreadable", errors: scan.errors };
+    // The ladder, and it is `ungraded` rather than an empty answer. Once the
+    // feature's own capability deltas are unioned in, `declared` is null for
+    // exactly one reason — `architecture/capabilities.yaml` exists and does not
+    // read as a vocabulary — so no `#cap-` tag can resolve and no claim can be
+    // made either way. Returning "keeps nothing" here is what let
+    // `capability.uncovered` convict a flow that does resolve, over a file the
+    // feature gate reports nothing else about.
+    if (req.declared === null) {
+        return {
+            kind: "ungraded",
+            why: "architecture/capabilities.yaml does not read as a capability vocabulary (`loam validate --all` reports it as capability.invalid)",
+        };
+    }
+    // A real, empty answer: loam read the flows and none of them claims anything.
+    if (scan.views.length === 0)
+        return { kind: "read", kept: [] };
+    const byPromise = new Map();
+    for (const view of scan.views) {
+        const scope = resolveCapabilityTags(view.tags, req.declared).flatMap((claim) => claim.kind === "resolved" ? [claim.id] : []);
+        for (const claim of resolveRequirementTags(view.tags, scope, req.requirementsOf)) {
+            if (claim.kind !== "resolved")
+                continue;
+            // Keyed on the pair, never on a joined string: see the header. The Map is
+            // only here to collapse two views keeping one promise into one row.
+            const key = JSON.stringify([claim.capability, claim.id]);
+            const found = byPromise.get(key);
+            if (found === undefined) {
+                byPromise.set(key, {
+                    promise: { capability: claim.capability, requirement: claim.id, flows: [] },
+                    flows: new Set([view.id]),
+                });
+            }
+            else {
+                found.flows.add(view.id);
+            }
+        }
+    }
+    // Sorted, and the view ids inside each row sorted too: nothing in loam has
+    // measured that LikeC4 preserves view declaration order, so a message built
+    // from it would reorder under a dependency bump.
+    const kept = [...byPromise.values()]
+        .map(({ promise, flows }) => ({ ...promise, flows: [...flows].sort(compareIds) }))
+        .sort((a, b) => compareIds(a.capability, b.capability) || compareIds(a.requirement, b.requirement));
+    return { kind: "read", kept };
+}
+/**
+ * What this feature's own flows keep, resolved against the vocabulary and the
+ * requirement ids its own merge would leave behind.
+ *
+ * THE WIDENING IS THE POINT, and it is `capabilities/delta/overlay.ts`'s
+ * judgement applied to the other carrier: an analyst adds `NOTIFY-ONCE` to a
+ * capability delta and an architect answers it with a flow in the same change,
+ * so a `#req-` tag resolved against the LIVING tree alone names a promise that
+ * does not exist yet — and the same archive that would land the flow lands the
+ * promise it points at.
+ *
+ * `requirementsOf` KNOWS ONLY THE CAPABILITIES THIS FEATURE HAS A DELTA FOR, and
+ * within those it carries living ∪ ADDED ∪ MODIFIED ids. The narrowing changes
+ * no answer, for a reason stronger than "it is probably fine":
+ * `uncoveredIssues` grades `r.kind === "ADDED"` and nothing else, and every
+ * ADDED requirement it grades lives in one of these documents by construction —
+ * so no id outside this map can reach a verdict. The LIVING half is in there
+ * because a widening of the graded set must not silently need a second edit
+ * here; today it decides nothing. A flow keeping a promise of a capability this
+ * feature does NOT touch resolves to `undocumented` and counts for nothing,
+ * which is correct: the fleet-scope `capability.requirement-unrealized` grades
+ * that join over the whole corpus, and answering it here from a partial index is
+ * how two surfaces start disagreeing.
+ *
+ * `declared` IS NOT NARROWED, and that asymmetry is load-bearing. It is what
+ * `resolveCapabilityTags` compares a `#cap-` slug against, and a slug is not
+ * injective — `payments/refunds` and `payments-refunds` flatten to one. Handing
+ * it a short list would resolve a tag that is genuinely ambiguous fleet-wide and
+ * attribute a whole flow to the wrong capability, silently. So the vocabulary is
+ * the fleet's whole one, read once by the caller.
+ *
+ * AND THE SAME FLOWS ARE GRADED, against everything as the merge would leave it
+ * (`../grade/feature.ts`): the hops against the staged post-merge map, and the
+ * tags against the whole requirement corpus — not the narrowed index above,
+ * because a `#req-` tag naming a capability this feature does not touch is
+ * exactly as broken after the archive as one naming a capability it does.
+ * There REMOVED does subtract: a tag naming a promise this feature retires
+ * resolves to nothing the moment the archive lands.
+ */
+export async function flowCoverage(req) {
+    const vocab = withFeatureCapabilities(req.vocabulary, req.capabilities.map((doc) => doc.id));
+    const byCapability = new Map();
+    for (const doc of req.capabilities) {
+        const ids = new Set();
+        // REMOVED is excluded on both sides — a promise on its way out keeps nothing.
+        for (const r of doc.living)
+            if (r.kind !== "REMOVED" && r.id !== undefined)
+                ids.add(r.id);
+        for (const r of doc.reqs)
+            if ((r.kind === "ADDED" || r.kind === "MODIFIED") && r.id !== undefined)
+                ids.add(r.id);
+        byCapability.set(doc.id, ids);
+    }
+    const scan = await readFeatureFlows({
+        docsDir: req.docsDir,
+        featureDir: req.featureDir,
+        featureId: req.featureId,
+        known: req.known,
+        ...(req.load === undefined ? {} : { load: req.load }),
+        ...(req.models === undefined ? {} : { models: req.models }),
+    });
+    const declared = gradableCapabilityIds(vocab);
+    const promises = featureFlowPromises(scan, { declared, requirementsOf: (capability) => byCapability.get(capability) });
+    if (scan.kind === "unreadable" || scan.views.length === 0)
+        return { promises, issues: [] };
+    const after = new Map((await capabilityRequirementIndex(req.vocabulary, req.read)).byCapability);
+    for (const doc of req.capabilities) {
+        const retired = new Set(doc.reqs
+            .filter((r) => r.kind === "REMOVED")
+            .flatMap((r) => (r.id !== undefined ? [r.id] : doc.living.filter((l) => l.name === r.name).flatMap((l) => (l.id === undefined ? [] : [l.id])))));
+        after.set(doc.id, new Set([...(byCapability.get(doc.id) ?? [])].filter((id) => !retired.has(id))));
+    }
+    return {
+        promises,
+        issues: featureFlowIssues({ docsDir: req.docsDir, scan, capabilities: declared, requirementsOf: (capability) => after.get(capability) }),
+    };
+}
+//# sourceMappingURL=claims.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../../../../src/core/usecases/delta/claims.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which of this feature's own promises its own flows keep.\n *\n * A cross-service criterion — \"I enter a login and a password and I am in\" —\n * belongs to no single service's spec, because each service promises only its\n * own part. A `dynamic view` can carry it, because it IS the hop sequence, and\n * that is the whole reason `#req-` exists. Until `./flows.ts` gave a feature a\n * slot for one, this answer could only ever be empty inside a feature window:\n * the flow was a fleet document, so a tag naming a requirement the same change\n * was adding named something that was not living yet.\n *\n * WHAT THIS FEEDS. `capability.uncovered` — the archive gate that refuses a\n * promise nothing keeps. Its message used to end by telling authors to archive\n * with `--approve` and tag the flow AFTERWARDS, which was honest advice about a\n * hole rather than a workflow anybody wanted: it lands the promise first, kept\n * by nothing, and relies on somebody coming back.\n *\n * THE RULE IS `../capability.ts`'s AND MUST STAY SO. Only a RESOLVED claim\n * counts, and both halves must resolve — the `#cap-` tag to exactly one declared\n * capability, the `#req-` tag to exactly one of its requirements. A broken tag\n * of either kind is already an error (`usecase.capability-unresolved`,\n * `usecase.requirement-unresolved`) and must never also mark a promise kept: a\n * typo that silenced the gate would turn a mistake into a green archive. The two\n * resolvers are called directly rather than through\n * `useCaseRequirementClaims` for one reason, and it is not a difference of\n * opinion about the rule — that function flattens its answer to a `<cap>#<id>`\n * string, and `capabilities/delta/uncovered.ts` keys this same join on NUL\n * precisely because a capability id has no grammar forbidding `#`. Handing it a\n * key it has written down a reason not to use would be the wrong kind of reuse.\n *\n * THE LADDER TRAVELS. `declared === null` — an absent or unreadable\n * `architecture/capabilities.yaml` — is an empty answer, not a suspended one, and\n * the caller is already suppressing the whole family behind it. An `unreadable`\n * overlay is different and must NOT be flattened to \"keeps nothing\": loam did not\n * look, which is never the same answer as \"there is nothing there\", and a gate\n * that refused on it would blame the author for a map it could not read.\n */\nimport type { LoadedDoc } from \"../../c4/likec4.js\";\nimport type { ExtendingModel } from \"../../c4/splice/contract.js\";\nimport type { CapabilityVocabulary } from \"../../capabilities/capabilities.js\";\nimport type { Requirement } from \"../../document/spec.js\";\nimport { withFeatureCapabilities } from \"../../capabilities/delta/overlay.js\";\nimport type { CapabilityDeltaDoc } from \"../../capabilities/delta/uncovered.js\";\nimport { capabilityRequirementIndex, gradableCapabilityIds } from \"../../capabilities/findings.js\";\nimport { resolveCapabilityTags, resolveRequirementTags } from \"../../capabilities/usecase-join.js\";\nimport type { DocsDir, FeatureDir } from \"../../kernel/ids/dirs.js\";\nimport { compareIds } from \"../../repo/entries.js\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport type { UseCaseScan } from \"../fleet.js\";\nimport { featureFlowIssues } from \"../grade/feature.js\";\nimport { readFeatureFlows } from \"./overlay.js\";\n\n/** One promise this feature's flows keep, with the flows that keep it. */\nexport interface FlowPromise {\n  /** The capability the keeping view's `#cap-` tag resolved to. */\n  capability: string;\n  /** The `Requirement-ID` its `#req-` tag resolved to, inside that capability. */\n  requirement: string;\n  /** The view ids keeping it, deduplicated and sorted — message text, never identity. */\n  flows: readonly string[];\n}\n\n/**\n * What the feature's flows keep, or one of the two honest refusals to say.\n *\n * THREE ARMS, because the two failures are not the same failure and a caller\n * that merged them would say the wrong thing. `unreadable` is loam unable to\n * READ the flows — a parse error, a hop naming an element the merge does not\n * land — and it earns `usecase.flow-invalid` and a refusal. `ungraded` is loam\n * able to read them and unable to RESOLVE their tags, because the capability\n * vocabulary this feature's merge would leave behind does not parse; the flows\n * are fine, the file they point into is not, and refusing over the flows would\n * name the wrong document.\n *\n * `read` with an empty `kept` is the ordinary answer and a real one: loam\n * looked, and no flow of this feature keeps a promise it adds.\n */\nexport type FlowPromises =\n  | { kind: \"read\"; kept: readonly FlowPromise[] }\n  | { kind: \"ungraded\"; why: string }\n  | { kind: \"unreadable\"; errors: string[] };\n\n/** Everything the join needs beside the flows themselves. */\nexport interface FlowPromisesRequest {\n  /**\n   * The capability ids to resolve `#cap-` against — the LIVING vocabulary\n   * widened with the ids this feature's own capability deltas introduce, which\n   * is the same both-corpora rule `Realizes:` follows\n   * (`core/capabilities/delta/overlay.ts`). `null` suspends the axis.\n   */\n  declared: readonly string[] | null;\n  /**\n   * The requirement ids per capability, widened the same way\n   * (`withFeatureRequirements`). `undefined` for a capability with no document\n   * at all is a different answer from an empty set, and both are real here.\n   */\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined;\n}\n\n/**\n * The promises this feature's own flows keep, read over the post-merge map.\n *\n * A feature with no flow is `read` with nothing kept, which is the ordinary\n * answer and costs one walk over a directory that is not there. The scan is\n * read by the caller (`flowCoverage`), which grades the same flows too — one\n * staged parse for both questions, because it is a Langium workspace spin.\n */\nexport function featureFlowPromises(scan: UseCaseScan, req: FlowPromisesRequest): FlowPromises {\n  if (scan.kind === \"unreadable\") return { kind: \"unreadable\", errors: scan.errors };\n  // The ladder, and it is `ungraded` rather than an empty answer. Once the\n  // feature's own capability deltas are unioned in, `declared` is null for\n  // exactly one reason — `architecture/capabilities.yaml` exists and does not\n  // read as a vocabulary — so no `#cap-` tag can resolve and no claim can be\n  // made either way. Returning \"keeps nothing\" here is what let\n  // `capability.uncovered` convict a flow that does resolve, over a file the\n  // feature gate reports nothing else about.\n  if (req.declared === null) {\n    return {\n      kind: \"ungraded\",\n      why: \"architecture/capabilities.yaml does not read as a capability vocabulary (`loam validate --all` reports it as capability.invalid)\",\n    };\n  }\n  // A real, empty answer: loam read the flows and none of them claims anything.\n  if (scan.views.length === 0) return { kind: \"read\", kept: [] };\n\n  const byPromise = new Map<string, { promise: FlowPromise; flows: Set<string> }>();\n  for (const view of scan.views) {\n    const scope = resolveCapabilityTags(view.tags, req.declared).flatMap((claim) =>\n      claim.kind === \"resolved\" ? [claim.id] : [],\n    );\n    for (const claim of resolveRequirementTags(view.tags, scope, req.requirementsOf)) {\n      if (claim.kind !== \"resolved\") continue;\n      // Keyed on the pair, never on a joined string: see the header. The Map is\n      // only here to collapse two views keeping one promise into one row.\n      const key = JSON.stringify([claim.capability, claim.id]);\n      const found = byPromise.get(key);\n      if (found === undefined) {\n        byPromise.set(key, {\n          promise: { capability: claim.capability, requirement: claim.id, flows: [] },\n          flows: new Set([view.id]),\n        });\n      } else {\n        found.flows.add(view.id);\n      }\n    }\n  }\n  // Sorted, and the view ids inside each row sorted too: nothing in loam has\n  // measured that LikeC4 preserves view declaration order, so a message built\n  // from it would reorder under a dependency bump.\n  const kept = [...byPromise.values()]\n    .map(({ promise, flows }) => ({ ...promise, flows: [...flows].sort(compareIds) }))\n    .sort((a, b) => compareIds(a.capability, b.capability) || compareIds(a.requirement, b.requirement));\n  return { kind: \"read\", kept };\n}\n\n/** Everything the coverage join needs, and nothing it would have to read twice. */\nexport interface FlowCoverageRequest {\n  docsDir: DocsDir;\n  featureDir: FeatureDir;\n  featureId: string;\n  /**\n   * The feature's capability deltas, ALREADY PARSED by the caller's walk. They\n   * arrive rather than being read because the one caller has just produced them,\n   * and re-reading a document to answer a question about it is how two answers\n   * about one file appear.\n   */\n  capabilities: readonly CapabilityDeltaDoc[];\n  /** The LIVING capability vocabulary, read by the caller through its own index. */\n  vocabulary: CapabilityVocabulary;\n  /** The enumerated fleet, for `readFeatureFlows`' resolver and for its reason. */\n  known: ReadonlySet<string>;\n  /** The caller's memoised LikeC4 read; see `./overlay.ts`. */\n  load?: (path: string) => Promise<LoadedDoc>;\n  /**\n   * How a LIVING capability document's requirements are read — the caller's\n   * memo where it has one. Asked only for the grade below, and only once a\n   * feature really brings a flow: a `#req-` tag may name ANY capability, so\n   * the post-merge index it is resolved in is the whole corpus.\n   */\n  read: (path: string) => Promise<Requirement[]>;\n  /**\n   * The fleet's extending models for the merge preview, as a thunk the overlay\n   * calls only when this feature really brings a flow; see `./overlay.ts` for\n   * why the preview is wrong without them and why it arrives as a function.\n   */\n  models?: () => Promise<readonly ExtendingModel[]>;\n}\n\n/**\n * What this feature's own flows keep, resolved against the vocabulary and the\n * requirement ids its own merge would leave behind.\n *\n * THE WIDENING IS THE POINT, and it is `capabilities/delta/overlay.ts`'s\n * judgement applied to the other carrier: an analyst adds `NOTIFY-ONCE` to a\n * capability delta and an architect answers it with a flow in the same change,\n * so a `#req-` tag resolved against the LIVING tree alone names a promise that\n * does not exist yet — and the same archive that would land the flow lands the\n * promise it points at.\n *\n * `requirementsOf` KNOWS ONLY THE CAPABILITIES THIS FEATURE HAS A DELTA FOR, and\n * within those it carries living ∪ ADDED ∪ MODIFIED ids. The narrowing changes\n * no answer, for a reason stronger than \"it is probably fine\":\n * `uncoveredIssues` grades `r.kind === \"ADDED\"` and nothing else, and every\n * ADDED requirement it grades lives in one of these documents by construction —\n * so no id outside this map can reach a verdict. The LIVING half is in there\n * because a widening of the graded set must not silently need a second edit\n * here; today it decides nothing. A flow keeping a promise of a capability this\n * feature does NOT touch resolves to `undocumented` and counts for nothing,\n * which is correct: the fleet-scope `capability.requirement-unrealized` grades\n * that join over the whole corpus, and answering it here from a partial index is\n * how two surfaces start disagreeing.\n *\n * `declared` IS NOT NARROWED, and that asymmetry is load-bearing. It is what\n * `resolveCapabilityTags` compares a `#cap-` slug against, and a slug is not\n * injective — `payments/refunds` and `payments-refunds` flatten to one. Handing\n * it a short list would resolve a tag that is genuinely ambiguous fleet-wide and\n * attribute a whole flow to the wrong capability, silently. So the vocabulary is\n * the fleet's whole one, read once by the caller.\n *\n * AND THE SAME FLOWS ARE GRADED, against everything as the merge would leave it\n * (`../grade/feature.ts`): the hops against the staged post-merge map, and the\n * tags against the whole requirement corpus — not the narrowed index above,\n * because a `#req-` tag naming a capability this feature does not touch is\n * exactly as broken after the archive as one naming a capability it does.\n * There REMOVED does subtract: a tag naming a promise this feature retires\n * resolves to nothing the moment the archive lands.\n */\nexport async function flowCoverage(req: FlowCoverageRequest): Promise<{ promises: FlowPromises; issues: Issue[] }> {\n  const vocab = withFeatureCapabilities(req.vocabulary, req.capabilities.map((doc) => doc.id));\n  const byCapability = new Map<string, ReadonlySet<string>>();\n  for (const doc of req.capabilities) {\n    const ids = new Set<string>();\n    // REMOVED is excluded on both sides — a promise on its way out keeps nothing.\n    for (const r of doc.living) if (r.kind !== \"REMOVED\" && r.id !== undefined) ids.add(r.id);\n    for (const r of doc.reqs) if ((r.kind === \"ADDED\" || r.kind === \"MODIFIED\") && r.id !== undefined) ids.add(r.id);\n    byCapability.set(doc.id, ids);\n  }\n  const scan = await readFeatureFlows({\n    docsDir: req.docsDir,\n    featureDir: req.featureDir,\n    featureId: req.featureId,\n    known: req.known,\n    ...(req.load === undefined ? {} : { load: req.load }),\n    ...(req.models === undefined ? {} : { models: req.models }),\n  });\n  const declared = gradableCapabilityIds(vocab);\n  const promises = featureFlowPromises(scan, { declared, requirementsOf: (capability) => byCapability.get(capability) });\n  if (scan.kind === \"unreadable\" || scan.views.length === 0) return { promises, issues: [] };\n  const after = new Map((await capabilityRequirementIndex(req.vocabulary, req.read)).byCapability);\n  for (const doc of req.capabilities) {\n    const retired = new Set(\n      doc.reqs\n        .filter((r) => r.kind === \"REMOVED\")\n        .flatMap((r) => (r.id !== undefined ? [r.id] : doc.living.filter((l) => l.name === r.name).flatMap((l) => (l.id === undefined ? [] : [l.id])))),\n    );\n    after.set(doc.id, new Set([...(byCapability.get(doc.id) ?? [])].filter((id) => !retired.has(id))));\n  }\n  return {\n    promises,\n    issues: featureFlowIssues({ docsDir: req.docsDir, scan, capabilities: declared, requirementsOf: (capability) => after.get(capability) }),\n  };\n}\n"]}

package/dist/core/usecases/delta/flows.js

@@ -0,0 +1,101 @@
+/**
+ * A feature's own flows: `features/<FEAT>/usecases/<name>.likec4`.
+ *
+ * A `dynamic view` is the only realizer a cross-service promise has, and until
+ * this slot existed it was the one realizer no feature could carry. Every other
+ * axis had a delta — a C4 delta, a requirement delta on both spec axes, both
+ * contract deltas, a capability delta, a glossary term — so the business axis's
+ * own headline case had to be written backwards: an analyst adds a capability
+ * requirement, the architect answers it with a flow, and the flow could not ship
+ * in that change. It merged only after the promise was already living, which
+ * meant the promise landed first with nothing keeping it.
+ *
+ * CREATE-ONLY, for `core/glossary/delta.ts`'s reasons rather than a weaker
+ * version of them. A capability document is a DELTA because it merges INTO a
+ * living document and two features editing one requirement would otherwise
+ * overwrite each other silently. A flow has none of that: the file is one
+ * ordered hop sequence, the merge is a whole-file copy, and there is nothing to
+ * merge partially. Rewriting a living flow through a feature would be a silent
+ * whole-file replacement with no pin to collide on, where editing
+ * `architecture/usecases/<name>.likec4` directly in the same pull request
+ * produces an ordinary git conflict a human resolves. `usecase.flow-exists`
+ * refuses the first and names the second — the same shape, and the same
+ * severity, as `glossary.term-exists`.
+ *
+ * WHY A FILE OF ITS OWN AND NOT `delta.likec4`. The C4 delta is a MODEL delta:
+ * it re-declares the landscape's own identifiers to anchor its new edges, and it
+ * carries its own `specification` block because LikeC4 parses it standalone.
+ * Both make it unstageable beside the landscape in one project — a duplicate
+ * specification is an error blamed on both files, and a re-declared element is a
+ * duplicate id. A views-only document declares neither, which is exactly why
+ * living use cases already live in files of their own; the feature-local slot
+ * mirrors that layout so the merge is a copy and the overlay is a stage.
+ * `core/c4/splice/delta-blocks.ts` goes on refusing a `dynamic view` inside
+ * `delta.likec4` and now names this slot as the place it belongs.
+ *
+ * ONE CALL for the walk (`relativeDocuments`, which the topology axis in
+ * `core/deployment/delta.ts` shares). `architectureDocuments` already implements "every
+ * `.likec4` under a directory, recursively, in a stable order, and an absent
+ * directory is an empty list" — which is the whole of what a feature's flow
+ * directory is. A second walk would be two implementations free to disagree
+ * about what a flow file is, and they would disagree first about nesting.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { relativeDocuments } from "../../c4/project/documents.js";
+import { architectureDir } from "../../c4/project/architecture.js";
+import { featureUseCasesDir } from "../../repo/authored/paths.js";
+import {} from "../../vocabulary/issue.js";
+/** The directory living flows are filed under, inside `architecture/`. */
+export const USECASE_SUBDIR = "usecases";
+/**
+ * The flows one feature carries, ordered by path.
+ *
+ * Zero readdirs when the feature has no `usecases/` directory, which is every
+ * feature in a fleet that has not adopted the axis: `architectureDocuments`
+ * answers an absent directory with an empty list rather than a throw.
+ */
+export async function featureFlows(featureDir) {
+    return relativeDocuments(featureUseCasesDir(featureDir));
+}
+/**
+ * The LIVING path a feature-local flow addresses. Spelled here because three
+ * readers need it — the refusal below, the archive merge, and the overlay that
+ * grades the flow before either — and a reader resolving it differently would
+ * refuse a flow the merge then wrote anyway.
+ *
+ * `rel` is joined un-split, which `node:path` normalizes. What holds the join is
+ * PROVENANCE, exactly as it holds `livingTermPath` one axis over: every `rel`
+ * here came out of an `architectureDocuments` walk, so each component is a
+ * directory entry that exists. No caller takes one from argv.
+ */
+export function livingFlowPath(docsDir, rel) {
+    return join(architectureDir(docsDir), USECASE_SUBDIR, rel);
+}
+/**
+ * `usecase.flow-exists` — a flow this feature introduces that the living
+ * `architecture/` already holds.
+ *
+ * An ERROR and never a warning-that-gates, for `glossary.term-exists`'s reason:
+ * there is no legal reading of it. The merge would replace an authored flow
+ * wholesale, and no `--approve` makes that a different act than it is. Two
+ * features introducing the same flow is the case that makes it load-bearing
+ * rather than pedantic — whichever archives first creates the living document,
+ * and the second is told before it merges that its own file is the one to
+ * delete.
+ */
+export async function flowDeltaIssues(docsDir, featureDir) {
+    const flows = await featureFlows(featureDir);
+    return flows
+        .filter((flow) => existsSync(livingFlowPath(docsDir, flow.rel)))
+        .map((flow) => ({
+        severity: "error",
+        code: "usecase.flow-exists",
+        subject: flow.rel,
+        message: `architecture/${USECASE_SUBDIR}/${flow.rel} already exists, so this feature's flow would replace an authored one wholesale — ` +
+            "a feature-local flow INTRODUCES a use case, it does not rewrite one. " +
+            `Delete features/<FEAT>/${USECASE_SUBDIR}/${flow.rel} and edit architecture/${USECASE_SUBDIR}/${flow.rel} directly in this same change, ` +
+            "where git produces an ordinary conflict if somebody else is editing it too.",
+    }));
+}
+//# sourceMappingURL=flows.js.map

package/dist/core/usecases/delta/flows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.js","sourceRoot":"","sources":["../../../../src/core/usecases/delta/flows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,OAAO,EAAc,MAAM,2BAA2B,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;AAezC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAsB;IACvD,OAAO,iBAAiB,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,GAAW;IAC1D,OAAO,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAgB,EAAE,UAAsB;IAC5E,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,CAAC;IAC7C,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;SAC/D,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE,OAAgB;QAC1B,IAAI,EAAE,qBAA8B;QACpC,OAAO,EAAE,IAAI,CAAC,GAAG;QACjB,OAAO,EACL,gBAAgB,cAAc,IAAI,IAAI,CAAC,GAAG,oFAAoF;YAC9H,uEAAuE;YACvE,0BAA0B,cAAc,IAAI,IAAI,CAAC,GAAG,0BAA0B,cAAc,IAAI,IAAI,CAAC,GAAG,iCAAiC;YACzI,6EAA6E;KAChF,CAAC,CAAC,CAAC;AACR,CAAC","sourcesContent":["/**\n * A feature's own flows: `features/<FEAT>/usecases/<name>.likec4`.\n *\n * A `dynamic view` is the only realizer a cross-service promise has, and until\n * this slot existed it was the one realizer no feature could carry. Every other\n * axis had a delta — a C4 delta, a requirement delta on both spec axes, both\n * contract deltas, a capability delta, a glossary term — so the business axis's\n * own headline case had to be written backwards: an analyst adds a capability\n * requirement, the architect answers it with a flow, and the flow could not ship\n * in that change. It merged only after the promise was already living, which\n * meant the promise landed first with nothing keeping it.\n *\n * CREATE-ONLY, for `core/glossary/delta.ts`'s reasons rather than a weaker\n * version of them. A capability document is a DELTA because it merges INTO a\n * living document and two features editing one requirement would otherwise\n * overwrite each other silently. A flow has none of that: the file is one\n * ordered hop sequence, the merge is a whole-file copy, and there is nothing to\n * merge partially. Rewriting a living flow through a feature would be a silent\n * whole-file replacement with no pin to collide on, where editing\n * `architecture/usecases/<name>.likec4` directly in the same pull request\n * produces an ordinary git conflict a human resolves. `usecase.flow-exists`\n * refuses the first and names the second — the same shape, and the same\n * severity, as `glossary.term-exists`.\n *\n * WHY A FILE OF ITS OWN AND NOT `delta.likec4`. The C4 delta is a MODEL delta:\n * it re-declares the landscape's own identifiers to anchor its new edges, and it\n * carries its own `specification` block because LikeC4 parses it standalone.\n * Both make it unstageable beside the landscape in one project — a duplicate\n * specification is an error blamed on both files, and a re-declared element is a\n * duplicate id. A views-only document declares neither, which is exactly why\n * living use cases already live in files of their own; the feature-local slot\n * mirrors that layout so the merge is a copy and the overlay is a stage.\n * `core/c4/splice/delta-blocks.ts` goes on refusing a `dynamic view` inside\n * `delta.likec4` and now names this slot as the place it belongs.\n *\n * ONE CALL for the walk (`relativeDocuments`, which the topology axis in\n * `core/deployment/delta.ts` shares). `architectureDocuments` already implements \"every\n * `.likec4` under a directory, recursively, in a stable order, and an absent\n * directory is an empty list\" — which is the whole of what a feature's flow\n * directory is. A second walk would be two implementations free to disagree\n * about what a flow file is, and they would disagree first about nesting.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { relativeDocuments } from \"../../c4/project/documents.js\";\nimport { architectureDir } from \"../../c4/project/architecture.js\";\nimport { featureUseCasesDir } from \"../../repo/authored/paths.js\";\nimport type { DocsDir, FeatureDir } from \"../../kernel/ids/dirs.js\";\nimport { type Issue } from \"../../vocabulary/issue.js\";\n\n/** The directory living flows are filed under, inside `architecture/`. */\nexport const USECASE_SUBDIR = \"usecases\";\n\n/** One flow document a feature carries. */\nexport interface FeatureFlow {\n  /**\n   * The path INSIDE the feature's `usecases/` directory, `/`-separated — the id\n   * this axis has, and the same path the merge writes under\n   * `architecture/usecases/`. Nesting is spelled by the tree, as it is for every\n   * other authored tree in the repo.\n   */\n  rel: string;\n  /** The absolute path of the authored file. */\n  path: string;\n}\n\n/**\n * The flows one feature carries, ordered by path.\n *\n * Zero readdirs when the feature has no `usecases/` directory, which is every\n * feature in a fleet that has not adopted the axis: `architectureDocuments`\n * answers an absent directory with an empty list rather than a throw.\n */\nexport async function featureFlows(featureDir: FeatureDir): Promise<FeatureFlow[]> {\n  return relativeDocuments(featureUseCasesDir(featureDir));\n}\n\n/**\n * The LIVING path a feature-local flow addresses. Spelled here because three\n * readers need it — the refusal below, the archive merge, and the overlay that\n * grades the flow before either — and a reader resolving it differently would\n * refuse a flow the merge then wrote anyway.\n *\n * `rel` is joined un-split, which `node:path` normalizes. What holds the join is\n * PROVENANCE, exactly as it holds `livingTermPath` one axis over: every `rel`\n * here came out of an `architectureDocuments` walk, so each component is a\n * directory entry that exists. No caller takes one from argv.\n */\nexport function livingFlowPath(docsDir: DocsDir, rel: string): string {\n  return join(architectureDir(docsDir), USECASE_SUBDIR, rel);\n}\n\n/**\n * `usecase.flow-exists` — a flow this feature introduces that the living\n * `architecture/` already holds.\n *\n * An ERROR and never a warning-that-gates, for `glossary.term-exists`'s reason:\n * there is no legal reading of it. The merge would replace an authored flow\n * wholesale, and no `--approve` makes that a different act than it is. Two\n * features introducing the same flow is the case that makes it load-bearing\n * rather than pedantic — whichever archives first creates the living document,\n * and the second is told before it merges that its own file is the one to\n * delete.\n */\nexport async function flowDeltaIssues(docsDir: DocsDir, featureDir: FeatureDir): Promise<Issue[]> {\n  const flows = await featureFlows(featureDir);\n  return flows\n    .filter((flow) => existsSync(livingFlowPath(docsDir, flow.rel)))\n    .map((flow) => ({\n      severity: \"error\" as const,\n      code: \"usecase.flow-exists\" as const,\n      subject: flow.rel,\n      message:\n        `architecture/${USECASE_SUBDIR}/${flow.rel} already exists, so this feature's flow would replace an authored one wholesale — ` +\n        \"a feature-local flow INTRODUCES a use case, it does not rewrite one. \" +\n        `Delete features/<FEAT>/${USECASE_SUBDIR}/${flow.rel} and edit architecture/${USECASE_SUBDIR}/${flow.rel} directly in this same change, ` +\n        \"where git produces an ordinary conflict if somebody else is editing it too.\",\n    }));\n}\n"]}

package/dist/core/usecases/delta/modified.js

@@ -0,0 +1,315 @@
+/**
+ * The LIVING flows whose `#req-` tag claims a requirement this feature changes:
+ * `usecase.requirement-modified` for one it rewrites, and
+ * `usecase.requirement-unresolved` for one it takes away.
+ *
+ * THE HOLE. A `#req-` tag joins a flow to one named promise, and the join is by
+ * id. A MODIFIED requirement keeps its id and replaces its whole text, so after
+ * the archive the tag still resolves, every grade of the flow stays green — and
+ * the flow can be drawing exactly the behaviour the new wording forbids: an
+ * event path the requirement now says is gone, a hop through a service it no
+ * longer names. Nothing in loam reads a flow's MEANING, so nothing can say
+ * whether the drawing still keeps the promise. What loam can say is that the
+ * promise moved under it, and it said nothing.
+ *
+ * A WARNING, AND IT NEVER GATES. Rewording a promise a flow keeps is ordinary;
+ * the flow may well still keep it. This names each flow and the requirement, so
+ * the author reads one against the other while the feature is still open — and
+ * redraws the flow in the same change where it no longer holds.
+ *
+ * A REMOVAL IS THE FLEET'S OWN ERROR, ONE ARCHIVE EARLY. The merge deletes the
+ * promise and leaves the tag, so the very next `validate --all` reports the flow
+ * `usecase.requirement-unresolved` — while the feature gate had said nothing and
+ * the archive had exited 0 (the real-fleet review, 2026-10-21). That grade holds
+ * no judgement about the drawing: the tag resolves to nothing, whatever the flow
+ * shows. So it is raised here under the SAME code, at the same severity, with
+ * the VIEW as its subject as at fleet altitude — the fleet's grade predicted,
+ * not a second opinion beside it — and as an error it gates the archive.
+ * `--approve` may walk past it, for `capability.remove-requirement-realized`'s
+ * reason one carrier over: retiring a promise something still claims is the
+ * author's call about the feature, loam reads the flow perfectly well (this is
+ * no `usecase.flow-invalid` blindness), and the living docs then carry exactly
+ * the error this named.
+ *
+ * GRADED AGAINST WHAT THE MERGE LEAVES, not against the REMOVED list. Each
+ * document's after-side is the merge's own fold (`applyRequirementDelta`), so a
+ * removal the same delta re-spells under an id that flattens to the same tag
+ * leaves the tag resolving and earns nothing, exactly as the fleet will grade
+ * it. The same verdict is asked of a MODIFIED: it keeps its id, but
+ * an id this feature adds beside it may flatten to the same tag, and then the
+ * merge breaks the tag too — the error, not the warning, whose "the tag will
+ * still resolve" would be false. And only a claim that resolves TODAY is asked
+ * about: one that is already broken is `validate --all`'s finding now, and
+ * reporting it again here would be one mistake counted twice.
+ *
+ * TWO ALTITUDES, TWO SCOPES — the ones `validate --all` resolves the tag with.
+ * A flow in `architecture/` keeps a BUSINESS promise: its `#req-` tag is scoped
+ * by its `#cap-` tag to a capability document (`core/capabilities/usecase-join.ts`),
+ * so it is asked about the capability requirements this feature changes. A
+ * flow beside a service's model keeps that SERVICE's promise: its `#req-` tag is
+ * scoped by the directory to the ids of that service's spec.md and arch.spec.md
+ * (`commands/validate/service/usecases/tags.ts`), so it is asked about the
+ * service requirements this feature changes there — and only the services the
+ * feature's `specs/` touch can hold one. BOTH documents are that scope, so the
+ * one a touched service carries no delta for is read as it stands: without it
+ * an id the other document also declares would read as gone after the merge,
+ * and gate an archive the fleet then grades green. The feature's own
+ * `usecases/` are not living and are graded against the new text already
+ * (`../grade/feature.ts`).
+ *
+ * WHAT IT COSTS. Nothing, for a feature that modifies and removes no
+ * requirement — which is nearly every feature, and the caller does not call
+ * this then. For one that does, a byte scan for the tag's own spelling
+ * (`req-<slug>`) over the documents that could declare it, the living document
+ * of a touched service's other axis, and a LikeC4 load only for a project one
+ * of them is in: a tag name is one token, so a document without its characters
+ * cannot carry it. A project that does not parse is skipped, not reported —
+ * `validate --all` owns that answer (`usecase.flow-invalid`, `landscape.invalid`),
+ * and a finding about one requirement must not become a second report of a
+ * broken map.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { REQ_TAG_PREFIX, resolveCapabilityTags, resolveRequirementTags, tagSlug, } from "../../capabilities/usecase-join.js";
+import { gradableCapabilityIds } from "../../capabilities/findings.js";
+import { architectureDocuments } from "../../c4/project/documents.js";
+import { architectureProjectDocuments } from "../../c4/project/architecture.js";
+import { applyRequirementDelta, replacementsOf } from "../../document/apply.js";
+import { SPEC_AXES } from "../../repo/paths.js";
+import { compareIds } from "../../repo/entries.js";
+import { useCasesIn } from "../fleet.js";
+import { viewFile } from "../place.js";
+import { readServiceFlows } from "../service/flows.js";
+export async function changedPromiseFlowIssues(req) {
+    const tables = {
+        capability: tableOf(req.capabilities),
+        service: tableOf(await withUntouchedAxes(req)),
+    };
+    const flows = [
+        ...(await fleetFlows(req, changedIds(tables.capability))),
+        ...(await serviceFlows(req, changedIds(tables.service))),
+    ];
+    const issues = [];
+    for (const flow of flows.sort((a, b) => compareIds(a.file, b.file) || compareIds(a.view.id, b.view.id))) {
+        const table = tables[flow.altitude];
+        const after = new Map(resolveRequirementTags(flow.view.tags, flow.scope, (id) => table.merged.get(id)).map((c) => [c.tag, c]));
+        for (const claim of resolveRequirementTags(flow.view.tags, flow.scope, (id) => table.living.get(id))) {
+            if (claim.kind !== "resolved")
+                continue;
+            const change = changeOf(table, claim);
+            if (change === null)
+                continue;
+            // The merge's verdict first, for either change: a MODIFIED keeps its id,
+            // but an id this feature adds beside it can flatten to the same tag, and
+            // then the warning's "the tag will still resolve" would be false.
+            const later = after.get(claim.tag);
+            if (later !== undefined && later.kind !== "resolved")
+                issues.push(brokenIssue(flow, claim, { change, later }));
+            else if (change === "MODIFIES")
+                issues.push(modifiedIssue(flow, claim));
+        }
+    }
+    return issues;
+}
+function changeOf(table, claim) {
+    if (table.modified.get(claim.capability)?.has(claim.id) === true)
+        return "MODIFIES";
+    return table.removed.get(claim.capability)?.has(claim.id) === true ? "REMOVES" : null;
+}
+function whose(flow, claim) {
+    return flow.altitude === "capability" ? `${claim.capability}#${claim.id}` : `${claim.capability}'s requirement ${claim.id}`;
+}
+function modifiedIssue(flow, claim) {
+    return {
+        severity: "warn",
+        code: "usecase.requirement-modified",
+        subject: claim.capability,
+        message: `${flow.file}: flow '${flow.view.id}' is tagged #${claim.tag} — it claims ${whose(flow, claim)}, which this feature MODIFIES. ` +
+            `The tag will still resolve after the archive and nothing grades what the flow draws against the new ` +
+            `wording: read the flow against the replacement, and redraw it in this change if it no longer keeps the promise.`,
+        locations: [{ path: flow.file, role: "primary" }],
+    };
+}
+/**
+ * The tag the merge breaks. Two ways, and each has its own fix: a removal
+ * leaves nothing the tag names, and an id this feature adds can flatten to the
+ * same tag as the one it claims — the only way a MODIFIED, which keeps its id,
+ * can break it at all.
+ */
+function brokenIssue(flow, claim, broken) {
+    const { change, later } = broken;
+    const [why, fix] = later.kind === "many"
+        ? [
+            `${later.ids.length} requirements will flatten to '${later.slug}' (${later.ids.join(", ")}), so nothing in the tag can say which promise the flow keeps`,
+            "rename one of the colliding ids in this change",
+        ]
+        : [
+            "nothing it names is left",
+            "drop the tag (or point it at the promise that replaces this one) in this change, or MODIFY the requirement instead of removing it",
+        ];
+    return {
+        severity: "error",
+        code: "usecase.requirement-unresolved",
+        // The VIEW, as `validate --all` names it once the archive lands — so the
+        // prediction and the outcome are about one thing a reader opens.
+        subject: flow.view.id,
+        message: `${flow.file}: flow '${flow.view.id}' is tagged #${claim.tag} — it claims ${whose(flow, claim)}, which this feature ${change}. ` +
+            `After the archive the tag no longer resolves — ${why} — and \`loam validate --all\` reports this flow with this ` +
+            `same error: ${fix}.`,
+        locations: [{ path: flow.file, role: "primary" }],
+    };
+}
+/**
+ * Each document's table rows. The modified and removed ids are named by the id
+ * the LIVING document gives them — selected by `replacementsOf`, the merge's own
+ * walk, so a MODIFIED or REMOVED written by heading alone still names the id a
+ * tag carries — and the after-side is that same merge's result. A document the
+ * merge would refuse keeps its living ids on both sides and changes nothing:
+ * the delta gate reports it, and nothing here has a true thing to say about a
+ * merge that cannot happen.
+ *
+ * TODAY'S side leaves out a living requirement sitting under a REMOVED heading,
+ * as both fleet indexes do (`capabilityRequirementIndex`, `requirementIdsOf`):
+ * a tag resolving only through one is already the fleet's error. The fold
+ * still runs on the whole living list, because that is the archive's input.
+ */
+function tableOf(docs) {
+    const table = { living: new Map(), merged: new Map(), modified: new Map(), removed: new Map() };
+    for (const doc of docs) {
+        const living = doc.living.filter((r) => r.kind !== "REMOVED");
+        let fold;
+        try {
+            fold = { replaced: replacementsOf([...doc.living], [...doc.reqs]), merged: applyRequirementDelta([...doc.living], [...doc.reqs]) };
+        }
+        catch {
+            fold = { replaced: [], merged: living };
+        }
+        idsInto(table.living, doc.id, living);
+        idsInto(table.merged, doc.id, fold.merged);
+        for (const r of fold.replaced) {
+            if (r.living.id === undefined || (r.kind !== "MODIFIED" && r.kind !== "REMOVED"))
+                continue;
+            const into = r.kind === "MODIFIED" ? table.modified : table.removed;
+            into.set(doc.id, (into.get(doc.id) ?? new Set()).add(r.living.id));
+        }
+    }
+    return table;
+}
+/** A document's ids, unioned into its row — created even when empty, which is the `empty` arm's answer rather than `undocumented`'s. */
+function idsInto(rows, id, reqs) {
+    const ids = rows.get(id) ?? new Set();
+    for (const r of reqs)
+        if (r.id !== undefined)
+            ids.add(r.id);
+    rows.set(id, ids);
+}
+/** The ids each document's delta modifies or removes — what a flow has to mention to be asked about at all. */
+function changedIds(table) {
+    const out = new Map();
+    for (const rows of [table.modified, table.removed]) {
+        for (const [id, ids] of rows)
+            out.set(id, new Set([...(out.get(id) ?? []), ...ids]));
+    }
+    return out;
+}
+/**
+ * The service pairs, plus — for each service whose delta modifies or removes
+ * something — every document of it the feature carries no delta for, as it
+ * stands (`reqs: []`, so it changes nothing and only widens both sides).
+ * `requirementIdsOf` (`commands/validate/service/usecases/usecases.ts`) reads
+ * both documents for a service-local tag, skipping a requirement under a
+ * REMOVED heading; so must this, or a tag the untouched document keeps
+ * resolving reads as broken — and one only a REMOVED entry there answers reads
+ * as kept, though the archive leaves that document as it is.
+ */
+async function withUntouchedAxes(req) {
+    const out = [...req.services];
+    const asked = new Set();
+    // Sequential, and it costs nothing worth racing: a feature names a handful of
+    // services, each read is one memoised document, and most services here
+    // already have both axes in the feature or no second document at all.
+    for (const pair of req.services) {
+        const own = req.services.filter((p) => p.id === pair.id);
+        if (asked.has(pair.id) || !own.some((p) => p.reqs.some((r) => r.kind === "MODIFIED" || r.kind === "REMOVED")))
+            continue;
+        asked.add(pair.id);
+        const paths = await pair.paths();
+        for (const axis of SPEC_AXES) {
+            if (own.some((p) => p.axis === axis.key) || !existsSync(paths[axis.key]))
+                continue;
+            const living = (await req.readRequirements(paths[axis.key])).filter((r) => r.kind !== "REMOVED");
+            out.push({ id: pair.id, reqs: [], living });
+        }
+    }
+    return out;
+}
+/** The tag spellings that could claim one of these ids. */
+function needlesFor(changed) {
+    return [...new Set([...changed.values()].flatMap((ids) => [...ids].map((id) => `${REQ_TAG_PREFIX}${tagSlug(id)}`)))];
+}
+/** Does any of these documents contain one of the tag spellings at all? Unreadable fails closed, as `../fleet.ts`'s gate does. */
+async function mentions(paths, needles) {
+    for (const path of paths) {
+        try {
+            const text = (await readFile(path)).toString("latin1");
+            if (needles.some((needle) => text.includes(needle)))
+                return true;
+        }
+        catch {
+            return true;
+        }
+    }
+    return false;
+}
+async function fleetFlows(req, changed) {
+    // The vocabulary ladder (`core/capabilities/findings.ts`): with nothing
+    // declared no `#cap-` tag resolves, so no fleet flow can be said to claim anything.
+    const declared = gradableCapabilityIds(req.vocabulary);
+    if (changed.size === 0 || declared === null)
+        return [];
+    if (!(await mentions(await architectureProjectDocuments(req.docsDir), needlesFor(changed))))
+        return [];
+    const read = useCasesIn(await req.architecture(), req.known);
+    if (read.kind !== "read")
+        return [];
+    return read.views.map((view) => ({
+        view,
+        file: viewFile(view),
+        scope: resolveCapabilityTags(view.tags, declared).flatMap((c) => (c.kind === "resolved" ? [c.id] : [])),
+        altitude: "capability",
+    }));
+}
+async function serviceFlows(req, changed) {
+    const out = [];
+    for (const [service, ids] of changed) {
+        // Sequential on purpose, for `../fleet.ts`'s gate's reason: nearly every
+        // service answers from one readdir and a byte scan, and the rare one that
+        // opens a workspace should not be raced by the ones that do not need one.
+        const pair = req.services.find((doc) => doc.id === service);
+        if (pair === undefined)
+            continue;
+        const paths = await pair.paths();
+        if (!(await mentions(await architectureDocuments(paths.dir), needlesFor(new Map([[service, ids]])))))
+            continue;
+        const model = await req.serviceModel(paths);
+        if (model.mapUnreadable || model.doc.errors.length > 0)
+            continue;
+        const flows = await readServiceFlows({
+            paths,
+            model: model.doc,
+            known: req.known,
+            ...(model.shape === "extending" && model.project !== null
+                ? { extending: { docsDir: req.docsDir, project: model.project } }
+                : {}),
+        });
+        if (flows.kind !== "read")
+            continue;
+        for (const view of flows.views) {
+            const file = relative(req.docsDir, join(paths.dir, view.sourcePath ?? "model.likec4")).split(/[\\/]/).join("/");
+            out.push({ view, file, scope: [service], altitude: "service" });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=modified.js.map