@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/coaching-confirmation/schema/payloads/coaching.lesson.confirmation_decided-v1.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/coaching-confirmation/schema/payloads/coaching.lesson.confirmation_decided-v1.json",
+  "title": "coaching.lesson.confirmation_decided payload v1",
+  "description": "Payload for the coaching.lesson.confirmation_decided event_type at schema_version 1. Coaching emits this after deciding a Sales lead.coach.confirmation.requested event. The envelope subject is confirmation_request_id. The payload intentionally excludes customer contact details, full Lead notes, Guardian details, and coach private contact details.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "organization_id",
+    "lead_id",
+    "confirmation_request_id",
+    "coach_id",
+    "decision",
+    "denial_reason",
+    "lesson_window",
+    "service_area_id",
+    "lesson_type_id",
+    "decided_at",
+    "decided_by",
+    "notes"
+  ],
+  "properties": {
+    "organization_id": {
+      "type": "string",
+      "description": "Organization scope copied from the Sales confirmation request.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "lead_id": {
+      "type": "string",
+      "description": "Sales Lead identifier copied from the request.",
+      "pattern": "^lead_[A-Za-z0-9._:-]+$",
+      "maxLength": 160
+    },
+    "confirmation_request_id": {
+      "type": "string",
+      "description": "Sales-minted idempotency and correlation key. Mirrors the event envelope subject.",
+      "minLength": 1,
+      "maxLength": 160
+    },
+    "coach_id": {
+      "type": "string",
+      "description": "Coach identifier Coaching evaluated.",
+      "pattern": "^coa_[A-Za-z0-9._:-]+$",
+      "maxLength": 160
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["confirmed", "denied"],
+      "description": "Coaching's decision for the requested coach and lesson window."
+    },
+    "denial_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        "coach_unavailable",
+        "capacity_changed",
+        "coverage_mismatch",
+        "certification_mismatch",
+        "operator_declined",
+        "other",
+        null
+      ],
+      "description": "Required when decision=denied. Null when decision=confirmed."
+    },
+    "lesson_window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["start", "end"],
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Requested lesson start, UTC ISO 8601."
+        },
+        "end": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Requested lesson end, UTC ISO 8601."
+        }
+      }
+    },
+    "service_area_id": {
+      "type": "string",
+      "description": "Service area copied from the request.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "lesson_type_id": {
+      "type": ["string", "null"],
+      "description": "Lesson type copied from the request when Sales supplied one.",
+      "maxLength": 128
+    },
+    "decided_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When Coaching made the decision, UTC ISO 8601."
+    },
+    "decided_by": {
+      "type": ["string", "null"],
+      "description": "Operator id when human-decided. Null only for a future system path.",
+      "maxLength": 160
+    },
+    "notes": {
+      "type": ["string", "null"],
+      "description": "Optional operator context. Not for PII or state-machine logic.",
+      "maxLength": 500
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "decision": { "const": "confirmed" } },
+        "required": ["decision"]
+      },
+      "then": {
+        "properties": { "denial_reason": { "type": "null" } }
+      }
+    },
+    {
+      "if": {
+        "properties": { "decision": { "const": "denied" } },
+        "required": ["decision"]
+      },
+      "then": {
+        "properties": {
+          "denial_reason": {
+            "type": "string",
+            "enum": [
+              "coach_unavailable",
+              "capacity_changed",
+              "coverage_mismatch",
+              "certification_mismatch",
+              "operator_declined",
+              "other"
+            ]
+          }
+        },
+        "required": ["denial_reason"]
+      }
+    }
+  ]
+}

package/contracts/coaching-confirmation/schema/payloads/lead.coach.confirmation.requested-v1.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/coaching-confirmation/schema/payloads/lead.coach.confirmation.requested-v1.json",
+  "title": "lead.coach.confirmation.requested payload v1",
+  "description": "Payload for the lead.coach.confirmation.requested event_type at schema_version 1. Sales emits this when a Lead enters the coach-confirmation workflow and asks Coaching to confirm or deny a proposed coach and lesson window. The envelope subject is confirmation_request_id. The payload intentionally excludes customer contact details, full Lead notes, Guardian details, and coach private contact details.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "organization_id",
+    "lead_id",
+    "confirmation_request_id",
+    "coach_id",
+    "service_area_id",
+    "lesson_type_id",
+    "lesson_window",
+    "required_certifications",
+    "requested_at",
+    "source_pointer"
+  ],
+  "properties": {
+    "organization_id": {
+      "type": "string",
+      "description": "Organization scope for the confirmation request.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "lead_id": {
+      "type": "string",
+      "description": "Sales Lead identifier for the Lead entering coach confirmation.",
+      "pattern": "^lead_[A-Za-z0-9._:-]+$",
+      "maxLength": 160
+    },
+    "confirmation_request_id": {
+      "type": "string",
+      "description": "Sales-minted idempotency and correlation key. Mirrors the event envelope subject and is echoed by coaching.lesson.confirmation_decided.",
+      "minLength": 1,
+      "maxLength": 160
+    },
+    "coach_id": {
+      "type": "string",
+      "description": "Coach identifier Sales proposes for the lesson.",
+      "pattern": "^coa_[A-Za-z0-9._:-]+$",
+      "maxLength": 160
+    },
+    "service_area_id": {
+      "type": "string",
+      "description": "Service area for the proposed lesson.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "lesson_type_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Lesson type for the proposed lesson when Sales has one.",
+      "maxLength": 128
+    },
+    "lesson_window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "start",
+        "end"
+      ],
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Requested lesson start, UTC ISO 8601."
+        },
+        "end": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Requested lesson end, UTC ISO 8601."
+        }
+      }
+    },
+    "required_certifications": {
+      "type": [
+        "array",
+        "null"
+      ],
+      "description": "Certification keys Sales believes are required for this lesson. Null when none are required or Sales has no source-backed certification requirement.",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128
+      },
+      "uniqueItems": true
+    },
+    "requested_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When Sales created the confirmation request, UTC ISO 8601."
+    },
+    "source_pointer": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "description": "Optional Sales-side source pointer for audit. This points to the local action or workflow source, not customer-visible content.",
+      "additionalProperties": false,
+      "required": [
+        "source_type",
+        "source_id"
+      ],
+      "properties": {
+        "source_type": {
+          "type": "string",
+          "description": "Sales source kind, for example manual_action, stage_transition, or cadence_runtime.",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "source_id": {
+          "type": "string",
+          "description": "Sales-local source row or workflow id.",
+          "minLength": 1,
+          "maxLength": 160
+        }
+      }
+    }
+  }
+}

package/contracts/credit-reservation-funding-state/README.md

@@ -0,0 +1,147 @@
+# Credit Reservation Funding State
+
+**Status:** v1.0.0
+**Date:** 2026-05-05
+**Owner:** revenue (credit-reservations module, credit-ledger-entries module, payment-adapters module)
+**Consumers:** revenue (own funding-state reconciliation runbook reads these events for cross-checking provider-side state against canonical commercial state), platform-warehouse (analytics ingestion). No other domain subscribes at v1: Sales gates Lead-close on `customer.handoff` not on funding sub-state per `coordination/contracts/credit-reservation-lock/README.md` §5; Delivery's lock-state subscriber consumes `credit.funded` for the funded-by-credit-availability invariant per Delivery's reply on `2026-05-02-delivery-funding-event-shape-and-payment-refund-acks`; Coaching's lock-aware availability projection keys on lock state per `coach-availability` v1.0.1 §4.3 not on funding sub-state; Growth subscribes only to `payment.received` per its parent-thread reply.
+**Related ADRs:** ADR-0001 (tenant_id), ADR-0002 (canonical entity ID template; `crr_` and `per_` prefixes), ADR-0003 (Person canonical, Revenue does not own Person), ADR-0005 (event envelope), ADR-0006 (credit-reservation-lock state machine; this contract is a sibling that extends Revenue's producer surface without amending the lock state machine), ADR-0009 (dispatcher transport, producer transactional guarantee), ADR-0010 (provider externals at Platform; Square is the v1 provider for the payment-processor reference)
+**Related contracts:** Event Envelope Contract (`../event-envelope/README.md`), Credit Reservation Lock Contract (`../credit-reservation-lock/README.md`), Payment Flow Contract (`../payment-flow/README.md`), Refund Flow Contract (`../refund-flow/README.md`)
+**Sub-specs (authoritative):** `schema/payloads/reservation.funded-v1.json`, `schema/payloads/reservation.refunding-v1.json`, `schema/payloads/reservation.refunded-v1.json`
+**Validations:** none yet
+
+## 1. Purpose and scope
+
+This contract specifies the producer responsibilities and consumer-visible payload shape for Revenue's three funding-sub-state events: `reservation.funded`, `reservation.refunding`, `reservation.refunded`. The events are produced by Revenue at the writeback transaction commit for funding-sub-state transitions on a credit reservation, with the payment-processor reference carried on every payload per the funding-state external-reference rule in `coordination/domains/revenue.md`. All three fire under the producer-transactional-guarantee shape from ADR-0009 (dispatcher.publish inside the same Prisma transaction as the funding-state transition's row write).
+
+This contract is the Shape A landing per `2026-05-05-revenue-funding-event-shape-decided-shape-a`, converging the `reservation.*` family decision unanimously endorsed by Delivery, Sales, Growth, Coaching, and Platform on the parent thread (`2026-05-02-revenue-emit-wiring-registry-additions`). The architectural shape: lock-state semantics stay on the credit-reservation-lock contract, the funding-sub-state surface lives here as a sibling, and the cross-domain consumer surface stays clean (lock-state events to broad consumers, funding sub-state to Revenue + warehouse only).
+
+In scope: the three event names, the payload shapes at v1, the producer's transactional-guarantee discipline, the consumer-visible enum partitions on `funding_source` and `refund_reason`, the payment-processor reference fields, idempotency expectations, and the versioning policy under additive discipline.
+
+Out of scope: the lock state machine and its `reserved -> locked` transition (covered by `credit-reservation-lock` §3-§5; lock-state semantics live there); the credit-purchase flow that creates funded balances on credit accounts (covered by `credit-reservation-lock` §9.1 with `credit.purchased`); payment provider adapter wire-format and webhook handling (lives in `revenue/src/lib/providers/square/` and the upstream external-actions module per ADR-0011); the payment-flow and refund-flow events that fire on the order side (covered by sibling contracts `payment-flow` and `refund-flow`); revenue recognition (Revenue-internal, see `domains/revenue.md`).
+
+## 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
+
+**Funding sub-state.** A property of a credit reservation in the `reserved` lifecycle state, separate from the lifecycle state itself. Values: `pending_funding`, `funded`, `refunding`, `refunded`. The funding sub-state is what the lock-state machine's T-24h lock check reads to decide `reserved -> locked` vs `reserved -> released (system_unpaid)` per credit-reservation-lock §4.2. This contract emits events on the three transitions out of `pending_funding`: `pending_funding -> funded` (`reservation.funded`), `funded -> refunding` (`reservation.refunding`), and `refunding -> refunded` (`reservation.refunded`).
+
+**Funding-state writeback.** The Revenue-internal transaction that records a funding-sub-state transition: the credit-reservation funding-status update, optional credit-ledger-entry adjustments, the payment-processor reference snapshot, and the dispatcher.publish for the corresponding event. Distinct from the **provider call** (the payment-flow or refund-flow operation that motivates the funding-state transition).
+
+**Payment-processor reference.** The provider-side identifier that links a funding-state transition back to the payment provider's record. Required on every payload per the funding-state external-reference rule in `domains/revenue.md`. Format: `<provider>:<provider_ref>` where provider is one of `square`, `stripe`, `manual` (for cash/check/credit_balance internal reconciliations) and provider_ref is the provider's own id. The shape mirrors the payment-flow `provider_ref` field but adds the explicit provider prefix because the funding-state surface is multi-provider over time and the audit trail benefits from explicit provider attribution.
+
+**Funding source.** The path through which the reservation became funded. Enum partition per §4.4. Used by Revenue's reconciliation runbook to route by source-specific verification rules; warehouse consumes it as a dimensional join on the funding-event grain.
+
+**Refund reason.** The cancellation or operator action that triggered the refund-flow against the reservation's funded balance. Enum partition per §4.5. Mirrors the `reason_code` enum on `credit.released` v2 per ADR-0006 amended (the `_in_window` vs `_exception` partition lands here too) so reconciliation can join the credit.released event and the reservation.refunding event on the same logical operator decision.
+
+## 4. Event types
+
+### 4.1 reservation.funded
+
+Emitted by Revenue at the writeback transaction commit when a credit reservation's funding sub-state transitions from `pending_funding` to `funded`. The corresponding upstream event is the payment-flow's `payment.received` (the customer paid, and the order's owning credit account now has the funded credits available); this contract's `reservation.funded` fires when the per-reservation funding sub-state on a specific reservation flips, which happens at credit-purchase commit time when the reservation is the next-up claim against the newly-purchased credits.
+
+The publish lives inside the same `prisma.$transaction` as the credit-reservation funding-status update per ADR-0009. Either the writeback commits and the event fires, or the writeback rolls back and no event fires.
+
+Payload v1: `credit_reservation_id`, `person_id`, `funding_source`, `payment_processor_provider`, `payment_processor_ref`, `funded_at`. See `schema/payloads/reservation.funded-v1.json` for the authoritative shape and field constraints.
+
+The `funding_source` field is partitioned per §4.4 and disambiguates whether the funding came from a Square invoice payment, an active charge, a cash/check operator-recorded payment, an internal credit-balance application, or a refund recovery (the rare path where a previously-refunded reservation gets re-funded by a follow-up purchase).
+
+### 4.2 reservation.refunding
+
+Emitted by Revenue at the writeback transaction commit when a credit reservation's funding sub-state transitions from `funded` to `refunding`. The transition typically follows the lock-state machine's `released` event (with `credit.released` v2 carrying the `reason_code`); this contract's `reservation.refunding` is the funding-side mirror that captures the refund-flow's intent before the refund completes against the provider.
+
+The pairing: a `credit.released` event on the credit-reservation-lock contract (lock-state side) plus a `reservation.refunding` event on this contract (funding-state side) together describe the same operator decision viewed from two angles. Subscribers that care about lock state (Delivery, Coaching) read the lock event; subscribers that care about funding state (Revenue's reconciliation, warehouse) read this event. The two events are emitted in the same Prisma transaction when both apply.
+
+Not all `credit.released` transitions emit `reservation.refunding`. A reservation released for `reason_code = customer_requested_in_window` with the credits going back to the credit-account balance (no provider-side refund) does not emit `reservation.refunding`; the funding sub-state stays at `funded` until the credits are re-claimed by another reservation. A reservation released for `reason_code = customer_requested_exception` with the credits being refunded to the customer's payment method DOES emit `reservation.refunding` because the funding-state machine transitions to `refunding`.
+
+Payload v1: `credit_reservation_id`, `person_id`, `refund_reason`, `payment_processor_provider`, `payment_processor_ref`, `refund_amount_cents`, `currency`, `refunding_at`. See `schema/payloads/reservation.refunding-v1.json` for the authoritative shape.
+
+### 4.3 reservation.refunded
+
+Emitted by Revenue at the writeback transaction commit when a credit reservation's funding sub-state transitions from `refunding` to `refunded`. The corresponding upstream event is the refund-flow's `refund.completed` (the provider has settled the refund); this contract's `reservation.refunded` fires when the per-reservation funding sub-state on a specific reservation reflects the completed refund, which happens at the refund-completion writeback.
+
+Payload v1: `credit_reservation_id`, `person_id`, `refund_reason`, `payment_processor_provider`, `payment_processor_ref`, `refund_amount_cents`, `currency`, `refunding_at`, `refunded_at`. The `refunding_at` field on this payload SHALL match the corresponding `reservation.refunding` event's `refunding_at` so consumers correlating the two via the funding-state machine have a stable join key. See `schema/payloads/reservation.refunded-v1.json` for the authoritative shape.
+
+### 4.4 funding_source partition
+
+The `funding_source` enum at v1 covers the paths through which a reservation becomes funded. Consumers SHALL treat unknown values as safe-to-ignore per the additive-discipline in §8:
+
+- `invoice_paid`. Customer paid against a Square invoice; the payment-flow's `payment.received` event fired with `payment_path = invoice_paid` upstream.
+- `active_charge`. Customer's payment-method-on-file was charged via a Revenue-initiated Square call; the payment-flow's `payment.received` event fired with `payment_path = active_charge` upstream.
+- `cash`. Operator recorded a cash payment in person at a Sguild facility; the external-actions row records the operator who handled it.
+- `check`. Operator recorded a check payment; the external-actions row records the check number and the operator.
+- `credit_balance`. The reservation was funded from existing credit-account balance without a provider call (the customer had previously-purchased credits; this reservation drew from that pool).
+- `refund_recovery`. Rare: a previously-refunded reservation got re-funded because the customer made a follow-up purchase that the reconciliation runbook routed back to the original reservation. Mostly an audit-trail value; the warehouse model dimensionally distinguishes recovered fundings from primary fundings.
+
+### 4.5 refund_reason partition
+
+The `refund_reason` enum at v1 mirrors the `reason_code` enum on `credit.released` v2 per ADR-0006 amended. The two enums are co-versioned: a value that lands on `credit.released` v2 SHALL also land here at the same version, and vice versa. This co-versioning is the seam that lets reconciliation join the lock-state event and the funding-state event on the same operator decision.
+
+Values at v1: `site_closure`, `coach_unavailable_reschedule_failed`, `force_majeure`, `weather`, `administrative_void`, `customer_requested_in_window`, `customer_requested_exception`, `policy_exception`, `bad_debt_writeoff`. See `credit-reservation-lock` §6 and §9.6 for the per-value semantics; this contract does not duplicate those definitions. Consumers SHALL treat unknown values as safe-to-ignore per the additive-discipline.
+
+Note: not every `refund_reason` value triggers a `reservation.refunding` event. The auto-release subset (`site_closure`, `coach_unavailable_reschedule_failed`, `force_majeure`, `weather`, `administrative_void`, `customer_requested_in_window`) routes credits back to the credit-account balance without a provider-side refund, in which case the funding sub-state stays at `funded` and no `reservation.refunding` event fires. The explicit-operator subset (`customer_requested_exception`, `policy_exception`, `bad_debt_writeoff`) typically routes through a provider-side refund and DOES emit `reservation.refunding`. The `funding_source` enum on the prior `reservation.funded` event determines whether a provider-side refund is even possible (a `credit_balance`-funded reservation cannot be refunded to a payment method; it routes back to the credit-account balance regardless of `refund_reason`).
+
+## 5. Producer responsibilities
+
+Revenue SHALL emit `reservation.funded` exactly once per reservation when its funding sub-state transitions from `pending_funding` to `funded`. Idempotency is enforced at the Prisma transaction level: the writeback transaction is keyed by the credit-reservation id, and a duplicate writeback against the same `credit_reservation_id` with funding sub-state already at `funded` no-ops at the upstream funding-state-machine validation rather than re-emitting.
+
+Revenue SHALL emit `reservation.refunding` and `reservation.refunded` per the funding-state machine transitions described in §4.2 and §4.3. The two events fire in separate Prisma transactions: `reservation.refunding` at refund-flow initiation (paired with `refund.initiated` on the refund-flow contract), `reservation.refunded` at refund-flow completion (paired with `refund.completed` on the refund-flow contract).
+
+Revenue SHALL emit all three events inside the same Prisma transaction as the credit-reservation funding-status row update 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 populate `payment_processor_provider` and `payment_processor_ref` on every emit. The funding-state external-reference rule in `domains/revenue.md` requires both fields. For `funding_source` values that have no provider call (`cash`, `check`, `credit_balance`), `payment_processor_provider` SHALL be `manual` and `payment_processor_ref` SHALL be the external-actions row id, prefixed with `ext_` to distinguish from provider-issued ids. The consistent shape across providers is what makes the warehouse's dimensional join on (provider, provider_ref) work.
+
+Revenue SHALL NOT emit any of these events if the upstream payment-flow or refund-flow event did not fire. The funding-state events are downstream of payment/refund settlement; an emit without the corresponding upstream fact is a producer-side bug.
+
+Revenue SHALL preserve the `refunding_at` value across `reservation.refunding` and `reservation.refunded` for the same refund-flow instance, so consumers correlating the two events have a stable join key.
+
+## 6. Consumer responsibilities
+
+Consumers SHALL handle each of the three events independently; the funding-state machine's transitions are emitted at separate transaction commits and consumers SHALL NOT presume a temporal ordering beyond the natural funded -> refunding -> refunded sequence within a single reservation.
+
+Consumers SHALL treat unknown values for the `funding_source` and `refund_reason` 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 treat the `reservation.refunding` and `reservation.refunded` event pair as a refund-flow-instance-correlated pair, joining on `(credit_reservation_id, refunding_at)`. A `reservation.refunded` without a prior `reservation.refunding` for the same `(credit_reservation_id, refunding_at)` pair is a reconciliation case that the consumer SHOULD surface but SHALL NOT block on.
+
+### 6.1 Revenue's own consumption (reconciliation)
+
+Revenue's funding-state reconciliation runbook reads all three events to cross-check provider-side state against canonical commercial state. The flow:
+
+For each `reservation.funded` event, the runbook verifies the corresponding `payment.received` (or `payment.failed` followed by a recovery `payment.received`) exists on the payment-flow event stream with matching `(payment_processor_provider, payment_processor_ref)`. Drift surfaces as a runbook-flagged case the operator resolves manually.
+
+For each `reservation.refunding` event, the runbook verifies the corresponding `refund.initiated` exists on the refund-flow event stream with matching reference. Drift surfaces as above.
+
+For each `reservation.refunded` event, the runbook verifies the corresponding `refund.completed` exists on the refund-flow event stream. Drift surfaces as above.
+
+The reconciliation is observational; Revenue does not gate any state transition on the consumer-side processing of these events from its own seat. The producer-transactional-guarantee on the producer side is the load-bearing correctness primitive; this consumer-side reconciliation is the audit-trail surface that catches the rare cases where producer-side discipline got bypassed (e.g., a manual SQL edit on a reservation row that didn't fire through the state machine).
+
+### 6.2 platform-warehouse
+
+The platform-warehouse semantic-layer model picks up all three events as facts on a funding-event grain. Dimensional joins on `payment_processor_provider`, `payment_processor_ref`, `funding_source`, `refund_reason`, and the time fields. The model correlates with the payment-flow and refund-flow facts via the shared `payment_processor_ref`, and with the credit-reservation-lock facts via `credit_reservation_id`. Warehouse usage is observability-only; Platform does not gate any state transition on these events per Platform's parent-thread reply on `2026-05-02-platform-revenue-emit-wiring-acks-and-shape-a`.
+
+## 7. Idempotency and dedup
+
+The producer-transactional-guarantee plus the funding-state-machine's idempotency keys (each transition is keyed by the credit-reservation id and the from-state) prevent double-emits at the producer side. At the consumer side, the dispatcher SDK's per-(consumer, event_id) dedup per the Phase 2 ship memo (`2026-05-09-platform-dispatcher-sdk-phase-2-shipped` Slice 3) handles redelivery semantics; consumers do not need application-level dedup against these events at v1.
+
+Future cutover windows where the funding-state-machine emits both v1 and v2 of any event_type would introduce a dual-emit-window dedup case. Per Revenue's pattern-positions reply (`2026-05-05-revenue-engineering-method-patterns-positions` §4), consumers SHOULD be prepared to add payload-composite dedup at that point. No such window is in flight today.
+
+## 8. Versioning policy
+
+This contract follows the same versioning policy as `credit-reservation-lock` and the sibling payment-flow / refund-flow contracts. Per-event-type `schema_version` is independent across the three event types. Additive discipline holds: a new optional field, a new enum value on `funding_source` or `refund_reason`, or a new event type can be added at v1.x without a cutover; a breaking change increments to v2 with a deprecation window per the operator standard "no consumer running against a deprecated contract version for more than two weeks."
+
+The `refund_reason` enum is co-versioned with `credit.released`'s `reason_code` enum on the credit-reservation-lock contract per §4.5. A v2 of either enum forces a coordinated v2 of the other; the joint-review pattern lands the amendment per `2026-05-08-delivery-reason-codes-signoff-accepted`'s precedent.
+
+## 9. Producer's emit-site map
+
+The Revenue-side call sites for the three events are documented in the Revenue repo's emit-wiring inventory at `revenue/docs/dispatcher-emit-wiring.md`. Summary for cross-domain readers:
+
+`reservation.funded` fires from the credit-ledger-entries module's funding-state transition handler, inside the same Prisma transaction as the credit-reservation funding-status update from `pending_funding` to `funded`. The transition is triggered upstream by either a `payment.received` arrival (for invoice_paid / active_charge sources) or a credit-purchase commit (for credit_balance source) or an operator action (for cash / check sources).
+
+`reservation.refunding` fires from the refunds module's refund-initiation handler, inside the same Prisma transaction as the credit-reservation funding-status update from `funded` to `refunding`. Paired with the refund-flow's `refund.initiated` event in the same transaction.
+
+`reservation.refunded` fires from the refunds module's refund-completion handler, inside the same Prisma transaction as the credit-reservation funding-status update from `refunding` to `refunded`. Paired with the refund-flow's `refund.completed` event in the same transaction.
+
+## 10. Changelog
+
+- **v1.0.0** (2026-05-05) — Initial release. Three event types (`reservation.funded`, `reservation.refunding`, `reservation.refunded`) with the funding_source and refund_reason enum partitions, the payment-processor reference fields per the funding-state external-reference rule, the producer-transactional-guarantee discipline mirroring credit-reservation-lock and payment-flow / refund-flow, and the additive-discipline versioning policy. Lands per `2026-05-05-revenue-funding-event-shape-decided-shape-a` after unanimous Shape A endorsement on the parent thread.