@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

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

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

package/dist/core/brief/unchecked.js

@@ -22,15 +22,25 @@ export const UNCHECKED = [
     // grades their absence, and the failure this comment records — agents
     // learning that a views block is owed to loam — is the one rule 26 is
     // written to prevent recurring.
-    "Whether model.likec4 declares a `views { ... }` block, or any view at all — and nothing in loam ever will. What loam reads, when a `dynamic view` IS present, is only what its author declared: the view's tags and its ordered steps. It computes no view and renders nothing, and it never grades a model for lacking one — a fleet that draws no diagrams owes loam no views block, today or ever. Views belong to LikeC4's own renderer: write them if you want diagrams, and read them with `npx likec4 start <dir>` pointed at ONE directory — `services/<id>` for a service model, the docs repo root for the fleet map (`likec4.config.json` scopes that root project to `architecture/`). The renderer merges every `.likec4` file it is given into one model, and loam parses each of them alone, so each declares its own `specification` block: point it at a directory holding two of them and every declaration reads as a duplicate. Scope your views too — computing a view is superlinear in the number of edges, and an `include *` over `architecture/landscape.likec4` is the expensive one, because that file holds every call in the fleet.",
+    "Whether model.likec4 declares a `views { ... }` block, or any view at all — and nothing in loam ever will. What loam reads, when a `dynamic view` IS present — in the fleet map, or in this service's own project once a view there carries `#req-` — is only what its author declared: the view's tags and its ordered steps. It computes no view and renders nothing, and it never grades a model for lacking one — a fleet that draws no diagrams owes loam no views block, today or ever. Views belong to LikeC4's own renderer: write them if you want diagrams, and read them with `npx likec4 start` at the docs repo root. The root project holds `architecture/` AND every model that EXTENDS the map, so a model written the way this brief asks for it renders there beside the fleet map with no second file to write — one project, one entry in the renderer's picker. The exception is a model that declares its own `specification` block and is therefore parsed alone: its kinds would be duplicates inside the root project, so its directory is excluded there and its own `services/<id>/likec4.config.json` — written by `loam subsystem sync`, loam's file and never yours — makes it a project of its own. A feature's delta.likec4 is the one document always pointed at alone (`npx likec4 start features/<FEAT>`), because it re-declares the landscape's identifiers and carries a `specification` block of its own. Scope your views too — computing a view is superlinear in the number of edges, and an `include *` over `architecture/landscape.likec4` is the expensive one, because that file holds every call in the fleet.",
     // The readability half of the entry above. They are separate entries because
     // the failures are: one is a view that takes minutes to compute, the other is
     // a view that computes instantly and cannot be read. A fleet acquires the
     // second one the day its second service starts publishing, and every service
     // after that makes it worse by exactly one edge — which is why it arrives as
     // a surprise on a map that was fine last quarter.
-    "Whether the fleet map is LEGIBLE — nothing in loam draws it, so nothing in loam notices. The shape that goes first is a shared broker: Kafka, a bus, a gateway, drawn as ONE element, is the node every service in the fleet points at, and a view over it is a star with sixty spokes. Model the TOPIC rather than the broker — `paymentEvents = topic 'payment.events'` nested inside the broker's element, with the edges pointing at `kafka.paymentEvents` — and one hub of degree sixty becomes twelve of degree five, which is also the truer model: the contract a producer and a consumer share is the topic, never the broker. Declare `element topic { #external, style { shape queue } }` in the `specification` block and give the nested elements that kind: LikeC4 does not inherit tags, so a topic under an `#external` broker is NOT external itself and `loam validate --all` asks for a `services/payment.events/` nobody owes (`landscape.service-undocumented`). Then scope the views, which is where the rest of the legibility lives: `exclude element.tag = #external` keeps the fleet overview to the calls between our own services, and a second view over the broker draws the event spine on its own.",
-    "Whether the model has exactly ONE top-level element for the service, with its containers nested inside. Five top-level boxes for one service parse, validate and bind exactly as well as one — and then the fleet map, which joins elements to directories, has five candidates for the same service and no way to say which is wrong.",
+    "Whether the fleet map is LEGIBLE — nothing in loam draws it, so nothing in loam notices. The shape that goes first is a shared broker: Kafka, a bus, a gateway, drawn as ONE element, is the node every service in the fleet points at, and a view over it is a star with sixty spokes. Model the TOPIC rather than the broker — `paymentEvents = topic 'payment.events'` nested inside the broker's element, with the edges pointing at `kafka.paymentEvents` — and one hub of degree sixty becomes twelve of degree five, which is also the truer model: the contract a producer and a consumer share is the topic, never the broker. Declare `element topic { style { shape queue } }` in the `specification` block and give the nested elements that kind: loam reads `database`, `queue`, `topic`, `cache` and `bucket` as infrastructure rather than as candidate services, so a topic drawn this way is out of the service census and nobody is asked for a `services/payment.events/` (the same element spelled `container` earns `landscape.service-undocumented`). Adding `#external` to that kind is now a VIEW choice — LikeC4 does not inherit tags, so a topic under an `#external` broker is not external itself, and tagging the kind is what puts the topics behind the `exclude` below — not a way to silence a check. Then scope the views, which is where the rest of the legibility lives: `exclude element.tag = #external` keeps the fleet overview to the calls between our own services, and a second view over the broker draws the event spine on its own.",
+    // The third view entry, and the one docs/DESIGN.md rule 26 makes permanent:
+    // what a rendered view SHOWS is never computed, so whether an adopted service
+    // is on the picture is a fact loam cannot have. It is here rather than a
+    // check because each of the three ways to vanish is either the fleet's own
+    // vocabulary (a placeholder tag `loam seed` never writes), a static view's
+    // `include` predicates (unread by rule), or LikeC4's semantics — and a
+    // warning that is right once and noise forty times is the warning somebody
+    // silences. The brief NAMES the element's unread tags (landscape.ts); this
+    // entry says what nothing will ever do with them.
+    "Whether an adopted service is VISIBLE on the fleet map, which is a different state from being drawn on it. Three things make a documented, bound, edged service disappear, and no check names any of them. A placeholder tag somebody put on the element before adoption — `#provisional`, or whatever your fleet uses to mean drawn-ahead-of-adoption — survives adoption untouched: loam's `seed` writes no such tag, loam reads none, and a fleet view written `exclude element.tag = #<that>` keeps hiding the service until a human removes it, so clearing it is part of the landscape edit. A curated view that lists its members by id (`include paymentService, billingService`) gains nothing by itself. And `include *` shows top-level elements only: once services nest inside a boundary element — the shape loam's own generated subsystem views draw a box around — a fleet view written that way collapses to the boundary and shows no service at all, and needs `include <boundary>.**` (LikeC4's semantics, not loam's). Adopted and visible are two states; only the second is yours to make, and nothing here can tell you which one you are in.",
+    "Whether the model has exactly ONE top-level element for the service, with its containers nested inside — which is a question only for a model that declares its own `specification` and is parsed alone. Five top-level boxes for one service parse, validate and bind exactly as well as one there, and then the fleet map, which joins elements to directories, has five candidates for the same service and no way to say which is wrong. A model that EXTENDS the map cannot get into that state by accident: it opens one element, the map's, and anything it declares beside that element is `c4.element-unowned` — which is the same rule enforced instead of stated.",
     "Whether the model is the architecture the code actually has. loam parses model.likec4; it never reads a line of the service.",
     "Whether a requirement is TRUE of the service. `loam validate` checks that a requirement has a scenario, never that either one describes real behaviour.",
     "Whether the scenarios are acceptance criteria somebody could test, or the requirement restated in Given/When/Then.",
@@ -38,6 +48,7 @@ export const UNCHECKED = [
     "Whether the runbook's steps work, or the health.yaml SLOs are numbers anyone agreed to.",
     "Whether an arch scenario really exercises what its `Covers:` line names. The entries are resolved against the model and health.yaml — never against code, tests, dashboards or alert rules.",
     "Whether an ADR records a decision that was made, or one reconstructed afterwards to justify the code.",
+    "Whether the DEPLOYMENT model is the topology the fleet actually runs. Every join over it is between documents: `instanceOf` resolves against the C4 model, a `#obl-` tag resolves against the obligation vocabulary, and a `Covers: node:` entry resolves against the nodes the map declares. Nothing here knows whether the second cluster exists, whether it is reachable, whether replication is configured, or whether it holds the data a requirement claims — and no check counts datacenters, because how many a service needs is an architectural decision the fleet makes and writes down as a requirement, never one loam evaluates.",
     "COMPLETENESS. Forty behaviours documented as one requirement passes every check loam has. So does a service with one endpoint documented out of thirty.",
     "REPRODUCIBILITY — the bar the artifact set aims at: could a reader answer, without the code, what the service exposes, what it reaches, what shapes it exchanges, how it is run and what pages whom. The depth probes catch an EMPTY contract; nothing measures a shallow one against the service, so green means the files agree with each other, never that they reach the bar.",
     "Whether an arch requirement recording effective configuration or a library's semantics ('retries: -1 is unbounded, proven from the bytecode') is still true of the chart and the classpath. The convention names arch.spec.md as the home for such facts; loam never verifies the values.",

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

@@ -1 +1 @@
-{"version":3,"file":"unchecked.js","sourceRoot":"","sources":["../../../src/core/brief/unchecked.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAa;IACjC,4EAA4E;IAC5E,uEAAuE;IACvE,4EAA4E;IAC5E,2EAA2E;IAC3E,qDAAqD;IACrD,EAAE;IACF,6EAA6E;IAC7E,2EAA2E;IAC3E,sEAAsE;IACtE,sEAAsE;IACtE,gCAAgC;IAChC,mmCAAmmC;IACnmC,6EAA6E;IAC7E,8EAA8E;IAC9E,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,kDAAkD;IAClD,oqCAAoqC;IACpqC,wUAAwU;IACxU,8HAA8H;IAC9H,yJAAyJ;IACzJ,oHAAoH;IACpH,wUAAwU;IACxU,yFAAyF;IACzF,6LAA6L;IAC7L,uGAAuG;IACvG,yJAAyJ;IACzJ,mXAAmX;IACnX,2RAA2R;IAC3R,mjBAAmjB;IACnjB,gIAAgI;CACjI,CAAC","sourcesContent":["/**\n * What no check will ever tell you. Read it as the list of ways to be wrong\n * quietly. The checks that do exist — the table an adoption baseline actually\n * meets — live in checks.ts; this module is that table's counterpart, split\n * out so each half can grow without crowding the other.\n *\n * The first two entries are here because they used to be `shape` rules on\n * model.likec4, phrased exactly like the enforced ones. A brief that states an\n * unenforced rule beside four enforced ones is not merely useless — it is the\n * way an agent learns that a green `loam validate` means more than it does.\n * Anything nothing checks belongs on this list, where its status IS the point.\n */\nexport const UNCHECKED: string[] = [\n  // Not merely unchecked — unread. This entry used to end \"write one\", on the\n  // theory that a view is what makes a model legible. It is, to LikeC4's\n  // renderer; loam computes none. Saying otherwise taught agents that a views\n  // block was owed to loam, and an `include *` over the FLEET map is the one\n  // shape that costs minutes rather than milliseconds.\n  //\n  // Still exactly true of PRESENCE, which is what this entry is about. Rule 26\n  // lets loam read a dynamic view's declared steps WHERE ONE EXISTS; nothing\n  // grades their absence, and the failure this comment records — agents\n  // learning that a views block is owed to loam — is the one rule 26 is\n  // written to prevent recurring.\n  \"Whether model.likec4 declares a `views { ... }` block, or any view at all — and nothing in loam ever will. What loam reads, when a `dynamic view` IS present, is only what its author declared: the view's tags and its ordered steps. It computes no view and renders nothing, and it never grades a model for lacking one — a fleet that draws no diagrams owes loam no views block, today or ever. Views belong to LikeC4's own renderer: write them if you want diagrams, and read them with `npx likec4 start <dir>` pointed at ONE directory — `services/<id>` for a service model, the docs repo root for the fleet map (`likec4.config.json` scopes that root project to `architecture/`). The renderer merges every `.likec4` file it is given into one model, and loam parses each of them alone, so each declares its own `specification` block: point it at a directory holding two of them and every declaration reads as a duplicate. Scope your views too — computing a view is superlinear in the number of edges, and an `include *` over `architecture/landscape.likec4` is the expensive one, because that file holds every call in the fleet.\",\n  // The readability half of the entry above. They are separate entries because\n  // the failures are: one is a view that takes minutes to compute, the other is\n  // a view that computes instantly and cannot be read. A fleet acquires the\n  // second one the day its second service starts publishing, and every service\n  // after that makes it worse by exactly one edge — which is why it arrives as\n  // a surprise on a map that was fine last quarter.\n  \"Whether the fleet map is LEGIBLE — nothing in loam draws it, so nothing in loam notices. The shape that goes first is a shared broker: Kafka, a bus, a gateway, drawn as ONE element, is the node every service in the fleet points at, and a view over it is a star with sixty spokes. Model the TOPIC rather than the broker — `paymentEvents = topic 'payment.events'` nested inside the broker's element, with the edges pointing at `kafka.paymentEvents` — and one hub of degree sixty becomes twelve of degree five, which is also the truer model: the contract a producer and a consumer share is the topic, never the broker. Declare `element topic { #external, style { shape queue } }` in the `specification` block and give the nested elements that kind: LikeC4 does not inherit tags, so a topic under an `#external` broker is NOT external itself and `loam validate --all` asks for a `services/payment.events/` nobody owes (`landscape.service-undocumented`). Then scope the views, which is where the rest of the legibility lives: `exclude element.tag = #external` keeps the fleet overview to the calls between our own services, and a second view over the broker draws the event spine on its own.\",\n  \"Whether the model has exactly ONE top-level element for the service, with its containers nested inside. Five top-level boxes for one service parse, validate and bind exactly as well as one — and then the fleet map, which joins elements to directories, has five candidates for the same service and no way to say which is wrong.\",\n  \"Whether the model is the architecture the code actually has. loam parses model.likec4; it never reads a line of the service.\",\n  \"Whether a requirement is TRUE of the service. `loam validate` checks that a requirement has a scenario, never that either one describes real behaviour.\",\n  \"Whether the scenarios are acceptance criteria somebody could test, or the requirement restated in Given/When/Then.\",\n  \"Whether an operationId is the one the code serves, and whether the request and response schemas resemble what the endpoint really accepts and returns. Presence is probed — an operation with no response schema at all is warned about — but what a declared schema SAYS is never compared with anything; only the operationId joins.\",\n  \"Whether the runbook's steps work, or the health.yaml SLOs are numbers anyone agreed to.\",\n  \"Whether an arch scenario really exercises what its `Covers:` line names. The entries are resolved against the model and health.yaml — never against code, tests, dashboards or alert rules.\",\n  \"Whether an ADR records a decision that was made, or one reconstructed afterwards to justify the code.\",\n  \"COMPLETENESS. Forty behaviours documented as one requirement passes every check loam has. So does a service with one endpoint documented out of thirty.\",\n  \"REPRODUCIBILITY — the bar the artifact set aims at: could a reader answer, without the code, what the service exposes, what it reaches, what shapes it exchanges, how it is run and what pages whom. The depth probes catch an EMPTY contract; nothing measures a shallow one against the service, so green means the files agree with each other, never that they reach the bar.\",\n  \"Whether an arch requirement recording effective configuration or a library's semantics ('retries: -1 is unbounded, proven from the bytecode') is still true of the chart and the classpath. The convention names arch.spec.md as the home for such facts; loam never verifies the values.\",\n  \"Whether a permission in `architecture/permissions.yaml` is one the system actually has. `Requires:` is checked against that file and the file against nothing: a vocabulary that agrees with every requirement citing it can still name three permissions the identity provider retired last year, and `owned_by` / `enforced_by` are read as prose — neither is resolved against `services/`, and a realm is never opened. The check is a spelling guard between documents, exactly as `Operations:` is; whether the word is real is a question only the running system answers.\",\n  \"Whether `sources` names the files you read. loam checks those paths exist — not that they are the ones the document came from.\",\n];\n"]}
+{"version":3,"file":"unchecked.js","sourceRoot":"","sources":["../../../src/core/brief/unchecked.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAa;IACjC,4EAA4E;IAC5E,uEAAuE;IACvE,4EAA4E;IAC5E,2EAA2E;IAC3E,qDAAqD;IACrD,EAAE;IACF,6EAA6E;IAC7E,2EAA2E;IAC3E,sEAAsE;IACtE,sEAAsE;IACtE,gCAAgC;IAChC,gkDAAgkD;IAChkD,6EAA6E;IAC7E,8EAA8E;IAC9E,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,kDAAkD;IAClD,u/CAAu/C;IACv/C,4EAA4E;IAC5E,8EAA8E;IAC9E,yEAAyE;IACzE,2EAA2E;IAC3E,2EAA2E;IAC3E,uEAAuE;IACvE,2EAA2E;IAC3E,2EAA2E;IAC3E,kDAAkD;IAClD,wmCAAwmC;IACxmC,8oBAA8oB;IAC9oB,8HAA8H;IAC9H,yJAAyJ;IACzJ,oHAAoH;IACpH,wUAAwU;IACxU,yFAAyF;IACzF,6LAA6L;IAC7L,uGAAuG;IACvG,gnBAAgnB;IAChnB,yJAAyJ;IACzJ,mXAAmX;IACnX,2RAA2R;IAC3R,mjBAAmjB;IACnjB,gIAAgI;CACjI,CAAC","sourcesContent":["/**\n * What no check will ever tell you. Read it as the list of ways to be wrong\n * quietly. The checks that do exist — the table an adoption baseline actually\n * meets — live in checks.ts; this module is that table's counterpart, split\n * out so each half can grow without crowding the other.\n *\n * The first two entries are here because they used to be `shape` rules on\n * model.likec4, phrased exactly like the enforced ones. A brief that states an\n * unenforced rule beside four enforced ones is not merely useless — it is the\n * way an agent learns that a green `loam validate` means more than it does.\n * Anything nothing checks belongs on this list, where its status IS the point.\n */\nexport const UNCHECKED: string[] = [\n  // Not merely unchecked — unread. This entry used to end \"write one\", on the\n  // theory that a view is what makes a model legible. It is, to LikeC4's\n  // renderer; loam computes none. Saying otherwise taught agents that a views\n  // block was owed to loam, and an `include *` over the FLEET map is the one\n  // shape that costs minutes rather than milliseconds.\n  //\n  // Still exactly true of PRESENCE, which is what this entry is about. Rule 26\n  // lets loam read a dynamic view's declared steps WHERE ONE EXISTS; nothing\n  // grades their absence, and the failure this comment records — agents\n  // learning that a views block is owed to loam — is the one rule 26 is\n  // written to prevent recurring.\n  \"Whether model.likec4 declares a `views { ... }` block, or any view at all — and nothing in loam ever will. What loam reads, when a `dynamic view` IS present — in the fleet map, or in this service's own project once a view there carries `#req-` — is only what its author declared: the view's tags and its ordered steps. It computes no view and renders nothing, and it never grades a model for lacking one — a fleet that draws no diagrams owes loam no views block, today or ever. Views belong to LikeC4's own renderer: write them if you want diagrams, and read them with `npx likec4 start` at the docs repo root. The root project holds `architecture/` AND every model that EXTENDS the map, so a model written the way this brief asks for it renders there beside the fleet map with no second file to write — one project, one entry in the renderer's picker. The exception is a model that declares its own `specification` block and is therefore parsed alone: its kinds would be duplicates inside the root project, so its directory is excluded there and its own `services/<id>/likec4.config.json` — written by `loam subsystem sync`, loam's file and never yours — makes it a project of its own. A feature's delta.likec4 is the one document always pointed at alone (`npx likec4 start features/<FEAT>`), because it re-declares the landscape's identifiers and carries a `specification` block of its own. Scope your views too — computing a view is superlinear in the number of edges, and an `include *` over `architecture/landscape.likec4` is the expensive one, because that file holds every call in the fleet.\",\n  // The readability half of the entry above. They are separate entries because\n  // the failures are: one is a view that takes minutes to compute, the other is\n  // a view that computes instantly and cannot be read. A fleet acquires the\n  // second one the day its second service starts publishing, and every service\n  // after that makes it worse by exactly one edge — which is why it arrives as\n  // a surprise on a map that was fine last quarter.\n  \"Whether the fleet map is LEGIBLE — nothing in loam draws it, so nothing in loam notices. The shape that goes first is a shared broker: Kafka, a bus, a gateway, drawn as ONE element, is the node every service in the fleet points at, and a view over it is a star with sixty spokes. Model the TOPIC rather than the broker — `paymentEvents = topic 'payment.events'` nested inside the broker's element, with the edges pointing at `kafka.paymentEvents` — and one hub of degree sixty becomes twelve of degree five, which is also the truer model: the contract a producer and a consumer share is the topic, never the broker. Declare `element topic { style { shape queue } }` in the `specification` block and give the nested elements that kind: loam reads `database`, `queue`, `topic`, `cache` and `bucket` as infrastructure rather than as candidate services, so a topic drawn this way is out of the service census and nobody is asked for a `services/payment.events/` (the same element spelled `container` earns `landscape.service-undocumented`). Adding `#external` to that kind is now a VIEW choice — LikeC4 does not inherit tags, so a topic under an `#external` broker is not external itself, and tagging the kind is what puts the topics behind the `exclude` below — not a way to silence a check. Then scope the views, which is where the rest of the legibility lives: `exclude element.tag = #external` keeps the fleet overview to the calls between our own services, and a second view over the broker draws the event spine on its own.\",\n  // The third view entry, and the one docs/DESIGN.md rule 26 makes permanent:\n  // what a rendered view SHOWS is never computed, so whether an adopted service\n  // is on the picture is a fact loam cannot have. It is here rather than a\n  // check because each of the three ways to vanish is either the fleet's own\n  // vocabulary (a placeholder tag `loam seed` never writes), a static view's\n  // `include` predicates (unread by rule), or LikeC4's semantics — and a\n  // warning that is right once and noise forty times is the warning somebody\n  // silences. The brief NAMES the element's unread tags (landscape.ts); this\n  // entry says what nothing will ever do with them.\n  \"Whether an adopted service is VISIBLE on the fleet map, which is a different state from being drawn on it. Three things make a documented, bound, edged service disappear, and no check names any of them. A placeholder tag somebody put on the element before adoption — `#provisional`, or whatever your fleet uses to mean drawn-ahead-of-adoption — survives adoption untouched: loam's `seed` writes no such tag, loam reads none, and a fleet view written `exclude element.tag = #<that>` keeps hiding the service until a human removes it, so clearing it is part of the landscape edit. A curated view that lists its members by id (`include paymentService, billingService`) gains nothing by itself. And `include *` shows top-level elements only: once services nest inside a boundary element — the shape loam's own generated subsystem views draw a box around — a fleet view written that way collapses to the boundary and shows no service at all, and needs `include <boundary>.**` (LikeC4's semantics, not loam's). Adopted and visible are two states; only the second is yours to make, and nothing here can tell you which one you are in.\",\n  \"Whether the model has exactly ONE top-level element for the service, with its containers nested inside — which is a question only for a model that declares its own `specification` and is parsed alone. Five top-level boxes for one service parse, validate and bind exactly as well as one there, and then the fleet map, which joins elements to directories, has five candidates for the same service and no way to say which is wrong. A model that EXTENDS the map cannot get into that state by accident: it opens one element, the map's, and anything it declares beside that element is `c4.element-unowned` — which is the same rule enforced instead of stated.\",\n  \"Whether the model is the architecture the code actually has. loam parses model.likec4; it never reads a line of the service.\",\n  \"Whether a requirement is TRUE of the service. `loam validate` checks that a requirement has a scenario, never that either one describes real behaviour.\",\n  \"Whether the scenarios are acceptance criteria somebody could test, or the requirement restated in Given/When/Then.\",\n  \"Whether an operationId is the one the code serves, and whether the request and response schemas resemble what the endpoint really accepts and returns. Presence is probed — an operation with no response schema at all is warned about — but what a declared schema SAYS is never compared with anything; only the operationId joins.\",\n  \"Whether the runbook's steps work, or the health.yaml SLOs are numbers anyone agreed to.\",\n  \"Whether an arch scenario really exercises what its `Covers:` line names. The entries are resolved against the model and health.yaml — never against code, tests, dashboards or alert rules.\",\n  \"Whether an ADR records a decision that was made, or one reconstructed afterwards to justify the code.\",\n  \"Whether the DEPLOYMENT model is the topology the fleet actually runs. Every join over it is between documents: `instanceOf` resolves against the C4 model, a `#obl-` tag resolves against the obligation vocabulary, and a `Covers: node:` entry resolves against the nodes the map declares. Nothing here knows whether the second cluster exists, whether it is reachable, whether replication is configured, or whether it holds the data a requirement claims — and no check counts datacenters, because how many a service needs is an architectural decision the fleet makes and writes down as a requirement, never one loam evaluates.\",\n  \"COMPLETENESS. Forty behaviours documented as one requirement passes every check loam has. So does a service with one endpoint documented out of thirty.\",\n  \"REPRODUCIBILITY — the bar the artifact set aims at: could a reader answer, without the code, what the service exposes, what it reaches, what shapes it exchanges, how it is run and what pages whom. The depth probes catch an EMPTY contract; nothing measures a shallow one against the service, so green means the files agree with each other, never that they reach the bar.\",\n  \"Whether an arch requirement recording effective configuration or a library's semantics ('retries: -1 is unbounded, proven from the bytecode') is still true of the chart and the classpath. The convention names arch.spec.md as the home for such facts; loam never verifies the values.\",\n  \"Whether a permission in `architecture/permissions.yaml` is one the system actually has. `Requires:` is checked against that file and the file against nothing: a vocabulary that agrees with every requirement citing it can still name three permissions the identity provider retired last year, and `owned_by` / `enforced_by` are read as prose — neither is resolved against `services/`, and a realm is never opened. The check is a spelling guard between documents, exactly as `Operations:` is; whether the word is real is a question only the running system answers.\",\n  \"Whether `sources` names the files you read. loam checks those paths exist — not that they are the ones the document came from.\",\n];\n"]}

package/dist/core/c4/arch.js

@@ -10,33 +10,41 @@
  * scenarios exercise, so coverage can be derived mechanically instead of
  * trusted to an author who was never going to write the outbox down.
  *
- * Three entry forms, resolved against the documents loam already reads:
+ * Four entry forms, resolved against the documents loam already reads:
  *
  *   paymentService.db               a C4 element id — resolved against the
  *                                   in-scope elements the way every check joins
  *                                   them: the id itself, or the service the
  *                                   element stands for (binding, then title);
  *   paymentService -> kafka         an edge — each side resolved the same way,
- *                                   against the declared relationships;
+ *                                   against the declared relationships; the
+ *                                   edge may carry the relationship's kind as
+ *                                   LikeC4 writes it, `paymentService -[async]->
+ *                                   kafka` or `paymentService .async kafka`,
+ *                                   which is read past rather than compared;
  *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`
- *                                   declares (core/vocabulary/health.ts).
+ *                                   declares (core/vocabulary/health.ts);
+ *   node:<id>, node:a -> node:b     a deployment object — a node or an instance
+ *                                   in the landscape's `deployment { }` model,
+ *                                   matched literally. This is the form that
+ *                                   lets a requirement about replication name
+ *                                   the two clusters it is written about
+ *                                   (ROADMAP's deployment axis).
  *
  * Resolution never reads code. An entry that resolves to nothing is the typo
  * guard (`covers.unknown`, warn); the emitters live with the other validate
  * checks, this module owns only the grammar and the matching.
  *
- * `attributeStep` at the foot of the file answers the same shape of question for
- * a different axis. A `dynamic view`'s hop says "web talks to orders"; which
- * declared relationship backs that hop, and what that relationship says the
- * operation is, is the join `coversEdge` already performs — same two tiers, same
- * cached `serviceResolver`, same "an endpoint names an element or the service it
- * stands for" rule. It lives here rather than beside the view reader in
- * `parsed/` because a second copy of that join is the copy that drifts, and
- * because `parsed/dynamic-views.ts` may read `$data` and nothing else
- * (docs/DESIGN.md rule 26) — it has no business holding the model join.
+ * `attributeStep` used to sit at the foot of this file and now lives in
+ * `./resolve/steps.ts`. It answers the same shape of question for a different
+ * axis — which declared relationship backs a `dynamic view`'s hop — over the
+ * same two tiers and the same cached resolver, and the seam was named here long
+ * before the line limit forced it. What the two still share is
+ * `./resolve/service.ts`'s `resolverFor`, which is where that cache moved with
+ * it: one id→service resolver per document, serving both axes.
  */
 import {} from "./likec4.js";
-import { elementService, serviceResolver } from "./resolve/service.js";
+import { elementService, resolverFor } from "./resolve/service.js";
 /** Parse one comma-separated `Covers:` entry into its form. Never fails: an
  * unclassifiable string is an element entry that will not resolve, and the
  * covers.unknown message is a better diagnosis than a parse refusal. */
@@ -47,61 +55,49 @@ export function parseCoversEntry(raw) {
     const sli = /^sli:\s*(.+)$/.exec(raw);
     if (sli)
         return { form: "sli", id: sli[1].trim(), raw };
-    const edge = /^(.+?)\s*->\s*(.+)$/.exec(raw);
-    if (edge)
-        return { form: "edge", source: edge[1].trim(), target: edge[2].trim(), raw };
+    // An edge may be spelled with its relationship kind, the two ways LikeC4
+    // writes one — `a -[async]-> b`, and `a .async b` for a kind the
+    // specification declares — because that is how the edge itself is written
+    // and an author copies the edge line. The split used to stop at the first
+    // `->`, the one AFTER the `]`, so the bracket form became `a -[async]` ->
+    // `b`, and the dotted form, with no `->` at all, fell through to an element
+    // entry: both were `covers.unknown` while the kind-less spelling of the same
+    // edge resolved. The kind is read past, not compared: loam identifies an
+    // edge by its two endpoints (`flattenModel` keeps no kind), so either kinded
+    // spelling covers exactly what `a -> b` covers. The dotted form needs no
+    // specification to tell it from an element id: an id never holds a space,
+    // so `<id> .<kind> <id>` can be nothing else.
+    const edge = /^(.+?)\s*(?:-\[[^\]]*\])?->\s*(.+)$/.exec(raw) ?? /^(\S+)\s+\.[A-Za-z_][\w-]*\s+(\S+)$/.exec(raw);
+    if (edge) {
+        const source = edge[1].trim();
+        const target = edge[2].trim();
+        const from = nodeId(source);
+        const to = nodeId(target);
+        // BOTH sides, or neither. A mixed entry stays an ordinary edge whose
+        // prefixed side then resolves to nothing — which is the honest answer:
+        // there is no edge in any model with one endpoint in the logical map and
+        // one in the deployment map, so accepting a half-prefixed line would be
+        // inventing a join rather than reading one. The `->` split runs FIRST for
+        // the same reason the alert/sli tests do: `node:a -> node:b` read as a
+        // single id would be one entry that can never resolve.
+        if (from !== undefined && to !== undefined)
+            return { form: "node-edge", source: from, target: to, raw };
+        return { form: "edge", source, target, raw };
+    }
+    const node = nodeId(raw);
+    if (node !== undefined)
+        return { form: "node", id: node, raw };
     return { form: "element", id: raw, raw };
 }
+/** The id behind a `node:` prefix, or nothing when the entry does not carry one. */
+function nodeId(text) {
+    const m = /^node:\s*(.+)$/.exec(text);
+    return m === null ? undefined : m[1].trim();
+}
 /** Does an element entry name this element? Its id, or the service it stands for. */
 function namesElement(name, e) {
     return e.id === name || elementService(e) === name;
 }
-/**
- * One `id -> service` resolver per document, not one per lookup.
- *
- * `serviceOf` builds a fresh id map on every call, and this axis calls it twice
- * for every relationship in scope — inside loops that already run over every
- * relationship a service can see. `serviceResolver`'s own doc says it is "built
- * once per document and shared"; this is where the Covers axis keeps that
- * promise, since `coversEdge` is exported and its callers hold only the element
- * array.
- *
- * A module-level cache is normally the wrong shape here, because a command runs
- * against whatever directory it was invoked in. This one is safe: the key is the
- * per-invocation `Elem[]` a parse produced, its value is a pure function of that
- * key alone, and nothing in it is derived from the working directory — so two
- * runs can never see each other's answer, and the entry dies with the document.
- * Nothing mutates an `Elem[]` after parse.
- *
- * Two tiers because the fleet set is part of the answer: the same document
- * resolves differently with and without `known`, so a cache keyed on the
- * elements alone handed a with-fleet caller the without-fleet resolver.
- * Callers build ONE set per run and pass the same instance through, which is
- * what lets the inner WeakMap key on the set's identity.
- */
-const RESOLVERS = new WeakMap();
-const FLEET_RESOLVERS = new WeakMap();
-function resolverFor(elements, known) {
-    if (known === undefined) {
-        const cached = RESOLVERS.get(elements);
-        if (cached !== undefined)
-            return cached;
-        const resolver = serviceResolver(elements);
-        RESOLVERS.set(elements, resolver);
-        return resolver;
-    }
-    let perSet = FLEET_RESOLVERS.get(elements);
-    if (perSet === undefined) {
-        perSet = new WeakMap();
-        FLEET_RESOLVERS.set(elements, perSet);
-    }
-    const cached = perSet.get(known);
-    if (cached !== undefined)
-        return cached;
-    const resolver = serviceResolver(elements, known);
-    perSet.set(known, resolver);
-    return resolver;
-}
 /** Does an edge entry's side name this relationship endpoint? */
 function namesEndpoint(name, endpointId, elements, known) {
     return endpointId === name || resolverFor(elements, known)(endpointId) === name;
@@ -116,6 +112,14 @@ export function coversEdge(entry, r, elements, known) {
         namesEndpoint(entry.source, r.source, elements, known) &&
         namesEndpoint(entry.target, r.target, elements, known));
 }
+/** Does a Covers entry name this deployment node or instance? Matched literally — see `entryResolves`. */
+export function coversDeployNode(entry, id) {
+    return entry.form === "node" && entry.id === id;
+}
+/** Does a Covers entry name this deployment edge? Both endpoints, literally. */
+export function coversDeployEdge(entry, source, target) {
+    return entry.form === "node-edge" && entry.source === source && entry.target === target;
+}
 /** Does the entry resolve to ANYTHING in scope? False is `covers.unknown`. */
 export function entryResolves(entry, scope) {
     switch (entry.form) {
@@ -127,8 +131,26 @@ export function entryResolves(entry, scope) {
             return scope.relationships.some((r) => coversEdge(entry, r, scope.elements, scope.known));
         case "element":
             return scope.elements.some((e) => coversElement(entry, e));
+        case "node":
+            return deployedIds(scope).includes(entry.id);
+        case "node-edge":
+            // Endpoints matched literally, and only literally. The logical forms
+            // resolve a name through `serviceResolver` because an author writes
+            // `checkout-web -> payment-service` about an edge the model draws between
+            // two containers; a deployment id is already the exact path to one place
+            // on the map, there is no coarser name for it, and inventing one would
+            // make `node:eu.dcA` silently match an edge between two clusters inside
+            // it.
+            return (scope.deployment?.relationships ?? []).some((r) => r.source === entry.source && r.target === entry.target);
     }
 }
+/** Every deployment object a `node:` entry may name: the nodes, and the instances in them. */
+function deployedIds(scope) {
+    const d = scope.deployment;
+    if (d === undefined)
+        return [];
+    return [...d.nodes.map((n) => n.id), ...d.instances.map((i) => i.id)];
+}
 /** Ids a covers.unknown hint may offer for a mistyped entry — always real ones. */
 export function coversCandidates(entry, scope) {
     switch (entry.form) {
@@ -137,11 +159,17 @@ export function coversCandidates(entry, scope) {
         case "sli":
             return closeIds(entry.id, scope.health.slis).map((id) => `sli:${id}`);
         case "edge":
+        case "node-edge":
             // Cheap on purpose: no pairwise edge fuzzing — the sides are element
             // names, so the element hint is the useful one.
             return [];
         case "element":
             return closeIds(entry.id, [...new Set(scope.elements.map((e) => e.id))]);
+        case "node":
+            // Offered WITH the prefix, because that is the line the author has to
+            // type. A hint spelling an id the grammar would then read as an element
+            // entry is a hint that sends the reader round the loop a second time.
+            return closeIds(entry.id, [...new Set(deployedIds(scope))]).map((id) => `node:${id}`);
     }
 }
 /**
@@ -159,124 +187,4 @@ export function closeIds(typo, ids) {
     })
         .slice(0, 5);
 }
-/**
- * The pair a step's backing relationship is looked up under. This is the half
- * that mis-grades the whole fleet if it is wrong, because a reply arrow is the
- * commonest step in any sequence diagram.
- *
- * MEASURED at the `likec4@1.59.2` pin, and `test/likec4-view-shape.test.ts` holds
- * the raw form: a reply written `a <- b 'reply'` parses as
- * `{source: "b", target: "a", isBackward: true}` — LikeC4 has ALREADY reversed
- * the endpoints and set the flag — while the forward `b -> a` yields that same
- * pair with no `isBackward` key at all (ABSENT, not false). So the endpoints as
- * parsed describe the direction the MESSAGE travels, and the flag records which
- * arrow the author typed.
- *
- * loam attributes a reply to the CALL it answers, so the reversal is undone
- * here. A landscape declares `web -> orders` because that edge is the
- * dependency; a mirror `orders -> web` for each response is not something a
- * fleet writes down. Reading a reply hop under the message's own direction would
- * report every return hop against such a landscape as `unbacked`, and where a
- * fleet does draw the mirror edge it would file the two halves of one call under
- * two operations — the call under `op 'createOrder'`, its reply under none.
- *
- * That is deliberately NOT what LikeC4's own computed stage does, and the
- * difference is measured rather than assumed: that stage resolves a backward
- * step's `relations` from the UNFLIPPED pair, so at this pin a `web <- orders`
- * step computes to `relations: []` when only `web -> orders` exists, and to the
- * mirror edge when only `orders -> web` does. It is answering which arrow to
- * draw; loam is answering which operation the hop exercises, and reads what a
- * view DECLARES rather than what it shows — which is why loam never reaches that
- * stage at all (docs/DESIGN.md rule 26, enforced by `scripts/arch-check.mjs`).
- * The consequence to know before changing this: where
- * a fleet declares BOTH directions, the mirror edge is not what backs the reply
- * here — the call is, and the mirror edge backs only a hop drawn forward along
- * it.
- */
-function callPair(step) {
-    return step.isBackward ? { from: step.target, to: step.source } : { from: step.source, to: step.target };
-}
-/**
- * The distinct `op` values across candidates, first-seen order preserved.
- *
- * Absent is a VALUE here, not a gap to skip: a relationship carrying no `op` and
- * one carrying `createOrder` disagree about the operation just as surely as two
- * different ops do, and skipping the absent one would silently promote that
- * disagreement to a confident answer. `includes` rather than a `Set` because a
- * candidate list is the handful of relationships between one pair of endpoints,
- * and it keeps `undefined` comparing the way the rest of this file expects.
- */
-function distinctOps(rels) {
-    const out = [];
-    for (const r of rels)
-        if (!out.includes(r.op))
-            out.push(r.op);
-    return out;
-}
-/**
- * The verdict one tier's candidates imply, or `undefined` when that tier found
- * nothing and is therefore not the tier that answers.
- *
- * The count that decides is the DISTINCT-OP count, never the candidate count.
- * That distinction is what makes the service tier safe: once a service is drawn
- * as containers, `a.api -> b` and `a.worker -> b` both carrying
- * `op 'createOrder'` are two relationships and one operation, and a verdict read
- * off `rels.length` would convict a perfectly consistent model of contesting
- * itself.
- */
-function verdictOn(pair, tier, rels) {
-    if (rels.length === 0)
-        return undefined;
-    const ops = distinctOps(rels);
-    if (ops.length > 1)
-        return { ...pair, verdict: "contested", tier, rels, ops };
-    // Length is exactly one here, so the single distinct value is the answer —
-    // and `undefined` is a legitimate answer: every candidate agreed that this
-    // hop names no operation.
-    const [only] = ops;
-    return { ...pair, verdict: "attributed", tier, rels, ...(only === undefined ? {} : { op: only }) };
-}
-/**
- * Relationships whose ENDPOINTS resolve to the same two services as the pair —
- * the fallback tier, and the reason a step drawn between two services matches an
- * edge drawn between two containers.
- *
- * Through the module's cached `resolverFor`, not a fresh `serviceResolver`: this
- * runs once per step of every use case in the fleet, and building the id map per
- * step is the cost that comment above `RESOLVERS` exists to prevent.
- */
-function resolvedTier(pair, scope) {
-    const resolve = resolverFor(scope.elements, scope.known);
-    const from = resolve(pair.from);
-    const to = resolve(pair.to);
-    return scope.relationships.filter((r) => resolve(r.source) === from && resolve(r.target) === to);
-}
-/**
- * Which relationship in the model backs one hop of a use case, and what it says
- * the operation is.
- *
- * Two tiers, and the second runs ONLY when the first is empty. That ordering is
- * load-bearing rather than an optimisation: the service tier necessarily
- * re-finds every exact match — an endpoint that matches literally resolves to
- * the same service trivially — so running it unconditionally would let a
- * container-level edge with a different `op` contest a step the model already
- * answers exactly, turning an `attributed` verdict into a `contested` one on a
- * document nobody changed.
- *
- * Relationship `kind` is deliberately not part of the match, and that is
- * measured too: at this pin `a -[http]-> b` without a `relationship http` in the
- * `specification` block is "Could not resolve reference to RelationshipKind
- * named 'http'" — a parse error, which under loam's standing rule means no model
- * at all — and `test/helpers/harness.ts`'s own `LANDSCAPE` declares no
- * relationship kinds. So narrowing by kind would mean a fix message asking an
- * author to write a line their document does not parse.
- */
-export function attributeStep(step, scope) {
-    const pair = callPair(step);
-    const exact = scope.relationships.filter((r) => r.source === pair.from && r.target === pair.to);
-    const declared = verdictOn(pair, 1, exact);
-    if (declared !== undefined)
-        return declared;
-    return verdictOn(pair, 2, resolvedTier(pair, scope)) ?? { ...pair, verdict: "unbacked" };
-}
 //# sourceMappingURL=arch.js.map