@ybotok/loam 0.2.0-alpha.5 → 0.2.0-alpha.7

package/dist/core/brief/map/extend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend.js","sourceRoot":"","sources":["../../../../src/core/brief/map/extend.ts"],"names":[],"mappings":"AAiBA,uFAAuF;AACvF,MAAM,CAAC,MAAM,GAAG,GAAG,OAAO,CAAC;AAC3B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,OAAO,CAAC;AAE3B,6GAA6G;AAC7G,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAgBxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,WAAW,CAAC,SAA2B;IACrD,IAAI,SAAS,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO;YACL,EAAE,EAAE,WAAW;YACf,IAAI,EACF,uGAAuG;gBACvG,uGAAuG;gBACvG,2DAA2D;SAC9D,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAChD,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC;IAC5B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO;YACL,EAAE,EAAE,WAAW;YACf,IAAI,EACF,8EAA8E;gBAC9E,4FAA4F;SAC/F,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,MAAmB,EAAE,OAAe;IAC9E,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACzE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,GAAG,YAAY,CAAC,GAAG,MAAM,CAAC,EAAE,sBAAsB,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC;AACvF,CAAC;AAED,8FAA8F;AAC9F,SAAS,YAAY,CAAC,IAAY,EAAE,KAAK,GAAG,EAAE;IAC5C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;YAC3D,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACf,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;;YAAM,IAAI,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IAClC,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC","sourcesContent":["/**\n * Which element of the fleet map an extending `model.likec4` says it is inside,\n * and what the brief's model example prints where the map has no answer.\n *\n * A module of its own beside `./owed.ts` for the reason that package exists: the\n * two are the fleet map's half of the brief, and `brief.ts` — which resolves the\n * artifact list against a docs repo — went past the file cap carrying the\n * substitution and its three-state reasoning. The subjects are distinct: this\n * one is about the ONE token an agent copies into three code positions, and\n * getting it wrong writes a model that cannot parse.\n *\n * Type-only import from `../` (`LandscapeContext`), which `verbatimModuleSyntax`\n * erases — so this package still value-imports nothing from its parent and the\n * package graph stays acyclic.\n */\nimport type { LandscapeContext } from \"../landscape.js\";\n\n/** The literals `targets.ts` leaves in the model target for this module to fill in. */\nexport const FQN = \"<fqn>\";\n/**\n * The service being adopted, in the model example's header. It is a placeholder\n * for the same reason `<fqn>` is: the example is handed to an agent that copies\n * it, and a header naming payment-service travelled verbatim into every other\n * service's model — the more convincingly for sitting one line above an\n * `extend` the brief HAD substituted.\n */\nexport const SVC = \"<svc>\";\n\n/** The token an example carries where loam has no id to substitute. Short on purpose — see `ExtendPoint`. */\nconst PLACEHOLDER = \"<your-element-id>\";\n\n/** What every `<fqn>` becomes, and the sentence that explains a placeholder. */\nexport interface ExtendPoint {\n  id: string;\n  /**\n   * Why `id` is a placeholder, carried ONCE as a comment above the example\n   * rather than substituted into it. `<fqn>` occupies three code positions —\n   * the `extend` line, the source of a container edge, and `view of` — and the\n   * explanation only reads as an instruction in the first: a 103-character\n   * English sentence standing in for an id inside `view of … { include * }` is\n   * noise the agent has to read past, on the command's most common invocation.\n   */\n  note?: string;\n}\n\n/**\n * Which element an extending `model.likec4` says it is inside — the id, when\n * the map leaves no doubt, and a placeholder plus the doubt when it does.\n *\n * Four answers because the map is in four states and only one of them has an\n * answer to give. With exactly ONE service-level element resolving to this\n * service, `extend <that id> {` is the file's first line and printing anything\n * else makes an agent go and look it up. With NONE, there is nothing to extend\n * yet — the landscape target below this one is what the agent must do first, and\n * saying so is what stops it inventing an id and writing a model that cannot\n * parse. With SEVERAL — `landscape.binding-duplicate`, a real and reported\n * state — loam must not choose: every element→service join in the fleet picks\n * one of them arbitrarily, so a brief that named one would be teaching an agent\n * the arbitrary answer as the right one. And when the map could not be READ\n * (`modelled === null`) the empty element list is evidence of nothing: \"write\n * the element into the map first\" is exactly the instruction that draws a second\n * box for a service the map already holds, so that arm says the map is\n * unreadable and asks for no map write at all.\n */\nexport function extendPoint(landscape: LandscapeContext): ExtendPoint {\n  if (landscape.modelled === null) {\n    return {\n      id: PLACEHOLDER,\n      note:\n        \"the fleet map (architecture/) does not parse, so loam cannot say which element binds this directory. \" +\n        \"Fix the map first — the landscape section of this brief names the documents that failed — then write \" +\n        \"the id of the element that resolves to this service here.\",\n    };\n  }\n  const ids = landscape.elements.map((e) => e.id);\n  const [only, ...rest] = ids;\n  if (only === undefined) {\n    return {\n      id: PLACEHOLDER,\n      note:\n        \"nothing in the fleet map resolves to this directory yet. Add the element to \" +\n        \"architecture/landscape.likec4 first — the landscape target below — then write its id here.\",\n    };\n  }\n  return { id: rest.length === 0 ? only : `<one of: ${ids.join(\", \")}>` };\n}\n\n/**\n * An example with its placeholders resolved, and the placeholder's explanation\n * prepended as a comment when there is one.\n *\n * Guarded on the example actually containing `<fqn>`: the note is about that\n * substitution, and heading an example that never had one with it would answer a\n * question its reader did not ask.\n */\nexport function exampleFor(example: string, extend: ExtendPoint, service: string): string {\n  const body = example.replaceAll(FQN, extend.id).replaceAll(SVC, service);\n  if (extend.note === undefined || !example.includes(FQN)) return body;\n  return `${commentLines(`${extend.id} is a placeholder: ${extend.note}`)}\\n\\n${body}`;\n}\n\n/** One sentence as `//` lines, wrapped to the width the examples around it are written at. */\nfunction commentLines(text: string, width = 76): string {\n  const out: string[] = [];\n  let line = \"//\";\n  for (const word of text.trim().split(/\\s+/)) {\n    if (line !== \"//\" && line.length + 1 + word.length > width) {\n      out.push(line);\n      line = `// ${word}`;\n    } else line = `${line} ${word}`;\n  }\n  out.push(line);\n  return out.join(\"\\n\");\n}\n"]}

package/dist/core/brief/map/owed.js

@@ -0,0 +1,284 @@
+/**
+ * The write one service still owes `architecture/landscape.likec4`: the
+ * target the brief hands over (`landscapeArtifact` — its shape rules and the
+ * example block or edges) and the instruction in prose (`instructionFor` —
+ * the file, the block, and the consequence, in the four states a landscape
+ * can be in). Both exist to stop an agent inventing a parallel model: the
+ * fleet has already drawn some of these boxes and edges, and a baseline has to
+ * attach.
+ *
+ * A sub-package of `core/brief/` because that package sits at its five-file
+ * cap and `landscape.ts` — which READS what the map already says about the
+ * service and decides which state it is in — had parked at the file ceiling
+ * with its object literals collapsed onto single lines to fit. The two halves
+ * are distinct subjects: one is the derivation over a parsed document, the
+ * other is all of the prose plus the vocabulary that prose reads (`BrokenMap`
+ * and its builder live here for that reason — beside the arm that spends them,
+ * not in the caller that fills them). The only tie back to the parent is
+ * `import type { BriefTarget }`, which `verbatimModuleSyntax` erases, so this
+ * package value-imports nothing from `../` and the package graph stays acyclic.
+ */
+import { relative } from "node:path";
+import { spellCall, edgeTemplates } from "../../c4/resolve/attested.js";
+/**
+ * The LikeC4 identifier the fleet map's element for a service conventionally
+ * carries: the directory name, camel-cased. A suggestion and nothing more —
+ * `metadata { service '<id>' }` is what joins the element to the directory —
+ * but a brief handing over a concrete block gets followed, and one describing
+ * a block in prose gets improvised on.
+ */
+function elementIdFor(service) {
+    const parts = service.split(/[^A-Za-z0-9]+/).filter((p) => p !== "");
+    if (parts.length === 0)
+        return "service";
+    const head = parts[0].toLowerCase();
+    const tail = parts.slice(1).map((p) => p[0].toUpperCase() + p.slice(1).toLowerCase());
+    const id = head + tail.join("");
+    // LikeC4 identifiers cannot open with a digit; a service id can.
+    return /^[0-9]/.test(id) ? `svc${id[0].toUpperCase()}${id.slice(1)}` : id;
+}
+/**
+ * The write this service still owes `architecture/landscape.likec4`.
+ *
+ * `expects` is what the fleet ALREADY calls on the service — those edges exist
+ * in the map today, so the example draws the outbound side as a comment rather
+ * than telling an agent to duplicate an edge that is already there. With
+ * `elementId` set the example is EDGES ONLY, on the element that exists: a
+ * block here would be the second box the edgeless state exists to refuse, and
+ * the attested calls are listed as comments the agent turns into edges by
+ * naming the other party as the map spells it.
+ */
+function landscapeBlock(req) {
+    const { service, expects, present } = req;
+    if (req.elementId !== undefined) {
+        const id = req.elementId;
+        return [
+            "model {",
+            `  // ... every element stays exactly as it is — ${id} already resolves to ${req.servicePath}/ ...`,
+            "",
+            "  // every call in or out of it, one edge each, on the existing element:",
+            `  //   ${id} -> <callee> 'Calls <operationId>' { metadata { op '<operationId>' } }`,
+            `  //   <caller> -> ${id} 'Calls <operationId>' { metadata { op '<operationId>' } }`,
+            ...(req.attested.length > 0
+                ? [
+                    `  // the calls ${req.servicePath}/model.likec4 already attests, as the model spells the other party:`,
+                    ...req.attested.map((c) => `  //   ${id} ${spellCall(c)}`),
+                ]
+                : []),
+            "}",
+        ].join("\n");
+    }
+    const id = elementIdFor(service);
+    const calls = expects.length > 0
+        ? expects.map((op) => `//   <caller> -> ${id} 'Calls ${op}' { metadata { op '${op}' } }`)
+        : [`//   <caller> -> ${id} 'Calls <operationId>' { metadata { op '<operationId>' } }`];
+    const model = [
+        "model {",
+        ...(present ? ["  // ... the fleet's other services stay exactly as they are ...", ""] : []),
+        `  ${id} = softwareSystem '${service}' {`,
+        "    description '<one line: what this service is responsible for>'",
+        `    metadata { service '${service}' }`,
+        "  }",
+        "",
+        "  // every call in or out of it, one edge each:",
+        ...calls.map((line) => `  ${line}`),
+        "}",
+    ];
+    // When the file does not exist the example is the WHOLE file, so it carries
+    // the `specification` block a bare `model` would be rejected without: the
+    // brief must never hand over a document `loam validate` refuses. When the file
+    // does exist the example is a fragment to splice, and repeating a
+    // `specification` block there would invite a second one.
+    return present
+        ? model.join("\n")
+        : ["specification {", "  element softwareSystem", "}", "", ...model].join("\n");
+}
+const OP_EDGE_RULE = "Draw every cross-service call as an edge carrying the operation it uses: `a -> b 'Calls createSplit' { metadata { op 'createSplit' } }`. The `op` must be an operationId the TARGET's openapi.yaml defines, or `spine.op-undefined` (error) — a broken contract between services.";
+/** What the edgeless state costs when a check is watching — the ordinary case. */
+const ISOLATED_RULE = (servicePath) => `\`loam validate --all\` reports \`landscape.service-isolated\` (warn) while this element has no edge and ` +
+    `\`${servicePath}/model.likec4\` declares a call across its boundary; with no such call it stays silent, so ` +
+    `an edgeless service that truly calls nothing is correct, and this brief says so.`;
+/**
+ * The same state under `#external`, where NO check is watching.
+ *
+ * `landscape.service-isolated` removes every `#external` element from its
+ * subject set — the fix that stopped a foreign box answering for one of our
+ * directories — so on this tree the warning the brief used to promise cannot
+ * fire, measured: `validate --all` reports `landscape.matched` and the full
+ * `--json` findings walk holds no isolation finding at all. A brief that names
+ * a warning nothing will raise is worse than one that says nothing, because the
+ * agent budgets against the check instead of against the sentence.
+ */
+const EXTERNAL_RULE = (elementId, servicePath) => `\`${elementId}\` carries \`#external\`, so \`landscape.service-isolated\` will NOT fire here whatever this ` +
+    `element's edges are — the check skips every element the map marks as somebody else's, exactly as the two ` +
+    `binding checks do. Nothing in \`loam validate --all\` names this state; this brief is the only place it is ` +
+    `said. If \`${servicePath}/\` is ours, drop \`#external\` from the element and the check applies again; if it ` +
+    `is genuinely somebody else's, the calls belong on the element of the service that makes them.`;
+/** The fleet map's own brief — assembled per service, because the write it owes names the service. */
+export function landscapeArtifact(req) {
+    const { service, servicePath, elementId } = req;
+    const whole = "This file is the WHOLE FLEET's, not this service's. Add to it; never rewrite it. Everything already in `model { ... }` belongs to the other services, and replacing the file destroys their map along with their edges.";
+    return {
+        artifact: "landscape.likec4",
+        required: true,
+        purpose: `the fleet map — ${elementId === undefined
+            ? "until an element here resolves to this directory, the service is documented"
+            : "an element here resolves to this directory and no edge touches it, so the service is drawn"} and invisible to every cross-service check`,
+        shape: elementId === undefined
+            ? [
+                whole,
+                `Add one top-level element for the service, bound to its directory: \`metadata { service '${service}' }\`. Until an element resolves to \`${servicePath}/\`, \`loam validate --all\` reports \`landscape.service-unmodelled\` (error).`,
+                "Bind rather than rename: a binding whose id names no directory is `landscape.binding-unknown` (error), and two elements binding the SAME directory is `landscape.binding-duplicate` (warn) — every element→service join then picks one of them arbitrarily.",
+                OP_EDGE_RULE,
+                "If the file does not exist yet, create it with a `specification { ... }` block declaring the kinds you use, then the `model { ... }` block. A landscape that does not parse is `landscape.invalid` (error) and blinds every cross-service check at once.",
+            ]
+            : [
+                whole,
+                `An element already resolves to \`${servicePath}/\` (\`${elementId}\`). Do NOT add a second one — two elements resolving to one directory is \`landscape.binding-duplicate\` (warn) and every element→service join then picks one of them arbitrarily. What the map lacks is every call in or out of it.`,
+                OP_EDGE_RULE,
+                req.external === true ? EXTERNAL_RULE(elementId, servicePath) : ISOLATED_RULE(servicePath),
+            ],
+        example: landscapeBlock(req),
+    };
+}
+/**
+ * That record, built from a project's diagnostics — beside the type it fills and
+ * the arm that reads it, rather than in the caller.
+ *
+ * Spelled exactly as `commands/validate/fleet/landscape.ts` spells it for
+ * `landscape.invalid` — deduped, relative to the docs root, `/`-joined — because
+ * the two surfaces are read one after the other on the same tree and an agent
+ * has to be able to tell that they name the same file.
+ */
+export function brokenDocuments(docsDir, land) {
+    const paths = [...new Set(land.errors.map((e) => e.sourceFsPath).filter((p) => p !== undefined))]
+        .map((abs) => relative(docsDir, abs).split(/[\\/]/).join("/"))
+        .sort();
+    return { paths, errors: land.errors.length };
+}
+/**
+ * The fleet-map instruction, in the four states a landscape can be in. It says
+ * the file, the block, and the consequence, in that order. The consequence is
+ * the part agents acted on: "add an element" reads as tidiness, "until you do,
+ * `loam validate --all` fails and no cross-service check can see this service"
+ * reads as work.
+ */
+export function instructionFor(req) {
+    const { service, state, expects, servicePath } = req;
+    const id = elementIdFor(service);
+    const bind = `an element bound with \`metadata { service '${service}' }\``;
+    const consequence = `Until one resolves, \`loam validate --all\` reports \`landscape.service-unmodelled\` (error) for ` +
+        `${servicePath}/: the service is documented and invisible — no edge into it can be checked ` +
+        `against its openapi.yaml, and no feature can draw a call to it.`;
+    // `expects` is reachable only through inbound edges, so it is empty in every
+    // state that ASKS for an element — the edgeless one by definition. (The
+    // unparseable state can carry it, off the landscape-file fallback, and that
+    // arm deliberately does not append this sentence: it asks for no element, so
+    // "your element is what they will resolve to" would name one loam has not
+    // read.) It is threaded through anyway rather than dropped: the caller
+    // computes it once, and the day an unmodelled service can inherit an edge (a
+    // container-level binding, say) the sentence is already here.
+    const owed = expects.length > 0
+        ? ` The fleet already calls ${expects.map((o) => `'${o}'`).join(", ")} on this service, so those edges exist; your element is what they will resolve to.`
+        : "";
+    if (state === "absent") {
+        return (`architecture/landscape.likec4 does not exist yet. Create it with a \`specification { ... }\` block ` +
+            `declaring the kinds you use and a \`model { ... }\` block containing ${bind} ` +
+            `(conventionally \`${id} = softwareSystem '${service}'\`), plus one edge per cross-service call, each ` +
+            `carrying \`metadata { op '<operationId>' }\`. ${consequence}${owed}`);
+    }
+    if (state === "unparseable") {
+        // The map is the whole `architecture/` project, so the document that broke
+        // is usually a SIBLING of the landscape — a use case, a palette. This arm
+        // named `architecture/landscape.likec4` regardless and told an agent to go
+        // and fix parse errors in a file that has none, contradicting the
+        // `landscape.invalid` that `validate --all` prints on the same tree one
+        // second later. The EDGELESS arm below carries the same rule in its own WHY:
+        // never name bytes loam did not read.
+        const b = req.broken;
+        const named = b === undefined || b.paths.length === 0
+            ? "The fleet map (architecture/) does not parse"
+            : `${b.paths.join(", ")} ${b.paths.length === 1 ? "does" : "do"} not parse (${String(b.errors)} error(s)` +
+                `${b.paths.length === 1 ? "" : " between them"}), so the fleet map (architecture/) cannot be read`;
+        return (`${named} (\`landscape.invalid\`). Nothing can be said about what the map already models — not that it ` +
+            `lacks an element for ${servicePath}/, and not that it holds one — so this brief asks for no edit to it. ` +
+            `Fix the parse errors first (they blind every cross-service check at once, and \`loam validate --all\` ` +
+            `names the same file), then re-run \`loam adopt --service ${service}\`: it will say whether the map already ` +
+            `holds ${bind}, and adding one before then risks a second box for a service the map already draws ` +
+            `(\`landscape.binding-duplicate\`).`);
+    }
+    if (state === "edgeless")
+        return edgelessInstruction(req);
+    return (`Nothing in architecture/landscape.likec4 resolves to ${servicePath}/. ADD to that file — do not rewrite ` +
+        `it, every other service's map is in there — ${bind}, conventionally ` +
+        `\`${id} = softwareSystem '${service}'\`, inside the existing \`model { ... }\` block, and draw each ` +
+        `cross-service call as an edge carrying \`metadata { op '<operationId>' }\`. ${consequence}${owed}`);
+}
+/**
+ * The fourth state, in two arms: with attested calls it names each and says to
+ * carry it up as ONE edge on the existing element; without, it points at the
+ * walk stops that produce the evidence and otherwise says draw NOTHING — an
+ * invented edge is a dependency the fleet then plans against. Neither arm asks
+ * for a second element, and both name the tags loam does not read.
+ */
+/**
+ * Which sentence the attested arm may end on: what will hold the agent to this
+ * edit, or the admission that nothing will.
+ *
+ * `landscape.service-isolated` skips every `#external` element, so on such a
+ * tree the promise "reports it until an edge lands" is one the check cannot
+ * keep — and the brief was making it on exactly the tree that fix was written
+ * for (verification 2026-09-04). The `#external` arm says so instead, and says
+ * how to make the check apply.
+ */
+function accountability(req, id) {
+    if (req.external === true) {
+        return (`\`${id}\` carries \`#external\`, so \`landscape.service-isolated\` will NOT fire here whatever you draw — ` +
+            `the check skips every element the map marks as somebody else's. Nothing in \`loam validate --all\` names ` +
+            `this state; this brief is the only place it is said. Drop \`#external\` from the element if ` +
+            `${req.servicePath}/ is ours, and the check applies again.`);
+    }
+    return ("`loam validate --all` reports `landscape.service-isolated` (warn) until an edge lands — ONE edge, on any " +
+        "of them: the check is touched/untouched, not a set difference, so nothing will name the calls you leave " +
+        "undrawn.");
+}
+function edgelessInstruction(req) {
+    const { servicePath, attested, foreignTags } = req;
+    const id = req.elementId ?? elementIdFor(req.service);
+    // "the fleet map (architecture/)" rather than the landscape FILE: the map is
+    // the whole project, an element may be declared in any document of it, and
+    // LikeC4 hands back no source document for an element — so naming a file
+    // here would be a claim about bytes loam did not read. The write still lands
+    // in `architecture/landscape.likec4`; the target's `path` says so.
+    const opening = `\`${id}\` in the fleet map (architecture/) resolves to ${servicePath}/ and no edge in the map touches it — ` +
+        `the service is drawn and invisible to every cross-service check.`;
+    const tags = foreignTags.length === 0
+        ? ""
+        : ` The element carries ${foreignTags.map((t) => `#${t}`).join(", ")} — tags loam does not read; if one marks a ` +
+            `placeholder drawn ahead of adoption, clearing it is part of this edit, because a view written ` +
+            `\`exclude element.tag = #<that>\` keeps an adopted service hidden.`;
+    if (attested.length > 0) {
+        // The edge form follows the calls' direction (`edgeTemplates`): this arm
+        // used to spell the outbound form alone, so an inbound call was carried
+        // up backwards.
+        const forms = edgeTemplates(id, attested)
+            .map((t) => `\`${t}\``)
+            .join(" or ");
+        return (`${opening} ${servicePath}/model.likec4 already declares ${attested.length} call(s) across its boundary: ` +
+            `${attested.map(spellCall).join(", ")}. Carry each one up as ONE edge on \`${id}\`, collapsed to the ` +
+            `service — ${forms} for a call, \`publishes\`/\`consumes\` ` +
+            `for an event — naming the other party as the map already spells it; where the model's word names a ` +
+            `different thing in the map, say so in the hand-back instead of drawing it. Do not add a second element: ` +
+            `one already resolves. ${accountability(req, id)} Carry all of them up now, or say in the hand-back which ` +
+            `you did not and why.${tags}`);
+    }
+    return (`${opening} Nothing in ${servicePath}/model.likec4 attests a call across its boundary — absent, unparseable ` +
+        `and internal-only read alike here, because this brief may only name calls already attested. Draw the ones ` +
+        `the walk's outbound and message stops (stops 4 and 7) find, each as one edge on \`${id}\` carrying ` +
+        `\`metadata { op '<operationId>' }\` for a call or \`publishes\`/\`consumes\` for an event; if the service ` +
+        `genuinely makes and receives no call, draw NOTHING — an invented edge is a dependency the fleet then plans ` +
+        `against, and an edgeless element that is TRUE is a fact. Do not add a second element: one already resolves. ` +
+        `Nothing in \`loam validate --all\` names this state while the model attests no call; this brief is the only ` +
+        `place it is said.${tags}`);
+}
+//# sourceMappingURL=owed.js.map

package/dist/core/brief/map/owed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owed.js","sourceRoot":"","sources":["../../../../src/core/brief/map/owed.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The write one service still owes `architecture/landscape.likec4`: the\n * target the brief hands over (`landscapeArtifact` — its shape rules and the\n * example block or edges) and the instruction in prose (`instructionFor` —\n * the file, the block, and the consequence, in the four states a landscape\n * can be in). Both exist to stop an agent inventing a parallel model: the\n * fleet has already drawn some of these boxes and edges, and a baseline has to\n * attach.\n *\n * A sub-package of `core/brief/` because that package sits at its five-file\n * cap and `landscape.ts` — which READS what the map already says about the\n * service and decides which state it is in — had parked at the file ceiling\n * with its object literals collapsed onto single lines to fit. The two halves\n * are distinct subjects: one is the derivation over a parsed document, the\n * other is all of the prose plus the vocabulary that prose reads (`BrokenMap`\n * and its builder live here for that reason — beside the arm that spends them,\n * not in the caller that fills them). The only tie back to the parent is\n * `import type { BriefTarget }`, which `verbatimModuleSyntax` erases, so this\n * package value-imports nothing from `../` and the package graph stays acyclic.\n */\nimport { relative } from \"node:path\";\nimport type { LikeC4Error } from \"../../c4/likec4.js\";\nimport { spellCall, edgeTemplates, type AttestedCall } from \"../../c4/resolve/attested.js\";\nimport type { BriefTarget } from \"../targets.js\";\n\n/**\n * The LikeC4 identifier the fleet map's element for a service conventionally\n * carries: the directory name, camel-cased. A suggestion and nothing more —\n * `metadata { service '<id>' }` is what joins the element to the directory —\n * but a brief handing over a concrete block gets followed, and one describing\n * a block in prose gets improvised on.\n */\nfunction elementIdFor(service: string): string {\n  const parts = service.split(/[^A-Za-z0-9]+/).filter((p) => p !== \"\");\n  if (parts.length === 0) return \"service\";\n  const head = parts[0]!.toLowerCase();\n  const tail = parts.slice(1).map((p) => p[0]!.toUpperCase() + p.slice(1).toLowerCase());\n  const id = head + tail.join(\"\");\n  // LikeC4 identifiers cannot open with a digit; a service id can.\n  return /^[0-9]/.test(id) ? `svc${id[0]!.toUpperCase()}${id.slice(1)}` : id;\n}\n\n/* ------------------------------------------------------------------ */\n/* The target                                                          */\n/* ------------------------------------------------------------------ */\n\n/** What `landscapeArtifact` needs — one record, because the fields only ever travel together. */\nexport interface LandscapeArtifactRequest {\n  service: string;\n  expects: string[];\n  present: boolean;\n  servicePath: string;\n  /** The element that already resolves to the service — set only in the edgeless state — and the calls its model attests. */\n  elementId?: string;\n  /**\n   * Whether that element carries `#external`. It changes what the brief may\n   * PROMISE and nothing else: `landscape.service-isolated` removes every\n   * `#external` element from its subject set, so on such a tree no warning holds\n   * the agent accountable, and saying one will is the false promise this flag\n   * exists to stop (verification 2026-09-04).\n   */\n  external?: boolean;\n  attested: AttestedCall[];\n}\n\n/**\n * The write this service still owes `architecture/landscape.likec4`.\n *\n * `expects` is what the fleet ALREADY calls on the service — those edges exist\n * in the map today, so the example draws the outbound side as a comment rather\n * than telling an agent to duplicate an edge that is already there. With\n * `elementId` set the example is EDGES ONLY, on the element that exists: a\n * block here would be the second box the edgeless state exists to refuse, and\n * the attested calls are listed as comments the agent turns into edges by\n * naming the other party as the map spells it.\n */\nfunction landscapeBlock(req: LandscapeArtifactRequest): string {\n  const { service, expects, present } = req;\n  if (req.elementId !== undefined) {\n    const id = req.elementId;\n    return [\n      \"model {\",\n      `  // ... every element stays exactly as it is — ${id} already resolves to ${req.servicePath}/ ...`,\n      \"\",\n      \"  // every call in or out of it, one edge each, on the existing element:\",\n      `  //   ${id} -> <callee> 'Calls <operationId>' { metadata { op '<operationId>' } }`,\n      `  //   <caller> -> ${id} 'Calls <operationId>' { metadata { op '<operationId>' } }`,\n      ...(req.attested.length > 0\n        ? [\n            `  // the calls ${req.servicePath}/model.likec4 already attests, as the model spells the other party:`,\n            ...req.attested.map((c) => `  //   ${id} ${spellCall(c)}`),\n          ]\n        : []),\n      \"}\",\n    ].join(\"\\n\");\n  }\n  const id = elementIdFor(service);\n  const calls =\n    expects.length > 0\n      ? expects.map((op) => `//   <caller> -> ${id} 'Calls ${op}' { metadata { op '${op}' } }`)\n      : [`//   <caller> -> ${id} 'Calls <operationId>' { metadata { op '<operationId>' } }`];\n  const model = [\n    \"model {\",\n    ...(present ? [\"  // ... the fleet's other services stay exactly as they are ...\", \"\"] : []),\n    `  ${id} = softwareSystem '${service}' {`,\n    \"    description '<one line: what this service is responsible for>'\",\n    `    metadata { service '${service}' }`,\n    \"  }\",\n    \"\",\n    \"  // every call in or out of it, one edge each:\",\n    ...calls.map((line) => `  ${line}`),\n    \"}\",\n  ];\n  // When the file does not exist the example is the WHOLE file, so it carries\n  // the `specification` block a bare `model` would be rejected without: the\n  // brief must never hand over a document `loam validate` refuses. When the file\n  // does exist the example is a fragment to splice, and repeating a\n  // `specification` block there would invite a second one.\n  return present\n    ? model.join(\"\\n\")\n    : [\"specification {\", \"  element softwareSystem\", \"}\", \"\", ...model].join(\"\\n\");\n}\n\nconst OP_EDGE_RULE =\n  \"Draw every cross-service call as an edge carrying the operation it uses: `a -> b 'Calls createSplit' { metadata { op 'createSplit' } }`. The `op` must be an operationId the TARGET's openapi.yaml defines, or `spine.op-undefined` (error) — a broken contract between services.\";\n\n/** What the edgeless state costs when a check is watching — the ordinary case. */\nconst ISOLATED_RULE = (servicePath: string): string =>\n  `\\`loam validate --all\\` reports \\`landscape.service-isolated\\` (warn) while this element has no edge and ` +\n  `\\`${servicePath}/model.likec4\\` declares a call across its boundary; with no such call it stays silent, so ` +\n  `an edgeless service that truly calls nothing is correct, and this brief says so.`;\n\n/**\n * The same state under `#external`, where NO check is watching.\n *\n * `landscape.service-isolated` removes every `#external` element from its\n * subject set — the fix that stopped a foreign box answering for one of our\n * directories — so on this tree the warning the brief used to promise cannot\n * fire, measured: `validate --all` reports `landscape.matched` and the full\n * `--json` findings walk holds no isolation finding at all. A brief that names\n * a warning nothing will raise is worse than one that says nothing, because the\n * agent budgets against the check instead of against the sentence.\n */\nconst EXTERNAL_RULE = (elementId: string, servicePath: string): string =>\n  `\\`${elementId}\\` carries \\`#external\\`, so \\`landscape.service-isolated\\` will NOT fire here whatever this ` +\n  `element's edges are — the check skips every element the map marks as somebody else's, exactly as the two ` +\n  `binding checks do. Nothing in \\`loam validate --all\\` names this state; this brief is the only place it is ` +\n  `said. If \\`${servicePath}/\\` is ours, drop \\`#external\\` from the element and the check applies again; if it ` +\n  `is genuinely somebody else's, the calls belong on the element of the service that makes them.`;\n\n/** The fleet map's own brief — assembled per service, because the write it owes names the service. */\nexport function landscapeArtifact(req: LandscapeArtifactRequest): Omit<BriefTarget, \"path\" | \"exists\" | \"action\"> {\n  const { service, servicePath, elementId } = req;\n  const whole =\n    \"This file is the WHOLE FLEET's, not this service's. Add to it; never rewrite it. Everything already in `model { ... }` belongs to the other services, and replacing the file destroys their map along with their edges.\";\n  return {\n    artifact: \"landscape.likec4\",\n    required: true,\n    purpose: `the fleet map — ${\n      elementId === undefined\n        ? \"until an element here resolves to this directory, the service is documented\"\n        : \"an element here resolves to this directory and no edge touches it, so the service is drawn\"\n    } and invisible to every cross-service check`,\n    shape:\n      elementId === undefined\n        ? [\n            whole,\n            `Add one top-level element for the service, bound to its directory: \\`metadata { service '${service}' }\\`. Until an element resolves to \\`${servicePath}/\\`, \\`loam validate --all\\` reports \\`landscape.service-unmodelled\\` (error).`,\n            \"Bind rather than rename: a binding whose id names no directory is `landscape.binding-unknown` (error), and two elements binding the SAME directory is `landscape.binding-duplicate` (warn) — every element→service join then picks one of them arbitrarily.\",\n            OP_EDGE_RULE,\n            \"If the file does not exist yet, create it with a `specification { ... }` block declaring the kinds you use, then the `model { ... }` block. A landscape that does not parse is `landscape.invalid` (error) and blinds every cross-service check at once.\",\n          ]\n        : [\n            whole,\n            `An element already resolves to \\`${servicePath}/\\` (\\`${elementId}\\`). Do NOT add a second one — two elements resolving to one directory is \\`landscape.binding-duplicate\\` (warn) and every element→service join then picks one of them arbitrarily. What the map lacks is every call in or out of it.`,\n            OP_EDGE_RULE,\n            req.external === true ? EXTERNAL_RULE(elementId, servicePath) : ISOLATED_RULE(servicePath),\n          ],\n    example: landscapeBlock(req),\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* The instruction                                                     */\n/* ------------------------------------------------------------------ */\n\n/** Which documents of `architecture/` failed, and how many errors they carry between them. */\nexport interface BrokenMap {\n  /** Docs-relative POSIX paths, deduped and sorted — spelled as `landscape.invalid` spells them. */\n  paths: string[];\n  errors: number;\n}\n\n/**\n * That record, built from a project's diagnostics — beside the type it fills and\n * the arm that reads it, rather than in the caller.\n *\n * Spelled exactly as `commands/validate/fleet/landscape.ts` spells it for\n * `landscape.invalid` — deduped, relative to the docs root, `/`-joined — because\n * the two surfaces are read one after the other on the same tree and an agent\n * has to be able to tell that they name the same file.\n */\nexport function brokenDocuments(docsDir: string, land: { errors: readonly LikeC4Error[] }): BrokenMap {\n  const paths = [...new Set(land.errors.map((e) => e.sourceFsPath).filter((p): p is string => p !== undefined))]\n    .map((abs) => relative(docsDir, abs).split(/[\\\\/]/).join(\"/\"))\n    .sort();\n  return { paths, errors: land.errors.length };\n}\n\n/** The inputs of `instructionFor` — a record, because the function sat at the parameter cap. */\nexport interface InstructionRequest {\n  service: string;\n  state: \"absent\" | \"unparseable\" | \"unmodelled\" | \"edgeless\";\n  expects: string[];\n  servicePath: string;\n  /**\n   * The documents that failed (`unparseable` state only). Optional so the other\n   * three arms need not carry it, and the arm degrades to naming the project\n   * rather than guessing a file when a caller has none.\n   */\n  broken?: BrokenMap;\n  /** The element that already resolves to the service (edgeless state only), and its tags loam does not read. */\n  elementId?: string;\n  /** Whether that element carries `#external` — see `LandscapeArtifactRequest.external`. */\n  external?: boolean;\n  attested: AttestedCall[];\n  foreignTags: string[];\n}\n\n/**\n * The fleet-map instruction, in the four states a landscape can be in. It says\n * the file, the block, and the consequence, in that order. The consequence is\n * the part agents acted on: \"add an element\" reads as tidiness, \"until you do,\n * `loam validate --all` fails and no cross-service check can see this service\"\n * reads as work.\n */\nexport function instructionFor(req: InstructionRequest): string {\n  const { service, state, expects, servicePath } = req;\n  const id = elementIdFor(service);\n  const bind = `an element bound with \\`metadata { service '${service}' }\\``;\n  const consequence =\n    `Until one resolves, \\`loam validate --all\\` reports \\`landscape.service-unmodelled\\` (error) for ` +\n    `${servicePath}/: the service is documented and invisible — no edge into it can be checked ` +\n    `against its openapi.yaml, and no feature can draw a call to it.`;\n  // `expects` is reachable only through inbound edges, so it is empty in every\n  // state that ASKS for an element — the edgeless one by definition. (The\n  // unparseable state can carry it, off the landscape-file fallback, and that\n  // arm deliberately does not append this sentence: it asks for no element, so\n  // \"your element is what they will resolve to\" would name one loam has not\n  // read.) It is threaded through anyway rather than dropped: the caller\n  // computes it once, and the day an unmodelled service can inherit an edge (a\n  // container-level binding, say) the sentence is already here.\n  const owed =\n    expects.length > 0\n      ? ` The fleet already calls ${expects.map((o) => `'${o}'`).join(\", \")} on this service, so those edges exist; your element is what they will resolve to.`\n      : \"\";\n\n  if (state === \"absent\") {\n    return (\n      `architecture/landscape.likec4 does not exist yet. Create it with a \\`specification { ... }\\` block ` +\n      `declaring the kinds you use and a \\`model { ... }\\` block containing ${bind} ` +\n      `(conventionally \\`${id} = softwareSystem '${service}'\\`), plus one edge per cross-service call, each ` +\n      `carrying \\`metadata { op '<operationId>' }\\`. ${consequence}${owed}`\n    );\n  }\n  if (state === \"unparseable\") {\n    // The map is the whole `architecture/` project, so the document that broke\n    // is usually a SIBLING of the landscape — a use case, a palette. This arm\n    // named `architecture/landscape.likec4` regardless and told an agent to go\n    // and fix parse errors in a file that has none, contradicting the\n    // `landscape.invalid` that `validate --all` prints on the same tree one\n    // second later. The EDGELESS arm below carries the same rule in its own WHY:\n    // never name bytes loam did not read.\n    const b = req.broken;\n    const named =\n      b === undefined || b.paths.length === 0\n        ? \"The fleet map (architecture/) does not parse\"\n        : `${b.paths.join(\", \")} ${b.paths.length === 1 ? \"does\" : \"do\"} not parse (${String(b.errors)} error(s)` +\n          `${b.paths.length === 1 ? \"\" : \" between them\"}), so the fleet map (architecture/) cannot be read`;\n    return (\n      `${named} (\\`landscape.invalid\\`). Nothing can be said about what the map already models — not that it ` +\n      `lacks an element for ${servicePath}/, and not that it holds one — so this brief asks for no edit to it. ` +\n      `Fix the parse errors first (they blind every cross-service check at once, and \\`loam validate --all\\` ` +\n      `names the same file), then re-run \\`loam adopt --service ${service}\\`: it will say whether the map already ` +\n      `holds ${bind}, and adding one before then risks a second box for a service the map already draws ` +\n      `(\\`landscape.binding-duplicate\\`).`\n    );\n  }\n  if (state === \"edgeless\") return edgelessInstruction(req);\n  return (\n    `Nothing in architecture/landscape.likec4 resolves to ${servicePath}/. ADD to that file — do not rewrite ` +\n    `it, every other service's map is in there — ${bind}, conventionally ` +\n    `\\`${id} = softwareSystem '${service}'\\`, inside the existing \\`model { ... }\\` block, and draw each ` +\n    `cross-service call as an edge carrying \\`metadata { op '<operationId>' }\\`. ${consequence}${owed}`\n  );\n}\n\n/**\n * The fourth state, in two arms: with attested calls it names each and says to\n * carry it up as ONE edge on the existing element; without, it points at the\n * walk stops that produce the evidence and otherwise says draw NOTHING — an\n * invented edge is a dependency the fleet then plans against. Neither arm asks\n * for a second element, and both name the tags loam does not read.\n */\n/**\n * Which sentence the attested arm may end on: what will hold the agent to this\n * edit, or the admission that nothing will.\n *\n * `landscape.service-isolated` skips every `#external` element, so on such a\n * tree the promise \"reports it until an edge lands\" is one the check cannot\n * keep — and the brief was making it on exactly the tree that fix was written\n * for (verification 2026-09-04). The `#external` arm says so instead, and says\n * how to make the check apply.\n */\nfunction accountability(req: InstructionRequest, id: string): string {\n  if (req.external === true) {\n    return (\n      `\\`${id}\\` carries \\`#external\\`, so \\`landscape.service-isolated\\` will NOT fire here whatever you draw — ` +\n      `the check skips every element the map marks as somebody else's. Nothing in \\`loam validate --all\\` names ` +\n      `this state; this brief is the only place it is said. Drop \\`#external\\` from the element if ` +\n      `${req.servicePath}/ is ours, and the check applies again.`\n    );\n  }\n  return (\n    \"`loam validate --all` reports `landscape.service-isolated` (warn) until an edge lands — ONE edge, on any \" +\n    \"of them: the check is touched/untouched, not a set difference, so nothing will name the calls you leave \" +\n    \"undrawn.\"\n  );\n}\n\nfunction edgelessInstruction(req: InstructionRequest): string {\n  const { servicePath, attested, foreignTags } = req;\n  const id = req.elementId ?? elementIdFor(req.service);\n  // \"the fleet map (architecture/)\" rather than the landscape FILE: the map is\n  // the whole project, an element may be declared in any document of it, and\n  // LikeC4 hands back no source document for an element — so naming a file\n  // here would be a claim about bytes loam did not read. The write still lands\n  // in `architecture/landscape.likec4`; the target's `path` says so.\n  const opening =\n    `\\`${id}\\` in the fleet map (architecture/) resolves to ${servicePath}/ and no edge in the map touches it — ` +\n    `the service is drawn and invisible to every cross-service check.`;\n  const tags =\n    foreignTags.length === 0\n      ? \"\"\n      : ` The element carries ${foreignTags.map((t) => `#${t}`).join(\", \")} — tags loam does not read; if one marks a ` +\n        `placeholder drawn ahead of adoption, clearing it is part of this edit, because a view written ` +\n        `\\`exclude element.tag = #<that>\\` keeps an adopted service hidden.`;\n  if (attested.length > 0) {\n    // The edge form follows the calls' direction (`edgeTemplates`): this arm\n    // used to spell the outbound form alone, so an inbound call was carried\n    // up backwards.\n    const forms = edgeTemplates(id, attested)\n      .map((t) => `\\`${t}\\``)\n      .join(\" or \");\n    return (\n      `${opening} ${servicePath}/model.likec4 already declares ${attested.length} call(s) across its boundary: ` +\n      `${attested.map(spellCall).join(\", \")}. Carry each one up as ONE edge on \\`${id}\\`, collapsed to the ` +\n      `service — ${forms} for a call, \\`publishes\\`/\\`consumes\\` ` +\n      `for an event — naming the other party as the map already spells it; where the model's word names a ` +\n      `different thing in the map, say so in the hand-back instead of drawing it. Do not add a second element: ` +\n      `one already resolves. ${accountability(req, id)} Carry all of them up now, or say in the hand-back which ` +\n      `you did not and why.${tags}`\n    );\n  }\n  return (\n    `${opening} Nothing in ${servicePath}/model.likec4 attests a call across its boundary — absent, unparseable ` +\n    `and internal-only read alike here, because this brief may only name calls already attested. Draw the ones ` +\n    `the walk's outbound and message stops (stops 4 and 7) find, each as one edge on \\`${id}\\` carrying ` +\n    `\\`metadata { op '<operationId>' }\\` for a call or \\`publishes\\`/\\`consumes\\` for an event; if the service ` +\n    `genuinely makes and receives no call, draw NOTHING — an invented edge is a dependency the fleet then plans ` +\n    `against, and an edgeless element that is TRUE is a fact. Do not add a second element: one already resolves. ` +\n    `Nothing in \\`loam validate --all\\` names this state while the model attests no call; this brief is the only ` +\n    `place it is said.${tags}`\n  );\n}\n"]}

package/dist/core/brief/targets.js

@@ -5,8 +5,23 @@
  * one a later check depends on, and test/agent-contract.test.ts pins the
  * mapping. This module is the list alone — `serviceBrief` (brief.ts) resolves
  * it against a docs repo, and the fleet map's own target, whose block names
- * the service, is assembled per service in landscape.ts.
+ * the service, is assembled per service in map/owed.ts.
  */
+/**
+ * The service-local use-case directory, and the one artifact key `ServicePaths`
+ * deliberately does NOT carry.
+ *
+ * `repo/paths.ts` spells the paths loam JOINS ON — the ones a check resolves, a
+ * writer writes and the tree walk classifies a directory by. This is not one of
+ * them: the slot a service's flows are graded out of is the service's whole
+ * LikeC4 project, every `.likec4` under its directory
+ * (`core/usecases/service/flows.ts`), and `usecases/<name>.likec4` is the
+ * CONVENTION the brief publishes for it. Putting the directory in
+ * `ARTIFACT_FILES` would be worse than redundant — `isServiceArtifactName`
+ * reads that table, so a `usecases/` directory anywhere under `services/` would
+ * mint a service.
+ */
+export const USECASES_DIR = "usecases";
 /** The artifacts, in the order a baseline is best written in. */
 export const ARTIFACTS = [
     {
@@ -21,41 +36,41 @@ export const ARTIFACTS = [
         // `loam validate` passing means more than it does. They now live in
         // UNCHECKED, where their status is the point.
         shape: [
-            "A `specification { ... }` block declaring every element kind you use (`element softwareSystem`, `element container`). LikeC4 rejects an undeclared kind, and `loam validate --service <id>` reports it as `c4.invalid` with line numbers.",
-            "A `model { ... }` block holding the service's element, with containers and components nested inside it. The whole file has to parse — `loam validate` runs LikeC4 in-process and reports `c4.invalid` with line numbers.",
-            "The service element binds to this directory: `metadata { service '<id>' }`. Without a binding the element's TITLE has to equal the directory name — and then renaming the box silently unlinks every check that joined the two. The same binding is what makes the FLEET map resolve an element to `services/<id>/`; until one does, `loam validate --all` reports `landscape.service-unmodelled`.",
-            "A call to another service is an edge that names the operation it uses: `a -> b 'Calls createSplit' { metadata { op 'createSplit' } }`. Cross-service edges belong in `architecture/landscape.likec4` (a target of its own, below) — this file cannot even resolve the other service's element — and there the `op` must be an operationId the TARGET's openapi.yaml defines, or `spine.op-undefined` fires.",
+            "No `specification` block of its own: the kinds and tags come from `architecture/landscape.likec4` (a kind this model needs that the map does not declare — `element database`, `element queue` — is added there, once). A model that declares its own element kinds is the standalone shape: it still parses, alone, and loam then reports where its copies of the map's elements diverge (`c4.declaration-diverged`). New models never use it.",
+            "A `model { ... }` block whose body is `extend <id> { ... }` — the fully-qualified id of the element the fleet map already binds to this directory (the landscape section of this brief names it; write the element into the map first when none resolves) — with containers and components nested inside. The binding and the description live on the map's element; this file may add `#tags` and metadata to it and never a description. The whole file has to parse: `loam validate` runs LikeC4 in-process over the map plus this file and reports `c4.invalid` with line numbers.",
+            "A store or component this service OWNS goes INSIDE the `extend <fqn> { }` block, where its id becomes `<fqn>.<name>`: that is the only place an extending model may declare an element, and one declared anywhere else is `c4.element-unowned` (warn) — the fleet project then carries this service's private copy of somebody else's box. A call to another system is an edge from the container that makes it to the other party's element as the map spells it — `marketplace.paymentService.api -> stripe 'Authorizes cards'` — never a copy of that element: the map declares a system this service merely REACHES once, and another service's internals belong in that service's own model. The map still carries the service-level edge the fleet checks read (`metadata { op '<operationId>' }` graded by `spine.op-undefined`); draw it there too.",
+            "The map's element is the binding: `metadata { service '<id>' }` on the element you extend (the landscape target below). Without it the element's title has to equal the directory name — and then renaming the box silently unlinks every check that joined the two. Until something in the map resolves to `services/<id>/`, `loam validate --all` reports `landscape.service-unmodelled` and there is no element for this file to extend.",
         ],
-        example: `specification {
-  element softwareSystem
-  element container
-}
-
+        // `<fqn>` and `<svc>` are PLACEHOLDERS this module leaves literal:
+        // `serviceBrief` (brief.ts) substitutes the landscape element's real id and
+        // the service being adopted, and for `<fqn>` the "the element's id in
+        // architecture/landscape.likec4" wording where the map holds none. ARTIFACTS
+        // stays a static constant — a target list that varied per repository would
+        // be a second thing to keep true. The header carried the literal
+        // `payment-service` for every service, beside an `extend` line that WAS
+        // substituted, so the half of the example that was personalised taught an
+        // agent the other half had been too.
+        example: `// <svc>'s own C4 — what is INSIDE the element the fleet map binds to
+// this directory. The map declares the kinds and the element; this
+// file extends it and re-declares nothing.
 model {
-  paymentService = softwareSystem 'payment-service' {
-    description 'Owns payment authorization and capture'
-    metadata { service 'payment-service' }
-
+  extend <fqn> {
     api = container 'HTTP API'
-    ledger = container 'Ledger store'
+    ledger = database 'Ledger store'
+    api -> ledger 'Writes every authorization'
   }
+  // 'stripe' stands for the OTHER party, spelled as the fleet map already
+  // declares it — loam has no id to substitute here, and inventing one is
+  // the edge that makes the model unresolvable. The containers above are
+  // this example's own: name yours after what they are.
+  <fqn>.api -> stripe 'Authorizes cards'
 }
 
-// Views are LikeC4's, not loam's: loam parses this file and computes no view,
-// and it never reads a STATIC view's contents in any document, so nothing below
-// is read by any check (docs/DESIGN.md rule 26 — the one thing loam does read is
-// a dynamic view's declared steps, and only in the fleet landscape).
-// Keep it for the renderer, which does draw it — 'npx likec4 start' from the docs
-// repo ROOT, once 'loam subsystem sync' has written services/<id>/likec4.config.json:
-// that file is loam's, never yours, and it is what registers this model as a
-// LikeC4 project of its own beside the fleet map. The root project stays scoped
-// to architecture/ (the root likec4.config.json) because every model declares
-// its own 'specification' block, and a root that merged them would read each
-// declaration as a duplicate.
-// Scoped to one service 'include *' is cheap; the same line in
-// architecture/landscape.likec4 walks every call in the fleet and takes minutes.
+// Views are LikeC4's, not loam's (docs/DESIGN.md rule 26). Render with
+// 'npx likec4 start' from the docs repo root: this file is part of the root
+// project, beside the map — nothing else to write.
 views {
-  view of paymentService {
+  view of <fqn> {
     include *
   }
 }
@@ -127,6 +142,7 @@ Operations: refundPayment
         shape: [
             "Same grammar and frontmatter as spec.md: `## Requirements`, `### Requirement:` + `#### Scenario:` with Given/When/Then. The same checks read it.",
             "A `Covers:` line per requirement names what its scenarios exercise: a C4 element id (`paymentService.db`), an edge (`paymentService -> kafka`), or a health signal from health.yaml (`alert:<id>` / `sli:<id>`). Every entry must resolve, or `covers.unknown` (warn) flags the typo.",
+            "A requirement whose `Covers:` names containers may have its hop sequence drawn as a `dynamic view` in a `.likec4` beside model.likec4 (`usecases/<name>.likec4` by convention; the renderer's per-service project reads every `.likec4` under the directory, and loam reads the same set), tagged `#req-<Requirement-ID>` — with the tag declared in `architecture/landscape.likec4`'s `specification` where the model extends the map, or in model.likec4's own block where it declares one; declaring it in BOTH is a duplicate, and the code lands where the second declaration's FILE is, not at fleet altitude: `c4.invalid` (an ERROR, and the model's grading is suspended behind it) when the tags-only block is in model.likec4, `usecase.flow-invalid` when it is in a sibling. `c4.fleet-project-invalid` is the fleet-scope class one step out — TWO SERVICES each declaring the same tag locally, which no per-service project sees. Graded by `loam validate --service <id>` (`usecase.step-unbacked` when a hop names a call the model does not declare, `usecase.requirement-unresolved` when the tag names no `Requirement-ID` here or in spec.md). Optional; nothing grades its absence. Never `architecture/usecases/`, which cannot resolve a container.",
             "Optional, but expected for a service with real architecture: every alert/SLI health.yaml declares wants a covering requirement here (`health.uncovered`, warn) — a signal nothing tests is dashboard decoration.",
             "Write the obligations no business requirement states — the transactional outbox, what a caller's retry may assume, what pages whom. An arch scenario becomes an integration/ops test, not an acceptance test.",
         ],
@@ -152,6 +168,55 @@ Covers: paymentService.db, paymentService -> kafka
 - **Given** an event in the outbox
 - **When** the broker is unavailable
 - **Then** the state stays committed and the event is published once it returns
+`,
+    },
+    {
+        artifact: "usecases/<name>.likec4",
+        key: "usecasesDir",
+        // Never required, and here the optionality is a RULE rather than a
+        // judgement. docs/DESIGN.md rule 26 — "presence is never owed. A model with
+        // no views is missing nothing loam wants, and no check may grade its
+        // absence" — is enforced by scripts/arch-check.mjs, not merely written, so
+        // there is no `service.usecases-missing` and there never will be one.
+        //
+        // The slot is briefed anyway because a team cannot choose a slot nobody
+        // named. The grader landed 2026-09-03 (`core/usecases/service/flows.ts`) and
+        // `c4.valid` has been reporting ` · K tagged flow(s) graded` ever since, on
+        // an axis nothing scaffolded, briefed or named — so the only way to discover
+        // it was to read the source. Publication is the whole of this entry: every
+        // rule below is either a check that already exists or a convention loam
+        // states and never grades, and each says which it is.
+        required: false,
+        purpose: "optional — one requirement's hop sequence, drawn as a LikeC4 dynamic view over this service's own containers",
+        shape: [
+            "A `dynamic view` in a `.likec4` under this service's directory. THE SLOT IS THE PROJECT: `loam subsystem sync` registers every `.likec4` under `services/<…>/<id>/` as one LikeC4 project, and loam reads exactly the set the renderer reads — `model.likec4` plus every sibling, recursively. `usecases/<name>.likec4` is the convention this brief publishes, and `<name>` is yours. Never `architecture/usecases/`, which is a different project: it holds the map and no service's containers, so a hop naming one is `landscape.invalid` for the whole fleet.",
+            "`#req-<Requirement-ID>` as the FIRST thing in the view body, before `title` — written after it, LikeC4 reports five parse errors and none of them mentions tags. The tag is the opt-in: an untagged view is somebody's hand-drawn diagram and loam never says a word about it. The slug is the `Requirement-ID` from this service's own `spec.md` or `arch.spec.md` with every character outside `[A-Za-z0-9_-]` flattened to `-`; a slug naming no requirement of this service is `usecase.requirement-unresolved`. Several `#req-` tags on one view are legal and normal.",
+            "DECLARE the tag exactly once — in `architecture/landscape.likec4`'s `specification` block when this model EXTENDS the map (the usual shape, and the block the whole root project shares), or in `model.likec4`'s own `specification` when the model STANDS ALONE. Declaring it in both is a duplicate, and the code lands where the SECOND declaration's file is: `c4.invalid` when a tags-only block sits in model.likec4, `usecase.flow-invalid` when it sits in a sibling. Two SERVICES each declaring the same tag locally is the fleet-scope class one step out, `c4.fleet-project-invalid`.",
+            "Every hop must be backed by a relationship the model already declares, or it is `usecase.step-unbacked` — LikeC4 itself reports nothing for an unbacked hop, so the diagram renders and every other check stays green. A return step is written `<target> <- <source>`: a reply is attributed to the CALL it answers. A hop whose caller and provider resolve to the SAME service never owes an `operationId`, which is what makes this altitude cheap: `usecase.step-unlinked` is silent inside one service.",
+            "Namespace the view id by the service — `uc_payment_service_authorize`, not `uc_authorize`. An EXTENDING model's views live in the ROOT project beside the map, so view ids are one flat namespace across the whole fleet: two services minting `uc_authorize` makes the renderer refuse the entire project. Ids beginning `subsystem_` or `service_` are loam's own (`subsystem.view-id-collision`).",
+            "Title it `'<subsystem path> / <service id> / <use case>'`. LikeC4 has no view-folder syntax — it splits a view title on `/` into browser folders and shows only the last segment (measured at 1.59.2) — so that convention lands the flow in the same folder as the generated overview of its service in `architecture/services.likec4`. **Nothing checks this**: it is a convention loam states and never grades, exactly like the EARS form in spec.md.",
+            "OPTIONAL, and its absence is graded by nothing, ever. That is docs/DESIGN.md rule 26 and it is enforced. Write one where a requirement's `Covers:` names containers and the sequence is the thing that is hard to hold in the head; write none otherwise. `c4.valid` reports ` · K tagged flow(s) graded` when the project declares any, and that count is the only place a healthy flow appears at all.",
+        ],
+        example: `// One of <svc>'s own use cases: the hops behind ONE requirement of its
+// arch.spec.md, over its OWN containers. Optional — nothing grades the
+// absence of this file, and an untagged view here is never graded either.
+views {
+  // Namespace the id by the service, underscores for hyphens: an extending
+  // model's views share ONE flat id namespace with the whole root project.
+  dynamic view uc_authorize_payment {
+    // The tag comes FIRST. Written after 'title' this is five parse errors.
+    // AUTH-1 is a Requirement-ID in this service's spec.md or arch.spec.md.
+    #req-AUTH-1
+    title '<subsystem path> / <svc> / Authorize a payment'
+    description 'What the service does between the request and the answer'
+
+    // Every hop is backed by a relationship model.likec4 declares. Both of
+    // these are inside one service, so neither owes an operationId.
+    <fqn>.api -> <fqn>.ledger 'Records the authorization'
+    // A reply is attributed to the call it answers, hence the '<-'.
+    <fqn>.api <- <fqn>.ledger 'Confirms the write'
+  }
+}
 `,
     },
     {