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

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

@@ -0,0 +1,116 @@
+import { withFeatureCapabilities } from "../../capabilities/delta/overlay.js";
+import { gradableCapabilityIds } from "../../capabilities/findings.js";
+import { resolveCapabilityTags, resolveRequirementTags } from "../../capabilities/usecase-join.js";
+import { compareIds } from "../../repo/entries.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.
+ */
+export async function featureFlowPromises(req) {
+    const scan = await readFeatureFlows(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.
+ */
+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);
+    }
+    return featureFlowPromises({
+        docsDir: req.docsDir,
+        featureDir: req.featureDir,
+        featureId: req.featureId,
+        known: req.known,
+        declared: gradableCapabilityIds(vocab),
+        requirementsOf: (capability) => byCapability.get(capability),
+        ...(req.load === undefined ? {} : { load: req.load }),
+    });
+}
+//# 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 { CapabilityVocabulary } from \"../../capabilities/capabilities.js\";\nimport { withFeatureCapabilities } from \"../../capabilities/delta/overlay.js\";\nimport type { CapabilityDeltaDoc } from \"../../capabilities/delta/uncovered.js\";\nimport { 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 { readFeatureFlows, type FlowOverlayRequest } 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, on top of what the overlay already asks for. */\nexport interface FlowPromisesRequest extends FlowOverlayRequest {\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.\n */\nexport async function featureFlowPromises(req: FlowPromisesRequest): Promise<FlowPromises> {\n  const scan = await readFeatureFlows(req);\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\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 */\nexport async function flowCoverage(req: FlowCoverageRequest): Promise<FlowPromises> {\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  return featureFlowPromises({\n    docsDir: req.docsDir,\n    featureDir: req.featureDir,\n    featureId: req.featureId,\n    known: req.known,\n    declared: gradableCapabilityIds(vocab),\n    requirementsOf: (capability) => byCapability.get(capability),\n    ...(req.load === undefined ? {} : { load: req.load }),\n  });\n}\n"]}

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

@@ -0,0 +1,103 @@
+/**
+ * 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. `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, relative, resolve } from "node:path";
+import { architectureDocuments } 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) {
+    const dir = featureUseCasesDir(featureDir);
+    const paths = await architectureDocuments(dir);
+    const base = resolve(dir);
+    return paths.map((path) => ({ rel: relative(base, path).split(/[\\/]/).join("/"), path }));
+}
+/**
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,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,MAAM,GAAG,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC7F,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. `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, relative, resolve } from \"node:path\";\nimport { architectureDocuments } 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  const dir = featureUseCasesDir(featureDir);\n  const paths = await architectureDocuments(dir);\n  const base = resolve(dir);\n  return paths.map((path) => ({ rel: relative(base, path).split(/[\\\\/]/).join(\"/\"), path }));\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/overlay.js

@@ -0,0 +1,235 @@
+/**
+ * A feature's flows, read against the fleet map AS THIS FEATURE'S MERGE WOULD
+ * LEAVE IT.
+ *
+ * WHY THE POST-MERGE MAP AND NOT THE LIVING ONE. A `dynamic view`'s steps name
+ * elements, and a feature that adds a service adds the element its own flow
+ * draws a hop into. Graded against the LIVING landscape that flow is unresolved
+ * — LikeC4 refuses the document, the project blanks, and loam would report a
+ * hole against a file whose only fault is arriving with the change that makes
+ * it true. Graded against the merge it resolves exactly when the merge lands
+ * the element it names, which is the judgement `core/capabilities/delta/
+ * overlay.ts` takes one axis over and `spec-api.op-undefined` takes one axis
+ * over from that: inside a feature window, the corpus is feature ∪ living.
+ *
+ * IT IS ALSO THE CHECK. The merge preview is the only reading under which "a
+ * flow naming an element the merge does not land" is answerable at all, and
+ * that refusal is why this runs before `loam archive` writes rather than after:
+ * without it a flow is copied into `architecture/` and the NEXT reader's `loam
+ * validate --all` carries the failure, against a document they did not write.
+ *
+ * WHY IT STAGES ITS OWN TREE. `loadProject` copies documents from disk, keyed
+ * on their path relative to a base — so it can be handed neither a landscape
+ * that exists only in memory nor a document living outside `architecture/`, and
+ * both are exactly what this needs. Teaching it to take content would put a
+ * second, rarely-exercised staging rule inside the loader whose docstring
+ * already carries two rules that invert what holds elsewhere. Staging here
+ * costs one copy of a handful of small files and keeps that loader's contract
+ * at one.
+ *
+ * THE PRICE OF THAT CHOICE IS PATHS, and it is paid in `authored` below rather
+ * than left to the caller: every path LikeC4 reports — a parse error's
+ * `sourceFsPath`, a view's `sourcePath` — names this module's temp tree, and a
+ * finding naming a temp directory is a finding nobody can act on. Both are
+ * mapped back to the file the author wrote before anything leaves here.
+ *
+ * FAIL CLOSED, and not silently. Every failure is the `unreadable` arm carrying
+ * LikeC4's own messages: a flow this cannot read is never a flow that grades
+ * clean, which is the asymmetry `../fleet.ts` states for the fleet-scope scan.
+ */
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { loadFile } from "../../c4/likec4.js";
+import { architectureDir } from "../../c4/project/architecture.js";
+import { architectureDocuments } from "../../c4/project/documents.js";
+import { asLoadedDoc, loadProject } from "../../c4/project/load.js";
+import { serviceResolver } from "../../c4/resolve/service.js";
+import { planLandscapeMerge } from "../../c4/splice/landscape-merge.js";
+import { inOrder } from "../../kernel/concurrency.js";
+import { decodeDocument } from "../../kernel/document-bytes.js";
+import { featurePaths, landscapePath, subsystemViewsPath } from "../../repo/paths.js";
+import { isUseCase } from "../fleet.js";
+import { featureFlows, USECASE_SUBDIR } from "./flows.js";
+/**
+ * The flows this feature carries, parsed over the post-merge map — or the
+ * honest refusal to say.
+ *
+ * A feature with no `usecases/` directory is `read` with no views, at the cost
+ * of one walk over a directory that is not there. That is the axis's
+ * per-feature opt-in and the whole price a fleet that has not adopted it pays.
+ */
+export async function readFeatureFlows(req) {
+    const flows = await featureFlows(req.featureDir);
+    if (flows.length === 0) {
+        return { kind: "read", views: [], model: { elements: [], relationships: [], known: req.known }, resolve: (id) => id };
+    }
+    const merged = await mergedLandscape(req);
+    if (merged.kind === "failed")
+        return { kind: "unreadable", errors: [merged.reason] };
+    const arch = architectureDir(req.docsDir);
+    const living = await architectureDocuments(arch, [subsystemViewsPath(req.docsDir)]);
+    const root = await mkdtemp(join(tmpdir(), "loam-flow-"));
+    try {
+        // Staged rel -> the path the AUTHOR wrote, so every message that leaves here
+        // names a file they can open. Built as the tree is staged, because that is
+        // the one moment both spellings are in hand.
+        const authored = new Map();
+        const landscape = resolve(landscapePath(req.docsDir));
+        await inOrder(living, async (path) => {
+            // The living landscape is staged from the merge preview when there is one;
+            // copying it as well would declare every element twice.
+            if (merged.kind === "merged" && resolve(path) === landscape)
+                return null;
+            await stage(root, spell(relative(arch, path)), path, authored);
+            return null;
+        });
+        if (merged.kind === "merged") {
+            const rel = spell(relative(arch, landscape));
+            await write(root, rel, merged.content);
+            authored.set(rel, landscape);
+        }
+        // The feature's own flows LAST, so a flow whose living twin exists wins the
+        // staging rather than colliding with it on view id. That case is already
+        // `usecase.flow-exists` — an error the gate refuses before any merge — and
+        // grading the feature's version is the more useful of the two answers to
+        // give an author who is about to be told to delete the file.
+        const rels = new Set();
+        for (const flow of flows) {
+            const rel = `${USECASE_SUBDIR}/${flow.rel}`;
+            await stage(root, rel, flow.path, authored);
+            rels.add(rel);
+        }
+        return interpret(await loadProjectAt(root), { root, authored, rels, known: req.known });
+    }
+    catch (err) {
+        // The `unreadable` arm is a PROMISE, not a description of the happy path.
+        // Two things under here throw rather than return: `loadProject` refuses an
+        // error it cannot attribute to a document, and every `mkdir`/`copyFile` in
+        // the staging above can fail on a full disk or a denied temp directory. This
+        // function is called from `featureCoherence`, which runs inside `loam
+        // validate --feature` and the archive gate — and the one behaviour a check
+        // added to those may never have is failing the run it was added to
+        // (`../fleet.ts` states the same rule for the fleet-scope scan). So a throw
+        // becomes the same could-not-look answer a parse error already produces,
+        // which the caller turns into `usecase.flow-invalid` and a refusal that
+        // writes nothing.
+        return { kind: "unreadable", errors: [err instanceof Error ? err.message : String(err)] };
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+/** The staged project, loaded the way `loadArchitecture` loads the living one. */
+async function loadProjectAt(root) {
+    return asLoadedDoc(await loadProject(root, await architectureDocuments(root)));
+}
+/**
+ * The staged parse, spelled in authored paths.
+ *
+ * THE FEATURE'S OWN FLOWS ONLY. A living use case is the fleet scan's to report,
+ * and repeating it here would file somebody else's finding against this
+ * feature's gate — the same scoping every other feature-side check keeps.
+ */
+function interpret(doc, staged) {
+    const real = (path) => staged.authored.get(spell(relative(staged.root, path))) ?? path;
+    if (doc.errors.length > 0) {
+        // An error naming no document is LikeC4 declining to attribute one. It still
+        // travels: a hole loam cannot place is still a hole, and dropping it here
+        // would grade the flow clean on the strength of a missing field.
+        return {
+            kind: "unreadable",
+            errors: doc.errors.map((e) => (e.sourceFsPath === undefined ? e.message : `${real(e.sourceFsPath)}: ${e.message}`)),
+        };
+    }
+    // Through `isUseCase`, because `UseCaseScan.views` is documented as the
+    // reserved-tag views ONLY and this is the type's second producer. The
+    // resolvers below filter on the prefix anyway, so no answer changes today —
+    // but `flowsClaiming` and `servicesInFlowsClaiming` take a `UseCaseScan` and
+    // read `scan.views` straight, and the whole point of exporting one predicate
+    // was that a second spelling of the opt-in drifts.
+    const mine = (doc.views ?? [])
+        .filter((view) => view.sourcePath !== undefined && staged.rels.has(view.sourcePath))
+        .filter(isUseCase);
+    return {
+        kind: "read",
+        views: mine.map((view) => ({ ...view, sourcePath: staged.authored.get(view.sourcePath ?? "") ?? view.sourcePath })),
+        model: { elements: doc.elements, relationships: doc.relationships, known: staged.known },
+        resolve: serviceResolver(doc.elements, staged.known),
+    };
+}
+/**
+ * The merge preview, computed with the SAME function `loam archive` commits
+ * with.
+ *
+ * Reusing `planLandscapeMerge` rather than approximating it is what makes this
+ * an answer about the archive rather than a second opinion beside it: an element
+ * placed differently, a tag stripped differently, or a splice refused there and
+ * allowed here would be a flow graded against a map the merge never writes.
+ *
+ * THE PARITY IS THE MERGE, NOT THE WHOLE GATE, and the difference is worth
+ * naming rather than leaving for a reader to discover. `planLandscape` runs one
+ * check BEFORE it computes the merge and this does not: a delta declaring the
+ * feature tag on a specification KIND is refused there, because every element of
+ * that kind inherits the tag and the merge would splice the whole document. Such
+ * a delta reaches `newEls` here unfiltered, so the preview this grades against
+ * is one the archive would never write. It changes no verdict — that archive
+ * refuses either way, before anything is written — and it is recorded because
+ * the next reader to widen either side needs to know the two are not the same
+ * gate.
+ *
+ * A throw is `failed` rather than propagated. Every `LandscapeSpliceError` this
+ * can raise is one `planLandscape` raises again — with its own message, its own
+ * refusal code, and before anything is written — so throwing here would only
+ * decide which of two identical refusals an author reads first.
+ */
+async function mergedLandscape(req) {
+    const deltaPath = featurePaths(req.featureDir).delta;
+    const landscape = landscapePath(req.docsDir);
+    if (!existsSync(deltaPath) || !existsSync(landscape))
+        return { kind: "living" };
+    const delta = await (req.load ?? loadFile)(deltaPath);
+    if (delta.errors.length > 0) {
+        return {
+            kind: "failed",
+            reason: `delta.likec4 has ${delta.errors.length} parse error(s) — a flow cannot be graded against a map that does not parse`,
+        };
+    }
+    try {
+        const plan = await planLandscapeMerge({
+            landscapeText: await text(landscape),
+            deltaText: await text(deltaPath),
+            deltaElements: delta.elements,
+            newEls: delta.elements.filter((e) => e.tags.includes(req.featureId)),
+            newRels: delta.relationships.filter((r) => r.tags.includes(req.featureId)),
+            featureId: req.featureId,
+        });
+        return plan.content === null ? { kind: "living" } : { kind: "merged", content: plan.content };
+    }
+    catch (err) {
+        return { kind: "failed", reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Read a document loam is about to hand LikeC4, refusing the encodings that decode as empty. */
+async function text(path) {
+    return decodeDocument(await readFile(path), path);
+}
+/** A path spelled the way a staged rel is spelled — `/`-separated, on every platform. */
+function spell(path) {
+    return path.split(/[\\/]/).join("/");
+}
+/** Copy one authored document into the staged tree, remembering where it came from. */
+async function stage(root, rel, path, authored) {
+    const dest = join(root, ...rel.split("/"));
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(path, dest);
+    authored.set(rel, resolve(path));
+}
+/** Write one document into the staged tree from bytes loam holds rather than a file. */
+async function write(root, rel, content) {
+    const dest = join(root, ...rel.split("/"));
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, content, "utf8");
+}
+//# sourceMappingURL=overlay.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../../../../src/core/usecases/delta/overlay.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A feature's flows, read against the fleet map AS THIS FEATURE'S MERGE WOULD\n * LEAVE IT.\n *\n * WHY THE POST-MERGE MAP AND NOT THE LIVING ONE. A `dynamic view`'s steps name\n * elements, and a feature that adds a service adds the element its own flow\n * draws a hop into. Graded against the LIVING landscape that flow is unresolved\n * — LikeC4 refuses the document, the project blanks, and loam would report a\n * hole against a file whose only fault is arriving with the change that makes\n * it true. Graded against the merge it resolves exactly when the merge lands\n * the element it names, which is the judgement `core/capabilities/delta/\n * overlay.ts` takes one axis over and `spec-api.op-undefined` takes one axis\n * over from that: inside a feature window, the corpus is feature ∪ living.\n *\n * IT IS ALSO THE CHECK. The merge preview is the only reading under which \"a\n * flow naming an element the merge does not land\" is answerable at all, and\n * that refusal is why this runs before `loam archive` writes rather than after:\n * without it a flow is copied into `architecture/` and the NEXT reader's `loam\n * validate --all` carries the failure, against a document they did not write.\n *\n * WHY IT STAGES ITS OWN TREE. `loadProject` copies documents from disk, keyed\n * on their path relative to a base — so it can be handed neither a landscape\n * that exists only in memory nor a document living outside `architecture/`, and\n * both are exactly what this needs. Teaching it to take content would put a\n * second, rarely-exercised staging rule inside the loader whose docstring\n * already carries two rules that invert what holds elsewhere. Staging here\n * costs one copy of a handful of small files and keeps that loader's contract\n * at one.\n *\n * THE PRICE OF THAT CHOICE IS PATHS, and it is paid in `authored` below rather\n * than left to the caller: every path LikeC4 reports — a parse error's\n * `sourceFsPath`, a view's `sourcePath` — names this module's temp tree, and a\n * finding naming a temp directory is a finding nobody can act on. Both are\n * mapped back to the file the author wrote before anything leaves here.\n *\n * FAIL CLOSED, and not silently. Every failure is the `unreadable` arm carrying\n * LikeC4's own messages: a flow this cannot read is never a flow that grades\n * clean, which is the asymmetry `../fleet.ts` states for the fleet-scope scan.\n */\nimport { existsSync } from \"node:fs\";\nimport { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join, relative, resolve } from \"node:path\";\nimport { loadFile, type LoadedDoc } from \"../../c4/likec4.js\";\nimport { architectureDir } from \"../../c4/project/architecture.js\";\nimport { architectureDocuments } from \"../../c4/project/documents.js\";\nimport { asLoadedDoc, loadProject } from \"../../c4/project/load.js\";\nimport { serviceResolver } from \"../../c4/resolve/service.js\";\nimport { planLandscapeMerge } from \"../../c4/splice/landscape-merge.js\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { decodeDocument } from \"../../kernel/document-bytes.js\";\nimport type { DocsDir, FeatureDir } from \"../../kernel/ids/dirs.js\";\nimport { featurePaths, landscapePath, subsystemViewsPath } from \"../../repo/paths.js\";\nimport { isUseCase, type UseCaseScan } from \"../fleet.js\";\nimport { featureFlows, USECASE_SUBDIR } from \"./flows.js\";\n\n/** Everything the overlay needs, and nothing it would have to read twice. */\nexport interface FlowOverlayRequest {\n  docsDir: DocsDir;\n  featureDir: FeatureDir;\n  /** The feature's id — the tag that selects the delta's own additions. */\n  featureId: string;\n  /**\n   * The enumerated fleet, for the element→service resolver. It rides in for the\n   * reason every other edge join carries it: without it a hop drawn into a\n   * modelled container `payment.api` resolves to a service called \"api\" that\n   * has never existed.\n   */\n  known: ReadonlySet<string>;\n  /**\n   * The caller's memoised LikeC4 read, when it has one. Only `delta.likec4` goes\n   * through it, and only to compute the merge preview — but the caller\n   * (`featureCoherence`) has already loaded that exact document, and loading one\n   * spins a fresh Langium workspace, which `core/coherence/coherence.ts` calls\n   * the dominant per-feature cost.\n   *\n   * A FUNCTION rather than the `FleetContext` itself, deliberately: this package\n   * has no edge to `core/fleet-context.ts`, one memoised read does not justify\n   * adding one, and the edge would push `core/usecases/` up a DAG level for\n   * nothing. Absent, the load happens directly, which is right for a caller\n   * running outside an invocation index.\n   */\n  load?: (path: string) => Promise<LoadedDoc>;\n}\n\n/**\n * The flows this feature carries, parsed over the post-merge map — or the\n * honest refusal to say.\n *\n * A feature with no `usecases/` directory is `read` with no views, at the cost\n * of one walk over a directory that is not there. That is the axis's\n * per-feature opt-in and the whole price a fleet that has not adopted it pays.\n */\nexport async function readFeatureFlows(req: FlowOverlayRequest): Promise<UseCaseScan> {\n  const flows = await featureFlows(req.featureDir);\n  if (flows.length === 0) {\n    return { kind: \"read\", views: [], model: { elements: [], relationships: [], known: req.known }, resolve: (id) => id };\n  }\n  const merged = await mergedLandscape(req);\n  if (merged.kind === \"failed\") return { kind: \"unreadable\", errors: [merged.reason] };\n\n  const arch = architectureDir(req.docsDir);\n  const living = await architectureDocuments(arch, [subsystemViewsPath(req.docsDir)]);\n  const root = await mkdtemp(join(tmpdir(), \"loam-flow-\"));\n  try {\n    // Staged rel -> the path the AUTHOR wrote, so every message that leaves here\n    // names a file they can open. Built as the tree is staged, because that is\n    // the one moment both spellings are in hand.\n    const authored = new Map<string, string>();\n    const landscape = resolve(landscapePath(req.docsDir));\n    await inOrder(living, async (path) => {\n      // The living landscape is staged from the merge preview when there is one;\n      // copying it as well would declare every element twice.\n      if (merged.kind === \"merged\" && resolve(path) === landscape) return null;\n      await stage(root, spell(relative(arch, path)), path, authored);\n      return null;\n    });\n    if (merged.kind === \"merged\") {\n      const rel = spell(relative(arch, landscape));\n      await write(root, rel, merged.content);\n      authored.set(rel, landscape);\n    }\n    // The feature's own flows LAST, so a flow whose living twin exists wins the\n    // staging rather than colliding with it on view id. That case is already\n    // `usecase.flow-exists` — an error the gate refuses before any merge — and\n    // grading the feature's version is the more useful of the two answers to\n    // give an author who is about to be told to delete the file.\n    const rels = new Set<string>();\n    for (const flow of flows) {\n      const rel = `${USECASE_SUBDIR}/${flow.rel}`;\n      await stage(root, rel, flow.path, authored);\n      rels.add(rel);\n    }\n    return interpret(await loadProjectAt(root), { root, authored, rels, known: req.known });\n  } catch (err) {\n    // The `unreadable` arm is a PROMISE, not a description of the happy path.\n    // Two things under here throw rather than return: `loadProject` refuses an\n    // error it cannot attribute to a document, and every `mkdir`/`copyFile` in\n    // the staging above can fail on a full disk or a denied temp directory. This\n    // function is called from `featureCoherence`, which runs inside `loam\n    // validate --feature` and the archive gate — and the one behaviour a check\n    // added to those may never have is failing the run it was added to\n    // (`../fleet.ts` states the same rule for the fleet-scope scan). So a throw\n    // becomes the same could-not-look answer a parse error already produces,\n    // which the caller turns into `usecase.flow-invalid` and a refusal that\n    // writes nothing.\n    return { kind: \"unreadable\", errors: [err instanceof Error ? err.message : String(err)] };\n  } finally {\n    await rm(root, { recursive: true, force: true });\n  }\n}\n\n/** Everything `interpret` needs to turn a staged parse back into authored paths. */\ninterface Staged {\n  root: string;\n  /** Staged rel -> authored absolute path. */\n  authored: Map<string, string>;\n  /** The staged rels that are THIS feature's flows. */\n  rels: ReadonlySet<string>;\n  known: ReadonlySet<string>;\n}\n\n/** The staged project, loaded the way `loadArchitecture` loads the living one. */\nasync function loadProjectAt(root: string): Promise<LoadedDoc> {\n  return asLoadedDoc(await loadProject(root, await architectureDocuments(root)));\n}\n\n/**\n * The staged parse, spelled in authored paths.\n *\n * THE FEATURE'S OWN FLOWS ONLY. A living use case is the fleet scan's to report,\n * and repeating it here would file somebody else's finding against this\n * feature's gate — the same scoping every other feature-side check keeps.\n */\nfunction interpret(doc: LoadedDoc, staged: Staged): UseCaseScan {\n  const real = (path: string): string => staged.authored.get(spell(relative(staged.root, path))) ?? path;\n  if (doc.errors.length > 0) {\n    // An error naming no document is LikeC4 declining to attribute one. It still\n    // travels: a hole loam cannot place is still a hole, and dropping it here\n    // would grade the flow clean on the strength of a missing field.\n    return {\n      kind: \"unreadable\",\n      errors: doc.errors.map((e) => (e.sourceFsPath === undefined ? e.message : `${real(e.sourceFsPath)}: ${e.message}`)),\n    };\n  }\n  // Through `isUseCase`, because `UseCaseScan.views` is documented as the\n  // reserved-tag views ONLY and this is the type's second producer. The\n  // resolvers below filter on the prefix anyway, so no answer changes today —\n  // but `flowsClaiming` and `servicesInFlowsClaiming` take a `UseCaseScan` and\n  // read `scan.views` straight, and the whole point of exporting one predicate\n  // was that a second spelling of the opt-in drifts.\n  const mine = (doc.views ?? [])\n    .filter((view) => view.sourcePath !== undefined && staged.rels.has(view.sourcePath))\n    .filter(isUseCase);\n  return {\n    kind: \"read\",\n    views: mine.map((view) => ({ ...view, sourcePath: staged.authored.get(view.sourcePath ?? \"\") ?? view.sourcePath })),\n    model: { elements: doc.elements, relationships: doc.relationships, known: staged.known },\n    resolve: serviceResolver(doc.elements, staged.known),\n  };\n}\n\n/** What the landscape looks like after this feature's C4 delta is spliced in. */\ntype MergedLandscape =\n  /** The delta adds nothing, or there is none — the living landscape stands. */\n  | { kind: \"living\" }\n  /** The merge preview, as authored bytes. */\n  | { kind: \"merged\"; content: string }\n  /** The merge could not be computed; `planLandscape` owns the refusal and says why. */\n  | { kind: \"failed\"; reason: string };\n\n/**\n * The merge preview, computed with the SAME function `loam archive` commits\n * with.\n *\n * Reusing `planLandscapeMerge` rather than approximating it is what makes this\n * an answer about the archive rather than a second opinion beside it: an element\n * placed differently, a tag stripped differently, or a splice refused there and\n * allowed here would be a flow graded against a map the merge never writes.\n *\n * THE PARITY IS THE MERGE, NOT THE WHOLE GATE, and the difference is worth\n * naming rather than leaving for a reader to discover. `planLandscape` runs one\n * check BEFORE it computes the merge and this does not: a delta declaring the\n * feature tag on a specification KIND is refused there, because every element of\n * that kind inherits the tag and the merge would splice the whole document. Such\n * a delta reaches `newEls` here unfiltered, so the preview this grades against\n * is one the archive would never write. It changes no verdict — that archive\n * refuses either way, before anything is written — and it is recorded because\n * the next reader to widen either side needs to know the two are not the same\n * gate.\n *\n * A throw is `failed` rather than propagated. Every `LandscapeSpliceError` this\n * can raise is one `planLandscape` raises again — with its own message, its own\n * refusal code, and before anything is written — so throwing here would only\n * decide which of two identical refusals an author reads first.\n */\nasync function mergedLandscape(req: FlowOverlayRequest): Promise<MergedLandscape> {\n  const deltaPath = featurePaths(req.featureDir).delta;\n  const landscape = landscapePath(req.docsDir);\n  if (!existsSync(deltaPath) || !existsSync(landscape)) return { kind: \"living\" };\n  const delta = await (req.load ?? loadFile)(deltaPath);\n  if (delta.errors.length > 0) {\n    return {\n      kind: \"failed\",\n      reason: `delta.likec4 has ${delta.errors.length} parse error(s) — a flow cannot be graded against a map that does not parse`,\n    };\n  }\n  try {\n    const plan = await planLandscapeMerge({\n      landscapeText: await text(landscape),\n      deltaText: await text(deltaPath),\n      deltaElements: delta.elements,\n      newEls: delta.elements.filter((e) => e.tags.includes(req.featureId)),\n      newRels: delta.relationships.filter((r) => r.tags.includes(req.featureId)),\n      featureId: req.featureId,\n    });\n    return plan.content === null ? { kind: \"living\" } : { kind: \"merged\", content: plan.content };\n  } catch (err) {\n    return { kind: \"failed\", reason: err instanceof Error ? err.message : String(err) };\n  }\n}\n\n/** Read a document loam is about to hand LikeC4, refusing the encodings that decode as empty. */\nasync function text(path: string): Promise<string> {\n  return decodeDocument(await readFile(path), path);\n}\n\n/** A path spelled the way a staged rel is spelled — `/`-separated, on every platform. */\nfunction spell(path: string): string {\n  return path.split(/[\\\\/]/).join(\"/\");\n}\n\n/** Copy one authored document into the staged tree, remembering where it came from. */\nasync function stage(root: string, rel: string, path: string, authored: Map<string, string>): Promise<void> {\n  const dest = join(root, ...rel.split(\"/\"));\n  await mkdir(dirname(dest), { recursive: true });\n  await copyFile(path, dest);\n  authored.set(rel, resolve(path));\n}\n\n/** Write one document into the staged tree from bytes loam holds rather than a file. */\nasync function write(root: string, rel: string, content: string): Promise<void> {\n  const dest = join(root, ...rel.split(\"/\"));\n  await mkdir(dirname(dest), { recursive: true });\n  await writeFile(dest, content, \"utf8\");\n}\n"]}