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

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

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