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

package/dist/core/brief/landscape.js

@@ -1,194 +1,277 @@
 /**
- * The fleet-map half of the adoption brief: what `architecture/landscape.likec4`
+ * The fleet-map half of the adoption brief, READ side: what the fleet map
  * already says about one service — its elements, its inbound and outbound
- * edges, the operations the fleet already calls on it — and the block the
- * service still owes the file when nothing in it resolves to the service yet.
- * Both halves exist to stop an agent inventing a parallel model: the fleet has
- * already drawn some of these boxes and edges, and a baseline has to attach to
- * them.
+ * edges, the operations the fleet already calls on it — and which of the four
+ * states the map is in for it. The write the service still owes the file — the
+ * block, when nothing in it resolves to the service yet, or the EDGES, when an
+ * element does and no edge touches it — is spelled in `./map/owed.ts`
+ * (`landscapeArtifact`, `instructionFor`), which this module hands its findings
+ * to. Both halves exist to stop an agent inventing a parallel model: the fleet
+ * has already drawn some of these boxes and edges, and a baseline has to attach.
+ *
+ * "The fleet map" is the `architecture/` PROJECT — the landscape plus every
+ * other `.likec4` under it, minus the generated views file — and not the
+ * landscape FILE. The two are the same document set `validate --all` grades
+ * `landscape.service-isolated` over, and reading one file here let the two
+ * surfaces disagree about the same tree.
  */
 import { existsSync } from "node:fs";
 import { loadFile } from "../c4/likec4.js";
-import { elementService, serviceResolver } from "../c4/resolve/service.js";
+import { loadArchitecture } from "../c4/project/architecture.js";
+import { attestedCalls } from "../c4/resolve/attested.js";
+import { serviceResolver } from "../c4/resolve/service.js";
+import { ServiceModels } from "../c4/prefetch/fleet.js";
+import { OBLIGATION_TAG_PREFIX } from "../obligations/obligations.js";
 import { landscapePath } from "../repo/paths.js";
 import { enumeratedServiceIds, serviceTreePathOf } from "../repo/service-target.js";
+import { EXTERNAL_TAG, GRADED_TAGS } from "../vocabulary/maturity.js";
+import { brokenDocuments, instructionFor } from "./map/owed.js";
+import { properAncestorIds } from "../kernel/ids/fqn/ancestors.js";
 /**
- * The LikeC4 identifier the fleet map's element for a service conventionally
- * carries: the directory name, camel-cased. It is a suggestion and nothing
- * more — `metadata { service '<id>' }` is what actually joins the element to
- * the directory — but a brief that hands over a concrete block gets followed,
- * and one that describes a block in prose gets improvised on.
+ * The service ids the resolver may fall back on when an element carries no
+ * `metadata { service }` binding — the same positive evidence `validate` and
+ * `list` hand it. A docs repo with no `services/` yet (`adopt` runs there)
+ * leaves the resolver with bindings alone, which is what it had before.
  */
-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;
+async function knownServices(docsDir) {
+    return new Set(await enumeratedServiceIds(docsDir));
 }
 /**
- * The block this service still owes `architecture/landscape.likec4`.
- *
- * `expects` is what the fleet ALREADY calls on the service — those edges exist
- * in the map today, so the example draws the outbound side as a comment rather
- * than telling an agent to duplicate an edge that is already there.
+ * The tags loam reads on an ELEMENT. `GRADED_TAGS` is the vocabulary's own
+ * list of the tags that change what loam concludes — spelled once there, so
+ * the day a third tag is graded this set follows and the instruction below
+ * does not tell an agent to clear it as unread. The obligation prefix is the
+ * one tag PREFIX loam reads on an element; `#cap-`/`#req-` are view tags and
+ * never sit on one, so they are not in this list.
  */
-function landscapeBlock(service, expects, present) {
-    const id = elementIdFor(service);
-    const calls = expects.length > 0
-        ? expects.map((op) => `//   <caller> -> ${id} 'Calls ${op}' { metadata { op '${op}' } }`)
-        : [`//   <caller> -> ${id} 'Calls <operationId>' { metadata { op '<operationId>' } }`];
-    const model = [
-        "model {",
-        ...(present ? ["  // ... the fleet's other services stay exactly as they are ...", ""] : []),
-        `  ${id} = softwareSystem '${service}' {`,
-        "    description '<one line: what this service is responsible for>'",
-        `    metadata { service '${service}' }`,
-        "  }",
-        "",
-        "  // every call in or out of it, one edge each:",
-        ...calls.map((line) => `  ${line}`),
-        "}",
-    ];
-    // When the file does not exist the example is the WHOLE file, so it carries
-    // the `specification` block a bare `model` would be rejected without: the
-    // brief must never hand over a document `loam validate` refuses. When the file
-    // does exist the example is a fragment to splice, and repeating a
-    // `specification` block there would invite a second one.
-    return present
-        ? model.join("\n")
-        : ["specification {", "  element softwareSystem", "}", "", ...model].join("\n");
-}
-/** The fleet map's own brief — assembled per service, because the block it owes names the service. */
-export function landscapeArtifact(service, expects, present, servicePath) {
-    return {
-        artifact: "landscape.likec4",
-        required: true,
-        purpose: "the fleet map — until an element here resolves to this directory, the service is documented and invisible to every cross-service check",
-        shape: [
-            "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.",
-            `Add one top-level element for the service, bound to its directory: \`metadata { service '${service}' }\`. Until an element resolves to \`${servicePath}/\`, \`loam validate --all\` reports \`landscape.service-unmodelled\` (error).`,
-            "Bind rather than rename: a binding whose id names no directory is `landscape.binding-unknown` (error), and two elements binding the SAME directory is `landscape.binding-duplicate` (warn) — every element→service join then picks one of them arbitrarily.",
-            "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.",
-            "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.",
-        ],
-        example: landscapeBlock(service, expects, present),
-    };
-}
+const LOAM_TAGS = new Set(GRADED_TAGS);
+const LOAM_TAG_PREFIXES = [OBLIGATION_TAG_PREFIX];
 /**
- * The service ids the resolver may fall back on when an element carries no
- * `metadata { service }` binding — the same positive evidence `validate` and
- * `list` hand it. A docs repo that cannot be enumerated (no `services/` yet:
- * `adopt` runs there) leaves the resolver with bindings alone, which is what it
- * had before.
+ * The element's tags loam does NOT read — named in the instruction and never
+ * interpreted. A placeholder convention ("drawn ahead of adoption") is the
+ * fleet's own, `loam seed` writes none, and a view written `exclude
+ * element.tag = #<that>` keeps an adopted service hidden until it is cleared.
  */
-async function knownServices(docsDir) {
-    return new Set(await enumeratedServiceIds(docsDir));
+function foreignTagsOf(elements) {
+    const unread = (t) => !LOAM_TAGS.has(t) && !LOAM_TAG_PREFIXES.some((p) => t.startsWith(p));
+    return [...new Set(elements.flatMap((e) => e.tags))].filter(unread);
 }
 /**
- * What the living landscape already says about this service.
+ * The attested calls, or nothing off a model that could not be read: `c4.invalid`
+ * is validate's finding, and an edge list read off half a document is invention.
  *
- * This is the half of the brief that stops an agent inventing a parallel model:
- * the fleet has already drawn some of these boxes and edges, and the baseline has
- * to attach to them. A landscape that does not parse yields `modelled: null` —
- * "nothing models it" would be a claim about a document nobody could read.
+ * Through the ONE reader of `model.likec4` (`core/c4/service-model/load.ts`),
+ * because the two shapes are read differently and this brief is handed to an
+ * agent that will act on it: a model that EXTENDS the fleet map, opened as a
+ * lone file, comes back as a pile of parse errors — so the brief would tell
+ * every migrated service that its model attests nothing and quietly drop the
+ * edges the map most likely owes. `mapUnreadable` is the same empty answer for
+ * the same reason: an extending model whose map does not parse was never read.
+ */
+async function attestedFrom(docsDir, paths, service, known) {
+    // The memo directly rather than through `core/fleet-context.ts`, and the
+    // reason is the package graph: this module already depends on `core/c4/`, and
+    // reaching for the read index would add a `brief -> core-root` edge for one
+    // read in a command that grades a single service. The three things the memo
+    // cannot know for itself are supplied here — the enumeration this function
+    // was already handed, the per-file loader, and a counter nobody is keeping.
+    const models = new ServiceModels({
+        onProjectLoad: () => {
+            // `adopt` reports no read counters, so there is nothing to increment. The
+            // hook is the memo's way of letting a caller own its own statistics, and
+            // an empty one is that answer, not a forgotten line.
+        },
+        known: async () => known,
+        standalone: (path) => loadFile(path),
+    });
+    const model = await models.model(docsDir, paths);
+    if (model.mapUnreadable || model.doc.errors.length > 0)
+        return [];
+    return attestedCalls(model.doc, service, known);
+}
+/**
+ * What the living fleet map already says about this service — the half of the
+ * brief that stops an agent inventing a parallel model: the fleet has already
+ * drawn some of these boxes and edges, and the baseline has to attach to them.
+ * An `architecture/` project that does not parse yields `modelled: null` —
+ * "nothing models it" would be a claim about documents nobody could read; the
+ * landscape FILE parsing on its own does not rescue it, because the map the
+ * renderer and `validate --all` see is the whole project. `paths` is the
+ * service's own artifact set, located by the caller through the enumeration
+ * (never joined at `services/<id>/`): the model is opened in exactly one state —
+ * an element with no edge — to name the calls the map most likely owes. The
+ * WHOLE record travels rather than the model path alone, because the model is
+ * now read through its own shape and an extending one is read as a project of
+ * the service's directory plus the map. It is required rather than optional
+ * because the edgeless instruction states what that file attests, and a caller
+ * that omitted it would get a brief asserting a fact about a document loam never
+ * opened.
  */
-export async function landscapeContext(docsDir, service) {
+export async function landscapeContext(docsDir, service, paths) {
     const path = landscapePath(docsDir);
     // The service's own directory, spelled from the enumeration rather than joined
     // at the root: this text is handed to an AGENT that will go and edit files, and
     // a filed service named at `services/<id>/` sends it to create a second
     // directory beside the one that already exists.
     const servicePath = await serviceTreePathOf(docsDir, service);
+    const bare = { service, expects: [], servicePath, attested: [], foreignTags: [] };
     const empty = {
         present: existsSync(path),
         parses: false,
+        callersKnown: false,
         modelled: null,
         elements: [],
         inbound: [],
         outbound: [],
         expects: [],
+        touched: null,
+        attested: [],
         instruction: null,
     };
     if (!empty.present)
-        return { ...empty, modelled: false, instruction: instructionFor(service, "absent", [], servicePath) };
-    const land = await loadFile(path);
-    if (land.errors.length > 0)
-        return { ...empty, instruction: instructionFor(service, "unparseable", [], servicePath) };
-    const mine = (e) => elementService(e) === service;
-    const elements = land.elements.filter(mine).map((e) => ({
+        return { ...empty, modelled: false, instruction: instructionFor({ ...bare, state: "absent" }) };
+    // The `architecture/` PROJECT, through the one loader every other reader
+    // shares — never `loadFile(path)`. A fleet spreads its model over more than
+    // the landscape (a second `model { }` block in a sibling, a use case, a
+    // palette), and `landscape.service-isolated` grades `touched` over exactly
+    // this set: reading the landscape alone made `adopt` report `touched: false`,
+    // the attested calls and an edit target for a service the fleet run on the
+    // same tree called matched, with nothing to tell an agent which was right.
+    const known = await knownServices(docsDir);
+    const land = await loadArchitecture(docsDir);
+    if (land.errors.length > 0) {
+        // Since W4 this arm answers for the whole `architecture/` PROJECT, so the
+        // document that broke is very often a SIBLING beside a landscape that parses
+        // perfectly — and two things followed from not saying so:
+        //   - the instruction told an agent to go and fix parse errors in
+        //     `architecture/landscape.likec4`, which has none, contradicting
+        //     `validate --all` run one second later on the same tree;
+        //   - the API question — who CALLS this service — was answered "unknown"
+        //     off a landscape file loam can read, so a broken palette flipped
+        //     `openapi.yaml` to required for a browser UI the map proves nobody
+        //     calls, while `list` and `context` (which read the FILE, see
+        //     core/pack/living.ts) answered the opposite about the same tree.
+        // Nothing else is rescued: `modelled`, `elements` and `touched` stay
+        // unknown, because those are claims about the project the renderer loads.
+        const expects = await expectsFromFile(path, service, known);
+        return {
+            ...empty,
+            callersKnown: expects !== null,
+            expects: expects ?? [],
+            instruction: instructionFor({
+                ...bare,
+                expects: expects ?? [],
+                state: "unparseable",
+                broken: brokenDocuments(docsDir, land),
+            }),
+        };
+    }
+    // One resolver for the whole scan, built with the real service ids, and
+    // built BEFORE the element filter: "an element resolves to this service" is
+    // the resolver's answer — a nearest-ancestor binding wins over a descendant's
+    // title — and it is the answer `validate --all` grades `service-unmodelled`
+    // on and `loam context` prints `modelled` from. This used to ask each
+    // element for its OWN binding-or-title instead, so a container titled
+    // 'payment-service' inside an element bound to order-service read as
+    // payment-service's box, and the edgeless arm told an agent "do not add a
+    // second element" for a service the fleet run reported unmodelled (error).
+    // The same resolver serves the edges: one drawn into a modelled container
+    // (`paymentService.api`) is an edge into the service, and `expects` — which
+    // decides whether this service owes an OpenAPI contract at all — has to see
+    // it. Building it once also stops the per-edge rebuild the old
+    // `serviceOf(land.elements, id)` call did.
+    const svcOf = serviceResolver(land.elements, known);
+    const mine = (id) => svcOf(id) === service;
+    // The service-LEVEL elements only: one that resolves to the service while
+    // an ancestor does too is a container of it, and listing it would show a
+    // second box the map does not have.
+    const elements = land.elements
+        .filter((e) => mine(e.id) && !properAncestorIds(e.id).some(mine))
+        .map((e) => ({
         id: e.id,
         title: e.title,
         kind: e.kind,
         tags: e.tags,
         bound: e.service !== undefined,
     }));
-    // One resolver for the whole scan, built with the real service ids: an edge
-    // drawn into a modelled container (`paymentService.api`) is an edge into the
-    // service, and `expects` — which now decides whether this service owes an
-    // OpenAPI contract at all — has to see it. Building it once also stops the
-    // per-edge rebuild the old `serviceOf(land.elements, id)` call did.
-    const svcOf = serviceResolver(land.elements, await knownServices(docsDir));
     const inbound = [];
     const outbound = [];
+    // An edge whose BOTH endpoints resolve here is the service's own internal
+    // wiring: filed as inbound it made the service its own caller (verification
+    // 2026-09-04). It still TOUCHES the service, so `touched` below reads the
+    // relationships rather than these lists — the isolation check counts either
+    // endpoint, and the two predicates must not disagree.
+    const self = (r) => mine(r.source) && mine(r.target);
     for (const r of land.relationships) {
+        if (self(r))
+            continue;
         const edge = { op: r.op ?? null, title: r.title ?? null };
-        if (svcOf(r.target) === service)
+        if (mine(r.target))
             inbound.push({ from: svcOf(r.source), ...edge });
-        else if (svcOf(r.source) === service)
+        else if (mine(r.source))
             outbound.push({ to: svcOf(r.target), ...edge });
     }
     const expects = [...new Set(inbound.map((e) => e.op).filter((op) => op !== null))];
+    const modelled = land.elements.some((e) => mine(e.id));
+    const touched = modelled ? land.relationships.some((r) => mine(r.source) || mine(r.target)) : null;
+    const attested = touched === false && existsSync(paths.model) ? await attestedFrom(docsDir, paths, service, known) : [];
+    const req = {
+        service,
+        expects,
+        servicePath,
+        attested,
+        foreignTags: foreignTagsOf(elements),
+        elementId: elements[0]?.id,
+        // The one graded tag that changes what the brief may PROMISE: an `#external`
+        // element is never `landscape.service-isolated`'s subject. Off the same
+        // element `elementId` names, never the union.
+        external: elements[0]?.tags.includes(EXTERNAL_TAG) ?? false,
+    };
+    const instruction = !modelled
+        ? instructionFor({ ...req, state: "unmodelled" })
+        : touched === false
+            ? instructionFor({ ...req, state: "edgeless" })
+            : null;
     return {
         present: true,
         parses: true,
-        modelled: elements.length > 0,
+        callersKnown: true,
+        modelled,
         elements,
         inbound,
         outbound,
         expects,
-        instruction: elements.length > 0 ? null : instructionFor(service, "unmodelled", expects, servicePath),
+        touched,
+        attested,
+        instruction,
     };
 }
 /**
- * The fleet-map instruction, in the three states a landscape can be in.
+ * The operations the fleet already calls on this service, read off the landscape
+ * FILE alone — `null` when that file cannot be read either.
  *
- * It says the file, the block, and the consequence, in that order. The
- * consequence is the part agents acted on: "add an element" reads as tidiness,
- * "until you do, `loam validate --all` fails and no cross-service check can see
- * this service" reads as work.
+ * The fallback for an `architecture/` project that does not parse, and the
+ * narrowest one that can be justified: it answers ONE question, the one `loam
+ * list` and `loam context` answer off the same bytes (`landscapeEvidence`,
+ * core/vocabulary/maturity.ts). "Nothing calls this service" and "loam could not
+ * tell" are different answers, and only the first may switch an API contract
+ * off, which is why the empty list and the unreadable file are told apart here
+ * rather than collapsed to `[]`.
  */
-function instructionFor(service, state, expects, servicePath) {
-    const id = elementIdFor(service);
-    const bind = `an element bound with \`metadata { service '${service}' }\``;
-    const consequence = `Until one resolves, \`loam validate --all\` reports \`landscape.service-unmodelled\` (error) for ` +
-        `${servicePath}/: the service is documented and invisible — no edge into it can be checked ` +
-        `against its openapi.yaml, and no feature can draw a call to it.`;
-    // `expects` is reachable only through elements that already resolve to this
-    // service, so it is empty in every state that produces an instruction. It is
-    // threaded through anyway rather than dropped: the caller computes it once,
-    // and the day an unmodelled service can inherit an edge (a container-level
-    // binding, say) the sentence is already here instead of being noticed missing.
-    const owed = expects.length > 0
-        ? ` The fleet already calls ${expects.map((o) => `'${o}'`).join(", ")} on this service, so those edges exist; your element is what they will resolve to.`
-        : "";
-    if (state === "absent") {
-        return (`architecture/landscape.likec4 does not exist yet. Create it with a \`specification { ... }\` block ` +
-            `declaring the kinds you use and a \`model { ... }\` block containing ${bind} ` +
-            `(conventionally \`${id} = softwareSystem '${service}'\`), plus one edge per cross-service call, each ` +
-            `carrying \`metadata { op '<operationId>' }\`. ${consequence}${owed}`);
+async function expectsFromFile(path, service, known) {
+    try {
+        const doc = await loadFile(path);
+        if (doc.errors.length > 0)
+            return null;
+        const svcOf = serviceResolver(doc.elements, known);
+        const ops = doc.relationships
+            .filter((r) => svcOf(r.target) === service)
+            .map((r) => r.op)
+            .filter((op) => op !== undefined);
+        return [...new Set(ops)];
     }
-    if (state === "unparseable") {
-        return (`architecture/landscape.likec4 exists but does not parse (\`landscape.invalid\`), so nothing can be said ` +
-            `about what it already models. Fix the parse errors first — they blind every cross-service check at once — ` +
-            `then make sure it holds ${bind}. ${consequence}`);
+    catch {
+        return null;
     }
-    return (`Nothing in architecture/landscape.likec4 resolves to ${servicePath}/. ADD to that file — do not rewrite ` +
-        `it, every other service's map is in there — ${bind}, conventionally ` +
-        `\`${id} = softwareSystem '${service}'\`, inside the existing \`model { ... }\` block, and draw each ` +
-        `cross-service call as an edge carrying \`metadata { op '<operationId>' }\`. ${consequence}${owed}`);
 }
 //# sourceMappingURL=landscape.js.map

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: what `architecture/landscape.likec4`\n * already says about one service — its elements, its inbound and outbound\n * edges, the operations the fleet already calls on it — and the block the\n * service still owes the file when nothing in it resolves to the service yet.\n * Both halves exist to stop an agent inventing a parallel model: the fleet has\n * already drawn some of these boxes and edges, and a baseline has to attach to\n * them.\n */\nimport { existsSync } from \"node:fs\";\nimport { loadFile, type Elem } from \"../c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../c4/resolve/service.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { enumeratedServiceIds, serviceTreePathOf } from \"../repo/service-target.js\";\nimport type { BriefTarget } from \"./targets.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * The LikeC4 identifier the fleet map's element for a service conventionally\n * carries: the directory name, camel-cased. It is a suggestion and nothing\n * more — `metadata { service '<id>' }` is what actually joins the element to\n * the directory — but a brief that hands over a concrete block gets followed,\n * and one that describes 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 block 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.\n */\nfunction landscapeBlock(service: string, expects: string[], present: boolean): string {\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\n/** The fleet map's own brief — assembled per service, because the block it owes names the service. */\nexport function landscapeArtifact(\n  service: string,\n  expects: string[],\n  present: boolean,\n  servicePath: string,\n): Omit<BriefTarget, \"path\" | \"exists\" | \"action\"> {\n  return {\n    artifact: \"landscape.likec4\",\n    required: true,\n    purpose:\n      \"the fleet map — until an element here resolves to this directory, the service is documented and invisible to every cross-service check\",\n    shape: [\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      `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      \"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      \"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    example: landscapeBlock(service, expects, present),\n  };\n}\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  present: boolean;\n  /** False when the landscape exists but does not parse. */\n  parses: boolean;\n  /** Whether any element resolves to this service — null when nothing could be read. */\n  modelled: boolean | null;\n  elements: LandscapeElement[];\n  inbound: LandscapeEdge[];\n  outbound: LandscapeEdge[];\n  /** Operations other services already call on this one: the contract owes them. */\n  expects: string[];\n  /**\n   * The write this service still owes the fleet map, in prose — null once an\n   * element resolves to it.\n   *\n   * It duplicates the `landscape.likec4` target's shape rules on purpose: an\n   * agent driving off `--json` reads `landscape` to learn what the fleet\n   * already says, and every `targets[]` consumer walks the artifact list. Only\n   * one of those two readers used to exist, so `adopt` briefed eight files and\n   * never once said the ninth thing — that a documented service nobody drew is\n   * invisible to the whole 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 that cannot be enumerated (no `services/` yet:\n * `adopt` runs there) leaves the resolver with bindings alone, which is what it\n * had before.\n */\nasync function knownServices(docsDir: DocsDir): Promise<ReadonlySet<string>> {\n  return new Set(await enumeratedServiceIds(docsDir));\n}\n\n/**\n * What the living landscape already says about this service.\n *\n * This is the half of the brief that stops an agent inventing a parallel model:\n * the fleet has already drawn some of these boxes and edges, and the baseline has\n * to attach to them. A landscape that does not parse yields `modelled: null` —\n * \"nothing models it\" would be a claim about a document nobody could read.\n */\nexport async function landscapeContext(docsDir: DocsDir, service: string): 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 empty: LandscapeContext = {\n    present: existsSync(path),\n    parses: false,\n    modelled: null,\n    elements: [],\n    inbound: [],\n    outbound: [],\n    expects: [],\n    instruction: null,\n  };\n  if (!empty.present)\n    return { ...empty, modelled: false, instruction: instructionFor(service, \"absent\", [], servicePath) };\n\n  const land = await loadFile(path);\n  if (land.errors.length > 0)\n    return { ...empty, instruction: instructionFor(service, \"unparseable\", [], servicePath) };\n\n  const mine = (e: Elem): boolean => elementService(e) === service;\n  const elements: LandscapeElement[] = land.elements.filter(mine).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  // One resolver for the whole scan, built with the real service ids: an edge\n  // drawn into a modelled container (`paymentService.api`) is an edge into the\n  // service, and `expects` — which now decides whether this service owes an\n  // OpenAPI contract at all — has to see it. Building it once also stops the\n  // per-edge rebuild the old `serviceOf(land.elements, id)` call did.\n  const svcOf = serviceResolver(land.elements, await knownServices(docsDir));\n  const inbound: LandscapeEdge[] = [];\n  const outbound: LandscapeEdge[] = [];\n  for (const r of land.relationships) {\n    const edge = { op: r.op ?? null, title: r.title ?? null };\n    if (svcOf(r.target) === service) inbound.push({ from: svcOf(r.source), ...edge });\n    else if (svcOf(r.source) === service) 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  return {\n    present: true,\n    parses: true,\n    modelled: elements.length > 0,\n    elements,\n    inbound,\n    outbound,\n    expects,\n    instruction:\n      elements.length > 0 ? null : instructionFor(service, \"unmodelled\", expects, servicePath),\n  };\n}\n\n/**\n * The fleet-map instruction, in the three states a landscape can be in.\n *\n * It says the file, the block, and the consequence, in that order. The\n * consequence is the part agents acted on: \"add an element\" reads as tidiness,\n * \"until you do, `loam validate --all` fails and no cross-service check can see\n * this service\" reads as work.\n */\nfunction instructionFor(\n  service: string,\n  state: \"absent\" | \"unparseable\" | \"unmodelled\",\n  expects: string[],\n  servicePath: string,\n): string {\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 elements that already resolve to this\n  // service, so it is empty in every state that produces an instruction. It is\n  // threaded through anyway rather than dropped: the caller computes it once,\n  // and the day an unmodelled service can inherit an edge (a container-level\n  // binding, say) the sentence is already here instead of being noticed missing.\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    return (\n      `architecture/landscape.likec4 exists but does not parse (\\`landscape.invalid\\`), so nothing can be said ` +\n      `about what it already models. Fix the parse errors first — they blind every cross-service check at once — ` +\n      `then make sure it holds ${bind}. ${consequence}`\n    );\n  }\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"]}
+{"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"]}

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

@@ -0,0 +1,81 @@
+/** 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.
+ */
+export const SVC = "<svc>";
+/** The token an example carries where loam has no id to substitute. Short on purpose — see `ExtendPoint`. */
+const PLACEHOLDER = "<your-element-id>";
+/**
+ * Which element an extending `model.likec4` says it is inside — the id, when
+ * the map leaves no doubt, and a placeholder plus the doubt when it does.
+ *
+ * Four answers because the map is in four states and only one of them has an
+ * answer to give. With exactly ONE service-level element resolving to this
+ * service, `extend <that id> {` is the file's first line and printing anything
+ * else makes an agent go and look it up. With NONE, there is nothing to extend
+ * yet — the landscape target below this one is what the agent must do first, and
+ * saying so is what stops it inventing an id and writing a model that cannot
+ * parse. With SEVERAL — `landscape.binding-duplicate`, a real and reported
+ * state — loam must not choose: every element→service join in the fleet picks
+ * one of them arbitrarily, so a brief that named one would be teaching an agent
+ * the arbitrary answer as the right one. And when the map could not be READ
+ * (`modelled === null`) the empty element list is evidence of nothing: "write
+ * the element into the map first" is exactly the instruction that draws a second
+ * box for a service the map already holds, so that arm says the map is
+ * unreadable and asks for no map write at all.
+ */
+export function extendPoint(landscape) {
+    if (landscape.modelled === null) {
+        return {
+            id: PLACEHOLDER,
+            note: "the fleet map (architecture/) does not parse, so loam cannot say which element binds this directory. " +
+                "Fix the map first — the landscape section of this brief names the documents that failed — then write " +
+                "the id of the element that resolves to this service here.",
+        };
+    }
+    const ids = landscape.elements.map((e) => e.id);
+    const [only, ...rest] = ids;
+    if (only === undefined) {
+        return {
+            id: PLACEHOLDER,
+            note: "nothing in the fleet map resolves to this directory yet. Add the element to " +
+                "architecture/landscape.likec4 first — the landscape target below — then write its id here.",
+        };
+    }
+    return { id: rest.length === 0 ? only : `<one of: ${ids.join(", ")}>` };
+}
+/**
+ * An example with its placeholders resolved, and the placeholder's explanation
+ * prepended as a comment when there is one.
+ *
+ * Guarded on the example actually containing `<fqn>`: the note is about that
+ * substitution, and heading an example that never had one with it would answer a
+ * question its reader did not ask.
+ */
+export function exampleFor(example, extend, service) {
+    const body = example.replaceAll(FQN, extend.id).replaceAll(SVC, service);
+    if (extend.note === undefined || !example.includes(FQN))
+        return body;
+    return `${commentLines(`${extend.id} is a placeholder: ${extend.note}`)}\n\n${body}`;
+}
+/** One sentence as `//` lines, wrapped to the width the examples around it are written at. */
+function commentLines(text, width = 76) {
+    const out = [];
+    let line = "//";
+    for (const word of text.trim().split(/\s+/)) {
+        if (line !== "//" && line.length + 1 + word.length > width) {
+            out.push(line);
+            line = `// ${word}`;
+        }
+        else
+            line = `${line} ${word}`;
+    }
+    out.push(line);
+    return out.join("\n");
+}
+//# sourceMappingURL=extend.js.map