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

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

@@ -0,0 +1,119 @@
+/**
+ * Which `.likec4` files beside a `model.likec4` the RENDERER actually loads —
+ * the `exclude` list of the service's own `likec4.config.json`.
+ *
+ * loam writes that file with two keys and never reads it back
+ * (`core/repo/tree/render/projects.ts` states the ownership rule), but a team
+ * may add keys to it, and `exclude` is the one that changes what the project
+ * holds. Until this module existed the service-flow reader staged every sibling
+ * regardless: a view the renderer never sees was graded, and the finding it
+ * earned said the project is "read the way the renderer reads it" and that the
+ * view still renders — three claims about a file nobody would ever open
+ * (verification 2026-09-04, D10).
+ *
+ * STANDALONE MODELS ONLY, which is where this file IS the project config. A
+ * model that extends the map is read inside the ROOT project, whose own
+ * `exclude` decides what it holds; a per-service config beside such a model is
+ * a stray with a finding of its own (`service.likec4-config-stray`), and
+ * honouring its list here would silence a document the renderer really does
+ * load.
+ *
+ * THE MATCHER IS THE ONE MEASURED, at the likec4 1.59.2 pin, on a scratch
+ * service directory holding `model.likec4`, `views.likec4` and
+ * `usecases/flow.likec4` (`npx likec4 validate <dir>`, counting "found N source
+ * files"): an entry drops a file when the file's directory-relative path STARTS
+ * WITH the entry (`views`, `views.`, `views.likec4`, `usecases`, `usecases/`,
+ * `usecases/flow` each dropped one; `ews.likec4` dropped none), or when it
+ * matches as a glob whose `*` crosses `/` (`*.likec4` dropped all THREE), or
+ * when a leading RECURSIVE segment — a doubled star and a slash — stands for
+ * the zero or more directories above the file: that segment before `*.likec4`
+ * dropped all three, and before `usecases` (with a recursive tail) or
+ * `views.likec4` it dropped one each. All three halves are implemented because
+ * all three were observed; nothing here interprets more than that, and an entry
+ * loam cannot match leaves the file loaded — grading a file the renderer skips
+ * is a wrong sentence, and skipping one it reads is a missing finding, which is
+ * the worse of the two.
+ */
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { isRecord } from "../../kernel/records.js";
+import { excludingPath } from "../../c4/root-project/exclude.js";
+/** The per-service project file, by the name `core/repo/tree/render/projects.ts` writes it under. */
+const CONFIG = "likec4.config.json";
+/**
+ * The service project's `exclude` entries, or `[]` when there is no list to
+ * read — absent, unreadable, not JSON, or an `exclude` that is not a list of
+ * strings. Failing open is right here and nowhere else: the answer decides
+ * whether loam GRADES a document, and an empty list grades everything, which is
+ * exactly what loam did before this module and never a new silence.
+ */
+export async function serviceProjectExclude(dir) {
+    const text = await readFile(`${dir}/${CONFIG}`, "utf8").catch(() => null);
+    if (text === null)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (!isRecord(parsed))
+        return [];
+    const exclude = parsed["exclude"];
+    if (!Array.isArray(exclude))
+        return [];
+    const entries = exclude;
+    return entries.filter((entry) => typeof entry === "string" && entry.trim() !== "");
+}
+/** The siblings that survive the list — absolute paths in, absolute paths out, order kept. */
+export function keepIncluded(dir, exclude, paths) {
+    if (exclude.length === 0)
+        return [...paths];
+    return paths.filter((path) => !excluded(exclude, relative(dir, path).split(/[\\/]/).join("/")));
+}
+/**
+ * Three rungs, because three separate spellings were measured hiding a file and
+ * no one of them subsumes the others.
+ *
+ *  - the bare PREFIX (`views`, `usecases/flow`), which is the renderer's own
+ *    behaviour and matches nothing a glob would;
+ *  - `excludingPath`, the segment walk `core/c4/root-project/exclude.ts` already
+ *    owns, which is what reads a doubled star anywhere in the entry — the three
+ *    recursive spellings the docstring above measured each hide what the
+ *    renderer hides, and the `globRe` half alone matched NONE of them, because a
+ *    leading recursive segment compiled to a REQUIRED slash. loam therefore
+ *    graded a file in no project it may claim to be reading, and gated the run
+ *    on it (verification 2026-09-04);
+ *  - `globRe`, kept for the one case the segment walk cannot express: a `*` that
+ *    CROSSES `/`, which is what `*.likec4` hiding `usecases/flow.likec4` was
+ *    measured doing.
+ *
+ * A union only ever hides more, and the module's own rule says the worse of the
+ * two mistakes is skipping a file the renderer reads; each rung above is a
+ * measurement rather than an interpretation, so the union stays honest.
+ */
+function excluded(exclude, rel) {
+    return exclude.some((raw) => {
+        const entry = raw.replace(/^\.\//, "");
+        if (entry === "")
+            return false;
+        if (rel.startsWith(entry))
+            return true;
+        if (excludingPath([entry], rel) !== null)
+            return true;
+        return entry.includes("*") && globRe(entry).test(rel);
+    });
+}
+/**
+ * One entry as a whole-path regular expression, with `*` crossing `/` — which
+ * is what `*.likec4` excluding `usecases/flow.likec4` measures. Built per call
+ * rather than cached: a `RegExp` is cheap beside the readdir that produced the
+ * paths, and a module-level cache keyed on a string is the shared state
+ * AGENTS.md warns about.
+ */
+function globRe(entry) {
+    const source = entry.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*+/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${source}$`);
+}
+//# sourceMappingURL=exclude.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exclude.js","sourceRoot":"","sources":["../../../../src/core/usecases/service/exclude.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which `.likec4` files beside a `model.likec4` the RENDERER actually loads —\n * the `exclude` list of the service's own `likec4.config.json`.\n *\n * loam writes that file with two keys and never reads it back\n * (`core/repo/tree/render/projects.ts` states the ownership rule), but a team\n * may add keys to it, and `exclude` is the one that changes what the project\n * holds. Until this module existed the service-flow reader staged every sibling\n * regardless: a view the renderer never sees was graded, and the finding it\n * earned said the project is \"read the way the renderer reads it\" and that the\n * view still renders — three claims about a file nobody would ever open\n * (verification 2026-09-04, D10).\n *\n * STANDALONE MODELS ONLY, which is where this file IS the project config. A\n * model that extends the map is read inside the ROOT project, whose own\n * `exclude` decides what it holds; a per-service config beside such a model is\n * a stray with a finding of its own (`service.likec4-config-stray`), and\n * honouring its list here would silence a document the renderer really does\n * load.\n *\n * THE MATCHER IS THE ONE MEASURED, at the likec4 1.59.2 pin, on a scratch\n * service directory holding `model.likec4`, `views.likec4` and\n * `usecases/flow.likec4` (`npx likec4 validate <dir>`, counting \"found N source\n * files\"): an entry drops a file when the file's directory-relative path STARTS\n * WITH the entry (`views`, `views.`, `views.likec4`, `usecases`, `usecases/`,\n * `usecases/flow` each dropped one; `ews.likec4` dropped none), or when it\n * matches as a glob whose `*` crosses `/` (`*.likec4` dropped all THREE), or\n * when a leading RECURSIVE segment — a doubled star and a slash — stands for\n * the zero or more directories above the file: that segment before `*.likec4`\n * dropped all three, and before `usecases` (with a recursive tail) or\n * `views.likec4` it dropped one each. All three halves are implemented because\n * all three were observed; nothing here interprets more than that, and an entry\n * loam cannot match leaves the file loaded — grading a file the renderer skips\n * is a wrong sentence, and skipping one it reads is a missing finding, which is\n * the worse of the two.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport { excludingPath } from \"../../c4/root-project/exclude.js\";\nimport type { ServiceDir } from \"../../kernel/ids/dirs.js\";\n\n/** The per-service project file, by the name `core/repo/tree/render/projects.ts` writes it under. */\nconst CONFIG = \"likec4.config.json\";\n\n/**\n * The service project's `exclude` entries, or `[]` when there is no list to\n * read — absent, unreadable, not JSON, or an `exclude` that is not a list of\n * strings. Failing open is right here and nowhere else: the answer decides\n * whether loam GRADES a document, and an empty list grades everything, which is\n * exactly what loam did before this module and never a new silence.\n */\nexport async function serviceProjectExclude(dir: ServiceDir): Promise<string[]> {\n  const text = await readFile(`${dir}/${CONFIG}`, \"utf8\").catch(() => null);\n  if (text === null) return [];\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(text);\n  } catch {\n    return [];\n  }\n  if (!isRecord(parsed)) return [];\n  const exclude: unknown = parsed[\"exclude\"];\n  if (!Array.isArray(exclude)) return [];\n  const entries: unknown[] = exclude;\n  return entries.filter((entry): entry is string => typeof entry === \"string\" && entry.trim() !== \"\");\n}\n\n/** The siblings that survive the list — absolute paths in, absolute paths out, order kept. */\nexport function keepIncluded(dir: ServiceDir, exclude: readonly string[], paths: readonly string[]): string[] {\n  if (exclude.length === 0) return [...paths];\n  return paths.filter((path) => !excluded(exclude, relative(dir, path).split(/[\\\\/]/).join(\"/\")));\n}\n\n/**\n * Three rungs, because three separate spellings were measured hiding a file and\n * no one of them subsumes the others.\n *\n *  - the bare PREFIX (`views`, `usecases/flow`), which is the renderer's own\n *    behaviour and matches nothing a glob would;\n *  - `excludingPath`, the segment walk `core/c4/root-project/exclude.ts` already\n *    owns, which is what reads a doubled star anywhere in the entry — the three\n *    recursive spellings the docstring above measured each hide what the\n *    renderer hides, and the `globRe` half alone matched NONE of them, because a\n *    leading recursive segment compiled to a REQUIRED slash. loam therefore\n *    graded a file in no project it may claim to be reading, and gated the run\n *    on it (verification 2026-09-04);\n *  - `globRe`, kept for the one case the segment walk cannot express: a `*` that\n *    CROSSES `/`, which is what `*.likec4` hiding `usecases/flow.likec4` was\n *    measured doing.\n *\n * A union only ever hides more, and the module's own rule says the worse of the\n * two mistakes is skipping a file the renderer reads; each rung above is a\n * measurement rather than an interpretation, so the union stays honest.\n */\nfunction excluded(exclude: readonly string[], rel: string): boolean {\n  return exclude.some((raw) => {\n    const entry = raw.replace(/^\\.\\//, \"\");\n    if (entry === \"\") return false;\n    if (rel.startsWith(entry)) return true;\n    if (excludingPath([entry], rel) !== null) return true;\n    return entry.includes(\"*\") && globRe(entry).test(rel);\n  });\n}\n\n/**\n * One entry as a whole-path regular expression, with `*` crossing `/` — which\n * is what `*.likec4` excluding `usecases/flow.likec4` measures. Built per call\n * rather than cached: a `RegExp` is cheap beside the readdir that produced the\n * paths, and a module-level cache keyed on a string is the shared state\n * AGENTS.md warns about.\n */\nfunction globRe(entry: string): RegExp {\n  const source = entry.replace(/[.+^${}()|[\\]\\\\]/g, \"\\\\$&\").replace(/\\*+/g, \".*\").replace(/\\?/g, \".\");\n  return new RegExp(`^${source}$`);\n}\n"]}

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/verify/answers.js

@@ -36,6 +36,17 @@ export const VERDICTS = ["confirmed", "unconfirmed"];
  * `attestedClaims` in `./record.ts` — exactly where it was.
  */
 export const ANSWERED_BY = ["runner", "external-runner", "agent"];
+/**
+ * The entries an answers file holds — a bare array, or an object with an
+ * `answers` array — or null for any other shape. One reading of the file's
+ * shape for `checkAnswers` and `--diff-answers`' off-lens note, so the two
+ * cannot disagree about which entries a file has.
+ */
+export function answerEntries(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    return isRecord(raw) && Array.isArray(raw["answers"]) ? raw["answers"] : null;
+}
 /**
  * Accept an answer set only if it answers THIS checklist: every claim once, no
  * claim twice, nothing extra, and no "confirmed" that shows nothing.
@@ -66,11 +77,7 @@ export const ANSWERED_BY = ["runner", "external-runner", "agent"];
  */
 export function checkAnswers(claims, raw, runnerOwned, context) {
     const refuse = (code, message) => ({ ok: false, code, message });
-    const list = Array.isArray(raw)
-        ? raw
-        : isRecord(raw) && Array.isArray(raw["answers"])
-            ? raw["answers"]
-            : null;
+    const list = answerEntries(raw);
     if (list === null) {
         return refuse("answers-unreadable", "Expected a JSON array of answers, or an object with an `answers` array: " +
             `[{ "id": "...", "verdict": "confirmed", "evidence": ["file:line"] }]`);