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

package/dist/core/brief/brief.js

@@ -0,0 +1,285 @@
+/**
+ * The adoption brief: what an agent needs in order to write one service's
+ * baseline documentation, and what will be checked when it does.
+ *
+ * `adopt` was specified for years as "read the code, emit the C4". It is not
+ * being built, because it cannot be: nothing deterministic reads a legacy
+ * service and says what its architecture MEANS, and a guessed model is worse
+ * than no model — everyone downstream has to re-derive it to know whether to
+ * believe it.
+ *
+ * So loam takes the half of the job that IS deterministic. It states the work
+ * precisely (which files, in which grammar, bound to which existing elements),
+ * it says exactly which checks the result will face, and then it says which
+ * checks do not exist — because everything in that last list is honesty no
+ * validator will ever supply, and an agent that does not know where the checking
+ * stops will assume it never does.
+ *
+ * Nothing here reads code. `sources` in the frontmatter is the only line that
+ * ties the result to a repository, which is why the brief argues for it instead
+ * of merely listing it.
+ */
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { landscapePath } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { specAdoption } from "../repo/repo.js";
+import { entryIs } from "../repo/tree/fs.js";
+import { VALIDATE_CHECKS } from "./checks.js";
+import { UNCHECKED } from "./unchecked.js";
+import { landscapeContext } from "./landscape.js";
+import { landscapeArtifact } from "./map/owed.js";
+import { exampleFor, extendPoint, FQN } from "./map/extend.js";
+import { ARTIFACTS, USECASES_DIR } from "./targets.js";
+import { EXTERNAL_TAG } from "../vocabulary/maturity.js";
+/**
+ * The architecture walk: the order a service is read in, and what each stop is
+ * for.
+ *
+ * The brief said "read the code: entry points, HTTP routes and handlers,
+ * published events, config, deploy manifests, tests" — one sentence, six nouns,
+ * no order and no landing site. What came back matched the sentence: the HTTP
+ * surface documented well, because it is the noun an agent recognises fastest,
+ * and the scheduler, the consumer group and the outbox missing entirely. Not
+ * because they were judged unimportant — because nothing said to go and look,
+ * and every check loam owns is computed from what was written rather than from
+ * what is there. `UNCHECKED` has said COMPLETENESS is unverifiable since the
+ * beginning; that is an argument for stating the sweep, not for leaving it
+ * implied.
+ *
+ * The order is deliberate and it is not the order a reader browses in. Stops 1
+ * and 2 fix the SHAPE of the service — which processes exist at all — before
+ * any surface is enumerated, because an agent that starts at the HTTP routes
+ * has already concluded the service is an API by the time it meets the
+ * scheduler. Everything after them is one surface each.
+ *
+ * `lands` names artifacts rather than describing them, because the two lists
+ * are joined: test/agent-contract.test.ts requires every name here to be a
+ * target the same brief hands over, so a stop can never feed a file nobody was
+ * asked to write.
+ */
+export const WALK = [
+    {
+        where: "the build and dependency manifests — pom.xml, build.gradle, package.json, go.mod, requirements.txt, and whatever the repo's own README calls the build",
+        find: "what this service is built from, and every client library it links against. A broker client, an HTTP client, a database driver: each one is a dependency that has to appear as an edge or a container later, and this list is the only place they are all named at once. A library whose SEMANTICS decide behaviour — a retry budget, a delivery guarantee, a serialization format — is an arch requirement (arch.spec.md), not a fact to leave in your head.",
+        lands: ["model.likec4", "runbook.md", "arch.spec.md"],
+    },
+    {
+        where: "the entry points — main/Application/server bootstrap, the DI or module wiring, and anything the deploy manifests actually start",
+        find: "how many PROCESSES this service is, and what each one is. An API, a worker, a scheduler, a consumer — a service that is three of those and documented as one is the most common way a baseline is wrong, and it is wrong in a shape no later check can see.",
+        lands: ["model.likec4"],
+    },
+    {
+        where: "the HTTP surface — every route, controller, handler and middleware, counted",
+        find: "the operation set, in full, and inside each operation the DECISIONS its code makes: the permission and role checks — each one is a `Requires:` entry, and a name `architecture/permissions.yaml` does not declare yet is a line to ADD to that shared file, never to invent locally — the fields required only when another field is present, the defaults and normalisations applied before anything is stored, the transitions a request is refused for. Count both — operations, and branches per operation — before you write, and say both counts in the hand-back. `api.ungoverned` can tell you an operation you WROTE has no requirement; nothing at all can tell you about the twelve you never wrote down, or about the thirty branches inside the one you did. A guard is not implementation detail: what a service REFUSES is behaviour its caller observes and a test pins, and it is the half of a legacy service that lives only in the code and in one developer's head.",
+        lands: ["openapi.yaml", "spec.md"],
+    },
+    {
+        where: "the message surface — producers, consumers, listener annotations, topic and queue names, the outbox table and its relay",
+        find: "every message this service puts on and takes off the bus, with its direction, and — on the consuming side — the DECISIONS the handler makes about a message before it acts on one. The direction is the half that gets lost: a consumer documented as a producer is a contract the whole fleet then joins against backwards. The guards are the half nobody looks for at all: which messages are filtered out and on what field, what happens to one whose entity has since been deleted, what is idempotency-keyed against a replay, what is dead-lettered rather than retried. Each of those is a scenario, and none of them appears anywhere in the contract — asyncapi.yaml describes the message, never what this service refuses to do with it.",
+        lands: ["asyncapi.yaml", "landscape.likec4"],
+    },
+    {
+        where: "the scheduled and background work — cron entries, timers, retry loops, reconcilers, migrations that run at boot",
+        find: "behaviour no request ever triggers, and the conditions under which it does or does not run. It has requirements like anything else, and it is invisible to every surface above — which is why a baseline written from routes alone describes a service that does half of what it does. Take the decisions with it: which rows a reconciler SELECTS and which it skips, what a retry loop gives up on and after how long, what a migration does when it finds the state it is meant to fix already fixed. A scheduled job documented as 'runs nightly' is a requirement with no behaviour in it.",
+        lands: ["spec.md", "arch.spec.md"],
+    },
+    {
+        where: "the state — datastores, caches, buckets, and the schema or migration directory that says what is in them",
+        find: "what this service OWNS versus what it borrows. Ownership is the fact the C4 is for, and it is the one nobody can reconstruct later from the code without re-reading all of it.",
+        lands: ["model.likec4"],
+    },
+    {
+        where: "the outbound calls — HTTP clients, generated stubs, gRPC channels, and the config that says which host each one points at",
+        find: "who this service calls, and which operation each call names. These become the fleet map's edges; an edge missing here is a dependency the fleet cannot see, and `loam explore` will under-report the blast radius of every future change to the callee. An edge that only configuration attests is PROVISIONAL until the runtime stop: hold it until the deploy manifests confirm nothing switches that client off.",
+        lands: ["landscape.likec4"],
+    },
+    {
+        where: "the runtime — config and env vars, deploy manifests, pipelines, alert rules, dashboards",
+        find: "how it is run and what pages whom. Alerts are the honest source for health.yaml: an SLO nobody agreed to is invention, but an alert that already fires is a fact somebody wrote down. Deployment manifests OVERRIDE configuration files, and they usually live in another repository — go and find them before any dependency that only configuration attests goes in the model, and check for an environment variable that disables the feature. A capability switched off at deploy time is not a dependency, however completely the config wires it: delete its edge and container, and record it in runbook.md's 'configured but not a dependency, and why' list. A manifest read from another repository is named in the runbook's prose — never in `sources`, which may only hold paths of this service's own repository. An EFFECTIVE configuration value behaviour depends on — the timeout the chart sets, the flag that switches a code path — is an arch requirement in arch.spec.md, with a Covers: line naming what it decides; loam holds its coverage even though it can never check the value.",
+        lands: ["runbook.md", "health.yaml", "arch.spec.md"],
+    },
+    {
+        where: "the tests, integration and component ones first",
+        find: "the behaviours somebody already thought worth pinning. This is the PRIMARY source for scenarios, not the last sweep: a behaviour a test already pins is written FROM that test, and the code is read only for what no test covers. A test suite is the only part of a legacy service that states intent rather than mechanism, and a scenario derived from one is the only kind that starts out true. Carry the shape across as well as the content — a parameterised test (`@ParameterizedTest`, `@parametrize`, `test.each`) is one scenario with a table, not one scenario per case. Then say in the hand-back how well this service is covered and how many of its tests became scenarios: that number is the ceiling on what this whole baseline can be worth, and nothing downstream can compute it.",
+        lands: ["spec.md", "arch.spec.md"],
+    },
+];
+/**
+ * The stop that closes the walk. Separate from `WALK` because it is not a place
+ * to go — it is the question asked once the walking is done, and the only
+ * defence against a sweep that felt thorough because the parts it covered were
+ * covered well.
+ */
+export const WALK_CLOSE = "Then list the directories you did NOT open, and say why for each. `loam validate --service <id>`, run inside the service's own repo, reports the same list back as `sources.unwalked` — it compares your `sources` against the files git tracks. A directory you deliberately skipped is a sentence in the hand-back; a directory you skipped without noticing is the gap this walk exists to find.";
+const FRONTMATTER_BRIEF = {
+    fields: {
+        service: "the directory this file lives under, exactly. A mismatch is an error (`frontmatter.field-mismatch`).",
+        status: "`draft`, always. `verified` is a human's word, stamped by `loam vouch --service <id>` run inside the service's own repo — never written by hand.",
+        owner: "the team or person who answers for this service.",
+        sources: "the paths in THIS SERVICE'S repository you actually read to write the document — files and directories only, a directory covering everything beneath it; glob patterns are refused. Not the paths a reader would expect to have been read. This is NOT a reading list for a human: nobody follows these, and nothing about the document asks them to.",
+    },
+    // `vouch_scope` is in this list for a sharper reason than its siblings: the
+    // others are stamps an agent could only forge, while this one is a stamp an
+    // agent could DELETE — and deleting it turns a vouch that read four sections
+    // into one that read the document, on every surface at once.
+    never: ["last_verified", "sources_digest", "content_digest", "sources_files", "vouch_scope"],
+    why: "`sources` is digest input, not a citation. It is the only mechanical tie between this document and the code — everything else loam checks is internal consistency, and a corpus can agree with itself perfectly while describing nothing that exists. `loam validate`, run inside the service's repo, checks every listed path is still there; `loam vouch` hashes their CONTENT so that a later `validate` can say the code has moved since anyone read it. That hash is the entire point, and it is why padding the list costs something real rather than merely being untidy: a path nobody read still gets hashed, so its next change reports as drift in a document it never described, and a path that WAS read and went unlisted moves under the document in silence. Neither failure is visible to a reader; both are decided by whether this list is honest.",
+};
+const NEVER_OVERWRITE = "Do not overwrite an artifact that already exists. Read it, diff your findings against it, and report what disagrees — a document somebody wrote is evidence, and replacing it destroys the only copy of what they knew.";
+/**
+ * Assemble the brief for one service. Reads the docs repo; writes nothing.
+ * `at` overrides where the artifacts are briefed to land — `adopt
+ * --subsystem`'s target inside a group — and is only ever passed for a
+ * service the enumeration does NOT answer: an existing service is briefed
+ * where it already lives, because the brief's one rule is to never overwrite,
+ * and a second address would brief a duplicate.
+ */
+export async function serviceBrief(docsDir, service, at) {
+    const paths = at ?? (await locateServicePaths(docsDir, service));
+    const rel = (abs) => relative(docsDir, abs).split(/[\\/]/).join("/");
+    // Read before the artifact loop, not after it: what the fleet already says
+    // about this service decides whether it owes an API contract at all. The
+    // model path travels with it — located through the enumeration above, never
+    // joined at `services/<id>/` — so the edgeless state can name the calls the
+    // service's own model attests.
+    const landscape = await landscapeContext(docsDir, service, paths);
+    const owesApi = apiExpected(landscape);
+    // The one id the model target's grammar and example are written against,
+    // resolved here because `ARTIFACTS` is static on purpose (a target list that
+    // varied per repository would be a second thing to keep true) and because this
+    // is the only place the fleet map has already been read.
+    const extend = extendPoint(landscape);
+    const targets = [];
+    for (const { key, ...artifact } of ARTIFACTS) {
+        // `adrs/` and `usecases/` are DIRECTORIES, and an empty one is not an
+        // existing artifact — reporting it as present would tell the agent to diff
+        // against nothing, and for `usecases/` it would also tell the agent an
+        // optional slot was already taken.
+        //
+        // `usecases/` is the one target with no `ServicePaths` entry, and that is
+        // deliberate rather than an omission: nothing loam checks JOINS on that
+        // path. The slot a service's flows are graded out of is its whole LikeC4
+        // project (`core/usecases/service/flows.ts` reads every `.likec4` under the
+        // directory), so `usecases/<name>.likec4` is a convention this brief
+        // publishes, not a path a writer writes — and `targets.ts` is where a
+        // convention belongs.
+        const ext = key === "adrsDir" ? ".md" : key === "usecasesDir" ? ".likec4" : null;
+        const at = key === "usecasesDir" ? join(paths.dir, USECASES_DIR) : paths[key];
+        const exists = ext === null ? existsSync(at) : await hasEntry(at, ext);
+        const partial = key === "spec" && exists && (await specAdoption(at)) === "partial";
+        targets.push({
+            ...artifact,
+            ...(partial ? { partial: true } : {}),
+            ...(key === "openapi" ? { required: owesApi } : {}),
+            // Every `<fqn>` in the model target, replaced by the element this service
+            // actually extends. The placeholder is left literal in `targets.ts` — the
+            // brief is handed to an agent that will WRITE the file, and
+            // `extend <fqn> {` copied verbatim is a document that does not parse.
+            shape: artifact.shape.map((rule) => rule.replaceAll(FQN, extend.id)),
+            ...(artifact.example === undefined ? {} : { example: exampleFor(artifact.example, extend, service) }),
+            path: ext === null ? rel(at) : `${rel(at)}/`,
+            exists,
+            action: exists ? "diff" : "create",
+        });
+    }
+    // The eighth target is the fleet map, and it is conditional on TWO facts: an
+    // element resolving to the service, and an edge touching it. A service the
+    // landscape already draws AND reaches owes it nothing, and briefing an edit
+    // there would invite an agent to draw a second box for a service that has
+    // one. A service with a box and no edge — what `loam seed` leaves for every
+    // service nobody listed under `calls:` — owes it the edges, and until
+    // 2026-09-03 element existence alone read as "the map is complete" here, so
+    // the brief declared the map finished for exactly the services it had not
+    // reached. Everything else about the target is unconditional — the file is
+    // shared, so `action` is `edit` whenever it exists and `create` only for the
+    // very first service of a brand-new docs repo.
+    //
+    // `modelled === false` and not `!== true`: `null` is "loam could not read the
+    // map", and it fell through the same branch as "the map genuinely draws
+    // nothing for this service". The brief then handed over the UNDRAWN target —
+    // whose shape rule is "add one top-level element bound to its directory" and
+    // whose example is a block to splice — for services the map already declares
+    // and binds, and an agent that spliced it earned `landscape.binding-duplicate`
+    // for doing exactly what the brief asked. With the map unreadable there is no
+    // write to ask for; `landscape.instruction` carries the whole answer and names
+    // the documents that failed.
+    if (landscape.modelled === false || landscape.touched === false) {
+        targets.push({
+            ...landscapeArtifact({
+                service,
+                expects: landscape.expects,
+                present: landscape.present,
+                servicePath: rel(paths.dir),
+                // The existing element's id, in the edgeless state only: it switches
+                // the example from a block to edges on that element.
+                // …and whether it is `#external`, which decides what the shape rule may
+                // promise: `landscape.service-isolated` never fires on such an element.
+                ...(landscape.touched === false && landscape.elements[0] !== undefined
+                    ? { elementId: landscape.elements[0].id, external: landscape.elements[0].tags.includes(EXTERNAL_TAG) }
+                    : {}),
+                attested: landscape.attested,
+            }),
+            path: rel(landscapePath(docsDir)),
+            exists: landscape.present,
+            action: landscape.present ? "edit" : "create",
+        });
+    }
+    return {
+        service,
+        docsDir,
+        path: rel(paths.dir),
+        targets,
+        walk: WALK,
+        walkClose: WALK_CLOSE,
+        landscape,
+        frontmatter: FRONTMATTER_BRIEF,
+        checks: VALIDATE_CHECKS,
+        unchecked: UNCHECKED,
+        rule: NEVER_OVERWRITE,
+    };
+}
+/**
+ * Does this directory already hold an artifact of the given extension? The
+ * "exists" question for the two DIRECTORY targets — `adrs/` (`.md`) and
+ * `usecases/` (`.likec4`) — where an empty or absent directory is the same
+ * answer, because neither is something to diff against.
+ */
+async function hasEntry(dir, ext) {
+    if (!existsSync(dir))
+        return false;
+    const entries = await readdir(dir, { withFileTypes: true });
+    // `entryIs` for the symlink case: a Dirent never follows one, so `isFile()`
+    // is false for a symlinked ADR and the directory would read as empty — the
+    // same rule `services/` and `features/` are enumerated by.
+    return entries.some((e) => e.name.endsWith(ext) && entryIs(dir, e, "file"));
+}
+/**
+ * Does the fleet expect an API of this service?
+ *
+ * The brief marked `openapi.yaml` required unconditionally, and printed the
+ * absence as `MISSING` in capitals — while `loam validate` and `loam list`
+ * derive the opposite from the same landscape (`service.no-openapi` stays quiet
+ * when nothing calls the service, and `list`'s maturity ladder stops demanding
+ * a contract). For a UI, a worker or a cron the brief was therefore telling an
+ * agent to INVENT an API contract into the source of truth — the one class of
+ * guess this whole module exists to refuse, and the one the brief itself names
+ * in `openapi.yaml`'s shape rules (`ARTIFACTS`, targets.ts).
+ *
+ * Positive evidence only, exactly as `list` reads it: a landscape that is
+ * absent or unreadable proves nothing about who calls this service, so the
+ * contract is still owed. `expects` is the ops on inbound edges, which is
+ * `list`'s `called` set seen from one service.
+ *
+ * `callersKnown` and not `parses`, because since W4 `parses` answers about the
+ * whole `architecture/` PROJECT: a broken palette or use case beside a landscape
+ * loam reads perfectly made this discard the map and demand an OpenAPI contract
+ * of a browser UI — inventing an API into the source of truth, which is the one
+ * class of guess this module exists to refuse. `callersKnown` is the narrower
+ * fact this question actually needs, and it is the one `list` and `context` read.
+ */
+function apiExpected(landscape) {
+    return !landscape.callersKnown || landscape.expects.length > 0;
+}
+//# sourceMappingURL=brief.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brief.js","sourceRoot":"","sources":["../../../src/core/brief/brief.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The adoption brief: what an agent needs in order to write one service's\n * baseline documentation, and what will be checked when it does.\n *\n * `adopt` was specified for years as \"read the code, emit the C4\". It is not\n * being built, because it cannot be: nothing deterministic reads a legacy\n * service and says what its architecture MEANS, and a guessed model is worse\n * than no model — everyone downstream has to re-derive it to know whether to\n * believe it.\n *\n * So loam takes the half of the job that IS deterministic. It states the work\n * precisely (which files, in which grammar, bound to which existing elements),\n * it says exactly which checks the result will face, and then it says which\n * checks do not exist — because everything in that last list is honesty no\n * validator will ever supply, and an agent that does not know where the checking\n * stops will assume it never does.\n *\n * Nothing here reads code. `sources` in the frontmatter is the only line that\n * ties the result to a repository, which is why the brief argues for it instead\n * of merely listing it.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join, relative } from \"node:path\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { landscapePath, type ServicePaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { specAdoption } from \"../repo/repo.js\";\nimport { entryIs } from \"../repo/tree/fs.js\";\nimport { VALIDATE_CHECKS, type BriefCheck } from \"./checks.js\";\nimport { UNCHECKED } from \"./unchecked.js\";\nimport { landscapeContext, type LandscapeContext } from \"./landscape.js\";\nimport { landscapeArtifact } from \"./map/owed.js\";\nimport { exampleFor, extendPoint, FQN } from \"./map/extend.js\";\nimport { ARTIFACTS, USECASES_DIR, type BriefTarget } from \"./targets.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { EXTERNAL_TAG } from \"../vocabulary/maturity.js\";\n\n/* ------------------------------------------------------------------ */\n/* The walk — what to read, in what order, and where each finding lands */\n/* ------------------------------------------------------------------ */\n\nexport interface WalkStop {\n  /** What to open, named as a thing to go and find rather than a file name. */\n  where: string;\n  /** What to take out of it. */\n  find: string;\n  /** The artifacts this stop feeds, by `artifact` name from `targets[]`. */\n  lands: string[];\n}\n\n/**\n * The architecture walk: the order a service is read in, and what each stop is\n * for.\n *\n * The brief said \"read the code: entry points, HTTP routes and handlers,\n * published events, config, deploy manifests, tests\" — one sentence, six nouns,\n * no order and no landing site. What came back matched the sentence: the HTTP\n * surface documented well, because it is the noun an agent recognises fastest,\n * and the scheduler, the consumer group and the outbox missing entirely. Not\n * because they were judged unimportant — because nothing said to go and look,\n * and every check loam owns is computed from what was written rather than from\n * what is there. `UNCHECKED` has said COMPLETENESS is unverifiable since the\n * beginning; that is an argument for stating the sweep, not for leaving it\n * implied.\n *\n * The order is deliberate and it is not the order a reader browses in. Stops 1\n * and 2 fix the SHAPE of the service — which processes exist at all — before\n * any surface is enumerated, because an agent that starts at the HTTP routes\n * has already concluded the service is an API by the time it meets the\n * scheduler. Everything after them is one surface each.\n *\n * `lands` names artifacts rather than describing them, because the two lists\n * are joined: test/agent-contract.test.ts requires every name here to be a\n * target the same brief hands over, so a stop can never feed a file nobody was\n * asked to write.\n */\nexport const WALK: WalkStop[] = [\n  {\n    where: \"the build and dependency manifests — pom.xml, build.gradle, package.json, go.mod, requirements.txt, and whatever the repo's own README calls the build\",\n    find: \"what this service is built from, and every client library it links against. A broker client, an HTTP client, a database driver: each one is a dependency that has to appear as an edge or a container later, and this list is the only place they are all named at once. A library whose SEMANTICS decide behaviour — a retry budget, a delivery guarantee, a serialization format — is an arch requirement (arch.spec.md), not a fact to leave in your head.\",\n    lands: [\"model.likec4\", \"runbook.md\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the entry points — main/Application/server bootstrap, the DI or module wiring, and anything the deploy manifests actually start\",\n    find: \"how many PROCESSES this service is, and what each one is. An API, a worker, a scheduler, a consumer — a service that is three of those and documented as one is the most common way a baseline is wrong, and it is wrong in a shape no later check can see.\",\n    lands: [\"model.likec4\"],\n  },\n  {\n    where: \"the HTTP surface — every route, controller, handler and middleware, counted\",\n    find: \"the operation set, in full, and inside each operation the DECISIONS its code makes: the permission and role checks — each one is a `Requires:` entry, and a name `architecture/permissions.yaml` does not declare yet is a line to ADD to that shared file, never to invent locally — the fields required only when another field is present, the defaults and normalisations applied before anything is stored, the transitions a request is refused for. Count both — operations, and branches per operation — before you write, and say both counts in the hand-back. `api.ungoverned` can tell you an operation you WROTE has no requirement; nothing at all can tell you about the twelve you never wrote down, or about the thirty branches inside the one you did. A guard is not implementation detail: what a service REFUSES is behaviour its caller observes and a test pins, and it is the half of a legacy service that lives only in the code and in one developer's head.\",\n    lands: [\"openapi.yaml\", \"spec.md\"],\n  },\n  {\n    where: \"the message surface — producers, consumers, listener annotations, topic and queue names, the outbox table and its relay\",\n    find: \"every message this service puts on and takes off the bus, with its direction, and — on the consuming side — the DECISIONS the handler makes about a message before it acts on one. The direction is the half that gets lost: a consumer documented as a producer is a contract the whole fleet then joins against backwards. The guards are the half nobody looks for at all: which messages are filtered out and on what field, what happens to one whose entity has since been deleted, what is idempotency-keyed against a replay, what is dead-lettered rather than retried. Each of those is a scenario, and none of them appears anywhere in the contract — asyncapi.yaml describes the message, never what this service refuses to do with it.\",\n    lands: [\"asyncapi.yaml\", \"landscape.likec4\"],\n  },\n  {\n    where: \"the scheduled and background work — cron entries, timers, retry loops, reconcilers, migrations that run at boot\",\n    find: \"behaviour no request ever triggers, and the conditions under which it does or does not run. It has requirements like anything else, and it is invisible to every surface above — which is why a baseline written from routes alone describes a service that does half of what it does. Take the decisions with it: which rows a reconciler SELECTS and which it skips, what a retry loop gives up on and after how long, what a migration does when it finds the state it is meant to fix already fixed. A scheduled job documented as 'runs nightly' is a requirement with no behaviour in it.\",\n    lands: [\"spec.md\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the state — datastores, caches, buckets, and the schema or migration directory that says what is in them\",\n    find: \"what this service OWNS versus what it borrows. Ownership is the fact the C4 is for, and it is the one nobody can reconstruct later from the code without re-reading all of it.\",\n    lands: [\"model.likec4\"],\n  },\n  {\n    where: \"the outbound calls — HTTP clients, generated stubs, gRPC channels, and the config that says which host each one points at\",\n    find: \"who this service calls, and which operation each call names. These become the fleet map's edges; an edge missing here is a dependency the fleet cannot see, and `loam explore` will under-report the blast radius of every future change to the callee. An edge that only configuration attests is PROVISIONAL until the runtime stop: hold it until the deploy manifests confirm nothing switches that client off.\",\n    lands: [\"landscape.likec4\"],\n  },\n  {\n    where: \"the runtime — config and env vars, deploy manifests, pipelines, alert rules, dashboards\",\n    find: \"how it is run and what pages whom. Alerts are the honest source for health.yaml: an SLO nobody agreed to is invention, but an alert that already fires is a fact somebody wrote down. Deployment manifests OVERRIDE configuration files, and they usually live in another repository — go and find them before any dependency that only configuration attests goes in the model, and check for an environment variable that disables the feature. A capability switched off at deploy time is not a dependency, however completely the config wires it: delete its edge and container, and record it in runbook.md's 'configured but not a dependency, and why' list. A manifest read from another repository is named in the runbook's prose — never in `sources`, which may only hold paths of this service's own repository. An EFFECTIVE configuration value behaviour depends on — the timeout the chart sets, the flag that switches a code path — is an arch requirement in arch.spec.md, with a Covers: line naming what it decides; loam holds its coverage even though it can never check the value.\",\n    lands: [\"runbook.md\", \"health.yaml\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the tests, integration and component ones first\",\n    find: \"the behaviours somebody already thought worth pinning. This is the PRIMARY source for scenarios, not the last sweep: a behaviour a test already pins is written FROM that test, and the code is read only for what no test covers. A test suite is the only part of a legacy service that states intent rather than mechanism, and a scenario derived from one is the only kind that starts out true. Carry the shape across as well as the content — a parameterised test (`@ParameterizedTest`, `@parametrize`, `test.each`) is one scenario with a table, not one scenario per case. Then say in the hand-back how well this service is covered and how many of its tests became scenarios: that number is the ceiling on what this whole baseline can be worth, and nothing downstream can compute it.\",\n    lands: [\"spec.md\", \"arch.spec.md\"],\n  },\n];\n\n/**\n * The stop that closes the walk. Separate from `WALK` because it is not a place\n * to go — it is the question asked once the walking is done, and the only\n * defence against a sweep that felt thorough because the parts it covered were\n * covered well.\n */\nexport const WALK_CLOSE =\n  \"Then list the directories you did NOT open, and say why for each. `loam validate --service <id>`, run inside the service's own repo, reports the same list back as `sources.unwalked` — it compares your `sources` against the files git tracks. A directory you deliberately skipped is a sentence in the hand-back; a directory you skipped without noticing is the gap this walk exists to find.\";\n\n/* ------------------------------------------------------------------ */\n/* The frontmatter                                                     */\n/* ------------------------------------------------------------------ */\n\nexport interface FrontmatterBrief {\n  /** Field -> what to write in it. */\n  fields: Record<string, string>;\n  /** Fields to leave alone entirely. */\n  never: string[];\n  /** Why `sources` carries the weight. */\n  why: string;\n}\n\nconst FRONTMATTER_BRIEF: FrontmatterBrief = {\n  fields: {\n    service: \"the directory this file lives under, exactly. A mismatch is an error (`frontmatter.field-mismatch`).\",\n    status:\n      \"`draft`, always. `verified` is a human's word, stamped by `loam vouch --service <id>` run inside the service's own repo — never written by hand.\",\n    owner: \"the team or person who answers for this service.\",\n    sources:\n      \"the paths in THIS SERVICE'S repository you actually read to write the document — files and directories only, a directory covering everything beneath it; glob patterns are refused. Not the paths a reader would expect to have been read. This is NOT a reading list for a human: nobody follows these, and nothing about the document asks them to.\",\n  },\n  // `vouch_scope` is in this list for a sharper reason than its siblings: the\n  // others are stamps an agent could only forge, while this one is a stamp an\n  // agent could DELETE — and deleting it turns a vouch that read four sections\n  // into one that read the document, on every surface at once.\n  never: [\"last_verified\", \"sources_digest\", \"content_digest\", \"sources_files\", \"vouch_scope\"],\n  why:\n    \"`sources` is digest input, not a citation. It is the only mechanical tie between this document and the code — everything else loam checks is internal consistency, and a corpus can agree with itself perfectly while describing nothing that exists. `loam validate`, run inside the service's repo, checks every listed path is still there; `loam vouch` hashes their CONTENT so that a later `validate` can say the code has moved since anyone read it. That hash is the entire point, and it is why padding the list costs something real rather than merely being untidy: a path nobody read still gets hashed, so its next change reports as drift in a document it never described, and a path that WAS read and went unlisted moves under the document in silence. Neither failure is visible to a reader; both are decided by whether this list is honest.\",\n};\n\nexport interface Brief {\n  service: string;\n  /** Absolute docs repo root — the anchor the repo-relative paths hang off. */\n  docsDir: DocsDir;\n  /** Repo-relative path of services/<id>/. */\n  path: string;\n  targets: BriefTarget[];\n  /** The order to read the service in, and what each stop feeds. */\n  walk: WalkStop[];\n  /** The question the walk ends on — see `WALK_CLOSE`. */\n  walkClose: string;\n  landscape: LandscapeContext;\n  frontmatter: FrontmatterBrief;\n  checks: BriefCheck[];\n  unchecked: string[];\n  /** The one instruction that outranks the rest. */\n  rule: string;\n}\n\nconst NEVER_OVERWRITE =\n  \"Do not overwrite an artifact that already exists. Read it, diff your findings against it, and report what disagrees — a document somebody wrote is evidence, and replacing it destroys the only copy of what they knew.\";\n\n/**\n * Assemble the brief for one service. Reads the docs repo; writes nothing.\n * `at` overrides where the artifacts are briefed to land — `adopt\n * --subsystem`'s target inside a group — and is only ever passed for a\n * service the enumeration does NOT answer: an existing service is briefed\n * where it already lives, because the brief's one rule is to never overwrite,\n * and a second address would brief a duplicate.\n */\nexport async function serviceBrief(\n  docsDir: DocsDir,\n  service: PathableService,\n  at?: ServicePaths,\n): Promise<Brief> {\n  const paths = at ?? (await locateServicePaths(docsDir, service));\n  const rel = (abs: string): string => relative(docsDir, abs).split(/[\\\\/]/).join(\"/\");\n\n  // Read before the artifact loop, not after it: what the fleet already says\n  // about this service decides whether it owes an API contract at all. The\n  // model path travels with it — located through the enumeration above, never\n  // joined at `services/<id>/` — so the edgeless state can name the calls the\n  // service's own model attests.\n  const landscape = await landscapeContext(docsDir, service, paths);\n  const owesApi = apiExpected(landscape);\n\n  // The one id the model target's grammar and example are written against,\n  // resolved here because `ARTIFACTS` is static on purpose (a target list that\n  // varied per repository would be a second thing to keep true) and because this\n  // is the only place the fleet map has already been read.\n  const extend = extendPoint(landscape);\n\n  const targets: BriefTarget[] = [];\n  for (const { key, ...artifact } of ARTIFACTS) {\n    // `adrs/` and `usecases/` are DIRECTORIES, and an empty one is not an\n    // existing artifact — reporting it as present would tell the agent to diff\n    // against nothing, and for `usecases/` it would also tell the agent an\n    // optional slot was already taken.\n    //\n    // `usecases/` is the one target with no `ServicePaths` entry, and that is\n    // deliberate rather than an omission: nothing loam checks JOINS on that\n    // path. The slot a service's flows are graded out of is its whole LikeC4\n    // project (`core/usecases/service/flows.ts` reads every `.likec4` under the\n    // directory), so `usecases/<name>.likec4` is a convention this brief\n    // publishes, not a path a writer writes — and `targets.ts` is where a\n    // convention belongs.\n    const ext = key === \"adrsDir\" ? \".md\" : key === \"usecasesDir\" ? \".likec4\" : null;\n    const at = key === \"usecasesDir\" ? join(paths.dir, USECASES_DIR) : paths[key];\n    const exists = ext === null ? existsSync(at) : await hasEntry(at, ext);\n    const partial = key === \"spec\" && exists && (await specAdoption(at)) === \"partial\";\n    targets.push({\n      ...artifact,\n      ...(partial ? { partial: true as const } : {}),\n      ...(key === \"openapi\" ? { required: owesApi } : {}),\n      // Every `<fqn>` in the model target, replaced by the element this service\n      // actually extends. The placeholder is left literal in `targets.ts` — the\n      // brief is handed to an agent that will WRITE the file, and\n      // `extend <fqn> {` copied verbatim is a document that does not parse.\n      shape: artifact.shape.map((rule) => rule.replaceAll(FQN, extend.id)),\n      ...(artifact.example === undefined ? {} : { example: exampleFor(artifact.example, extend, service) }),\n      path: ext === null ? rel(at) : `${rel(at)}/`,\n      exists,\n      action: exists ? \"diff\" : \"create\",\n    });\n  }\n\n  // The eighth target is the fleet map, and it is conditional on TWO facts: an\n  // element resolving to the service, and an edge touching it. A service the\n  // landscape already draws AND reaches owes it nothing, and briefing an edit\n  // there would invite an agent to draw a second box for a service that has\n  // one. A service with a box and no edge — what `loam seed` leaves for every\n  // service nobody listed under `calls:` — owes it the edges, and until\n  // 2026-09-03 element existence alone read as \"the map is complete\" here, so\n  // the brief declared the map finished for exactly the services it had not\n  // reached. Everything else about the target is unconditional — the file is\n  // shared, so `action` is `edit` whenever it exists and `create` only for the\n  // very first service of a brand-new docs repo.\n  //\n  // `modelled === false` and not `!== true`: `null` is \"loam could not read the\n  // map\", and it fell through the same branch as \"the map genuinely draws\n  // nothing for this service\". The brief then handed over the UNDRAWN target —\n  // whose shape rule is \"add one top-level element bound to its directory\" and\n  // whose example is a block to splice — for services the map already declares\n  // and binds, and an agent that spliced it earned `landscape.binding-duplicate`\n  // for doing exactly what the brief asked. With the map unreadable there is no\n  // write to ask for; `landscape.instruction` carries the whole answer and names\n  // the documents that failed.\n  if (landscape.modelled === false || landscape.touched === false) {\n    targets.push({\n      ...landscapeArtifact({\n        service,\n        expects: landscape.expects,\n        present: landscape.present,\n        servicePath: rel(paths.dir),\n        // The existing element's id, in the edgeless state only: it switches\n        // the example from a block to edges on that element.\n        // …and whether it is `#external`, which decides what the shape rule may\n        // promise: `landscape.service-isolated` never fires on such an element.\n        ...(landscape.touched === false && landscape.elements[0] !== undefined\n          ? { elementId: landscape.elements[0].id, external: landscape.elements[0].tags.includes(EXTERNAL_TAG) }\n          : {}),\n        attested: landscape.attested,\n      }),\n      path: rel(landscapePath(docsDir)),\n      exists: landscape.present,\n      action: landscape.present ? \"edit\" : \"create\",\n    });\n  }\n\n  return {\n    service,\n    docsDir,\n    path: rel(paths.dir),\n    targets,\n    walk: WALK,\n    walkClose: WALK_CLOSE,\n    landscape,\n    frontmatter: FRONTMATTER_BRIEF,\n    checks: VALIDATE_CHECKS,\n    unchecked: UNCHECKED,\n    rule: NEVER_OVERWRITE,\n  };\n}\n\n/**\n * Does this directory already hold an artifact of the given extension? The\n * \"exists\" question for the two DIRECTORY targets — `adrs/` (`.md`) and\n * `usecases/` (`.likec4`) — where an empty or absent directory is the same\n * answer, because neither is something to diff against.\n */\nasync function hasEntry(dir: string, ext: string): Promise<boolean> {\n  if (!existsSync(dir)) return false;\n  const entries = await readdir(dir, { withFileTypes: true });\n  // `entryIs` for the symlink case: a Dirent never follows one, so `isFile()`\n  // is false for a symlinked ADR and the directory would read as empty — the\n  // same rule `services/` and `features/` are enumerated by.\n  return entries.some((e) => e.name.endsWith(ext) && entryIs(dir, e, \"file\"));\n}\n\n/**\n * Does the fleet expect an API of this service?\n *\n * The brief marked `openapi.yaml` required unconditionally, and printed the\n * absence as `MISSING` in capitals — while `loam validate` and `loam list`\n * derive the opposite from the same landscape (`service.no-openapi` stays quiet\n * when nothing calls the service, and `list`'s maturity ladder stops demanding\n * a contract). For a UI, a worker or a cron the brief was therefore telling an\n * agent to INVENT an API contract into the source of truth — the one class of\n * guess this whole module exists to refuse, and the one the brief itself names\n * in `openapi.yaml`'s shape rules (`ARTIFACTS`, targets.ts).\n *\n * Positive evidence only, exactly as `list` reads it: a landscape that is\n * absent or unreadable proves nothing about who calls this service, so the\n * contract is still owed. `expects` is the ops on inbound edges, which is\n * `list`'s `called` set seen from one service.\n *\n * `callersKnown` and not `parses`, because since W4 `parses` answers about the\n * whole `architecture/` PROJECT: a broken palette or use case beside a landscape\n * loam reads perfectly made this discard the map and demand an OpenAPI contract\n * of a browser UI — inventing an API into the source of truth, which is the one\n * class of guess this module exists to refuse. `callersKnown` is the narrower\n * fact this question actually needs, and it is the one `list` and `context` read.\n */\nfunction apiExpected(landscape: LandscapeContext): boolean {\n  return !landscape.callersKnown || landscape.expects.length > 0;\n}\n"]}