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

package/examples/docs/features/FEAT-101-payment-splitting/specs/payment-service/asyncapi.yaml

@@ -0,0 +1,132 @@
+# The event-contract delta: what FEAT-101 changes about the messages
+# payment-service puts on the bus.
+#
+# A delta needs only the slots it adds, changes or removes — the merge leaves
+# every slot it does not declare exactly as the living contract has it. This
+# one restates the living contract around the change ON PURPOSE, to show what
+# a pin does with a restatement: identity is the slot — `channels.<key>`,
+# `operations.<key>`, `components.messages.<key>` — and `x-loam-based-on`
+# (written by `loam rebase`, never by hand) is what lets the merge tell a
+# restated slot from an edited one: a pinned QUOTE is never a merge input, so
+# a change that lands on the living contract after this delta was written
+# survives the archive. Outside a demonstration, leave quotes out: each one
+# is a pin, and a parallel feature's removal turns it into an error. The new
+# slots below carry no pin — there is no living version for them to be based on.
+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'
+    x-loam-based-on: 036cbb7e0245e1a9
+  # NEW: split authorizations are announced on their own topic, so a consumer
+  # that only reconciles splits does not filter the whole lifecycle stream.
+  paymentSplitEvents:
+    address: payment.splits.v1
+    description: Split-authorization events, published by the outbox relay
+    messages:
+      PaymentSplitAuthorized:
+        $ref: '#/components/messages/PaymentSplitAuthorized'
+
+operations:
+  sendPaymentAuthorized:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentAuthorized'
+    x-loam-based-on: 72934fd7ed7f6df9
+  sendPaymentCaptured:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentCaptured'
+    x-loam-based-on: 01ac447e38a868cc
+  sendPaymentSplitAuthorized:
+    action: send
+    channel:
+      $ref: '#/channels/paymentSplitEvents'
+
+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
+      x-loam-based-on: 0e5a230802d1573b
+    PaymentCaptured:
+      name: payment.PaymentCaptured
+      title: Payment captured
+      payload:
+        type: object
+        required: [ paymentId, orderId, capturedAmount, currency, capturedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          capturedAmount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          capturedAt:
+            type: string
+            format: date-time
+      x-loam-based-on: 449d5409ccf1b59f
+    # NEW: the split-aware half of an authorization. The split itself is
+    # payment-split-service's business; this event says the reservation on the
+    # payer's card is covered by a recorded split.
+    PaymentSplitAuthorized:
+      name: payment.PaymentSplitAuthorized
+      title: Split authorization completed
+      payload:
+        type: object
+        required: [ paymentId, orderId, splitId, authorizedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          splitId:
+            type: string
+            format: uuid
+          authorizedAt:
+            type: string
+            format: date-time

package/examples/docs/features/FEAT-101-payment-splitting/specs/payment-service/spec.md

@@ -0,0 +1,36 @@
+# payment-service — requirement delta for FEAT-101
+
+## MODIFIED Requirements
+
+### Requirement: Authorize a payment, splitting it when the order is flagged
+
+Requirement-ID: PAY-AUTHORIZE
+Based-On: 820301445e65f9f4
+The service SHALL reserve funds for an order before capture, SHALL treat an authorization
+request as idempotent by order id, and SHALL delegate splitting to `payment-split-service` when
+the order is flagged for splitting.
+
+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
+
+#### Scenario: Split order delegates to the split service
+- **Given** an order flagged for splitting
+- **When** authorization is requested
+- **Then** payment-service calls `createSplit` on `payment-split-service`
+- **And** the authorization succeeds only once the split is recorded

package/examples/docs/features/FEAT-101-payment-splitting/specs/payment-split-service/arch.spec.md

@@ -0,0 +1,40 @@
+# payment-split-service — architecture delta for FEAT-101
+
+Architectural obligations of the new service — what no business scenario was ever
+going to say. Each requirement's `Covers:` line names the delta's tagged elements
+and edges it accounts for; a tagged addition nothing covers is `c4.uncovered`.
+(The `checkout-web -> payment-split-service` edge is left uncovered on purpose —
+it is the example's demonstration of that warning.)
+
+Every entry below names a SERVICE rather than an element id. Both forms resolve — an entry
+matches an element by its id or by the service it stands for, and an edge by resolving each
+endpoint the same way — and the service form is the one that survives the landscape moving a box
+into a grouping element, which is exactly what happened to this fleet.
+
+## ADDED Requirements
+
+### Requirement: PaymentSplit leaves through the transactional outbox
+
+Requirement-ID: ARCH-SPL-OUTBOX
+The service SHALL record a split and its `PaymentSplit` event in one database
+transaction, published to kafka by an outbox relay — never a dual write.
+
+Covers: payment-split-service, payment-split-service -> kafka.paymentEvents
+
+#### Scenario: Broker down when a split is recorded
+- **Given** a recorded split whose `PaymentSplit` event is still in the outbox
+- **When** kafka is unavailable
+- **Then** the split stays committed and the event is published once kafka returns
+
+### Requirement: createSplit is idempotent under retries
+
+Requirement-ID: ARCH-SPL-IDEMPOTENT
+The service SHALL treat createSplit as idempotent by order id, so a caller's
+timeout-and-retry never records a second split.
+
+Covers: payment-service -> payment-split-service
+
+#### Scenario: payment-service retries createSplit
+- **Given** a split already recorded for order "A-1"
+- **When** the same createSplit request arrives again after a caller timeout
+- **Then** the original split is returned and no second split is recorded

package/examples/docs/features/FEAT-101-payment-splitting/specs/payment-split-service/openapi.yaml

@@ -0,0 +1,116 @@
+# API delta for FEAT-101 — payment-split-service (new) gains the split API.
+# On `loam archive` this folds into services/payment-split-service/openapi.yaml (living).
+#
+# A feature contract holds only what the feature adds, changes or removes, and the merge upserts
+# every operation it spells. Both operations here are new, like the service, so neither carries
+# an `x-loam-based-on` pin — there is no living operation for a pin to be the digest of. On a
+# service that already exists, an operation the delta edits carries one, written by `loam
+# rebase`; one it would only quote belongs out of the delta, because a restatement is exactly
+# the shape that silently reverts whoever landed in between unless something pins it.
+openapi: 3.1.0
+info:
+  title: payment-split-service
+  version: "1.0"
+paths:
+  /splits:
+    post:
+      operationId: createSplit
+      summary: Create a split of a payment across payees
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SplitRequest'
+      responses:
+        "201":
+          description: Split created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Split'
+        "422":
+          description: The shares do not sum to the payment total
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+  /splits/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    get:
+      operationId: getSplit
+      summary: Read a recorded split
+      responses:
+        "200":
+          description: The split and its shares
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Split'
+        "404":
+          description: No such split
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+
+components:
+  schemas:
+    SplitRequest:
+      type: object
+      required: [orderId, currency, shares]
+      properties:
+        orderId:
+          type: string
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        shares:
+          type: array
+          minItems: 2
+          items:
+            $ref: '#/components/schemas/Share'
+    Split:
+      type: object
+      required: [splitId, orderId, currency, shares]
+      properties:
+        splitId:
+          type: string
+          format: uuid
+        orderId:
+          type: string
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        shares:
+          type: array
+          items:
+            $ref: '#/components/schemas/Share'
+    Share:
+      type: object
+      required: [payee, amount]
+      properties:
+        payee:
+          type: string
+        amount:
+          type: integer
+          description: minor units
+    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/FEAT-101-payment-splitting/specs/payment-split-service/spec.md

@@ -0,0 +1,55 @@
+# payment-split-service — requirement delta for FEAT-101
+
+A delta is reviewed as a diff. Every requirement below sits under an `## ADDED|MODIFIED|REMOVED
+Requirements` heading, which is what gives it a kind: a requirement under any other H2 merges as
+nothing, and `delta.requirement-not-merged` names it rather than letting authored text vanish.
+
+## ADDED Requirements
+
+### Requirement: Split a payment
+
+Requirement-ID: SPL-SPLIT
+The service SHALL split a payment across two or more payees such that the shares sum to the
+total, and SHALL refuse a split whose shares do not.
+
+Operations: createSplit
+
+#### Scenario: Split across two payees
+- **Given** a payment of 100.00 USD for order "A-1"
+- **When** it is split 60.00 to "seller-x" and 40.00 to "seller-y"
+- **Then** a split with two shares summing to 100.00 is recorded
+- **And** a `PaymentSplit` event is published to kafka
+
+#### Scenario: Reject a split that does not sum to the total
+- **Given** a payment of 100.00 USD
+- **When** a split of 60.00 + 30.00 is requested
+- **Then** the split is refused with 422 and the shares that were sent are echoed back
+
+#### Scenario: Split across many payees
+- **Given** a payment of 100.00 USD for order "A-1"
+- **When** it is split across the payees below
+- **Then** a split with those shares is recorded
+
+  | payee    | share |
+  |----------|-------|
+  | seller-x | 50.00 |
+  | seller-y | 30.00 |
+  | seller-z | 20.00 |
+
+### Requirement: Read a split
+
+Requirement-ID: SPL-READ
+The service SHALL return a recorded split with its shares, so that checkout can show a customer
+what was agreed before confirmation.
+
+Operations: getSplit
+
+#### Scenario: Read a recorded split
+- **Given** a split recorded for order "A-1"
+- **When** it is requested by its id
+- **Then** its shares and their payees are returned
+
+#### Scenario: Read a split that does not exist
+- **Given** a split id nothing ever recorded
+- **When** it is requested
+- **Then** the request is refused with 404

package/examples/docs/features/FEAT-112-retire-order-v1/intent.md

@@ -0,0 +1,35 @@
+---
+feature: FEAT-112
+title: Retire the v1 order API
+status: in_progress
+owner: orders-team
+services: [order-service]
+---
+
+# FEAT-112 — Retire the v1 order API
+
+## Why
+`createOrderV1` was deprecated when `createOrder` shipped with idempotency keys and a currency
+field. The last caller — a partner integration — moved in June, and the operation has served no
+traffic since. Leaving it declared is not free: it is a live surface with its own validation
+path, and `api.requirement-deprecated` has been warning on the requirement that governs it ever
+since the flag went on.
+
+## Business acceptance
+- `POST /v1/orders` no longer exists.
+- No behaviour reachable only through the v1 path is lost: `createOrder` accepts everything the
+  v1 request could express.
+
+## Architectural summary
+This feature is the **smallest legal shape** loam accepts, and deliberately so: it changes no
+boxes and no edges, so there is no `delta.likec4` at all — an absent architecture axis is a
+legible statement that the architecture is unchanged, and the merge simply has nothing to do
+there. (A file that *declares* elements with none carrying the feature tag would be
+`delta.nothing-tagged` instead: declared-but-untagged is almost always a forgotten tag.)
+
+What it does carry is the two halves of an explicit removal, which loam requires together:
+a `REMOVED` requirement whose `Operations:` line names the operation, and an
+`x-loam-remove: true` marker inside that operation object in `specs/order-service/openapi.yaml`.
+Either half alone is refused — a marker with no requirement is `openapi.remove-marker-unjustified`,
+a `REMOVED` requirement with no marker is `openapi.remove-marker-missing` — because a contract
+shrinking with nothing to point at is how a consumer finds out by outage.

package/examples/docs/features/FEAT-112-retire-order-v1/specs/order-service/openapi.yaml

@@ -0,0 +1,31 @@
+# API delta for FEAT-112 — order-service retires `createOrderV1`.
+#
+# A removal is spelled as the exact living path and HTTP method, the operationId kept, and
+# `x-loam-remove: true` INSIDE the operation object beside it. Three things are load-bearing:
+#
+#   - the path+method must address a living operation (`openapi.remove-target-missing`);
+#   - the operationId must be the one living at that slot (`openapi.remove-target-mismatch`);
+#   - the marker must sit at operation level, not one level up beside the methods, where it
+#     names no operation and retires nothing (`openapi.remove-marker-path-level`).
+#
+# The marker never reaches the living contract — archive strips `x-loam-remove` and
+# `x-loam-based-on` on every merge branch — and a path item consisting of nothing but a marker
+# publishes no phantom path. Archive deletes only the matching method, and deliberately does not
+# garbage-collect the components the operation used: another operation may still reference them,
+# and a merge is not the place to decide that.
+#
+# Removal markers carry no baseline pin, unlike the operations a feature edits:
+# `openapi.remove-target-mismatch` already checks that exact slot, which is the same question a
+# pin would answer.
+#
+# `info` restates the living contract's. No merge carries `info`, so a value that differs here
+# would be lost at archive — `openapi.info-not-merged` says so in the plan instead of letting it vanish.
+openapi: 3.1.0
+info:
+  title: order-service
+  version: "2.0"
+paths:
+  /v1/orders:
+    post:
+      operationId: createOrderV1
+      x-loam-remove: true

package/examples/docs/features/FEAT-112-retire-order-v1/specs/order-service/spec.md

@@ -0,0 +1,17 @@
+# order-service — requirement delta for FEAT-112
+
+## REMOVED Requirements
+
+### Requirement: Accept an order through the v1 API
+
+Requirement-ID: ORD-PLACE-V1
+Based-On: 3671415e0f4d7b13
+The service SHALL accept an order through the pre-idempotency `/v1/orders` path for the one
+partner integration that has not migrated.
+
+Operations: createOrderV1
+
+#### Scenario: A partner places an order through the v1 path
+- **Given** a partner request with no idempotency key
+- **When** it is posted to the v1 path
+- **Then** an order is created and its id is returned