@sguild/dispatcher 2.0.0

package/contracts/identity/schema/payloads/intake.captured-v2.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/identity/schema/payloads/intake.captured-v2.json",
+  "title": "intake.captured payload v2",
+  "description": "Payload for the intake.captured event_type at schema_version 2. Growth emits this when a form_submission enters the intake flow. v2 adds visitor_id for pre-mint attribution stitching and carries the bundled source expansion for subscriber_promotion, partner_upload, manual_capture, and derived_match per the 2026-05-01 Platform-Growth attribution and subscriber-promotion threads. The envelope subject carries the fsm_<UUID v7> form_submission id; payload tenant_id mirrors the envelope tenant_id for producer-local validation and downstream warehouse convenience.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenant_id",
+    "source",
+    "campaign_code",
+    "landing_url",
+    "submission",
+    "person_id",
+    "visitor_id"
+  ],
+  "properties": {
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id. Per ADR-0001 this is tenancy, not organization_id."
+    },
+    "source": {
+      "type": "string",
+      "description": "Growth intake source. Known values include website_form, meta_lead_ad, subscriber_promotion, partner_upload, manual_capture, and derived_match. Flexible string by design; consumers SHALL tolerate unknown source values per the event-envelope consumer rules."
+    },
+    "campaign_code": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Growth campaign code, typically derived from utm_campaign. Null when no campaign attribution is present."
+    },
+    "landing_url": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Landing page URL or intake origin URL as observed by Growth. Null when unavailable."
+    },
+    "submission": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "first_name",
+        "last_name",
+        "phone",
+        "zip"
+      ],
+      "properties": {
+        "first_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Submitted given name."
+        },
+        "last_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Submitted family name."
+        },
+        "phone": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Submitted phone number in Growth's normalized display format. Platform normalizes before identity resolution."
+        },
+        "zip": {
+          "type": "string",
+          "pattern": "^[0-9]{5}$",
+          "description": "Submitted five-digit ZIP code."
+        },
+        "email": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "email",
+          "description": "Optional submitted email. Present for subscriber-derived or email-bearing intakes when Growth has it."
+        },
+        "dob": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date",
+          "description": "Optional submitted date of birth when available. Platform treats DOB as identity input and does not redistribute it on the canonical Person contract."
+        }
+      }
+    },
+    "person_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Canonical Person id when Growth already knows the match, otherwise null until Platform emits intake.matched.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "visitor_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Growth-owned non-canonical visitor identifier used by the warehouse semantic layer for pre-mint attribution stitching. Null is accepted during transition or when no visitor token is available."
+    },
+    "subscriber_row_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Optional Growth subscriber row back-reference for subscriber_promotion synthetic submissions. Growth currently uses sub_<UUID v7>; earlier thread prose mentioned gws_ as a candidate before the Growth schema reserved sub_.",
+      "pattern": "^sub_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    }
+  }
+}

package/contracts/identity/schema/payloads/person.updated-v1.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/identity/schema/payloads/person.updated-v1.json",
+  "title": "person.updated payload v1",
+  "description": "Payload for the person.updated event_type at schema_version 1. Platform's identity service emits this when any canonical field on a Person changes: status transitions (active to archived, archived to active), name edits (given_name, family_name, display_name), or the is_minor flip from the daily invariant job. Producer SHALL emit inside the same Prisma transaction as the Person row update per ADR-0009 producer-transactional guarantee. Subscribers filter on changed_fields to skip irrelevant changes (e.g., a name-edit subscriber ignores status-only changes). prior_status is populated only when status is among the changed_fields, so archive consumers can detect the active to archived transition without a separate fetch.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenant_id",
+    "person",
+    "changed_fields"
+  ],
+  "properties": {
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id. Per ADR-0001 this is tenancy, not organization_id."
+    },
+    "person": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "person_id",
+        "status",
+        "alias_of",
+        "given_name",
+        "family_name",
+        "display_name",
+        "is_minor",
+        "created_at",
+        "updated_at"
+      ],
+      "description": "The full post-update canonical Person, exactly matching the nine-field shape from contracts/identity/person-canonical-fields.md. Consumers MAY treat this as a refresh of their local Person cache without a follow-up fetch.",
+      "properties": {
+        "person_id": {
+          "type": "string",
+          "description": "per_<UUID v7> 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": {
+          "type": "string",
+          "enum": ["active", "archived", "merged"],
+          "description": "Current canonical status. archived means preserve history, do not accept new relationships, stop comms per person-canonical-fields.md."
+        },
+        "alias_of": {
+          "type": ["string", "null"],
+          "description": "Canonical person_id when status is merged; null otherwise. Populated by mergePersons, never by this event's update path (status: merged is not a legal update target; merge has its own flow).",
+          "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+        },
+        "given_name": {
+          "type": ["string", "null"],
+          "maxLength": 200
+        },
+        "family_name": {
+          "type": ["string", "null"],
+          "maxLength": 200
+        },
+        "display_name": {
+          "type": ["string", "null"],
+          "description": "When null, consumers fall back to given_name + family_name trimmed per the canonical-fields contract."
+        },
+        "is_minor": {
+          "type": "boolean",
+          "description": "Maintained as a Platform invariant by the daily runIsMinorInvariantJob; a flip from true to false fires its own person.updated."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Wall-clock UTC at row creation."
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Wall-clock UTC at the writeback transaction commit for this update. Consumers MAY compare against their cached updated_at for ordering."
+        }
+      }
+    },
+    "changed_fields": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "The canonical fields that actually changed in this update. Always non-empty; the producer SHALL NOT emit on a no-op patch. Consumers filter handlers on this list (a Sales archive consumer subscribes to person.updated and short-circuits unless changed_fields includes status).",
+      "items": {
+        "type": "string",
+        "enum": [
+          "given_name",
+          "family_name",
+          "display_name",
+          "status",
+          "is_minor"
+        ]
+      }
+    },
+    "prior_status": {
+      "type": ["string", "null"],
+      "enum": ["active", "archived", "merged", null],
+      "description": "The status value before this update, populated only when changed_fields includes status. Null otherwise. Lets archive consumers detect the active to archived transition without a separate fetch."
+    }
+  }
+}

package/contracts/lead-lifecycle/schema/payloads/lead.attempt.exhausted-v1.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lead-lifecycle/schema/payloads/lead.attempt.exhausted-v1.json",
+  "title": "lead.attempt.exhausted payload v1",
+  "description": "Payload for the lead.attempt.exhausted event_type per contracts/lead-lifecycle/README.md §4.5. Emitted by Sales when the cadence's four-attempt cap is hit and the Lead transitions to the 'attempt_exhausted' terminal stage. The event is the explicit-decision artifact required by the coordination/domains/sales.md quality bar ('no Lead sits in the cadence past the four-attempt cap without an explicit decision'). Producer SHALL emit inside the same Prisma transaction that transitions the Lead. lead.stage.changed co-fires from the same transaction with transition_reason: cadence_runtime.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lead_id",
+    "final_attempt_at",
+    "exhausted_at",
+    "attempt_count"
+  ],
+  "properties": {
+    "lead_id": {
+      "type": "string",
+      "description": "The Lead transitioning to attempt_exhausted. lead_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "final_attempt_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp of the last unsuccessful attempt (the one that triggered the exhaustion). UTC."
+    },
+    "exhausted_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the transition fired. Sales' wall-clock at commit. UTC. Typically very close in time to final_attempt_at but distinct in principle."
+    },
+    "attempt_count": {
+      "type": "integer",
+      "description": "Number of attempts at exhaustion. Expected value 4 per the cadence cap in domains/sales.md; the field allows for future cadence-cap changes without a v2 schema bump.",
+      "minimum": 1
+    }
+  }
+}

package/contracts/lead-lifecycle/schema/payloads/lead.callback.scheduled-v1.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lead-lifecycle/schema/payloads/lead.callback.scheduled-v1.json",
+  "title": "lead.callback.scheduled payload v1",
+  "description": "Payload for the lead.callback.scheduled event_type per contracts/lead-lifecycle/README.md §4.4. Emitted by Sales when an operator explicitly schedules a callback for a Lead. Per coordination/domains/sales.md's 'no auto-callback queueing without explicit operator action' rule, this event always carries an operator identity in scheduled_by; system-driven scheduling is not a valid producer path. Producer SHALL emit inside the same Prisma transaction that creates the callback record. If the scheduling also moves the Lead's stage, lead.stage.changed co-fires from the same transaction with transition_reason: operator_action.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lead_id",
+    "scheduled_for",
+    "scheduled_at",
+    "scheduled_by"
+  ],
+  "properties": {
+    "lead_id": {
+      "type": "string",
+      "description": "The Lead the callback is scheduled for. lead_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "scheduled_for": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the callback should happen. Operator-chosen target time, UTC."
+    },
+    "scheduled_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the operator scheduled the callback. Sales' wall-clock at commit. UTC."
+    },
+    "scheduled_by": {
+      "type": "string",
+      "description": "The operator who scheduled the callback. Required per the 'human-driven' framing in domains/sales.md. Sales-internal id format at v1.0.0 (carried as flexible string)."
+    },
+    "notes": {
+      "type": ["string", "null"],
+      "description": "Optional freeform notes attached to the callback by the scheduling operator. Subscribers MUST NOT treat notes as structured data; the field is a human-readable annotation only."
+    }
+  }
+}

package/contracts/lead-lifecycle/schema/payloads/lead.created-v1.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lead-lifecycle/schema/payloads/lead.created-v1.json",
+  "title": "lead.created payload v1",
+  "description": "Payload for the lead.created event_type per contracts/lead-lifecycle/README.md §4.1. Emitted by Sales when a new Lead opens. Two opening cases: from intake.captured (Growth's form-submission event; person_id null until Platform matches identity) or from intake.matched (Platform's Person-attachment event; person_id populated). Reactivations also fire lead.created with reactivated_from populated. Producer SHALL emit inside the same Prisma transaction that creates the Lead row per ADR-0009's producer-transactional-guarantee shape.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lead_id",
+    "source",
+    "stage",
+    "originating_intake_event_id",
+    "created_at"
+  ],
+  "properties": {
+    "lead_id": {
+      "type": "string",
+      "description": "The new Lead's id. lead_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "source": {
+      "type": "string",
+      "description": "The Lead's intake source. Values reflect the source enumeration carried on the originating intake event (e.g., paid_search, organic, referral, partner_upload, subscriber_promotion, manual_capture, derived_match, reactivation). Flexible string at v1.0.0; tightening to a closed enum is a v1.1 candidate per §8 of the contract."
+    },
+    "stage": {
+      "type": "string",
+      "description": "Initial stage of the Lead. Typically 'new' for fresh intake-driven creations and 'pending_match' for intake.captured cases waiting on Platform's match. Flexible string at v1.0.0; tightening to a closed enum is a v1.1 candidate per §8 of the contract."
+    },
+    "person_id": {
+      "type": ["string", "null"],
+      "description": "The canonical Person this Lead attaches to. Null until Platform matches identity via intake.matched per ADR-0003 and the Identity Contract. per_<UUID v7 canonical>.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "originating_intake_event_id": {
+      "type": "string",
+      "description": "Correlation back to the intake event (intake.captured or intake.matched) that opened this Lead. evt_<UUID v7 canonical> per the event-envelope contract.",
+      "pattern": "^evt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "reactivated_from": {
+      "type": ["string", "null"],
+      "description": "If this Lead is a reactivation per 2026-05-02-growth-sales-lead-reactivation-confirmed, points at the prior Lead's id. Null for fresh-intake Leads. lead_<UUID v7 canonical>.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the Lead opened. Sales' wall-clock at the moment the Lead row committed. UTC."
+    }
+  }
+}

package/contracts/lead-lifecycle/schema/payloads/lead.reached-v1.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lead-lifecycle/schema/payloads/lead.reached-v1.json",
+  "title": "lead.reached payload v1",
+  "description": "Payload for the lead.reached event_type per contracts/lead-lifecycle/README.md §4.3. Emitted by Sales when an outbound call attempt connects to a real conversation with the Person (or with an authorized Guardian per the comms-routing rule in coordination/domains/sales.md). Voicemail, busy signal, no-answer, and disconnected number do NOT fire this event; they increment the cadence counter without producing lead.reached. Producer SHALL emit inside the same Prisma transaction that records the reach in the Lead's reach history.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lead_id",
+    "attempt_number",
+    "reached_at"
+  ],
+  "properties": {
+    "lead_id": {
+      "type": "string",
+      "description": "The Lead reached. lead_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "attempt_number": {
+      "type": "integer",
+      "description": "Which attempt out of the four-attempt cap connected. 1-indexed.",
+      "minimum": 1,
+      "maximum": 4
+    },
+    "reached_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the call connected. Sales' wall-clock at the moment the reach was recorded. UTC."
+    },
+    "outcome": {
+      "type": ["string", "null"],
+      "description": "Post-reach disposition. Examples include 'qualified', 'callback_requested', 'not_interested', 'wrong_number', 'guardian_only', 'other'. Flexible string at v1.0.0; tightening to a closed enum is a v1.1 candidate per §8 of the contract once the disposition taxonomy stabilizes in production."
+    },
+    "operator_id": {
+      "type": ["string", "null"],
+      "description": "The operator who made the call. Sales-internal id format at v1.0.0 (carried as flexible string). Null only if the reach was recorded without operator attribution, which SHOULD be a rare path."
+    }
+  }
+}

package/contracts/lead-lifecycle/schema/payloads/lead.stage.changed-v1.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lead-lifecycle/schema/payloads/lead.stage.changed-v1.json",
+  "title": "lead.stage.changed payload v1",
+  "description": "Payload for the lead.stage.changed event_type per contracts/lead-lifecycle/README.md §4.2. Emitted by Sales on every Lead stage transition. The broad state-transition event; subscribers tracking stage progression read this rather than synthesizing it from the specialized events (lead.reached, lead.callback.scheduled, lead.attempt.exhausted), each of which may co-fire alongside lead.stage.changed when both apply. Producer SHALL emit inside the same Prisma transaction that updates the Lead row.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lead_id",
+    "from_stage",
+    "to_stage",
+    "transition_reason",
+    "transition_at"
+  ],
+  "properties": {
+    "lead_id": {
+      "type": "string",
+      "description": "The Lead transitioning. lead_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "from_stage": {
+      "type": "string",
+      "description": "The Lead's stage before the transition. Flexible string at v1.0.0 (Sales' stage taxonomy is open-ended at this version); examples include 'new', 'pending_match', 'qualified', 'callback_scheduled', 'attempt_exhausted', 'handed_off'. Tightening to a closed enum is a v1.1 candidate per §8 of the contract."
+    },
+    "to_stage": {
+      "type": "string",
+      "description": "The Lead's stage after the transition. Flexible string at v1.0.0; same value space as from_stage."
+    },
+    "transition_reason": {
+      "type": "string",
+      "enum": ["operator_action", "cadence_runtime", "inbound_event"],
+      "description": "What drove the transition. 'operator_action' for human-driven (qualifying, scheduling a callback, etc.); 'cadence_runtime' for Sales' cadence runtime (incrementing attempt count, hitting the four-attempt cap); 'inbound_event' for transitions driven by a subscribed event (customer.handoff arriving and closing the Lead, intake.matched arriving with person_id)."
+    },
+    "transition_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the transition fired. Sales' wall-clock at commit. UTC."
+    },
+    "transitioned_by": {
+      "type": ["string", "null"],
+      "description": "Operator identity when transition_reason is 'operator_action'. Null for system-driven transitions ('cadence_runtime' and 'inbound_event'). Operator id format is Sales-internal at v1.0.0 (carried as flexible string)."
+    }
+  }
+}

package/contracts/payment-flow/schema/payloads/payment.failed-v1.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/payment-flow/schema/payloads/payment.failed-v1.json",
+  "title": "payment.failed payload v1",
+  "description": "Payload for the payment.failed event_type per contracts/payment-flow/README.md §4.2. 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. Producer SHALL emit inside the same Prisma transaction as the external-actions row insert per ADR-0009. Subscribers: Sales (Lead reactivation routing differs by failure cause), Growth (funnel attribution), platform-warehouse. Delivery does not subscribe at v1; the order's status is unchanged so no Delivery-visible state changes.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "order_id",
+    "person_id",
+    "payment_method",
+    "payment_path",
+    "amount_cents",
+    "currency",
+    "provider_ref",
+    "failed_at",
+    "failure_code",
+    "failure_reason"
+  ],
+  "properties": {
+    "order_id": {
+      "type": "string",
+      "description": "The Revenue-owned Order the failed payment was attempted against. ord_<UUID v7>.",
+      "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 Person whose payment attempt failed. per_<UUID v7>.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "payment_method": {
+      "type": "string",
+      "description": "Payment method attempted per §4.3.",
+      "enum": [
+        "card",
+        "ach",
+        "cash",
+        "check",
+        "credit_balance"
+      ]
+    },
+    "payment_path": {
+      "type": "string",
+      "description": "Writeback path per §4.1.",
+      "enum": [
+        "invoice_paid",
+        "active_charge"
+      ]
+    },
+    "amount_cents": {
+      "type": "integer",
+      "description": "Amount of the attempted payment in the smallest currency unit.",
+      "minimum": 1
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO-4217 currency code.",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "provider_ref": {
+      "type": "string",
+      "description": "Provider-side identifier for the failed attempt. Square payment id for paths that reached the provider; external-actions row id (ext_ prefix) for paths that failed before the provider call.",
+      "minLength": 1
+    },
+    "failed_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC timestamp at the writeback transaction commit. Producer's clock."
+    },
+    "failure_code": {
+      "type": "string",
+      "description": "Failure cause per §4.4. Consumers route on this field; consumers SHALL treat unknown values as safe-to-ignore per §8. Phase-2 narrowing may add values without a major version bump.",
+      "enum": [
+        "card_declined",
+        "insufficient_funds",
+        "expired_card",
+        "network_error",
+        "provider_unavailable",
+        "other"
+      ]
+    },
+    "failure_reason": {
+      "type": "string",
+      "description": "Free-form provider-side message. Consumers SHALL NOT parse this field; the format is provider-specific and may change without contract bump. Use failure_code for routing.",
+      "minLength": 1
+    }
+  }
+}

package/contracts/payment-flow/schema/payloads/payment.received-v1.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/payment-flow/schema/payloads/payment.received-v1.json",
+  "title": "payment.received payload v1",
+  "description": "Payload for the payment.received event_type per contracts/payment-flow/README.md §4.1. Emitted by Revenue at the writeback transaction commit for a successful payment. Producer SHALL emit inside the same Prisma transaction as the order-status update per ADR-0009. Subscribers: Sales (Lead reactivation close), Growth (funnel-close attribution), Delivery (awareness of credit availability), platform-warehouse.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "order_id",
+    "person_id",
+    "payment_method",
+    "payment_path",
+    "amount_cents",
+    "currency",
+    "provider_ref",
+    "received_at"
+  ],
+  "properties": {
+    "order_id": {
+      "type": "string",
+      "description": "The Revenue-owned Order this payment satisfies. ord_<UUID v7>.",
+      "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 Person who paid. Sourced from the Order's client per the Identity canonical surface. per_<UUID v7>.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "payment_method": {
+      "type": "string",
+      "description": "Payment method per §4.3. Consumers SHALL treat unknown values as safe-to-ignore per §8.",
+      "enum": [
+        "card",
+        "ach",
+        "cash",
+        "check",
+        "credit_balance"
+      ]
+    },
+    "payment_path": {
+      "type": "string",
+      "description": "Writeback path per §4.1. invoice_paid for the asynchronous webhook-driven path through runApplyInvoicePayment; active_charge for the synchronous path through runChargeOrder.",
+      "enum": [
+        "invoice_paid",
+        "active_charge"
+      ]
+    },
+    "amount_cents": {
+      "type": "integer",
+      "description": "Amount of the payment in the smallest currency unit (cents for USD).",
+      "minimum": 1
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO-4217 currency code. USD at v1 in production.",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "provider_ref": {
+      "type": "string",
+      "description": "Provider-side identifier for the payment per the funding-state external-reference rule. Square payment id for card/ach paths (sqpay_<id>); external-actions row id prefixed with ext_ for cash/check/credit_balance paths.",
+      "minLength": 1
+    },
+    "received_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC timestamp at the writeback transaction commit. Producer's clock."
+    }
+  }
+}