@shortlink-org/portolan 0.1.0

package/src/testing/estate/data__flows.json

@@ -0,0 +1,1724 @@
+{
+  "generatedAt": "2026-09-05T00:22:18+07:00",
+  "commit": "8149120",
+  "contexts": [],
+  "defs": {},
+  "flows": [
+    {
+      "id": "flow.checkout",
+      "slug": "checkout",
+      "name": "Checkout",
+      "summary": "Basket to dispatch, as the e2e suite drives it: a priced basket, a risk call whose peer is not in the catalog, an outbox publish, an authorization at the gateway, a capture retried with backoff, and a shipment held until the money lands. Three branches and two hops are read from the code rather than observed.",
+      "source": "services/oms/test/e2e/checkout_test.go",
+      "owner": "shop",
+      "participants": [
+        {
+          "id": "customer",
+          "kind": "actor",
+          "context": null
+        },
+        {
+          "id": "shop.oms",
+          "kind": "service",
+          "context": "shop"
+        },
+        {
+          "id": "oms-db",
+          "kind": "store",
+          "context": "shop",
+          "label": "oms-db (postgres)"
+        },
+        {
+          "id": "shop.pricing",
+          "kind": "service",
+          "context": "shop"
+        },
+        {
+          "id": "fraud-scoring",
+          "kind": "unknown",
+          "context": null,
+          "label": "fraud-scoring (unknown)"
+        },
+        {
+          "id": "bus",
+          "kind": "broker",
+          "context": null
+        },
+        {
+          "id": "payments.ledger",
+          "kind": "service",
+          "context": "payments"
+        },
+        {
+          "id": "psp-gateway",
+          "kind": "external",
+          "context": null,
+          "label": "psp-gateway (external)"
+        },
+        {
+          "id": "delivery.core",
+          "kind": "service",
+          "context": "delivery"
+        }
+      ],
+      "steps": [
+        {
+          "type": "step",
+          "id": "s1",
+          "from": "customer",
+          "to": "shop.oms",
+          "kind": "rpc",
+          "label": "PlaceOrder",
+          "status": "verified",
+          "note": "HTTP edge. The handler requires an Idempotency-Key header and replays the stored response for a key it has already answered, so a double-tapped checkout cannot open two orders.",
+          "line": "checkout_test.go:62"
+        },
+        {
+          "type": "step",
+          "id": "s2",
+          "from": "shop.oms",
+          "to": "oms-db",
+          "kind": "call",
+          "label": "loadBasket",
+          "status": "verified",
+          "line": "internal/oms/adapter/postgres/basket_repo.go:58"
+        },
+        {
+          "type": "step",
+          "id": "s3",
+          "from": "shop.oms",
+          "to": "shop.oms",
+          "kind": "call",
+          "label": "validateBasket",
+          "status": "verified",
+          "note": "Rejects empty baskets and lines whose stock reservation has expired. Runs before anything leaves the process.",
+          "line": "internal/oms/app/checkout.go:88"
+        },
+        {
+          "type": "step",
+          "id": "s4",
+          "from": "shop.oms",
+          "to": "shop.pricing",
+          "kind": "rpc",
+          "ref": "shop.v1.Pricing/GetQuote",
+          "label": "GetQuote",
+          "status": "verified",
+          "note": "250 ms deadline, one retry on UNAVAILABLE.",
+          "line": "internal/oms/app/checkout.go:104"
+        },
+        {
+          "type": "alt",
+          "id": "alt-quote",
+          "branches": [
+            {
+              "title": "pricing answers within the deadline",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s5",
+                  "from": "shop.pricing",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "shop.pricing.quote.QuoteIssued",
+                  "label": "QuoteIssued",
+                  "status": "verified",
+                  "note": "Published for the audit trail. The price checkout actually uses is the synchronous response above, not this event.",
+                  "line": "checkout_test.go:96"
+                }
+              ]
+            },
+            {
+              "title": "pricing deadline exceeded",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s6",
+                  "from": "shop.oms",
+                  "to": "oms-db",
+                  "kind": "call",
+                  "label": "readLastPriceSnapshot",
+                  "status": "declared",
+                  "note": "Falls back to the snapshot written by the last price-list import and marks the order repriceable. The e2e suite has no case for this branch; it is read from the code.",
+                  "line": "internal/oms/app/checkout.go:118"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "step",
+          "id": "s7",
+          "from": "shop.oms",
+          "to": "fraud-scoring",
+          "kind": "rpc",
+          "ref": "fraud.v2.Scoring/Score",
+          "label": "Score",
+          "status": "unresolved",
+          "note": "No service in the catalog provides fraud.v2.Scoring. The address comes from FRAUD_ADDR at runtime, so the peer cannot be resolved statically.",
+          "line": "internal/oms/client/fraud.go:22"
+        },
+        {
+          "type": "alt",
+          "id": "alt-risk",
+          "branches": [
+            {
+              "title": "score below 40",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s8",
+                  "from": "shop.oms",
+                  "to": "shop.oms",
+                  "kind": "call",
+                  "label": "acceptOrder",
+                  "status": "verified",
+                  "line": "checkout_test.go:131"
+                }
+              ]
+            },
+            {
+              "title": "score at or above 40",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s9",
+                  "from": "shop.oms",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "shop.oms.order.OrderCancelled",
+                  "label": "OrderCancelled",
+                  "status": "declared",
+                  "note": "The customer is shown a generic decline and the score never reaches the edge. Declared: the suite has no high-score fixture.",
+                  "line": "internal/oms/app/checkout.go:176"
+                }
+              ],
+              "terminal": true
+            },
+            {
+              "title": "scorer did not answer within 800 ms",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s10",
+                  "from": "shop.oms",
+                  "to": "shop.oms",
+                  "kind": "call",
+                  "label": "failOpenAndFlagForReview",
+                  "status": "declared",
+                  "note": "The order continues and is queued for manual review. Failing open is read from the code; nothing exercises the timeout.",
+                  "line": "internal/oms/app/checkout.go:161"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "step",
+          "id": "s11",
+          "from": "shop.oms",
+          "to": "oms-db",
+          "kind": "call",
+          "label": "persistOrderAndOutboxRow",
+          "status": "verified",
+          "note": "One transaction for the order and the OrderPlaced outbox row. The order-accepted flow pins this hop on its own.",
+          "line": "internal/oms/app/checkout.go:191"
+        },
+        {
+          "type": "loop",
+          "id": "loop-outbox",
+          "title": "outbox relay, every 200 ms until the batch is empty",
+          "steps": [
+            {
+              "type": "step",
+              "id": "s12",
+              "from": "shop.oms",
+              "to": "bus",
+              "kind": "event",
+              "ref": "shop.oms.order.OrderPlaced",
+              "label": "OrderPlaced",
+              "status": "verified",
+              "line": "checkout_test.go:118"
+            },
+            {
+              "type": "step",
+              "id": "s13",
+              "from": "shop.oms",
+              "to": "oms-db",
+              "kind": "call",
+              "label": "markOutboxRowSent",
+              "status": "verified",
+              "note": "Marking happens after the broker acks, so a crash in between republishes rather than drops. Consumers are expected to tolerate the repeat.",
+              "line": "internal/oms/adapter/postgres/outbox.go:73"
+            }
+          ]
+        },
+        {
+          "type": "parallel",
+          "id": "par-placed",
+          "title": "OrderPlaced fan-out",
+          "branches": [
+            [
+              {
+                "type": "step",
+                "id": "s14",
+                "from": "bus",
+                "to": "payments.ledger",
+                "kind": "event",
+                "ref": "shop.oms.order.OrderPlaced",
+                "label": "OrderPlaced",
+                "status": "verified",
+                "note": "Consumer group `ledger-orders`. Opens the reconciliation record the gateway webhook later matches against.",
+                "line": "checkout_test.go:126"
+              }
+            ],
+            [
+              {
+                "type": "step",
+                "id": "s15",
+                "from": "bus",
+                "to": "shop.pricing",
+                "kind": "event",
+                "ref": "shop.oms.order.OrderPlaced",
+                "label": "OrderPlaced",
+                "status": "declared",
+                "note": "Pricing marks the quote consumed. The subscription is registered in code but no test drives it.",
+                "line": "internal/pricing/app/subscribe.go:38"
+              }
+            ]
+          ]
+        },
+        {
+          "type": "step",
+          "id": "s16",
+          "from": "shop.oms",
+          "to": "payments.ledger",
+          "kind": "rpc",
+          "ref": "payments.v1.Payments/Authorize",
+          "label": "Authorize",
+          "status": "verified",
+          "note": "Carries the same idempotency key as the edge request, so a retried checkout cannot authorize twice.",
+          "line": "checkout_test.go:141"
+        },
+        {
+          "type": "alt",
+          "id": "alt-currency",
+          "branches": [
+            {
+              "title": "order currency is the acquirer's settlement currency",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s17",
+                  "from": "payments.ledger",
+                  "to": "payments.ledger",
+                  "kind": "call",
+                  "label": "settleDirect",
+                  "status": "verified",
+                  "note": "No conversion and no FX row: `settlement` is the order amount. This is every EUR order, which is most of them.",
+                  "line": "checkout_test.go:144"
+                }
+              ]
+            },
+            {
+              "title": "order currency differs from the settlement currency",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s18",
+                  "from": "payments.ledger",
+                  "to": "payments.ledger",
+                  "kind": "call",
+                  "label": "quoteFxRate",
+                  "status": "declared",
+                  "note": "The rate comes from the acquirer, not from the daily reference feed, and is refused if it is more than 60 s old. It is stored on the payment so the posting can be reproduced later.",
+                  "line": "internal/ledger/app/fx.go:38"
+                }
+              ]
+            },
+            {
+              "title": "no acquirer is configured for the currency",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s19",
+                  "from": "payments.ledger",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentDeclined",
+                  "label": "PaymentDeclined",
+                  "status": "declared",
+                  "note": "Code `currency_unsupported`, category `hard`. Nothing retries it and no other acquirer is tried, because there is only one.",
+                  "line": "internal/ledger/app/authorize.go:61"
+                },
+                {
+                  "type": "step",
+                  "id": "s20",
+                  "from": "bus",
+                  "to": "shop.oms",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentDeclined",
+                  "label": "PaymentDeclined",
+                  "status": "declared",
+                  "line": "internal/oms/app/decline.go:18"
+                },
+                {
+                  "type": "step",
+                  "id": "s21",
+                  "from": "shop.oms",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "shop.oms.order.OrderCancelled",
+                  "label": "OrderCancelled",
+                  "status": "declared",
+                  "note": "The customer is told the currency is not accepted. This is the one decline that is worth saying out loud, and the edge says it.",
+                  "line": "internal/oms/app/decline.go:29"
+                }
+              ],
+              "terminal": true
+            }
+          ]
+        },
+        {
+          "type": "step",
+          "id": "s22",
+          "from": "payments.ledger",
+          "to": "psp-gateway",
+          "kind": "rpc",
+          "ref": "psp.v2.Charges/Create",
+          "label": "Charges.Create (auth only)",
+          "status": "unresolved",
+          "note": "Third-party gateway; no service in the estate provides psp.v2.Charges. A timeout here leaves the charge in a state only the gateway knows — the gateway-webhook flow is what resolves it.",
+          "line": "internal/ledger/adapter/psp/client.go:64"
+        },
+        {
+          "type": "alt",
+          "id": "alt-auth",
+          "branches": [
+            {
+              "title": "gateway approves",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s23",
+                  "from": "payments.ledger",
+                  "to": "payments.ledger",
+                  "kind": "call",
+                  "label": "postAuthorizationHold",
+                  "status": "verified",
+                  "line": "internal/ledger/app/authorize.go:88"
+                },
+                {
+                  "type": "step",
+                  "id": "s24",
+                  "from": "payments.ledger",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentAuthorized",
+                  "label": "PaymentAuthorized",
+                  "status": "verified",
+                  "line": "checkout_test.go:151"
+                },
+                {
+                  "type": "step",
+                  "id": "s25",
+                  "from": "bus",
+                  "to": "shop.oms",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentAuthorized",
+                  "label": "PaymentAuthorized",
+                  "status": "verified",
+                  "line": "checkout_test.go:154"
+                }
+              ]
+            },
+            {
+              "title": "gateway declines",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s26",
+                  "from": "payments.ledger",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentDeclined",
+                  "label": "PaymentDeclined",
+                  "status": "verified",
+                  "line": "checkout_test.go:167"
+                },
+                {
+                  "type": "step",
+                  "id": "s27",
+                  "from": "bus",
+                  "to": "shop.oms",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentDeclined",
+                  "label": "PaymentDeclined",
+                  "status": "verified",
+                  "line": "checkout_test.go:170"
+                },
+                {
+                  "type": "step",
+                  "id": "s28",
+                  "from": "shop.oms",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "shop.oms.order.OrderCancelled",
+                  "label": "OrderCancelled",
+                  "status": "declared",
+                  "note": "The order is cancelled and the basket released. The publish is in the decline handler; no assertion covers it.",
+                  "line": "internal/oms/app/decline.go:29"
+                }
+              ],
+              "terminal": true
+            }
+          ]
+        },
+        {
+          "type": "step",
+          "id": "s29",
+          "from": "shop.oms",
+          "to": "bus",
+          "kind": "event",
+          "ref": "shop.oms.order.OrderConfirmed",
+          "label": "OrderConfirmed",
+          "status": "verified",
+          "line": "checkout_test.go:158"
+        },
+        {
+          "type": "step",
+          "id": "s30",
+          "from": "bus",
+          "to": "delivery.core",
+          "kind": "event",
+          "ref": "shop.oms.order.OrderConfirmed",
+          "label": "OrderConfirmed",
+          "status": "verified",
+          "note": "Creates the shipment in `held`. Nothing is handed to a carrier until the capture lands.",
+          "line": "internal/delivery/app/subscribe.go:44"
+        },
+        {
+          "type": "loop",
+          "id": "loop-capture",
+          "title": "capture retried with exponential backoff, at most 5 attempts over 24 h",
+          "steps": [
+            {
+              "type": "step",
+              "id": "s31",
+              "from": "shop.oms",
+              "to": "payments.ledger",
+              "kind": "rpc",
+              "ref": "payments.v1.Payments/Capture",
+              "label": "Capture",
+              "status": "declared",
+              "note": "The e2e suite stubs the ledger from this point, so the capture leg is read from the client rather than observed.",
+              "line": "internal/oms/app/capture.go:33"
+            },
+            {
+              "type": "step",
+              "id": "s32",
+              "from": "payments.ledger",
+              "to": "psp-gateway",
+              "kind": "rpc",
+              "ref": "psp.v2.Charges/Capture",
+              "label": "Charges.Capture",
+              "status": "unresolved",
+              "line": "internal/ledger/adapter/psp/client.go:102"
+            },
+            {
+              "type": "step",
+              "id": "s33",
+              "from": "payments.ledger",
+              "to": "payments.ledger",
+              "kind": "call",
+              "label": "postJournalEntry",
+              "status": "verified",
+              "note": "Idempotent by (order_id, attempt), so a retry after a timeout cannot double-post. See ADR payments.0004.",
+              "line": "internal/ledger/app/capture.go:59"
+            },
+            {
+              "type": "step",
+              "id": "s34",
+              "from": "payments.ledger",
+              "to": "bus",
+              "kind": "event",
+              "ref": "payments.ledger.payment.PaymentCaptured",
+              "label": "PaymentCaptured",
+              "status": "declared",
+              "line": "internal/ledger/app/capture.go:91"
+            }
+          ]
+        },
+        {
+          "type": "alt",
+          "id": "alt-capture",
+          "branches": [
+            {
+              "title": "captured within the attempt budget",
+              "steps": [
+                {
+                  "type": "parallel",
+                  "id": "par-captured",
+                  "title": "PaymentCaptured fan-out",
+                  "branches": [
+                    [
+                      {
+                        "type": "step",
+                        "id": "s35",
+                        "from": "bus",
+                        "to": "delivery.core",
+                        "kind": "event",
+                        "ref": "payments.ledger.payment.PaymentCaptured",
+                        "label": "PaymentCaptured",
+                        "status": "verified",
+                        "note": "Releases the held shipment. This is the hop that turns money into a parcel.",
+                        "line": "checkout_test.go:188"
+                      }
+                    ],
+                    [
+                      {
+                        "type": "step",
+                        "id": "s36",
+                        "from": "bus",
+                        "to": "shop.oms",
+                        "kind": "event",
+                        "ref": "payments.ledger.payment.PaymentCaptured",
+                        "label": "PaymentCaptured",
+                        "status": "verified",
+                        "line": "checkout_test.go:190"
+                      }
+                    ]
+                  ]
+                }
+              ]
+            },
+            {
+              "title": "declined on every attempt",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "s37",
+                  "from": "payments.ledger",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentDeclined",
+                  "label": "PaymentDeclined",
+                  "status": "declared",
+                  "note": "After the fifth attempt the authorization has expired anyway. Category `soft`: the customer can pay again, but not on this order.",
+                  "line": "internal/ledger/app/capture.go:118"
+                },
+                {
+                  "type": "step",
+                  "id": "s38",
+                  "from": "bus",
+                  "to": "shop.oms",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentDeclined",
+                  "label": "PaymentDeclined",
+                  "status": "declared",
+                  "line": "internal/oms/app/decline.go:18"
+                },
+                {
+                  "type": "step",
+                  "id": "s39",
+                  "from": "shop.oms",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "shop.oms.order.OrderCancelled",
+                  "label": "OrderCancelled",
+                  "status": "declared",
+                  "line": "internal/oms/app/decline.go:29"
+                },
+                {
+                  "type": "step",
+                  "id": "s40",
+                  "from": "bus",
+                  "to": "delivery.core",
+                  "kind": "event",
+                  "ref": "shop.oms.order.OrderCancelled",
+                  "label": "OrderCancelled",
+                  "status": "declared",
+                  "note": "Drops the shipment that has been sitting in `held` since the order was confirmed. Nothing observed this hop — it is the failure path nobody has watched run.",
+                  "line": "internal/delivery/app/subscribe.go:62"
+                }
+              ],
+              "terminal": true
+            }
+          ]
+        },
+        {
+          "type": "step",
+          "id": "s41",
+          "from": "delivery.core",
+          "to": "delivery.core",
+          "kind": "call",
+          "label": "planRoute",
+          "status": "verified",
+          "line": "internal/delivery/app/route.go:71"
+        },
+        {
+          "type": "step",
+          "id": "s42",
+          "from": "delivery.core",
+          "to": "bus",
+          "kind": "event",
+          "ref": "delivery.core.route.RoutePlanned",
+          "label": "RoutePlanned",
+          "status": "declared",
+          "note": "OMS subscribes to this for the promised delivery date. The publish is in the planner; the suite asserts the shipment, not the route.",
+          "line": "internal/delivery/app/route.go:94"
+        },
+        {
+          "type": "step",
+          "id": "s43",
+          "from": "delivery.core",
+          "to": "bus",
+          "kind": "event",
+          "ref": "delivery.core.shipment.ShipmentDispatched",
+          "label": "ShipmentDispatched",
+          "status": "verified",
+          "line": "checkout_test.go:203"
+        },
+        {
+          "type": "step",
+          "id": "s44",
+          "from": "bus",
+          "to": "shop.oms",
+          "kind": "event",
+          "ref": "delivery.core.shipment.ShipmentDispatched",
+          "label": "ShipmentDispatched",
+          "status": "verified",
+          "line": "checkout_test.go:206"
+        },
+        {
+          "type": "step",
+          "id": "s45",
+          "from": "shop.oms",
+          "to": "customer",
+          "kind": "rpc",
+          "label": "order confirmation",
+          "status": "declared",
+          "note": "Handed to the transactional mail provider. The hop leaves the estate and nothing in the catalog covers what happens to it.",
+          "line": "internal/oms/notify/confirmation.go:27"
+        }
+      ]
+    },
+    {
+      "id": "flow.gateway-webhook",
+      "slug": "gateway-webhook",
+      "name": "Gateway webhook",
+      "summary": "The gateway's side of the story, arriving after the fact. One signed callback, four ways to read it: a replay to ignore, a capture to record, a charge with no local payment to adopt, and a failure to pass on. The adopt branch is the only repair for a checkout that timed out mid-authorization, and it is the one branch no test covers.",
+      "source": "services/ledger/test/integration/webhook_test.go",
+      "owner": "payments",
+      "participants": [
+        {
+          "id": "psp-gateway",
+          "kind": "external",
+          "context": null,
+          "label": "psp-gateway (external)"
+        },
+        {
+          "id": "payments.ledger",
+          "kind": "service",
+          "context": "payments"
+        },
+        {
+          "id": "bus",
+          "kind": "broker",
+          "context": null
+        },
+        {
+          "id": "shop.oms",
+          "kind": "service",
+          "context": "shop"
+        }
+      ],
+      "steps": [
+        {
+          "type": "step",
+          "id": "w1",
+          "from": "psp-gateway",
+          "to": "payments.ledger",
+          "kind": "rpc",
+          "label": "POST /webhooks/psp/v2",
+          "status": "verified",
+          "note": "HMAC-signed body. The gateway retries for three days with backoff until it gets a 2xx, so every branch below has to tolerate being run twice.",
+          "line": "webhook_test.go:38"
+        },
+        {
+          "type": "step",
+          "id": "w2",
+          "from": "payments.ledger",
+          "to": "payments.ledger",
+          "kind": "call",
+          "label": "verifySignatureAndParse",
+          "status": "verified",
+          "note": "A bad signature is answered 401 and never reaches the dedup table. The test drives a tampered body for this.",
+          "line": "internal/ledger/adapter/psp/webhook.go:44"
+        },
+        {
+          "type": "alt",
+          "id": "alt-webhook",
+          "branches": [
+            {
+              "title": "event id already applied",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "w3",
+                  "from": "payments.ledger",
+                  "to": "payments.ledger",
+                  "kind": "call",
+                  "label": "dropDuplicate",
+                  "status": "verified",
+                  "note": "Dedup table keyed by the gateway's event id, rows kept 30 days. A replay older than that would be applied again; nothing guards it.",
+                  "line": "webhook_test.go:71"
+                }
+              ]
+            },
+            {
+              "title": "charge.succeeded, matching a local authorization",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "w4",
+                  "from": "payments.ledger",
+                  "to": "payments.ledger",
+                  "kind": "call",
+                  "label": "markCaptured",
+                  "status": "verified",
+                  "line": "internal/ledger/app/webhook.go:96"
+                },
+                {
+                  "type": "step",
+                  "id": "w5",
+                  "from": "payments.ledger",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentCaptured",
+                  "label": "PaymentCaptured",
+                  "status": "verified",
+                  "line": "webhook_test.go:104"
+                }
+              ]
+            },
+            {
+              "title": "charge.succeeded, no local payment",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "w6",
+                  "from": "payments.ledger",
+                  "to": "shop.oms",
+                  "kind": "rpc",
+                  "ref": "shop.v1.Orders/GetOrder",
+                  "label": "GetOrder",
+                  "status": "verified",
+                  "note": "The order reference travels in the gateway's metadata. The ledger reads the order back to decide whether the charge belongs to this estate at all.",
+                  "line": "internal/ledger/app/webhook.go:132"
+                },
+                {
+                  "type": "step",
+                  "id": "w7",
+                  "from": "payments.ledger",
+                  "to": "payments.ledger",
+                  "kind": "call",
+                  "label": "adoptOrphanCharge",
+                  "status": "declared",
+                  "note": "Closes the gap left when the synchronous Authorize in checkout timed out after the gateway had already charged. Read from the code; the integration suite has no fixture for it, and it is the only path that keeps a customer from being charged for an order the estate never opened.",
+                  "line": "internal/ledger/app/webhook.go:151"
+                },
+                {
+                  "type": "step",
+                  "id": "w8",
+                  "from": "payments.ledger",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentAuthorized",
+                  "label": "PaymentAuthorized",
+                  "status": "declared",
+                  "note": "Published late and out of order — consumers see the authorization after the charge already settled.",
+                  "line": "internal/ledger/app/webhook.go:168"
+                }
+              ]
+            },
+            {
+              "title": "charge.failed",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "w9",
+                  "from": "payments.ledger",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentDeclined",
+                  "label": "PaymentDeclined",
+                  "status": "verified",
+                  "line": "webhook_test.go:126"
+                },
+                {
+                  "type": "step",
+                  "id": "w10",
+                  "from": "bus",
+                  "to": "shop.oms",
+                  "kind": "event",
+                  "ref": "payments.ledger.payment.PaymentDeclined",
+                  "label": "PaymentDeclined",
+                  "status": "verified",
+                  "line": "webhook_test.go:131"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "step",
+          "id": "w11",
+          "from": "payments.ledger",
+          "to": "psp-gateway",
+          "kind": "rpc",
+          "label": "ack 200",
+          "status": "verified",
+          "note": "Acked only after the branch above has committed. Anything else and the gateway replays, which is what makes the dedup table load-bearing.",
+          "line": "webhook_test.go:142"
+        }
+      ]
+    },
+    {
+      "id": "flow.order-accepted",
+      "slug": "order-accepted",
+      "name": "Order accepted",
+      "summary": "The narrow slice one integration test pins end to end: an order commits with its outbox row, the relay publishes it, the ledger picks it up and the authorization comes back. Every hop here is asserted, which is why this is the only flow with no gaps in it.",
+      "source": "services/oms/test/integration/order_accepted_test.go",
+      "owner": "shop",
+      "participants": [
+        {
+          "id": "shop.oms",
+          "kind": "service",
+          "context": "shop"
+        },
+        {
+          "id": "oms-db",
+          "kind": "store",
+          "context": "shop",
+          "label": "oms-db (postgres)"
+        },
+        {
+          "id": "bus",
+          "kind": "broker",
+          "context": null
+        },
+        {
+          "id": "payments.ledger",
+          "kind": "service",
+          "context": "payments"
+        }
+      ],
+      "steps": [
+        {
+          "type": "step",
+          "id": "a1",
+          "from": "shop.oms",
+          "to": "oms-db",
+          "kind": "call",
+          "label": "insertOrderAndOutboxRow",
+          "status": "verified",
+          "note": "The order row and the OrderPlaced outbox row commit in one transaction, so the event cannot be published before the order exists or lost after it does.",
+          "line": "internal/oms/adapter/postgres/order_repo.go:141"
+        },
+        {
+          "type": "step",
+          "id": "a2",
+          "from": "shop.oms",
+          "to": "bus",
+          "kind": "event",
+          "ref": "shop.oms.order.OrderPlaced",
+          "label": "OrderPlaced",
+          "status": "verified",
+          "note": "Published by the outbox relay, not by the request handler. The test waits on the relay rather than on PlaceOrder returning.",
+          "line": "order_accepted_test.go:58"
+        },
+        {
+          "type": "step",
+          "id": "a3",
+          "from": "bus",
+          "to": "payments.ledger",
+          "kind": "event",
+          "ref": "shop.oms.order.OrderPlaced",
+          "label": "OrderPlaced",
+          "status": "verified",
+          "note": "Consumer group `ledger-orders`, at-least-once. The test replays the same message a second time and asserts nothing changes.",
+          "line": "order_accepted_test.go:71"
+        },
+        {
+          "type": "step",
+          "id": "a4",
+          "from": "payments.ledger",
+          "to": "payments.ledger",
+          "kind": "call",
+          "label": "openReconciliationRecord",
+          "status": "verified",
+          "note": "The event only opens the record the gateway webhook later matches against. Authorizing is the synchronous call below, because checkout needs the answer before it can confirm.",
+          "line": "internal/ledger/app/intent.go:47"
+        },
+        {
+          "type": "step",
+          "id": "a5",
+          "from": "shop.oms",
+          "to": "payments.ledger",
+          "kind": "rpc",
+          "ref": "payments.v1.Payments/Authorize",
+          "label": "Authorize",
+          "status": "verified",
+          "note": "Carries the order's idempotency key. The gateway behind the ledger is the sandbox stub here; the real hop out of the estate is drawn in the checkout flow.",
+          "line": "order_accepted_test.go:88"
+        },
+        {
+          "type": "step",
+          "id": "a6",
+          "from": "payments.ledger",
+          "to": "bus",
+          "kind": "event",
+          "ref": "payments.ledger.payment.PaymentAuthorized",
+          "label": "PaymentAuthorized",
+          "status": "verified",
+          "line": "order_accepted_test.go:103"
+        },
+        {
+          "type": "step",
+          "id": "a7",
+          "from": "bus",
+          "to": "shop.oms",
+          "kind": "event",
+          "ref": "payments.ledger.payment.PaymentAuthorized",
+          "label": "PaymentAuthorized",
+          "status": "verified",
+          "line": "order_accepted_test.go:114"
+        }
+      ]
+    },
+    {
+      "id": "flow.order-cancelled",
+      "slug": "order-cancelled",
+      "name": "Order cancelled",
+      "summary": "A customer cancels before the parcel moves, and two compensations run side by side: the money is unwound at the gateway, and the stop is taken off the route. Whether the money is voided or refunded depends on how far payment got, and the delivery half is declared everywhere and observed nowhere.",
+      "source": "services/oms/test/e2e/cancel_test.go",
+      "owner": "shop",
+      "participants": [
+        {
+          "id": "customer",
+          "kind": "actor",
+          "context": null
+        },
+        {
+          "id": "shop.oms",
+          "kind": "service",
+          "context": "shop"
+        },
+        {
+          "id": "bus",
+          "kind": "broker",
+          "context": null
+        },
+        {
+          "id": "payments.ledger",
+          "kind": "service",
+          "context": "payments"
+        },
+        {
+          "id": "psp-gateway",
+          "kind": "external",
+          "context": null,
+          "label": "psp-gateway (external)"
+        },
+        {
+          "id": "delivery.core",
+          "kind": "service",
+          "context": "delivery"
+        }
+      ],
+      "steps": [
+        {
+          "type": "step",
+          "id": "x1",
+          "from": "customer",
+          "to": "shop.oms",
+          "kind": "rpc",
+          "label": "CancelOrder",
+          "status": "verified",
+          "line": "cancel_test.go:44"
+        },
+        {
+          "type": "step",
+          "id": "x2",
+          "from": "shop.oms",
+          "to": "delivery.core",
+          "kind": "rpc",
+          "ref": "delivery.v1.Delivery/GetShipment",
+          "label": "GetShipment",
+          "status": "declared",
+          "note": "Cancelling is only allowed while the shipment is `held` or `planned`. The state comes from delivery, not from the order, so a stale read here is what lets a dispatched parcel be cancelled.",
+          "line": "internal/oms/client/delivery.go:41"
+        },
+        {
+          "type": "alt",
+          "id": "alt-cancel",
+          "branches": [
+            {
+              "title": "shipment not yet dispatched",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "x3",
+                  "from": "shop.oms",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "shop.oms.order.OrderCancelled",
+                  "label": "OrderCancelled",
+                  "status": "verified",
+                  "line": "cancel_test.go:61"
+                },
+                {
+                  "type": "parallel",
+                  "id": "par-compensate",
+                  "title": "compensations, which do not wait for each other",
+                  "branches": [
+                    [
+                      {
+                        "type": "step",
+                        "id": "x4",
+                        "from": "bus",
+                        "to": "payments.ledger",
+                        "kind": "event",
+                        "ref": "shop.oms.order.OrderCancelled",
+                        "label": "OrderCancelled",
+                        "status": "verified",
+                        "line": "cancel_test.go:70"
+                      },
+                      {
+                        "type": "alt",
+                        "id": "alt-money",
+                        "branches": [
+                          {
+                            "title": "authorization not yet captured",
+                            "steps": [
+                              {
+                                "type": "step",
+                                "id": "x5",
+                                "from": "payments.ledger",
+                                "to": "psp-gateway",
+                                "kind": "rpc",
+                                "ref": "psp.v2.Charges/Void",
+                                "label": "Charges.Void",
+                                "status": "unresolved",
+                                "note": "Voiding costs nothing and leaves no trace on the customer's statement, which is why the capture is held back until dispatch in the first place.",
+                                "line": "internal/ledger/adapter/psp/client.go:171"
+                              },
+                              {
+                                "type": "step",
+                                "id": "x6",
+                                "from": "payments.ledger",
+                                "to": "payments.ledger",
+                                "kind": "call",
+                                "label": "releaseHold",
+                                "status": "verified",
+                                "line": "cancel_test.go:83"
+                              }
+                            ]
+                          },
+                          {
+                            "title": "payment already captured",
+                            "steps": [
+                              {
+                                "type": "step",
+                                "id": "x7",
+                                "from": "payments.ledger",
+                                "to": "psp-gateway",
+                                "kind": "rpc",
+                                "ref": "psp.v2.Charges/Refund",
+                                "label": "Charges.Refund",
+                                "status": "unresolved",
+                                "line": "internal/ledger/adapter/psp/client.go:138"
+                              },
+                              {
+                                "type": "step",
+                                "id": "x8",
+                                "from": "payments.ledger",
+                                "to": "bus",
+                                "kind": "event",
+                                "ref": "payments.ledger.refund.RefundIssued",
+                                "label": "RefundIssued",
+                                "status": "declared",
+                                "note": "The same event the support refund publishes. Nothing in the payload says which of the two happened, so a consumer cannot tell a cancelled order from a returned one.",
+                                "line": "internal/ledger/app/refund.go:88"
+                              }
+                            ]
+                          }
+                        ]
+                      }
+                    ],
+                    [
+                      {
+                        "type": "step",
+                        "id": "x9",
+                        "from": "bus",
+                        "to": "delivery.core",
+                        "kind": "event",
+                        "ref": "shop.oms.order.OrderCancelled",
+                        "label": "OrderCancelled",
+                        "status": "declared",
+                        "note": "The subscription is registered in the delivery repo, but no test covers it and no trace in the sampled window shows it firing.",
+                        "line": "internal/delivery/app/subscribe.go:62"
+                      },
+                      {
+                        "type": "step",
+                        "id": "x10",
+                        "from": "delivery.core",
+                        "to": "delivery.core",
+                        "kind": "call",
+                        "label": "removeStopAndReplan",
+                        "status": "declared",
+                        "line": "internal/delivery/app/route.go:112"
+                      },
+                      {
+                        "type": "step",
+                        "id": "x11",
+                        "from": "delivery.core",
+                        "to": "bus",
+                        "kind": "event",
+                        "ref": "delivery.core.route.RoutePlanned",
+                        "label": "RoutePlanned",
+                        "status": "declared",
+                        "note": "The route is republished without the stop. Consumers see a second RoutePlanned for the same route and are expected to take the later one.",
+                        "line": "internal/delivery/app/route.go:94"
+                      }
+                    ]
+                  ]
+                },
+                {
+                  "type": "step",
+                  "id": "x12",
+                  "from": "shop.oms",
+                  "to": "customer",
+                  "kind": "rpc",
+                  "label": "cancellation confirmation",
+                  "status": "declared",
+                  "line": "internal/oms/notify/cancellation.go:19"
+                }
+              ]
+            },
+            {
+              "title": "shipment already dispatched",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "x13",
+                  "from": "shop.oms",
+                  "to": "customer",
+                  "kind": "rpc",
+                  "label": "409 Conflict",
+                  "status": "verified",
+                  "note": "The edge refuses and points the customer at returns instead. What happens from there is the refund-requested flow, and none of it is observed.",
+                  "line": "cancel_test.go:118"
+                }
+              ],
+              "terminal": true
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "flow.quote-expired-on-checkout",
+      "slug": "quote-expired-on-checkout",
+      "name": "Quote expired on checkout",
+      "summary": "A basket that has been checked out is a basket whose quote is spent. Pricing hears the event the cart publishes and expires the quote it issued for that basket, so a second checkout of the same basket has to be priced again rather than reuse a number the price list may have moved on from.",
+      "source": "services/pricing/internal/policy/expire_quote.go",
+      "owner": "shop",
+      "participants": [
+        {
+          "id": "bus",
+          "kind": "broker",
+          "context": null
+        },
+        {
+          "id": "shop.pricing",
+          "kind": "service",
+          "context": "shop"
+        },
+        {
+          "id": "pricing-db",
+          "kind": "store",
+          "context": "shop",
+          "label": "pricing-db (postgres)"
+        }
+      ],
+      "steps": [
+        {
+          "type": "step",
+          "id": "s1",
+          "from": "bus",
+          "to": "shop.pricing",
+          "kind": "event",
+          "ref": "shop.cart.basket.BasketCheckedOut",
+          "label": "BasketCheckedOut",
+          "status": "declared",
+          "note": "One consumer group, the basket id as the routing key. A basket with no quote on file is ignored, not an error: not every basket was priced.",
+          "line": "internal/policy/expire_quote.go:24"
+        },
+        {
+          "type": "step",
+          "id": "s2",
+          "from": "shop.pricing",
+          "to": "pricing-db",
+          "kind": "call",
+          "label": "expireQuote",
+          "status": "declared",
+          "line": "internal/adapter/postgres/quotes.go:71"
+        },
+        {
+          "type": "step",
+          "id": "s3",
+          "from": "shop.pricing",
+          "to": "bus",
+          "kind": "event",
+          "ref": "shop.pricing.quote.QuoteExpired",
+          "label": "QuoteExpired",
+          "status": "declared",
+          "note": "Published for the audit trail; nothing in the estate acts on it yet.",
+          "line": "internal/policy/expire_quote.go:31"
+        }
+      ]
+    },
+    {
+      "id": "flow.refund-requested",
+      "slug": "refund-requested",
+      "name": "Refund requested",
+      "summary": "How a support-initiated refund is meant to travel: the window is read off the shipment, an undispatched parcel is recalled first, and the money is returned through the ledger. Written by hand from the design doc — not one step has been observed in a test or a trace, which is why every hop on this page is declared.",
+      "source": "docs/flows/refund-requested.md",
+      "owner": "shop",
+      "participants": [
+        {
+          "id": "agent",
+          "kind": "actor",
+          "context": null,
+          "label": "support agent"
+        },
+        {
+          "id": "shop.oms",
+          "kind": "service",
+          "context": "shop"
+        },
+        {
+          "id": "delivery.core",
+          "kind": "service",
+          "context": "delivery"
+        },
+        {
+          "id": "bus",
+          "kind": "broker",
+          "context": null
+        },
+        {
+          "id": "payments.ledger",
+          "kind": "service",
+          "context": "payments"
+        }
+      ],
+      "steps": [
+        {
+          "type": "step",
+          "id": "c1",
+          "from": "agent",
+          "to": "shop.oms",
+          "kind": "rpc",
+          "label": "RequestRefund",
+          "status": "declared",
+          "note": "The support console, not the storefront. The doc does not say what authorizes the agent or whether a partial amount is allowed.",
+          "line": "refund-requested.md:24"
+        },
+        {
+          "type": "step",
+          "id": "c2",
+          "from": "shop.oms",
+          "to": "delivery.core",
+          "kind": "rpc",
+          "ref": "delivery.v1.Delivery/GetShipment",
+          "label": "GetShipment",
+          "status": "declared",
+          "note": "The refund window runs from the delivery date on the shipment, not from the order date, so the shipment has to be read before anything is decided.",
+          "line": "internal/oms/client/delivery.go:41"
+        },
+        {
+          "type": "step",
+          "id": "c3",
+          "from": "shop.oms",
+          "to": "shop.oms",
+          "kind": "call",
+          "label": "checkRefundWindow",
+          "status": "declared",
+          "note": "30 days after delivery. Orders never delivered have no window at all — the doc leaves that case open.",
+          "line": "internal/oms/app/refund.go:52"
+        },
+        {
+          "type": "alt",
+          "id": "alt-parcel",
+          "branches": [
+            {
+              "title": "shipment already delivered",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "c4",
+                  "from": "shop.oms",
+                  "to": "shop.oms",
+                  "kind": "call",
+                  "label": "openReturnLabel",
+                  "status": "declared",
+                  "line": "internal/oms/app/refund.go:71"
+                }
+              ]
+            },
+            {
+              "title": "shipment still in transit",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "c5",
+                  "from": "shop.oms",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "shop.oms.order.OrderCancelled",
+                  "label": "OrderCancelled",
+                  "status": "declared",
+                  "line": "refund-requested.md:58"
+                },
+                {
+                  "type": "step",
+                  "id": "c6",
+                  "from": "bus",
+                  "to": "delivery.core",
+                  "kind": "event",
+                  "ref": "shop.oms.order.OrderCancelled",
+                  "label": "OrderCancelled",
+                  "status": "declared",
+                  "note": "Delivery is expected to recall the parcel here. The handler is described in the design doc, but no subscription for OrderCancelled was found in the delivery repository.",
+                  "line": "refund-requested.md:61"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "step",
+          "id": "c7",
+          "from": "shop.oms",
+          "to": "payments.ledger",
+          "kind": "rpc",
+          "ref": "payments.v1.Payments/Refund",
+          "label": "Refund",
+          "status": "declared",
+          "note": "Both branches rejoin here. The doc does not say what the amount is when the parcel was recalled but the shipping was already billed.",
+          "line": "internal/oms/client/payments.go:104"
+        },
+        {
+          "type": "step",
+          "id": "c8",
+          "from": "payments.ledger",
+          "to": "payments.ledger",
+          "kind": "call",
+          "label": "openRefund",
+          "status": "declared",
+          "line": "internal/ledger/app/refund.go:31"
+        },
+        {
+          "type": "loop",
+          "id": "loop-settle",
+          "title": "polled hourly until the gateway leaves `pending`, up to 7 days",
+          "steps": [
+            {
+              "type": "step",
+              "id": "c9",
+              "from": "payments.ledger",
+              "to": "payments.ledger",
+              "kind": "call",
+              "label": "pollGatewaySettlement",
+              "status": "declared",
+              "note": "The doc says the gateway confirms by webhook and that the poll is only the fallback. Neither path is covered by a test, and nothing says what happens on day 8.",
+              "line": "internal/ledger/app/refund.go:64"
+            }
+          ]
+        },
+        {
+          "type": "alt",
+          "id": "alt-settlement",
+          "branches": [
+            {
+              "title": "the gateway settles the refund",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "c10",
+                  "from": "payments.ledger",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "payments.ledger.refund.RefundIssued",
+                  "label": "RefundIssued",
+                  "status": "declared",
+                  "line": "refund-requested.md:83"
+                },
+                {
+                  "type": "parallel",
+                  "id": "par-refunded",
+                  "title": "RefundIssued fan-out",
+                  "branches": [
+                    [
+                      {
+                        "type": "step",
+                        "id": "c11",
+                        "from": "bus",
+                        "to": "shop.oms",
+                        "kind": "event",
+                        "ref": "payments.ledger.refund.RefundIssued",
+                        "label": "RefundIssued",
+                        "status": "declared",
+                        "note": "Moves the order to `refunded`.",
+                        "line": "refund-requested.md:88"
+                      }
+                    ],
+                    [
+                      {
+                        "type": "step",
+                        "id": "c12",
+                        "from": "bus",
+                        "to": "delivery.core",
+                        "kind": "event",
+                        "ref": "payments.ledger.refund.RefundIssued",
+                        "label": "RefundIssued",
+                        "status": "declared",
+                        "note": "Closes the return leg. Same gap as the cancel handler above: declared in the doc, absent from the repository.",
+                        "line": "refund-requested.md:91"
+                      }
+                    ]
+                  ]
+                },
+                {
+                  "type": "step",
+                  "id": "c13",
+                  "from": "shop.oms",
+                  "to": "agent",
+                  "kind": "rpc",
+                  "label": "refund receipt",
+                  "status": "declared",
+                  "line": "refund-requested.md:96"
+                }
+              ]
+            },
+            {
+              "title": "the gateway refuses the refund",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "c14",
+                  "from": "payments.ledger",
+                  "to": "payments.ledger",
+                  "kind": "call",
+                  "label": "recordRejection",
+                  "status": "declared",
+                  "note": "The code and category are stored on the refund and nothing publishes them. Support finds out by looking, which the doc admits and does not fix.",
+                  "line": "refund-requested.md:101"
+                }
+              ],
+              "terminal": true
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "flow.shipment-tracking",
+      "slug": "shipment-tracking",
+      "name": "Shipment tracking",
+      "summary": "Reconstructed from production traces over a 24 hour window: the tracking page, the carrier's scan webhook, and what each scan code sets off. Two things only the traces know about — a consumer no repository accounts for, and an exception path whose reader emits no spans at all.",
+      "source": "data/flows/shipment-tracking.flow.md",
+      "owner": "delivery",
+      "participants": [
+        {
+          "id": "customer",
+          "kind": "actor",
+          "context": null
+        },
+        {
+          "id": "carrier-api",
+          "kind": "external",
+          "context": null,
+          "label": "carrier-api (external)"
+        },
+        {
+          "id": "delivery.core",
+          "kind": "service",
+          "context": "delivery"
+        },
+        {
+          "id": "shop.oms",
+          "kind": "service",
+          "context": "shop"
+        },
+        {
+          "id": "bus",
+          "kind": "broker",
+          "context": null
+        },
+        {
+          "id": "analytics-sink",
+          "kind": "unknown",
+          "context": null,
+          "label": "analytics-sink (unknown)"
+        }
+      ],
+      "steps": [
+        {
+          "type": "step",
+          "id": "d1",
+          "from": "customer",
+          "to": "delivery.core",
+          "kind": "rpc",
+          "label": "TrackShipment",
+          "status": "verified",
+          "note": "Storefront tracking page. 41k calls in the window, p95 180 ms.",
+          "line": "trace 9f2c1a../span 04"
+        },
+        {
+          "type": "step",
+          "id": "d2",
+          "from": "delivery.core",
+          "to": "shop.oms",
+          "kind": "rpc",
+          "ref": "shop.v1.Orders/GetOrder",
+          "label": "GetOrder",
+          "status": "verified",
+          "note": "Resolves the order reference shown beside the parcel. Present in 96% of the traces; the rest are served from the tracking cache.",
+          "line": "trace 9f2c1a../span 06"
+        },
+        {
+          "type": "loop",
+          "id": "loop-scan",
+          "title": "one iteration per carrier scan; 4 scans per shipment at p50 over the window",
+          "steps": [
+            {
+              "type": "step",
+              "id": "d3",
+              "from": "carrier-api",
+              "to": "delivery.core",
+              "kind": "rpc",
+              "label": "POST /webhooks/carrier/scan",
+              "status": "verified",
+              "note": "Signed with the carrier's shared secret. 1.3% of scans in the window are retries after a 5xx, and the traces show the retry landing on the same shipment without a second state change.",
+              "line": "trace 7be40d../span 01"
+            },
+            {
+              "type": "step",
+              "id": "d4",
+              "from": "delivery.core",
+              "to": "delivery.core",
+              "kind": "call",
+              "label": "RecordScan",
+              "status": "verified",
+              "line": "trace 7be40d../span 03"
+            }
+          ]
+        },
+        {
+          "type": "alt",
+          "id": "alt-scan",
+          "branches": [
+            {
+              "title": "scan code DELIVERED",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "d5",
+                  "from": "delivery.core",
+                  "to": "bus",
+                  "kind": "event",
+                  "ref": "delivery.core.shipment.ShipmentDelivered",
+                  "label": "ShipmentDelivered",
+                  "status": "verified",
+                  "line": "trace 7be40d../span 27"
+                },
+                {
+                  "type": "parallel",
+                  "id": "par-delivered",
+                  "title": "ShipmentDelivered fan-out",
+                  "branches": [
+                    [
+                      {
+                        "type": "step",
+                        "id": "d6",
+                        "from": "bus",
+                        "to": "shop.oms",
+                        "kind": "event",
+                        "ref": "delivery.core.shipment.ShipmentDelivered",
+                        "label": "ShipmentDelivered",
+                        "status": "verified",
+                        "note": "Closes the order and starts the 30-day refund window the refund flow reads.",
+                        "line": "trace 7be40d../span 29"
+                      }
+                    ],
+                    [
+                      {
+                        "type": "step",
+                        "id": "d7",
+                        "from": "bus",
+                        "to": "analytics-sink",
+                        "kind": "event",
+                        "ref": "delivery.core.shipment.ShipmentDelivered",
+                        "label": "ShipmentDelivered",
+                        "status": "unresolved",
+                        "note": "Seen in traces only, under client id `analytics-sink-2`. No subscription registration exists in any indexed repository, so the owning team is unknown and nobody can be told before this topic changes shape.",
+                        "line": "trace 7be40d../span 31"
+                      }
+                    ]
+                  ]
+                }
+              ]
+            },
+            {
+              "title": "scan code EXCEPTION",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "d8",
+                  "from": "delivery.core",
+                  "to": "delivery.core",
+                  "kind": "call",
+                  "label": "openDeliveryException",
+                  "status": "verified",
+                  "note": "The trace ends here. Whatever reads the exception queue emits no spans, so the catalog cannot say what happens to the parcel next.",
+                  "line": "trace 4c81f3../span 09"
+                }
+              ],
+              "terminal": true
+            },
+            {
+              "title": "scan code IN_TRANSIT",
+              "steps": [
+                {
+                  "type": "step",
+                  "id": "d9",
+                  "from": "delivery.core",
+                  "to": "delivery.core",
+                  "kind": "call",
+                  "label": "updateEta",
+                  "status": "verified",
+                  "note": "No event is published for an in-transit scan; the tracking page reads the shipment directly. 83% of the scans in the window end here.",
+                  "line": "trace 7be40d../span 12"
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "adrs": []
+}