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

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

@@ -2,54 +2,22 @@
  * 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.
+ * The staging and the merge preview that make that possible are no longer here:
+ * they moved to `core/c4/project/staged.ts` when the deployment slot became the
+ * second feature-local `.likec4` document, because a second copy of that
+ * machinery is the copy that drifts, and the two would disagree first about the
+ * merge preview — the one thing both axes' refusals rest on. That module's
+ * header carries the WHY of the post-merge corpus; this one keeps what is
+ * particular to use cases, which is the interpretation: which of the staged
+ * views are this feature's, and what they resolve against.
  *
  * 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 {} from "../../c4/likec4.js";
+import { stageMergedProject } from "../../c4/project/staged.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";
 /**
@@ -65,171 +33,44 @@ export async function readFeatureFlows(req) {
     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)));
+    // AFTER the early return, which is what makes the thunk worth its shape: the
+    // fleet read is paid only by a feature that actually brings a flow.
+    const models = req.models === undefined ? undefined : await req.models();
+    const staged = await stageMergedProject({
+        docsDir: req.docsDir,
+        featureDir: req.featureDir,
+        featureId: req.featureId,
+        documents: flows.map((flow) => ({ rel: `${USECASE_SUBDIR}/${flow.rel}`, path: flow.path })),
+        ...(req.load === undefined ? {} : { load: req.load }),
+        ...(models === undefined ? {} : { models }),
+    });
+    return interpret(staged, req.known);
 }
 /**
- * The staged parse, spelled in authored paths.
+ * The staged parse as the use-case axis reads it.
  *
  * 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}`)),
-        };
-    }
+function interpret(staged, known) {
+    if (staged.kind === "unreadable")
+        return { kind: "unreadable", errors: staged.errors };
+    const { doc, real, mine } = staged;
     // 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))
+    const views = (doc.views ?? [])
+        .filter((view) => view.sourcePath !== undefined && mine.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),
+        views: views.map((view) => ({ ...view, sourcePath: view.sourcePath === undefined ? view.sourcePath : real(view.sourcePath) })),
+        model: { elements: doc.elements, relationships: doc.relationships, known },
+        resolve: serviceResolver(doc.elements, 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

@@ -1 +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"]}
+{"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 * The staging and the merge preview that make that possible are no longer here:\n * they moved to `core/c4/project/staged.ts` when the deployment slot became the\n * second feature-local `.likec4` document, because a second copy of that\n * machinery is the copy that drifts, and the two would disagree first about the\n * merge preview — the one thing both axes' refusals rest on. That module's\n * header carries the WHY of the post-merge corpus; this one keeps what is\n * particular to use cases, which is the interpretation: which of the staged\n * views are this feature's, and what they resolve against.\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 { type LoadedDoc } from \"../../c4/likec4.js\";\nimport { stageMergedProject, type StagedProject } from \"../../c4/project/staged.js\";\nimport type { ExtendingModel } from \"../../c4/splice/contract.js\";\nimport { serviceResolver } from \"../../c4/resolve/service.js\";\nimport type { DocsDir, FeatureDir } from \"../../kernel/ids/dirs.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   * The fleet's extending models, for the merge preview — the SAME list\n   * `loam archive` routes with. Without it the preview holds interior the\n   * archive will put in `services/<…>/model.likec4`, so a hop naming\n   * `<service-fqn>.<container>` resolves here and against nothing once the flow\n   * is living: `usecase.flow-invalid` fails open, and it is the gate\n   * `--approve` cannot override (verification 2026-09-04, review F8).\n   *\n   * A THUNK, and both halves of that matter. A function for the reason `load`\n   * is one: the reader takes a `FleetContext` and this package has no edge to\n   * it, so the caller that owns the fleet read supplies the answer. LAZY\n   * because the early return above is the axis's per-feature opt-in — a feature\n   * with no `usecases/` directory must not pay for a fleet enumeration and one\n   * read per extending model to be told there is nothing to grade.\n   */\n  models?: () => Promise<readonly ExtendingModel[]>;\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  // AFTER the early return, which is what makes the thunk worth its shape: the\n  // fleet read is paid only by a feature that actually brings a flow.\n  const models = req.models === undefined ? undefined : await req.models();\n  const staged = await stageMergedProject({\n    docsDir: req.docsDir,\n    featureDir: req.featureDir,\n    featureId: req.featureId,\n    documents: flows.map((flow) => ({ rel: `${USECASE_SUBDIR}/${flow.rel}`, path: flow.path })),\n    ...(req.load === undefined ? {} : { load: req.load }),\n    ...(models === undefined ? {} : { models }),\n  });\n  return interpret(staged, req.known);\n}\n\n/**\n * The staged parse as the use-case axis reads it.\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(staged: StagedProject, known: ReadonlySet<string>): UseCaseScan {\n  if (staged.kind === \"unreadable\") return { kind: \"unreadable\", errors: staged.errors };\n  const { doc, real, mine } = staged;\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 views = (doc.views ?? [])\n    .filter((view) => view.sourcePath !== undefined && mine.has(view.sourcePath))\n    .filter(isUseCase);\n  return {\n    kind: \"read\",\n    views: views.map((view) => ({ ...view, sourcePath: view.sourcePath === undefined ? view.sourcePath : real(view.sourcePath) })),\n    model: { elements: doc.elements, relationships: doc.relationships, known },\n    resolve: serviceResolver(doc.elements, known),\n  };\n}\n"]}