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

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.

package/examples/docs/services/order-service/arch.spec.md

@@ -0,0 +1,127 @@
+---
+service: order-service
+status: draft
+owner: orders-team
+sources:
+  - src/main/kotlin/
+---
+
+# order-service — architecture spec
+
+The **living architecture spec**: the obligations no business scenario in `spec.md` was ever
+going to carry. "Place an order" says an order is placed; it does not say that the placement
+and its `OrderPlaced` row commit together, that a caller's retry must not buy the basket twice,
+or that a redelivered `PaymentAuthorized` must confirm the order exactly once. Those are the
+corners an agent writing the implementation cuts first, so they are written down mechanically
+here instead of being trusted to a reviewer.
+
+Same grammar as `spec.md`, and a separate requirement namespace — an arch requirement never
+collides with a business one of the same name, and `loam gherkin` emits these tagged
+`@architecture` so the suite knows an integration or operational test is being asked for.
+
+What makes the file checkable is the `Covers:` line: it names the model objects a requirement's
+scenarios exercise, and `loam validate` grades it both ways. Every entry must resolve against
+this service's own `model.likec4` plus the landscape (`covers.unknown`, with a did-you-mean
+hint, is the typo guard — a mistyped entry otherwise costs exactly the coverage it was written
+for), and every `slis[].name` and `alerts[].name` in `health.yaml` must be named by one of them
+(`health.uncovered`, or a signal ships to the on-call rotation with nothing testing it). Edge
+entries below are spelled as this model draws them — `orderService.outbox -> kafka.orderEvents`
+— because the endpoint that matters is the container; `order-service -> payment-service`
+resolves too, through the `metadata { service }` binding on the root element.
+
+## Requirements
+
+### Requirement: Order creation is idempotent under a caller's key
+
+Requirement-ID: ARCH-ORD-IDEMPOTENCY
+The service SHALL record the `Idempotency-Key` of every accepted `createOrder` in the same
+transaction that stores the order, and SHALL replay the stored response for a repeat of that
+key rather than placing a second order or requesting a second authorization. checkout-web's
+retry on a gateway timeout is not a rare path — it is the normal shape of a mobile checkout —
+and without the key a customer's flaky connection charges the card twice.
+
+Covers: orderService.db, orderService.domain -> paymentService
+
+#### Scenario: checkout-web retries a placement it never saw acknowledged
+- **Given** an order placed under `Idempotency-Key` "ik-8842" with an authorization already requested
+- **When** the identical `createOrder` request arrives again after the caller timed out
+- **Then** the stored response for "ik-8842" is returned unchanged
+- **And** payment-service receives no second `authorizePayment` call
+
+#### Scenario: An authorization call that times out is retried, not abandoned
+- **Given** a `createOrder` whose `authorizePayment` call times out with no response
+- **When** the placement path retries the authorization
+- **Then** `authorizePayment` is called again for the same `orderId`, amount and currency
+- **And** payment-service's idempotency by order id returns the first authorization instead of reserving funds twice
+
+### Requirement: OrderPlaced leaves through the transactional outbox
+
+Requirement-ID: ARCH-ORD-OUTBOX
+The service SHALL write the order and its `OrderPlaced` event into the same database
+transaction and SHALL publish the event from the outbox relay — never by writing to the
+database and then to kafka. A dual write has no failure mode in which both sides agree: a crash
+between them either announces an order nobody stored or stores one nobody hears about, and
+notification-service is the service that pays for the second case.
+
+Covers: orderService.outbox, orderService.outbox -> kafka.orderEvents
+
+#### Scenario: The broker is unavailable when an order is placed
+- **Given** an accepted order whose `OrderPlaced` row is still in the outbox table
+- **When** kafka is unreachable
+- **Then** the order stays committed and is readable through `getOrder`
+- **And** the relay publishes the event once kafka returns, without the caller retrying
+
+#### Scenario: The relay crashes after publishing and before marking the row sent
+- **Given** an outbox row published to `order.events.v1` but not yet marked sent
+- **When** the relay restarts and picks the row up again
+- **Then** the event is published a second time with the same order id
+- **And** consumers deduplicate on it, because this relay promises at-least-once and not exactly-once
+
+### Requirement: PaymentAuthorized is consumed at least once and applied once
+
+Requirement-ID: ARCH-ORD-DEDUPE
+The service SHALL record the `paymentId` of every `payment.PaymentAuthorized` it applies, in
+the transaction that advances the order, and SHALL ignore a message whose `paymentId` is
+already recorded. The producer's outbox promises at-least-once delivery and a rebalance
+redelivers whatever was in flight, so a consumer without a ledger is a consumer that confirms
+an order it already confirmed — and, once ORD-CANCEL has moved on, resurrects a cancelled one.
+
+Covers: orderService.consumer, kafka.paymentEvents -> orderService.consumer
+Consumes: payment.PaymentAuthorized
+
+#### Scenario: The same authorization is redelivered after a consumer rebalance
+- **Given** an order confirmed from `payment.PaymentAuthorized` for payment "pay-77"
+- **When** the same message is redelivered after the consumer group rebalances
+- **Then** the ledger already holds "pay-77" and the message is acknowledged without a write
+- **And** the order's state and its updated-at timestamp are unchanged
+
+#### Scenario: The consumer fails mid-batch and the offset is not committed
+- **Given** a batch of authorizations where the third message fails to apply
+- **When** the consumer restarts from the last committed offset
+- **Then** the first two are recognized by the ledger and skipped
+- **And** the third is applied, so no authorization is lost to a partial batch
+
+### Requirement: Order placement is measured and paged
+
+Requirement-ID: ARCH-ORD-SIGNALS
+The service SHALL export availability and placement-latency SLIs, and SHALL page the orders
+on-call when placements fail at a sustained rate. Placement is the fleet's revenue path and it
+fails silently from the customer's side — a broken authorization call looks like a slow
+checkout — so the alert is on the outcome, not on any one dependency being down.
+
+Covers: sli:availability, sli:order_placement_latency_p95_ms, alert:order_placement_failures
+
+#### Scenario: Sustained placement failures page the on-call
+- **Given** more than 2% of `createOrder` calls failing over five minutes
+- **When** the alert rules are evaluated
+- **Then** `order_placement_failures` pages the orders on-call with the runbook link
+
+#### Scenario: The SLIs are exported against their objectives
+- **Given** the service is serving traffic
+- **When** its metrics endpoint is scraped
+- **Then** `availability` and `order_placement_latency_p95_ms` report values against their SLOs
+
+#### Scenario: A degraded payment-service shows up as placement latency, not as a silent stall
+- **Given** payment-service answering `authorizePayment` slowly but successfully
+- **When** placements queue behind it
+- **Then** `order_placement_latency_p95_ms` rises above its objective before any request times out