@sguild/dispatcher 2.0.0

package/contracts/event-types-registry.json

@@ -0,0 +1,541 @@
+{
+  "$schema-self": "Each entry under 'events' maps an event_type to its producer, consumers, and per-schema-version payload schema location. Producers SHALL register every new event_type here before first use per §10.4 of the event-envelope contract. Consumers SHALL handle unknown values gracefully per §9.5. Adding a new event_type or a new schema_version is a minor change on the owning contract per §8.1; this registry is a discovery surface, not a versioning gate.",
+  "$schema-format": {
+    "events": {
+      "<event_type>": {
+        "producer": "<closed-set domain>",
+        "consumers": [
+          "<closed-set domains, or 'platform-warehouse' for the warehouse loader>"
+        ],
+        "owning_contract": "<contracts/<contract>/README.md path>",
+        "schema_versions": [
+          {
+            "version": "<integer, starts at 1>",
+            "payload_schema": "<contracts/<contract>/schema/payloads/<event_type>-v<n>.json path; null if not yet authored>",
+            "status": "<active | deprecated | sunset>",
+            "registered_at": "<YYYY-MM-DD>",
+            "notes": "<optional, human-readable>"
+          }
+        ]
+      }
+    }
+  },
+  "registry_version": "0.1.0-phase-0",
+  "registry_date": "2026-05-02",
+  "registry_owner": "platform",
+  "registry_notes": "Phase 0 of the dispatcher SDK build per memos/2026/2026-05-01-platform-dispatcher-sdk-build-plan. Stood up before the SDK runtime exists; payload_schema paths are populated as Phase 0 authors them and may be null for events that have not yet had a JSON Schema authored. The registry is the single source of truth for which (event_type, schema_version) pairs are valid; the dispatcher SDK reads this manifest at startup to drive validation. CI validation that every emit matches a registered (event_type, schema_version) is a Phase 0 deliverable that lands when the SDK runtime ships.",
+  "events": {
+    "intake.captured": {
+      "producer": "growth",
+      "consumers": [
+        "platform",
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/identity/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": null,
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Form submission with intake metadata (source, campaign, UTM, submission). Phone-bearing or email-bearing. Platform mints/matches; Sales opens a Lead. v2 bundles visitor_id (per cross-device-attribution thread) and source enum extensions for subscriber_promotion/partner_upload/manual_capture/derived_match (per subscriber-promotion thread); both expected before 2026-06-15 Identity Contract v1 ship."
+        },
+        {
+          "version": 2,
+          "payload_schema": "contracts/identity/schema/payloads/intake.captured-v2.json",
+          "status": "active",
+          "registered_at": "2026-05-07",
+          "active_from": "2026-05-07",
+          "notes": "Growth producer emits schema_version=2. v2 carries visitor_id plus source/campaign/submission metadata used by downstream stitching and lead-opening consumers. Payload schema authored 2026-05-07 per 2026-05-01-platform-growth-subscriber-promotion-confirmed."
+        }
+      ]
+    },
+    "intake.amended": {
+      "producer": "growth",
+      "consumers": [
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/identity/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/identity/schema/payloads/intake.amended-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-12",
+          "notes": "Operator-correction event for previously-captured intakes. Emitted by Growth when fields on a lead_intake row change (typo fix, missing zip filled in, refined student_age_group, lesson_setting reclassification, new_qualified upgrade/downgrade). Producer-transactional with the lead_intake update per ADR-0009. Sales updates lead_intake_snapshot in place; phone/email amendments are out of scope at v1 (identity-bearing, require Person merge through Platform). The cross-domain motivation: gives operators a clean fix path for wrong captured data without needing manual cross-DB row editing or breaking event immutability via dispatcher_event payload edits."
+        }
+      ]
+    },
+    "intake.matched": {
+      "producer": "platform",
+      "consumers": [
+        "growth",
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/identity/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": null,
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted after Person mint or match on intake.captured. Carries person_id and the originating event_id (correlation)."
+        }
+      ]
+    },
+    "person.updated": {
+      "producer": "platform",
+      "consumers": [
+        "sales",
+        "growth",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/identity/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/identity/schema/payloads/person.updated-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-11",
+          "notes": "Emitted by Platform's identity service when any canonical Person field changes (status transition, name edits, is_minor flip from the daily invariant job). Carries the full post-update canonical Person, the list of changed_fields, and prior_status when status was among the changes. Subscribers filter on changed_fields to skip noise. Delivery, revenue, and coaching may join the consumer set additively (additive consumer registration is a minor change per envelope contract §8.1); the initial registration covers sales and growth, who need archive-aware behavior on Lead nurture and acquisition messaging respectively, plus the warehouse loader."
+        }
+      ]
+    },
+    "customer.handoff": {
+      "producer": "revenue",
+      "consumers": [
+        "delivery",
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-lock/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/customer.handoff-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Sidecar emission on first credit.locked per Person, per credit-reservation-lock §5. Payload: person_id, first_lesson_id, credit_reservation_id, handoff_at."
+        }
+      ]
+    },
+    "credit.purchased": {
+      "producer": "revenue",
+      "consumers": [
+        "sales",
+        "growth",
+        "delivery",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-lock/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.purchased-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted on Purchase Credit ledger entry per §9.1. Payload: credit_account_id, person_id, purchased_credits, order_id, purchased_at."
+        }
+      ]
+    },
+    "credit.reserved": {
+      "producer": "revenue",
+      "consumers": [
+        "delivery",
+        "coaching",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-lock/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.reserved-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted at scheduling per §9.2. Coaching subscribes per coach-availability §4.3 and ADR-0008."
+        }
+      ]
+    },
+    "credit.funded": {
+      "producer": "revenue",
+      "consumers": [
+        "sales",
+        "delivery"
+      ],
+      "owning_contract": "contracts/credit-reservation-lock/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.funded-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted on funding sub-state flip per §9.3. Coaching does NOT subscribe (§4.3.1 of coach-availability)."
+        }
+      ]
+    },
+    "credit.locked": {
+      "producer": "revenue",
+      "consumers": [
+        "delivery",
+        "sales",
+        "coaching",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-lock/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.locked-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted on T-48h lock per §9.4. customer.handoff sidecar fires on first per Person."
+        }
+      ]
+    },
+    "credit.consumed": {
+      "producer": "revenue",
+      "consumers": [
+        "delivery",
+        "revenue",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-lock/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.consumed-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted at lesson delivery per §9.5. Coaching does NOT subscribe (terminal-past, ages out on a clock)."
+        }
+      ]
+    },
+    "credit.released": {
+      "producer": "revenue",
+      "consumers": [
+        "delivery",
+        "sales",
+        "coaching",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-lock/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.released-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "deprecated_at": "2026-05-22",
+          "notes": "Initial release. Active until the v1.1.0 cutover date 2026-05-22 per the credit-reservation-lock contract §16 changelog. Status flips to deprecated at cutover; v1 consumers continue to work indefinitely per §11 additive-discipline (the new reason_code field on v2 is safe-to-ignore on the v1 surface)."
+        },
+        {
+          "version": 2,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.released-v2.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "active_from": "2026-05-22",
+          "notes": "Adds the required reason_code field per the v1.1.0 amendment landed 2026-05-08 (memos/2026-05-08-revenue-refund-reason-codes-signoff and 2026-05-08-delivery-reason-codes-signoff-accepted). Producers SHALL emit at v2 from 2026-05-22 (v1.0.2 envelope publish date plus 14 days). reason_code is partitioned per §6.1 into auto-release and explicit-operator subsets."
+        }
+      ]
+    },
+    "credit.forfeited": {
+      "producer": "revenue",
+      "consumers": [
+        "delivery",
+        "revenue",
+        "coaching",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-lock/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.forfeited-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted on locked → forfeited per §9.7. Customer-side cancellations only (forfeiture_reason: late_cancel | no_show)."
+        }
+      ]
+    },
+    "lesson.scheduled": {
+      "producer": "delivery",
+      "consumers": [],
+      "owning_contract": null,
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": null,
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted by Delivery when a lesson is scheduled. No cross-domain consumer registered yet; Coaching MAY subscribe in future for assigned-vs-eligible projection enrichment per coach-availability §4.2.1 producer-internal note."
+        }
+      ]
+    },
+    "lesson.attended": {
+      "producer": "delivery",
+      "consumers": [],
+      "owning_contract": null,
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": null,
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted on attendance reconciliation. No cross-domain consumer registered yet."
+        }
+      ]
+    },
+    "lesson.cancelled": {
+      "producer": "delivery",
+      "consumers": [],
+      "owning_contract": null,
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": null,
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted on lesson cancellation by Delivery. The cancellation request to Revenue (which runs the lock state machine) is separate; that submission produces credit.released or credit.forfeited per §6 and §12.4 of the credit-reservation-lock contract, not this event."
+        }
+      ]
+    },
+    "lesson.delivered": {
+      "producer": "delivery",
+      "consumers": [
+        "revenue"
+      ],
+      "owning_contract": null,
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": null,
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted post-delivery, triggers Revenue's Lesson Completion Job per §10 of credit-reservation-lock."
+        }
+      ]
+    },
+    "coach.assigned": {
+      "producer": "delivery",
+      "consumers": [
+        "coaching"
+      ],
+      "owning_contract": "contracts/coach-availability/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": null,
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Single-writer per ADR-0008. Coaching consumes for the assigned-vs-eligible projection enrichment per coach-availability §4.3 prose."
+        }
+      ]
+    },
+    "lead.created": {
+      "producer": "sales",
+      "consumers": [
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/lead-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.created-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-14",
+          "notes": "Emitted by Sales when a new Lead opens per lead-lifecycle §4.1. Two opening cases (from intake.captured with null person_id, or from intake.matched with person_id populated) plus reactivations carrying reactivated_from. Producer-transactional emit per ADR-0009; same Prisma transaction as the Lead row creation."
+        }
+      ]
+    },
+    "lead.stage.changed": {
+      "producer": "sales",
+      "consumers": [
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/lead-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.stage.changed-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-14",
+          "notes": "Broad state-transition event per lead-lifecycle §4.2. transition_reason enum (operator_action | cadence_runtime | inbound_event) identifies what drove the move. May co-fire with lead.reached, lead.callback.scheduled, or lead.attempt.exhausted when both apply. Stage values flexible string at v1.0.0; v1.1 candidate to tighten to a closed enum."
+        }
+      ]
+    },
+    "lead.reached": {
+      "producer": "sales",
+      "consumers": [
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/lead-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.reached-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-14",
+          "notes": "Successful reach event per lead-lifecycle §4.3. Voicemail, busy, no-answer, disconnected do NOT fire this event; only real conversations. attempt_number 1-4 per the cadence cap. outcome flexible string at v1.0.0; v1.1 candidate to tighten."
+        }
+      ]
+    },
+    "lead.callback.scheduled": {
+      "producer": "sales",
+      "consumers": [
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/lead-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.callback.scheduled-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-14",
+          "notes": "Operator-driven callback scheduling per lead-lifecycle §4.4. scheduled_by required (no auto-callback queueing per domains/sales.md). May co-fire with lead.stage.changed when the scheduling moves the Lead's stage."
+        }
+      ]
+    },
+    "lead.attempt.exhausted": {
+      "producer": "sales",
+      "consumers": [
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/lead-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.attempt.exhausted-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-14",
+          "notes": "Cadence-cap-hit terminal-transition event per lead-lifecycle §4.5. Co-fires with lead.stage.changed (transition_reason: cadence_runtime, to_stage: attempt_exhausted). The explicit-decision artifact required by the domains/sales.md quality bar."
+        }
+      ]
+    },
+    "payment.received": {
+      "producer": "revenue",
+      "consumers": [
+        "sales",
+        "growth",
+        "delivery",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/payment-flow/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/payment-flow/schema/payloads/payment.received-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted on writeback transaction commit for a successful payment per payment-flow §4.1. Producer-transactional-guarantee shape from ADR-0009. payment_path field disambiguates invoice_paid vs active_charge."
+        }
+      ]
+    },
+    "payment.failed": {
+      "producer": "revenue",
+      "consumers": [
+        "sales",
+        "growth",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/payment-flow/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/payment-flow/schema/payloads/payment.failed-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted on writeback transaction commit when the provider reports failure per payment-flow §4.2. Order is NOT flipped to PAID. Consumers route on failure_code per §4.4."
+        }
+      ]
+    },
+    "refund.initiated": {
+      "producer": "revenue",
+      "consumers": [
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/refund-flow/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/refund-flow/schema/payloads/refund.initiated-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted at the writeback transaction commit when the Refund record is minted at PENDING per refund-flow §4.1. Producer-transactional-guarantee shape from ADR-0009. Optional cancellation_reason mirrors credit.released v2 reason_code for lock-tied refunds."
+        }
+      ]
+    },
+    "refund.completed": {
+      "producer": "revenue",
+      "consumers": [
+        "sales",
+        "delivery",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/refund-flow/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/refund-flow/schema/payloads/refund.completed-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-02",
+          "notes": "Emitted at the writeback transaction commit when the Square webhook confirms settlement and the Refund Debit ledger entries post per refund-flow §4.2. Delivery subscribes for lock-released invariant verification per the refund-flow rule."
+        }
+      ]
+    },
+    "reservation.funded": {
+      "producer": "revenue",
+      "consumers": [
+        "revenue",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-funding-state/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-funding-state/schema/payloads/reservation.funded-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-05",
+          "notes": "Emitted at the writeback transaction commit when a credit reservation's funding sub-state transitions from pending_funding to funded per credit-reservation-funding-state §4.1. Revenue consumes for reconciliation; platform-warehouse ingests on the funding-event grain."
+        }
+      ]
+    },
+    "reservation.refunding": {
+      "producer": "revenue",
+      "consumers": [
+        "revenue",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-funding-state/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-funding-state/schema/payloads/reservation.refunding-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-05",
+          "notes": "Emitted at the writeback transaction commit when a credit reservation's funding sub-state transitions from funded to refunding per credit-reservation-funding-state §4.2. Paired with refund.initiated when a provider-side refund starts."
+        }
+      ]
+    },
+    "reservation.refunded": {
+      "producer": "revenue",
+      "consumers": [
+        "revenue",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/credit-reservation-funding-state/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/credit-reservation-funding-state/schema/payloads/reservation.refunded-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-05",
+          "notes": "Emitted at the writeback transaction commit when a credit reservation's funding sub-state transitions from refunding to refunded per credit-reservation-funding-state §4.3. Paired with refund.completed when the provider-side refund settles."
+        }
+      ]
+    }
+  }
+}

package/contracts/identity/schema/payloads/intake.amended-v1.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/identity/schema/payloads/intake.amended-v1.json",
+  "title": "intake.amended payload v1",
+  "description": "Payload for the intake.amended event_type at schema_version 1. Emitted by Growth when an operator corrects fields on a previously-captured intake (typo fixes, missing zip, refined student_age_group, lesson_setting reclassification, etc.). Producer-transactional with the lead_intake row update per ADR-0009. Consumers update their snapshot in place: Sales updates lead_intake_snapshot; platform-warehouse projects to the latest-snapshot model. The envelope subject carries the fsm_<UUID v7> form_submission_id and tenant_id mirrors the envelope tenant_id for producer-local validation and downstream warehouse convenience.\n\nIdentity-bearing field amendments (phone, email) are deliberately out of scope at v1. Phone is the identity key per the Identity Contract; changing it via a snapshot-only event would orphan the existing Person attachment. Operators correcting phone numbers SHALL initiate a Person merge through Platform's identity API instead. Email is also restricted at v1 for symmetry — Platform's matcher uses it as a secondary signal and a change here could create a mismatched view between producer snapshot and Platform Person. The changed_fields enum reflects this constraint by omitting phone and email.\n\nProducers SHALL emit intake.amended only when at least one of the enumerated fields actually changed value; the changed_fields array is minItems: 1 and consumers SHALL NOT receive no-op amendments. The submission block carries the FULL post-amendment snapshot (not a diff) so consumers can apply the new shape without joining back to the producer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenant_id",
+    "form_submission_id",
+    "person_id",
+    "amended_at",
+    "changed_fields",
+    "submission"
+  ],
+  "properties": {
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id. Per ADR-0001 this is tenancy, not organization_id."
+    },
+    "form_submission_id": {
+      "type": "string",
+      "pattern": "^fsm_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+      "description": "The intake row being amended. Same id space as the originating intake.captured event's subject and Growth's lead_intake.id."
+    },
+    "person_id": {
+      "type": ["string", "null"],
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+      "description": "Current Person attachment at the time of amendment. Null when the intake is still unmatched. Carried for convenience so consumers can decide whether to also touch identity-derived state without a separate lookup."
+    },
+    "amended_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC at which the amendment was committed on Growth's lead_intake row."
+    },
+    "amended_by": {
+      "type": ["string", "null"],
+      "description": "Operator identity (Growth-internal id at v1.0.0, flexible string). Null for system-driven amendments (e.g., a deduplication job correcting a normalized field across many rows). SHOULD be non-null for operator-initiated UI actions so the audit trail records the human."
+    },
+    "reason": {
+      "type": ["string", "null"],
+      "description": "Free-form operator note explaining the amendment. Carried verbatim into consumers' snapshots for audit. Null when no reason was captured (e.g., system-driven or trivial corrections)."
+    },
+    "changed_fields": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": [
+          "first_name",
+          "last_name",
+          "zip",
+          "dob",
+          "student_age_group",
+          "timeline",
+          "lesson_setting",
+          "new_qualified"
+        ]
+      },
+      "description": "Which fields actually changed value. Closed enum: source/campaign_code/landing_url are immutable provenance and not amendable; phone/email are identity-bearing and out of scope at v1 (see header description). Producers SHALL NOT emit intake.amended when no enumerated field changed."
+    },
+    "submission": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "first_name",
+        "last_name",
+        "phone",
+        "zip"
+      ],
+      "description": "Full post-amendment submission snapshot. Same shape as intake.captured-v2.submission. Carries the new value for every field including those that did not change, so consumers can apply the whole block without joining back to producer state. Phone is required and present (because it was on the original capture) but is not amendable through this event.",
+      "properties": {
+        "first_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Given name after amendment."
+        },
+        "last_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Family name after amendment."
+        },
+        "phone": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Phone number in Growth's normalized display format. Carried for parity with intake.captured-v2 but unchanged from the original capture (phone amendments are out of scope at v1)."
+        },
+        "zip": {
+          "type": "string",
+          "pattern": "^[0-9]{5}$",
+          "description": "Five-digit ZIP code after amendment. The pattern matches intake.captured-v2.submission.zip; producers SHALL coerce / validate before emit so consumers can rely on the constraint."
+        },
+        "email": {
+          "type": ["string", "null"],
+          "format": "email",
+          "description": "Optional email. Carried for snapshot parity; not amendable through this event."
+        },
+        "dob": {
+          "type": ["string", "null"],
+          "format": "date",
+          "description": "Optional date of birth after amendment."
+        },
+        "student_age_group": {
+          "type": ["string", "null"],
+          "description": "Submitted age bracket of the prospective student after amendment. Same flexible-string shape as intake.captured-v2.submission.student_age_group."
+        },
+        "timeline": {
+          "type": ["string", "null"],
+          "description": "When the prospect wants to start lessons, after amendment. Same shape as intake.captured-v2.submission.timeline."
+        },
+        "lesson_setting": {
+          "type": ["string", "null"],
+          "description": "Preferred lesson setting / format after amendment. Same shape as intake.captured-v2.submission.lesson_setting."
+        },
+        "new_qualified": {
+          "type": ["string", "null"],
+          "enum": ["new", "qualified", null],
+          "description": "Stage hint after amendment. Same closed enum as intake.captured-v2.submission.new_qualified."
+        }
+      }
+    }
+  }
+}