@ybotok/loam 0.2.0-alpha.4 → 0.2.0-alpha.6

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

@@ -0,0 +1,161 @@
+/**
+ * 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 prefix in any
+ *     document (`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;
+ *  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 prefix in any\n *     document (`mentionsTagPrefix`, the fleet's own byte gate) → nothing opted\n *     in, no workspace. An untagged `views.likec4` is somebody's hand-drawn\n *     diagram, never graded, exactly as an untagged fleet view is — and its\n *     parse errors are the renderer's business until a view opts the project\n *     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 mentions a prefix in prose and declares no tagged view), because only\n * the second one 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/vocabulary/maturity.js

@@ -129,6 +129,16 @@ export function landscapeEvidence(req) {
     const inbound = [];
     const outbound = [];
     for (const r of relationships) {
+        // An edge whose BOTH endpoints resolve to this service is its own internal
+        // wiring (`svc.web -> svc.db`): filed as inbound it made the service its own
+        // caller — `← <id> "reads"` in `loam context` (verification 2026-09-04) —
+        // and, through `apiExpected` below, told a service nobody calls that it owed
+        // an OpenAPI contract. `core/brief/landscape.ts` drops it for the same
+        // reason. It still TOUCHES the service, which is why the brief's `touched`
+        // and `landscape.service-isolated` read the relationships rather than these
+        // two lists.
+        if (svcOf(r.source) === id && svcOf(r.target) === id)
+            continue;
         const edge = { op: r.op ?? null, title: r.title ?? null };
         if (svcOf(r.target) === id)
             inbound.push({ service: svcOf(r.source), ...edge });

package/dist/core/vocabulary/maturity.js.map

@@ -1 +1 @@
-{"version":3,"file":"maturity.js","sourceRoot":"","sources":["../../../src/core/vocabulary/maturity.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The adoption-maturity ladder: one monotone word for how far a service's\n * documentation has got, and what stands between it and the next rung.\n *\n * This lived inside `commands/list.ts` while `list` was the only caller. It\n * moved here when `explore` needed the same answer, because the alternative is\n * the failure `core/kernel/ids/service.ts` already records for the service-id grammar: a\n * second, subtly different copy, so two commands grade the same directory\n * differently and nobody can tell which one is lying. The rung is a fleet dial\n * — `list` prints it per service and in a rollup, `explore` prints it for a\n * service somebody is about to build against — and a dial with two readings is\n * not a dial.\n */\nimport type { ServiceEntry } from \"../repo/entries.js\";\n\n/** The ladder, in order. Each rung stands on every rung below it. */\nexport const MATURITY_LADDER = [\"empty\", \"partial\", \"documented\", \"sourced\", \"vouched\"] as const;\nexport type Maturity = (typeof MATURITY_LADDER)[number];\n\n/**\n * A service entry plus the two facts the directory enumeration cannot know on\n * its own. Both change what a rung MEANS, and both are fleet-level: they need\n * the landscape, not `services/<id>/`.\n */\nexport interface MaturityInput {\n  entry: ServiceEntry;\n  /** `arch.spec.md` — the architecture-obligations axis, absent from ServiceEntry.has. */\n  archSpec: boolean;\n  /**\n   * Does anything in the fleet call an operation on this service? True unless\n   * the landscape PROVES otherwise, exactly as `validate`'s no-openapi grace\n   * reads it: a missing or unparseable landscape proves nothing.\n   */\n  apiExpected: boolean;\n}\n\n/**\n * How far a service's documentation has got. Derived from artifact PRESENCE and\n * provenance state only — the data an enumeration already holds — never from\n * what the artifacts say. COMPLETENESS of adopted docs is explicitly on the\n * unchecked list (brief/unchecked.ts): a service with one endpoint documented out of\n * thirty climbs this ladder exactly as fast as a thorough one, which is why no\n * rung is called \"adopted\".\n *\n *   empty       services/<id>/ exists, no artifact is in it\n *   partial     some artifacts, but not the required set\n *   documented  the artifacts the adopt brief marks required are present\n *   sourced     the living spec declares `sources` — something ties it to code\n *   vouched     status: verified with a sources_digest behind it — a person\n *               stamped it. `verified` with no digest is a claim with nothing\n *               behind it and stays below this rung.\n *\n * `openapi.yaml` is required ONLY where an API is expected. The rung used to\n * demand it of everything, which permanently pinned every worker, cron and\n * consumer in the fleet at `partial` — services that are fully documented and\n * vouched for, reported as unfinished forever, leaving the rollup permanently\n * below its true documentation state. The evidence is the same one\n * `validate` uses to keep `service.no-openapi` quiet, so a service cannot be\n * green in one command and unfinished in the other.\n */\nexport function serviceMaturity(v: MaturityInput): Maturity {\n  const s = v.entry;\n  if (!Object.values(s.has).some(Boolean) && !v.archSpec && s.adrs === 0) return \"empty\";\n  if (!(s.has.model && s.has.spec && (!v.apiExpected || s.has.openapi))) return \"partial\";\n  if (!s.sources.declared) return \"documented\";\n  if (!(s.status === \"verified\" && s.sources.stamped)) return \"sourced\";\n  return \"vouched\";\n}\n\n/**\n * What stands between this service and `vouched`, named as the thing to go and\n * do. One rung's worth at a time: telling somebody at `empty` that they also\n * need a vouch is noise, and the vouch is not even possible yet.\n */\nexport function maturityGaps(v: MaturityInput): string[] {\n  const s = v.entry;\n  const files = [\n    ...(s.has.model ? [] : [\"model.likec4\"]),\n    ...(s.has.spec ? [] : [\"spec.md\"]),\n    ...(v.apiExpected && !s.has.openapi ? [\"openapi.yaml\"] : []),\n  ];\n  if (files.length > 0) return files;\n  if (!s.sources.declared) return [\"sources: in the spec.md frontmatter\"];\n  if (!(s.status === \"verified\" && s.sources.stamped)) return [`\\`loam vouch --service ${s.id}\\``];\n  return [];\n}\n\n/** Counts per rung, every rung present — a stable shape a fleet dashboard can diff. */\nexport function maturityRollup(graded: readonly { maturity: Maturity }[]): Record<Maturity, number> {\n  const out = Object.fromEntries(MATURITY_LADDER.map((m) => [m, 0])) as Record<Maturity, number>;\n  for (const v of graded) out[v.maturity] += 1;\n  return out;\n}\n\n/* ------------------------------------------------------------------ */\n/* What the fleet map proves about one service                         */\n/* ------------------------------------------------------------------ */\n\n/**\n * C4 kinds that model people, and the tag marking an element as somebody\n * else's system. A person is never a service directory, and `#external` is\n * undocumented on purpose — every census and exemption over the fleet map\n * asks both questions.\n *\n * Extracted on the third strike: `commands/validate/checks/vocabulary.ts`,\n * `core/gate/partners.ts` and `core/verify/checklist.ts` each carried a copy.\n * Their real home is `core/c4/likec4.ts` beside the model they describe, but\n * that file sits against the 300-line limit and its package holds five files\n * — so the trio lives here, beside `landscapeEvidence`, which reads the same\n * map for the same per-service questions.\n *\n * `PLATFORM_TAG` joined them from `commands/validate/checks/fleet-shape.ts`,\n * where it was declared beside its one reader. It moved for the rule above the\n * others came for: `fleet/kind-tags.ts` needs to know which tag names loam\n * grades on, and reaching into fleet-shape.ts for a five-character constant\n * would import a module that reads permissions, capabilities and every\n * service's requirements to get it. The two tags loam gives meaning to belong\n * in one place anyway — that list IS what the kind-tag check is about.\n */\nexport const ACTOR_KINDS = new Set([\"person\", \"actor\", \"user\"]);\nexport const EXTERNAL_TAG = \"external\";\n/** Tag marking ubiquitous infrastructure; the scaffolded fleet view excludes it. */\nexport const PLATFORM_TAG = \"platform\";\n\n/**\n * The tags loam GRADES on, as opposed to the ones it merely carries.\n *\n * A tag in this list changes what loam concludes about a fleet: `#external`\n * exempts an element from the landscape↔services reconciliation entirely, and\n * `#platform` silences the hub warning. Every other tag on an element is the\n * author's own vocabulary and loam does not read it.\n *\n * The list exists because since LikeC4 1.59.0 a tag can be declared on a KIND\n * — `specification { element softwareSystem { #external } }` — and LikeC4\n * applies it to every element of that kind. A kind-wide declaration of a tag on\n * this list switches loam's grading off for the whole fleet at once, which is\n * what `kindTagFindings` refuses. A tag NOT on this list is safe to declare\n * kind-wide, so the check must ask exactly this question and no broader one.\n */\nexport const GRADED_TAGS: readonly string[] = [EXTERNAL_TAG, PLATFORM_TAG];\n\n/** One end of a call the fleet map draws, as every per-service view spells it. */\nexport interface LandscapeEdge {\n  service: string;\n  op: string | null;\n  title: string | null;\n}\n\n/**\n * The slice of a parsed relationship the partition reads. Structural on\n * purpose — the smallest parameter type the derivation needs — so this module\n * stays a leaf: `core/c4/likec4.ts`'s `Rel` satisfies it without an import\n * edge from the vocabulary package into the parser.\n */\nexport interface EdgeSource {\n  source: string;\n  target: string;\n  op?: string;\n  title?: string;\n}\n\nexport interface LandscapeEvidenceRequest {\n  /** The service being asked about. */\n  id: string;\n  /** Whether the landscape parsed — what makes its silence evidence rather than absence. */\n  parses: boolean;\n  /** The parsed relationships; empty when the landscape is absent or unparseable. */\n  relationships: readonly EdgeSource[];\n  /** Every element id in the map, for the `modelled` probe. */\n  elementIds: readonly string[];\n  /** The shared resolver (`core/c4/resolve/service.ts` `serviceResolver`), widened to plain strings. */\n  svcOf: (id: string) => string;\n}\n\nexport interface LandscapeEvidence {\n  inbound: LandscapeEdge[];\n  outbound: LandscapeEdge[];\n  /** Whether anything in the fleet map resolves to this service. */\n  modelled: boolean;\n  /** The `apiExpected` input the ladder above consumes. */\n  apiExpected: boolean;\n}\n\n/**\n * The fleet map's evidence about one service: the edges into and out of it,\n * whether the map draws it at all, and whether an API is expected of it.\n *\n * One spelling, because it had grown three. `explore`'s describe and the\n * context pack's living slice partitioned the same relationships with the\n * same positive-evidence rule line for line — an inbound edge carrying an\n * operation proves somebody calls the service; a landscape that is absent or\n * does not parse proves NOTHING about who calls it, so the contract is still\n * owed — and a rule spelled twice is how the same service grades `partial` in\n * one command and `documented` in another. `list`'s serviceViews\n * (`commands/list/views.ts`) derives the same rule fleet-wide in ONE pass —\n * a single `called` set for every service, not a partition per service —\n * so that spelling deliberately stays there, cross-referenced from both\n * sides: calling this per service inside a fleet loop would re-walk the\n * whole relationship list once per service.\n */\nexport function landscapeEvidence(req: LandscapeEvidenceRequest): LandscapeEvidence {\n  const { id, parses, relationships, svcOf } = req;\n  const inbound: LandscapeEdge[] = [];\n  const outbound: LandscapeEdge[] = [];\n  for (const r of relationships) {\n    const edge = { op: r.op ?? null, title: r.title ?? null };\n    if (svcOf(r.target) === id) inbound.push({ service: svcOf(r.source), ...edge });\n    else if (svcOf(r.source) === id) outbound.push({ service: svcOf(r.target), ...edge });\n  }\n  return {\n    inbound,\n    outbound,\n    modelled: req.elementIds.some((e) => svcOf(e) === id),\n    apiExpected: !parses || inbound.some((e) => e.op !== null),\n  };\n}\n"]}
+{"version":3,"file":"maturity.js","sourceRoot":"","sources":["../../../src/core/vocabulary/maturity.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The adoption-maturity ladder: one monotone word for how far a service's\n * documentation has got, and what stands between it and the next rung.\n *\n * This lived inside `commands/list.ts` while `list` was the only caller. It\n * moved here when `explore` needed the same answer, because the alternative is\n * the failure `core/kernel/ids/service.ts` already records for the service-id grammar: a\n * second, subtly different copy, so two commands grade the same directory\n * differently and nobody can tell which one is lying. The rung is a fleet dial\n * — `list` prints it per service and in a rollup, `explore` prints it for a\n * service somebody is about to build against — and a dial with two readings is\n * not a dial.\n */\nimport type { ServiceEntry } from \"../repo/entries.js\";\n\n/** The ladder, in order. Each rung stands on every rung below it. */\nexport const MATURITY_LADDER = [\"empty\", \"partial\", \"documented\", \"sourced\", \"vouched\"] as const;\nexport type Maturity = (typeof MATURITY_LADDER)[number];\n\n/**\n * A service entry plus the two facts the directory enumeration cannot know on\n * its own. Both change what a rung MEANS, and both are fleet-level: they need\n * the landscape, not `services/<id>/`.\n */\nexport interface MaturityInput {\n  entry: ServiceEntry;\n  /** `arch.spec.md` — the architecture-obligations axis, absent from ServiceEntry.has. */\n  archSpec: boolean;\n  /**\n   * Does anything in the fleet call an operation on this service? True unless\n   * the landscape PROVES otherwise, exactly as `validate`'s no-openapi grace\n   * reads it: a missing or unparseable landscape proves nothing.\n   */\n  apiExpected: boolean;\n}\n\n/**\n * How far a service's documentation has got. Derived from artifact PRESENCE and\n * provenance state only — the data an enumeration already holds — never from\n * what the artifacts say. COMPLETENESS of adopted docs is explicitly on the\n * unchecked list (brief/unchecked.ts): a service with one endpoint documented out of\n * thirty climbs this ladder exactly as fast as a thorough one, which is why no\n * rung is called \"adopted\".\n *\n *   empty       services/<id>/ exists, no artifact is in it\n *   partial     some artifacts, but not the required set\n *   documented  the artifacts the adopt brief marks required are present\n *   sourced     the living spec declares `sources` — something ties it to code\n *   vouched     status: verified with a sources_digest behind it — a person\n *               stamped it. `verified` with no digest is a claim with nothing\n *               behind it and stays below this rung.\n *\n * `openapi.yaml` is required ONLY where an API is expected. The rung used to\n * demand it of everything, which permanently pinned every worker, cron and\n * consumer in the fleet at `partial` — services that are fully documented and\n * vouched for, reported as unfinished forever, leaving the rollup permanently\n * below its true documentation state. The evidence is the same one\n * `validate` uses to keep `service.no-openapi` quiet, so a service cannot be\n * green in one command and unfinished in the other.\n */\nexport function serviceMaturity(v: MaturityInput): Maturity {\n  const s = v.entry;\n  if (!Object.values(s.has).some(Boolean) && !v.archSpec && s.adrs === 0) return \"empty\";\n  if (!(s.has.model && s.has.spec && (!v.apiExpected || s.has.openapi))) return \"partial\";\n  if (!s.sources.declared) return \"documented\";\n  if (!(s.status === \"verified\" && s.sources.stamped)) return \"sourced\";\n  return \"vouched\";\n}\n\n/**\n * What stands between this service and `vouched`, named as the thing to go and\n * do. One rung's worth at a time: telling somebody at `empty` that they also\n * need a vouch is noise, and the vouch is not even possible yet.\n */\nexport function maturityGaps(v: MaturityInput): string[] {\n  const s = v.entry;\n  const files = [\n    ...(s.has.model ? [] : [\"model.likec4\"]),\n    ...(s.has.spec ? [] : [\"spec.md\"]),\n    ...(v.apiExpected && !s.has.openapi ? [\"openapi.yaml\"] : []),\n  ];\n  if (files.length > 0) return files;\n  if (!s.sources.declared) return [\"sources: in the spec.md frontmatter\"];\n  if (!(s.status === \"verified\" && s.sources.stamped)) return [`\\`loam vouch --service ${s.id}\\``];\n  return [];\n}\n\n/** Counts per rung, every rung present — a stable shape a fleet dashboard can diff. */\nexport function maturityRollup(graded: readonly { maturity: Maturity }[]): Record<Maturity, number> {\n  const out = Object.fromEntries(MATURITY_LADDER.map((m) => [m, 0])) as Record<Maturity, number>;\n  for (const v of graded) out[v.maturity] += 1;\n  return out;\n}\n\n/* ------------------------------------------------------------------ */\n/* What the fleet map proves about one service                         */\n/* ------------------------------------------------------------------ */\n\n/**\n * C4 kinds that model people, and the tag marking an element as somebody\n * else's system. A person is never a service directory, and `#external` is\n * undocumented on purpose — every census and exemption over the fleet map\n * asks both questions.\n *\n * Extracted on the third strike: `commands/validate/checks/vocabulary.ts`,\n * `core/gate/partners.ts` and `core/verify/checklist.ts` each carried a copy.\n * Their real home is `core/c4/likec4.ts` beside the model they describe, but\n * that file sits against the 300-line limit and its package holds five files\n * — so the trio lives here, beside `landscapeEvidence`, which reads the same\n * map for the same per-service questions.\n *\n * `PLATFORM_TAG` joined them from `commands/validate/checks/fleet-shape.ts`,\n * where it was declared beside its one reader. It moved for the rule above the\n * others came for: `fleet/kind-tags.ts` needs to know which tag names loam\n * grades on, and reaching into fleet-shape.ts for a five-character constant\n * would import a module that reads permissions, capabilities and every\n * service's requirements to get it. The two tags loam gives meaning to belong\n * in one place anyway — that list IS what the kind-tag check is about.\n */\nexport const ACTOR_KINDS = new Set([\"person\", \"actor\", \"user\"]);\nexport const EXTERNAL_TAG = \"external\";\n/** Tag marking ubiquitous infrastructure; the scaffolded fleet view excludes it. */\nexport const PLATFORM_TAG = \"platform\";\n\n/**\n * The tags loam GRADES on, as opposed to the ones it merely carries.\n *\n * A tag in this list changes what loam concludes about a fleet: `#external`\n * exempts an element from the landscape↔services reconciliation entirely, and\n * `#platform` silences the hub warning. Every other tag on an element is the\n * author's own vocabulary and loam does not read it.\n *\n * The list exists because since LikeC4 1.59.0 a tag can be declared on a KIND\n * — `specification { element softwareSystem { #external } }` — and LikeC4\n * applies it to every element of that kind. A kind-wide declaration of a tag on\n * this list switches loam's grading off for the whole fleet at once, which is\n * what `kindTagFindings` refuses. A tag NOT on this list is safe to declare\n * kind-wide, so the check must ask exactly this question and no broader one.\n */\nexport const GRADED_TAGS: readonly string[] = [EXTERNAL_TAG, PLATFORM_TAG];\n\n/** One end of a call the fleet map draws, as every per-service view spells it. */\nexport interface LandscapeEdge {\n  service: string;\n  op: string | null;\n  title: string | null;\n}\n\n/**\n * The slice of a parsed relationship the partition reads. Structural on\n * purpose — the smallest parameter type the derivation needs — so this module\n * stays a leaf: `core/c4/likec4.ts`'s `Rel` satisfies it without an import\n * edge from the vocabulary package into the parser.\n */\nexport interface EdgeSource {\n  source: string;\n  target: string;\n  op?: string;\n  title?: string;\n}\n\nexport interface LandscapeEvidenceRequest {\n  /** The service being asked about. */\n  id: string;\n  /** Whether the landscape parsed — what makes its silence evidence rather than absence. */\n  parses: boolean;\n  /** The parsed relationships; empty when the landscape is absent or unparseable. */\n  relationships: readonly EdgeSource[];\n  /** Every element id in the map, for the `modelled` probe. */\n  elementIds: readonly string[];\n  /** The shared resolver (`core/c4/resolve/service.ts` `serviceResolver`), widened to plain strings. */\n  svcOf: (id: string) => string;\n}\n\nexport interface LandscapeEvidence {\n  inbound: LandscapeEdge[];\n  outbound: LandscapeEdge[];\n  /** Whether anything in the fleet map resolves to this service. */\n  modelled: boolean;\n  /** The `apiExpected` input the ladder above consumes. */\n  apiExpected: boolean;\n}\n\n/**\n * The fleet map's evidence about one service: the edges into and out of it,\n * whether the map draws it at all, and whether an API is expected of it.\n *\n * One spelling, because it had grown three. `explore`'s describe and the\n * context pack's living slice partitioned the same relationships with the\n * same positive-evidence rule line for line — an inbound edge carrying an\n * operation proves somebody calls the service; a landscape that is absent or\n * does not parse proves NOTHING about who calls it, so the contract is still\n * owed — and a rule spelled twice is how the same service grades `partial` in\n * one command and `documented` in another. `list`'s serviceViews\n * (`commands/list/views.ts`) derives the same rule fleet-wide in ONE pass —\n * a single `called` set for every service, not a partition per service —\n * so that spelling deliberately stays there, cross-referenced from both\n * sides: calling this per service inside a fleet loop would re-walk the\n * whole relationship list once per service.\n */\nexport function landscapeEvidence(req: LandscapeEvidenceRequest): LandscapeEvidence {\n  const { id, parses, relationships, svcOf } = req;\n  const inbound: LandscapeEdge[] = [];\n  const outbound: LandscapeEdge[] = [];\n  for (const r of relationships) {\n    // An edge whose BOTH endpoints resolve to this service is its own internal\n    // wiring (`svc.web -> svc.db`): filed as inbound it made the service its own\n    // caller — `← <id> \"reads\"` in `loam context` (verification 2026-09-04) —\n    // and, through `apiExpected` below, told a service nobody calls that it owed\n    // an OpenAPI contract. `core/brief/landscape.ts` drops it for the same\n    // reason. It still TOUCHES the service, which is why the brief's `touched`\n    // and `landscape.service-isolated` read the relationships rather than these\n    // two lists.\n    if (svcOf(r.source) === id && svcOf(r.target) === id) continue;\n    const edge = { op: r.op ?? null, title: r.title ?? null };\n    if (svcOf(r.target) === id) inbound.push({ service: svcOf(r.source), ...edge });\n    else if (svcOf(r.source) === id) outbound.push({ service: svcOf(r.target), ...edge });\n  }\n  return {\n    inbound,\n    outbound,\n    modelled: req.elementIds.some((e) => svcOf(e) === id),\n    apiExpected: !parses || inbound.some((e) => e.op !== null),\n  };\n}\n"]}

package/examples/README.md

@@ -149,6 +149,29 @@ and `validate --all` answers `subsystem.views-stale`. (`order-service` and `paym
 unfiled deliberately: FEAT-088's committed version-2 snapshot restores them by literal path, and the
 `loam unarchive FEAT-088` walkthrough must keep working byte-for-byte.)
 
+**All five models are EXTENDING models, and that is the shape this example teaches.** None of them
+declares a `specification` block, none re-declares a partner, and none has a `likec4.config.json`
+beside it. Each one says what is inside its service with `extend marketplace.<svc> { … }` on the
+element `architecture/landscape.likec4` already binds to its directory, so `kafka`, `stripe`,
+`notification-provider` and every peer service are declared exactly once — in the map — and no two
+documents can disagree about their tags. The root `likec4.config.json` therefore excludes only
+`**/node_modules/**` and `features/**`: `npx likec4 validate examples/docs` names ONE project,
+`fleet`, holding the map and all five models, and needs no `--project` flag. The other shape — a
+model that declares its own `specification` and is parsed alone, which is what every model here was
+before — is still legal and still supported; SCHEMA.md's "Two shapes of a service model" has both,
+the eight grades in its table — seven that came with the pair, plus the one it narrowed
+(`service.likec4-config-missing`, now standalone-only) — and the
+ordered recipe for migrating between them.
+
+Two consequences are visible in the tree and worth reading for. Element ids carry their full path,
+so `services/order-service/arch.spec.md` writes `Covers: marketplace.orderService.db` — the
+container has no shorter name, because the model extends an element nested in the `marketplace`
+group. And a cross-boundary call is written **twice** on purpose: container-level in the model
+(`marketplace.notificationService.sender -> notificationProvider`) and service-level in the map
+(`marketplace.notificationService -> notificationProvider`), because every fleet check — the spine,
+`landscape.service-isolated`, the platform census — reads the map alone. ROADMAP.md keeps that
+remainder written down rather than hidden.
+
 Plus one count rather than a finding: `sourcesUnverifiableFromHere: 4`. Four specs name paths in
 their own service repositories, and this is none of those repositories — the fleet gate reports the
 blind spot instead of resolving it. Running `loam validate --service <id>` inside each service repo

package/examples/docs/architecture/landscape.likec4

@@ -8,6 +8,16 @@
 // service needs a directory (warning). An element is tied to its directory by
 // `metadata { service '<id>' }`, or by its title when there is no binding.
 // Systems that are not ours carry #external and are exempt.
+//
+// This file is also the SPECIFICATION every service model borrows. Each
+// `services/<…>/<svc>/model.likec4` here is an EXTENDING model: it declares no
+// kinds and no partners, and says what is inside its service with
+// `extend marketplace.<svc> { … }` on the element below that binds to its
+// directory. The root `likec4.config.json` therefore does NOT exclude
+// `services/**` — the map and every model are ONE LikeC4 project, so an element
+// is declared exactly once and no two documents can disagree about its tags.
+// SCHEMA.md, "Two shapes of a service model", has both shapes and the rule that
+// picks between them; a kind or tag a model needs is added HERE, once.
 specification {
   // A grouping element — it stands for no service and owns no directory. The
   // service checks WALK the tree rather than reading only top-level elements:
@@ -20,7 +30,18 @@ specification {
   // Declared here because archive SPLICES a delta's additions verbatim: FEAT-101's
   // new system carries its `api` container along, and the kind has to be legal in
   // THIS document for the merged landscape to parse (archive refuses otherwise).
+  // Only a NEW service arrives this way — one that already has an extending model
+  // takes the addition into that model instead, and this file never grows an
+  // interior.
   element container
+  // Declared here for the SERVICE MODELS, and nothing in this file uses it: a
+  // store lives inside the service that owns it (`landscape.datastore-private`
+  // is the check that pushes one back in), so every `database` element in this
+  // fleet is written in a `services/<svc>/model.likec4` under
+  // `extend marketplace.<svc>`. An extending model declares no kinds of its
+  // own, so a kind it needs and this block does not declare is ONE parse error
+  // on the model — which is what this line prevents.
+  element database
   element person
   // A topic is an element, and the kind carries #external rather than each
   // instance doing it: LikeC4 does NOT inherit tags, so a topic nested inside
@@ -137,6 +158,18 @@ model {
     description 'CRM of record — the fleet reads its events and writes none'
   }
 
+  // Declared HERE rather than in notification-service's model, and that is the
+  // rule an extending model turns on: a system a service reaches is the fleet's
+  // element, declared once, and a model that declared its own copy would be
+  // `c4.element-unowned` (an extending model may only add elements under the
+  // element that resolves to its own service). One consumer, so it never
+  // becomes `landscape.platform-candidate`; #external, so no
+  // services/notification-provider/ is asked for.
+  notificationProvider = softwareSystem 'notification-provider' {
+    #external
+    description 'Third-party email and SMS gateway — quota-limited, and outside this fleet'
+  }
+
   customer -> marketplace.checkoutWeb 'Uses'
 
   // The synchronous spine. Every one of these resolves against the TARGET's
@@ -185,6 +218,14 @@ model {
   // it raises no warning because its title does not claim to be a call into a
   // fleet service.
   marketplace.paymentService -> stripe 'Authorizes cards'
+  // The second half of the rule the extending shape keeps: the container that
+  // really makes the call is drawn in the service's own model
+  // (`marketplace.notificationService.sender -> notificationProvider`), and the
+  // SERVICE-level twin is drawn here, because every fleet check — the spine,
+  // `landscape.service-isolated`, the platform census — reads this file alone.
+  // The edge exists twice on purpose; SCHEMA.md says so where it says the map
+  // is the one document holding every cross-service edge.
+  marketplace.notificationService -> notificationProvider 'Sends email and SMS'
 
   // The event spine, the async mirror of `metadata { op }`: the name must be a
   // message the PRODUCER's own asyncapi.yaml declares an `action: send` for, or

package/examples/docs/architecture/usecases/order-notification.likec4

@@ -14,7 +14,10 @@
 // read as ONE LikeC4 project, so the steps below resolve against the landscape's
 // elements even though this file declares none — which also means exactly one
 // file in this directory declares the `specification` block, and it is not this
-// one.
+// one. (The renderer's root project is WIDER than what loam grades here: it also
+// holds every `services/<svc>/model.likec4`, because each of them extends the
+// map. A tag declared twice across that whole set is `c4.fleet-project-invalid`,
+// which is why a tag belongs in the landscape's one block.)
 //
 // THE TAG MUST BE THE FIRST THING IN THE VIEW BODY. Written after `title` it is
 // five parse errors, none of which mentions tags. That is the mistake every
@@ -30,7 +33,7 @@
 // `usecase.step-unlinked` is met except the one that matters, which is that a
 // person is not a caller. Somebody clicking a button owes no operationId. Delete
 // that exemption from the checker and this file is what notices: the example
-// fleet's warning count moves from eight to nine and test/examples.test.ts
+// fleet's warning count moves from ten to eleven and test/examples.test.ts
 // fails.
 //
 // The hop from checkout-web to order-service is DELIBERATELY NOT DRAWN, and its

package/examples/docs/likec4.config.json

@@ -3,7 +3,6 @@
   "title": "Fleet landscape",
   "exclude": [
     "**/node_modules/**",
-    "services/**",
     "features/**"
   ]
 }

package/examples/docs/services/checkout-web/model.likec4

@@ -1,27 +1,24 @@
-// Per-service C4 for a UI service. A UI is a first-class C4 system: it has
-// containers, it has runtime dependencies, and its pages (ui/pages/*.page.yaml)
-// hang off the operations the edges below name.
+// checkout-web's own C4 — what is INSIDE the element the fleet map binds to
+// services/checkout-web/. A UI is a first-class C4 system: it has containers, it
+// has runtime dependencies, and its pages (ui/pages/*.page.yaml) hang off the
+// operations the edges below name.
 //
-// Every .likec4 file is parsed ON ITS OWN — loam never concatenates them — so
-// this document declares the kinds it uses even though architecture/landscape.likec4
-// declares the same ones. Leaving them out here does not inherit, it fails to parse
-// (`c4.invalid`, an error), and the spec/API joins that read the model go quiet with it.
-specification {
-  element softwareSystem
-  element container
-  element person
-}
-
+// An EXTENDING model: no `specification` block, no partner copies. The kinds and
+// every element this file points at — `customer`, `marketplace.orderService`,
+// `marketplace.paymentService` — are declared once in
+// architecture/landscape.likec4, and the root `likec4.config.json` does not
+// exclude `services/**`, so the map and every model are read as ONE LikeC4
+// project. `extend` takes the fully-qualified id, because the element is nested
+// in the `marketplace` group.
+//
+// Note what this file does NOT do: it does not declare `customer = person`. The
+// actor is the map's, and the edge below simply points at it. That is the rule
+// the shape turns on — an element declared here outside
+// `marketplace.checkoutWeb` is `c4.element-unowned` — and it is also what stops
+// two documents from holding two different descriptions of the same person.
+// SCHEMA.md, "Two shapes of a service model", has the other shape.
 model {
-  // The actor belongs in a UI's own model in a way it does not in a backend's:
-  // the pages exist for this person, and the flows in ui/pages/ start at them.
-  // The landscape draws the same customer -> checkout-web edge at fleet scale;
-  // a person is exempt from the service/directory cross-check either way.
-  customer = person 'Customer'
-
-  checkoutWeb = softwareSystem 'checkout-web' {
-    description 'Customer-facing checkout UI'
-
+  extend marketplace.checkoutWeb {
     spa = container 'spa' {
       description 'Checkout SPA — cart, payment and order status pages'
       technology 'React'
@@ -37,37 +34,21 @@ model {
       technology 'Node.js'
     }
 
-    customer -> spa 'Buys'
     spa -> bff 'Calls the checkout BFF'
   }
 
-  // The services this one actually calls. A service model carries everything the
-  // service touches, cross-boundary included, drawn with the edge the service
-  // really has — the landscape carries only the boundary crossing (checkout-web ->
-  // order-service), while the edge below says WHICH container makes the call.
-  // Without these three edges this file would be two boxes and a hop, and
-  // `c4.no-relationships` would be right to say a model that reaches nothing is
-  // almost never true.
-  orderService = softwareSystem 'order-service' {
-    description 'Owns the order lifecycle'
-    // Bind rather than rely on the title. A renamed box silently stops matching
-    // its directory everywhere the two are joined — in the landscape that costs
-    // `landscape.binding-unknown` (error) when the id is wrong, and here it is
-    // what `health.dependency-unmodelled` resolves a declared dependency
-    // through in the services that have a health.yaml. checkout-web has none:
-    // a UI is nobody's runtime dependency, so it declares no SLIs, no alerts
-    // and no dependency graph, and owes no arch.spec.md to cover them.
-    metadata {
-      service 'order-service'
-    }
-  }
-  paymentService = softwareSystem 'payment-service' {
-    description 'Owns payment authorization/capture'
-    metadata {
-      service 'payment-service'
-    }
-  }
+  // The person is the MAP's element and the hop into this UI is drawn from it.
+  // The landscape draws the coarser `customer -> marketplace.checkoutWeb` twin
+  // at fleet scale; this one says which container the click reaches. A person is
+  // exempt from the service/directory cross-check either way.
+  customer -> marketplace.checkoutWeb.spa 'Buys'
 
+  // The services this one actually calls, drawn with the edge the service really
+  // has — the landscape carries only the boundary crossing (checkout-web ->
+  // order-service), while the edges below say WHICH container makes the call.
+  // Without them this file would be two boxes and a hop, and `c4.no-relationships`
+  // would be right to say a model that reaches nothing is almost never true.
+  //
   // `metadata { op }` is the C4 half of the operation join: the exact
   // operationId order-service's openapi.yaml declares. What `loam validate`
   // grades is the LANDSCAPE's twin of each edge below — `spine.op-undefined`
@@ -77,12 +58,12 @@ model {
   // nothing would catch it if they did. Two calls to one service are two edges,
   // not one edge with a list — a view has to be able to show that the status
   // page and the checkout page stand on different operations.
-  checkoutWeb.bff -> orderService 'Calls createOrder' {
+  marketplace.checkoutWeb.bff -> marketplace.orderService 'Calls createOrder' {
     metadata {
       op 'createOrder'
     }
   }
-  checkoutWeb.bff -> orderService 'Calls getOrder' {
+  marketplace.checkoutWeb.bff -> marketplace.orderService 'Calls getOrder' {
     metadata {
       op 'getOrder'
     }
@@ -94,16 +75,18 @@ model {
   // for an edge that SAYS it calls something and names no operation, so nothing
   // can check the call still exists. Free here and one warning there, which is
   // the asymmetry worth knowing: the fleet map is what the spine reads.
-  checkoutWeb.spa -> paymentService 'Calls the payment API'
+  marketplace.checkoutWeb.spa -> marketplace.paymentService 'Calls the payment API'
 }
 
 // Views are the LikeC4 renderer's, never loam's — no check reads this block.
-// Scoped to the system so the page answers "what does the checkout UI stand on"
-// rather than redrawing the fleet, which architecture/landscape.likec4 already does.
+// Scoped to the service's element so the page answers "what does the checkout UI
+// stand on" rather than redrawing the fleet, which architecture/landscape.likec4
+// already does. This file is part of the root project: `npx likec4 start` at the
+// docs root draws it, with no per-service project file to write.
 views {
-  view checkout_web of checkoutWeb {
+  view checkout_web of marketplace.checkoutWeb {
     title 'checkout-web — containers and the services they call'
     include *
-    include orderService, paymentService
+    include marketplace.orderService, marketplace.paymentService
   }
 }

package/examples/docs/services/order-service/arch.spec.md

@@ -25,9 +25,16 @@ this service's own `model.likec4` plus the landscape (`covers.unknown`, with a d
 hint, is the typo guard — a mistyped entry otherwise costs exactly the coverage it was written
 for), and every `slis[].name` and `alerts[].name` in `health.yaml` must be named by one of them
 (`health.uncovered`, or a signal ships to the on-call rotation with nothing testing it). Edge
-entries below are spelled as this model draws them — `orderService.outbox -> kafka.orderEvents`
-— because the endpoint that matters is the container; `order-service -> payment-service`
-resolves too, through the `metadata { service }` binding on the root element.
+entries below are spelled as this model draws them — `marketplace.orderService.outbox ->
+kafka.orderEvents` — because the endpoint that matters is the container; `order-service ->
+payment-service` resolves too, through the `metadata { service }` binding on the map's element.
+
+Element ids here carry the FULL path, `marketplace.` and all. That is a consequence of the model
+shape rather than a style: `model.likec4` extends the element the fleet map declares inside the
+`marketplace` group, so the container it adds is `marketplace.orderService.db` and no shorter
+spelling of it exists. A service whose model declares its own `specification` and is parsed alone
+mints shorter ids and writes them here — see SCHEMA.md, "Two shapes of a service model", which also
+lists requalifying these lines as a step of the migration between the two.
 
 ## Requirements
 
@@ -40,7 +47,7 @@ key rather than placing a second order or requesting a second authorization. che
 retry on a gateway timeout is not a rare path — it is the normal shape of a mobile checkout —
 and without the key a customer's flaky connection charges the card twice.
 
-Covers: orderService.db, orderService.domain -> paymentService
+Covers: marketplace.orderService.db, marketplace.orderService.domain -> marketplace.paymentService
 
 #### Scenario: checkout-web retries a placement it never saw acknowledged
 - **Given** an order placed under `Idempotency-Key` "ik-8842" with an authorization already requested
@@ -63,7 +70,7 @@ database and then to kafka. A dual write has no failure mode in which both sides
 between them either announces an order nobody stored or stores one nobody hears about, and
 notification-service is the service that pays for the second case.
 
-Covers: orderService.outbox, orderService.outbox -> kafka.orderEvents
+Covers: marketplace.orderService.outbox, marketplace.orderService.outbox -> kafka.orderEvents
 
 #### Scenario: The broker is unavailable when an order is placed
 - **Given** an accepted order whose `OrderPlaced` row is still in the outbox table
@@ -86,7 +93,7 @@ already recorded. The producer's outbox promises at-least-once delivery and a re
 redelivers whatever was in flight, so a consumer without a ledger is a consumer that confirms
 an order it already confirmed — and, once ORD-CANCEL has moved on, resurrects a cancelled one.
 
-Covers: orderService.consumer, kafka.paymentEvents -> orderService.consumer
+Covers: marketplace.orderService.consumer, kafka.paymentEvents -> marketplace.orderService.consumer
 Consumes: payment.PaymentAuthorized
 
 #### Scenario: The same authorization is redelivered after a consumer rebalance