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

package/dist/core/workspace/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/core/workspace/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAY1D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,QAAgB;IACjE,MAAM,QAAQ,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;IACpG,OAAO,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAmC,EACnC,OAAe;IAEf,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACvC,MAAM;QACN,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,qBAAqB,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC;KACxE,CAAC,CAAC,CAAC;IACJ,MAAM,IAAI,GACR,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACjG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC","sourcesContent":["/**\n * Deterministic `.code-workspace` rendering — pure computation, no printing.\n *\n * The output is a derived file: same members plus same target path must\n * produce the same bytes on every machine, which is why every path is spelled\n * with forward slashes (VS Code and Cursor accept them on Windows too, and\n * they are the one spelling that diffs identically across checkouts) and why\n * the JSON shape follows saveConfig's convention — 2-space indent, trailing\n * newline.\n */\nimport { dirname, isAbsolute, relative } from \"node:path\";\nimport type { WorkspaceMember } from \"./discover.js\";\n\n/** One folder row, still carrying the member it was derived from. */\nexport interface RenderedFolder {\n  member: WorkspaceMember;\n  /** Exactly what lands in the file's `name`. */\n  name: string;\n  /** Exactly what lands in the file's `path` — the forward-slash spelling. */\n  path: string;\n}\n\n/**\n * The `path` a folder entry gets, from the already-computed relative and the\n * member's absolute path.\n *\n * Split out of `renderWorkspace` because the fallback decision is win32-only\n * on a win32 host — `relative()` answers a cross-drive pair with the ABSOLUTE\n * target, since no `..` chain crosses drives — and a POSIX test host can\n * therefore never steer the platform `relative()` into producing one. Taking\n * `rel` as data lets the suite exercise the branch with win32-shaped input.\n *\n * The drive-letter test backs up `isAbsolute` because that check is also\n * platform-bound: on POSIX, `D:\\other\\svc` reads as a relative name. A POSIX\n * directory literally named `D:` would match too and get the absolute\n * spelling instead of the relative one — a stranger workspace file, but a\n * correct one, and the pathological name is not worth a platform fork here.\n */\nexport function workspacePathSpelling(rel: string, absolute: string): string {\n  const spelling = rel === \"\" ? \".\" : isAbsolute(rel) || /^[A-Za-z]:[\\\\/]/.test(rel) ? absolute : rel;\n  return spelling.split(/[\\\\/]/).join(\"/\");\n}\n\n/**\n * Render the workspace document for `members`, targeted at `outPath`.\n *\n * Folder paths are relative to the file's own directory, so the committed\n * side-by-side layout opens on every machine that checks it out; a member on\n * another drive keeps its absolute path, because no relative spelling exists.\n * The folders are returned still attached to their members so the command can\n * echo the exact written spelling into its `--json` payload without joining\n * two arrays by position.\n */\nexport function renderWorkspace(\n  members: readonly WorkspaceMember[],\n  outPath: string,\n): { text: string; folders: RenderedFolder[] } {\n  const outDir = dirname(outPath);\n  const folders = members.map((member) => ({\n    member,\n    name: member.name,\n    path: workspacePathSpelling(relative(outDir, member.path), member.path),\n  }));\n  const text =\n    JSON.stringify({ folders: folders.map(({ name, path }) => ({ name, path })) }, null, 2) + \"\\n\";\n  return { text, folders };\n}\n"]}

package/examples/README.md

@@ -0,0 +1,189 @@
+# The example fleet
+
+`docs/` is a complete, runnable loam docs repo. It is small enough to read in one sitting and large
+enough that every row of [SCHEMA.md](../SCHEMA.md)'s canonical-joins table is exercised by something
+— including the joins that only appear once a fleet has more than two services in it.
+
+Run it from a clone. `docs/loam.json` is committed and says `"docsDir": "."`, so the tree governs
+itself: every command below resolves to this fleet because it is run from inside it. There is
+nothing to write first and nothing to delete afterwards.
+
+```bash
+cd examples/docs
+loam list                          # the fleet and its maturity ladder
+loam status                        # what to do next, derived from the files
+loam validate --all                # the gate CI runs
+loam archive FEAT-101 --dry-run    # the three-axis merge plan, writing nothing
+loam archive FEAT-112 --dry-run    # an operation being retired, writing nothing
+loam verify FEAT-088               # a shipped feature's done-check: attested
+loam verify FEAT-120               # …and its pair, the same check: verified
+loam dependencies                  # the active-feature graph
+```
+
+Working on loam itself and running from source, use `npx tsx ../../src/cli.ts <args>` in place of
+`loam`. Not `npm run dev --`: npm runs a script from the package root, so it would leave
+`examples/docs` and resolve some other `loam.json` — the fleet it reported would not be this one.
+
+`test/examples.test.ts` pins the validate summary, every finding code and the archive plans
+file-for-file, so nothing below can drift away from the code without a test going red.
+
+## What is in it
+
+Five services, drawn inside one grouping element so the map looks like ordinary grouped C4:
+
+| service | what it is here to show |
+|---|---|
+| `checkout-web` | a UI service: page-specs under `ui/pages/`, no `openapi.yaml` of its own, and the one spec in the fleet that names no `sources` |
+| `order-service` | the busiest spine: four operations, a produced event, a consumed event, and a deprecated operation with a feature already open to retire it |
+| `payment-service` | the outbox, the acquirer, and an `arch.spec.md` whose `Covers:` lines reach the C4 model *and* the health signals |
+| `identity-service` | the permission vocabulary's owner, and a deprecated operation whose consumer has not migrated — filed into `services/platform/` |
+| `notification-service` | a service with no HTTP API at all — three consumed messages, one of them from a producer outside the fleet — filed into `services/platform/` |
+
+Around them: `kafka` as an `#external` `#platform` system with a topic per channel (edges point at
+the topic, never at the broker), `stripe` and `salesforce` as external systems, and
+`architecture/permissions.yaml` as the fleet's authorization vocabulary.
+
+**Three authored capability documents**, which are the business tree rather than the architecture:
+`capabilities/checkout/spec.md`, `capabilities/identity/tokens/spec.md` and
+`capabilities/order-notifications/spec.md`. The third carries the axis's second realizer: its one
+promise — "a placed order produces exactly one confirmation" — is cross-service by construction, so
+no service's `spec.md` can keep it, and `architecture/usecases/order-notification.likec4` claims it
+with `#req-NOTIFY-ONCE` beside its `#cap-` tag. The other two are kept by service requirements
+through `Realizes:`. Both ids are also declared in `architecture/capabilities.yaml` — the vocabulary
+is the union of the two sides, and a name a document elaborates does not have to leave the YAML,
+which is what keeps the metadata (`description`, `owner`) that a document has no field for. The
+nested one carries the lesson: the id `identity/tokens` keeps its slash everywhere it is written, so
+the tree spells it as directories, and `capabilities/identity/` holding no `spec.md` of its own is a
+GROUP and earns no finding. Each requirement in both files is a promise a customer could check,
+names no service, and carries a `Requirement-ID:` — required here, unlike in a service spec, because
+these documents outlive every service that realizes them.
+
+**Two glossary terms**, `glossary/order.md` and the nested `glossary/payments/authorization.md`,
+each cited from the capability documents that use the word. This is the axis's whole mechanism in
+two files: the citation is an ordinary markdown link, so `loam validate` resolves it like any other
+and `loam list glossary` can answer "which documents use this term" as a join rather than a grep.
+The two terms also cite EACH OTHER, which is deliberate — a glossary is a network of definitions —
+and that reciprocal pair is exactly what does NOT count as adoption: both terms stay out of
+`glossary.unlinked` because a capability document cites them, not because they cite each other.
+Delete either of those two capability citations and the example gains a tenth warning.
+
+**One architectural obligation, declared and applied and met** — which is three files agreeing, and
+the axis's whole mechanism. `architecture/adrs/0001-transactional-outbox.md` says WHAT was decided;
+`#obl-outbox` on the `payment-service → kafka.paymentEvents` edge in the fleet map says WHERE it
+holds (on the publish edge, not on the service — payment-service also serves an API that owes
+nothing of the kind); `architecture/obligations.yaml` declares the name so a mistyped tag is an
+error rather than a word nobody notices; and `ARCH-PAY-OUTBOX` in payment-service's `arch.spec.md`
+covers that same edge, which is the team saying it is met. Because all four line up, the example is
+SILENT about the outbox — the working join produces no finding, which is what a working join should
+do. The second declaration, `idempotency-key`, is the one that talks: it is declared and placed
+nowhere, and `obligation.unapplied` is the warning in the table below.
+
+**On the event spine the arrow follows the message** — producer → topic for `publishes`, topic →
+consumer for `consumes` — and that is load-bearing rather than aesthetic. `publishes` binds the
+edge's source and `consumes` binds its target, so a consume edge drawn the other way round binds to
+nothing: the metadata parses, the document validates, and the check silently grades zero edges.
+Nothing in loam reports that today, which is why the landscape says so in a comment.
+
+## Four features, at four points in their life
+
+The two archived ones are a **matched pair**, and the pairing is the point: same command, same
+shape of record, two different verdicts. A showcase that demonstrated only one would teach that the
+distinction is decorative — and keeping those two answers apart is most of what loam claims to be
+for.
+
+- **`features/archive/FEAT-088-refunds/`** — shipped, and **`attested`**. It was merged by the real
+  `loam archive`, so its `.loam-before/` snapshot holds the exact bytes the merge overwrote and
+  `loam unarchive FEAT-088` would put them back. Its `verification.yaml` is the done-check written
+  down: every claim is confirmed, but the scenario claims rest on an agent's word instead of a
+  digest-matched test run. loam does not pretend those are the same thing.
+- **`features/archive/FEAT-120-refund-notification/`** — shipped, and **`verified`**. The sequel
+  FEAT-088 left open: the money went back and nobody told the customer. It publishes
+  `payment.PaymentRefunded` from payment-service and has notification-service turn it into the
+  message the customer is waiting for — so it exercises the event spine end to end, across two
+  services, with no HTTP anywhere in it.
+
+  Its five scenario claims were answered by `--results` from the `scenario-report.json` beside it:
+  loam's own runner-neutral `{"loamScenarioReport": 1, …}` shape, which any runner can be adapted
+  into. Its two `event.declares` claims still rest on an agent's word. That mix is the honest
+  common case — a suite that answers the scenarios, and wiring claims a human vouches for — and it
+  still reads `verified`, because the verdict turns on the scenario claims alone.
+- **`features/FEAT-101-payment-splitting/`** — in flight, and the big one: a new service arriving
+  with its own requirements, architecture requirements and contract, a C4 delta that splices a
+  nested element into the living landscape, a `MODIFIED` requirement that **renames its heading**
+  while keeping its `Requirement-ID` — loam's rename mechanism — and an **event-contract delta**
+  (`specs/payment-service/asyncapi.yaml`): a complete AsyncAPI 3.0 document restating
+  payment-service's living contract under `loam rebase`-written `x-loam-based-on` pins and adding
+  one new producer side, so the archive merges the new slots and leaves every pinned quote to the
+  living contract's own copy.
+- **`features/FEAT-112-retire-order-v1/`** — in flight, and the smallest legal shape: no
+  `delta.likec4` at all, because retiring an operation moves no boxes. It carries the two halves
+  loam requires together for a removal — a `REMOVED` requirement and an `x-loam-remove: true` marker
+  inside the operation object.
+
+## The warnings are the lesson
+
+`loam validate --all` reports **0 errors and 10 warnings** here, and every one of them is
+deliberate. An example that reported nothing would teach nothing about what these checks catch:
+
+| finding | what it is demonstrating |
+|---|---|
+| `sources.absent` | `checkout-web`'s spec names no `sources`, so nothing ties it to code and `loam vouch` would refuse to stamp it |
+| `spine.op-link-missing` | one landscape edge says it calls payment-service and names no operation, so no check can tell whether the call still exists |
+| `spine.op-deprecated` | payment-service still calls identity-service's `validateToken`, which that contract marks `deprecated: true` — the consumer, not the provider, is the one being told |
+| `api.requirement-deprecated` (×2) | `IDN-VALIDATE-LEGACY` and `ORD-PLACE-V1` each govern only a deprecated operation: promised behaviour on its way out |
+| `permissions.unenforced` | `user/profile:read` is declared in the vocabulary and named by no requirement — the shape a vocabulary drifts into |
+| `capability.unrealized` | `payments/settlement` is declared in `architecture/capabilities.yaml` and no living requirement's `Capability:` line names it — a promise nobody implemented, or a word nobody adopted; `loam list capabilities` shows it as `0 — unrealized` beside the realized ones |
+| `capability.requirement-unrealized` | `checkout#CHECKOUT-PRICE-HONOURED` — one promise inside a capability whose OTHER promise three services realize, so the row above says nothing about it. That contrast IS the demonstration: `capability.unrealized` finds a capability nobody claimed, and only this code finds the gap inside a capability that looks healthy. Three requirements do carry `Realizes:` lines — `WEB-CHECKOUT`, `ORD-PLACE` and `PAY-AUTHORIZE` all name `checkout#CHECKOUT-CHARGE-ONCE` — and the fourth promise is simply not implemented, which is a normal state for a business document written ahead of the fleet |
+| `c4.uncovered` | FEAT-101 adds a `checkout-web → payment-split-service` edge that no arch requirement covers, so its architectural obligations would ship untested |
+| `obligation.unapplied` | `idempotency-key` is declared in `architecture/obligations.yaml` and no `#obl-` tag applies it anywhere on the fleet map — a decision that was reversed and left its word behind, or one nobody has placed yet. Its sibling `outbox` IS placed and IS covered, and says nothing: that contrast is the demonstration |
+
+**Two of the five are filed into a subsystem.** `services/platform/` (its `subsystem.yaml` is the
+marker — title and description, never members) groups `identity-service` and `notification-service`,
+while the other three sit unfiled — the permanent, normal state a partially organized fleet lives
+in, counted by `loam list` and never a finding. Placement is not identity: both services' specs,
+contracts and digests are byte-identical to their unfiled days, every command addresses them by bare
+id, and `architecture/subsystems.likec4` — GENERATED by `loam subsystem sync`, one view per
+subsystem, one `include` per line — is the only file the grouping added. Edit the tree with
+`loam subsystem move|rename|rm` and the views file travels in the same transaction; edit it by hand
+and `validate --all` answers `subsystem.views-stale`. (`order-service` and `payment-service` stay
+unfiled deliberately: FEAT-088's committed version-2 snapshot restores them by literal path, and the
+`loam unarchive FEAT-088` walkthrough must keep working byte-for-byte.)
+
+Plus one count rather than a finding: `sourcesUnverifiableFromHere: 4`. Four specs name paths in
+their own service repositories, and this is none of those repositories — the fleet gate reports the
+blind spot instead of resolving it. Running `loam validate --service <id>` inside each service repo
+is what closes it.
+
+## What the example deliberately does not carry
+
+- **`AGENTS.md`.** A real docs repo has one, written by `loam init --docs . --create`. It is left
+  out here because a generated `AGENTS.md` carries the version stamp of the binary that wrote it,
+  and this tree is committed while the binary keeps moving — a stamped copy in the repository would
+  be stale by the next release and would say so to every reader of the example.
+
+  **`loam.json` used to be left out with it**, on the same "keep the tree a pure set of documents"
+  reasoning, and that trade was wrong: without it the example could not be RUN. `loam status` here
+  answered "No loam.json found" and exited 1, and the workaround this page printed instead — a
+  throwaway `loam.json` at the repository root — then governed every other directory in the clone,
+  so `loam init` from anywhere below it refused, and forgetting to delete it silently pointed later
+  commands at the example fleet. It is committed now, byte-for-byte the two lines `loam init` writes
+  for a docs repo that governs itself, which makes `cd examples/docs` the whole of the setup.
+- **`payment-split-service`'s own `asyncapi.yaml`.** The async axis has the full feature lifecycle
+  now — FEAT-101's `specs/payment-service/asyncapi.yaml` demonstrates the merge half on a living
+  contract — but the NEW service's contract for the drawn `PaymentSplit` edge is deliberately
+  deferred: the edge keeps the message in its title and no `metadata { publishes }`, because that
+  metadata is a join and the join demands a contract declaring the send
+  (`c4-event.message-undefined` refuses one without it). A
+  `specs/payment-split-service/asyncapi.yaml` would ride the archive's creation branch once the
+  consumer of `PaymentSplit` exists. The comment in `delta.likec4` says so rather than leaving it to
+  be discovered.
+- **A generated Gherkin suite.** `loam gherkin` writes into a *service's* repository, and there are
+  none here — this fleet is six repositories, and `docs/` is one of them. The same reason leaves
+  `sources` unresolvable and every service `draft`: `loam vouch` only runs where the code is, so no
+  SERVICE in this tree can be promoted past `draft`.
+
+  That is a different word from FEAT-120's `verified` verdict and the two must not be read as one.
+  A service's ladder rung (`empty → partial → documented → sourced → vouched`) says a human stamped
+  its living spec against the code; a feature's verdict says how its claims were answered. FEAT-120
+  is `verified` in a fleet whose services are all `draft`, which is exactly the state a team is in
+  the day its first suite goes green.

package/examples/docs/architecture/adrs/0001-transactional-outbox.md

@@ -0,0 +1,33 @@
+# 0001 — Event publishers write through a transactional outbox
+
+Status: accepted
+Date: 2026-08-28
+
+## Context
+
+A service that writes its own state and then publishes an event about it has two
+places to fail between. The failure is silent and asymmetric: the state change
+lands, the event does not, and every consumer's view of the world is quietly
+wrong until somebody reconciles by hand.
+
+## Decision
+
+A service that publishes a domain event SHALL write the event and the state
+change it reports in one database transaction, and relay it to the broker
+afterwards. Never a dual write.
+
+## Scope
+
+This is not a fleet-wide policy every service inherits — that is the shape this
+repository deliberately does not use. It applies where it is tagged: see
+`#obl-outbox` in [the fleet map](../landscape.likec4), which today marks the
+`payment-service → kafka.paymentEvents` edge and nothing else.
+`payment-service`'s [ARCH-PAY-OUTBOX](../../services/payment-service/arch.spec.md)
+is the requirement that keeps it.
+
+## Consequences
+
+A publisher needs an outbox table and a relay. A consumer must tolerate a
+duplicate: the relay guarantees at-least-once, which is why
+`checkout#CHECKOUT-CHARGE-ONCE` is a promise about the customer's card and not
+about the number of messages.

package/examples/docs/architecture/capabilities.yaml

@@ -0,0 +1,31 @@
+# The fleet's capability vocabulary, joined to requirements by `Capability:`.
+#
+# Opt-in the OTHER way round from permissions.yaml: the FILE is the opt-in, not the line.
+# A fleet without this file gets no capability findings at all, however many `Capability:`
+# lines its requirements carry; writing it is the moment the axis turns on. `loam validate`
+# then grades both directions — an undeclared name is `capability.unknown` (error, with
+# close-name suggestions), an unreadable file is `capability.invalid` exactly once per run,
+# and a declared capability nothing realizes is `capability.unrealized` (warning, one per
+# capability). `loam list capabilities` reports the whole rollup: which requirements realize
+# each capability, in which services, and how much of that rests on drafts.
+#
+# Ids are flat keys with `/` allowed for nesting — `identity/tokens` is ONE id, exactly the
+# token a requirement writes, never collapsed to `identity`. Descriptions and owners are
+# explanatory; nothing resolves them.
+capabilities:
+  checkout:
+    description: carry a customer from a filled cart to a confirmed, paid order
+    owner: checkout-team
+  identity/tokens:
+    description: issue and answer for the access tokens every fleet call presents
+    owner: platform-identity
+  order-notifications:
+    description: tell the customer what happened to their order, exactly once per event
+    owner: growth-team
+  # Declared, and realized by no living requirement anywhere in the fleet — the example's
+  # `capability.unrealized` (warning) demonstration. It is the shape this axis exists to
+  # make visible: a capability page was agreed in a meeting, the word entered the fleet's
+  # vocabulary, and no requirement anywhere claims to implement any part of it.
+  payments/settlement:
+    description: pay merchants out for captured orders
+    owner: payments-team

package/examples/docs/architecture/landscape.likec4

@@ -0,0 +1,280 @@
+// Global C4 fleet landscape — the LIVING current state.
+// `loam archive` folds a feature's #FEAT-tagged elements/relationships in here.
+// One landscape file, by decision: conflicts resolve through PRs. See SCHEMA.md,
+// "Operating at fleet scale", for the trigger that would change this.
+//
+// `loam validate --all` cross-checks this file against services/: every service
+// directory needs an element here (error), and every element that looks like a
+// service needs a directory (warning). An element is tied to its directory by
+// `metadata { service '<id>' }`, or by its title when there is no binding.
+// Systems that are not ours carry #external and are exempt.
+specification {
+  // A grouping element — it stands for no service and owns no directory. The
+  // service checks WALK the tree rather than reading only top-level elements:
+  // an element is graded at service level when no ancestor already stands for a
+  // service, so nesting the fleet inside a boundary costs nothing, and the
+  // group itself never raises `landscape.service-undocumented` because it
+  // CONTAINS services rather than being one.
+  element group
+  element softwareSystem
+  // Declared here because archive SPLICES a delta's additions verbatim: FEAT-101's
+  // new system carries its `api` container along, and the kind has to be legal in
+  // THIS document for the merged landscape to parse (archive refuses otherwise).
+  element container
+  element person
+  // A topic is an element, and the kind carries #external rather than each
+  // instance doing it: LikeC4 does NOT inherit tags, so a topic nested inside
+  // the #external broker is not external itself, and `loam validate --all`
+  // would ask for a services/payment.events/ nobody owes
+  // (`landscape.service-undocumented`).
+  element topic {
+    #external
+    // The channel is platform too, and the tag has to be HERE rather than on
+    // the broker alone: `landscape.platform-candidate` grades each drawn
+    // element by how many services consume it, and once the edges point at
+    // topics it is the topics that collect three consumers each — tagging only
+    // `kafka` would leave three untagged hubs behind.
+    #platform
+    style {
+      shape queue
+    }
+  }
+  tag external
+  // Ubiquitous infrastructure. Three consuming services is where an untagged
+  // external hub starts warning (`landscape.platform-candidate`), because that
+  // is where one more edge per modelled service stops being a fact about two
+  // services and starts being the shape of the map. Tagging keeps both pictures:
+  // the fleet view below excludes #platform, and the platform view keeps "who
+  // depends on it" answerable during an incident. LikeC4 refuses an undeclared
+  // tag, so the declaration here and the tag on the element are both needed.
+  tag platform
+  // The capability a use case opts in with. `architecture/usecases/` declares
+  // no 'specification` of its own — the whole directory is ONE LikeC4 project,
+  // and a second declaration there is a duplicate error blamed on both files —
+  // so a tag a flow carries is declared here, beside the kinds.
+  tag cap-order-notifications
+  // The requirement tag beside it: a flow says WHICH of the capability's named
+  // promises it keeps, and the id is spelled with every character a tag name
+  // cannot carry flattened to `-`. Declared here for the same reason — one
+  // specification block serves the whole `architecture/` project.
+  tag req-NOTIFY-ONCE
+  // An ARCHITECTURAL OBLIGATION, declared in architecture/obligations.yaml and
+  // applied HERE, on the objects it holds for. The decision itself is
+  // architecture/adrs/0001-transactional-outbox.md; this tag is the architect
+  // saying where it applies, and payment-service's ARCH-PAY-OUTBOX is the team
+  // saying it is met. Applied to the edge rather than to the service, because
+  // an outbox is a property of publishing, and payment-service also calls an
+  // API that owes nothing of the kind.
+  tag obl-outbox
+}
+
+model {
+  customer = person 'Customer'
+
+  // Our own fleet, drawn inside a boundary the way ordinary grouped C4 is. The
+  // group has no `metadata { service }` and no directory under services/: it is
+  // scenery for the reader, and every check below resolves through it to the
+  // element that really stands for each service.
+  marketplace = group 'Marketplace' {
+    description 'Everything this organisation runs'
+
+    checkoutWeb = softwareSystem 'checkout-web' {
+      description 'Customer-facing checkout UI'
+      metadata {
+        service 'checkout-web'
+      }
+    }
+    orderService = softwareSystem 'order-service' {
+      description 'Owns the order lifecycle'
+      metadata {
+        service 'order-service'
+      }
+    }
+    paymentService = softwareSystem 'payment-service' {
+      description 'Owns payment authorization/capture'
+      metadata {
+        service 'payment-service'
+      }
+    }
+    identityService = softwareSystem 'identity-service' {
+      description 'Issues and introspects access tokens'
+      metadata {
+        service 'identity-service'
+      }
+    }
+    notificationService = softwareSystem 'notification-service' {
+      description 'Turns events into customer email and push'
+      metadata {
+        service 'notification-service'
+      }
+    }
+  }
+
+  kafka = softwareSystem 'kafka' {
+    // Not one of ours: no services/kafka/ is expected, and none is asked for.
+    #external
+    // Three of our services reach it, which is exactly the count at which the
+    // untagged version of this element becomes `landscape.platform-candidate`.
+    #platform
+    description 'Event backbone'
+    // Edges point HERE, not at the broker. Two producers make no difference;
+    // sixty do — a broker drawn as one element is the node every service in the
+    // fleet points at, and a view over it is a star nobody can read. The topic
+    // is also the truer target: what a producer and a consumer share is the
+    // channel, never the server it happens to live on.
+    paymentEvents = topic 'payment.events'
+    orderEvents = topic 'order.events'
+    crmEvents = topic 'crm.events'
+  }
+
+  stripe = softwareSystem 'stripe' {
+    #external
+    description 'Card acquirer'
+  }
+
+  salesforce = softwareSystem 'salesforce' {
+    #external
+    description 'CRM of record — the fleet reads its events and writes none'
+  }
+
+  customer -> marketplace.checkoutWeb 'Uses'
+
+  // The synchronous spine. Every one of these resolves against the TARGET's
+  // openapi.yaml: `loam validate` fails the fleet when an `op` names an
+  // operation the callee does not define ('spine.op-undefined`), which is what
+  // turns a rename in one repository into a red build in the one that depended
+  // on it.
+  marketplace.checkoutWeb -> marketplace.orderService 'Calls createOrder' {
+    metadata {
+      op 'createOrder'
+    }
+  }
+  marketplace.checkoutWeb -> marketplace.orderService 'Calls getOrder' {
+    metadata {
+      op 'getOrder'
+    }
+  }
+  // Deliberately unlinked, and the example's demonstration of
+  // 'spine.op-link-missing` (warn): an edge whose title starts with "Call" and
+  // carries no `metadata { op }` is drawn but joined to nothing, so no check can
+  // tell whether the operation behind it still exists. Every other call edge
+  // here carries its op; this one is what the warning looks like.
+  marketplace.checkoutWeb -> marketplace.paymentService 'Calls the payment API'
+  marketplace.orderService -> marketplace.paymentService 'Calls authorizePayment' {
+    metadata {
+      op 'authorizePayment'
+    }
+  }
+  marketplace.orderService -> marketplace.identityService 'Calls introspectToken' {
+    metadata {
+      op 'introspectToken'
+    }
+  }
+  // The other half of the deprecation story, and the example's
+  // 'spine.op-deprecated` (warn): identity-service still DEFINES validateToken,
+  // so the contract holds and this is not an error — but its OpenAPI marks the
+  // operation `deprecated: true`, and this edge is the consumer that has not
+  // migrated yet. The warning is addressed to payment-service, not to identity.
+  marketplace.paymentService -> marketplace.identityService 'Calls validateToken' {
+    metadata {
+      op 'validateToken'
+    }
+  }
+  // An edge into a system nobody owns a directory for. It carries no `op`
+  // because there is no contract in this repository to resolve one against, and
+  // it raises no warning because its title does not claim to be a call into a
+  // fleet service.
+  marketplace.paymentService -> stripe 'Authorizes cards'
+
+  // The event spine, the async mirror of `metadata { op }`: the name must be a
+  // message the PRODUCER's own asyncapi.yaml declares an `action: send` for, or
+  // 'spine.message-undefined` fires. A consumer's edge carries
+  // `metadata { consumes }` instead, and its name has to have a producer
+  // SOMEWHERE in the fleet — the one check no single repository can answer.
+  //
+  // THE ARROW FOLLOWS THE MESSAGE, and that is load-bearing rather than
+  // aesthetic. `publishes` binds the edge's SOURCE and `consumes` binds its
+  // TARGET, so a consume edge drawn the other way round — `orderService ->
+  // kafka.paymentEvents` — binds to nothing at all: the metadata parses, the
+  // document validates, and the check silently grades zero edges. Producer to
+  // topic, topic to consumer, every time.
+  marketplace.paymentService -> kafka.paymentEvents 'Publishes PaymentAuthorized' {
+    #obl-outbox
+    metadata {
+      publishes 'payment.PaymentAuthorized'
+    }
+  }
+  marketplace.paymentService -> kafka.paymentEvents 'Publishes PaymentCaptured' {
+    metadata {
+      publishes 'payment.PaymentCaptured'
+    }
+  }
+  kafka.paymentEvents -> marketplace.orderService 'PaymentAuthorized advances the order' {
+    metadata {
+      consumes 'payment.PaymentAuthorized'
+    }
+  }
+  marketplace.orderService -> kafka.orderEvents 'Publishes OrderPlaced' {
+    metadata {
+      publishes 'order.OrderPlaced'
+    }
+  }
+  marketplace.orderService -> marketplace.paymentService 'Calls refundPayment' {
+    metadata { op 'refundPayment' }
+  }
+  kafka.orderEvents -> marketplace.notificationService 'OrderPlaced triggers the confirmation' {
+    metadata {
+      consumes 'order.OrderPlaced'
+    }
+  }
+  kafka.paymentEvents -> marketplace.notificationService 'PaymentCaptured triggers the receipt' {
+    metadata {
+      consumes 'payment.PaymentCaptured'
+    }
+  }
+  kafka.paymentEvents -> marketplace.notificationService 'PaymentRefunded triggers the refund notice' {
+    metadata {
+      consumes 'payment.PaymentRefunded'
+    }
+  }
+  // A producer OUTSIDE the fleet, expressed rather than left implicit. Without
+  // this edge notification-service's `consumes 'crm.CustomerUpdated'` would be
+  // 'spine.message-unproduced` (error) — nobody in the fleet declares it is
+  // sent — and the exit ramp people take from that error is deleting the link.
+  // The edge moves the contract question to the one file that can settle it:
+  // the consumer's own asyncapi.yaml, which must define the payload
+  // ('spine.message-external` fires while it does not).
+  salesforce -> kafka.crmEvents 'Publishes CustomerUpdated' {
+    metadata {
+      publishes 'crm.CustomerUpdated'
+    }
+  }
+  kafka.crmEvents -> marketplace.notificationService 'CustomerUpdated refreshes contact details' {
+    metadata {
+      consumes 'crm.CustomerUpdated'
+    }
+  }
+}
+
+// Views are LikeC4's renderer's, never loam's — nothing below is read by any
+// check. Three of them rather than one `include *`, because at fleet scale a
+// single view holding every call is both the slow one to compute and the one
+// nobody can read: the synchronous map, the event spine and the platform
+// dependencies answer different questions and belong on different pages.
+views {
+  view landscape {
+    title 'Fleet — calls between our own services'
+    include *
+    exclude element.tag = #external
+  }
+
+  view events {
+    title 'Fleet — the event spine'
+    include kafka, kafka.*, * -> kafka.*, kafka.* -> *
+  }
+
+  view platform {
+    title 'Fleet — who depends on shared infrastructure'
+    include element.tag = #platform, * -> element.tag = #platform
+  }
+}

package/examples/docs/architecture/obligations.yaml

@@ -0,0 +1,23 @@
+# The fleet's ARCHITECTURAL OBLIGATIONS: rules an architect decided once and
+# applies where they apply. The decision itself lives in an ADR; a `#obl-<id>`
+# tag on architecture/landscape.likec4 says WHERE it holds; and the owning
+# team's `Covers:` line in its arch.spec.md says it is met, with a scenario.
+#
+# The three grades this file earns are the point of declaring names at all: a
+# tag naming nothing here is `obligation.unknown` (error — a typo reads exactly
+# like a rule), a name nothing tags is `obligation.unapplied` (warn), and a
+# tagged object no living requirement covers is `obligation.uncovered` (warn).
+#
+# An id is its own tag suffix, so it may hold letters, digits, `_` and `-` only.
+obligations:
+  outbox:
+    description: >-
+      A service that publishes a domain event writes the event and the state
+      change it reports in one transaction, relayed to the broker afterwards —
+      never a dual write.
+    adr: architecture/adrs/0001-transactional-outbox.md
+  idempotency-key:
+    description: >-
+      A write a caller may retry accepts an idempotency key and returns the
+      first result for a repeat. Declared and applied nowhere yet, which is
+      what `obligation.unapplied` is for.

package/examples/docs/architecture/permissions.yaml

@@ -0,0 +1,50 @@
+# The fleet's authorization vocabulary, joined to requirements by `Requires:`.
+#
+# Opt-in: a fleet with no `Requires:` line owes no file at all. The first such line makes an
+# absent declaration an error rather than letting each service invent a permission locally,
+# which is how one capability ends up spelled three ways across three repositories.
+#
+# The unit is the pair `<subject>/<permission>`. The subject is the entity the check is
+# performed ON — `user` for a customer acting on their own data, `service` for a fleet service
+# acting on its own behalf — not necessarily the caller. `loam validate` grades exactly two
+# things here: that every `Requires:` pair is declared (`permissions.unknown`, error), and that
+# every declared pair is named by some requirement (`permissions.unenforced`, warning — the
+# authorization mirror of `api.ungoverned`).
+#
+# `owned_by` and `enforced_by` are explanatory and are NOT resolved against services/. This is a
+# spelling and coverage join, not an identity-provider audit: nothing here proves the running
+# system implements a declared permission, and pretending otherwise would be the most dangerous
+# green tick in the repository.
+subjects:
+  user:
+    description: a human account acting on its own data
+  service:
+    description: a fleet service acting on its own behalf, with a machine token
+
+permissions:
+  user:
+    payments:refund:
+      description: refund a captured payment
+      owned_by: identity-service
+      enforced_by: [payment-service]
+    orders:cancel:
+      description: cancel an order that has not shipped
+      owned_by: identity-service
+      enforced_by: [order-service]
+    # Declared, and named by no requirement anywhere in the fleet — the example's
+    # `permissions.unenforced` (warning) demonstration. It is the shape a vocabulary drifts
+    # into: a permission survives the feature that introduced it, the requirement that needed
+    # it is rewritten, and the declaration stays behind looking enforced.
+    profile:read:
+      description: read a customer's own profile
+      owned_by: identity-service
+      enforced_by: [identity-service]
+  service:
+    payments:capture:
+      description: capture funds a previous authorization reserved
+      owned_by: identity-service
+      enforced_by: [payment-service]
+    tokens:introspect:
+      description: ask identity-service what a token currently grants
+      owned_by: identity-service
+      enforced_by: [identity-service]

package/examples/docs/architecture/subsystems.likec4

@@ -0,0 +1,11 @@
+// generated by loam — the subsystem tree under services/, one view per subsystem.
+// Do not edit: `loam subsystem sync` regenerates this file from the directories,
+// and `loam validate --all` reports `subsystem.views-stale` when it drifts.
+
+views {
+  // services/platform
+  view subsystem_platform {
+    include marketplace.identityService
+    include marketplace.notificationService
+  }
+}