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

package/examples/docs/features/FEAT-101-payment-splitting/delta.likec4

@@ -0,0 +1,94 @@
+// C4 DELTA for FEAT-101 — new/changed elements + relationships tagged #FEAT-101.
+// Self-contained so it validates on its own; loam projects the #FEAT-101 subset per service.
+//
+// The tag is loam's ONLY way of seeing the delta: a file that declares elements or
+// relationships with none carrying `#FEAT-101` is `delta.nothing-tagged` (error), because
+// everything in it would be invisible to the checks and the archive would merge nothing.
+specification {
+  element group
+  element softwareSystem
+  element container
+  element topic {
+    #external
+    #platform
+  }
+  tag external
+  tag platform
+  tag FEAT-101
+}
+
+model {
+  // Existing elements, referenced for context and left untagged — archive merges only what
+  // carries the feature tag, so quoting the neighbourhood costs nothing.
+  //
+  // The new service is declared INSIDE the group the landscape already draws, which is where
+  // archive splices it: a nested element lands inside its parent's block, never as a flat
+  // dotted id, which LikeC4 rejects at top level.
+  marketplace = group 'Marketplace' {
+    checkoutWeb = softwareSystem 'checkout-web'
+    paymentService = softwareSystem 'payment-service'
+
+    paymentSplitService = softwareSystem 'payment-split-service' {
+      #FEAT-101
+      description 'Splits a payment across payees'
+      // The binding, not the title, is what ties this element to the
+      // `services/payment-split-service/` directory archive will create. A
+      // title works too and is what most existing repositories rely on — and
+      // it is also the trap: rename the box in a diagram and every check that
+      // joined it to its directory silently stops matching.
+      metadata {
+        service 'payment-split-service'
+      }
+
+      api = container 'api' {
+        technology 'Spring Boot'
+      }
+    }
+  }
+
+  // The broker AND the topic the new edge points at, both already in the
+  // landscape: a delta references the channel, never the server, so the merged
+  // map does not grow one more spoke on a hub.
+  kafka = softwareSystem 'kafka' {
+    #external
+    #platform
+    paymentEvents = topic 'payment.events'
+  }
+
+  marketplace.paymentService -> marketplace.paymentSplitService 'Calls createSplit' {
+    #FEAT-101
+    metadata { op 'createSplit' }
+  }
+  // Read back at capture time: settlement needs the shares the split recorded.
+  marketplace.paymentService -> marketplace.paymentSplitService 'Calls getSplit' {
+    #FEAT-101
+    metadata { op 'getSplit' }
+  }
+  // The one tagged addition this feature leaves uncovered, on purpose: no
+  // `Covers:` line in any of its arch.spec.md deltas names it, so
+  // `c4.uncovered` (warn) says the architectural obligations behind this call
+  // ship untested. A `Covers: checkout-web -> payment-split-service` line
+  // would close it — and would also close the edge above, since an edge entry
+  // resolves by ENDPOINT, so two edges between one pair are one target.
+  marketplace.checkoutWeb -> marketplace.paymentSplitService 'Calls createSplit' {
+    #FEAT-101
+    metadata { op 'createSplit' }
+  }
+  // Drawn with the message in its title and no `metadata { publishes }`, deliberately: the
+  // metadata is a JOIN, and the join demands a contract — an edge publishing a message its
+  // bound service's contract (feature ∪ living) declares no send for is refused as
+  // `c4-event.message-undefined`. The async axis has the full feature lifecycle
+  // (`specs/payment-service/asyncapi.yaml` beside this delta is its demonstration — the
+  // living contract restated under `loam rebase` pins, plus a new producer side), but
+  // payment-split-service's own contract is deferred until the consumer of `PaymentSplit`
+  // exists, so the edge stays title-only rather than pointing at a contract nobody wrote.
+  marketplace.paymentSplitService -> kafka.paymentEvents 'Publishes PaymentSplit' {
+    #FEAT-101
+  }
+}
+
+views {
+  view feat_101 {
+    include *
+  }
+}

package/examples/docs/features/FEAT-101-payment-splitting/intent.md

@@ -0,0 +1,44 @@
+---
+feature: FEAT-101
+title: Payment splitting
+status: in_progress          # proposed -> in_progress -> built -> done
+owner: payments-team
+services: [payment-service, payment-split-service, checkout-web]
+---
+
+# FEAT-101 — Payment splitting
+
+## Why
+Marketplaces need to split one customer payment across multiple payees (sellers). Today a
+seller is paid by a separate transfer run reconciled by hand at the end of the day, which is
+where every payout dispute this quarter came from: the customer's payment and the sellers'
+shares are two records nothing joins.
+
+This file is where the "why" lives, and the archive gate holds it to that: the delta says what
+changed, and nothing else says what for. A feature whose `intent.md` is missing, or says nothing
+outside the scaffold's own comments, is refused by `intent.empty` — a warning that gates, so a
+change cannot fold into the living docs with its reason unwritten.
+
+## Business acceptance
+- A customer can split a payment across 2+ payees before confirming.
+- Each payee receives their share; the shares sum to the total.
+- A split that does not sum to the total is refused, and the customer is told which shares are
+  in play — a silent rounding fix is a payout dispute six weeks later.
+
+## Architectural summary
+New `payment-split-service`; `payment-service` and `checkout-web` call it; it publishes
+`PaymentSplit`. UI adds a split-payment page in `checkout-web`. See `delta.likec4`, and
+`adrs/0001-dedicated-split-service.md` for why the logic is not folded into `payment-service`.
+
+## Not in this feature
+Payouts themselves. A split records who is owed what; moving the money is separate work, and
+deliberately not smuggled in here — a feature whose intent and whose delta describe different
+scopes is one nobody can review as a diff.
+
+The `PaymentSplit` event is drawn in `delta.likec4` with the message in its title and no
+contract join yet — deliberately, not for lack of machinery. The async axis has the full
+feature lifecycle, and this feature's `specs/payment-service/asyncapi.yaml` is its
+demonstration: the living contract restated under `loam rebase`'s pins, plus the new
+`payment.PaymentSplitAuthorized` producer side the archive will merge. The split service's own
+contract is deferred until a consumer of `PaymentSplit` exists, and the edge stays unjoined
+rather than pointing at a contract nobody wrote.

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

@@ -0,0 +1,21 @@
+# checkout-web — requirement delta for FEAT-101
+
+## ADDED Requirements
+
+### Requirement: Split payment on checkout
+
+Requirement-ID: WEB-SPLIT
+The UI SHALL let a customer split a payment across two or more payees before confirming, and
+SHALL show the recorded split back to them before the payment is taken.
+
+#### Scenario: Customer splits a payment across two payees
+- **Given** a payment of 100.00 USD
+- **When** the customer assigns 60.00 to "seller-x" and 40.00 to "seller-y"
+- **And** confirms
+- **Then** `createSplit` is called on `payment-split-service`
+- **And** the split is shown as confirmed
+
+#### Scenario: A split that does not sum to the total cannot be confirmed
+- **Given** a payment of 100.00 USD
+- **When** the customer assigns 60.00 to "seller-x" and 30.00 to "seller-y"
+- **Then** the confirm control stays disabled and the remaining 10.00 is shown as unassigned

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

@@ -0,0 +1,129 @@
+# The event-contract delta: what FEAT-101 changes about the messages
+# payment-service puts on the bus.
+#
+# Like the openapi delta, this is a COMPLETE AsyncAPI 3.0 document, not a
+# patch: the living contract is restated around the one change. 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. 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 is a COMPLETE document, not a patch: the author restates the living
+# contract around the slot being changed, and the merge upserts every operation the document
+# spells. Both operations here are new, 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, every
+# quoted operation carries one, written by `loam rebase`, and an unpinned restatement is exactly
+# the shape that silently reverts whoever landed in between.
+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,28 @@
+# 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.
+openapi: 3.1.0
+info:
+  title: order-service
+  version: "1.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