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

package/examples/docs/features/archive/FEAT-120-refund-notification/specs/payment-service/asyncapi.yaml

@@ -0,0 +1,137 @@
+# The async contract — the messages this service puts on the bus.
+#
+# AsyncAPI 3.0 only. Its operations are named top-level objects carrying
+# `action: send|receive`, which is what makes a message's direction legible;
+# 2.x spells the same thing as publish/subscribe under a channel, where the
+# two words are ambiguous about whose perspective they take.
+#
+# 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, a non-JSON
+# `schemaFormat` is skipped) — which is what keeps swapping JSON Schema for
+# Avro a `schemaFormat` line here rather than a change in loam.
+#
+# The name is the spine: the landscape edge's `metadata { publishes }`, the
+# requirement's `Publishes:` line and `name` below are one name spelled three
+# times, and they must be identical.
+asyncapi: 3.0.0
+info:
+  title: payment-service events
+  version: "1.0"
+
+channels:
+  paymentEvents:
+    address: payment.events.v1
+    description: Payment lifecycle events, published by the outbox relay
+    messages:
+      PaymentAuthorized:
+        $ref: '#/components/messages/PaymentAuthorized'
+      PaymentCaptured:
+        $ref: '#/components/messages/PaymentCaptured'
+      # NEW: the refund rides the existing lifecycle topic rather than one of
+      # its own — a consumer already filtering payment.events for a capture is
+      # the same consumer that wants the refund.
+      PaymentRefunded:
+        $ref: '#/components/messages/PaymentRefunded'
+    x-loam-based-on: 036cbb7e0245e1a9
+
+operations:
+  sendPaymentAuthorized:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentAuthorized'
+    x-loam-based-on: 72934fd7ed7f6df9
+  sendPaymentCaptured:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentCaptured'
+    x-loam-based-on: 01ac447e38a868cc
+  # NEW: announced once, and only after the acquirer has reconciled.
+  sendPaymentRefunded:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentRefunded'
+
+components:
+  messages:
+    # NEW: the money is back and the acquirer agrees. `refundedAmount` is what
+    # the refund actually returned, which is not always the captured amount —
+    # a partial refund is the same event with a smaller number.
+    PaymentRefunded:
+      name: payment.PaymentRefunded
+      title: Payment refunded
+      payload:
+        type: object
+        required: [ paymentId, orderId, refundedAmount, currency, refundedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          refundedAmount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          refundedAt:
+            type: string
+            format: date-time
+    PaymentAuthorized:
+      # Namespaced by the domain that owns it. One message has exactly one
+      # producer: two services declaring they send this name is
+      # `asyncapi.message-contested`, and then which contract a consumer reads
+      # is a coin flip.
+      name: payment.PaymentAuthorized
+      title: Payment authorized
+      # JSON Schema today, because this fleet runs no schema registry. An Avro
+      # record here later needs a `schemaFormat:` line and no other change:
+      # everything below is opaque to loam.
+      payload:
+        type: object
+        required: [ paymentId, orderId, amount, currency, authorizedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          amount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          authorizedAt:
+            type: string
+            format: date-time
+      x-loam-based-on: 0e5a230802d1573b
+    PaymentCaptured:
+      name: payment.PaymentCaptured
+      title: Payment captured
+      payload:
+        type: object
+        required: [ paymentId, orderId, capturedAmount, currency, capturedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          capturedAmount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          capturedAt:
+            type: string
+            format: date-time
+      x-loam-based-on: 449d5409ccf1b59f

package/examples/docs/features/archive/FEAT-120-refund-notification/specs/payment-service/spec.md

@@ -0,0 +1,31 @@
+# payment-service — requirement delta for FEAT-120
+
+## MODIFIED Requirements
+
+### Requirement: Refund a captured payment
+
+Requirement-ID: PAY-REFUND
+Based-On: 0d5b4ce25f5b07ae
+The service SHALL return captured funds to the customer's payment method, SHALL reconcile the
+refund against the acquirer before reporting it complete, and SHALL refuse a second refund of a
+payment it has already refunded.
+
+Operations: refundPayment
+Publishes: payment.PaymentRefunded
+Requires: user/payments:refund
+
+#### Scenario: Refund a captured payment in full
+- **Given** a captured payment of 100.00 USD
+- **When** a refund is requested for it
+- **Then** 100.00 USD is returned to the customer's payment method
+- **And** the payment is recorded as refunded
+
+#### Scenario: A second refund of the same payment is refused
+- **Given** a payment already refunded in full
+- **When** a refund is requested for it again
+- **Then** the request is refused with 409 and no second refund is issued
+
+#### Scenario: The refund is announced only after the acquirer reconciles
+- **Given** a refund accepted by the acquirer but not yet reconciled
+- **When** the reconciliation completes
+- **Then** `payment.PaymentRefunded` is published exactly once for that payment

package/examples/docs/features/archive/FEAT-120-refund-notification/verification.yaml

@@ -0,0 +1,84 @@
+# Verification record for FEAT-120 — written by `loam verify FEAT-120` (--results / --contract-results / --record).
+#
+# Every claim below was derived mechanically from this feature's own artifacts:
+# delta.likec4, specs/<svc>/spec.md, specs/<svc>/arch.spec.md and specs/<svc>/
+# openapi.yaml. Each verdict names who answered it: `answered_by: runner` means a
+# test report's digest-tagged scenarios answered it mechanically — cucumber JSON,
+# or loam's own {"loamScenarioReport": 1, ...} shape that any runner adapts into;
+# `answered_by: external-runner` means a contract-test report's operationId-matched
+# entries did, and `contractReport:` records which file a --contract-results run
+# read; `answered_by: agent` means somebody's word about the code, which loam did
+# not check. Nothing gates on any of them.
+#
+# A `scenario.tested` claim confirmed by an agent is ATTESTED, not run: loam
+# reports it as `verify.scenario-attested` and the feature does not count as
+# verified until a report answers it. `report:` records the file a --results run
+# read — its sha256 and mtime say WHICH file, not that it came from that commit;
+# no digest can say that.
+#
+# `checklist` is a digest of the claim ids. If `loam verify` stops reporting the same
+# one, the feature changed after this was recorded and these answers are stale.
+feature: FEAT-120
+recorded: 2026-08-29
+checklist: 060a0cc49fcb1d64
+summary:
+  claims: 7
+  confirmed: 7
+  unconfirmed: 0
+claims:
+  - id: event.declares-5ba57275
+    kind: event.declares
+    claim: notification-service declares it receives message 'payment.PaymentRefunded'
+    verdict: confirmed
+    answered_by: agent
+    evidence:
+      - internal/consumer/refund.go:18
+    note: the consumer subscribes to payment.events.v1 and dispatches PaymentRefunded to the refund notice renderer
+  - id: event.declares-02a85dfd
+    kind: event.declares
+    claim: payment-service declares it sends message 'payment.PaymentRefunded'
+    verdict: confirmed
+    answered_by: agent
+    evidence:
+      - src/main/java/com/marketplace/payments/outbox/RefundOutboxRelay.java:44
+    note: the outbox relay publishes payment.PaymentRefunded on the acquirer reconciliation callback
+  - id: scenario.tested-6a899c70
+    kind: scenario.tested
+    claim: scenario 'A completed refund is announced once' of requirement 'Notify a customer when a refund completes' (notification-service) is covered by a test
+    verdict: confirmed
+    answered_by: runner
+    evidence:
+      - "docs/features/FEAT-120-refund-notification/scenario-report.json: TestRefundNotice_SendsOnce"
+  - id: scenario.tested-173ff6e0
+    kind: scenario.tested
+    claim: scenario 'The broker redelivers a refund already announced' of requirement 'Notify a customer when a refund completes' (notification-service) is covered by a test
+    verdict: confirmed
+    answered_by: runner
+    evidence:
+      - "docs/features/FEAT-120-refund-notification/scenario-report.json: TestRefundNotice_IgnoresRedelivery"
+  - id: scenario.tested-b8dc0f33
+    kind: scenario.tested
+    claim: scenario 'Refund a captured payment in full' of requirement 'Refund a captured payment' (payment-service) is covered by a test
+    verdict: confirmed
+    answered_by: runner
+    evidence:
+      - "docs/features/FEAT-120-refund-notification/scenario-report.json: RefundPaymentTest#refundsInFull"
+  - id: scenario.tested-75b9e98d
+    kind: scenario.tested
+    claim: scenario 'A second refund of the same payment is refused' of requirement 'Refund a captured payment' (payment-service) is covered by a test
+    verdict: confirmed
+    answered_by: runner
+    evidence:
+      - "docs/features/FEAT-120-refund-notification/scenario-report.json: RefundPaymentTest#refusesSecondRefund"
+  - id: scenario.tested-8aa6f501
+    kind: scenario.tested
+    claim: scenario 'The refund is announced only after the acquirer reconciles' of requirement 'Refund a captured payment' (payment-service) is covered by a test
+    verdict: confirmed
+    answered_by: runner
+    evidence:
+      - "docs/features/FEAT-120-refund-notification/scenario-report.json: RefundOutboxTest#publishesOnceAfterReconciliation"
+report:
+  path: docs/features/FEAT-120-refund-notification/scenario-report.json
+  digest: 602bd905c7a4878195fccb98f2134b6d883c0ef42c33b5d8772aaee067dfa3f5
+  mtime: 2026-08-28T18:49:56.422Z
+  scenarios: 5

package/examples/docs/glossary/order.md

@@ -0,0 +1,15 @@
+# Order
+
+What a customer has committed to buy: a set of items, a total they were shown,
+and the intent to pay it. An order exists from the moment the customer confirms
+— before any money moves, and whether or not the
+[authorization](payments/authorization.md) succeeds.
+
+An order is not a cart. A cart is what the customer is still editing; an order
+is what they have decided. Nothing in the fleet edits an order in place.
+
+The word is used in `capabilities/checkout/spec.md` and
+`capabilities/order-notifications/spec.md`, and the services that carry parts of
+those promises use it in the same sense. That agreement is what a glossary is
+for, and the links to this file are what make it checkable: `glossary.unlinked`
+would name this term the day nothing cited it any more.

package/examples/docs/glossary/payments/authorization.md

@@ -0,0 +1,14 @@
+# Authorization
+
+The card issuer's promise that the money for an [order](../order.md) is there
+and reserved. It is not a payment: no funds have moved, and an authorization
+expires if nothing captures it.
+
+The distinction matters to the business and not only to the payments team. A
+customer whose card was authorized has not been charged, so "we took your money"
+is the wrong thing to tell them — and a confirmed order that was never
+authorized is the failure `checkout#CHECKOUT-CHARGE-ONCE` exists to rule out.
+
+Filed under `glossary/payments/` because the tree spells nesting the way the
+capability tree does: this term's id is `payments/authorization`, and a flat
+directory is not the only shape a growing vocabulary is allowed.

package/examples/docs/likec4.config.json

@@ -0,0 +1,9 @@
+{
+  "name": "fleet",
+  "title": "Fleet landscape",
+  "exclude": [
+    "**/node_modules/**",
+    "services/**",
+    "features/**"
+  ]
+}

package/examples/docs/loam.json

@@ -0,0 +1,3 @@
+{
+  "docsDir": "."
+}

package/examples/docs/services/checkout-web/model.likec4

@@ -0,0 +1,109 @@
+// Per-service C4 for a UI service. A UI is a first-class C4 system: it has
+// containers, it has runtime dependencies, and its pages (ui/pages/*.page.yaml)
+// hang off the operations the edges below name.
+//
+// Every .likec4 file is parsed ON ITS OWN — loam never concatenates them — so
+// this document declares the kinds it uses even though architecture/landscape.likec4
+// declares the same ones. Leaving them out here does not inherit, it fails to parse
+// (`c4.invalid`, an error), and the spec/API joins that read the model go quiet with it.
+specification {
+  element softwareSystem
+  element container
+  element person
+}
+
+model {
+  // The actor belongs in a UI's own model in a way it does not in a backend's:
+  // the pages exist for this person, and the flows in ui/pages/ start at them.
+  // The landscape draws the same customer -> checkout-web edge at fleet scale;
+  // a person is exempt from the service/directory cross-check either way.
+  customer = person 'Customer'
+
+  checkoutWeb = softwareSystem 'checkout-web' {
+    description 'Customer-facing checkout UI'
+
+    spa = container 'spa' {
+      description 'Checkout SPA — cart, payment and order status pages'
+      technology 'React'
+    }
+    // A backend-for-frontend, drawn because it is where the fleet call actually
+    // originates: the browser holds a session cookie, the fleet speaks bearer
+    // tokens, and something has to be the place that translation happens. Drawn
+    // as a container of checkout-web and not as a service of its own, because it
+    // is deployed and released with the SPA and has no consumer but the SPA —
+    // a services/checkout-bff/ would owe a spec, a contract and an owner nobody has.
+    bff = container 'bff' {
+      description 'Backend-for-frontend: session to bearer, response shaping'
+      technology 'Node.js'
+    }
+
+    customer -> spa 'Buys'
+    spa -> bff 'Calls the checkout BFF'
+  }
+
+  // The services this one actually calls. A service model carries everything the
+  // service touches, cross-boundary included, drawn with the edge the service
+  // really has — the landscape carries only the boundary crossing (checkout-web ->
+  // order-service), while the edge below says WHICH container makes the call.
+  // Without these three edges this file would be two boxes and a hop, and
+  // `c4.no-relationships` would be right to say a model that reaches nothing is
+  // almost never true.
+  orderService = softwareSystem 'order-service' {
+    description 'Owns the order lifecycle'
+    // Bind rather than rely on the title. A renamed box silently stops matching
+    // its directory everywhere the two are joined — in the landscape that costs
+    // `landscape.binding-unknown` (error) when the id is wrong, and here it is
+    // what `health.dependency-unmodelled` resolves a declared dependency
+    // through in the services that have a health.yaml. checkout-web has none:
+    // a UI is nobody's runtime dependency, so it declares no SLIs, no alerts
+    // and no dependency graph, and owes no arch.spec.md to cover them.
+    metadata {
+      service 'order-service'
+    }
+  }
+  paymentService = softwareSystem 'payment-service' {
+    description 'Owns payment authorization/capture'
+    metadata {
+      service 'payment-service'
+    }
+  }
+
+  // `metadata { op }` is the C4 half of the operation join: the exact
+  // operationId order-service's openapi.yaml declares. What `loam validate`
+  // grades is the LANDSCAPE's twin of each edge below — `spine.op-undefined`
+  // (error) is what it says there when the id names no operation the callee
+  // defines. Carrying the op here anyway is what keeps the two documents from
+  // drifting into different answers about which operation this container calls;
+  // nothing would catch it if they did. Two calls to one service are two edges,
+  // not one edge with a list — a view has to be able to show that the status
+  // page and the checkout page stand on different operations.
+  checkoutWeb.bff -> orderService 'Calls createOrder' {
+    metadata {
+      op 'createOrder'
+    }
+  }
+  checkoutWeb.bff -> orderService 'Calls getOrder' {
+    metadata {
+      op 'getOrder'
+    }
+  }
+  // Card details go from the browser straight to payment-service and never
+  // through the BFF or order-service, which is why this edge starts at the SPA.
+  // It carries no `metadata { op }` deliberately: its twin in the landscape is
+  // the example's demonstration of `spine.op-link-missing` (warn) — the finding
+  // for an edge that SAYS it calls something and names no operation, so nothing
+  // can check the call still exists. Free here and one warning there, which is
+  // the asymmetry worth knowing: the fleet map is what the spine reads.
+  checkoutWeb.spa -> paymentService 'Calls the payment API'
+}
+
+// Views are the LikeC4 renderer's, never loam's — no check reads this block.
+// Scoped to the system so the page answers "what does the checkout UI stand on"
+// rather than redrawing the fleet, which architecture/landscape.likec4 already does.
+views {
+  view checkout_web of checkoutWeb {
+    title 'checkout-web — containers and the services they call'
+    include *
+    include orderService, paymentService
+  }
+}

package/examples/docs/services/checkout-web/spec.md

@@ -0,0 +1,91 @@
+---
+service: checkout-web
+status: draft
+owner: checkout-team
+---
+
+# checkout-web
+
+The customer-facing checkout SPA. It owns no store and exposes no operations of its own —
+every requirement below is satisfied by calling `order-service` and `payment-service` — which
+is why no requirement here carries an `Operations:` line and why this directory holds no
+`openapi.yaml`. That absence is graded on evidence, not on the file list: `service.no-openapi`
+stays silent because the landscape parses and no op-linked edge points AT checkout-web, so
+nobody is expecting a contract here. A UI in a fleet map that could not be read would get the
+warning instead, because "I could not look" and "nobody calls me" are different facts.
+
+**This spec names no `sources:`, on purpose.** `loam validate` reports `sources.absent`
+against it, and that warning is the point: the UI baseline is not yet tied to code, so nothing
+can tell you when the pages drift from what the SPA actually renders, and `loam vouch` would
+refuse to stamp it. Every other service in this example names the paths in its own repository
+its spec was written from; this one shows what the absence costs — a document that is internally
+consistent, passes every join below, and is answerable to nothing outside itself.
+
+## Requirements
+
+### Requirement: Checkout flow
+
+Requirement-ID: WEB-CHECKOUT
+The UI SHALL carry a customer from a filled cart to a confirmed order in one pass, and SHALL
+show a confirmation only for an order `order-service` has acknowledged — never for one the
+client assumed went through.
+
+Capability: checkout
+Realizes: checkout#CHECKOUT-CHARGE-ONCE
+
+#### Scenario: Complete a checkout
+- **Given** a cart holding at least one line and a payment method the customer has entered
+- **When** the customer confirms the purchase
+- **Then** `createOrder` records the order and `authorizePayment` reserves the funds against it
+- **And** the confirmation shows the order id the API returned, not one the UI minted
+
+#### Scenario: Authorization is refused
+- **Given** a filled cart and a card the issuer declines
+- **When** the customer confirms the purchase
+- **Then** the payment step stays open with the cart, address and delivery choice intact
+- **And** the customer is asked for another payment method rather than being returned to the cart
+
+#### Scenario: The customer submits twice
+- **Given** a checkout that has already sent `createOrder` under an idempotency key
+- **When** the customer presses the confirm button again before the first response arrives
+- **Then** the second request carries the same key and `order-service` answers 409
+- **And** the UI opens the order that already exists instead of starting a second checkout
+
+### Requirement: Show order status
+
+Requirement-ID: WEB-ORDER-STATUS
+The UI SHALL show the current state of an order from `order-service`, and SHALL answer
+identically for an order that does not exist and for one that belongs to somebody else, so a
+guessed id cannot confirm that an order is real.
+
+Capability: checkout
+
+#### Scenario: Show the current state of an order
+- **Given** a placed order the signed-in customer owns
+- **When** the customer opens its status page
+- **Then** the page renders the state `getOrder` returns
+- **And** it does not fall back to the state the checkout flow last saw, stale since capture
+
+#### Scenario: The order id is not the customer's
+- **Given** an order id belonging to another customer
+- **When** the signed-in customer opens its status page
+- **Then** `order-service` answers 404 and the page says the order was not found
+- **And** an id that was never issued produces the same page, so the difference leaks nothing
+
+## UI
+
+Pages live under `ui/pages/`, one file per page. Each page-spec joins the two axes a UI sits
+between: `consumes:` names the fleet operations the page depends on, by the same `operationId`
+the provider's `openapi.yaml` declares, and `behavior:` names the scenarios above that govern
+what the page does with them. Where the matching landscape edge carries `metadata { op }`, the
+fleet map and the page-spec name that operation twice and can be read against each other; where
+it does not — the `checkout-web` → `payment-service` edge — the page-spec is the only place the
+operation is written down at all. Planned: `loam render` generates an HTML prototype from the
+page-spec, so the prototype and the requirement can never disagree about which endpoint a
+button calls.
+
+`split-payment.page.yaml` is the exception in this directory: it carries `feature: FEAT-101`
+because the requirement governing it lives under `features/FEAT-101-payment-splitting/` and not
+in this file yet. Its `behavior:` references are spelled with the feature id in front for exactly
+that reason, and drop it once `loam archive` has folded the delta into the requirements above —
+by hand, since no command reads page-specs yet and none will rewrite this one for you.

package/examples/docs/services/checkout-web/ui/pages/checkout.page.yaml

@@ -0,0 +1,40 @@
+# Page-spec (source of truth). planned: `loam render` generates an HTML prototype from this (model A).
+# Links the architecture (consumes endpoints) and behavior (governing scenarios).
+# No command reads page-specs yet — the format is illustrative, not contract.
+page: checkout
+title: Checkout
+service: checkout-web
+status: draft
+layout:
+  - { type: heading, text: "Checkout" }
+  - { type: list, id: cart-lines, itemFields: [sku, quantity, amount] }
+  - { type: text, id: total, label: "Total" }
+  - { type: field, id: payment-method, label: "Card", required: true }
+  - { type: button, id: confirm, text: "Pay and place order" }
+  # Every branch a governing scenario describes needs somewhere on the page to
+  # happen. This one is where "Authorization is refused" lands: without it the
+  # scenario is satisfied by an alert box nobody designed.
+  - { type: banner, id: declined, text: "That card was declined — try another payment method" }
+consumes:
+  # `consumes:` names the FLEET operation the page depends on — the exact
+  # operationId the provider's openapi.yaml declares — not the hop the call
+  # takes to get there. The two hops differ: `createOrder` goes through the
+  # `bff` container in model.likec4, `authorizePayment` leaves the browser
+  # directly so card details never touch our servers. Naming the hop here would
+  # make one dependency look unlike the other when the thing that can actually
+  # break under them is the same: the provider's contract.
+  - { service: order-service, op: createOrder }         # POST /orders
+  # The one dependency here whose edge carries no `metadata { op }` — see
+  # model.likec4, and `spine.op-link-missing` on its landscape twin. Nothing
+  # joins this line to anything, so it is a claim rather than a check: that is
+  # what the missing link costs, written at the only place that still knows.
+  - { service: payment-service, op: authorizePayment }  # POST /payments
+behavior:
+  # "<service> / <requirement> / <scenario>" for a LIVING scenario: the three
+  # names that locate it in services/<service>/spec.md. A scenario that still
+  # lives in a feature carries the feature id in front instead (see
+  # split-payment.page.yaml) — until FEAT-101 archives, there is no living
+  # requirement to point at.
+  - "checkout-web / Checkout flow / Complete a checkout"
+  - "checkout-web / Checkout flow / Authorization is refused"
+  - "checkout-web / Checkout flow / The customer submits twice"

package/examples/docs/services/checkout-web/ui/pages/order-status.page.yaml

@@ -0,0 +1,24 @@
+# Page-spec (source of truth). planned: `loam render` generates an HTML prototype from this (model A).
+# Links the architecture (consumes endpoints) and behavior (governing scenarios).
+# No command reads page-specs yet — the format is illustrative, not contract.
+page: order-status
+title: Order status
+service: checkout-web
+status: draft
+layout:
+  - { type: heading, text: "Order {orderId}" }
+  - { type: text, id: state, label: "Status" }
+  - { type: list, id: order-lines, itemFields: [sku, quantity, amount] }
+  # One empty state for both "no such order" and "not yours" — the page cannot
+  # tell them apart, and the governing scenario says it must not try: two
+  # different messages would turn the id into an oracle for whether an order exists.
+  - { type: banner, id: not-found, text: "We could not find that order" }
+consumes:
+  # One operation, one page. The status page reads and never writes, which is
+  # why `cancelOrder` is absent: it is order-service's own requirement, gated on
+  # `user/orders:cancel`, and a page that consumed it would owe that permission
+  # a place in the layout and a scenario naming the refusal.
+  - { service: order-service, op: getOrder }  # GET /orders/{id}
+behavior:
+  - "checkout-web / Show order status / Show the current state of an order"
+  - "checkout-web / Show order status / The order id is not the customer's"

package/examples/docs/services/checkout-web/ui/pages/split-payment.page.yaml

@@ -0,0 +1,26 @@
+# Page-spec (source of truth). planned: `loam render` generates an HTML prototype from this (model A).
+# Links the architecture (consumes endpoints) and behavior (governing scenarios).
+# No command reads page-specs yet — the format is illustrative, not contract.
+page: split-payment
+title: Split payment
+service: checkout-web
+feature: FEAT-101
+status: draft
+layout:
+  - { type: heading, text: "Split this payment" }
+  - { type: list, id: payees, itemFields: [name, amount] }
+  - { type: button, id: add-payee, text: "Add payee" }
+  # Where "A split that does not sum to the total cannot be confirmed" lands. A
+  # disabled confirm button with no remainder on screen is a dead end rather
+  # than an explanation, and the scenario says the 10.00 is shown.
+  - { type: text, id: unassigned, label: "Unassigned" }
+  - { type: button, id: confirm, text: "Confirm split" }
+consumes:
+  # createSplit only: the 201 carries back the split this page shows, so nothing
+  # here re-reads it through `getSplit`.
+  - { service: payment-split-service, op: createSplit }   # POST /splits
+behavior:
+  # BOTH scenarios of FEAT-101's ADDED `Split payment on checkout` — a page that
+  # names only the happy one leaves its own refusal path governed by nothing.
+  - "FEAT-101 / checkout-web / Split payment on checkout / Customer splits a payment across two payees"
+  - "FEAT-101 / checkout-web / Split payment on checkout / A split that does not sum to the total cannot be confirmed"

package/examples/docs/services/order-service/adrs/0001-orchestrated-order-lifecycle.md

@@ -0,0 +1,52 @@
+---
+id: ADR-order-service-0001
+status: accepted
+date: 2026-04-22
+service: order-service
+---
+
+# 1. Orchestrate the payment from order-service rather than choreograph it
+
+## Context
+Placing an order needs an authorization, and the two obvious shapes were both on the table.
+
+**Choreography**: order-service publishes `OrderPlaced`, payment-service consumes it,
+authorizes, and publishes `PaymentAuthorized`; every service reacts to events and nobody is in
+charge. **Orchestration**: order-service calls `authorizePayment` synchronously as part of
+`createOrder` and drives the lifecycle itself, consuming `PaymentAuthorized` only to learn how
+the decision landed.
+
+The deciding question was not coupling — both shapes couple, one through a topic and one
+through a contract — but where a placement that half-happened becomes somebody's problem. In
+the choreographed shape there is no moment at which any single service can answer "is this
+order going to be paid for", so the answer lives in the gaps between four consumers, and the
+customer-facing failure (an order acknowledged that no card will ever be charged for) is
+detectable only by reconciliation after the fact. checkout-web also needs a synchronous answer:
+a checkout page that acknowledges and then silently drops the order is the failure this fleet
+gets support tickets about.
+
+## Decision
+order-service orchestrates. `createOrder` calls `authorizePayment` before it acknowledges,
+holds the order in `awaiting_payment`, and advances it to `confirmed` when
+`payment.PaymentAuthorized` arrives. The event is a completion signal for a call this service
+already made — not the trigger that starts the work.
+
+Concretely: the synchronous edge `order-service -> payment-service` carries
+`metadata { op 'authorizePayment' }`, and the asynchronous one carries
+`metadata { consumes 'payment.PaymentAuthorized' }`. Both are drawn, because both are real.
+
+## Consequences
+- order-service is a hard runtime dependency on payment-service for placement, and
+  `health.yaml` says so (`criticality: critical`). A payment-service outage stops placements;
+  it is meant to be visible as `order_placement_failures`, not absorbed.
+- The lifecycle is readable in one file — the state machine in `domain` — instead of inferred
+  from four services' consumers. This is what makes ORD-CANCEL expressible at all: something
+  has to own the transition that refuses a cancellation.
+- Every call in the placement path must be idempotent, because orchestration means retrying.
+  ARCH-ORD-IDEMPOTENCY carries that obligation, and it is the reason `createOrder` takes an
+  `Idempotency-Key` header at all.
+- Redelivery is still ours to handle: the authorization arrives at-least-once, so
+  ARCH-ORD-DEDUPE keeps an applied-payment ledger. Orchestration removed the coordination
+  problem, not the delivery guarantee.
+- The v1 endpoint predates this decision and does not participate in it — it places orders
+  without an idempotency key, which is exactly why FEAT-112 retires it rather than fixing it.