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

package/examples/docs/architecture/landscape.likec4

@@ -0,0 +1,280 @@
+// 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
+  // The capability a use case opts in with. `architecture/usecases/` declares
+  // no 'specification` of its own — the whole directory is ONE LikeC4 project,
+  // and a second declaration there is a duplicate error blamed on both files —
+  // so a tag a flow carries is declared here, beside the kinds.
+  tag cap-order-notifications
+  // The requirement tag beside it: a flow says WHICH of the capability's named
+  // promises it keeps, and the id is spelled with every character a tag name
+  // cannot carry flattened to `-`. Declared here for the same reason — one
+  // specification block serves the whole `architecture/` project.
+  tag req-NOTIFY-ONCE
+  // An ARCHITECTURAL OBLIGATION, declared in architecture/obligations.yaml and
+  // applied HERE, on the objects it holds for. The decision itself is
+  // architecture/adrs/0001-transactional-outbox.md; this tag is the architect
+  // saying where it applies, and payment-service's ARCH-PAY-OUTBOX is the team
+  // saying it is met. Applied to the edge rather than to the service, because
+  // an outbox is a property of publishing, and payment-service also calls an
+  // API that owes nothing of the kind.
+  tag obl-outbox
+}
+
+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' {
+    #obl-outbox
+    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'
+    }
+  }
+  marketplace.orderService -> marketplace.paymentService 'Calls refundPayment' {
+    metadata { op 'refundPayment' }
+  }
+  kafka.orderEvents -> marketplace.notificationService 'OrderPlaced triggers the confirmation' {
+    metadata {
+      consumes 'order.OrderPlaced'
+    }
+  }
+  kafka.paymentEvents -> marketplace.notificationService 'PaymentCaptured triggers the receipt' {
+    metadata {
+      consumes 'payment.PaymentCaptured'
+    }
+  }
+  kafka.paymentEvents -> marketplace.notificationService 'PaymentRefunded triggers the refund notice' {
+    metadata {
+      consumes 'payment.PaymentRefunded'
+    }
+  }
+  // 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/architecture/obligations.yaml

@@ -0,0 +1,23 @@
+# The fleet's ARCHITECTURAL OBLIGATIONS: rules an architect decided once and
+# applies where they apply. The decision itself lives in an ADR; a `#obl-<id>`
+# tag on architecture/landscape.likec4 says WHERE it holds; and the owning
+# team's `Covers:` line in its arch.spec.md says it is met, with a scenario.
+#
+# The three grades this file earns are the point of declaring names at all: a
+# tag naming nothing here is `obligation.unknown` (error — a typo reads exactly
+# like a rule), a name nothing tags is `obligation.unapplied` (warn), and a
+# tagged object no living requirement covers is `obligation.uncovered` (warn).
+#
+# An id is its own tag suffix, so it may hold letters, digits, `_` and `-` only.
+obligations:
+  outbox:
+    description: >-
+      A service that publishes a domain event writes the event and the state
+      change it reports in one transaction, relayed to the broker afterwards —
+      never a dual write.
+    adr: architecture/adrs/0001-transactional-outbox.md
+  idempotency-key:
+    description: >-
+      A write a caller may retry accepts an idempotency key and returns the
+      first result for a repeat. Declared and applied nowhere yet, which is
+      what `obligation.unapplied` is for.

package/examples/docs/architecture/permissions.yaml

@@ -0,0 +1,50 @@
+# The fleet's authorization vocabulary, joined to requirements by `Requires:`.
+#
+# Opt-in: a fleet with no `Requires:` line owes no file at all. The first such line makes an
+# absent declaration an error rather than letting each service invent a permission locally,
+# which is how one capability ends up spelled three ways across three repositories.
+#
+# The unit is the pair `<subject>/<permission>`. The subject is the entity the check is
+# performed ON — `user` for a customer acting on their own data, `service` for a fleet service
+# acting on its own behalf — not necessarily the caller. `loam validate` grades exactly two
+# things here: that every `Requires:` pair is declared (`permissions.unknown`, error), and that
+# every declared pair is named by some requirement (`permissions.unenforced`, warning — the
+# authorization mirror of `api.ungoverned`).
+#
+# `owned_by` and `enforced_by` are explanatory and are NOT resolved against services/. This is a
+# spelling and coverage join, not an identity-provider audit: nothing here proves the running
+# system implements a declared permission, and pretending otherwise would be the most dangerous
+# green tick in the repository.
+subjects:
+  user:
+    description: a human account acting on its own data
+  service:
+    description: a fleet service acting on its own behalf, with a machine token
+
+permissions:
+  user:
+    payments:refund:
+      description: refund a captured payment
+      owned_by: identity-service
+      enforced_by: [payment-service]
+    orders:cancel:
+      description: cancel an order that has not shipped
+      owned_by: identity-service
+      enforced_by: [order-service]
+    # Declared, and named by no requirement anywhere in the fleet — the example's
+    # `permissions.unenforced` (warning) demonstration. It is the shape a vocabulary drifts
+    # into: a permission survives the feature that introduced it, the requirement that needed
+    # it is rewritten, and the declaration stays behind looking enforced.
+    profile:read:
+      description: read a customer's own profile
+      owned_by: identity-service
+      enforced_by: [identity-service]
+  service:
+    payments:capture:
+      description: capture funds a previous authorization reserved
+      owned_by: identity-service
+      enforced_by: [payment-service]
+    tokens:introspect:
+      description: ask identity-service what a token currently grants
+      owned_by: identity-service
+      enforced_by: [identity-service]

package/examples/docs/architecture/subsystems.likec4

@@ -0,0 +1,11 @@
+// generated by loam — the subsystem tree under services/, one view per subsystem.
+// Do not edit: `loam subsystem sync` regenerates this file from the directories,
+// and `loam validate --all` reports `subsystem.views-stale` when it drifts.
+
+views {
+  // services/platform
+  view subsystem_platform {
+    include marketplace.identityService
+    include marketplace.notificationService
+  }
+}

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`.