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

package/examples/docs/architecture/usecases/order-notification.likec4

@@ -0,0 +1,65 @@
+// A fleet use case: the ordered hops that fulfil one business capability.
+//
+// This file is the whole shape of the axis. A `dynamic view` tagged
+// `#cap-<slug>` opts in to grading; an untagged one is somebody's hand-drawn
+// diagram and loam never says a word about it. The slug is the capability id
+// from architecture/capabilities.yaml with every `/` flattened to `-`, because
+// a LikeC4 tag name cannot carry a slash — `identity/tokens` would be
+// `#cap-identity-tokens`.
+//
+// It lives in its own file rather than in architecture/landscape.likec4 for a
+// reason that is about people, not parsing: the map belongs to whoever owns the
+// fleet's topology, and a flow changes when a business need changes. Different
+// reasons to edit are different files. The whole `architecture/` directory is
+// read as ONE LikeC4 project, so the steps below resolve against the landscape's
+// elements even though this file declares none — which also means exactly one
+// file in this directory declares the `specification` block, and it is not this
+// one.
+//
+// THE TAG MUST BE THE FIRST THING IN THE VIEW BODY. Written after `title` it is
+// five parse errors, none of which mentions tags. That is the mistake every
+// author makes once.
+//
+// ---------------------------------------------------------------------------
+//
+// Two things about this particular flow are worth reading before you copy it.
+//
+// The first hop is a PERSON, and it is here on purpose: `customer ->
+// checkoutWeb` is backed by a real edge that carries no `metadata { op }`, and
+// checkout-web is a real services/ directory — so every condition of
+// `usecase.step-unlinked` is met except the one that matters, which is that a
+// person is not a caller. Somebody clicking a button owes no operationId. Delete
+// that exemption from the checker and this file is what notices: the example
+// fleet's warning count moves from eight to nine and test/examples.test.ts
+// fails.
+//
+// The hop from checkout-web to order-service is DELIBERATELY NOT DRAWN, and its
+// absence is the more useful half of the lesson. The landscape declares two
+// edges for that pair — `Calls createOrder` and `Calls getOrder` — so a step
+// between those two elements names two operations, and loam refuses to guess
+// which one the flow exercises: `usecase.step-contested` (warn), listing both
+// candidates. That is the check working. The two fixes are the ones the message
+// offers: draw the hop between elements that name exactly one operation, or give
+// the candidates one operation between them.
+
+views {
+  dynamic view uc_order_notification {
+    #cap-order-notifications
+    #req-NOTIFY-ONCE
+    title 'Order notification'
+    description 'A placed order reaches the customer as exactly one confirmation'
+
+    // A person, not a caller — see above.
+    customer -> marketplace.checkoutWeb 'places the order'
+
+    // Producer to topic: the edge carries `publishes`, so the hop reaches a
+    // declared API — an AsyncAPI one — and loam does not also demand an HTTP
+    // operationId for it. The event spine grades this edge on its own terms.
+    marketplace.orderService -> kafka.orderEvents 'announces OrderPlaced'
+
+    // Topic to consumer, the same exemption from the other side. Modelling the
+    // TOPIC rather than the broker is what keeps this readable: an edge into
+    // `kafka` itself would put every service in the fleet on one node.
+    kafka.orderEvents -> marketplace.notificationService 'sends the confirmation'
+  }
+}

package/examples/docs/capabilities/checkout/spec.md

@@ -0,0 +1,55 @@
+# Checkout
+
+The customer has chosen what to buy and now wants to be done. Everything from
+the filled cart to the confirmed, paid [order](../../glossary/order.md) is this
+capability: the prices they were shown, the money leaving their card exactly
+once, and the confirmation that tells them it worked. Exactly once means one
+[authorization](../../glossary/payments/authorization.md), which is a word this
+fleet uses in one sense and writes down.
+
+This narrative slot is why the tree exists at all. `architecture/capabilities.yaml`
+can declare the word `checkout` and nothing more; the paragraph above is what a
+business analyst actually writes, and before this file there was nowhere in a
+loam docs repo to put it. It is also the loam equivalent of OpenSpec's
+`## Purpose` prose, which the migrator used to drop into `legacy/`.
+
+The requirements below are the analyst's, and each one is a promise a customer
+could check from outside — no operationId, no element id, no message name, and
+no service named. That is the rule the tree is held to, and half of it is
+checked: `Operations:`, `Covers:`, `Publishes:` and `Consumes:` are refused here
+(`capability.requirement-service-scoped`), while "names no service" is an
+authoring rule this file keeps and pull-request review holds, because matching
+service names in prose would be a heuristic and loam does not guess.
+
+Which services carry which part of this is not written here and must not be:
+that is the fleet map's question, and `loam list capabilities` answers it from
+the `Capability:` lines the service specs already carry.
+
+## Requirements
+
+### Requirement: A confirmed order charges the customer exactly once
+Requirement-ID: CHECKOUT-CHARGE-ONCE
+The fleet SHALL charge a customer at most once for a single confirmed order,
+and SHALL confirm an order only after that charge has been authorized.
+
+#### Scenario: The customer submits the same order twice
+- **Given** a customer who has confirmed an order
+- **When** they submit the same order again without changing it
+- **Then** they are shown the order they already placed
+- **And** their card is charged only for the first one
+
+#### Scenario: Authorization is declined
+- **Given** a customer whose card is declined
+- **When** they confirm the order
+- **Then** no order is confirmed
+- **And** they are told the payment did not go through
+
+### Requirement: The price shown is the price charged
+Requirement-ID: CHECKOUT-PRICE-HONOURED
+The fleet SHALL charge the total the customer was shown at the moment they
+confirmed, even if a price changes while the order is being placed.
+
+#### Scenario: A price changes mid-checkout
+- **Given** a customer looking at a total of 40.00
+- **When** the price of an item rises before they confirm
+- **Then** confirming still charges 40.00

package/examples/docs/capabilities/identity/tokens/spec.md

@@ -0,0 +1,42 @@
+# Identity tokens
+
+Somebody signs in once and stays signed in for a while; the fleet has to keep
+answering "is this still them?" without asking again, and has to stop answering
+yes the moment it should not.
+
+This file also demonstrates NESTING, which is the part of the tree that is easy
+to get wrong when reading the layout. The id is `identity/tokens` — one id, with
+the slash inside it, exactly as `architecture/capabilities.yaml` spells the key
+and exactly as a requirement's `Capability:` line writes it. The tree does not
+collapse it and does not invent a separator: the id's own slashes ARE the
+directories, so the document lives at `capabilities/identity/tokens/spec.md`.
+
+`capabilities/identity/` therefore holds no `spec.md` of its own, and that earns
+no finding: a directory with a capability beneath it is a group. It would earn
+`capability.doc-missing` only if it held neither a document nor anything below.
+If the fleet later decides that `identity` is a capability in its own right,
+adding `capabilities/identity/spec.md` makes it one — a directory may be both a
+capability and the parent of others, because that is what the ids already say.
+
+## Requirements
+
+### Requirement: A revoked session stops working everywhere
+Requirement-ID: IDENTITY-REVOKE-EVERYWHERE
+When a person's session is revoked, the fleet SHALL stop honouring it — in
+every part of the product, not only the one they revoked it from.
+
+#### Scenario: Signing out of a lost phone
+- **Given** a person signed in on two devices
+- **When** they sign out one of them from the other
+- **Then** the signed-out device can no longer act as them
+
+### Requirement: A refused sign-in never says which half was wrong
+Requirement-ID: IDENTITY-ONE-REFUSAL
+When a sign-in is refused, the fleet SHALL give the same answer whether the
+account does not exist or the secret was wrong — a refusal that tells them apart
+lets anyone test which accounts exist.
+
+#### Scenario: An account that does not exist
+- **Given** a sign-in attempt for an account nobody has registered
+- **When** it is refused
+- **Then** the refusal is word for word the one a wrong password gets

package/examples/docs/capabilities/order-notifications/spec.md

@@ -0,0 +1,43 @@
+# Order notifications
+
+The customer has bought something and now wants to know it worked. Every event
+in an [order](../../glossary/order.md)'s life that they would want to hear about
+reaches them, once.
+
+This capability carries the example's demonstration of the axis's second
+realizer, and it is the reason the tree exists at all. The promise below is
+**cross-service by construction**: an order is placed in one service, the event
+crosses a broker, and a third service sends the message. No single service's
+`spec.md` can promise "exactly one confirmation", because each of them promises
+only its own part — `order-service` promises to announce the order,
+`notification-service` promises to send what it receives, and neither can
+promise what happens between them.
+
+A USE CASE can, because it IS the hop sequence. So
+`architecture/usecases/order-notification.likec4` carries `#req-NOTIFY-ONCE`
+beside its `#cap-order-notifications` tag, and that tag is the architect's
+answer to this promise: these hops, in this order, are what keeps it. loam
+grades the claim down to the operation, and `capability.requirement-unrealized`
+stays silent for this requirement because a flow keeps it.
+
+Written with no `Operations:`, `Covers:`, `Publishes:` or `Consumes:` line —
+those resolve against one service's own contract, and a capability requirement
+must be observable from outside the fleet.
+
+## Requirements
+
+### Requirement: A placed order produces exactly one confirmation
+Requirement-ID: NOTIFY-ONCE
+The fleet SHALL send a customer exactly one confirmation for an order they
+placed — not none if a service restarts mid-flight, and not two if a message is
+delivered twice.
+
+#### Scenario: The order is placed and the customer is told
+- **Given** a customer who has just placed an order
+- **When** the order is accepted
+- **Then** they receive one confirmation naming that order
+
+#### Scenario: The same event arrives twice
+- **Given** a confirmation already sent for an order
+- **When** the same event is delivered again
+- **Then** the customer receives nothing further

package/examples/docs/features/FEAT-101-payment-splitting/adrs/0001-dedicated-split-service.md

@@ -0,0 +1,18 @@
+---
+id: ADR-FEAT-101-0001
+status: accepted
+date: 2026-07-20
+feature: FEAT-101
+---
+
+# 1. Introduce a dedicated payment-split-service
+
+## Context
+Splitting logic is non-trivial and will be reused beyond checkout.
+
+## Decision
+Create a new bounded-context service `payment-split-service` rather than embedding the logic in `payment-service`.
+
+## Consequences
+- +1 service to operate, with clean ownership.
+- `payment-service` gains a synchronous dependency — modeled as `criticality: degradable` in its `health.yaml`.

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