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

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/services.likec4

@@ -0,0 +1,70 @@
+// generated by loam — one overview view per service under services/, drawn from the fleet map.
+// Do not edit: `loam subsystem sync` regenerates this file from the directories and the map,
+// and `loam validate --all` reports `subsystem.views-stale` when it drifts.
+// A navigation aid, not the fleet's architecture: author your own diagrams elsewhere.
+
+views {
+  view service_checkout_2dweb of marketplace.checkoutWeb {
+    title 'checkout-web'
+    include *
+    include customer
+    include marketplace.orderService
+    include marketplace.paymentService
+    exclude * -> *
+    include -> marketplace.checkoutWeb
+    include marketplace.checkoutWeb ->
+    include marketplace.checkoutWeb.* -> marketplace.checkoutWeb.*
+  }
+
+  view service_identity_2dservice of marketplace.identityService {
+    title 'Platform / identity-service'
+    include *
+    include marketplace.orderService
+    include marketplace.paymentService
+    exclude * -> *
+    include -> marketplace.identityService
+    include marketplace.identityService ->
+    include marketplace.identityService.* -> marketplace.identityService.*
+  }
+
+  view service_notification_2dservice of marketplace.notificationService {
+    title 'Platform / notification-service'
+    include *
+    include kafka.crmEvents
+    include kafka.orderEvents
+    include kafka.paymentEvents
+    include notificationProvider
+    exclude * -> *
+    include -> marketplace.notificationService
+    include marketplace.notificationService ->
+    include marketplace.notificationService.* -> marketplace.notificationService.*
+  }
+
+  view service_order_2dservice of marketplace.orderService {
+    title 'order-service'
+    include *
+    include kafka.orderEvents
+    include kafka.paymentEvents
+    include marketplace.checkoutWeb
+    include marketplace.identityService
+    include marketplace.paymentService
+    exclude * -> *
+    include -> marketplace.orderService
+    include marketplace.orderService ->
+    include marketplace.orderService.* -> marketplace.orderService.*
+  }
+
+  view service_payment_2dservice of marketplace.paymentService {
+    title 'payment-service'
+    include *
+    include kafka.paymentEvents
+    include marketplace.checkoutWeb
+    include marketplace.identityService
+    include marketplace.orderService
+    include stripe
+    exclude * -> *
+    include -> marketplace.paymentService
+    include marketplace.paymentService ->
+    include marketplace.paymentService.* -> marketplace.paymentService.*
+  }
+}

package/examples/docs/architecture/subsystems.likec4

@@ -0,0 +1,18 @@
+// 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.
+// A scoping aid, not the fleet's architecture: author your own diagrams elsewhere.
+
+views {
+  // services/platform
+  // model: no boundary — marketplace also holds services outside this subsystem.
+  view subsystem_platform {
+    title 'Platform'
+    description 'Cross-cutting identity and messaging'
+    include marketplace.identityService
+    include marketplace.notificationService
+
+    include marketplace.identityService -> *, * -> marketplace.identityService
+    include marketplace.notificationService -> *, * -> marketplace.notificationService
+  }
+}

package/examples/docs/architecture/usecases/order-notification.likec4

@@ -0,0 +1,74 @@
+// A fleet use case: the ordered hops that fulfil one business capability.
+//
+// This file is the whole shape of the axis. A `dynamic view` tagged
+// `#cap-<slug>` opts in to grading — so does one tagged only `#req-` or only
+// `#suite-<name>`, the suite a journey runs with (`loam list suites`); an
+// untagged one is somebody's hand-drawn diagram and loam never says a word
+// about it. The slug is the capability id
+// from architecture/capabilities.yaml with every `/` flattened to `-`, because
+// a LikeC4 tag name cannot carry a slash — `identity/tokens` would be
+// `#cap-identity-tokens`.
+//
+// It lives in its own file rather than in architecture/landscape.likec4 for a
+// reason that is about people, not parsing: the map belongs to whoever owns the
+// fleet's topology, and a flow changes when a business need changes. Different
+// reasons to edit are different files. The whole `architecture/` directory is
+// read as ONE LikeC4 project, so the steps below resolve against the landscape's
+// elements even though this file declares none — which also means exactly one
+// file in this directory declares the `specification` block, and it is not this
+// one. (The renderer's root project is WIDER than what loam grades here: it also
+// holds every `services/<svc>/model.likec4`, because each of them extends the
+// map. A tag declared twice across that whole set is `c4.fleet-project-invalid`,
+// which is why a tag belongs in the landscape's one block.)
+//
+// THE TAG MUST BE THE FIRST THING IN THE VIEW BODY. Written after `title` it is
+// five parse errors, none of which mentions tags. That is the mistake every
+// author makes once.
+//
+// ---------------------------------------------------------------------------
+//
+// Two things about this particular flow are worth reading before you copy it.
+//
+// The first hop is a PERSON, and it is here on purpose: `customer ->
+// checkoutWeb` is backed by a real edge that carries no `metadata { op }`, and
+// checkout-web is a real services/ directory — so every condition of
+// `usecase.step-unlinked` is met except the one that matters, which is that a
+// person is not a caller. Somebody clicking a button owes no operationId. Delete
+// that exemption from the checker and this file is what notices: the example
+// fleet's warning count moves from ten to eleven and test/examples.test.ts
+// fails.
+//
+// The hop from checkout-web to order-service is DELIBERATELY NOT DRAWN, and its
+// absence is the more useful half of the lesson. The landscape declares two
+// edges for that pair — `Calls createOrder` and `Calls getOrder` — so a step
+// between those two elements names two operations, and loam refuses to guess
+// which one the flow exercises: `usecase.step-contested` (warn), listing both
+// candidates. That is the check working. The fix is the one the message offers
+// first: say which operation the hop means by opening the step's title with it,
+// then punctuation — `marketplace.checkoutWeb -> marketplace.orderService
+// 'createOrder — creates the order'` — and loam attributes the hop to that edge.
+// (The other fix is to give the candidates one operation between them.)
+
+views {
+  dynamic view uc_order_notification {
+    #cap-order-notifications
+    #req-NOTIFY-ONCE
+    #suite-smoke
+    #suite-notifications
+    title 'Order notification'
+    description 'A placed order reaches the customer as exactly one confirmation'
+
+    // A person, not a caller — see above.
+    customer -> marketplace.checkoutWeb 'places the order'
+
+    // Producer to topic: the edge carries `publishes`, so the hop reaches a
+    // declared API — an AsyncAPI one — and loam does not also demand an HTTP
+    // operationId for it. The event spine grades this edge on its own terms.
+    marketplace.orderService -> kafka.orderEvents 'announces OrderPlaced'
+
+    // Topic to consumer, the same exemption from the other side. Modelling the
+    // TOPIC rather than the broker is what keeps this readable: an edge into
+    // `kafka` itself would put every service in the fleet on one node.
+    kafka.orderEvents -> marketplace.notificationService 'sends the confirmation'
+  }
+}

package/examples/docs/capabilities/checkout/spec.md

@@ -0,0 +1,55 @@
+# Checkout
+
+The customer has chosen what to buy and now wants to be done. Everything from
+the filled cart to the confirmed, paid [order](../../glossary/order.md) is this
+capability: the prices they were shown, the money leaving their card exactly
+once, and the confirmation that tells them it worked. Exactly once means one
+[authorization](../../glossary/payments/authorization.md), which is a word this
+fleet uses in one sense and writes down.
+
+This narrative slot is why the tree exists at all. `architecture/capabilities.yaml`
+can declare the word `checkout` and nothing more; the paragraph above is what a
+business analyst actually writes, and before this file there was nowhere in a
+loam docs repo to put it. It is also the loam equivalent of OpenSpec's
+`## Purpose` prose, which the migrator used to drop into `legacy/`.
+
+The requirements below are the analyst's, and each one is a promise a customer
+could check from outside — no operationId, no element id, no message name, and
+no service named. That is the rule the tree is held to, and half of it is
+checked: `Operations:`, `Covers:`, `Publishes:` and `Consumes:` are refused here
+(`capability.requirement-service-scoped`), while "names no service" is an
+authoring rule this file keeps and pull-request review holds, because matching
+service names in prose would be a heuristic and loam does not guess.
+
+Which services carry which part of this is not written here and must not be:
+that is the fleet map's question, and `loam list capabilities` answers it from
+the `Capability:` lines the service specs already carry.
+
+## Requirements
+
+### Requirement: A confirmed order charges the customer exactly once
+Requirement-ID: CHECKOUT-CHARGE-ONCE
+The fleet SHALL charge a customer at most once for a single confirmed order,
+and SHALL confirm an order only after that charge has been authorized.
+
+#### Scenario: The customer submits the same order twice
+- **Given** a customer who has confirmed an order
+- **When** they submit the same order again without changing it
+- **Then** they are shown the order they already placed
+- **And** their card is charged only for the first one
+
+#### Scenario: Authorization is declined
+- **Given** a customer whose card is declined
+- **When** they confirm the order
+- **Then** no order is confirmed
+- **And** they are told the payment did not go through
+
+### Requirement: The price shown is the price charged
+Requirement-ID: CHECKOUT-PRICE-HONOURED
+The fleet SHALL charge the total the customer was shown at the moment they
+confirmed, even if a price changes while the order is being placed.
+
+#### Scenario: A price changes mid-checkout
+- **Given** a customer looking at a total of 40.00
+- **When** the price of an item rises before they confirm
+- **Then** confirming still charges 40.00

package/examples/docs/capabilities/identity/tokens/spec.md

@@ -0,0 +1,42 @@
+# Identity tokens
+
+Somebody signs in once and stays signed in for a while; the fleet has to keep
+answering "is this still them?" without asking again, and has to stop answering
+yes the moment it should not.
+
+This file also demonstrates NESTING, which is the part of the tree that is easy
+to get wrong when reading the layout. The id is `identity/tokens` — one id, with
+the slash inside it, exactly as `architecture/capabilities.yaml` spells the key
+and exactly as a requirement's `Capability:` line writes it. The tree does not
+collapse it and does not invent a separator: the id's own slashes ARE the
+directories, so the document lives at `capabilities/identity/tokens/spec.md`.
+
+`capabilities/identity/` therefore holds no `spec.md` of its own, and that earns
+no finding: a directory with a capability beneath it is a group. It would earn
+`capability.doc-missing` only if it held neither a document nor anything below.
+If the fleet later decides that `identity` is a capability in its own right,
+adding `capabilities/identity/spec.md` makes it one — a directory may be both a
+capability and the parent of others, because that is what the ids already say.
+
+## Requirements
+
+### Requirement: A revoked session stops working everywhere
+Requirement-ID: IDENTITY-REVOKE-EVERYWHERE
+When a person's session is revoked, the fleet SHALL stop honouring it — in
+every part of the product, not only the one they revoked it from.
+
+#### Scenario: Signing out of a lost phone
+- **Given** a person signed in on two devices
+- **When** they sign out one of them from the other
+- **Then** the signed-out device can no longer act as them
+
+### Requirement: A refused sign-in never says which half was wrong
+Requirement-ID: IDENTITY-ONE-REFUSAL
+When a sign-in is refused, the fleet SHALL give the same answer whether the
+account does not exist or the secret was wrong — a refusal that tells them apart
+lets anyone test which accounts exist.
+
+#### Scenario: An account that does not exist
+- **Given** a sign-in attempt for an account nobody has registered
+- **When** it is refused
+- **Then** the refusal is word for word the one a wrong password gets

package/examples/docs/capabilities/order-notifications/spec.md

@@ -0,0 +1,43 @@
+# Order notifications
+
+The customer has bought something and now wants to know it worked. Every event
+in an [order](../../glossary/order.md)'s life that they would want to hear about
+reaches them, once.
+
+This capability carries the example's demonstration of the axis's second
+realizer, and it is the reason the tree exists at all. The promise below is
+**cross-service by construction**: an order is placed in one service, the event
+crosses a broker, and a third service sends the message. No single service's
+`spec.md` can promise "exactly one confirmation", because each of them promises
+only its own part — `order-service` promises to announce the order,
+`notification-service` promises to send what it receives, and neither can
+promise what happens between them.
+
+A USE CASE can, because it IS the hop sequence. So
+`architecture/usecases/order-notification.likec4` carries `#req-NOTIFY-ONCE`
+beside its `#cap-order-notifications` tag, and that tag is the architect's
+answer to this promise: these hops, in this order, are what keeps it. loam
+grades the claim down to the operation, and `capability.requirement-unrealized`
+stays silent for this requirement because a flow keeps it.
+
+Written with no `Operations:`, `Covers:`, `Publishes:` or `Consumes:` line —
+those resolve against one service's own contract, and a capability requirement
+must be observable from outside the fleet.
+
+## Requirements
+
+### Requirement: A placed order produces exactly one confirmation
+Requirement-ID: NOTIFY-ONCE
+The fleet SHALL send a customer exactly one confirmation for an order they
+placed — not none if a service restarts mid-flight, and not two if a message is
+delivered twice.
+
+#### Scenario: The order is placed and the customer is told
+- **Given** a customer who has just placed an order
+- **When** the order is accepted
+- **Then** they receive one confirmation naming that order
+
+#### Scenario: The same event arrives twice
+- **Given** a confirmation already sent for an order
+- **When** the same event is delivered again
+- **Then** the customer receives nothing further

package/examples/docs/features/FEAT-101-payment-splitting/adrs/0001-dedicated-split-service.md

@@ -0,0 +1,18 @@
+---
+id: ADR-FEAT-101-0001
+status: accepted
+date: 2026-07-20
+feature: FEAT-101
+---
+
+# 1. Introduce a dedicated payment-split-service
+
+## Context
+Splitting logic is non-trivial and will be reused beyond checkout.
+
+## Decision
+Create a new bounded-context service `payment-split-service` rather than embedding the logic in `payment-service`.
+
+## Consequences
+- +1 service to operate, with clean ownership.
+- `payment-service` gains a synchronous dependency — modeled as `criticality: degradable` in its `health.yaml`.

package/examples/docs/features/FEAT-101-payment-splitting/delta.likec4

@@ -0,0 +1,94 @@
+// C4 DELTA for FEAT-101 — new/changed elements + relationships tagged #FEAT-101.
+// Self-contained so it validates on its own; loam projects the #FEAT-101 subset per service.
+//
+// The tag is loam's ONLY way of seeing the delta: a file that declares elements or
+// relationships with none carrying `#FEAT-101` is `delta.nothing-tagged` (error), because
+// everything in it would be invisible to the checks and the archive would merge nothing.
+specification {
+  element group
+  element softwareSystem
+  element container
+  element topic {
+    #external
+    #platform
+  }
+  tag external
+  tag platform
+  tag FEAT-101
+}
+
+model {
+  // Existing elements, referenced for context and left untagged — archive merges only what
+  // carries the feature tag, so quoting the neighbourhood costs nothing.
+  //
+  // The new service is declared INSIDE the group the landscape already draws, which is where
+  // archive splices it: a nested element lands inside its parent's block, never as a flat
+  // dotted id, which LikeC4 rejects at top level.
+  marketplace = group 'Marketplace' {
+    checkoutWeb = softwareSystem 'checkout-web'
+    paymentService = softwareSystem 'payment-service'
+
+    paymentSplitService = softwareSystem 'payment-split-service' {
+      #FEAT-101
+      description 'Splits a payment across payees'
+      // The binding, not the title, is what ties this element to the
+      // `services/payment-split-service/` directory archive will create. A
+      // title works too and is what most existing repositories rely on — and
+      // it is also the trap: rename the box in a diagram and every check that
+      // joined it to its directory silently stops matching.
+      metadata {
+        service 'payment-split-service'
+      }
+
+      api = container 'api' {
+        technology 'Spring Boot'
+      }
+    }
+  }
+
+  // The broker AND the topic the new edge points at, both already in the
+  // landscape: a delta references the channel, never the server, so the merged
+  // map does not grow one more spoke on a hub.
+  kafka = softwareSystem 'kafka' {
+    #external
+    #platform
+    paymentEvents = topic 'payment.events'
+  }
+
+  marketplace.paymentService -> marketplace.paymentSplitService 'Calls createSplit' {
+    #FEAT-101
+    metadata { op 'createSplit' }
+  }
+  // Read back at capture time: settlement needs the shares the split recorded.
+  marketplace.paymentService -> marketplace.paymentSplitService 'Calls getSplit' {
+    #FEAT-101
+    metadata { op 'getSplit' }
+  }
+  // The one tagged addition this feature leaves uncovered, on purpose: no
+  // `Covers:` line in any of its arch.spec.md deltas names it, so
+  // `c4.uncovered` (warn) says the architectural obligations behind this call
+  // ship untested. A `Covers: checkout-web -> payment-split-service` line
+  // would close it — and would also close the edge above, since an edge entry
+  // resolves by ENDPOINT, so two edges between one pair are one target.
+  marketplace.checkoutWeb -> marketplace.paymentSplitService 'Calls createSplit' {
+    #FEAT-101
+    metadata { op 'createSplit' }
+  }
+  // Drawn with the message in its title and no `metadata { publishes }`, deliberately: the
+  // metadata is a JOIN, and the join demands a contract — an edge publishing a message its
+  // bound service's contract (feature ∪ living) declares no send for is refused as
+  // `c4-event.message-undefined`. The async axis has the full feature lifecycle
+  // (`specs/payment-service/asyncapi.yaml` beside this delta is its demonstration — the
+  // living contract restated under `loam rebase` pins, plus a new producer side), but
+  // payment-split-service's own contract is deferred until the consumer of `PaymentSplit`
+  // exists, so the edge stays title-only rather than pointing at a contract nobody wrote.
+  marketplace.paymentSplitService -> kafka.paymentEvents 'Publishes PaymentSplit' {
+    #FEAT-101
+  }
+}
+
+views {
+  view feat_101 {
+    include *
+  }
+}

package/examples/docs/features/FEAT-101-payment-splitting/intent.md

@@ -0,0 +1,44 @@
+---
+feature: FEAT-101
+title: Payment splitting
+status: in_progress          # proposed -> in_progress -> built -> done
+owner: payments-team
+services: [payment-service, payment-split-service, checkout-web]
+---
+
+# FEAT-101 — Payment splitting
+
+## Why
+Marketplaces need to split one customer payment across multiple payees (sellers). Today a
+seller is paid by a separate transfer run reconciled by hand at the end of the day, which is
+where every payout dispute this quarter came from: the customer's payment and the sellers'
+shares are two records nothing joins.
+
+This file is where the "why" lives, and the archive gate holds it to that: the delta says what
+changed, and nothing else says what for. A feature whose `intent.md` is missing, or says nothing
+outside the scaffold's own comments, is refused by `intent.empty` — a warning that gates, so a
+change cannot fold into the living docs with its reason unwritten.
+
+## Business acceptance
+- A customer can split a payment across 2+ payees before confirming.
+- Each payee receives their share; the shares sum to the total.
+- A split that does not sum to the total is refused, and the customer is told which shares are
+  in play — a silent rounding fix is a payout dispute six weeks later.
+
+## Architectural summary
+New `payment-split-service`; `payment-service` and `checkout-web` call it; it publishes
+`PaymentSplit`. UI adds a split-payment page in `checkout-web`. See `delta.likec4`, and
+`adrs/0001-dedicated-split-service.md` for why the logic is not folded into `payment-service`.
+
+## Not in this feature
+Payouts themselves. A split records who is owed what; moving the money is separate work, and
+deliberately not smuggled in here — a feature whose intent and whose delta describe different
+scopes is one nobody can review as a diff.
+
+The `PaymentSplit` event is drawn in `delta.likec4` with the message in its title and no
+contract join yet — deliberately, not for lack of machinery. The async axis has the full
+feature lifecycle, and this feature's `specs/payment-service/asyncapi.yaml` is its
+demonstration: the living contract restated under `loam rebase`'s pins, plus the new
+`payment.PaymentSplitAuthorized` producer side the archive will merge. The split service's own
+contract is deferred until a consumer of `PaymentSplit` exists, and the edge stays unjoined
+rather than pointing at a contract nobody wrote.

package/examples/docs/features/FEAT-101-payment-splitting/specs/checkout-web/spec.md

@@ -0,0 +1,21 @@
+# checkout-web — requirement delta for FEAT-101
+
+## ADDED Requirements
+
+### Requirement: Split payment on checkout
+
+Requirement-ID: WEB-SPLIT
+The UI SHALL let a customer split a payment across two or more payees before confirming, and
+SHALL show the recorded split back to them before the payment is taken.
+
+#### Scenario: Customer splits a payment across two payees
+- **Given** a payment of 100.00 USD
+- **When** the customer assigns 60.00 to "seller-x" and 40.00 to "seller-y"
+- **And** confirms
+- **Then** `createSplit` is called on `payment-split-service`
+- **And** the split is shown as confirmed
+
+#### Scenario: A split that does not sum to the total cannot be confirmed
+- **Given** a payment of 100.00 USD
+- **When** the customer assigns 60.00 to "seller-x" and 30.00 to "seller-y"
+- **Then** the confirm control stays disabled and the remaining 10.00 is shown as unassigned