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

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

@@ -1 +1 @@
-{"version":3,"file":"landscape.js","sourceRoot":"","sources":["../../../src/core/brief/landscape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet-map half of the adoption brief, READ side: what the fleet map\n * already says about one service — its elements, its inbound and outbound\n * edges, the operations the fleet already calls on it — and which of the four\n * states the map is in for it. The write the service still owes the file — the\n * block, when nothing in it resolves to the service yet, or the EDGES, when an\n * element does and no edge touches it — is spelled in `./map/owed.ts`\n * (`landscapeArtifact`, `instructionFor`), which this module hands its findings\n * to. Both halves exist to stop an agent inventing a parallel model: the fleet\n * has already drawn some of these boxes and edges, and a baseline has to attach.\n *\n * \"The fleet map\" is the `architecture/` PROJECT — the landscape plus every\n * other `.likec4` under it, minus the generated views file — and not the\n * landscape FILE. The two are the same document set `validate --all` grades\n * `landscape.service-isolated` over, and reading one file here let the two\n * surfaces disagree about the same tree.\n */\nimport { existsSync } from \"node:fs\";\nimport { loadFile } from \"../c4/likec4.js\";\nimport { loadArchitecture } from \"../c4/project/architecture.js\";\nimport { attestedCalls, type AttestedCall } from \"../c4/resolve/attested.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { ServiceModels } from \"../c4/prefetch/fleet.js\";\nimport { OBLIGATION_TAG_PREFIX } from \"../obligations/obligations.js\";\nimport { landscapePath, type ServicePaths } from \"../repo/paths.js\";\nimport { enumeratedServiceIds, serviceTreePathOf } from \"../repo/service-target.js\";\nimport { EXTERNAL_TAG, GRADED_TAGS } from \"../vocabulary/maturity.js\";\nimport { brokenDocuments, instructionFor } from \"./map/owed.js\";\nimport { properAncestorIds } from \"../kernel/ids/fqn/ancestors.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/* ------------------------------------------------------------------ */\n/* What the fleet already says about this service                      */\n/* ------------------------------------------------------------------ */\n\nexport interface LandscapeElement {\n  id: string;\n  title: string;\n  kind: string;\n  tags: string[];\n  /** True when the element binds explicitly with `metadata { service }`. */\n  bound: boolean;\n}\n\nexport interface LandscapeEdge {\n  from?: string;\n  to?: string;\n  op: string | null;\n  title: string | null;\n}\n\nexport interface LandscapeContext {\n  /** Whether `architecture/landscape.likec4` — the file the brief asks for edits to — is on disk. */\n  present: boolean;\n  /**\n   * False when the landscape exists but the `architecture/` project does not\n   * parse. A sibling under `architecture/` counts: a broken use case leaves the\n   * map unusable for `validate --all` too, and a brief that read the landscape\n   * alone would report a fleet nobody can render.\n   */\n  parses: boolean;\n  /**\n   * Whether loam could read WHO CALLS this service — the only evidence an EMPTY\n   * `expects` may be read as \"nothing calls it\".\n   *\n   * A separate fact from `parses` because they answer about different documents.\n   * `parses` is about the whole `architecture/` PROJECT (W4), and the callers\n   * live in the landscape FILE: a broken palette or use case beside a landscape\n   * that reads perfectly left `parses` false, and `apiExpected` then demanded an\n   * OpenAPI contract of a browser UI the map proves nobody calls — while `loam\n   * list` and `loam context`, which read the file (core/pack/living.ts), said the\n   * opposite about the same tree.\n   */\n  callersKnown: boolean;\n  /** Whether any element resolves to this service — null when nothing could be read. */\n  modelled: boolean | null;\n  /**\n   * The service-LEVEL elements that resolve to this service: an element whose\n   * ancestor also resolves to it is one of its containers, not a second box.\n   */\n  elements: LandscapeElement[];\n  /**\n   * The map's edges into and out of this service, INTERNAL edges excluded: an\n   * edge whose two endpoints both resolve here (`svc.web -> svc.db`) is this\n   * service's own wiring, and filed as inbound it named the service as its own\n   * caller.\n   */\n  inbound: LandscapeEdge[];\n  outbound: LandscapeEdge[];\n  /** Operations other services already call on this one: the contract owes them. */\n  expects: string[];\n  /**\n   * Whether at least one relationship in the map has an endpoint resolving to\n   * this service — read off the relationships, NOT off `inbound`/`outbound`,\n   * because an intra-service edge counts here (it is `landscape.service-\n   * isolated`'s predicate) while those two lists drop it. `null` exactly when\n   * `modelled` is `null` or `false`. It exists\n   * because `instruction` used to go null on element existence alone, and\n   * `loam seed` writes a bound, edgeless element for every service nobody\n   * listed under `calls:` — so the brief declared the map finished for exactly\n   * the services the map had not reached.\n   *\n   * Binary by design, and the fifth silent case of `landscape.service-isolated`\n   * with it: ONE edge closes the state, so a map drawing one of five attested\n   * calls reports `touched: true`, `attested: []` and no instruction. The check\n   * is touched/untouched, not a set difference — loam cannot tell a call the map\n   * omits from a call it deliberately does not draw at fleet level, and a\n   * difference reported as an omission would be an invented edge with a code\n   * beside it.\n   */\n  touched: boolean | null;\n  /**\n   * The calls `services/<…>/<svc>/model.likec4` declares ACROSS its boundary\n   * (`attestedCalls`, core/c4/resolve/attested.ts). `[]` when the model is\n   * absent, unparseable, or declares none — deliberately not told apart, since\n   * the only thing the brief may do with the list is name edges ALREADY\n   * ATTESTED, never invent one. Read only when `touched` is `false`: every\n   * other state either has edges (nothing owed) or no element (the block, not\n   * the edges, is owed), and a first adoption has no model to read anyway.\n   */\n  attested: AttestedCall[];\n  /**\n   * The write this service still owes the fleet map, in prose — null once an\n   * element resolves to it AND an edge touches that element. It duplicates the\n   * `landscape.likec4` target's shape rules on purpose: an agent driving off\n   * `--json` reads `landscape` to learn what the fleet already says, and every\n   * `targets[]` consumer walks the artifact list. Only one of those two readers\n   * used to exist, so `adopt` briefed eight files and never once said the ninth\n   * thing — that a documented service nobody drew is invisible to the whole\n   * cross-service layer.\n   */\n  instruction: string | null;\n}\n\n/**\n * The service ids the resolver may fall back on when an element carries no\n * `metadata { service }` binding — the same positive evidence `validate` and\n * `list` hand it. A docs repo with no `services/` yet (`adopt` runs there)\n * leaves the resolver with bindings alone, which is what it had before.\n */\nasync function knownServices(docsDir: DocsDir): Promise<ReadonlySet<string>> {\n  return new Set(await enumeratedServiceIds(docsDir));\n}\n\n/**\n * The tags loam reads on an ELEMENT. `GRADED_TAGS` is the vocabulary's own\n * list of the tags that change what loam concludes — spelled once there, so\n * the day a third tag is graded this set follows and the instruction below\n * does not tell an agent to clear it as unread. The obligation prefix is the\n * one tag PREFIX loam reads on an element; `#cap-`/`#req-` are view tags and\n * never sit on one, so they are not in this list.\n */\nconst LOAM_TAGS: ReadonlySet<string> = new Set(GRADED_TAGS);\nconst LOAM_TAG_PREFIXES: readonly string[] = [OBLIGATION_TAG_PREFIX];\n\n/**\n * The element's tags loam does NOT read — named in the instruction and never\n * interpreted. A placeholder convention (\"drawn ahead of adoption\") is the\n * fleet's own, `loam seed` writes none, and a view written `exclude\n * element.tag = #<that>` keeps an adopted service hidden until it is cleared.\n */\nfunction foreignTagsOf(elements: LandscapeElement[]): string[] {\n  const unread = (t: string): boolean => !LOAM_TAGS.has(t) && !LOAM_TAG_PREFIXES.some((p) => t.startsWith(p));\n  return [...new Set(elements.flatMap((e) => e.tags))].filter(unread);\n}\n\n/**\n * The attested calls, or nothing off a model that could not be read: `c4.invalid`\n * is validate's finding, and an edge list read off half a document is invention.\n *\n * Through the ONE reader of `model.likec4` (`core/c4/service-model/load.ts`),\n * because the two shapes are read differently and this brief is handed to an\n * agent that will act on it: a model that EXTENDS the fleet map, opened as a\n * lone file, comes back as a pile of parse errors — so the brief would tell\n * every migrated service that its model attests nothing and quietly drop the\n * edges the map most likely owes. `mapUnreadable` is the same empty answer for\n * the same reason: an extending model whose map does not parse was never read.\n */\nasync function attestedFrom(\n  docsDir: DocsDir,\n  paths: ServicePaths,\n  service: string,\n  known: ReadonlySet<string>,\n): Promise<AttestedCall[]> {\n  // The memo directly rather than through `core/fleet-context.ts`, and the\n  // reason is the package graph: this module already depends on `core/c4/`, and\n  // reaching for the read index would add a `brief -> core-root` edge for one\n  // read in a command that grades a single service. The three things the memo\n  // cannot know for itself are supplied here — the enumeration this function\n  // was already handed, the per-file loader, and a counter nobody is keeping.\n  const models = new ServiceModels({\n    onProjectLoad: () => {\n      // `adopt` reports no read counters, so there is nothing to increment. The\n      // hook is the memo's way of letting a caller own its own statistics, and\n      // an empty one is that answer, not a forgotten line.\n    },\n    known: async () => known,\n    standalone: (path) => loadFile(path),\n  });\n  const model = await models.model(docsDir, paths);\n  if (model.mapUnreadable || model.doc.errors.length > 0) return [];\n  return attestedCalls(model.doc, service, known);\n}\n\n/**\n * What the living fleet map already says about this service — the half of the\n * brief that stops an agent inventing a parallel model: the fleet has already\n * drawn some of these boxes and edges, and the baseline has to attach to them.\n * An `architecture/` project that does not parse yields `modelled: null` —\n * \"nothing models it\" would be a claim about documents nobody could read; the\n * landscape FILE parsing on its own does not rescue it, because the map the\n * renderer and `validate --all` see is the whole project. `paths` is the\n * service's own artifact set, located by the caller through the enumeration\n * (never joined at `services/<id>/`): the model is opened in exactly one state —\n * an element with no edge — to name the calls the map most likely owes. The\n * WHOLE record travels rather than the model path alone, because the model is\n * now read through its own shape and an extending one is read as a project of\n * the service's directory plus the map. It is required rather than optional\n * because the edgeless instruction states what that file attests, and a caller\n * that omitted it would get a brief asserting a fact about a document loam never\n * opened.\n */\nexport async function landscapeContext(\n  docsDir: DocsDir,\n  service: string,\n  paths: ServicePaths,\n): Promise<LandscapeContext> {\n  const path = landscapePath(docsDir);\n  // The service's own directory, spelled from the enumeration rather than joined\n  // at the root: this text is handed to an AGENT that will go and edit files, and\n  // a filed service named at `services/<id>/` sends it to create a second\n  // directory beside the one that already exists.\n  const servicePath = await serviceTreePathOf(docsDir, service);\n  const bare = { service, expects: [], servicePath, attested: [], foreignTags: [] };\n  const empty: LandscapeContext = {\n    present: existsSync(path),\n    parses: false,\n    callersKnown: false,\n    modelled: null,\n    elements: [],\n    inbound: [],\n    outbound: [],\n    expects: [],\n    touched: null,\n    attested: [],\n    instruction: null,\n  };\n  if (!empty.present) return { ...empty, modelled: false, instruction: instructionFor({ ...bare, state: \"absent\" }) };\n\n  // The `architecture/` PROJECT, through the one loader every other reader\n  // shares — never `loadFile(path)`. A fleet spreads its model over more than\n  // the landscape (a second `model { }` block in a sibling, a use case, a\n  // palette), and `landscape.service-isolated` grades `touched` over exactly\n  // this set: reading the landscape alone made `adopt` report `touched: false`,\n  // the attested calls and an edit target for a service the fleet run on the\n  // same tree called matched, with nothing to tell an agent which was right.\n  const known = await knownServices(docsDir);\n  const land = await loadArchitecture(docsDir);\n  if (land.errors.length > 0) {\n    // Since W4 this arm answers for the whole `architecture/` PROJECT, so the\n    // document that broke is very often a SIBLING beside a landscape that parses\n    // perfectly — and two things followed from not saying so:\n    //   - the instruction told an agent to go and fix parse errors in\n    //     `architecture/landscape.likec4`, which has none, contradicting\n    //     `validate --all` run one second later on the same tree;\n    //   - the API question — who CALLS this service — was answered \"unknown\"\n    //     off a landscape file loam can read, so a broken palette flipped\n    //     `openapi.yaml` to required for a browser UI the map proves nobody\n    //     calls, while `list` and `context` (which read the FILE, see\n    //     core/pack/living.ts) answered the opposite about the same tree.\n    // Nothing else is rescued: `modelled`, `elements` and `touched` stay\n    // unknown, because those are claims about the project the renderer loads.\n    const expects = await expectsFromFile(path, service, known);\n    return {\n      ...empty,\n      callersKnown: expects !== null,\n      expects: expects ?? [],\n      instruction: instructionFor({\n        ...bare,\n        expects: expects ?? [],\n        state: \"unparseable\",\n        broken: brokenDocuments(docsDir, land),\n      }),\n    };\n  }\n\n  // One resolver for the whole scan, built with the real service ids, and\n  // built BEFORE the element filter: \"an element resolves to this service\" is\n  // the resolver's answer — a nearest-ancestor binding wins over a descendant's\n  // title — and it is the answer `validate --all` grades `service-unmodelled`\n  // on and `loam context` prints `modelled` from. This used to ask each\n  // element for its OWN binding-or-title instead, so a container titled\n  // 'payment-service' inside an element bound to order-service read as\n  // payment-service's box, and the edgeless arm told an agent \"do not add a\n  // second element\" for a service the fleet run reported unmodelled (error).\n  // The same resolver serves the edges: one drawn into a modelled container\n  // (`paymentService.api`) is an edge into the service, and `expects` — which\n  // decides whether this service owes an OpenAPI contract at all — has to see\n  // it. Building it once also stops the per-edge rebuild the old\n  // `serviceOf(land.elements, id)` call did.\n  const svcOf = serviceResolver(land.elements, known);\n  const mine = (id: string): boolean => svcOf(id) === service;\n  // The service-LEVEL elements only: one that resolves to the service while\n  // an ancestor does too is a container of it, and listing it would show a\n  // second box the map does not have.\n  const elements: LandscapeElement[] = land.elements\n    .filter((e) => mine(e.id) && !properAncestorIds(e.id).some(mine))\n    .map((e) => ({\n      id: e.id,\n      title: e.title,\n      kind: e.kind,\n      tags: e.tags,\n      bound: e.service !== undefined,\n    }));\n\n  const inbound: LandscapeEdge[] = [];\n  const outbound: LandscapeEdge[] = [];\n  // An edge whose BOTH endpoints resolve here is the service's own internal\n  // wiring: filed as inbound it made the service its own caller (verification\n  // 2026-09-04). It still TOUCHES the service, so `touched` below reads the\n  // relationships rather than these lists — the isolation check counts either\n  // endpoint, and the two predicates must not disagree.\n  const self = (r: { source: string; target: string }): boolean => mine(r.source) && mine(r.target);\n  for (const r of land.relationships) {\n    if (self(r)) continue;\n    const edge = { op: r.op ?? null, title: r.title ?? null };\n    if (mine(r.target)) inbound.push({ from: svcOf(r.source), ...edge });\n    else if (mine(r.source)) outbound.push({ to: svcOf(r.target), ...edge });\n  }\n\n  const expects = [...new Set(inbound.map((e) => e.op).filter((op): op is string => op !== null))];\n  const modelled = land.elements.some((e) => mine(e.id));\n  const touched = modelled ? land.relationships.some((r) => mine(r.source) || mine(r.target)) : null;\n  const attested =\n    touched === false && existsSync(paths.model) ? await attestedFrom(docsDir, paths, service, known) : [];\n  const req = {\n    service,\n    expects,\n    servicePath,\n    attested,\n    foreignTags: foreignTagsOf(elements),\n    elementId: elements[0]?.id,\n    // The one graded tag that changes what the brief may PROMISE: an `#external`\n    // element is never `landscape.service-isolated`'s subject. Off the same\n    // element `elementId` names, never the union.\n    external: elements[0]?.tags.includes(EXTERNAL_TAG) ?? false,\n  };\n  const instruction = !modelled\n    ? instructionFor({ ...req, state: \"unmodelled\" })\n    : touched === false\n      ? instructionFor({ ...req, state: \"edgeless\" })\n      : null;\n  return {\n    present: true,\n    parses: true,\n    callersKnown: true,\n    modelled,\n    elements,\n    inbound,\n    outbound,\n    expects,\n    touched,\n    attested,\n    instruction,\n  };\n}\n\n/**\n * The operations the fleet already calls on this service, read off the landscape\n * FILE alone — `null` when that file cannot be read either.\n *\n * The fallback for an `architecture/` project that does not parse, and the\n * narrowest one that can be justified: it answers ONE question, the one `loam\n * list` and `loam context` answer off the same bytes (`landscapeEvidence`,\n * core/vocabulary/maturity.ts). \"Nothing calls this service\" and \"loam could not\n * tell\" are different answers, and only the first may switch an API contract\n * off, which is why the empty list and the unreadable file are told apart here\n * rather than collapsed to `[]`.\n */\nasync function expectsFromFile(path: string, service: string, known: ReadonlySet<string>): Promise<string[] | null> {\n  try {\n    const doc = await loadFile(path);\n    if (doc.errors.length > 0) return null;\n    const svcOf = serviceResolver(doc.elements, known);\n    const ops = doc.relationships\n      .filter((r) => svcOf(r.target) === service)\n      .map((r) => r.op)\n      .filter((op): op is string => op !== undefined);\n    return [...new Set(ops)];\n  } catch {\n    return null;\n  }\n}\n"]}
+{"version":3,"file":"landscape.js","sourceRoot":"","sources":["../../../src/core/brief/landscape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet-map half of the adoption brief, READ side: what the fleet map\n * already says about one service — its elements, its inbound and outbound\n * edges, the operations the fleet already calls on it — and which of the four\n * states the map is in for it. The write the service still owes the file — the\n * block, when nothing in it resolves to the service yet, or the EDGES, when an\n * element does and no edge touches it — is spelled in `./map/owed.ts`\n * (`landscapeArtifact`, `instructionFor`), which this module hands its findings\n * to. Both halves exist to stop an agent inventing a parallel model: the fleet\n * has already drawn some of these boxes and edges, and a baseline has to attach.\n *\n * \"The fleet map\" is the `architecture/` PROJECT — the landscape plus every\n * other `.likec4` under it, minus the generated views file — and not the\n * landscape FILE. The two are the same document set `validate --all` grades\n * `landscape.service-isolated` over, and reading one file here let the two\n * surfaces disagree about the same tree.\n */\nimport { existsSync } from \"node:fs\";\nimport { loadFile } from \"../c4/likec4.js\";\nimport { loadArchitecture } from \"../c4/project/architecture.js\";\nimport { attestedCalls, type AttestedCall } from \"../c4/resolve/attested.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { ServiceModels } from \"../c4/prefetch/fleet.js\";\nimport { OBLIGATION_TAG_PREFIX } from \"../obligations/obligations.js\";\nimport { landscapePath, type ServicePaths } from \"../repo/paths.js\";\nimport { enumeratedServiceIds, serviceTreePathOf } from \"../repo/service-target.js\";\nimport { EXTERNAL_TAG, GRADED_TAGS } from \"../vocabulary/maturity.js\";\nimport { brokenDocuments, instructionFor } from \"./map/owed.js\";\nimport { properAncestorIds } from \"../kernel/ids/fqn/ancestors.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/* ------------------------------------------------------------------ */\n/* What the fleet already says about this service                      */\n/* ------------------------------------------------------------------ */\n\nexport interface LandscapeElement {\n  id: string;\n  title: string;\n  kind: string;\n  tags: string[];\n  /** True when the element binds explicitly with `metadata { service }`. */\n  bound: boolean;\n}\n\nexport interface LandscapeEdge {\n  from?: string;\n  to?: string;\n  op: string | null;\n  title: string | null;\n}\n\nexport interface LandscapeContext {\n  /** Whether `architecture/landscape.likec4` — the file the brief asks for edits to — is on disk. */\n  present: boolean;\n  /**\n   * False when the landscape exists but the `architecture/` project does not\n   * parse. A sibling under `architecture/` counts: a broken use case leaves the\n   * map unusable for `validate --all` too, and a brief that read the landscape\n   * alone would report a fleet nobody can render.\n   */\n  parses: boolean;\n  /**\n   * Whether loam could read WHO CALLS this service — the only evidence an EMPTY\n   * `expects` may be read as \"nothing calls it\".\n   *\n   * A separate fact from `parses` because they answer about different documents.\n   * `parses` is about the whole `architecture/` PROJECT (W4), and the callers\n   * live in the landscape FILE: a broken palette or use case beside a landscape\n   * that reads perfectly left `parses` false, and `apiExpected` then demanded an\n   * OpenAPI contract of a browser UI the map proves nobody calls — while `loam\n   * list` and `loam context`, which read the file (core/pack/living.ts), said the\n   * opposite about the same tree.\n   */\n  callersKnown: boolean;\n  /** Whether any element resolves to this service — null when nothing could be read. */\n  modelled: boolean | null;\n  /**\n   * The service-LEVEL elements that resolve to this service: an element whose\n   * ancestor also resolves to it is one of its containers, not a second box.\n   */\n  elements: LandscapeElement[];\n  /**\n   * The map's edges into and out of this service, INTERNAL edges excluded: an\n   * edge whose two endpoints both resolve here (`svc.web -> svc.db`) is this\n   * service's own wiring, and filed as inbound it named the service as its own\n   * caller.\n   */\n  inbound: LandscapeEdge[];\n  outbound: LandscapeEdge[];\n  /** Operations other services already call on this one: the contract owes them. */\n  expects: string[];\n  /**\n   * Whether at least one relationship in the map has an endpoint resolving to\n   * this service — read off the relationships, NOT off `inbound`/`outbound`,\n   * because an intra-service edge counts here (it is `landscape.service-\n   * isolated`'s predicate) while those two lists drop it. `null` exactly when\n   * `modelled` is `null` or `false`. It exists\n   * because `instruction` used to go null on element existence alone, and\n   * `loam seed` writes a bound, edgeless element for every service nobody\n   * listed under `calls:` — so the brief declared the map finished for exactly\n   * the services the map had not reached.\n   *\n   * Binary by design, and the fifth silent case of `landscape.service-isolated`\n   * with it: ONE edge closes the state, so a map drawing one of five attested\n   * calls reports `touched: true`, `attested: []` and no instruction. The check\n   * is touched/untouched, not a set difference — loam cannot tell a call the map\n   * omits from a call it deliberately does not draw at fleet level, and a\n   * difference reported as an omission would be an invented edge with a code\n   * beside it.\n   */\n  touched: boolean | null;\n  /**\n   * The calls `services/<…>/<svc>/model.likec4` declares ACROSS its boundary\n   * (`attestedCalls`, core/c4/resolve/attested.ts). `[]` when the model is\n   * absent, unparseable, or declares none — deliberately not told apart, since\n   * the only thing the brief may do with the list is name edges ALREADY\n   * ATTESTED, never invent one. Read only when `touched` is `false`: every\n   * other state either has edges (nothing owed) or no element (the block, not\n   * the edges, is owed), and a first adoption has no model to read anyway.\n   */\n  attested: AttestedCall[];\n  /**\n   * The write this service still owes the fleet map, in prose — null once an\n   * element resolves to it AND an edge touches that element. It duplicates the\n   * `landscape.likec4` target's shape rules on purpose: an agent driving off\n   * `--json` reads `landscape` to learn what the fleet already says, and every\n   * `targets[]` consumer walks the artifact list. Only one of those two readers\n   * used to exist, so `adopt` briefed eight files and never once said the ninth\n   * thing — that a documented service nobody drew is invisible to the whole\n   * cross-service layer.\n   */\n  instruction: string | null;\n}\n\n/**\n * The tags loam reads on an ELEMENT. `GRADED_TAGS` is the vocabulary's own\n * list of the tags that change what loam concludes — spelled once there, so\n * the day a third tag is graded this set follows and the instruction below\n * does not tell an agent to clear it as unread. The obligation prefix is the\n * one tag PREFIX loam reads on an element; `#cap-`/`#req-` are view tags and\n * never sit on one, so they are not in this list.\n */\nconst LOAM_TAGS: ReadonlySet<string> = new Set(GRADED_TAGS);\n\n/**\n * The element's tags loam does NOT read — named in the instruction and never\n * interpreted. A placeholder convention (\"drawn ahead of adoption\") is the\n * fleet's own, `loam seed` writes none, and a view written `exclude\n * element.tag = #<that>` keeps an adopted service hidden until it is cleared.\n */\nfunction foreignTagsOf(elements: LandscapeElement[]): string[] {\n  const unread = (t: string): boolean => !LOAM_TAGS.has(t) && !t.startsWith(OBLIGATION_TAG_PREFIX);\n  return [...new Set(elements.flatMap((e) => e.tags))].filter(unread);\n}\n\n/**\n * The attested calls, or nothing off a model that could not be read: `c4.invalid`\n * is validate's finding, and an edge list read off half a document is invention.\n *\n * Through the ONE reader of `model.likec4` (`core/c4/service-model/load.ts`),\n * because the two shapes are read differently and this brief is handed to an\n * agent that will act on it: a model that EXTENDS the fleet map, opened as a\n * lone file, comes back as a pile of parse errors — so the brief would tell\n * every migrated service that its model attests nothing and quietly drop the\n * edges the map most likely owes. `mapUnreadable` is the same empty answer for\n * the same reason: an extending model whose map does not parse was never read.\n */\nasync function attestedFrom(\n  docsDir: DocsDir,\n  paths: ServicePaths,\n  service: string,\n  known: ReadonlySet<string>,\n): Promise<AttestedCall[]> {\n  // The memo directly rather than through `core/fleet-context.ts`, and the\n  // reason is the package graph: this module already depends on `core/c4/`, and\n  // reaching for the read index would add a `brief -> core-root` edge for one\n  // read in a command that grades a single service. The three things the memo\n  // cannot know for itself are supplied here — the enumeration this function\n  // was already handed, the per-file loader, and a counter nobody is keeping.\n  const models = new ServiceModels({\n    onProjectLoad: () => {\n      // `adopt` reports no read counters, so there is nothing to increment. The\n      // hook is the memo's way of letting a caller own its own statistics, and\n      // an empty one is that answer, not a forgotten line.\n    },\n    known: async () => known,\n    standalone: (path) => loadFile(path),\n  });\n  const model = await models.model(docsDir, paths);\n  if (model.mapUnreadable || model.doc.errors.length > 0) return [];\n  return attestedCalls(model.doc, service, known);\n}\n\n/**\n * What the living fleet map already says about this service — the half of the\n * brief that stops an agent inventing a parallel model: the fleet has already\n * drawn some of these boxes and edges, and the baseline has to attach to them.\n * An `architecture/` project that does not parse yields `modelled: null` —\n * \"nothing models it\" would be a claim about documents nobody could read; the\n * landscape FILE parsing on its own does not rescue it, because the map the\n * renderer and `validate --all` see is the whole project. `paths` is the\n * service's own artifact set, located by the caller through the enumeration\n * (never joined at `services/<id>/`): the model is opened in exactly one state —\n * an element with no edge — to name the calls the map most likely owes. The\n * WHOLE record travels rather than the model path alone, because the model is\n * now read through its own shape and an extending one is read as a project of\n * the service's directory plus the map. It is required rather than optional\n * because the edgeless instruction states what that file attests, and a caller\n * that omitted it would get a brief asserting a fact about a document loam never\n * opened.\n */\nexport async function landscapeContext(\n  docsDir: DocsDir,\n  service: string,\n  paths: ServicePaths,\n): Promise<LandscapeContext> {\n  const path = landscapePath(docsDir);\n  // The service's own directory, spelled from the enumeration rather than joined\n  // at the root: this text is handed to an AGENT that will go and edit files, and\n  // a filed service named at `services/<id>/` sends it to create a second\n  // directory beside the one that already exists.\n  const servicePath = await serviceTreePathOf(docsDir, service);\n  const bare = { service, expects: [], servicePath, attested: [], foreignTags: [] };\n  const empty: LandscapeContext = {\n    present: existsSync(path),\n    parses: false,\n    callersKnown: false,\n    modelled: null,\n    elements: [],\n    inbound: [],\n    outbound: [],\n    expects: [],\n    touched: null,\n    attested: [],\n    instruction: null,\n  };\n  if (!empty.present) return { ...empty, modelled: false, instruction: instructionFor({ ...bare, state: \"absent\" }) };\n\n  // The `architecture/` PROJECT, through the one loader every other reader\n  // shares — never `loadFile(path)`. A fleet spreads its model over more than\n  // the landscape (a second `model { }` block in a sibling, a use case, a\n  // palette), and `landscape.service-isolated` grades `touched` over exactly\n  // this set: reading the landscape alone made `adopt` report `touched: false`,\n  // the attested calls and an edit target for a service the fleet run on the\n  // same tree called matched, with nothing to tell an agent which was right.\n  //\n  // `known`: the service ids the resolver may fall back on when an element\n  // carries no `metadata { service }` binding — the same positive evidence\n  // `validate` and `list` hand it. A docs repo with no `services/` yet (`adopt`\n  // runs there) leaves the resolver with bindings alone, which is what it had\n  // before.\n  const known: ReadonlySet<string> = new Set(await enumeratedServiceIds(docsDir));\n  const land = await loadArchitecture(docsDir);\n  if (land.errors.length > 0) {\n    // Since W4 this arm answers for the whole `architecture/` PROJECT, so the\n    // document that broke is very often a SIBLING beside a landscape that parses\n    // perfectly — and two things followed from not saying so:\n    //   - the instruction told an agent to go and fix parse errors in\n    //     `architecture/landscape.likec4`, which has none, contradicting\n    //     `validate --all` run one second later on the same tree;\n    //   - the API question — who CALLS this service — was answered \"unknown\"\n    //     off a landscape file loam can read, so a broken palette flipped\n    //     `openapi.yaml` to required for a browser UI the map proves nobody\n    //     calls, while `list` and `context` (which read the FILE, see\n    //     core/pack/living.ts) answered the opposite about the same tree.\n    // Nothing else is rescued: `modelled`, `elements` and `touched` stay\n    // unknown, because those are claims about the project the renderer loads.\n    const expects = await expectsFromFile(path, service, known);\n    return {\n      ...empty,\n      callersKnown: expects !== null,\n      expects: expects ?? [],\n      instruction: instructionFor({\n        ...bare,\n        expects: expects ?? [],\n        state: \"unparseable\",\n        broken: brokenDocuments(docsDir, land),\n      }),\n    };\n  }\n\n  // One resolver for the whole scan, built with the real service ids, and\n  // built BEFORE the element filter: \"an element resolves to this service\" is\n  // the resolver's answer — a nearest-ancestor binding wins over a descendant's\n  // title — and it is the answer `validate --all` grades `service-unmodelled`\n  // on and `loam context` prints `modelled` from. This used to ask each\n  // element for its OWN binding-or-title instead, so a container titled\n  // 'payment-service' inside an element bound to order-service read as\n  // payment-service's box, and the edgeless arm told an agent \"do not add a\n  // second element\" for a service the fleet run reported unmodelled (error).\n  // The same resolver serves the edges: one drawn into a modelled container\n  // (`paymentService.api`) is an edge into the service, and `expects` — which\n  // decides whether this service owes an OpenAPI contract at all — has to see\n  // it. Building it once also stops the per-edge rebuild the old\n  // `serviceOf(land.elements, id)` call did.\n  const svcOf = serviceResolver(land.elements, known);\n  const mine = (id: string): boolean => svcOf(id) === service;\n  // The service-LEVEL elements only: one that resolves to the service while\n  // an ancestor does too is a container of it, and listing it would show a\n  // second box the map does not have.\n  const elements: LandscapeElement[] = land.elements\n    .filter((e) => mine(e.id) && !properAncestorIds(e.id).some(mine))\n    .map((e) => ({\n      id: e.id,\n      title: e.title,\n      kind: e.kind,\n      tags: e.tags,\n      bound: e.service !== undefined,\n    }));\n\n  const inbound: LandscapeEdge[] = [];\n  const outbound: LandscapeEdge[] = [];\n  // An edge whose BOTH endpoints resolve here is the service's own internal\n  // wiring: filed as inbound it made the service its own caller (verification\n  // 2026-09-04). It still TOUCHES the service, so `touched` below reads the\n  // relationships rather than these lists — the isolation check counts either\n  // endpoint, and the two predicates must not disagree.\n  const self = (r: { source: string; target: string }): boolean => mine(r.source) && mine(r.target);\n  for (const r of land.relationships) {\n    if (self(r)) continue;\n    const edge = { op: r.op ?? null, title: r.title ?? null };\n    if (mine(r.target)) inbound.push({ from: svcOf(r.source), ...edge });\n    else if (mine(r.source)) outbound.push({ to: svcOf(r.target), ...edge });\n  }\n\n  const expects = [...new Set(inbound.map((e) => e.op).filter((op): op is string => op !== null))];\n  const modelled = land.elements.some((e) => mine(e.id));\n  const touched = modelled ? land.relationships.some((r) => mine(r.source) || mine(r.target)) : null;\n  const attested =\n    touched === false && existsSync(paths.model) ? await attestedFrom(docsDir, paths, service, known) : [];\n  const req = {\n    service,\n    expects,\n    servicePath,\n    attested,\n    foreignTags: foreignTagsOf(elements),\n    elementId: elements[0]?.id,\n    // The one graded tag that changes what the brief may PROMISE: an `#external`\n    // element is never `landscape.service-isolated`'s subject. Off the same\n    // element `elementId` names, never the union.\n    external: elements[0]?.tags.includes(EXTERNAL_TAG) ?? false,\n  };\n  const instruction = !modelled\n    ? instructionFor({ ...req, state: \"unmodelled\" })\n    : touched === false\n      ? instructionFor({ ...req, state: \"edgeless\" })\n      : null;\n  return {\n    present: true,\n    parses: true,\n    callersKnown: true,\n    modelled,\n    elements,\n    inbound,\n    outbound,\n    expects,\n    touched,\n    attested,\n    instruction,\n  };\n}\n\n/**\n * The operations the fleet already calls on this service, read off the landscape\n * FILE alone — `null` when that file cannot be read either.\n *\n * The fallback for an `architecture/` project that does not parse, and the\n * narrowest one that can be justified: it answers ONE question, the one `loam\n * list` and `loam context` answer off the same bytes (`landscapeEvidence`,\n * core/vocabulary/maturity.ts). \"Nothing calls this service\" and \"loam could not\n * tell\" are different answers, and only the first may switch an API contract\n * off, which is why the empty list and the unreadable file are told apart here\n * rather than collapsed to `[]`.\n */\nasync function expectsFromFile(path: string, service: string, known: ReadonlySet<string>): Promise<string[] | null> {\n  try {\n    const doc = await loadFile(path);\n    if (doc.errors.length > 0) return null;\n    const svcOf = serviceResolver(doc.elements, known);\n    const ops = doc.relationships\n      .filter((r) => svcOf(r.target) === service)\n      .map((r) => r.op)\n      .filter((op): op is string => op !== undefined);\n    return [...new Set(ops)];\n  } catch {\n    return null;\n  }\n}\n"]}

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

@@ -1,11 +1,14 @@
 /** The literals `targets.ts` leaves in the model target for this module to fill in. */
 export const FQN = "<fqn>";
 /**
- * The service being adopted, in the model example's header. It is a placeholder
- * for the same reason `<fqn>` is: the example is handed to an agent that copies
- * it, and a header naming payment-service travelled verbatim into every other
- * service's model — the more convincingly for sitting one line above an
- * `extend` the brief HAD substituted.
+ * The service being adopted, in the model example's header and in the spec
+ * examples' frontmatter and title. It is a placeholder for the same reason
+ * `<fqn>` is: the example is handed to an agent that copies it, and a header
+ * naming payment-service travelled verbatim into every other service's model —
+ * the more convincingly for sitting one line above an `extend` the brief HAD
+ * substituted. In spec.md and arch.spec.md the literal was worse than
+ * misleading: `service:` must name the directory the file sits in, so a
+ * verbatim paste failed `frontmatter.field-mismatch` everywhere but one service.
  */
 export const SVC = "<svc>";
 /** The token an example carries where loam has no id to substitute. Short on purpose — see `ExtendPoint`. */

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

@@ -7,6 +7,21 @@
  * it against a docs repo, and the fleet map's own target, whose block names
  * the service, is assembled per service in map/owed.ts.
  */
+/**
+ * The service-local use-case directory, and the one artifact key `ServicePaths`
+ * deliberately does NOT carry.
+ *
+ * `repo/paths.ts` spells the paths loam JOINS ON — the ones a check resolves, a
+ * writer writes and the tree walk classifies a directory by. This is not one of
+ * them: the slot a service's flows are graded out of is the service's whole
+ * LikeC4 project, every `.likec4` under its directory
+ * (`core/usecases/service/flows.ts`), and `usecases/<name>.likec4` is the
+ * CONVENTION the brief publishes for it. Putting the directory in
+ * `ARTIFACT_FILES` would be worse than redundant — `isServiceArtifactName`
+ * reads that table, so a `usecases/` directory anywhere under `services/` would
+ * mint a service.
+ */
+export const USECASES_DIR = "usecases";
 /** The artifacts, in the order a baseline is best written in. */
 export const ARTIFACTS = [
     {
@@ -78,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.
 
@@ -102,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.
 
@@ -131,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.
 
@@ -153,6 +178,55 @@ Covers: paymentService.db, paymentService -> kafka
 - **Given** an event in the outbox
 - **When** the broker is unavailable
 - **Then** the state stays committed and the event is published once it returns
+`,
+    },
+    {
+        artifact: "usecases/<name>.likec4",
+        key: "usecasesDir",
+        // Never required, and here the optionality is a RULE rather than a
+        // judgement. docs/DESIGN.md rule 26 — "presence is never owed. A model with
+        // no views is missing nothing loam wants, and no check may grade its
+        // absence" — is enforced by scripts/arch-check.mjs, not merely written, so
+        // there is no `service.usecases-missing` and there never will be one.
+        //
+        // The slot is briefed anyway because a team cannot choose a slot nobody
+        // named. The grader landed 2026-09-03 (`core/usecases/service/flows.ts`) and
+        // `c4.valid` has been reporting ` · K tagged flow(s) graded` ever since, on
+        // an axis nothing scaffolded, briefed or named — so the only way to discover
+        // it was to read the source. Publication is the whole of this entry: every
+        // rule below is either a check that already exists or a convention loam
+        // states and never grades, and each says which it is.
+        required: false,
+        purpose: "optional — one requirement's hop sequence, drawn as a LikeC4 dynamic view over this service's own containers",
+        shape: [
+            "A `dynamic view` in a `.likec4` under this service's directory. THE SLOT IS THE PROJECT: `loam subsystem sync` registers every `.likec4` under `services/<…>/<id>/` as one LikeC4 project, and loam reads exactly the set the renderer reads — `model.likec4` plus every sibling, recursively. `usecases/<name>.likec4` is the convention this brief publishes, and `<name>` is yours. Never `architecture/usecases/`, which is a different project: it holds the map and no service's containers, so a hop naming one is `landscape.invalid` for the whole fleet.",
+            "`#req-<Requirement-ID>` as the FIRST thing in the view body, before `title` — written after it, LikeC4 reports five parse errors and none of them mentions tags. The tag is the opt-in: an untagged view is somebody's hand-drawn diagram and loam never says a word about it. The slug is the `Requirement-ID` from this service's own `spec.md` or `arch.spec.md` with every character outside `[A-Za-z0-9_-]` flattened to `-`; a slug naming no requirement of this service is `usecase.requirement-unresolved`. Several `#req-` tags on one view are legal and normal.",
+            "DECLARE the tag exactly once — in `architecture/landscape.likec4`'s `specification` block when this model EXTENDS the map (the usual shape, and the block the whole root project shares), or in `model.likec4`'s own `specification` when the model STANDS ALONE. Declaring it in both is a duplicate, and the code lands where the SECOND declaration's file is: `c4.invalid` when a tags-only block sits in model.likec4, `usecase.flow-invalid` when it sits in a sibling. Two SERVICES each declaring the same tag locally is the fleet-scope class one step out, `c4.fleet-project-invalid`.",
+            "Every hop must be backed by a relationship the model already declares, or it is `usecase.step-unbacked` — LikeC4 itself reports nothing for an unbacked hop, so the diagram renders and every other check stays green. A return step is written `<target> <- <source>`: a reply is attributed to the CALL it answers. A hop whose caller and provider resolve to the SAME service never owes an `operationId`, which is what makes this altitude cheap: `usecase.step-unlinked` is silent inside one service.",
+            "Namespace the view id by the service — `uc_payment_service_authorize`, not `uc_authorize`. An EXTENDING model's views live in the ROOT project beside the map, so view ids are one flat namespace across the whole fleet: two services minting `uc_authorize` makes the renderer refuse the entire project. Ids beginning `subsystem_` or `service_` are loam's own (`subsystem.view-id-collision`).",
+            "Title it `'<subsystem path> / <service id> / <use case>'`. LikeC4 has no view-folder syntax — it splits a view title on `/` into browser folders and shows only the last segment (measured at 1.59.2) — so that convention lands the flow in the same folder as the generated overview of its service in `architecture/services.likec4`. **Nothing checks this**: it is a convention loam states and never grades, exactly like the EARS form in spec.md.",
+            "OPTIONAL, and its absence is graded by nothing, ever. That is docs/DESIGN.md rule 26 and it is enforced. Write one where a requirement's `Covers:` names containers and the sequence is the thing that is hard to hold in the head; write none otherwise. `c4.valid` reports ` · K tagged flow(s) graded` when the project declares any, and that count is the only place a healthy flow appears at all.",
+        ],
+        example: `// One of <svc>'s own use cases: the hops behind ONE requirement of its
+// arch.spec.md, over its OWN containers. Optional — nothing grades the
+// absence of this file, and an untagged view here is never graded either.
+views {
+  // Namespace the id by the service, underscores for hyphens: an extending
+  // model's views share ONE flat id namespace with the whole root project.
+  dynamic view uc_authorize_payment {
+    // The tag comes FIRST. Written after 'title' this is five parse errors.
+    // AUTH-1 is a Requirement-ID in this service's spec.md or arch.spec.md.
+    #req-AUTH-1
+    title '<subsystem path> / <svc> / Authorize a payment'
+    description 'What the service does between the request and the answer'
+
+    // Every hop is backed by a relationship model.likec4 declares. Both of
+    // these are inside one service, so neither owes an operationId.
+    <fqn>.api -> <fqn>.ledger 'Records the authorization'
+    // A reply is attributed to the call it answers, hence the '<-'.
+    <fqn>.api <- <fqn>.ledger 'Confirms the write'
+  }
+}
 `,
     },
     {
@@ -186,7 +260,7 @@ Covers: paymentService.db, paymentService -> kafka
         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.",