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

package/examples/docs/features/archive/FEAT-120-refund-notification/.loam-before/files/architecture/landscape.likec4

@@ -0,0 +1,275 @@
+// 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'
+    }
+  }
+  // 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-120-refund-notification/.loam-before/files/services/payment-service/asyncapi.yaml

@@ -0,0 +1,96 @@
+# 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'
+
+operations:
+  sendPaymentAuthorized:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentAuthorized'
+  sendPaymentCaptured:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentCaptured'
+
+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
+    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

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

@@ -0,0 +1,82 @@
+---
+service: payment-service
+status: draft
+owner: payments-team
+sources:
+  - src/main/java/
+---
+
+# payment-service
+
+Owns payment authorization and capture. This is the **living spec** — the complete current
+state. Feature deltas (ADDED/MODIFIED/REMOVED requirements) merge in here on `loam archive`;
+`features/archive/` keeps every one of those deltas, so "which change introduced this
+requirement" stays a search rather than a record somebody has to maintain.
+
+## Requirements
+
+### Requirement: Authorize a payment
+
+Requirement-ID: PAY-AUTHORIZE
+The service SHALL reserve funds for an order before capture, and SHALL treat an authorization
+request as idempotent by order id so that a caller's timeout-and-retry never reserves twice.
+
+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
+
+### Requirement: Capture an authorized payment
+
+Requirement-ID: PAY-CAPTURE
+The service SHALL settle a previously authorized payment, and SHALL refuse to capture a payment
+it never authorized.
+
+Operations: capturePayment
+Publishes: payment.PaymentCaptured
+Requires: service/payments:capture
+
+#### Scenario: Capture an authorized payment
+- **Given** an authorized payment
+- **When** capture is requested
+- **Then** the payment is settled and a `PaymentCaptured` event is emitted
+
+#### Scenario: Capturing an unknown payment is refused
+- **Given** a payment id no authorization ever created
+- **When** capture is requested for it
+- **Then** the request is refused with 404 and nothing is settled
+
+### Requirement: Refund a captured payment
+
+Requirement-ID: PAY-REFUND
+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
+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

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

@@ -0,0 +1,164 @@
+# 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'
+  paymentEvents:
+    address: payment.events.v1
+    description: Payment lifecycle events, produced by payment-service's outbox relay
+    messages:
+      PaymentCaptured:
+        $ref: '#/components/messages/PaymentCaptured'
+  crmEvents:
+    address: crm.events.v1
+    description: Customer master-data events, produced by salesforce (outside the fleet)
+    messages:
+      CustomerUpdated:
+        $ref: '#/components/messages/CustomerUpdated'
+
+# 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'
+  receivePaymentCaptured:
+    action: receive
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentCaptured'
+  receiveCustomerUpdated:
+    action: receive
+    channel:
+      $ref: '#/channels/crmEvents'
+    messages:
+      - $ref: '#/channels/crmEvents/messages/CustomerUpdated'
+
+components:
+  messages:
+    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
+    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
+    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