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

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.

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