@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/lesson-lifecycle/schema/payloads/lesson.scheduled-v1.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lesson-lifecycle/schema/payloads/lesson.scheduled-v1.json",
+  "title": "lesson.scheduled payload v1",
+  "description": "Payload for the lesson.scheduled event_type. Emitted by Delivery when a lesson is first scheduled. The event is scheduling-side evidence only; Revenue-owned credit lifecycle facts remain on credit.* events.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lesson_id",
+    "organization_id",
+    "participant_id",
+    "reservation_id",
+    "reservation_lock_id",
+    "coach_id",
+    "lesson_site_id",
+    "service_area_id",
+    "lesson_zip",
+    "lesson_type_id",
+    "window"
+  ],
+  "properties": {
+    "lesson_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "organization_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "participant_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "reservation_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "reservation_lock_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "coach_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "lesson_site_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "service_area_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "lesson_zip": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "lesson_type_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "window": {
+      "$ref": "#/$defs/window"
+    }
+  },
+  "$defs": {
+    "window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "start",
+        "end"
+      ],
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "end": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

package/contracts/lesson-lifecycle/validation/README.md

@@ -0,0 +1,5 @@
+# Lesson Lifecycle contract: validation notes
+
+No validation notes yet. Validation notes for the lesson-lifecycle payload
+schemas (sample envelopes, conformance checks, producer/consumer fixtures)
+land here as they are written.

package/contracts/mart-consumer-api/README.md

@@ -0,0 +1,108 @@
+# Mart Consumer API Contract (Them OS Requirements)
+
+**Status:** v1.0.0 — requirements received; sections not yet shipped
+**Date:** 2026-05-17
+**Owner:** platform (mart infrastructure and identity spine); per-section owners listed below
+**Consumers:** Them OS (forecasting engine; sole consumer of this API surface)
+**Related ADRs:** ADR-0016 (medallion warehouse layout), ADR-0015 (Finance and Portfolio as cross-domain domains), ADR-0014 (org as multi-market collective), ADR-0013 (Platform-owned canonical geography), ADR-0019 (OrgMarket junction and tenancy grain)
+**Sub-specs (authoritative):** per-section field manifests land as siblings under this contract as sections ship; see `finance-mart/` and `portfolio-mart/` for the two cross-domain sections already under development
+
+## 1. Purpose and scope
+
+This contract records the requirements that Them OS (the forecasting engine) has specified for the data mart. The mart sits between the per-domain operational warehouses and Them OS. It exposes seven read-only API sections. The mart is NOT a forecasting engine; it is a data-shape contract. Them OS does all forecasting in-process and holds no upstream warehouse credentials.
+
+The full Them OS requirements document is the authoritative specification. This README is the coordination-repo entry point: it records the section structure, per-section ownership, the cross-cutting requirements that Platform owns, and the known alignment gaps between the requirements and Platform's current schema.
+
+## 2. Architecture (per Them OS spec §1)
+
+Three layers:
+
+1. **Per-domain operational warehouses** — Growth, Sales, Delivery, Coaching, Revenue source DBs. Upstream of the mart. Not accessible to Them OS.
+2. **The data mart** — seven read-only API sections. The firewall lives here. Platform owns the mart infrastructure and the identity/geography spine that all sections share.
+3. **Them OS** — reads from the mart's seven sections. Forecasts in-process.
+
+Section access is asymmetric:
+- **Firewalled sections (1–5):** Growth, Sales, Delivery, Coaching, Revenue. Each reads ONLY its own domain's warehouse. The mart's API output for these sections exposes no shared customer/lesson/coach key across sections.
+- **Cross-domain sections (6–7):** Finance, Portfolio. Read from ANY warehouse. Their API output may carry cross-domain context per the carve-outs in the spec.
+
+## 3. Section ownership
+
+| Section | Domain owner | Warehouse source | Status |
+|---|---|---|---|
+| 1. Growth | growth | growth warehouse | Not started |
+| 2. Sales | sales | sales warehouse | Not started |
+| 3. Delivery | delivery | delivery warehouse | Not started |
+| 4. Coaching | coaching | coaching warehouse | Not started |
+| 5. Revenue | revenue | revenue warehouse | Not started |
+| 6. Finance | finance | any | In progress (`finance-mart/`) |
+| 7. Portfolio | portfolio | any | In progress (`portfolio-mart/`) |
+
+Platform owns the mart shell, the identity/geography spine, the `org_market_id` namespace, the firewall enforcement mechanism, and the `/health`, `/schema`, `/changelog`, and `/corrections` cross-cutting endpoints per the spec.
+
+## 4. Core terminology (binding, per Them OS spec §1.5)
+
+| Term | Definition | Platform schema object |
+|---|---|---|
+| Portfolio | The full set of business units the operator runs | — (logical aggregate) |
+| Org | A discipline/vertical (swim, tennis). NOT geographic. | `Organization` |
+| Org-market | A vertical × market pair (dallas-swim). The operational grain. | `OrgMarket` |
+| `org_market_id` | Stable identifier for an org-market pair | `OrgMarket.id` (see §5 gap) |
+
+The rollup hierarchy is `portfolio → org → org-market`. Every firewalled section row carries both `org_id` and `org_market_id`. Cross-section joins at the `org_id` / `org_market_id` level are explicitly permitted; customer-grain cross-section joins are prohibited.
+
+## 5. Platform obligations and known gaps
+
+### 5.1 `org_market_id` slug (gap — action required)
+
+The Them OS spec uses examples like `"dallas-swim"` as `org_market_id` values, implying a human-readable compound slug. Platform's `OrgMarket.id` is a raw UUID. Platform must decide and publish the canonical `org_market_id` surface before any section ships:
+
+**Option A:** Add a `slug` column to `OrgMarket` (e.g. `dallas-swim`) as the published identifier. Stable, human-readable, URL-safe.
+**Option B:** Derive the slug at mart read time from `{org.slug}-{market.slug}` without storing it. Simpler schema, but mart must recompute on every read.
+
+Recommendation: Option A. The slug is the stable coordination key for Them OS; storing it on `OrgMarket` makes it explicit and prevents drift if org or market slugs change independently.
+
+### 5.2 `org_market_list` (Portfolio §9.2)
+
+The Portfolio section's `org_market_list` metric is a snapshot of all org-markets with status, parent `org_id`, and market tag. Platform's `OrgMarket` table is the direct source. Platform must expose this via the mart shell or confirm Portfolio reads it directly from the warehouse.
+
+### 5.3 Identity spine as the firewall backbone
+
+The §2.5 identifier discipline (each firewalled section exposes `org_id` and `org_market_id` but no cross-section customer keys) depends on Platform's `person_spine` being the identity resolution surface. Silver faces join to `person_spine` on `person_id`; the mart's firewall then strips the `person_id` from the API surface and exposes only the `org_market_id` grain. Platform must document this mechanism for each section owner.
+
+### 5.4 Aggregation rule declarations (`_org_rollup_rule`)
+
+The spec requires every metric exposed at both `per-org-market` and `per-org` grains to carry a `_org_rollup_rule` field (sum, weighted_mean_by_revenue, etc.). Platform's mart shell must support this field at the schema level; section owners declare the value per metric.
+
+### 5.5 Cross-cutting endpoints
+
+Platform owns the mart-level `/health`, `/schema`, `/changelog`, and `/corrections` endpoints per spec §§2.1–2.8. These are not domain-section outputs; they are mart infrastructure.
+
+## 6. Contract versioning and deprecation (per spec §2.1)
+
+Each section exposes a `contract_version` string following semver. MAJOR bump = field removed/renamed/semantics changed. MINOR = field added. PATCH = doc/computation fix.
+
+Them OS pins to MAJOR.MINOR per section. Platform's mart must run prior MAJOR versions in parallel for ≥ 60 days after a new MAJOR ships.
+
+## 7. Freshness SLOs summary
+
+| Section | Fastest metric SLO | Slowest metric SLO |
+|---|---|---|
+| Growth | lead volume ≤ 2h | attribution windows ≤ 24h |
+| Sales | first_lock_count ≤ 1h | pipeline snapshots ≤ 15min |
+| Delivery | lesson_completed_count ≤ 1h | cohort curves ≤ 24h |
+| Coaching | capacity/scheduled hours ≤ 2h | roster ≤ 24h |
+| Revenue | revenue_paid ≤ 1h | revenue_earned ≤ 24h |
+| Finance | margin ≤ 4h | LTV cohort ≤ 24h |
+| Portfolio | attention_queue ≤ 30min | initiative_progress ≤ 4h |
+
+## 8. Firewall enforcement summary
+
+The mart enforces the firewall at the API layer, not at the warehouse layer. Them OS verifies firewall enforcement via an automated leakage test (attempt cross-section identity joins; test must fail) as part of each section's acceptance criteria.
+
+Platform is responsible for the firewall mechanism in the mart shell. Domain section owners are responsible for not including prohibited identifiers in their section's output schema.
+
+## 9. Change log
+
+| Version | Date | Notes |
+|---|---|---|
+| v1.0.0 | 2026-05-17 | Initial filing of Them OS requirements. Sections not yet shipped. Platform gaps in §5 are open action items. |

package/contracts/order-flow/README.md

@@ -0,0 +1,106 @@
+# Order Flow
+
+**Status:** v1.0.0
+**Date:** 2026-05-14
+**Owner:** revenue (orders module)
+**Consumers:** revenue (internal reconciliation), sales (lead-reactivation close and cadence-stop signals), growth (funnel-close attribution), delivery (FYI-grade order-existence and status visibility), platform-warehouse (analytics ingestion)
+**Related ADRs:** ADR-0001 (tenant_id), ADR-0002 (canonical entity ID template), ADR-0003 (Person canonical), ADR-0005 (event envelope), ADR-0009 (dispatcher transport, producer transactional guarantee)
+**Related contracts:** Event Envelope Contract (`../event-envelope/README.md`), Identity Contract (`../identity/README.md`), Payment Flow Contract (`../payment-flow/README.md`), Refund Flow Contract (`../refund-flow/README.md`), Credit Reservation Lock Contract (`../credit-reservation-lock/README.md`)
+**Sub-specs (authoritative):** `schema/payloads/order.created-v1.json`, `schema/payloads/order.updated-v1.json`
+**Validations:** none yet
+
+## 1. Purpose and scope
+
+This contract specifies the producer responsibilities and consumer-visible payload shape for Revenue's two order-flow events: `order.created` and `order.updated`. Both events are produced by Revenue at writeback transaction commit time for canonical Order state changes.
+
+In scope: the event names, payload shapes at v1, producer transactional guarantee discipline, canonical-field update rule, consumer responsibilities, and versioning policy.
+
+Out of scope: payment settlement details (covered by `payment-flow`), refund settlement details (covered by `refund-flow`), credit reservation lock semantics (covered by `credit-reservation-lock`), order item line-grain events, and internal operator-only metadata edits.
+
+## 2. Normative language
+
+The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted per RFC 2119.
+
+## 3. Terminology
+
+**Order.** A Revenue-owned commercial record, identified by `ord_<UUID v7 canonical>` per ADR-0002. It is keyed to `person_id` and organization scope through Revenue's canonical store and event envelope.
+
+**Order writeback.** The Revenue-internal Prisma transaction that records an Order insert or load-bearing Order field update and publishes the corresponding event through the dispatcher inside the same transaction.
+
+**Load-bearing canonical fields.** `status`, `amount_paid_cents`, `amount_total_cents`, and `cancelled_at`. Changes to these fields emit `order.updated`. Free-text notes, operator-only flags, and other internal metadata do not emit `order.updated`.
+
+## 4. Event types
+
+### 4.1 order.created
+
+Emitted by Revenue at the writeback transaction commit when an Order row first lands in the canonical Postgres store. The publish lives inside the same `prisma.$transaction` as the Order insert per ADR-0009. Either the Order commits and the event fires, or the transaction rolls back and no event fires.
+
+Payload v1: `order_id`, `person_id`, `organization_id`, `status`, `currency`, `amount_total_cents`, `created_via`, `created_at`. See `schema/payloads/order.created-v1.json` for the authoritative shape.
+
+Known `created_via` values at v1 are `portal`, `cli`, `webhook_provider_invoice`, `webhook_growth_lead_close`, and `backfill`. Consumers SHALL treat unknown values as safe-to-ignore per the event-envelope additive discipline.
+
+### 4.2 order.updated
+
+Emitted by Revenue at the writeback transaction commit when an Order's load-bearing canonical fields change. Typical call sites include paid-state writebacks, cancellation paths, refund-driven status transitions, and amount-total adjustments.
+
+Payload v1: `order_id`, `person_id`, `status_from`, `status_to`, `amount_paid_cents_from`, `amount_paid_cents_to`, `amount_total_cents`, `updated_via`, `updated_at`. See `schema/payloads/order.updated-v1.json` for the authoritative shape.
+
+Known Order status values at v1 are `DRAFT`, `OPEN`, `PAID`, `PARTIALLY_PAID`, `CANCELLED`, and `REFUNDED`. Known `updated_via` values mirror `created_via` where applicable. Consumers SHALL treat unknown `status`, `created_via`, and `updated_via` values as safe-to-ignore per event-envelope §9.5.
+
+### 4.3 Refund-driven status transitions
+
+When a Refund completes against an Order, the Order status may transition to `REFUNDED` or another Revenue-owned status. That status transition emits `order.updated`; the refund itself emits `refund.completed` per the sibling refund-flow contract. Consumers that subscribe to both event families correlate by `order_id`; the two events are not collapsible.
+
+## 5. Producer responsibilities
+
+Revenue SHALL emit `order.created` exactly once for each Order insert that commits in the canonical store.
+
+Revenue SHALL emit `order.updated` exactly once for each committed update to a load-bearing canonical Order field.
+
+Revenue SHALL emit both event types inside the same Prisma transaction as the Order writeback per ADR-0009. The publish call is conventionally the last statement in the transaction, so earlier rollback prevents the event from firing.
+
+Revenue SHALL NOT put `tenant_id` in the payload. Tenant scope rides on the Event Envelope per ADR-0001 and the payment-flow precedent.
+
+Revenue SHALL NOT emit `order.updated` for free-text or operator-internal metadata-only edits.
+
+## 6. Consumer responsibilities
+
+Consumers SHALL deduplicate by `(consumer, event_id)` per the dispatcher SDK and event-envelope contract.
+
+Consumers SHALL treat unknown `status`, `created_via`, and `updated_via` values as safe-to-ignore. A new value is an additive change unless the contract removes or narrows an existing value.
+
+Sales consumes `order.created` and `order.updated` for lead-reactivation close, early cadence-stop, and status-transition policy signals.
+
+Growth consumes `order.created` for funnel-close attribution at the order grain. Growth does not rely on `order.updated` at v1.
+
+Delivery consumes both events as FYI-grade visibility for order existence and status transitions. Delivery's lock state machine continues to use credit and refund events for load-bearing state transitions.
+
+Platform warehouse ingests both events for order-grain commercial analytics.
+
+## 7. Idempotency and retry
+
+Producer-side idempotency is enforced by the Order writeback transaction and the state-transition validation at each call site. Consumer-side retry follows the dispatcher SDK default retry, dedup, and dead-letter behavior.
+
+## 8. Versioning
+
+This contract follows the additive-discipline pattern from the Event Envelope Contract. New optional fields and new enum-like values may land as v1.x changes. Removing fields, renaming fields, narrowing accepted values, or changing types requires a major version bump and a deprecation window.
+
+Per-event `schema_version` is independent between `order.created` and `order.updated`.
+
+## 9. Producer responsibilities trace
+
+Expected Revenue-side call sites:
+
+- `order.created` from the orders module creation path as the Postgres create service lands.
+- `order.updated` from paid-state writebacks in `revenue/src/modules/orders/service.charge-pg.ts`.
+- `order.updated` from future cancellation, refund-completion, partial-payment, and amount-adjustment Postgres paths as they land.
+
+This trace updates as part of the same contract change if new event-firing sites are added.
+
+## 10. Trigger to revisit
+
+Revisit this contract if OrderItem line-grain events become cross-domain, if a consumer needs `order.cancelled` split out from `order.updated`, if status semantics change materially, or if a new payment/refund provider creates Order state transitions that the v1 payload cannot describe additively.
+
+## 11. Change log
+
+- **v1.0.0** (2026-05-14): Initial release. Adds `order.created` and `order.updated` with v1 payload schemas and registry entries. Publishes the order-flow sibling contract next to payment-flow and refund-flow. Incorporates Platform's signoff modifications: status is v1.0.0 at publication, `tenant_id` remains envelope-only, Delivery is included after its day-one FYI ack, and enum-like values are documented while remaining open at the consumer boundary.

package/contracts/order-flow/schema/payloads/order.created-v1.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/order-flow/schema/payloads/order.created-v1.json",
+  "title": "order.created payload v1",
+  "description": "Payload for the order.created event_type per contracts/order-flow/README.md §4.1. Emitted by Revenue at the writeback transaction commit when an Order row first lands in the canonical Postgres store. Producer SHALL emit inside the same Prisma transaction as the Order insert per ADR-0009. Tenant scope rides on the Event Envelope, not this payload.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "order_id",
+    "person_id",
+    "organization_id",
+    "status",
+    "currency",
+    "amount_total_cents",
+    "created_via",
+    "created_at"
+  ],
+  "properties": {
+    "order_id": {
+      "type": "string",
+      "description": "The Revenue-owned Order. ord_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^ord_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "person_id": {
+      "type": "string",
+      "description": "The canonical Person the Order belongs to. per_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "organization_id": {
+      "type": "string",
+      "description": "The organization the Order is scoped to. org_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^org_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "status": {
+      "type": "string",
+      "description": "Initial Order status. Known values at v1: DRAFT, OPEN, PAID, PARTIALLY_PAID, CANCELLED, REFUNDED. Consumers SHALL treat unknown values as safe-to-ignore per event-envelope §9.5."
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO-4217 currency code. USD at v1 in production.",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "amount_total_cents": {
+      "type": "integer",
+      "description": "Order total in the smallest currency unit at creation time.",
+      "minimum": 0
+    },
+    "created_via": {
+      "type": "string",
+      "description": "Creation source. Known values at v1: portal, cli, webhook_provider_invoice, webhook_growth_lead_close, backfill. Consumers SHALL treat unknown values as safe-to-ignore per event-envelope §9.5."
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC timestamp at the writeback transaction commit. Producer's clock."
+    }
+  }
+}

package/contracts/order-flow/schema/payloads/order.updated-v1.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/order-flow/schema/payloads/order.updated-v1.json",
+  "title": "order.updated payload v1",
+  "description": "Payload for the order.updated event_type per contracts/order-flow/README.md §4.2. Emitted by Revenue at the writeback transaction commit when an Order's load-bearing canonical fields change. Producer SHALL emit inside the same Prisma transaction as the Order update per ADR-0009. Tenant scope rides on the Event Envelope, not this payload.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "order_id",
+    "person_id",
+    "status_from",
+    "status_to",
+    "amount_paid_cents_from",
+    "amount_paid_cents_to",
+    "amount_total_cents",
+    "updated_via",
+    "updated_at"
+  ],
+  "properties": {
+    "order_id": {
+      "type": "string",
+      "description": "The Revenue-owned Order. ord_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^ord_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "person_id": {
+      "type": "string",
+      "description": "The canonical Person the Order belongs to. per_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "status_from": {
+      "type": "string",
+      "description": "Prior Order status. Known values at v1: DRAFT, OPEN, PAID, PARTIALLY_PAID, CANCELLED, REFUNDED. Consumers SHALL treat unknown values as safe-to-ignore per event-envelope §9.5."
+    },
+    "status_to": {
+      "type": "string",
+      "description": "New Order status. Known values at v1: DRAFT, OPEN, PAID, PARTIALLY_PAID, CANCELLED, REFUNDED. Consumers SHALL treat unknown values as safe-to-ignore per event-envelope §9.5."
+    },
+    "amount_paid_cents_from": {
+      "type": ["integer", "null"],
+      "description": "Previous amount paid in the smallest currency unit. Null when the source row did not carry a prior value.",
+      "minimum": 0
+    },
+    "amount_paid_cents_to": {
+      "type": "integer",
+      "description": "New amount paid in the smallest currency unit.",
+      "minimum": 0
+    },
+    "amount_total_cents": {
+      "type": "integer",
+      "description": "Current Order total in the smallest currency unit after the update.",
+      "minimum": 0
+    },
+    "updated_via": {
+      "type": "string",
+      "description": "Update source. Known values at v1 mirror created_via where applicable: portal, cli, webhook_provider_invoice, webhook_growth_lead_close, backfill. Consumers SHALL treat unknown values as safe-to-ignore per event-envelope §9.5."
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC timestamp at the writeback transaction commit. Producer's clock."
+    }
+  }
+}

package/contracts/payment-flow/README.md

@@ -0,0 +1,157 @@
+# Payment Flow
+
+**Status:** v1.0.0
+**Date:** 2026-05-02
+**Owner:** revenue (payment-adapters, orders)
+**Consumers:** sales (Lead reactivation close on payment success per the lead-pipeline coupling), growth (funnel-close attribution), delivery (awareness of credit availability for the credit-reservation-lock state machine), platform-warehouse (analytics ingestion). Coaching does not subscribe at v1; the coach-availability projection is independent of payment timing per `coach-availability` v1.0.1 §4.3.
+**Related ADRs:** ADR-0001 (tenant_id), ADR-0002 (canonical entity ID template; `ord_` and `per_` prefixes), ADR-0003 (Person canonical, Revenue does not own Person), ADR-0005 (event envelope), ADR-0009 (dispatcher transport, producer transactional guarantee), ADR-0010 (provider externals at Platform; Square is the v1 provider, Quo when SMS lands)
+**Related contracts:** Event Envelope Contract (`../event-envelope/README.md`), Identity Contract (`../identity/README.md`), Credit Reservation Lock Contract (`../credit-reservation-lock/README.md`), Refund Flow Contract (`../refund-flow/README.md`)
+**Sub-specs (authoritative):** `schema/payloads/payment.received-v1.json`, `schema/payloads/payment.failed-v1.json`
+**Validations:** none yet
+
+## 1. Purpose and scope
+
+This contract specifies the producer responsibilities and consumer-visible payload shape for Revenue's two payment-flow events: `payment.received` and `payment.failed`. Both events are produced by Revenue at the writeback transaction commit for a payment outcome from Sguild's payment provider (Square at v1, with provider-agnostic shape so future Quo or alternative-provider integrations land additive). Both fire under the producer-transactional-guarantee shape from ADR-0009 (dispatcher.publish inside the same Prisma transaction as the order-status update and the external-actions row that records the provider outcome).
+
+In scope: the two event names, the payload shapes at v1, the producer's transactional-guarantee discipline, the consumer-visible enum partitions on `payment_method`, `payment_path`, and `failure_code`, idempotency and dedup expectations, and the versioning policy under the additive-discipline rule.
+
+Out of scope: the Square adapter's HTTP wire-format and webhook handling (lives in `revenue/src/lib/providers/square/` and the upstream external-actions module); the Refund flow (covered by the sibling `refund-flow` contract); the credit-reservation-lock state machine's funding sub-state transitions (covered by `credit-reservation-lock` §9.3 with `credit.funded` and the reservation.* family pending the cross-domain decision in `2026-05-02-revenue-emit-wiring-registry-additions`); revenue recognition (Revenue-internal, see `domains/revenue.md`); refund initiation against payments (covered by `refund-flow`).
+
+## 2. Normative language
+
+The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted per RFC 2119.
+
+## 3. Terminology
+
+**Payment writeback.** The Revenue-internal transaction that records a payment outcome: the order-status update (e.g. OPEN to PAID), the amount-paid update on the order, the external-actions row that captures the provider outcome and the reference id, and the dispatcher.publish for the corresponding event. Distinct from the **provider call**, which is the HTTP request to Square (or future provider) that initiates or settles the payment.
+
+**Provider call.** The outbound HTTP interaction with the payment provider. Either a Revenue-initiated charge (`runChargeOrder` in `revenue/src/modules/orders/service.ts`), an inbound webhook event the adapter receives (Square invoice payment notification routed through external-actions), or a sync-status check. The provider call's outcome is one fact; the writeback's outcome is a separate fact, per the writeback-separation rule in `domains/revenue.md`.
+
+**Active charge.** Revenue-initiated charge against the customer's payment-method-on-file. Synchronous from Revenue's perspective.
+
+**Invoice paid.** Customer-initiated payment against an invoice Revenue sent. Asynchronous from Revenue's perspective; Revenue learns of the outcome through a webhook event the provider posts back.
+
+**Provider reference.** The provider-side identifier for the payment (Square payment id at v1). Required per the funding-state external-reference rule in `domains/revenue.md` so the audit trail and reconciliation surface have a stable handle from Revenue's records back to the provider's records.
+
+## 4. Event types
+
+### 4.1 payment.received
+
+Emitted by Revenue at the writeback transaction commit for a successful payment. The provider call has succeeded (Square reports `COMPLETED` for an invoice payment, or `CAPTURED` for an active charge), the order has been flipped to PAID (or PARTIALLY_PAID for partial payments per the upstream order-amount logic), the amount-paid value has been updated on the order, and the external-actions row has recorded the provider outcome with the provider reference. The publish lives inside the same `prisma.$transaction` as the order update per ADR-0009; either the writeback commits and the event fires, or the writeback rolls back and no event fires (in which case the reconciliation surface running against the Square audit log catches the divergence per the writeback-separation rule).
+
+Payload v1: `order_id`, `person_id`, `payment_method`, `payment_path`, `amount_cents`, `currency`, `provider_ref`, `received_at`. See `schema/payloads/payment.received-v1.json` for the authoritative shape and field constraints.
+
+The `payment_path` field disambiguates the two writeback paths: `invoice_paid` for the asynchronous webhook-driven path through `runApplyInvoicePayment`, and `active_charge` for the synchronous path through `runChargeOrder`. Consumers that need path-specific behavior route on this field rather than on separate event_types.
+
+The `payment_method` field is partitioned per §4.3.
+
+### 4.2 payment.failed
+
+Emitted by Revenue at the writeback transaction commit when the provider has reported a payment failure and Revenue has recorded the failure as an external-actions row. The order does NOT flip to PAID on this event; the order status is preserved at its prior value (typically OPEN). The publish lives inside the same `prisma.$transaction` as the external-actions row insert per ADR-0009.
+
+Payload v1: `order_id`, `person_id`, `payment_method`, `payment_path`, `amount_cents`, `currency`, `provider_ref`, `failed_at`, `failure_code`, `failure_reason`. See `schema/payloads/payment.failed-v1.json` for the authoritative shape.
+
+The `failure_code` field is partitioned per §4.4 and is the consumer-routable signal; `failure_reason` is the free-form provider-side message and SHALL NOT be parsed by consumers (the message format is provider-specific and may change without contract bump).
+
+A provider-side failure on retry of an idempotent attempt that previously succeeded is a reconciliation case, not a `payment.failed` case; the original `payment.received` event from the first successful attempt remains the authoritative signal. Revenue's adapter SHALL NOT emit `payment.failed` for retry-of-success failure modes.
+
+### 4.3 payment_method partition
+
+The `payment_method` enum at v1 covers the methods Revenue's Square adapter supports today plus the methods the credit-balance flow uses internally. Consumers SHALL treat unknown values as safe-to-ignore per the additive-discipline in §8:
+
+- `card`. Credit or debit card payment via Square. The dominant path in practice.
+- `ach`. ACH bank transfer via Square. Lower volume; longer settlement window.
+- `cash`. Cash payment recorded in person at a Sguild facility. The provider call is a no-op (no Square-side capture); the external-actions row records the operator who handled the payment.
+- `check`. Check payment recorded by an operator. Same provider-call shape as `cash` (no Square-side capture); the external-actions row records the check number and the operator.
+- `credit_balance`. Internal payment via the customer's existing credit-account balance (no provider call). Used when an order's total is satisfied by previously-purchased credits without a provider transaction. The external-actions row records the credit-account id and the credit-ledger entries that satisfied the order.
+
+### 4.4 failure_code partition
+
+The `failure_code` enum at v1 carries values consumers can reasonably route on (Sales' Lead-reactivation logic differs by failure cause, and Growth's funnel-close attribution treats provider-down failures differently from declined-card failures). Consumers SHALL treat unknown values as safe-to-ignore per the additive-discipline:
+
+- `card_declined`. The provider declined the card. Most common failure cause; consumers typically retry on the customer's next interaction rather than auto-retrying.
+- `insufficient_funds`. Specific sub-type of card_declined the provider distinguishes; included separately because Sales' Lead-reactivation routes differently for it.
+- `expired_card`. The card on file is past its expiry date.
+- `network_error`. Transient network failure between Revenue and the provider. Auto-retryable per Revenue's external-actions retry policy.
+- `provider_unavailable`. The provider returned 5xx or timed out. Auto-retryable.
+- `other`. Catchall for failure causes not yet partitioned. Phase-2 narrowing may surface additional values; the additive-discipline lets Revenue add values without consumer breakage.
+
+## 5. Producer responsibilities
+
+Revenue SHALL emit `payment.received` exactly once per successful payment. Idempotency is enforced at the Prisma transaction level: the writeback transaction is keyed by the provider reference and the attempt number, and a duplicate writeback attempt against the same `(provider_ref, order_id)` no-ops at the upstream `runApplyInvoicePayment` or `runChargeOrder` validation rather than re-emitting.
+
+Revenue SHALL emit `payment.received` and `payment.failed` inside the same Prisma transaction as the corresponding writeback per ADR-0009's producer-transactional-guarantee shape. The publish call is the last statement in the transaction by convention, so any earlier rollback prevents the event from firing.
+
+Revenue SHALL NOT emit `payment.received` if the provider call succeeded but the writeback transaction rolled back. The divergence is detectable by the reconciliation surface running against the Square audit log; it is not the producer's job to emit a "writeback failed" event for it. The reconciliation surface is Revenue-internal and lives outside this contract's scope.
+
+Revenue SHALL populate `provider_ref` on every emit. The funding-state external-reference rule in `domains/revenue.md` requires this: a payment-flow event without a provider reference is a bug. For `payment_method` values that have no provider call (`cash`, `check`, `credit_balance`), the `provider_ref` SHALL be the external-actions row id, prefixed with `ext_` to distinguish from provider-issued ids.
+
+Revenue SHALL emit `payment.failed` only for the first failed attempt; subsequent retries against the same `(provider_ref, order_id)` that also fail SHALL NOT re-emit. Consumers see one `payment.failed` per order's failed-payment attempt, not one per retry.
+
+Revenue MAY emit `payment.received` for an order that previously emitted `payment.failed`; this is the recovery case (the customer fixed the underlying issue and the next attempt succeeded). Consumers SHOULD treat the latest event as the authoritative state.
+
+## 6. Consumer responsibilities
+
+Consumers SHALL handle `payment.received` and `payment.failed` independently; neither presupposes the other. An order's first payment attempt may emit `payment.received` directly without a prior `payment.failed`.
+
+Consumers SHALL treat unknown values for the `payment_method` and `failure_code` enums as safe-to-ignore per the additive-discipline in §8. The closed-set guarantee is at v1 publish time; future v1.x versions may add values without a consumer cutover.
+
+Consumers SHALL NOT parse `failure_reason`. The field is provider-specific free-form text and may change format. Use `failure_code` for routing.
+
+Consumers SHALL handle dispatcher redelivery. Per the event-envelope §9.2, Revenue's idempotency at the writeback level does not preclude the dispatcher redelivering the same `event_id` to a consumer that crashed mid-handler; consumers maintain per-(consumer, event_id) dedup tables per the SDK's at-most-once invocation guarantee.
+
+Sales SHALL NOT independently compute "did this payment close a Lead"; the `customer.handoff` event from `credit-reservation-lock` §5 is the authoritative Lead-close signal for purchase paths that involve credit reservations. The `payment.received` event is the input to Sales' separate Lead-reactivation flow (a customer paying off an unpaid invoice while the Lead is in reactivation cadence).
+
+Growth's funnel-close attribution SHOULD route on `payment_path`: `invoice_paid` events tie to a different funnel stage than `active_charge` events. The semantics are Growth-internal and not part of this contract.
+
+Delivery's awareness of credit availability is downstream of the credit-reservation-lock contract's `credit.purchased` and `credit.funded` events; `payment.received` is informational for Delivery and does not trigger Delivery-side state changes directly.
+
+## 7. Idempotency and retry
+
+Per ADR-0009, the dispatcher SDK guarantees at-most-once handler invocation per `(consumer, event_id)` via the per-(consumer, event_id) dedup table. Consumer handlers SHOULD be idempotent on their own work even with this guarantee, because handler failures mid-write can leave partial state that retries against.
+
+Revenue's producer-side idempotency is enforced by the upstream order-amount logic: a duplicate `runApplyInvoicePayment` or `runChargeOrder` against the same `(provider_ref, order_id)` is a no-op at the validation layer and never reaches the writeback transaction or the dispatcher.publish.
+
+Dispatcher delivery retry follows the SDK's default: exponential backoff with jitter, default 3 retries, then dead-letter to the platform-managed DLQ table per ADR-0009 action item 6.
+
+## 8. Versioning
+
+This contract follows the additive-discipline pattern from `event-envelope` §11. New fields MUST default to null or a backwards-compatible value. New enum values MUST be appended; consumers MUST treat unknown enum values as safe-to-ignore. Removal, type change, or narrowing of existing enum values requires a major version bump and a producer cutover with a deprecation window per the event-envelope contract.
+
+Patch versions (1.0.0 to 1.0.1) cover editorial clarifications. Minor versions (1.0.x to 1.1.0) cover additive changes. Major versions (1.x.y to 2.0.0) cover breaking changes; none are anticipated under v1's planning horizon.
+
+The producer cutover for any minor version follows the event-envelope §11 pattern: producers continue emitting at the prior schema_version until the cutover date (publish date plus 14 days by default), then flip to the new schema_version. Consumers MAY rely on new fields from the cutover date.
+
+## 9. Producer responsibilities trace
+
+The producer-side sites where these events fire (per `revenue/docs/dispatcher-emit-wiring.md`):
+
+- `payment.received` from `revenue/src/modules/orders/service.ts:runApplyInvoicePayment` (path: `invoice_paid`).
+- `payment.received` from `revenue/src/modules/orders/service.ts:runChargeOrder` (path: `active_charge`).
+- `payment.failed` from the failure branches of the same two functions, when the provider reports failure or the upstream validation determines the writeback should not flip the order to PAID.
+- `payment.received` from a future internal-credit-balance settlement path (`payment_method: credit_balance`); not yet built, lands when the orders module's full Postgres migration completes per `2026-05-09-revenue-q2-airtable-sunset-scoping` commitment 0.
+
+This trace is the live producer-side reference; if a future revision adds an event-firing site outside the orders module (Pay Runs, scheduled retries, manual operator-initiated charges), this section updates as part of the same contract change.
+
+## 10. Action items
+
+1. [ ] Revenue: register `payment.received` and `payment.failed` in `coordination/contracts/event-types-registry.json` with the consumer mappings named in this contract. Owner: Revenue. Due: at v1.0.0 publish (this filing).
+2. [ ] Revenue: wire the producer-side dispatcher.publish calls at the three named sites in §9 inside Prisma transactions per ADR-0009, alongside the per-module Postgres migration in `2026-05-09-revenue-q2-airtable-sunset-scoping` commitment 1. Owner: Revenue. Due: 2026-06-22 per the Q2 directive.
+3. [ ] Sales: scaffold a subscriber for `payment.received` in the lead-pipeline reactivation flow once Phase 2 SDK ships (2026-06-22). Owner: Sales. Due: per Sales' own roadmap.
+4. [ ] Growth: scaffold a subscriber for `payment.received` and `payment.failed` for funnel-close attribution. Owner: Growth. Due: per Growth's own roadmap.
+5. [ ] Delivery: subscribe to `payment.received` if the awareness signal informs scheduling logic (optional; the credit-reservation-lock events are the primary Delivery feed). Owner: Delivery. Due: per Delivery's own roadmap.
+6. [ ] Platform: ack the registry edits and the contract publication. Owner: Platform. Due: per the response window on `2026-05-02-revenue-emit-wiring-registry-additions`.
+
+## 11. Trigger to revisit
+
+Any of the following reopens this contract:
+
+- A new payment provider lands (Quo, alternative card processor, alternative ACH provider). The provider-agnostic shape SHOULD absorb additive without bumping; if the new provider's behavior differs in ways the v1 enums do not capture (e.g. a new failure_code value), the change lands as a v1.x patch.
+- The `credit_balance` payment method's internal-credit-balance settlement path lands and surfaces fields the v1 payload does not carry.
+- A consumer surfaces a routing requirement that the v1 enum partitions do not satisfy. Phase-2 narrowing of the enums lands as v1.x patches per the additive-discipline.
+- The funding-sub-state event family decision (collapse vs keep separate per `2026-05-02-revenue-emit-wiring-registry-additions`) introduces an overlap with payment-flow that warrants reorganization.
+- A multi-tenant or multi-region scope expansion changes the envelope's `tenant_id` semantics in a way that affects the payload field set.
+
+## Change log
+
+- **v1.0.0** (2026-05-02). Initial release. Two events (`payment.received`, `payment.failed`) with v1 payloads. Five-value `payment_method` enum (`card`, `ach`, `cash`, `check`, `credit_balance`). Two-value `payment_path` enum (`invoice_paid`, `active_charge`). Six-value `failure_code` enum (`card_declined`, `insufficient_funds`, `expired_card`, `network_error`, `provider_unavailable`, `other`). Producer-transactional-guarantee shape from ADR-0009 codified at §5. Sibling to refund-flow contract published the same day. Registered alongside the `2026-05-02-revenue-emit-wiring-registry-additions` memo's commitment 0.