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

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

@@ -1 +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"]}
+{"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;;;;;;;;;GASG;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 and in the spec\n * examples' frontmatter and title. It is a placeholder for the same reason\n * `<fqn>` is: the example is handed to an agent that copies it, and a header\n * naming payment-service travelled verbatim into every other service's model —\n * the more convincingly for sitting one line above an `extend` the brief HAD\n * substituted. In spec.md and arch.spec.md the literal was worse than\n * misleading: `service:` must name the directory the file sits in, so a\n * verbatim paste failed `frontmatter.field-mismatch` everywhere but one service.\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

@@ -18,25 +18,9 @@
  * `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 { brokenDocumentPaths } from "../../c4/likec4.js";
 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;
-}
+import { serviceElementId } from "../../c4/seed/template.js";
 /**
  * The write this service still owes `architecture/landscape.likec4`.
  *
@@ -68,7 +52,7 @@ function landscapeBlock(req) {
             "}",
         ].join("\n");
     }
-    const id = elementIdFor(service);
+    const id = serviceElementId(service);
     const calls = expects.length > 0
         ? expects.map((op) => `//   <caller> -> ${id} 'Calls ${op}' { metadata { op '${op}' } }`)
         : [`//   <caller> -> ${id} 'Calls <operationId>' { metadata { op '<operationId>' } }`];
@@ -148,13 +132,11 @@ export function landscapeArtifact(req) {
  * 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.
+ * has to be able to tell that they name the same file: both go through
+ * `c4/likec4.ts`'s `brokenDocumentPaths`.
  */
 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 };
+    return { paths: brokenDocumentPaths(docsDir, land.errors), errors: land.errors.length };
 }
 /**
  * The fleet-map instruction, in the four states a landscape can be in. It says
@@ -165,7 +147,7 @@ export function brokenDocuments(docsDir, land) {
  */
 export function instructionFor(req) {
     const { service, state, expects, servicePath } = req;
-    const id = elementIdFor(service);
+    const id = serviceElementId(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 ` +
@@ -244,7 +226,7 @@ function accountability(req, id) {
 }
 function edgelessInstruction(req) {
     const { servicePath, attested, foreignTags } = req;
-    const id = req.elementId ?? elementIdFor(req.service);
+    const id = req.elementId ?? serviceElementId(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

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

@@ -1 +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"]}
+{"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 { brokenDocumentPaths, type LikeC4Error } from \"../../c4/likec4.js\";\nimport { spellCall, edgeTemplates, type AttestedCall } from \"../../c4/resolve/attested.js\";\nimport { serviceElementId } from \"../../c4/seed/template.js\";\nimport type { BriefTarget } from \"../targets.js\";\n\n/*\n * The identifier a brief suggests for an element the map does not draw yet is\n * `serviceElementId` — `loam seed`'s `svc_<id>`, never a convention of the\n * brief's own. It used to be the directory name camel-cased here, so on a\n * seeded fleet the brief handed an agent `paymentService` beside a map whose\n * every box was `svc_payment_service`. 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, so the spelling has to be the fleet's.\n * The `svc_` prefix also covers what the old helper special-cased by hand: a\n * service id may open with a digit, a LikeC4 identifier may not.\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 = serviceElementId(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: both go through\n * `c4/likec4.ts`'s `brokenDocumentPaths`.\n */\nexport function brokenDocuments(docsDir: string, land: { errors: readonly LikeC4Error[] }): BrokenMap {\n  return { paths: brokenDocumentPaths(docsDir, land.errors), 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 = serviceElementId(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 ?? serviceElementId(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

@@ -93,19 +93,26 @@ views {
             "`Operations: <operationId>[, <operationId>]` in the requirement body names the API operations it governs. Every one must exist in this service's openapi.yaml — a name that does not is `spec-api.op-undefined` (error), reported against the LIVING spec, not only inside a feature delta.",
             "Document what the service DOES today, not what it should do. This is the baseline; changes to it belong in a feature delta.",
         ],
+        // `<svc>` is the model example's placeholder, filled the same way: the
+        // frontmatter `service:` must equal the directory it sits in, so a header
+        // naming payment-service was a paste that failed `frontmatter.field-mismatch`
+        // for every other service. And the blank line under each `### Requirement:`
+        // is the canonical shape `serializeRequirements` writes — a living spec
+        // copied from an example without it is reflowed by its first archive.
         example: `---
-service: payment-service
+service: <svc>
 status: draft
 owner: payments-team
 sources:
   - src/main/java/com/shop/payment/
 ---
 
-# payment-service
+# <svc>
 
 ## Requirements
 
 ### Requirement: Authorize a payment
+
 WHEN authorization is requested for a captured-eligible order THE SYSTEM SHALL
 authorize it against the issuer before any capture.
 
@@ -117,6 +124,7 @@ Operations: authorizePayment
 - **Then** the payment is authorized and an authorization id is returned
 
 ### Requirement: Refunding is permission-gated
+
 IF the caller lacks the refund permission THEN THE SYSTEM SHALL refuse the
 request and leave the payment untouched.
 
@@ -146,19 +154,21 @@ Operations: refundPayment
             "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.",
         ],
+        // Same placeholder and same canonical requirement shape as spec.md's above.
         example: `---
-service: payment-service
+service: <svc>
 status: draft
 owner: payments-team
 sources:
   - src/main/java/com/shop/payment/
 ---
 
-# payment-service — architecture
+# <svc> — architecture
 
 ## Requirements
 
 ### Requirement: Events leave through the transactional outbox
+
 The service SHALL write a domain event and its state change in one transaction,
 published by an outbox relay — never a dual write.
 
@@ -250,7 +260,7 @@ views {
         required: false,
         purpose: "the async contract — the messages this service puts on and takes off the bus",
         shape: [
-            "AsyncAPI **3.0** with `channels`, `operations` and `components.messages`. Only 3.0 is read: its operations are named top-level objects carrying `action: send|receive`, which is what makes a message's direction legible. A 2.x document declares no `operations` and reads as a contract with no messages.",
+            "AsyncAPI **3.0** with `channels`, `operations` and `components.messages`. Only 3.0 is read: its operations are named top-level objects carrying `action: send|receive`, which is what makes a message's direction legible. A 1.x or 2.x document is refused as `asyncapi.invalid` and nothing on the event axis is graded against it; upgrade an existing one with `asyncapi convert --target-version=3.0.0` rather than copying it in as is.",
             "EVERY message carries a `name` (or is declared under the key you intend to reference). That token is the spine: the C4 edge's `metadata { publishes }` / `metadata { consumes }`, the requirement's `Publishes:` / `Consumes:` line and this name are one name spelled three times.",
             "Namespace the name by the domain that owns it — `payment.PaymentAuthorized`. One message has exactly one producer; two services declaring they send one name is `asyncapi.message-contested`, and then which contract a consumer reads is a coin flip.",
             "loam reads message names and the `action` of the operation carrying them. **It never joins on anything inside `payload`** — the one look inside is a presence probe: a payload declaring no shape at all warns (`asyncapi.payload-undescribed`), and a payload with a non-JSON `schemaFormat` is skipped outright. Write the payload as JSON Schema today; if the fleet later adopts Avro, that is a `schemaFormat` line here and nothing in loam changes.",

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

@@ -1 +1 @@
-{"version":3,"file":"targets.js","sourceRoot":"","sources":["../../../src/core/brief/targets.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The artifacts of the adoption brief: what each file under `services/<svc>/`\n * is for, the grammar it has to be written in, and a minimal valid example\n * where showing one is shorter than describing it. Every `shape` rule here is\n * one a later check depends on, and test/agent-contract.test.ts pins the\n * mapping. This module is the list alone — `serviceBrief` (brief.ts) resolves\n * it against a docs repo, and the fleet map's own target, whose block names\n * the service, is assembled per service in map/owed.ts.\n */\n\n/* ------------------------------------------------------------------ */\n/* The artifacts                                                       */\n/* ------------------------------------------------------------------ */\n\nexport interface BriefTarget {\n  /** File name as it appears under `services/<svc>/`. */\n  artifact: string;\n  /** Repo-relative path to write. */\n  path: string;\n  exists: boolean;\n  /**\n   * `create` a missing artifact; `diff` an existing one — never overwrite it.\n   *\n   * `edit` is the third case and belongs to exactly one target: the fleet map.\n   * `architecture/landscape.likec4` is a SHARED document that already holds\n   * every other service, so \"diff it and report what disagrees\" is the wrong\n   * instruction — the file is not this service's baseline, it is the fleet's,\n   * and what this service owes it is an addition inside the existing\n   * `model { … }` block. Spelling that as `diff` taught agents to leave the\n   * fleet map alone; spelling it as `create` would have taught them to\n   * overwrite ten other services.\n   */\n  action: \"create\" | \"diff\" | \"edit\";\n  /**\n   * False for artifacts a baseline can legitimately ship without. True means\n   * required for a COMPLETE baseline — validate grades a missing spec.md or\n   * openapi.yaml as a warn (`service.no-spec` / `service.no-openapi`), not an\n   * error: partial adoption is a supported state, and the warns are the\n   * progress meter.\n   *\n   * Constant per artifact except one: `openapi.yaml` is required only where the\n   * fleet map shows an API is expected (see `apiExpected` in brief.ts), because\n   * the brief is read as an instruction and \"MISSING openapi.yaml\" told an agent\n   * to write a contract for a service that serves no requests.\n   */\n  required: boolean;\n  /** What the artifact is for, in one line. */\n  purpose: string;\n  /** The grammar. Every rule here is one a later check depends on. */\n  shape: string[];\n  /** A minimal valid instance, where showing one is shorter than describing it. */\n  example?: string;\n}\n\n/** Where an artifact lives — `repo/paths.ts` spells the filenames, this only points at them. */\ntype PathKey = \"model\" | \"spec\" | \"archSpec\" | \"openapi\" | \"asyncapi\" | \"adrsDir\" | \"runbook\" | \"health\";\n\n/**\n * The service-local use-case directory, and the one artifact key `ServicePaths`\n * deliberately does NOT carry.\n *\n * `repo/paths.ts` spells the paths loam JOINS ON — the ones a check resolves, a\n * writer writes and the tree walk classifies a directory by. This is not one of\n * them: the slot a service's flows are graded out of is the service's whole\n * LikeC4 project, every `.likec4` under its directory\n * (`core/usecases/service/flows.ts`), and `usecases/<name>.likec4` is the\n * CONVENTION the brief publishes for it. Putting the directory in\n * `ARTIFACT_FILES` would be worse than redundant — `isServiceArtifactName`\n * reads that table, so a `usecases/` directory anywhere under `services/` would\n * mint a service.\n */\nexport const USECASES_DIR = \"usecases\";\n\n/** The artifacts, in the order a baseline is best written in. */\nexport const ARTIFACTS: Array<\n  Omit<BriefTarget, \"path\" | \"exists\" | \"action\"> & { key: PathKey | \"usecasesDir\" }\n> = [\n  {\n    artifact: \"model.likec4\",\n    key: \"model\",\n    required: true,\n    purpose: \"the service's C4 — what it is, what is inside it, what it talks to\",\n    // Every rule below is one a later check depends on, and the mapping is\n    // pinned in test/agent-contract.test.ts. Rules nobody checks — the `views`\n    // block, \"exactly one top-level element\" — used to sit here reading exactly\n    // like the enforced ones, which is how a brief teaches an agent that\n    // `loam validate` passing means more than it does. They now live in\n    // UNCHECKED, where their status is the point.\n    shape: [\n      \"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.\",\n      \"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.\",\n      \"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.\",\n      \"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.\",\n    ],\n    // `<fqn>` and `<svc>` are PLACEHOLDERS this module leaves literal:\n    // `serviceBrief` (brief.ts) substitutes the landscape element's real id and\n    // the service being adopted, and for `<fqn>` the \"the element's id in\n    // architecture/landscape.likec4\" wording where the map holds none. ARTIFACTS\n    // stays a static constant — a target list that varied per repository would\n    // be a second thing to keep true. The header carried the literal\n    // `payment-service` for every service, beside an `extend` line that WAS\n    // substituted, so the half of the example that was personalised taught an\n    // agent the other half had been too.\n    example: `// <svc>'s own C4 — what is INSIDE the element the fleet map binds to\n// this directory. The map declares the kinds and the element; this\n// file extends it and re-declares nothing.\nmodel {\n  extend <fqn> {\n    api = container 'HTTP API'\n    ledger = database 'Ledger store'\n    api -> ledger 'Writes every authorization'\n  }\n  // 'stripe' stands for the OTHER party, spelled as the fleet map already\n  // declares it — loam has no id to substitute here, and inventing one is\n  // the edge that makes the model unresolvable. The containers above are\n  // this example's own: name yours after what they are.\n  <fqn>.api -> stripe 'Authorizes cards'\n}\n\n// Views are LikeC4's, not loam's (docs/DESIGN.md rule 26). Render with\n// 'npx likec4 start' from the docs repo root: this file is part of the root\n// project, beside the map — nothing else to write.\nviews {\n  view of <fqn> {\n    include *\n  }\n}\n`,\n  },\n  {\n    artifact: \"spec.md\",\n    key: \"spec\",\n    required: true,\n    purpose: \"the living requirements — what this service is required to do, as it stands today\",\n    shape: [\n      \"Frontmatter (below), then a `## Requirements` heading.\",\n      \"`### Requirement: <name>` — ONE observable behaviour, written with SHALL, testable without reading the code. Add `Requirement-ID: <id>` in its body for stable identity across heading renames; legacy requirements without one continue to match by exact name.\",\n      \"At least one `#### Scenario: <name>` per requirement, with Given/When/Then bullets. This is gated (`requirements.missing-scenarios`) — scenarios are the acceptance criteria and the source for tests.\",\n      \"A markdown TABLE in a scenario body becomes the `Examples` of a `Scenario Outline`: the header names the placeholders the steps use (`<permission>`), one row per case. This is how a matrix is written — a permission matrix, a validation matrix, a status-code table is ONE scenario with twenty rows, never twenty scenarios. `loam gherkin` emits the outline, cucumber reports one result per row carrying that scenario's digest tag, and `loam verify --results` confirms the claim only when EVERY row passed. Every row must have the header's column count and a header needs at least one row: a table loam cannot read stays in the description, the scenario then runs once instead of once per case, and the emission says so out loud.\",\n      \"A step takes an ARGUMENT by carrying it INDENTED under the bullet, and this is what lets one scenario assert a whole data pass rather than a sentence. An indented table becomes that step's Gherkin DATA TABLE — `- **Then** the outbox holds:` followed by the rows it must hold; a fenced block becomes its DOCSTRING, indentation intact — `- **When** the caller posts:` followed by the JSON body. Indentation is the entire disambiguation: indented under a step means this step's rows, at the margin means the scenario's cases, and both ride into the scenario digest. Write the ASSERTIONS OUT, one bullet each, including the negative ones (`no row is created in ...`, `... is not invoked`) and each meter separately: a scenario that summarises them reads complete, emits valid Gherkin, grades green, and tests a fraction of what it claims.\",\n      \"`Requires: <subject>/<permission>[, ...]` in the requirement body names the authorization it is gated on, resolved against the FLEET vocabulary in `architecture/permissions.yaml`. An entry that is not declared there is `permissions.unknown` (error) — the same grade as `Operations:`, because an invented permission reads exactly like a real one everywhere downstream. Add the permission to that file when this service enforces one nobody has written down yet; the subject is the entity it is checked ON (`user`, `profile`, `service`), which is not always the caller.\",\n      \"`Capability: <id>[, ...]` in the requirement body names the fleet capabilities this requirement realizes part of, declared in `architecture/capabilities.yaml`. A LIST, because the relation is many-to-many: one requirement commonly closes part of two capabilities. The FILE is this axis's opt-in — a fleet without it gets no capability findings — and once it exists an undeclared name is `capability.unknown` (error). Write the line only where the requirement genuinely carries part of the named capability.\",\n      \"Write the requirement body in EARS form — `WHEN <trigger> THE SYSTEM SHALL <response>`, `IF <precondition> THEN THE SYSTEM SHALL <response>`, `WHERE <feature is included> THE SYSTEM SHALL <response>`, or a bare `THE SYSTEM SHALL <response>` when it is unconditional. **Nothing checks this** — it is a writing convention, and it is here because the grammar forces the trigger and the response to be named separately, while free prose lets a requirement read as complete while stating no condition at all. That is the exact shape a guard collapses into when it is summarised rather than enumerated.\",\n      \"`Operations: <operationId>[, <operationId>]` in the requirement body names the API operations it governs. Every one must exist in this service's openapi.yaml — a name that does not is `spec-api.op-undefined` (error), reported against the LIVING spec, not only inside a feature delta.\",\n      \"Document what the service DOES today, not what it should do. This is the baseline; changes to it belong in a feature delta.\",\n    ],\n    example: `---\nservice: payment-service\nstatus: draft\nowner: payments-team\nsources:\n  - src/main/java/com/shop/payment/\n---\n\n# payment-service\n\n## Requirements\n\n### Requirement: Authorize a payment\nWHEN authorization is requested for a captured-eligible order THE SYSTEM SHALL\nauthorize it against the issuer before any capture.\n\nOperations: authorizePayment\n\n#### Scenario: Successful authorization\n- **Given** a valid card and an amount within its limit\n- **When** authorization is requested\n- **Then** the payment is authorized and an authorization id is returned\n\n### Requirement: Refunding is permission-gated\nIF the caller lacks the refund permission THEN THE SYSTEM SHALL refuse the\nrequest and leave the payment untouched.\n\nOperations: refundPayment\n\n#### Scenario: Refund by permission\n- **Given** a captured payment\n- **When** a caller holding <permission> requests a refund\n- **Then** the response is <status> and the payment is <state>\n\n| permission      | status | state    |\n|-----------------|--------|----------|\n| payments:refund | 200    | refunded |\n| payments:read   | 403    | captured |\n| (none)          | 401    | captured |\n`,\n  },\n  {\n    artifact: \"arch.spec.md\",\n    key: \"archSpec\",\n    required: false,\n    purpose:\n      \"the living architecture requirements — the obligations the business spec never carries: outbox, retries, idempotency, metrics, alerts\",\n    shape: [\n      \"Same grammar and frontmatter as spec.md: `## Requirements`, `### Requirement:` + `#### Scenario:` with Given/When/Then. The same checks read it.\",\n      \"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.\",\n      \"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.\",\n      \"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.\",\n      \"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.\",\n    ],\n    example: `---\nservice: payment-service\nstatus: draft\nowner: payments-team\nsources:\n  - src/main/java/com/shop/payment/\n---\n\n# payment-service — architecture\n\n## Requirements\n\n### Requirement: Events leave through the transactional outbox\nThe service SHALL write a domain event and its state change in one transaction,\npublished by an outbox relay — never a dual write.\n\nCovers: paymentService.db, paymentService -> kafka\n\n#### Scenario: Broker down at commit time\n- **Given** an event in the outbox\n- **When** the broker is unavailable\n- **Then** the state stays committed and the event is published once it returns\n`,\n  },\n  {\n    artifact: \"usecases/<name>.likec4\",\n    key: \"usecasesDir\",\n    // Never required, and here the optionality is a RULE rather than a\n    // judgement. docs/DESIGN.md rule 26 — \"presence is never owed. A model with\n    // no views is missing nothing loam wants, and no check may grade its\n    // absence\" — is enforced by scripts/arch-check.mjs, not merely written, so\n    // there is no `service.usecases-missing` and there never will be one.\n    //\n    // The slot is briefed anyway because a team cannot choose a slot nobody\n    // named. The grader landed 2026-09-03 (`core/usecases/service/flows.ts`) and\n    // `c4.valid` has been reporting ` · K tagged flow(s) graded` ever since, on\n    // an axis nothing scaffolded, briefed or named — so the only way to discover\n    // it was to read the source. Publication is the whole of this entry: every\n    // rule below is either a check that already exists or a convention loam\n    // states and never grades, and each says which it is.\n    required: false,\n    purpose:\n      \"optional — one requirement's hop sequence, drawn as a LikeC4 dynamic view over this service's own containers\",\n    shape: [\n      \"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.\",\n      \"`#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.\",\n      \"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`.\",\n      \"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.\",\n      \"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`).\",\n      \"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.\",\n      \"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.\",\n    ],\n    example: `// One of <svc>'s own use cases: the hops behind ONE requirement of its\n// arch.spec.md, over its OWN containers. Optional — nothing grades the\n// absence of this file, and an untagged view here is never graded either.\nviews {\n  // Namespace the id by the service, underscores for hyphens: an extending\n  // model's views share ONE flat id namespace with the whole root project.\n  dynamic view uc_authorize_payment {\n    // The tag comes FIRST. Written after 'title' this is five parse errors.\n    // AUTH-1 is a Requirement-ID in this service's spec.md or arch.spec.md.\n    #req-AUTH-1\n    title '<subsystem path> / <svc> / Authorize a payment'\n    description 'What the service does between the request and the answer'\n\n    // Every hop is backed by a relationship model.likec4 declares. Both of\n    // these are inside one service, so neither owes an operationId.\n    <fqn>.api -> <fqn>.ledger 'Records the authorization'\n    // A reply is attributed to the call it answers, hence the '<-'.\n    <fqn>.api <- <fqn>.ledger 'Confirms the write'\n  }\n}\n`,\n  },\n  {\n    artifact: \"openapi.yaml\",\n    key: \"openapi\",\n    // Overridden per service in `serviceBrief` (brief.ts): an API is required\n    // only where the fleet expects one. See `apiExpected` there.\n    required: true,\n    purpose: \"the API contract — the operations this service exposes\",\n    shape: [\n      \"OpenAPI 3.x with a `paths` map.\",\n      \"EVERY operation carries an `operationId`. That token is the spine: the C4 edge's `metadata { op }`, the requirement's `Operations:` line and this `operationId` are one name spelled three times, and they must be identical.\",\n      \"loam reads operationIds, and probes the rest by PRESENCE only: an operation whose responses declare no schema warns (`openapi.response-undescribed`), an internal `$ref` to nothing warns (`openapi.ref-unresolved`). What a declared schema SAYS is still never checked — the schemas are for humans, codegen and review, so getting them wrong is invisible here and expensive later.\",\n      \"Document the endpoints that exist. An operation the fleet already calls (see `landscape.expects`) must be in here, or the contract breaks the moment this lands.\",\n      // The instruction the brief was missing, and the one that matters most:\n      // it used to mark this artifact required unconditionally, in capitals,\n      // which for a UI, a worker or a cron told the agent to invent an API into\n      // the source of truth. `required` is derived now; this says so in prose\n      // as well, because an agent reading the shape rules must not re-derive\n      // \"MISSING\" as \"write something\".\n      \"If this service exposes no HTTP API, there is no file to write. Do not invent one — an empty or imagined contract is a claim the whole fleet then joins against. `required` above is derived from the fleet map: it is false exactly when the landscape parses and no edge calls an operation on this service, which is the same evidence that keeps `service.no-openapi` quiet.\",\n    ],\n  },\n  {\n    artifact: \"asyncapi.yaml\",\n    key: \"asyncapi\",\n    // Never required. Unlike the HTTP contract, whose necessity the fleet map\n    // can PROVE (an op-linked edge points here), most services in a legacy fleet\n    // touch no topic at all — and a required artifact nobody owes is how a\n    // whole adoption wave learns to ignore the brief.\n    required: false,\n    purpose: \"the async contract — the messages this service puts on and takes off the bus\",\n    shape: [\n      \"AsyncAPI **3.0** with `channels`, `operations` and `components.messages`. Only 3.0 is read: its operations are named top-level objects carrying `action: send|receive`, which is what makes a message's direction legible. A 2.x document declares no `operations` and reads as a contract with no messages.\",\n      \"EVERY message carries a `name` (or is declared under the key you intend to reference). That token is the spine: the C4 edge's `metadata { publishes }` / `metadata { consumes }`, the requirement's `Publishes:` / `Consumes:` line and this name are one name spelled three times.\",\n      \"Namespace the name by the domain that owns it — `payment.PaymentAuthorized`. One message has exactly one producer; two services declaring they send one name is `asyncapi.message-contested`, and then which contract a consumer reads is a coin flip.\",\n      \"loam reads message names and the `action` of the operation carrying them. **It never joins on anything inside `payload`** — the one look inside is a presence probe: a payload declaring no shape at all warns (`asyncapi.payload-undescribed`), and a payload with a non-JSON `schemaFormat` is skipped outright. Write the payload as JSON Schema today; if the fleet later adopts Avro, that is a `schemaFormat` line here and nothing in loam changes.\",\n      \"Keep payloads in `components.schemas` in THIS file rather than `$ref`-ing an external `.avsc`. External references are out of scope for the merge, exactly as on the OpenAPI axis, so a schema in another file will not travel with the message that needs it.\",\n      \"If this service publishes and consumes nothing, there is no file to write. Do not invent one.\",\n    ],\n  },\n  {\n    artifact: \"adrs/\",\n    key: \"adrsDir\",\n    required: false,\n    purpose: \"the decisions behind the shape of the service\",\n    shape: [\n      \"One file per decision: `adrs/NNNN-<slug>.md`, MADR-style (context · decision · consequences).\",\n      \"Only decisions whose consequences are still visible in the code. A reconstructed rationale for something nobody decided is fiction, and it is the kind that survives review because it sounds reasonable.\",\n      \"If a decision is evident but its reasoning is not, write the decision and say the reasoning is unknown. That is a fact; a plausible motive is not.\",\n    ],\n  },\n  {\n    artifact: \"runbook.md\",\n    key: \"runbook\",\n    required: false,\n    purpose: \"how it is run — deploys, dependencies, what to do when it pages\",\n    shape: [\n      \"Frontmatter, then how it is deployed and configured, what it depends on, and what to do about the failures that actually happen.\",\n      \"Written from what is in the repo (pipelines, manifests, alert definitions). Whoever carries the pager verifies it; leave `status: draft` until they have.\",\n      \"A 'configured but not a dependency, and why' list: every capability the configuration wires up that the deploy manifest switches off. Without it, the next reader re-derives the dependency from the config and re-adds what the manifest already removed.\",\n    ],\n  },\n  {\n    artifact: \"health.yaml\",\n    key: \"health\",\n    required: false,\n    purpose: \"SLIs, SLOs, checks and the dependencies that are critical\",\n    shape: [\n      \"SLIs and SLOs as they have been AGREED, plus health checks and critical dependencies.\",\n      \"If no SLO has ever been agreed, say so and leave it out. An invented 99.9% becomes a number other teams plan against.\",\n    ],\n  },\n];\n"]}
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../../../src/core/brief/targets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiDH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEvC,iEAAiE;AACjE,MAAM,CAAC,MAAM,SAAS,GAElB;IACF;QACE,QAAQ,EAAE,cAAc;QACxB,GAAG,EAAE,OAAO;QACZ,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,oEAAoE;QAC7E,uEAAuE;QACvE,2EAA2E;QAC3E,4EAA4E;QAC5E,qEAAqE;QACrE,oEAAoE;QACpE,8CAA8C;QAC9C,KAAK,EAAE;YACL,ibAAib;YACjb,wjBAAwjB;YACxjB,6zBAA6zB;YAC7zB,6aAA6a;SAC9a;QACD,mEAAmE;QACnE,4EAA4E;QAC5E,sEAAsE;QACtE,6EAA6E;QAC7E,2EAA2E;QAC3E,iEAAiE;QACjE,wEAAwE;QACxE,0EAA0E;QAC1E,qCAAqC;QACrC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;CAwBZ;KACE;IACD;QACE,QAAQ,EAAE,SAAS;QACnB,GAAG,EAAE,MAAM;QACX,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,mFAAmF;QAC5F,KAAK,EAAE;YACL,wDAAwD;YACxD,kQAAkQ;YAClQ,wMAAwM;YACxM,wtBAAwtB;YACxtB,o0BAAo0B;YACp0B,wjBAAwjB;YACxjB,4fAA4f;YAC5f,slBAAslB;YACtlB,6RAA6R;YAC7R,6HAA6H;SAC9H;QACD,uEAAuE;QACvE,0EAA0E;QAC1E,8EAA8E;QAC9E,4EAA4E;QAC5E,wEAAwE;QACxE,sEAAsE;QACtE,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCZ;KACE;IACD;QACE,QAAQ,EAAE,cAAc;QACxB,GAAG,EAAE,UAAU;QACf,QAAQ,EAAE,KAAK;QACf,OAAO,EACL,uIAAuI;QACzI,KAAK,EAAE;YACL,kJAAkJ;YAClJ,uRAAuR;YACvR,8sCAA8sC;YAC9sC,kNAAkN;YAClN,+MAA+M;SAChN;QACD,4EAA4E;QAC5E,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;CAuBZ;KACE;IACD;QACE,QAAQ,EAAE,wBAAwB;QAClC,GAAG,EAAE,aAAa;QAClB,mEAAmE;QACnE,4EAA4E;QAC5E,qEAAqE;QACrE,2EAA2E;QAC3E,sEAAsE;QACtE,EAAE;QACF,wEAAwE;QACxE,6EAA6E;QAC7E,4EAA4E;QAC5E,6EAA6E;QAC7E,2EAA2E;QAC3E,wEAAwE;QACxE,sDAAsD;QACtD,QAAQ,EAAE,KAAK;QACf,OAAO,EACL,8GAA8G;QAChH,KAAK,EAAE;YACL,oiBAAoiB;YACpiB,6iBAA6iB;YAC7iB,mkBAAmkB;YACnkB,+eAA+e;YAC/e,sYAAsY;YACtY,2bAA2b;YAC3b,0YAA0Y;SAC3Y;QACD,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;CAoBZ;KACE;IACD;QACE,QAAQ,EAAE,cAAc;QACxB,GAAG,EAAE,SAAS;QACd,0EAA0E;QAC1E,6DAA6D;QAC7D,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,wDAAwD;QACjE,KAAK,EAAE;YACL,iCAAiC;YACjC,+NAA+N;YAC/N,yXAAyX;YACzX,kKAAkK;YAClK,wEAAwE;YACxE,uEAAuE;YACvE,0EAA0E;YAC1E,wEAAwE;YACxE,uEAAuE;YACvE,kCAAkC;YAClC,kXAAkX;SACnX;KACF;IACD;QACE,QAAQ,EAAE,eAAe;QACzB,GAAG,EAAE,UAAU;QACf,0EAA0E;QAC1E,6EAA6E;QAC7E,uEAAuE;QACvE,kDAAkD;QAClD,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,8EAA8E;QACvF,KAAK,EAAE;YACL,+aAA+a;YAC/a,qRAAqR;YACrR,wPAAwP;YACxP,4bAA4b;YAC5b,gQAAgQ;YAChQ,+FAA+F;SAChG;KACF;IACD;QACE,QAAQ,EAAE,OAAO;QACjB,GAAG,EAAE,SAAS;QACd,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,+CAA+C;QACxD,KAAK,EAAE;YACL,+FAA+F;YAC/F,2MAA2M;YAC3M,oJAAoJ;SACrJ;KACF;IACD;QACE,QAAQ,EAAE,YAAY;QACtB,GAAG,EAAE,SAAS;QACd,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,iEAAiE;QAC1E,KAAK,EAAE;YACL,kIAAkI;YAClI,2JAA2J;YAC3J,4PAA4P;SAC7P;KACF;IACD;QACE,QAAQ,EAAE,aAAa;QACvB,GAAG,EAAE,QAAQ;QACb,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,2DAA2D;QACpE,KAAK,EAAE;YACL,uFAAuF;YACvF,uHAAuH;SACxH;KACF;CACF,CAAC","sourcesContent":["/**\n * The artifacts of the adoption brief: what each file under `services/<svc>/`\n * is for, the grammar it has to be written in, and a minimal valid example\n * where showing one is shorter than describing it. Every `shape` rule here is\n * one a later check depends on, and test/agent-contract.test.ts pins the\n * mapping. This module is the list alone — `serviceBrief` (brief.ts) resolves\n * it against a docs repo, and the fleet map's own target, whose block names\n * the service, is assembled per service in map/owed.ts.\n */\n\n/* ------------------------------------------------------------------ */\n/* The artifacts                                                       */\n/* ------------------------------------------------------------------ */\n\nexport interface BriefTarget {\n  /** File name as it appears under `services/<svc>/`. */\n  artifact: string;\n  /** Repo-relative path to write. */\n  path: string;\n  exists: boolean;\n  /**\n   * `create` a missing artifact; `diff` an existing one — never overwrite it.\n   *\n   * `edit` is the third case and belongs to exactly one target: the fleet map.\n   * `architecture/landscape.likec4` is a SHARED document that already holds\n   * every other service, so \"diff it and report what disagrees\" is the wrong\n   * instruction — the file is not this service's baseline, it is the fleet's,\n   * and what this service owes it is an addition inside the existing\n   * `model { … }` block. Spelling that as `diff` taught agents to leave the\n   * fleet map alone; spelling it as `create` would have taught them to\n   * overwrite ten other services.\n   */\n  action: \"create\" | \"diff\" | \"edit\";\n  /**\n   * False for artifacts a baseline can legitimately ship without. True means\n   * required for a COMPLETE baseline — validate grades a missing spec.md or\n   * openapi.yaml as a warn (`service.no-spec` / `service.no-openapi`), not an\n   * error: partial adoption is a supported state, and the warns are the\n   * progress meter.\n   *\n   * Constant per artifact except one: `openapi.yaml` is required only where the\n   * fleet map shows an API is expected (see `apiExpected` in brief.ts), because\n   * the brief is read as an instruction and \"MISSING openapi.yaml\" told an agent\n   * to write a contract for a service that serves no requests.\n   */\n  required: boolean;\n  /** What the artifact is for, in one line. */\n  purpose: string;\n  /** The grammar. Every rule here is one a later check depends on. */\n  shape: string[];\n  /** A minimal valid instance, where showing one is shorter than describing it. */\n  example?: string;\n}\n\n/** Where an artifact lives — `repo/paths.ts` spells the filenames, this only points at them. */\ntype PathKey = \"model\" | \"spec\" | \"archSpec\" | \"openapi\" | \"asyncapi\" | \"adrsDir\" | \"runbook\" | \"health\";\n\n/**\n * The service-local use-case directory, and the one artifact key `ServicePaths`\n * deliberately does NOT carry.\n *\n * `repo/paths.ts` spells the paths loam JOINS ON — the ones a check resolves, a\n * writer writes and the tree walk classifies a directory by. This is not one of\n * them: the slot a service's flows are graded out of is the service's whole\n * LikeC4 project, every `.likec4` under its directory\n * (`core/usecases/service/flows.ts`), and `usecases/<name>.likec4` is the\n * CONVENTION the brief publishes for it. Putting the directory in\n * `ARTIFACT_FILES` would be worse than redundant — `isServiceArtifactName`\n * reads that table, so a `usecases/` directory anywhere under `services/` would\n * mint a service.\n */\nexport const USECASES_DIR = \"usecases\";\n\n/** The artifacts, in the order a baseline is best written in. */\nexport const ARTIFACTS: Array<\n  Omit<BriefTarget, \"path\" | \"exists\" | \"action\"> & { key: PathKey | \"usecasesDir\" }\n> = [\n  {\n    artifact: \"model.likec4\",\n    key: \"model\",\n    required: true,\n    purpose: \"the service's C4 — what it is, what is inside it, what it talks to\",\n    // Every rule below is one a later check depends on, and the mapping is\n    // pinned in test/agent-contract.test.ts. Rules nobody checks — the `views`\n    // block, \"exactly one top-level element\" — used to sit here reading exactly\n    // like the enforced ones, which is how a brief teaches an agent that\n    // `loam validate` passing means more than it does. They now live in\n    // UNCHECKED, where their status is the point.\n    shape: [\n      \"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.\",\n      \"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.\",\n      \"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.\",\n      \"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.\",\n    ],\n    // `<fqn>` and `<svc>` are PLACEHOLDERS this module leaves literal:\n    // `serviceBrief` (brief.ts) substitutes the landscape element's real id and\n    // the service being adopted, and for `<fqn>` the \"the element's id in\n    // architecture/landscape.likec4\" wording where the map holds none. ARTIFACTS\n    // stays a static constant — a target list that varied per repository would\n    // be a second thing to keep true. The header carried the literal\n    // `payment-service` for every service, beside an `extend` line that WAS\n    // substituted, so the half of the example that was personalised taught an\n    // agent the other half had been too.\n    example: `// <svc>'s own C4 — what is INSIDE the element the fleet map binds to\n// this directory. The map declares the kinds and the element; this\n// file extends it and re-declares nothing.\nmodel {\n  extend <fqn> {\n    api = container 'HTTP API'\n    ledger = database 'Ledger store'\n    api -> ledger 'Writes every authorization'\n  }\n  // 'stripe' stands for the OTHER party, spelled as the fleet map already\n  // declares it — loam has no id to substitute here, and inventing one is\n  // the edge that makes the model unresolvable. The containers above are\n  // this example's own: name yours after what they are.\n  <fqn>.api -> stripe 'Authorizes cards'\n}\n\n// Views are LikeC4's, not loam's (docs/DESIGN.md rule 26). Render with\n// 'npx likec4 start' from the docs repo root: this file is part of the root\n// project, beside the map — nothing else to write.\nviews {\n  view of <fqn> {\n    include *\n  }\n}\n`,\n  },\n  {\n    artifact: \"spec.md\",\n    key: \"spec\",\n    required: true,\n    purpose: \"the living requirements — what this service is required to do, as it stands today\",\n    shape: [\n      \"Frontmatter (below), then a `## Requirements` heading.\",\n      \"`### Requirement: <name>` — ONE observable behaviour, written with SHALL, testable without reading the code. Add `Requirement-ID: <id>` in its body for stable identity across heading renames; legacy requirements without one continue to match by exact name.\",\n      \"At least one `#### Scenario: <name>` per requirement, with Given/When/Then bullets. This is gated (`requirements.missing-scenarios`) — scenarios are the acceptance criteria and the source for tests.\",\n      \"A markdown TABLE in a scenario body becomes the `Examples` of a `Scenario Outline`: the header names the placeholders the steps use (`<permission>`), one row per case. This is how a matrix is written — a permission matrix, a validation matrix, a status-code table is ONE scenario with twenty rows, never twenty scenarios. `loam gherkin` emits the outline, cucumber reports one result per row carrying that scenario's digest tag, and `loam verify --results` confirms the claim only when EVERY row passed. Every row must have the header's column count and a header needs at least one row: a table loam cannot read stays in the description, the scenario then runs once instead of once per case, and the emission says so out loud.\",\n      \"A step takes an ARGUMENT by carrying it INDENTED under the bullet, and this is what lets one scenario assert a whole data pass rather than a sentence. An indented table becomes that step's Gherkin DATA TABLE — `- **Then** the outbox holds:` followed by the rows it must hold; a fenced block becomes its DOCSTRING, indentation intact — `- **When** the caller posts:` followed by the JSON body. Indentation is the entire disambiguation: indented under a step means this step's rows, at the margin means the scenario's cases, and both ride into the scenario digest. Write the ASSERTIONS OUT, one bullet each, including the negative ones (`no row is created in ...`, `... is not invoked`) and each meter separately: a scenario that summarises them reads complete, emits valid Gherkin, grades green, and tests a fraction of what it claims.\",\n      \"`Requires: <subject>/<permission>[, ...]` in the requirement body names the authorization it is gated on, resolved against the FLEET vocabulary in `architecture/permissions.yaml`. An entry that is not declared there is `permissions.unknown` (error) — the same grade as `Operations:`, because an invented permission reads exactly like a real one everywhere downstream. Add the permission to that file when this service enforces one nobody has written down yet; the subject is the entity it is checked ON (`user`, `profile`, `service`), which is not always the caller.\",\n      \"`Capability: <id>[, ...]` in the requirement body names the fleet capabilities this requirement realizes part of, declared in `architecture/capabilities.yaml`. A LIST, because the relation is many-to-many: one requirement commonly closes part of two capabilities. The FILE is this axis's opt-in — a fleet without it gets no capability findings — and once it exists an undeclared name is `capability.unknown` (error). Write the line only where the requirement genuinely carries part of the named capability.\",\n      \"Write the requirement body in EARS form — `WHEN <trigger> THE SYSTEM SHALL <response>`, `IF <precondition> THEN THE SYSTEM SHALL <response>`, `WHERE <feature is included> THE SYSTEM SHALL <response>`, or a bare `THE SYSTEM SHALL <response>` when it is unconditional. **Nothing checks this** — it is a writing convention, and it is here because the grammar forces the trigger and the response to be named separately, while free prose lets a requirement read as complete while stating no condition at all. That is the exact shape a guard collapses into when it is summarised rather than enumerated.\",\n      \"`Operations: <operationId>[, <operationId>]` in the requirement body names the API operations it governs. Every one must exist in this service's openapi.yaml — a name that does not is `spec-api.op-undefined` (error), reported against the LIVING spec, not only inside a feature delta.\",\n      \"Document what the service DOES today, not what it should do. This is the baseline; changes to it belong in a feature delta.\",\n    ],\n    // `<svc>` is the model example's placeholder, filled the same way: the\n    // frontmatter `service:` must equal the directory it sits in, so a header\n    // naming payment-service was a paste that failed `frontmatter.field-mismatch`\n    // for every other service. And the blank line under each `### Requirement:`\n    // is the canonical shape `serializeRequirements` writes — a living spec\n    // copied from an example without it is reflowed by its first archive.\n    example: `---\nservice: <svc>\nstatus: draft\nowner: payments-team\nsources:\n  - src/main/java/com/shop/payment/\n---\n\n# <svc>\n\n## Requirements\n\n### Requirement: Authorize a payment\n\nWHEN authorization is requested for a captured-eligible order THE SYSTEM SHALL\nauthorize it against the issuer before any capture.\n\nOperations: authorizePayment\n\n#### Scenario: Successful authorization\n- **Given** a valid card and an amount within its limit\n- **When** authorization is requested\n- **Then** the payment is authorized and an authorization id is returned\n\n### Requirement: Refunding is permission-gated\n\nIF the caller lacks the refund permission THEN THE SYSTEM SHALL refuse the\nrequest and leave the payment untouched.\n\nOperations: refundPayment\n\n#### Scenario: Refund by permission\n- **Given** a captured payment\n- **When** a caller holding <permission> requests a refund\n- **Then** the response is <status> and the payment is <state>\n\n| permission      | status | state    |\n|-----------------|--------|----------|\n| payments:refund | 200    | refunded |\n| payments:read   | 403    | captured |\n| (none)          | 401    | captured |\n`,\n  },\n  {\n    artifact: \"arch.spec.md\",\n    key: \"archSpec\",\n    required: false,\n    purpose:\n      \"the living architecture requirements — the obligations the business spec never carries: outbox, retries, idempotency, metrics, alerts\",\n    shape: [\n      \"Same grammar and frontmatter as spec.md: `## Requirements`, `### Requirement:` + `#### Scenario:` with Given/When/Then. The same checks read it.\",\n      \"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.\",\n      \"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.\",\n      \"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.\",\n      \"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.\",\n    ],\n    // Same placeholder and same canonical requirement shape as spec.md's above.\n    example: `---\nservice: <svc>\nstatus: draft\nowner: payments-team\nsources:\n  - src/main/java/com/shop/payment/\n---\n\n# <svc> — architecture\n\n## Requirements\n\n### Requirement: Events leave through the transactional outbox\n\nThe service SHALL write a domain event and its state change in one transaction,\npublished by an outbox relay — never a dual write.\n\nCovers: paymentService.db, paymentService -> kafka\n\n#### Scenario: Broker down at commit time\n- **Given** an event in the outbox\n- **When** the broker is unavailable\n- **Then** the state stays committed and the event is published once it returns\n`,\n  },\n  {\n    artifact: \"usecases/<name>.likec4\",\n    key: \"usecasesDir\",\n    // Never required, and here the optionality is a RULE rather than a\n    // judgement. docs/DESIGN.md rule 26 — \"presence is never owed. A model with\n    // no views is missing nothing loam wants, and no check may grade its\n    // absence\" — is enforced by scripts/arch-check.mjs, not merely written, so\n    // there is no `service.usecases-missing` and there never will be one.\n    //\n    // The slot is briefed anyway because a team cannot choose a slot nobody\n    // named. The grader landed 2026-09-03 (`core/usecases/service/flows.ts`) and\n    // `c4.valid` has been reporting ` · K tagged flow(s) graded` ever since, on\n    // an axis nothing scaffolded, briefed or named — so the only way to discover\n    // it was to read the source. Publication is the whole of this entry: every\n    // rule below is either a check that already exists or a convention loam\n    // states and never grades, and each says which it is.\n    required: false,\n    purpose:\n      \"optional — one requirement's hop sequence, drawn as a LikeC4 dynamic view over this service's own containers\",\n    shape: [\n      \"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.\",\n      \"`#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.\",\n      \"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`.\",\n      \"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.\",\n      \"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`).\",\n      \"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.\",\n      \"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.\",\n    ],\n    example: `// One of <svc>'s own use cases: the hops behind ONE requirement of its\n// arch.spec.md, over its OWN containers. Optional — nothing grades the\n// absence of this file, and an untagged view here is never graded either.\nviews {\n  // Namespace the id by the service, underscores for hyphens: an extending\n  // model's views share ONE flat id namespace with the whole root project.\n  dynamic view uc_authorize_payment {\n    // The tag comes FIRST. Written after 'title' this is five parse errors.\n    // AUTH-1 is a Requirement-ID in this service's spec.md or arch.spec.md.\n    #req-AUTH-1\n    title '<subsystem path> / <svc> / Authorize a payment'\n    description 'What the service does between the request and the answer'\n\n    // Every hop is backed by a relationship model.likec4 declares. Both of\n    // these are inside one service, so neither owes an operationId.\n    <fqn>.api -> <fqn>.ledger 'Records the authorization'\n    // A reply is attributed to the call it answers, hence the '<-'.\n    <fqn>.api <- <fqn>.ledger 'Confirms the write'\n  }\n}\n`,\n  },\n  {\n    artifact: \"openapi.yaml\",\n    key: \"openapi\",\n    // Overridden per service in `serviceBrief` (brief.ts): an API is required\n    // only where the fleet expects one. See `apiExpected` there.\n    required: true,\n    purpose: \"the API contract — the operations this service exposes\",\n    shape: [\n      \"OpenAPI 3.x with a `paths` map.\",\n      \"EVERY operation carries an `operationId`. That token is the spine: the C4 edge's `metadata { op }`, the requirement's `Operations:` line and this `operationId` are one name spelled three times, and they must be identical.\",\n      \"loam reads operationIds, and probes the rest by PRESENCE only: an operation whose responses declare no schema warns (`openapi.response-undescribed`), an internal `$ref` to nothing warns (`openapi.ref-unresolved`). What a declared schema SAYS is still never checked — the schemas are for humans, codegen and review, so getting them wrong is invisible here and expensive later.\",\n      \"Document the endpoints that exist. An operation the fleet already calls (see `landscape.expects`) must be in here, or the contract breaks the moment this lands.\",\n      // The instruction the brief was missing, and the one that matters most:\n      // it used to mark this artifact required unconditionally, in capitals,\n      // which for a UI, a worker or a cron told the agent to invent an API into\n      // the source of truth. `required` is derived now; this says so in prose\n      // as well, because an agent reading the shape rules must not re-derive\n      // \"MISSING\" as \"write something\".\n      \"If this service exposes no HTTP API, there is no file to write. Do not invent one — an empty or imagined contract is a claim the whole fleet then joins against. `required` above is derived from the fleet map: it is false exactly when the landscape parses and no edge calls an operation on this service, which is the same evidence that keeps `service.no-openapi` quiet.\",\n    ],\n  },\n  {\n    artifact: \"asyncapi.yaml\",\n    key: \"asyncapi\",\n    // Never required. Unlike the HTTP contract, whose necessity the fleet map\n    // can PROVE (an op-linked edge points here), most services in a legacy fleet\n    // touch no topic at all — and a required artifact nobody owes is how a\n    // whole adoption wave learns to ignore the brief.\n    required: false,\n    purpose: \"the async contract — the messages this service puts on and takes off the bus\",\n    shape: [\n      \"AsyncAPI **3.0** with `channels`, `operations` and `components.messages`. Only 3.0 is read: its operations are named top-level objects carrying `action: send|receive`, which is what makes a message's direction legible. A 1.x or 2.x document is refused as `asyncapi.invalid` and nothing on the event axis is graded against it; upgrade an existing one with `asyncapi convert --target-version=3.0.0` rather than copying it in as is.\",\n      \"EVERY message carries a `name` (or is declared under the key you intend to reference). That token is the spine: the C4 edge's `metadata { publishes }` / `metadata { consumes }`, the requirement's `Publishes:` / `Consumes:` line and this name are one name spelled three times.\",\n      \"Namespace the name by the domain that owns it — `payment.PaymentAuthorized`. One message has exactly one producer; two services declaring they send one name is `asyncapi.message-contested`, and then which contract a consumer reads is a coin flip.\",\n      \"loam reads message names and the `action` of the operation carrying them. **It never joins on anything inside `payload`** — the one look inside is a presence probe: a payload declaring no shape at all warns (`asyncapi.payload-undescribed`), and a payload with a non-JSON `schemaFormat` is skipped outright. Write the payload as JSON Schema today; if the fleet later adopts Avro, that is a `schemaFormat` line here and nothing in loam changes.\",\n      \"Keep payloads in `components.schemas` in THIS file rather than `$ref`-ing an external `.avsc`. External references are out of scope for the merge, exactly as on the OpenAPI axis, so a schema in another file will not travel with the message that needs it.\",\n      \"If this service publishes and consumes nothing, there is no file to write. Do not invent one.\",\n    ],\n  },\n  {\n    artifact: \"adrs/\",\n    key: \"adrsDir\",\n    required: false,\n    purpose: \"the decisions behind the shape of the service\",\n    shape: [\n      \"One file per decision: `adrs/NNNN-<slug>.md`, MADR-style (context · decision · consequences).\",\n      \"Only decisions whose consequences are still visible in the code. A reconstructed rationale for something nobody decided is fiction, and it is the kind that survives review because it sounds reasonable.\",\n      \"If a decision is evident but its reasoning is not, write the decision and say the reasoning is unknown. That is a fact; a plausible motive is not.\",\n    ],\n  },\n  {\n    artifact: \"runbook.md\",\n    key: \"runbook\",\n    required: false,\n    purpose: \"how it is run — deploys, dependencies, what to do when it pages\",\n    shape: [\n      \"Frontmatter, then how it is deployed and configured, what it depends on, and what to do about the failures that actually happen.\",\n      \"Written from what is in the repo (pipelines, manifests, alert definitions). Whoever carries the pager verifies it; leave `status: draft` until they have.\",\n      \"A 'configured but not a dependency, and why' list: every capability the configuration wires up that the deploy manifest switches off. Without it, the next reader re-derives the dependency from the config and re-adds what the manifest already removed.\",\n    ],\n  },\n  {\n    artifact: \"health.yaml\",\n    key: \"health\",\n    required: false,\n    purpose: \"SLIs, SLOs, checks and the dependencies that are critical\",\n    shape: [\n      \"SLIs and SLOs as they have been AGREED, plus health checks and critical dependencies.\",\n      \"If no SLO has ever been agreed, say so and leave it out. An invented 99.9% becomes a number other teams plan against.\",\n    ],\n  },\n];\n"]}