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

package/examples/docs/features/archive/FEAT-088-refunds/.loam-before/files/architecture/landscape.likec4

@@ -0,0 +1,253 @@
+// 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
+}
+
+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' {
+    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'
+    }
+  }
+  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-088-refunds/.loam-before/files/services/order-service/spec.md

@@ -0,0 +1,121 @@
+---
+service: order-service
+status: draft
+owner: orders-team
+sources:
+  - src/main/kotlin/
+---
+
+# order-service
+
+Owns the order lifecycle — placement, the payment it orchestrates, and cancellation. This is
+the **living spec**: the complete current state, not a changelog. Feature deltas
+(`## ADDED|MODIFIED|REMOVED Requirements`) merge in here on `loam archive`, so what is written
+below is always what the service promises today.
+
+Three join lines carry the whole file into the rest of the docs, and each is graded:
+`Operations:` names operationIds from `openapi.yaml` (an operation nobody names is
+`api.ungoverned`; a name nothing defines is `spec-api.op-undefined`), `Publishes:` / `Consumes:`
+name messages `asyncapi.yaml` declares an `action: send` / `action: receive` for
+(`spec-event.message-undefined` otherwise), and `Requires:` names a pair
+`architecture/permissions.yaml` declares (`permissions.unknown` otherwise). The architectural
+obligations behind these promises — idempotency, the outbox, the dedupe ledger, the alerts —
+are not here; they live in `arch.spec.md`, which is a separate requirement namespace.
+
+## Requirements
+
+### Requirement: Place an order
+Requirement-ID: ORD-PLACE
+The service SHALL accept an order for a customer's basket, obtain a payment authorization from
+payment-service before acknowledging it, and announce the accepted order to the fleet. The
+authorization answers in band — `authorizePayment` returns the reservation, so nothing is
+acknowledged on a card nobody has reserved. The order is still placed in state
+`awaiting_payment`: what clears that state is `payment.PaymentAuthorized`, and the requirement
+that acts on it is ORD-ON-AUTHORIZED.
+
+Operations: createOrder
+Publishes: order.OrderPlaced
+
+#### Scenario: A basket becomes an order
+- **Given** a customer with a basket of two lines and a valid payment method
+- **When** `createOrder` is called with a fresh `Idempotency-Key`
+- **Then** the order is stored in state `awaiting_payment`
+- **And** `order.OrderPlaced` is announced with the order id, the customer id and the total
+
+#### Scenario: A reused idempotency key with a different basket is refused
+- **Given** an order already placed under `Idempotency-Key` "ik-8842"
+- **When** `createOrder` is called again with that key and a basket that differs from the first
+- **Then** the service refuses with 409 and names the conflicting key
+- **And** the first order is left exactly as it was placed
+
+### Requirement: Read an order
+Requirement-ID: ORD-READ
+The service SHALL return an order's current state to its owner, so checkout-web's status page
+reads the order rather than inferring it from payment events it cannot see.
+
+Operations: getOrder
+
+#### Scenario: An order is read back
+- **Given** an order placed for customer "cus-31"
+- **When** `getOrder` is called for that order id
+- **Then** the response carries the order's state, its lines and its total
+
+#### Scenario: An order id that was never issued
+- **Given** an order id no placement ever produced
+- **When** `getOrder` is called for it
+- **Then** the service answers 404 rather than an empty order
+
+### Requirement: Cancel an order
+Requirement-ID: ORD-CANCEL
+The service SHALL let an order be cancelled while nothing irreversible has happened to it, 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: 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`
+
+### Requirement: Accept an order through the v1 API
+Requirement-ID: ORD-PLACE-V1
+The service SHALL keep accepting orders on the v1 endpoint for as long as the partner batch
+importer still calls it. This is legacy: v1 takes a flat basket with no idempotency key and no
+currency, so a retried import creates a second order and every total is assumed to be EUR. It
+is kept alive for one remaining caller and nothing new may be built on it — FEAT-112 retires
+the endpoint once that importer has moved to `createOrder`.
+
+Operations: createOrderV1
+
+#### Scenario: The partner batch importer places an order on v1
+- **Given** the partner importer, the only caller left on v1
+- **When** it posts a flat basket to `createOrderV1`
+- **Then** an order is placed exactly as `createOrder` places one, with the currency defaulted to EUR
+- **And** no idempotency key is recorded, so a replayed import would place a second order
+
+### Requirement: Advance an order when payment is authorized
+Requirement-ID: ORD-ON-AUTHORIZED
+The service SHALL move an order to `confirmed` when payment-service announces that the order's
+payment was authorized, and SHALL leave an order that is no longer awaiting payment untouched.
+The authorization decision belongs to payment-service; what this requirement owns is the order
+state that follows from it.
+
+Consumes: payment.PaymentAuthorized
+
+#### Scenario: Authorization confirms the order
+- **Given** an order in state `awaiting_payment`
+- **When** `payment.PaymentAuthorized` arrives naming that order
+- **Then** the order moves to `confirmed` and becomes eligible for fulfilment
+
+#### Scenario: Authorization arrives for an order the customer already cancelled
+- **Given** an order cancelled while its authorization was still in flight
+- **When** `payment.PaymentAuthorized` arrives naming that order
+- **Then** the order stays `cancelled` and is never confirmed
+- **And** the authorization is left to expire uncaptured, because this service never captures

package/examples/docs/features/archive/FEAT-088-refunds/.loam-before/files/services/payment-service/openapi.yaml

@@ -0,0 +1,111 @@
+# API contract. Written by an agent from the `loam adopt` brief; forward-flow authors changes
+# in the feature's own `specs/<svc>/openapi.yaml` delta and lets `loam archive` merge them here.
+#
+# Only the eight HTTP methods of a path item are read for operationIds — an id tucked inside a
+# vendor extension does not exist as far as the spine is concerned, because a phantom id would
+# mask a contract break. Two things are graded beyond form: every operation wants a response
+# with a schema (`openapi.response-undescribed` otherwise — a contract that names an operation
+# and says nothing about what it returns still sends the reader to the code), and every 4xx/5xx
+# it declares wants a scenario that reaches it (`api.response-ungoverned`).
+openapi: 3.1.0
+info:
+  title: payment-service
+  version: "1.0"
+paths:
+  /payments:
+    post:
+      operationId: authorizePayment
+      summary: Authorize a payment
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AuthorizationRequest'
+      responses:
+        "201":
+          description: Authorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
+        "409":
+          description: A different authorization already exists for this order
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+  /payments/{id}/capture:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    post:
+      operationId: capturePayment
+      summary: Capture an authorized payment
+      responses:
+        "200":
+          description: Captured
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Capture'
+        "404":
+          description: No such authorized payment
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+
+components:
+  schemas:
+    AuthorizationRequest:
+      type: object
+      required: [orderId, amount, currency]
+      properties:
+        orderId:
+          type: string
+        amount:
+          type: integer
+          description: minor units
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+    Payment:
+      type: object
+      required: [paymentId, status]
+      properties:
+        paymentId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [authorized, declined]
+    Capture:
+      type: object
+      required: [paymentId, capturedAmount]
+      properties:
+        paymentId:
+          type: string
+          format: uuid
+        capturedAmount:
+          type: integer
+          description: minor units
+    # RFC 9457. One shared shape for every refusal, so a client parses failures once —
+    # and so the 409 and 404 above declare a schema rather than a bare description.
+    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/.loam-before/files/services/payment-service/spec.md

@@ -0,0 +1,58 @@
+---
+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
+
+#### 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

package/examples/docs/features/archive/FEAT-088-refunds/.loam-before/manifest.json

@@ -0,0 +1,32 @@
+{
+  "version": 2,
+  "feature": "FEAT-088",
+  "dirName": "FEAT-088-refunds",
+  "archivedAt": "2026-08-18T08:01:34.290Z",
+  "files": [
+    {
+      "path": "services/order-service/spec.md",
+      "existed": true,
+      "after": "fcb80dc0121340860b3e9f26a65a5f4aa8966f3c57e1e89c22ea260a8b90c73f",
+      "before": "26db38f9c6ccfea240bc088f987343325a9b2e4b2d57df4b2aff212c27fee8c8"
+    },
+    {
+      "path": "services/payment-service/spec.md",
+      "existed": true,
+      "after": "97b2b1b0f0bee2dcd7005dd792622f05cc701ff8f12ff5f21e7d9a2b36441b06",
+      "before": "a6248de65c69d3e42625cdd9be2d259e29840ab2377adb2e5669dab8ef9231cb"
+    },
+    {
+      "path": "services/payment-service/openapi.yaml",
+      "existed": true,
+      "after": "220bfd52275c43f996e5d88a7fd93bcd3d6587cb08832d80530d5bd5b05a8270",
+      "before": "e39f80d7755cd6f7b4b8223f08e9746a8d47a9416e6f14225e7ef7abe5caa3c8"
+    },
+    {
+      "path": "architecture/landscape.likec4",
+      "existed": true,
+      "after": "f9931344156869c15ea3e17ce384f78a90403898a2c2a2b296641b8d4a8a0492",
+      "before": "701780cf4f72ec137e5b5e4e5d9eda741148948c484ca0ab9998828028ed2020"
+    }
+  ]
+}

package/examples/docs/features/archive/FEAT-088-refunds/adrs/0001-refunds-stay-in-payment-service.md

@@ -0,0 +1,26 @@
+---
+id: ADR-FEAT-088-0001
+status: accepted
+date: 2026-07-02
+feature: FEAT-088
+---
+
+# 1. Refunds belong to payment-service, not to order-service
+
+## Context
+Cancellation is an order concept and refunding is a money concept, and the cancellation flow
+needs both. Putting the refund call in `order-service` is the shortest path; owning the refund
+state there is the tempting next step.
+
+## Decision
+`order-service` calls `refundPayment` and owns nothing about it. The refund's state, its
+idempotency and its reconciliation against the acquirer stay in `payment-service`, beside the
+authorization and capture they are a continuation of.
+
+## Consequences
+- One service reconciles with the acquirer, so there is one answer to "what does the acquirer
+  think happened".
+- `order-service` gains a synchronous dependency on `payment-service` for cancellation, which
+  its `health.yaml` already records as `critical`.
+- A refund initiated anywhere else — support tooling, a future payouts service — goes through
+  the same operation rather than a second implementation.

package/examples/docs/features/archive/FEAT-088-refunds/delta.likec4

@@ -0,0 +1,28 @@
+// C4 DELTA for FEAT-088 — one new edge, tagged #FEAT-088.
+//
+// A delta is self-contained so it validates on its own, which is why the two existing systems
+// and the group around them are quoted here. Only the tagged statement is merged; the quotes
+// are how the tagged statement gets something to attach to.
+specification {
+  element group
+  element softwareSystem
+  tag FEAT-088
+}
+
+model {
+  marketplace = group 'Marketplace' {
+    orderService = softwareSystem 'order-service'
+    paymentService = softwareSystem 'payment-service'
+  }
+
+  marketplace.orderService -> marketplace.paymentService 'Calls refundPayment' {
+    #FEAT-088
+    metadata { op 'refundPayment' }
+  }
+}
+
+views {
+  view feat_088 {
+    include *
+  }
+}

package/examples/docs/features/archive/FEAT-088-refunds/intent.md

@@ -0,0 +1,26 @@
+---
+feature: FEAT-088
+title: Refund a captured payment
+status: built
+owner: payments-team
+services: [payment-service, order-service]
+---
+
+# FEAT-088 — Refund a captured payment
+
+## Why
+Cancelling an order after capture leaves the customer's money with us. Support has been issuing
+refunds by hand in the acquirer's dashboard, which means the fleet's own records say the payment
+is still captured — the ledger and the truth disagree, and nothing in the docs said which one to
+believe.
+
+## Business acceptance
+- A captured payment can be refunded in full.
+- Cancelling an order whose payment was captured refunds it as part of the cancellation.
+- A second refund of the same payment is refused rather than issued twice.
+
+## Architectural summary
+`payment-service` gains `refundPayment`; `order-service` calls it when it cancels an order that
+was already captured. No new service and no new message: a refund is a state change of an
+existing payment, and the event that reports it is deliberately left for the payout work that
+needs it.