@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/brief/landscape.js

@@ -0,0 +1,273 @@
+/**
+ * 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 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 { 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 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.
+ */
+const LOAM_TAGS = new Set(GRADED_TAGS);
+/**
+ * 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.
+ */
+function foreignTagsOf(elements) {
+    const unread = (t) => !LOAM_TAGS.has(t) && !t.startsWith(OBLIGATION_TAG_PREFIX);
+    return [...new Set(elements.flatMap((e) => e.tags))].filter(unread);
+}
+/**
+ * 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.
+ *
+ * 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, 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({ ...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.
+    //
+    // `known`: 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.
+    const known = new Set(await enumeratedServiceIds(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,
+    }));
+    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 (mine(r.target))
+            inbound.push({ from: svcOf(r.source), ...edge });
+        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,
+        callersKnown: true,
+        modelled,
+        elements,
+        inbound,
+        outbound,
+        expects,
+        touched,
+        attested,
+        instruction,
+    };
+}
+/**
+ * The operations the fleet already calls on this service, read off the landscape
+ * FILE alone — `null` when that file cannot be read either.
+ *
+ * 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 `[]`.
+ */
+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)];
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=landscape.js.map

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

@@ -0,0 +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 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

@@ -0,0 +1,84 @@
+/** 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 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`. */
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"extend.js","sourceRoot":"","sources":["../../../../src/core/brief/map/extend.ts"],"names":[],"mappings":"AAiBA,uFAAuF;AACvF,MAAM,CAAC,MAAM,GAAG,GAAG,OAAO,CAAC;AAC3B;;;;;;;;;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"]}