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

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

@@ -0,0 +1,164 @@
+/**
+ * A service's OWN use cases: the `dynamic view`s its LikeC4 project declares,
+ * read the way the renderer reads that project.
+ *
+ * THE SLOT IS THE PROJECT. `loam subsystem sync` writes a
+ * `services/<…>/<svc>/likec4.config.json` that registers every `.likec4` under
+ * the service directory as one LikeC4 project, so the renderer already shows a
+ * `views.likec4` beside the model, or a `usecases/<name>.likec4` under it. loam
+ * reads exactly that set — `model.likec4` plus every sibling, recursively, minus
+ * whatever that project file's own `exclude` drops (`./exclude.ts`) — and
+ * nothing else, because a slot narrower than the renderer's would leave a flow
+ * that renders and is graded by nothing, which is the report this module
+ * answers: an intra-service flow behind an `arch.spec.md` requirement whose
+ * `Covers:` names containers had no home. `architecture/usecases/` is a
+ * separate project that cannot resolve a container (one such file turned a
+ * whole fleet `landscape.invalid`), and the author's workaround beside the
+ * model was invisible to every check. The read is NOT gated on the project
+ * file's presence: that file is create-only and a team may delete it, its
+ * absence has a warning of its own (`service.likec4-config-missing`), and a
+ * flow the renderer cannot show yet is still a flow loam can grade.
+ *
+ * MODEL FACTS STAY SINGLE-FILE. `c4.valid`'s counts, `Covers:` resolution,
+ * `health.dependency-unmodelled` and every other model reader keep the
+ * single-file load the service target already made; the project is loaded here
+ * for the VIEWS and their `sourcePath` only, and only when there is something
+ * to grade. A sibling that declares elements extends what a hop may name, and
+ * that is the renderer's reading too.
+ *
+ * TWO SHAPES, ONE SLOT. A model that stands alone is a project of its own
+ * directory, exactly as above. A model that EXTENDS the fleet map is not: its
+ * containers are declared inside an element the map owns, so a flow beside it
+ * naming one of those containers only resolves in a project that also holds the
+ * map (`c4/service-model/documents.ts`, `serviceFlowDocuments`). That project is
+ * staged from the DOCS ROOT, so every view comes back spelled
+ * `services/<tree>/usecases/x.likec4` — and the service prefix is stripped here,
+ * because every finding this scan feeds names a file relative to the service
+ * directory and a reader must not have to work out which spelling they were
+ * given. The same prefix is the FILTER: the map's own `architecture/usecases/`
+ * flows are in that project too, and without it every service in the fleet would
+ * be graded for every fleet-level use case.
+ *
+ * THE CHEAP GATE, in order, so a fleet without the axis pays one recursive
+ * readdir per service and nothing else:
+ *
+ *  1. no sibling → nothing new is loaded, and the model's own tagged views are
+ *     graded at zero cost against the project the model was READ in. For a
+ *     standalone model that is the single-file load already in hand, which IS
+ *     its whole project; for an extending one it is `ServiceModel.project`, the
+ *     map and this model together — NOT the service's own slice of it, which is
+ *     what the caller passes as `model` and what every count and `Covers:` line
+ *     is answered from. A hop backed by a map edge is backed wherever the view
+ *     is written, and grading the two arms against different documents made one
+ *     view `usecase.step-unbacked` in model.likec4 and clean in a sibling. A
+ *     standalone model's views came back named `source.c4`
+ *     (`core/usecases/place.ts` records the rule) and an extending model's carry
+ *     their docs-relative path, so the file is spelled here, where it is known,
+ *     for both: `model.likec4`;
+ *  2. siblings, no tagged view in the model, and no reserved tag REFERENCED in
+ *     any document — a `#` then `cap-`, `req-` or `suite-` (`mentionsTagPrefix`,
+ *     the fleet's own byte gate) → nothing opted in, no workspace. An untagged
+ *     `views.likec4` is somebody's hand-drawn diagram, never graded, exactly as
+ *     an untagged fleet view is — and its parse errors are the renderer's
+ *     business until a view opts the project in. That includes one whose prose
+ *     names a prefix without the `#` (a title about an e2e-suite job): the gate
+ *     used to open on the bare substring, and such a sibling that did not parse
+ *     became `usecase.flow-invalid` over a diagram that opted nothing in;
+ *  3. otherwise `loadProject` over model + siblings, the way the renderer reads
+ *     them. `own` and the project's views are never merged: when siblings
+ *     exist the project is the whole answer, which is what keeps one view from
+ *     being graded twice.
+ *
+ * A REQUEST RECORD rather than three parameters, for the reason
+ * docs/CODE-STYLE.md gives: the paths, the single-file doc and the fleet set
+ * are only ever passed together, and a caller handing in a doc loaded from
+ * some other path is exactly the inconsistent pair a record makes
+ * unrepresentable.
+ */
+import { relative } from "node:path";
+import { architectureDocuments } from "../../c4/project/documents.js";
+import { asLoadedDoc, loadProject } from "../../c4/project/load.js";
+import { serviceFlowDocuments } from "../../c4/service-model/documents.js";
+import { ARTIFACT_FILES } from "../../repo/paths.js";
+import { isUseCase, mentionsTagPrefix } from "../fleet.js";
+import { keepIncluded, serviceProjectExclude } from "./exclude.js";
+/**
+ * The service's declared use cases, with the model they are drawn over.
+ *
+ * Reads only, throws nothing: every failure is the `unreadable` arm. The caller
+ * has already established that `model.likec4` parses on its own — a project
+ * whose model is broken is `c4.invalid`'s business, and loading it again here
+ * would only repeat that cascade under a second code.
+ */
+export async function readServiceFlows(req) {
+    const found = await architectureDocuments(req.paths.dir, [req.paths.model]);
+    // What the RENDERER holds, for the standalone shape where this directory's
+    // own `likec4.config.json` IS the project config: a sibling its `exclude`
+    // covers is in no project loam may claim to be reading (`./exclude.ts`). The
+    // extending shape reads the root project instead, so its list does not apply
+    // — a per-service config beside an extending model is `service.likec4-config-stray`.
+    const siblings = req.extending === undefined
+        ? keepIncluded(req.paths.dir, await serviceProjectExclude(req.paths.dir), found)
+        : found;
+    // The scope of the no-sibling arm, and it is the PROJECT for both shapes: the
+    // single-file load for a standalone model (which is its whole project), and
+    // the map-plus-model load for an extending one. Reading `req.model` there for
+    // an extending model read its own slice instead, so one view was graded two
+    // different ways depending on which file it was written in.
+    const alone = req.extending?.project ?? req.model;
+    const scope = { elements: alone.elements, relationships: alone.relationships, known: req.known };
+    const own = (req.model.views ?? []).filter(isUseCase);
+    if (siblings.length === 0) {
+        if (own.length === 0)
+            return { kind: "none" };
+        return { kind: "read", views: own.map((view) => ({ ...view, sourcePath: ARTIFACT_FILES.model })), model: scope };
+    }
+    if (own.length === 0 && !(await mentionsTagPrefix(siblings)))
+        return { kind: "none" };
+    const base = req.extending?.docsDir ?? req.paths.dir;
+    const documents = req.extending === undefined
+        ? [req.paths.model, ...siblings]
+        : await serviceFlowDocuments(req.extending.docsDir, req.paths);
+    const project = await loadProject(base, documents);
+    if (!project.clean) {
+        // Each error already carries the real path of its document (`loadProject`
+        // rewrites the staged path back), and the flattening is `asLoadedDoc`'s —
+        // the fleet's own path-sorted order, taken from the one place it is
+        // spelled rather than re-spelled here: the caller names the FIRST broken
+        // file, and a second sort rule would let the service target name a
+        // different first file than the fleet target names for the same project.
+        return { kind: "unreadable", errors: asLoadedDoc(project).errors };
+    }
+    // The prefix the service's own documents are spelled under inside this
+    // project: empty for a standalone model (the project IS the directory, so
+    // every view in it is this service's) and `services/<tree>/` for an extending
+    // one, whose project also holds the whole fleet map.
+    const prefix = req.extending === undefined ? "" : `${relative(base, req.paths.dir).split(/[\\/]/).join("/")}/`;
+    return {
+        kind: "read",
+        views: rebase(project.views.filter(isUseCase), prefix),
+        model: { elements: project.elements, relationships: project.relationships, known: req.known },
+    };
+}
+/**
+ * The views this SERVICE declares, spelled relative to its own directory.
+ *
+ * With an empty prefix — the standalone shape — this is the identity, including
+ * for a view whose `sourcePath` is absent: that project holds nothing but the
+ * service's own files, so there is nothing to attribute and nothing to strip.
+ *
+ * With a prefix, it is both the filter and the rebase, and both halves are one
+ * rule about which document belongs to whom. The project also holds the fleet
+ * map, so `architecture/usecases/checkout.likec4` is in it — and without the
+ * filter every service in the fleet would be graded for every fleet-level use
+ * case. A view carrying no `sourcePath` cannot be attributed at all and is
+ * dropped for the same reason: the path is the only evidence there is.
+ */
+function rebase(views, prefix) {
+    if (prefix === "")
+        return [...views];
+    return views
+        .filter((view) => view.sourcePath?.startsWith(prefix) === true)
+        .map((view) => ({ ...view, sourcePath: (view.sourcePath ?? "").slice(prefix.length) }));
+}
+//# sourceMappingURL=flows.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flows.js","sourceRoot":"","sources":["../../../../src/core/usecases/service/flows.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A service's OWN use cases: the `dynamic view`s its LikeC4 project declares,\n * read the way the renderer reads that project.\n *\n * THE SLOT IS THE PROJECT. `loam subsystem sync` writes a\n * `services/<…>/<svc>/likec4.config.json` that registers every `.likec4` under\n * the service directory as one LikeC4 project, so the renderer already shows a\n * `views.likec4` beside the model, or a `usecases/<name>.likec4` under it. loam\n * reads exactly that set — `model.likec4` plus every sibling, recursively, minus\n * whatever that project file's own `exclude` drops (`./exclude.ts`) — and\n * nothing else, because a slot narrower than the renderer's would leave a flow\n * that renders and is graded by nothing, which is the report this module\n * answers: an intra-service flow behind an `arch.spec.md` requirement whose\n * `Covers:` names containers had no home. `architecture/usecases/` is a\n * separate project that cannot resolve a container (one such file turned a\n * whole fleet `landscape.invalid`), and the author's workaround beside the\n * model was invisible to every check. The read is NOT gated on the project\n * file's presence: that file is create-only and a team may delete it, its\n * absence has a warning of its own (`service.likec4-config-missing`), and a\n * flow the renderer cannot show yet is still a flow loam can grade.\n *\n * MODEL FACTS STAY SINGLE-FILE. `c4.valid`'s counts, `Covers:` resolution,\n * `health.dependency-unmodelled` and every other model reader keep the\n * single-file load the service target already made; the project is loaded here\n * for the VIEWS and their `sourcePath` only, and only when there is something\n * to grade. A sibling that declares elements extends what a hop may name, and\n * that is the renderer's reading too.\n *\n * TWO SHAPES, ONE SLOT. A model that stands alone is a project of its own\n * directory, exactly as above. A model that EXTENDS the fleet map is not: its\n * containers are declared inside an element the map owns, so a flow beside it\n * naming one of those containers only resolves in a project that also holds the\n * map (`c4/service-model/documents.ts`, `serviceFlowDocuments`). That project is\n * staged from the DOCS ROOT, so every view comes back spelled\n * `services/<tree>/usecases/x.likec4` — and the service prefix is stripped here,\n * because every finding this scan feeds names a file relative to the service\n * directory and a reader must not have to work out which spelling they were\n * given. The same prefix is the FILTER: the map's own `architecture/usecases/`\n * flows are in that project too, and without it every service in the fleet would\n * be graded for every fleet-level use case.\n *\n * THE CHEAP GATE, in order, so a fleet without the axis pays one recursive\n * readdir per service and nothing else:\n *\n *  1. no sibling → nothing new is loaded, and the model's own tagged views are\n *     graded at zero cost against the project the model was READ in. For a\n *     standalone model that is the single-file load already in hand, which IS\n *     its whole project; for an extending one it is `ServiceModel.project`, the\n *     map and this model together — NOT the service's own slice of it, which is\n *     what the caller passes as `model` and what every count and `Covers:` line\n *     is answered from. A hop backed by a map edge is backed wherever the view\n *     is written, and grading the two arms against different documents made one\n *     view `usecase.step-unbacked` in model.likec4 and clean in a sibling. A\n *     standalone model's views came back named `source.c4`\n *     (`core/usecases/place.ts` records the rule) and an extending model's carry\n *     their docs-relative path, so the file is spelled here, where it is known,\n *     for both: `model.likec4`;\n *  2. siblings, no tagged view in the model, and no reserved tag REFERENCED in\n *     any document — a `#` then `cap-`, `req-` or `suite-` (`mentionsTagPrefix`,\n *     the fleet's own byte gate) → nothing opted in, no workspace. An untagged\n *     `views.likec4` is somebody's hand-drawn diagram, never graded, exactly as\n *     an untagged fleet view is — and its parse errors are the renderer's\n *     business until a view opts the project in. That includes one whose prose\n *     names a prefix without the `#` (a title about an e2e-suite job): the gate\n *     used to open on the bare substring, and such a sibling that did not parse\n *     became `usecase.flow-invalid` over a diagram that opted nothing in;\n *  3. otherwise `loadProject` over model + siblings, the way the renderer reads\n *     them. `own` and the project's views are never merged: when siblings\n *     exist the project is the whole answer, which is what keeps one view from\n *     being graded twice.\n *\n * A REQUEST RECORD rather than three parameters, for the reason\n * docs/CODE-STYLE.md gives: the paths, the single-file doc and the fleet set\n * are only ever passed together, and a caller handing in a doc loaded from\n * some other path is exactly the inconsistent pair a record makes\n * unrepresentable.\n */\nimport { relative } from \"node:path\";\nimport type { LikeC4Error, LoadedDoc } from \"../../c4/likec4.js\";\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport { architectureDocuments } from \"../../c4/project/documents.js\";\nimport { asLoadedDoc, loadProject } from \"../../c4/project/load.js\";\nimport { serviceFlowDocuments } from \"../../c4/service-model/documents.js\";\nimport type { StepScope } from \"../../c4/resolve/steps.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { ARTIFACT_FILES, type ServicePaths } from \"../../repo/paths.js\";\nimport { isUseCase, mentionsTagPrefix } from \"../fleet.js\";\nimport { keepIncluded, serviceProjectExclude } from \"./exclude.js\";\n\nexport interface ServiceFlowRequest {\n  paths: ServicePaths;\n  /**\n   * The single-file load the service target already made and has verified\n   * parses. Its views are the project when no sibling exists; its elements are\n   * the model a no-sibling flow is graded over.\n   */\n  model: LoadedDoc;\n  /** The enumerated fleet, for `serviceResolver`'s reason: without it a container resolves to a service that has never existed. */\n  known: ReadonlySet<string>;\n  /**\n   * Set only when this model EXTENDS the fleet map, and then both halves of it\n   * — a record rather than two optional fields, for docs/CODE-STYLE.md's reason:\n   * they are only ever passed together, and a caller that supplied one without\n   * the other is exactly the inconsistent pair a record makes unrepresentable.\n   *\n   * `docsDir` decides which documents the sibling project holds (the map as\n   * well, or the directory alone) and which root they are staged from, and\n   * therefore how LikeC4 spells every `sourcePath` that comes back.\n   *\n   * `project` is the per-service project the model was READ in — the map plus\n   * this model (`ServiceModel.project`) — and it is the scope a hop resolves\n   * against when there is no sibling file. `model` above is then the service's\n   * own SLICE of that project, which is the right answer for every count and\n   * every `Covers:` line and the wrong one here: a hop backed by a MAP edge is\n   * backed, and grading it against the slice reported `usecase.step-unbacked`\n   * (exit 1) for a view in model.likec4 that was clean the moment the same view\n   * moved to a sibling file, where the loaded project holds the map. One\n   * question, two answers, decided by which file the author happened to write\n   * the view in.\n   *\n   * Absent means the standalone shape — the service directory is the project and\n   * the single-file load IS that project, exactly as it has always been.\n   */\n  extending?: { docsDir: DocsDir; project: LoadedDoc };\n}\n\n/**\n * What a service's flows are, or the honest refusal to say.\n *\n * Three variants rather than a record with flags, for `UseCaseScan`'s reason\n * one package up: a project that did not parse has no elements to resolve\n * against and no views to grade, and a caller handed `{ views: [], unreadable:\n * true }` is one `.length` check away from reporting a service as flow-free\n * when nobody could read it. `none` is the gate's answer — nothing opted in,\n * nothing was loaded — and it is distinct from `read` with no views (a project\n * that writes a reserved tag reference only outside a view — in a comment, or\n * on an element — and so declares no tagged view), because only the second one\n * cost a workspace.\n */\nexport type ServiceFlowScan =\n  | { kind: \"none\" }\n  | {\n      kind: \"read\";\n      /** The reserved-tag views ONLY, each carrying a `sourcePath` relative to the SERVICE directory. */\n      views: ParsedView[];\n      /** What a hop is attributed against — `known` required, as `UseCaseScan.model` requires it. */\n      model: StepScope & { known: ReadonlySet<string> };\n    }\n  | {\n      kind: \"unreadable\";\n      /**\n       * Every error the project raised, each carrying the real absolute path of\n       * the document that raised it, sorted by that path — so a caller can name\n       * the file, and a project with two broken documents reports them in a\n       * stable order.\n       */\n      errors: LikeC4Error[];\n    };\n\n/**\n * The service's declared use cases, with the model they are drawn over.\n *\n * Reads only, throws nothing: every failure is the `unreadable` arm. The caller\n * has already established that `model.likec4` parses on its own — a project\n * whose model is broken is `c4.invalid`'s business, and loading it again here\n * would only repeat that cascade under a second code.\n */\nexport async function readServiceFlows(req: ServiceFlowRequest): Promise<ServiceFlowScan> {\n  const found = await architectureDocuments(req.paths.dir, [req.paths.model]);\n  // What the RENDERER holds, for the standalone shape where this directory's\n  // own `likec4.config.json` IS the project config: a sibling its `exclude`\n  // covers is in no project loam may claim to be reading (`./exclude.ts`). The\n  // extending shape reads the root project instead, so its list does not apply\n  // — a per-service config beside an extending model is `service.likec4-config-stray`.\n  const siblings =\n    req.extending === undefined\n      ? keepIncluded(req.paths.dir, await serviceProjectExclude(req.paths.dir), found)\n      : found;\n  // The scope of the no-sibling arm, and it is the PROJECT for both shapes: the\n  // single-file load for a standalone model (which is its whole project), and\n  // the map-plus-model load for an extending one. Reading `req.model` there for\n  // an extending model read its own slice instead, so one view was graded two\n  // different ways depending on which file it was written in.\n  const alone = req.extending?.project ?? req.model;\n  const scope = { elements: alone.elements, relationships: alone.relationships, known: req.known };\n  const own = (req.model.views ?? []).filter(isUseCase);\n  if (siblings.length === 0) {\n    if (own.length === 0) return { kind: \"none\" };\n    return { kind: \"read\", views: own.map((view) => ({ ...view, sourcePath: ARTIFACT_FILES.model })), model: scope };\n  }\n  if (own.length === 0 && !(await mentionsTagPrefix(siblings))) return { kind: \"none\" };\n\n  const base = req.extending?.docsDir ?? req.paths.dir;\n  const documents =\n    req.extending === undefined\n      ? [req.paths.model, ...siblings]\n      : await serviceFlowDocuments(req.extending.docsDir, req.paths);\n  const project = await loadProject(base, documents);\n  if (!project.clean) {\n    // Each error already carries the real path of its document (`loadProject`\n    // rewrites the staged path back), and the flattening is `asLoadedDoc`'s —\n    // the fleet's own path-sorted order, taken from the one place it is\n    // spelled rather than re-spelled here: the caller names the FIRST broken\n    // file, and a second sort rule would let the service target name a\n    // different first file than the fleet target names for the same project.\n    return { kind: \"unreadable\", errors: asLoadedDoc(project).errors };\n  }\n  // The prefix the service's own documents are spelled under inside this\n  // project: empty for a standalone model (the project IS the directory, so\n  // every view in it is this service's) and `services/<tree>/` for an extending\n  // one, whose project also holds the whole fleet map.\n  const prefix = req.extending === undefined ? \"\" : `${relative(base, req.paths.dir).split(/[\\\\/]/).join(\"/\")}/`;\n  return {\n    kind: \"read\",\n    views: rebase(project.views.filter(isUseCase), prefix),\n    model: { elements: project.elements, relationships: project.relationships, known: req.known },\n  };\n}\n\n/**\n * The views this SERVICE declares, spelled relative to its own directory.\n *\n * With an empty prefix — the standalone shape — this is the identity, including\n * for a view whose `sourcePath` is absent: that project holds nothing but the\n * service's own files, so there is nothing to attribute and nothing to strip.\n *\n * With a prefix, it is both the filter and the rebase, and both halves are one\n * rule about which document belongs to whom. The project also holds the fleet\n * map, so `architecture/usecases/checkout.likec4` is in it — and without the\n * filter every service in the fleet would be graded for every fleet-level use\n * case. A view carrying no `sourcePath` cannot be attributed at all and is\n * dropped for the same reason: the path is the only evidence there is.\n */\nfunction rebase(views: readonly ParsedView[], prefix: string): ParsedView[] {\n  if (prefix === \"\") return [...views];\n  return views\n    .filter((view) => view.sourcePath?.startsWith(prefix) === true)\n    .map((view) => ({ ...view, sourcePath: (view.sourcePath ?? \"\").slice(prefix.length) }));\n}\n"]}

package/dist/core/usecases/suites/participants.js

@@ -0,0 +1,83 @@
+import { ancestorIds } from "../../kernel/ids/fqn/ancestors.js";
+import { compareIds } from "../../repo/entries.js";
+import { EXTERNAL_TAG } from "../../vocabulary/maturity.js";
+/**
+ * Every endpoint the views' steps draw, resolved through the scan's ONE
+ * element→service resolver — the resolver `attributeStep` grades the same hops
+ * with, built over the same enumerated fleet (`readUseCases`). A second
+ * resolver here could not disagree today and would be a second place to change.
+ *
+ * AN ENDPOINT THAT RESOLVES TO NO ENUMERATED SERVICE IS REPORTED, NEVER DROPPED.
+ * This answer is what a test environment is provisioned from, and a silently
+ * shorter list is the one failure that cannot be seen from the list itself: the
+ * stand comes up, the missing participant is simply absent, and the journey
+ * fails against something nobody was told to start. The actor who begins a
+ * flow, a topic in the middle, a partner's API — each is named here, so the
+ * reader decides whether it needs a double, a fixture or a directory. The
+ * caller that only wants seeds (`servicesInFlowsClaiming`) reads `services` and
+ * ignores the rest, which is a choice it can see itself making.
+ *
+ * Sorted with compareIds rather than in step order: a union has no document
+ * order to preserve, and a payload ordered by LikeC4's record order would
+ * reorder under a dependency bump.
+ */
+export function participantsOf(scan, views) {
+    const known = scan.model.known;
+    const services = new Set();
+    const unresolved = new Set();
+    for (const view of views) {
+        for (const step of view.steps) {
+            for (const id of [step.source, step.target]) {
+                const service = scan.resolve(id);
+                if (known.has(service))
+                    services.add(service);
+                else
+                    unresolved.add(id);
+            }
+        }
+    }
+    const byId = new Map(scan.model.elements.map((e) => [e.id, e]));
+    return {
+        services: [...services].sort(compareIds),
+        unresolved: [...unresolved].sort(compareIds).map((element) => ({ element, external: isExternal(element, byId, known) })),
+    };
+}
+/**
+ * `#external` on the element or on anything it is drawn inside — up to, and
+ * including, the first element that stands for a service.
+ *
+ * The walk is `core/gate/partners.ts`' reading of the same tag (`endFacts`),
+ * stop included, so `list suites` and the gate cannot disagree about whether
+ * an endpoint is ours. Walking up is what is true for a stand: `stripe.api`
+ * drawn inside an `#external` `stripe` is somebody else's endpoint whether or
+ * not the container repeats the tag, and LikeC4 does not inherit tags
+ * downward, so reading the element's own tags alone would print "ours, with no
+ * directory" over a partner's API. Stopping is just as true: an element bound
+ * with `metadata { service '<id>' }`, or titled for a real `services/<id>/`,
+ * IS a service, and what sits above it is a grouping whose `#external` is the
+ * grouping's claim, not the service's. Without the stop a service bound inside
+ * an `#external` zone and not yet given a directory was printed as "bring a
+ * double" while the gate graded it as ours. The tag on that element itself is
+ * read before the stop, as the gate reads it.
+ *
+ * "Stands for a service" is `commands/validate/fleet/census.ts`'
+ * `standsForService`, spelled here rather than imported because core may not
+ * reach into commands — as `core/gate/partners.ts` spells it, and as
+ * `core/c4/resolve/systems.ts` does for the feature-scope graders.
+ *
+ * A tag a KIND declares (`element topic { #external }`) arrives on every element
+ * of that kind in the parsed model, so a topic counts without repeating it.
+ */
+function isExternal(element, byId, known) {
+    for (const id of ancestorIds(element)) {
+        const e = byId.get(id);
+        if (e === undefined)
+            continue;
+        if (e.tags.includes(EXTERNAL_TAG))
+            return true;
+        if (e.service !== undefined || known.has(e.title))
+            return false;
+    }
+    return false;
+}
+//# sourceMappingURL=participants.js.map

package/dist/core/usecases/suites/participants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"participants.js","sourceRoot":"","sources":["../../../../src/core/usecases/suites/participants.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AA2B5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAc,EAAE,KAA4B;IACzE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC/B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,KAAK,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;gBACjC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;oBAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;;oBACzC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO;QACL,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;QACxC,UAAU,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;KACzH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAS,UAAU,CAAC,OAAe,EAAE,IAA+B,EAAE,KAA0B;IAC9F,KAAK,MAAM,EAAE,IAAI,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/C,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IAClE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["/**\n * Who takes part in a set of use cases — the union a test environment is built\n * from, and the participants that union cannot place.\n *\n * It began as `servicesInFlowsClaiming` in `../capability.ts`, which answered\n * the same question for the flows claiming one capability and kept only the\n * half `loam explore` needed: the enumerated services. A suite asks it of a\n * different set of views — the ones carrying one `#suite-` tag — and needs the\n * other half too, so the walk moved here and grew a second output rather than\n * being written twice. Two walks over \"which services does this flow touch\"\n * would be two answers to the question a test stand is provisioned from.\n *\n * THE DEPENDENCY RUNS PARENT → CHILD, never back. `../capability.ts` and\n * `../fleet.ts` (which takes the suite prefix from `./suites.ts`) import this\n * package, so nothing here may value-import `core/usecases/` — the package\n * graph would close a cycle `import/no-cycle` cannot see (docs/DESIGN.md rule\n * 21). `UseCaseScan` crosses as a TYPE only, which erases.\n */\nimport type { Elem } from \"../../c4/likec4.js\";\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport { ancestorIds } from \"../../kernel/ids/fqn/ancestors.js\";\nimport { compareIds } from \"../../repo/entries.js\";\nimport { EXTERNAL_TAG } from \"../../vocabulary/maturity.js\";\nimport type { UseCaseScan } from \"../fleet.js\";\n\n/** A scan that read — the only kind with elements to resolve against. */\nexport type ReadScan = Extract<UseCaseScan, { kind: \"read\" }>;\n\n/** A participant the element→service join could not land on an enumerated service. */\nexport interface UnresolvedParticipant {\n  /** The element id a step drew, exactly as the view spells it. */\n  element: string;\n  /**\n   * Does the element, or anything it is drawn inside short of a service, carry\n   * `#external`? Then it is deliberately not the fleet's, and a stand needs a\n   * double for it rather than a directory. See `isExternal` for why an\n   * ancestor's tag counts and why the walk stops at a service.\n   */\n  external: boolean;\n}\n\n/** The union of a set of views' participants, split by whether the fleet can stand each one up. */\nexport interface Participants {\n  /** Enumerated service ids, sorted and deduplicated. */\n  services: string[];\n  /** Everything else the steps drew, one entry per element id, sorted by it. */\n  unresolved: UnresolvedParticipant[];\n}\n\n/**\n * Every endpoint the views' steps draw, resolved through the scan's ONE\n * element→service resolver — the resolver `attributeStep` grades the same hops\n * with, built over the same enumerated fleet (`readUseCases`). A second\n * resolver here could not disagree today and would be a second place to change.\n *\n * AN ENDPOINT THAT RESOLVES TO NO ENUMERATED SERVICE IS REPORTED, NEVER DROPPED.\n * This answer is what a test environment is provisioned from, and a silently\n * shorter list is the one failure that cannot be seen from the list itself: the\n * stand comes up, the missing participant is simply absent, and the journey\n * fails against something nobody was told to start. The actor who begins a\n * flow, a topic in the middle, a partner's API — each is named here, so the\n * reader decides whether it needs a double, a fixture or a directory. The\n * caller that only wants seeds (`servicesInFlowsClaiming`) reads `services` and\n * ignores the rest, which is a choice it can see itself making.\n *\n * Sorted with compareIds rather than in step order: a union has no document\n * order to preserve, and a payload ordered by LikeC4's record order would\n * reorder under a dependency bump.\n */\nexport function participantsOf(scan: ReadScan, views: readonly ParsedView[]): Participants {\n  const known = scan.model.known;\n  const services = new Set<string>();\n  const unresolved = new Set<string>();\n  for (const view of views) {\n    for (const step of view.steps) {\n      for (const id of [step.source, step.target]) {\n        const service = scan.resolve(id);\n        if (known.has(service)) services.add(service);\n        else unresolved.add(id);\n      }\n    }\n  }\n  const byId = new Map(scan.model.elements.map((e) => [e.id, e]));\n  return {\n    services: [...services].sort(compareIds),\n    unresolved: [...unresolved].sort(compareIds).map((element) => ({ element, external: isExternal(element, byId, known) })),\n  };\n}\n\n/**\n * `#external` on the element or on anything it is drawn inside — up to, and\n * including, the first element that stands for a service.\n *\n * The walk is `core/gate/partners.ts`' reading of the same tag (`endFacts`),\n * stop included, so `list suites` and the gate cannot disagree about whether\n * an endpoint is ours. Walking up is what is true for a stand: `stripe.api`\n * drawn inside an `#external` `stripe` is somebody else's endpoint whether or\n * not the container repeats the tag, and LikeC4 does not inherit tags\n * downward, so reading the element's own tags alone would print \"ours, with no\n * directory\" over a partner's API. Stopping is just as true: an element bound\n * with `metadata { service '<id>' }`, or titled for a real `services/<id>/`,\n * IS a service, and what sits above it is a grouping whose `#external` is the\n * grouping's claim, not the service's. Without the stop a service bound inside\n * an `#external` zone and not yet given a directory was printed as \"bring a\n * double\" while the gate graded it as ours. The tag on that element itself is\n * read before the stop, as the gate reads it.\n *\n * \"Stands for a service\" is `commands/validate/fleet/census.ts`'\n * `standsForService`, spelled here rather than imported because core may not\n * reach into commands — as `core/gate/partners.ts` spells it, and as\n * `core/c4/resolve/systems.ts` does for the feature-scope graders.\n *\n * A tag a KIND declares (`element topic { #external }`) arrives on every element\n * of that kind in the parsed model, so a topic counts without repeating it.\n */\nfunction isExternal(element: string, byId: ReadonlyMap<string, Elem>, known: ReadonlySet<string>): boolean {\n  for (const id of ancestorIds(element)) {\n    const e = byId.get(id);\n    if (e === undefined) continue;\n    if (e.tags.includes(EXTERNAL_TAG)) return true;\n    if (e.service !== undefined || known.has(e.title)) return false;\n  }\n  return false;\n}\n"]}

package/dist/core/usecases/suites/suites.js

@@ -0,0 +1,45 @@
+import { compareIds } from "../../repo/entries.js";
+import { participantsOf } from "./participants.js";
+/**
+ * The reserved tag prefix, matched EXACTLY — case included — as `cap-` and
+ * `req-` are. Exported for `../fleet.ts`, where it joins the other two in the
+ * one opt-in predicate and the one byte gate in front of it.
+ */
+export const SUITE_TAG_PREFIX = "suite-";
+/**
+ * The suite names one view declares: the tags with the prefix stripped,
+ * deduplicated and sorted.
+ *
+ * A bare `#suite-` is a suite named `''` and is KEPT, for the reason a bare
+ * `#cap-` stays a claim: the prefix is the opt-in however little follows it,
+ * and a view that asked to be in a suite must not silently be in none.
+ */
+function suiteNames(view) {
+    const names = view.tags.filter((tag) => tag.startsWith(SUITE_TAG_PREFIX)).map((tag) => tag.slice(SUITE_TAG_PREFIX.length));
+    return [...new Set(names)].sort(compareIds);
+}
+/**
+ * Group the scan's use cases by suite.
+ *
+ * The order is by (document, view id). `../place.ts`' `viewFile` is how a
+ * document is SPELLED, and it only prefixes `sourcePath` with a constant, so
+ * ordering on `sourcePath` itself orders identically without pointing this
+ * package back at its parent.
+ */
+export function suiteListing(scan) {
+    const ordered = [...scan.views].sort((a, b) => compareIds(a.sourcePath ?? "", b.sourcePath ?? "") || compareIds(a.id, b.id));
+    const byName = new Map();
+    const ungrouped = [];
+    for (const view of ordered) {
+        const names = suiteNames(view);
+        if (names.length === 0)
+            ungrouped.push(view);
+        for (const name of names)
+            byName.set(name, [...(byName.get(name) ?? []), view]);
+    }
+    const suites = [...byName]
+        .sort(([a], [b]) => compareIds(a, b))
+        .map(([name, views]) => ({ name, views, ...participantsOf(scan, views) }));
+    return { suites, ungrouped };
+}
+//# sourceMappingURL=suites.js.map

package/dist/core/usecases/suites/suites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suites.js","sourceRoot":"","sources":["../../../../src/core/usecases/suites/suites.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAA6C,MAAM,mBAAmB,CAAC;AAE9F;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAEzC;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,IAAiC;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3H,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAC9C,CAAC;AA6BD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAClC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CACvF,CAAC;IACF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC/C,MAAM,SAAS,GAAiB,EAAE,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC;SACvB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;SACpC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7E,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC","sourcesContent":["/**\n * Suites: which use cases run together, and what a run of one needs standing up.\n *\n * A use case joins a suite by carrying a `#suite-<name>` tag on its `dynamic\n * view`. A TAG rather than a directory, because suites are many-to-many — one\n * journey belongs to the smoke suite and the payments suite at once — and a\n * directory gives exactly one group. The tag also buys the typo check for free:\n * LikeC4 refuses an undeclared tag, so a suite declared once in the landscape's\n * `specification` block makes a mistyped suite a parse error, where a mistyped\n * directory would silently open a second, empty suite.\n *\n * A SEPARATE PREFIX, not `#cap-`. A capability says what a flow is FOR and may\n * be claimed once per meaning; a suite says what a flow is RUN WITH, and a\n * flow is routinely in several. Reusing the capability tag would make every\n * suite a business promise and every smoke run a capability, and the `#cap-`\n * resolution ladder (`../../capabilities/usecase-join.ts`) would convict every\n * suite name the vocabulary does not declare. The prefix also keeps the tag\n * clear of the feature-id grammar: a view tag is never read as a `#FEAT-`\n * marker (feature tags are read off elements and relationships only), and no\n * other reserved prefix — `cap-`, `req-`, `obl-` — is a prefix of this one or\n * has it as a prefix, so no tag can be claimed by two readers.\n *\n * TAGGING IS THE OPT-IN, and that is the owner's call recorded in SCHEMA.md: a\n * view carrying only `#suite-` tags IS a use case — `../fleet.ts`' `isUseCase`\n * admits it — and is graded hop by hop like any other. Nothing here grades; this\n * module groups the views the scan already admitted.\n *\n * Depends on its parent by TYPE only — `./participants.ts` says why the value\n * direction is parent → child.\n */\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport { compareIds } from \"../../repo/entries.js\";\nimport { participantsOf, type ReadScan, type UnresolvedParticipant } from \"./participants.js\";\n\n/**\n * The reserved tag prefix, matched EXACTLY — case included — as `cap-` and\n * `req-` are. Exported for `../fleet.ts`, where it joins the other two in the\n * one opt-in predicate and the one byte gate in front of it.\n */\nexport const SUITE_TAG_PREFIX = \"suite-\";\n\n/**\n * The suite names one view declares: the tags with the prefix stripped,\n * deduplicated and sorted.\n *\n * A bare `#suite-` is a suite named `''` and is KEPT, for the reason a bare\n * `#cap-` stays a claim: the prefix is the opt-in however little follows it,\n * and a view that asked to be in a suite must not silently be in none.\n */\nfunction suiteNames(view: { tags: readonly string[] }): string[] {\n  const names = view.tags.filter((tag) => tag.startsWith(SUITE_TAG_PREFIX)).map((tag) => tag.slice(SUITE_TAG_PREFIX.length));\n  return [...new Set(names)].sort(compareIds);\n}\n\n/** One suite: its name, its use cases, and the environment their union needs. */\nexport interface Suite {\n  /** The tag without `#suite-` — what `loam list suites <name>` takes. */\n  name: string;\n  /** The use cases carrying the tag, ordered by (document, view id). */\n  views: ParsedView[];\n  /** The enumerated services those use cases draw — what must be up. */\n  services: string[];\n  /** Participants that resolve to no enumerated service — named, never dropped. */\n  unresolved: UnresolvedParticipant[];\n}\n\n/** Every suite the fleet's use cases declare, and the use cases in none. */\nexport interface SuiteListing {\n  /** Sorted by name. */\n  suites: Suite[];\n  /**\n   * The use cases carrying no `#suite-` tag, ordered by (document, view id).\n   *\n   * Answered because everything else here is per-suite: a journey in no suite\n   * is absent from every suite's list, which is the one absence a per-suite\n   * output cannot show. Legal and normal — an unfiled service is the same shape\n   * — so it is named and never graded.\n   */\n  ungrouped: ParsedView[];\n}\n\n/**\n * Group the scan's use cases by suite.\n *\n * The order is by (document, view id). `../place.ts`' `viewFile` is how a\n * document is SPELLED, and it only prefixes `sourcePath` with a constant, so\n * ordering on `sourcePath` itself orders identically without pointing this\n * package back at its parent.\n */\nexport function suiteListing(scan: ReadScan): SuiteListing {\n  const ordered = [...scan.views].sort(\n    (a, b) => compareIds(a.sourcePath ?? \"\", b.sourcePath ?? \"\") || compareIds(a.id, b.id),\n  );\n  const byName = new Map<string, ParsedView[]>();\n  const ungrouped: ParsedView[] = [];\n  for (const view of ordered) {\n    const names = suiteNames(view);\n    if (names.length === 0) ungrouped.push(view);\n    for (const name of names) byName.set(name, [...(byName.get(name) ?? []), view]);\n  }\n  const suites = [...byName]\n    .sort(([a], [b]) => compareIds(a, b))\n    .map(([name, views]) => ({ name, views, ...participantsOf(scan, views) }));\n  return { suites, ungrouped };\n}\n"]}

package/dist/core/usecases/touch.js

@@ -0,0 +1,101 @@
+/**
+ * Which business flows run through a service — the blast radius `loam delta`
+ * and `loam status` report beside the requirements and contracts a feature
+ * changes.
+ *
+ * ## The join is on ENDPOINTS, never on relationships
+ *
+ * `core/usecases/operations.ts` asks what a hop EXERCISES, which needs the
+ * relationship behind it. This asks something weaker and more useful early:
+ * does this hop mention the service at all? So it resolves the step's own two
+ * endpoints and stops — no `attributeStep`, no candidate scan.
+ *
+ * That is the difference between answering and not answering for the service a
+ * feature is about to INTRODUCE. A flow drawn for work that has not happened yet
+ * has hops nothing in the model backs — `usecase.step-unbacked` is validate's
+ * finding about exactly that, and it is an ERROR precisely because the fleet map
+ * has not caught up — and a relationship join reports such a flow as touching
+ * nobody. The endpoints are still there; the arrow is what is missing. An
+ * implementer reading a delta brief needs to know the flow exists most of all in
+ * that state, because that is the state their change is supposed to end.
+ *
+ * ## Everything a caller sees, it sees per HOP
+ *
+ * A view is reported only when at least one of its hops touches the addressed
+ * services, and only those hops travel. "Checkout touches you" is not actionable;
+ * "Checkout touches you at step 4" is where the reader goes to look.
+ */
+import { compareIds } from "../repo/entries.js";
+import { readUseCases } from "./fleet.js";
+import { viewFile } from "./place.js";
+/** The addressed services one hop mentions, source and target both, sorted and de-duplicated. */
+function touched(step, scan, services) {
+    const hit = [step.source, step.target].map((id) => scan.resolve(id)).filter((id) => services.has(id));
+    return [...new Set(hit)].sort(compareIds);
+}
+/** One view's touching hops, in the author's own step order — the order the diagram reads in. */
+function touchedView(view, scan, services) {
+    const steps = [];
+    for (const step of view.steps) {
+        const hit = touched(step, scan, services);
+        if (hit.length === 0)
+            continue;
+        steps.push({
+            ordinal: step.ordinal,
+            ...(step.title === undefined ? {} : { title: step.title }),
+            source: step.source,
+            target: step.target,
+            services: hit,
+        });
+    }
+    if (steps.length === 0)
+        return null;
+    return {
+        id: view.id,
+        ...(view.title === undefined ? {} : { title: view.title }),
+        file: viewFile(view),
+        tags: [...view.tags].sort(compareIds),
+        steps,
+    };
+}
+/**
+ * The flows touching a set of services, over a scan somebody already has.
+ *
+ * Separate from `useCaseBlastRadius` below because `core/pack/joins.ts` reads
+ * the scan ONCE and asks two different questions of it — this one and the
+ * capability claim join — and a second read there would be a second LikeC4
+ * project load inside a single `loam context`.
+ *
+ * An `unreadable` scan answers with nothing. Every caller pairs this with the
+ * scan's own health, because an empty list means "no flow mentions these
+ * services" and "nobody could look" only when read together.
+ */
+export function flowsTouching(scan, services) {
+    if (scan.kind !== "read")
+        return [];
+    return (scan.views
+        .map((view) => touchedView(view, scan, services))
+        .filter((flow) => flow !== null)
+        // Sorted by (file, view id) rather than reported in LikeC4's own record
+        // order: nothing in loam has measured that the parse preserves declaration
+        // order, so a payload ordered by it would reorder under a dependency bump.
+        .sort((a, b) => compareIds(a.file, b.file) || compareIds(a.id, b.id)));
+}
+/**
+ * The flows touching a set of services, read and joined in one call.
+ *
+ * The load underneath is `readUseCases`, which carries its own cheap gate: a
+ * fleet whose `architecture/` documents never mention the reserved tag prefix
+ * answers `{ flows: [] }` without starting LikeC4 at all. That gate is what
+ * makes this callable from `loam delta`, which sits in `/loam-implement`'s inner
+ * loop and would otherwise pay a Langium workspace spin-up on every iteration of
+ * somebody's afternoon.
+ */
+export async function useCaseBlastRadius(req) {
+    const scan = await readUseCases({ docsDir: req.docsDir, known: req.known });
+    if (scan.kind !== "read") {
+        return { unreadable: true, ...(scan.errors[0] === undefined ? {} : { error: scan.errors[0] }), flows: [] };
+    }
+    return { unreadable: false, flows: flowsTouching(scan, req.services) };
+}
+//# sourceMappingURL=touch.js.map

package/dist/core/usecases/touch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"touch.js","sourceRoot":"","sources":["../../../src/core/usecases/touch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which business flows run through a service — the blast radius `loam delta`\n * and `loam status` report beside the requirements and contracts a feature\n * changes.\n *\n * ## The join is on ENDPOINTS, never on relationships\n *\n * `core/usecases/operations.ts` asks what a hop EXERCISES, which needs the\n * relationship behind it. This asks something weaker and more useful early:\n * does this hop mention the service at all? So it resolves the step's own two\n * endpoints and stops — no `attributeStep`, no candidate scan.\n *\n * That is the difference between answering and not answering for the service a\n * feature is about to INTRODUCE. A flow drawn for work that has not happened yet\n * has hops nothing in the model backs — `usecase.step-unbacked` is validate's\n * finding about exactly that, and it is an ERROR precisely because the fleet map\n * has not caught up — and a relationship join reports such a flow as touching\n * nobody. The endpoints are still there; the arrow is what is missing. An\n * implementer reading a delta brief needs to know the flow exists most of all in\n * that state, because that is the state their change is supposed to end.\n *\n * ## Everything a caller sees, it sees per HOP\n *\n * A view is reported only when at least one of its hops touches the addressed\n * services, and only those hops travel. \"Checkout touches you\" is not actionable;\n * \"Checkout touches you at step 4\" is where the reader goes to look.\n */\nimport { compareIds } from \"../repo/entries.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { readUseCases, type UseCaseScan } from \"./fleet.js\";\nimport { viewFile } from \"./place.js\";\n\n/** One hop of a flow that mentions a service the caller asked about. */\nexport interface TouchedStep {\n  /** The view's own leaf numbering — what the author sees on the diagram. */\n  ordinal: number;\n  title?: string;\n  /** The step's endpoints as the view declares them: element ids, already oriented. */\n  source: string;\n  target: string;\n  /**\n   * Which of the ADDRESSED services this hop mentions, sorted. Both, when a flow\n   * calls a service and it answers within the same addressed set.\n   */\n  services: string[];\n}\n\n/** One flow that touches the addressed services, with only the hops that do. */\nexport interface TouchedUseCase {\n  id: string;\n  title?: string;\n  /** Repo-relative document the view is written in — where the reader goes to change it. */\n  file: string;\n  /**\n   * The `#cap-` tags the view carries, verbatim and unresolved.\n   *\n   * Verbatim because resolving them means reading\n   * `architecture/capabilities.yaml`, and a slug is not injective — the join can\n   * legitimately answer \"two capabilities\" (core/capabilities/usecase-join.ts).\n   * A blast-radius list is not the place to make that call: `loam validate --all`\n   * already grades every tag with `usecase.capability-unresolved`, and a second\n   * resolution here would be a second answer to the same question.\n   */\n  tags: string[];\n  steps: TouchedStep[];\n}\n\n/**\n * The flows over a set of services, and whether loam could look at all.\n *\n * `unreadable` is a HOLE, in the sense `core/pack/pack.ts` uses the word: `flows`\n * is empty because `architecture/` did not parse, not because the fleet draws no\n * use cases. A consumer that cannot tell those apart reads \"no business flow\n * depends on this\" off a directory nobody could open, which is the vacuously\n * green answer every surface in loam is built to refuse.\n */\nexport interface UseCaseBlastRadius {\n  unreadable: boolean;\n  /** LikeC4's first message, so a reader knows which document to open. */\n  error?: string;\n  flows: TouchedUseCase[];\n}\n\nexport interface BlastRadiusRequest {\n  docsDir: DocsDir;\n  /**\n   * The fleet the element→service resolver is built with. Wider than `services`\n   * on purpose: it should be every service the resolver could legitimately land\n   * on, so a hop into a modelled container resolves to its owner rather than to\n   * the container's own title.\n   */\n  known: ReadonlySet<string>;\n  /** The services being asked about. */\n  services: ReadonlySet<string>;\n}\n\n/** The addressed services one hop mentions, source and target both, sorted and de-duplicated. */\nfunction touched(step: ParsedStep, scan: Extract<UseCaseScan, { kind: \"read\" }>, services: ReadonlySet<string>): string[] {\n  const hit = [step.source, step.target].map((id) => scan.resolve(id)).filter((id) => services.has(id));\n  return [...new Set(hit)].sort(compareIds);\n}\n\n/** One view's touching hops, in the author's own step order — the order the diagram reads in. */\nfunction touchedView(view: ParsedView, scan: Extract<UseCaseScan, { kind: \"read\" }>, services: ReadonlySet<string>): TouchedUseCase | null {\n  const steps: TouchedStep[] = [];\n  for (const step of view.steps) {\n    const hit = touched(step, scan, services);\n    if (hit.length === 0) continue;\n    steps.push({\n      ordinal: step.ordinal,\n      ...(step.title === undefined ? {} : { title: step.title }),\n      source: step.source,\n      target: step.target,\n      services: hit,\n    });\n  }\n  if (steps.length === 0) return null;\n  return {\n    id: view.id,\n    ...(view.title === undefined ? {} : { title: view.title }),\n    file: viewFile(view),\n    tags: [...view.tags].sort(compareIds),\n    steps,\n  };\n}\n\n/**\n * The flows touching a set of services, over a scan somebody already has.\n *\n * Separate from `useCaseBlastRadius` below because `core/pack/joins.ts` reads\n * the scan ONCE and asks two different questions of it — this one and the\n * capability claim join — and a second read there would be a second LikeC4\n * project load inside a single `loam context`.\n *\n * An `unreadable` scan answers with nothing. Every caller pairs this with the\n * scan's own health, because an empty list means \"no flow mentions these\n * services\" and \"nobody could look\" only when read together.\n */\nexport function flowsTouching(scan: UseCaseScan, services: ReadonlySet<string>): TouchedUseCase[] {\n  if (scan.kind !== \"read\") return [];\n  return (\n    scan.views\n      .map((view) => touchedView(view, scan, services))\n      .filter((flow): flow is TouchedUseCase => flow !== null)\n      // Sorted by (file, view id) rather than reported in LikeC4's own record\n      // order: nothing in loam has measured that the parse preserves declaration\n      // order, so a payload ordered by it would reorder under a dependency bump.\n      .sort((a, b) => compareIds(a.file, b.file) || compareIds(a.id, b.id))\n  );\n}\n\n/**\n * The flows touching a set of services, read and joined in one call.\n *\n * The load underneath is `readUseCases`, which carries its own cheap gate: a\n * fleet whose `architecture/` documents never mention the reserved tag prefix\n * answers `{ flows: [] }` without starting LikeC4 at all. That gate is what\n * makes this callable from `loam delta`, which sits in `/loam-implement`'s inner\n * loop and would otherwise pay a Langium workspace spin-up on every iteration of\n * somebody's afternoon.\n */\nexport async function useCaseBlastRadius(req: BlastRadiusRequest): Promise<UseCaseBlastRadius> {\n  const scan = await readUseCases({ docsDir: req.docsDir, known: req.known });\n  if (scan.kind !== \"read\") {\n    return { unreadable: true, ...(scan.errors[0] === undefined ? {} : { error: scan.errors[0] }), flows: [] };\n  }\n  return { unreadable: false, flows: flowsTouching(scan, req.services) };\n}\n"]}