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

package/examples/docs/features/archive/FEAT-088-refunds/specs/order-service/spec.md

@@ -0,0 +1,37 @@
+# order-service — requirement delta for FEAT-088
+
+A `MODIFIED` requirement carries its full new text rather than a diff, so the merge REPLACES the
+living requirement instead of folding into it. That is what makes the `Based-On:` pin below
+load-bearing: it is the digest of the living requirement this text was written against, and
+`delta.baseline-stale` refuses the merge when the living text has moved under it. `loam rebase`
+writes the line and nobody writes it by hand — a pin says "I read this version", so restamping
+without re-reading merges your text over somebody else's.
+
+## MODIFIED Requirements
+
+### Requirement: Cancel an order
+Requirement-ID: ORD-CANCEL
+Based-On: 16ba4428e292c1d9
+The service SHALL let an order be cancelled while nothing irreversible has happened to it, SHALL
+return the customer's money when the order's payment was already captured, and SHALL refuse once
+the order has been handed to fulfilment — a cancellation after that point is a return, which
+this service does not model.
+
+Operations: cancelOrder
+Requires: user/orders:cancel
+
+#### Scenario: A customer cancels before fulfilment
+- **Given** an order in state `awaiting_payment`
+- **When** its owner calls `cancelOrder`
+- **Then** the order moves to `cancelled` and no further payment work is started
+
+#### Scenario: Cancelling a confirmed order refunds its captured payment
+- **Given** an order in state `confirmed` whose payment was captured
+- **When** its owner calls `cancelOrder`
+- **Then** `refundPayment` is called on payment-service for that payment
+- **And** the order moves to `cancelled` only once the refund is recorded
+
+#### Scenario: An order already handed to fulfilment cannot be cancelled
+- **Given** an order in state `fulfilling`
+- **When** `cancelOrder` is called for it
+- **Then** the service refuses with 409 and the order stays `fulfilling`

package/examples/docs/features/archive/FEAT-088-refunds/specs/payment-service/openapi.yaml

@@ -0,0 +1,70 @@
+# API delta for FEAT-088 — payment-service gains the refund operation.
+#
+# A feature contract is a COMPLETE document, not a patch, and the merge upserts every operation
+# it spells. This one adds an operation that does not exist living, so it carries no
+# `x-loam-based-on` pin: a pin is the digest of the LIVING operation, and there is none.
+# Restated operations are the ones that need pins — on a service with thirty operations a delta
+# quotes twenty-nine of them, and every unpinned quote is a candidate rollback of whoever landed
+# in between. `loam rebase` writes them.
+openapi: 3.1.0
+info:
+  title: payment-service
+  version: "1.0"
+paths:
+  /payments/{id}/refund:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    post:
+      operationId: refundPayment
+      summary: Refund a captured payment
+      responses:
+        "200":
+          description: Refunded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Refund'
+        "409":
+          description: The payment was already refunded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+
+components:
+  schemas:
+    Refund:
+      type: object
+      required: [paymentId, refundedAmount, refundedAt]
+      properties:
+        paymentId:
+          type: string
+          format: uuid
+        refundedAmount:
+          type: integer
+          description: minor units
+        refundedAt:
+          type: string
+          format: date-time
+    # Quoted from the living contract unchanged. The merge leaves a component the living
+    # document already holds IDENTICALLY alone; one it holds DIFFERENTLY is overwritten
+    # wholesale and reported as `openapi.component-modified`, because components carry no
+    # baseline pin the way operations do.
+    Problem:
+      type: object
+      required: [type, title, status]
+      properties:
+        type:
+          type: string
+          format: uri
+        title:
+          type: string
+        status:
+          type: integer
+        detail:
+          type: string

package/examples/docs/features/archive/FEAT-088-refunds/specs/payment-service/spec.md

@@ -0,0 +1,23 @@
+# payment-service — requirement delta for FEAT-088
+
+## ADDED Requirements
+
+### Requirement: Refund a captured payment
+Requirement-ID: PAY-REFUND
+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
+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

package/examples/docs/features/archive/FEAT-088-refunds/verification.yaml

@@ -0,0 +1,76 @@
+# Verification record for FEAT-088 — written by `loam verify FEAT-088` (--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
+# cucumber JSON report's digest-tagged scenarios answered it mechanically;
+# `answered_by: agent` means somebody's word about the code, which loam did not
+# check. Nothing gates on either.
+#
+# 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-088
+recorded: 2026-08-18
+checklist: 53d168ad70d5da6a
+summary:
+  claims: 7
+  confirmed: 7
+  unconfirmed: 0
+claims:
+  - id: api.exposes-0b428913
+    kind: api.exposes
+    claim: payment-service exposes operationId 'refundPayment'
+    verdict: confirmed
+    answered_by: agent
+    evidence:
+      - src/main/java/com/marketplace/payments/api/RefundController.java:31
+    note: POST /payments/{id}/refund, operationId refundPayment
+  - id: c4.calls-ce371652
+    kind: c4.calls
+    claim: order-service calls 'refundPayment' on payment-service
+    verdict: confirmed
+    answered_by: agent
+    evidence:
+      - src/main/kotlin/com/marketplace/orders/cancel/CancelOrderService.kt:74
+    note: the cancellation path calls refundPayment when the payment was captured
+  - id: scenario.tested-d95d0521
+    kind: scenario.tested
+    claim: scenario 'Cancel an order before payment is captured' of requirement 'Cancel an order' (order-service) is covered by a test
+    verdict: confirmed
+    answered_by: agent
+    evidence:
+      - src/test/kotlin/com/marketplace/orders/CancelOrderTest.kt:22
+  - id: scenario.tested-2521fcf9
+    kind: scenario.tested
+    claim: scenario 'Cancelling a captured order refunds it' of requirement 'Cancel an order' (order-service) is covered by a test
+    verdict: confirmed
+    answered_by: agent
+    evidence:
+      - src/test/kotlin/com/marketplace/orders/CancelOrderTest.kt:48
+  - id: scenario.tested-f676b29f
+    kind: scenario.tested
+    claim: scenario 'A shipped order cannot be cancelled' of requirement 'Cancel an order' (order-service) is covered by a test
+    verdict: confirmed
+    answered_by: agent
+    evidence:
+      - src/test/kotlin/com/marketplace/orders/CancelOrderTest.kt:71
+  - id: scenario.tested-0015cd33
+    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: agent
+    evidence:
+      - src/test/java/com/marketplace/payments/RefundPaymentTest.java:29
+  - id: scenario.tested-ec3b0881
+    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: agent
+    evidence:
+      - src/test/java/com/marketplace/payments/RefundPaymentTest.java:57

package/examples/docs/features/archive/FEAT-120-refund-notification/.loam-before/files/architecture/landscape.likec4

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

package/examples/docs/features/archive/FEAT-120-refund-notification/.loam-before/files/services/payment-service/asyncapi.yaml

@@ -0,0 +1,96 @@
+# 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'
+
+operations:
+  sendPaymentAuthorized:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentAuthorized'
+  sendPaymentCaptured:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentCaptured'
+
+components:
+  messages:
+    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
+    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

package/examples/docs/features/archive/FEAT-120-refund-notification/.loam-before/files/services/payment-service/spec.md

@@ -0,0 +1,82 @@
+---
+service: payment-service
+status: draft
+owner: payments-team
+sources:
+  - src/main/java/
+---
+
+# payment-service
+
+Owns payment authorization and capture. This is the **living spec** — the complete current
+state. Feature deltas (ADDED/MODIFIED/REMOVED requirements) merge in here on `loam archive`;
+`features/archive/` keeps every one of those deltas, so "which change introduced this
+requirement" stays a search rather than a record somebody has to maintain.
+
+## Requirements
+
+### Requirement: Authorize a payment
+
+Requirement-ID: PAY-AUTHORIZE
+The service SHALL reserve funds for an order before capture, and SHALL treat an authorization
+request as idempotent by order id so that a caller's timeout-and-retry never reserves twice.
+
+Operations: authorizePayment
+Publishes: payment.PaymentAuthorized
+Realizes: checkout#CHECKOUT-CHARGE-ONCE
+
+#### Scenario: Successful authorization
+- **Given** an order with a valid payment method
+- **When** authorization is requested
+- **Then** funds are reserved and a `PaymentAuthorized` event is emitted
+
+#### Scenario: A retry of the same authorization returns the first result
+- **Given** an authorization already reserved for order "A-1"
+- **When** the same request arrives again after a caller timeout
+- **Then** the original authorization is returned and no second reservation is made
+
+#### Scenario: A second authorization for the same order with a different amount is refused
+- **Given** an authorization already reserved for order "A-1" of 100.00 USD
+- **When** an authorization of 120.00 USD is requested for the same order
+- **Then** the request is refused with 409 and the first reservation stands
+
+### Requirement: Capture an authorized payment
+
+Requirement-ID: PAY-CAPTURE
+The service SHALL settle a previously authorized payment, and SHALL refuse to capture a payment
+it never authorized.
+
+Operations: capturePayment
+Publishes: payment.PaymentCaptured
+Requires: service/payments:capture
+
+#### Scenario: Capture an authorized payment
+- **Given** an authorized payment
+- **When** capture is requested
+- **Then** the payment is settled and a `PaymentCaptured` event is emitted
+
+#### Scenario: Capturing an unknown payment is refused
+- **Given** a payment id no authorization ever created
+- **When** capture is requested for it
+- **Then** the request is refused with 404 and nothing is settled
+
+### Requirement: Refund a captured payment
+
+Requirement-ID: PAY-REFUND
+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
+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