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

package/examples/docs/features/archive/FEAT-120-refund-notification/.loam-before/files/services/platform/notification-service/spec.md

@@ -0,0 +1,91 @@
+---
+service: notification-service
+status: draft
+owner: growth-team
+sources:
+  - internal/consumer/
+  - internal/sender/
+  - cmd/notifier/
+---
+
+# notification-service
+
+Turns fleet events into customer email and SMS. This is the **living spec** — the complete
+current state; feature deltas merge in here on `loam archive`.
+
+This service exposes **no HTTP API**: the liveness and readiness probes in `health.yaml` are the
+only ports it listens on, and nothing in the fleet calls them. That is a documented shape rather
+than a gap — no edge in the landscape carries `metadata { op }` into this service, so
+`loam validate` stays silent about the missing `openapi.yaml` instead of warning. The silence is
+earned rather than granted: it turns into a warning the moment the landscape stops proving
+nobody calls this service — it goes missing, or it stops parsing — and into an error the moment
+a requirement here grows an `Operations:` line or an op-linked edge points in. Every requirement
+below therefore carries a `Consumes:` line and no `Operations:` line: what this service promises
+is a reaction to a message, and the message name is the only join it has.
+
+## Requirements
+
+### Requirement: Notify a customer when an order is placed
+
+Requirement-ID: NTF-ORDER-PLACED
+The service SHALL send exactly one order-confirmation notification per order, addressed to the
+contact details it holds for the customer at the moment the confirmation is rendered.
+
+Consumes: order.OrderPlaced
+Capability: order-notifications
+
+#### Scenario: First delivery of an order event
+- **Given** an `order.OrderPlaced` carrying an `orderId` this service has never sent a confirmation for
+- **When** the consumer handles it
+- **Then** a confirmation is rendered from the contact details on file and handed to the provider
+- **And** the delivery log records the send under that `orderId`
+
+#### Scenario: The broker redelivers an event already sent
+- **Given** a confirmation already recorded in the delivery log for that `orderId`
+- **When** kafka redelivers the same `order.OrderPlaced`
+- **Then** no second notification is sent and the event is acknowledged
+- **And** the customer is not told twice about one order
+
+### Requirement: Send a receipt when a payment is captured
+
+Requirement-ID: NTF-RECEIPT
+The service SHALL send a receipt for every captured payment, stating the captured amount and
+currency exactly as the capture reported them.
+
+Consumes: payment.PaymentCaptured
+Capability: order-notifications
+
+#### Scenario: Receipt follows a capture
+- **Given** a `payment.PaymentCaptured` for an order this service has already confirmed
+- **When** the consumer handles it
+- **Then** a receipt showing `capturedAmount` in `currency` is sent to the contact on file
+
+#### Scenario: A capture arrives before the order it belongs to
+- **Given** a `payment.PaymentCaptured` whose `orderId` this service has not yet seen on the order topic
+- **When** the consumer handles it
+- **Then** the receipt is held until the matching `order.OrderPlaced` arrives, and sent then
+- **And** no receipt is sent for an order the customer has not been told exists
+
+### Requirement: Keep contact details current
+
+Requirement-ID: NTF-CONTACT
+The service SHALL keep its copy of a customer's email and phone in step with the CRM, applying
+an update only when it is newer than the copy already held.
+
+Consumes: crm.CustomerUpdated
+
+#### Scenario: A newer update replaces the copy on file
+- **Given** contact details held at `version` 4 for a customer
+- **When** a `crm.CustomerUpdated` for that customer arrives at `version` 5
+- **Then** the stored email and phone are replaced with the ones the event carries
+
+#### Scenario: An out-of-order update is ignored
+- **Given** contact details held at `version` 5 for a customer
+- **When** a `crm.CustomerUpdated` for that customer arrives at `version` 4
+- **Then** the stored details are left as they are
+- **And** the next notification still goes to the newer address
+
+#### Scenario: A customer this service has never notified
+- **Given** a `crm.CustomerUpdated` for a `customerId` with no contact details on file
+- **When** the consumer handles it
+- **Then** the details are stored, so the first notification for that customer is addressable

package/examples/docs/features/archive/FEAT-120-refund-notification/.loam-before/manifest.json

@@ -0,0 +1,46 @@
+{
+  "version": 3,
+  "feature": "FEAT-120",
+  "dirName": "FEAT-120-refund-notification",
+  "archivedAt": "2026-08-28T18:50:02.492Z",
+  "files": [
+    {
+      "path": "services/platform/notification-service/spec.md",
+      "service": "notification-service",
+      "artifact": "spec.md",
+      "existed": true,
+      "after": "94f8507d205439b713f344663f94c04e54b738d991e84acf381b381889d36264",
+      "before": "3be6c0aaa97062abe82b07ade26d901b1a29d4dfc4efdb9ee8fa2228fd3071c5"
+    },
+    {
+      "path": "services/payment-service/spec.md",
+      "service": "payment-service",
+      "artifact": "spec.md",
+      "existed": true,
+      "after": "14b02e45cbf3ed5a3a2a2f94afea36ee2c95179f0c2a78703af7680d1b4efd3f",
+      "before": "22b06835887686f28b8212a4c1ca89fe2cbf42f49497786fcf76bb9bf1e5ca61"
+    },
+    {
+      "path": "services/platform/notification-service/asyncapi.yaml",
+      "service": "notification-service",
+      "artifact": "asyncapi.yaml",
+      "existed": true,
+      "after": "c868aefa3c3bc2b72cab83c86e4fd4d803480a8a9b2ffc61bfa50af2922bfeae",
+      "before": "f7f788c1b7ee51593bc96441cd062876f4df89932c6ef65d99f451d843f1c0b6"
+    },
+    {
+      "path": "services/payment-service/asyncapi.yaml",
+      "service": "payment-service",
+      "artifact": "asyncapi.yaml",
+      "existed": true,
+      "after": "c79f510cb4d3f7b1a55ee1f1989c033f306e7cc80b96d09f13e95480647ec7b8",
+      "before": "8386d542683df59643eafabdb35ebf77fab370b5622614a82071f8566887b8e9"
+    },
+    {
+      "path": "architecture/landscape.likec4",
+      "existed": true,
+      "after": "eb7325adc158f06f883e15473b97960c6340fa2a046090dd80ba10460d5a8499",
+      "before": "93ce5bbe908a54949700d4a7a8992ca1eebbcbbfb1ffef7eb28548521890148b"
+    }
+  ]
+}

package/examples/docs/features/archive/FEAT-120-refund-notification/delta.likec4

@@ -0,0 +1,36 @@
+// FEAT-120 — architecture delta.
+//
+// One new edge: the refund event reaching the service that tells the customer.
+// Everything tagged #FEAT-120 is exactly what `loam archive` folds into
+// architecture/landscape.likec4; the elements below are untagged context so the
+// view has something to draw the edge between.
+
+specification {
+  element softwareSystem
+  element topic
+  tag FEAT-120
+}
+
+model {
+  marketplace = softwareSystem 'marketplace' {
+    notificationService = softwareSystem 'notification-service'
+  }
+  kafka = softwareSystem 'kafka' {
+    paymentEvents = topic 'payment.events'
+  }
+
+  // `consumes` binds the edge's TARGET, which is why this arrow points out of
+  // the topic and into the service: the consumer is what the message reaches.
+  kafka.paymentEvents -> marketplace.notificationService 'PaymentRefunded triggers the refund notice' {
+    #FEAT-120
+    metadata {
+      consumes 'payment.PaymentRefunded'
+    }
+  }
+}
+
+views {
+  view feat_120 {
+    include *
+  }
+}

package/examples/docs/features/archive/FEAT-120-refund-notification/intent.md

@@ -0,0 +1,22 @@
+---
+feature: FEAT-120
+status: built
+owner: growth-team
+---
+
+# FEAT-120 — Tell the customer when a refund is issued
+
+FEAT-088 gave the fleet refunds, and stopped at the money. A customer whose order is
+cancelled after capture gets their funds back and hears nothing: support tickets asking
+"has my refund gone through" are the second-most common contact reason this quarter,
+behind delivery.
+
+The refund already happens at a point payment-service knows exactly — the acquirer has
+reconciled and the payment is recorded as refunded. That is the moment worth announcing,
+and nothing announces it. This feature puts `payment.PaymentRefunded` on the existing
+payment topic and has notification-service turn it into the message the customer is
+waiting for.
+
+Deliberately NOT in scope: a refund status endpoint. A customer who has been told does
+not need somewhere to look, and an endpoint nobody calls is a contract to maintain
+forever. If the tickets continue after this ships, that is the evidence for one.

package/examples/docs/features/archive/FEAT-120-refund-notification/scenario-report.json

@@ -0,0 +1,10 @@
+{
+  "loamScenarioReport": 1,
+  "results": [
+    { "digest": "f8974d79182ec37d", "status": "passed", "test": "RefundPaymentTest#refundsInFull" },
+    { "digest": "24ec0c2dceacc6b0", "status": "passed", "test": "RefundPaymentTest#refusesSecondRefund" },
+    { "digest": "7affc9a6ee57a0d8", "status": "passed", "test": "RefundOutboxTest#publishesOnceAfterReconciliation" },
+    { "digest": "b0bb55d679e9c5c2", "status": "passed", "test": "TestRefundNotice_SendsOnce" },
+    { "digest": "b690937cc4dfdc74", "status": "passed", "test": "TestRefundNotice_IgnoresRedelivery" }
+  ]
+}

package/examples/docs/features/archive/FEAT-120-refund-notification/specs/notification-service/asyncapi.yaml

@@ -0,0 +1,208 @@
+# The async contract — read-only. Every operation here carries `action: receive`:
+# this service produces no message and exposes no HTTP operation, so the whole of
+# what it promises the fleet is what it does with three topics.
+#
+# AsyncAPI 3.0 only. Its operations are named top-level objects carrying
+# `action: send|receive`, which is what makes a message's direction legible;
+# 2.x spells the same thing as publish/subscribe under a channel, where the two
+# words are ambiguous about whose perspective they take — and a 2.x document
+# reads here as a contract with no messages at all.
+#
+# The name is the spine: the landscape edge's `metadata { consumes }`, the
+# requirement's `Consumes:` line and `name` below are one name spelled three
+# times, and they must be identical. For a consumer the line that grades THIS
+# file is the requirement's — a `Consumes:` naming a message no operation here
+# receives is `spec-event.message-undefined`. The edge's copy answers the other
+# question, the one no single repository can: whether anybody publishes the
+# name at all. Deleting a `Consumes:` line therefore does not move a check onto
+# the landscape, it removes one.
+#
+# WHY THE PAYLOADS ARE HERE AT ALL, and why one of them is different in kind:
+#
+#   * `order.OrderPlaced` and `payment.PaymentCaptured` are produced INSIDE the
+#     fleet, so order-service's and payment-service's own asyncapi.yaml are the
+#     authoritative contracts. What is restated below is the subset this consumer
+#     actually reads — enough that the handler is codeable from this file, not a
+#     second source of truth for the event.
+#
+#   * `crm.CustomerUpdated` is produced by `salesforce`, an `#external` element in
+#     the landscape. There is no services/salesforce/, there never will be, and so
+#     no producer contract exists anywhere in this docs repo. That is a legal
+#     shape — loam recognizes an external producer and does not report
+#     `spine.message-unproduced` — but it shifts the contract question onto the
+#     only file that can answer it: this one. `spine.message-external` (warn)
+#     fires for exactly as long as this document defines no shape for the message,
+#     and stops the moment it does. The payload below is therefore not a
+#     convenience copy; it IS the fleet's contract for that message, and the
+#     reason the finding is absent from this service's validate output.
+asyncapi: 3.0.0
+info:
+  title: notification-service events
+  version: "1.0"
+
+channels:
+  orderEvents:
+    address: order.events.v1
+    description: Order lifecycle events, produced by order-service
+    messages:
+      OrderPlaced:
+        $ref: '#/components/messages/OrderPlaced'
+    x-loam-based-on: dfe4fe6a1cca0df9
+  paymentEvents:
+    address: payment.events.v1
+    description: Payment lifecycle events, produced by payment-service's outbox relay
+    messages:
+      PaymentCaptured:
+        $ref: '#/components/messages/PaymentCaptured'
+      # NEW: the same topic, one more message. A consumer that already reads
+      # payment.events for the receipt reads the refund from it too.
+      PaymentRefunded:
+        $ref: '#/components/messages/PaymentRefunded'
+    x-loam-based-on: 12f1f33accf4b2a1
+  crmEvents:
+    address: crm.events.v1
+    description: Customer master-data events, produced by salesforce (outside the fleet)
+    messages:
+      CustomerUpdated:
+        $ref: '#/components/messages/CustomerUpdated'
+    x-loam-based-on: c3a0af34dc0301d7
+
+# One operation per message rather than one per channel, so that adding a second
+# message to a topic later is an addition here instead of a silent widening: an
+# operation that lists no messages applies to EVERY message of its channel, and
+# would start receiving contracts nobody read.
+operations:
+  receiveOrderPlaced:
+    action: receive
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderPlaced'
+    x-loam-based-on: 93b230182c7aa28f
+  receivePaymentCaptured:
+    action: receive
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentCaptured'
+    x-loam-based-on: 6d19f39f58ff9ef5
+  receivePaymentRefunded:
+    action: receive
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentRefunded'
+  receiveCustomerUpdated:
+    action: receive
+    channel:
+      $ref: '#/channels/crmEvents'
+    messages:
+      - $ref: '#/channels/crmEvents/messages/CustomerUpdated'
+    x-loam-based-on: b1a4223de79dc101
+
+components:
+  messages:
+    # The consumer's copy of the producer's contract. loam checks the NAME
+    # joins; keeping the payload here is what lets a reader of this service
+    # see what it actually receives without opening payment-service.
+    PaymentRefunded:
+      name: payment.PaymentRefunded
+      title: Payment refunded
+      payload:
+        type: object
+        required: [ paymentId, orderId, refundedAmount, currency, refundedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          refundedAmount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          refundedAt:
+            type: string
+            format: date-time
+    OrderPlaced:
+      # Namespaced by the domain that OWNS the message, never by the service
+      # reading it: `order.` says order-service is the one producer, and two
+      # services declaring they send this name would be
+      # `asyncapi.message-contested` — which contract a consumer reads must not
+      # be a coin flip.
+      name: order.OrderPlaced
+      title: Order placed
+      payload:
+        type: object
+        # A payload declaring no shape — absent, or a bare `type: object` — is
+        # `asyncapi.payload-undescribed`: the name joins the spine while nothing
+        # says what a handler would read. loam probes for presence and never
+        # reads a field, which is what keeps a later move to Avro a
+        # `schemaFormat:` line here and no change in loam.
+        required: [ orderId, customerId, placedAt ]
+        properties:
+          orderId:
+            type: string
+            format: uuid
+            description: The idempotency key for the confirmation — one send per orderId
+          customerId:
+            type: string
+            format: uuid
+          placedAt:
+            type: string
+            format: date-time
+      x-loam-based-on: 15e75c9de066971f
+    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
+            format: uuid
+            description: What joins a receipt to the order the customer was told about
+          capturedAmount:
+            type: integer
+            description: minor units, restated on the receipt exactly as captured
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          capturedAt:
+            type: string
+            format: date-time
+      x-loam-based-on: 543d75dc0e0e3199
+    CustomerUpdated:
+      name: crm.CustomerUpdated
+      title: Customer contact details updated
+      payload:
+        type: object
+        # `version` is load-bearing rather than descriptive: the CRM redelivers
+        # and reorders, and the "out-of-order update is ignored" scenario in
+        # spec.md is only implementable because this field is in the contract.
+        # Nothing outside this document defines it.
+        required: [ customerId, version, updatedAt ]
+        properties:
+          customerId:
+            type: string
+            format: uuid
+          version:
+            type: integer
+            description: Monotonic per customer; an update at or below the stored version is
+              dropped
+          email:
+            type: string
+            format: email
+          phone:
+            type: string
+            description: E.164; absent when the customer has no phone on record
+          updatedAt:
+            type: string
+            format: date-time
+      x-loam-based-on: ff659a336b678a26

package/examples/docs/features/archive/FEAT-120-refund-notification/specs/notification-service/spec.md

@@ -0,0 +1,24 @@
+# notification-service — requirement delta for FEAT-120
+
+## ADDED Requirements
+
+### Requirement: Notify a customer when a refund completes
+
+Requirement-ID: NTF-REFUND
+The service SHALL send exactly one refund notification per refunded payment, stating the
+refunded amount and currency exactly as the refund reported them, and SHALL NOT send one
+until the refund is complete.
+
+Consumes: payment.PaymentRefunded
+Capability: order-notifications
+
+#### Scenario: A completed refund is announced once
+- **Given** a `payment.PaymentRefunded` for an order this service has already confirmed
+- **When** the consumer handles it
+- **Then** a refund notification is rendered with the refunded amount and currency
+- **And** the delivery log records the send under that `paymentId`
+
+#### Scenario: The broker redelivers a refund already announced
+- **Given** a refund notification already recorded in the delivery log for that `paymentId`
+- **When** kafka redelivers the same `payment.PaymentRefunded`
+- **Then** no second notification is sent and the event is acknowledged

package/examples/docs/features/archive/FEAT-120-refund-notification/specs/payment-service/asyncapi.yaml

@@ -0,0 +1,137 @@
+# The async contract — the messages this service puts on the bus.
+#
+# AsyncAPI 3.0 only. Its operations are named top-level objects carrying
+# `action: send|receive`, which is what makes a message's direction legible;
+# 2.x spells the same thing as publish/subscribe under a channel, where the
+# two words are ambiguous about whose perspective they take.
+#
+# loam reads message NAMES and the `action` of the operation carrying them.
+# It never joins on anything inside `payload` — the one look inside is a
+# presence probe (a payload declaring no shape at all warns, a non-JSON
+# `schemaFormat` is skipped) — which is what keeps swapping JSON Schema for
+# Avro a `schemaFormat` line here rather than a change in loam.
+#
+# The name is the spine: the landscape edge's `metadata { publishes }`, the
+# requirement's `Publishes:` line and `name` below are one name spelled three
+# times, and they must be identical.
+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'
+      # NEW: the refund rides the existing lifecycle topic rather than one of
+      # its own — a consumer already filtering payment.events for a capture is
+      # the same consumer that wants the refund.
+      PaymentRefunded:
+        $ref: '#/components/messages/PaymentRefunded'
+    x-loam-based-on: 036cbb7e0245e1a9
+
+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
+  # NEW: announced once, and only after the acquirer has reconciled.
+  sendPaymentRefunded:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentRefunded'
+
+components:
+  messages:
+    # NEW: the money is back and the acquirer agrees. `refundedAmount` is what
+    # the refund actually returned, which is not always the captured amount —
+    # a partial refund is the same event with a smaller number.
+    PaymentRefunded:
+      name: payment.PaymentRefunded
+      title: Payment refunded
+      payload:
+        type: object
+        required: [ paymentId, orderId, refundedAmount, currency, refundedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          refundedAmount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          refundedAt:
+            type: string
+            format: date-time
+    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

package/examples/docs/features/archive/FEAT-120-refund-notification/specs/payment-service/spec.md

@@ -0,0 +1,31 @@
+# payment-service — requirement delta for FEAT-120
+
+## MODIFIED Requirements
+
+### Requirement: Refund a captured payment
+
+Requirement-ID: PAY-REFUND
+Based-On: 0d5b4ce25f5b07ae
+The service SHALL return captured funds to the customer's payment method, SHALL reconcile the
+refund against the acquirer before reporting it complete, and SHALL refuse a second refund of a
+payment it has already refunded.
+
+Operations: refundPayment
+Publishes: payment.PaymentRefunded
+Requires: user/payments:refund
+
+#### Scenario: Refund a captured payment in full
+- **Given** a captured payment of 100.00 USD
+- **When** a refund is requested for it
+- **Then** 100.00 USD is returned to the customer's payment method
+- **And** the payment is recorded as refunded
+
+#### Scenario: A second refund of the same payment is refused
+- **Given** a payment already refunded in full
+- **When** a refund is requested for it again
+- **Then** the request is refused with 409 and no second refund is issued
+
+#### Scenario: The refund is announced only after the acquirer reconciles
+- **Given** a refund accepted by the acquirer but not yet reconciled
+- **When** the reconciliation completes
+- **Then** `payment.PaymentRefunded` is published exactly once for that payment