@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/identity/person-resolution-semantics.md

@@ -0,0 +1,144 @@
+# Person resolution semantics
+
+**Status:** v1.0.0
+**Date:** 2026-04-24 (initial draft same day as v0.1; amended same day for Lifecycles dissolution; promoted to v1.0.0 same day after three validations passed)
+**Owner:** Platform (identity service)
+**Feeds:** Identity contract v1.0.0 (see `README.md`)
+**Related:** ADR-0002 (Person ID shape), ADR-0003 (Person canonical with role records per domain), person-canonical-fields.md
+
+## Scope
+
+How Platform's identity service decides, for any incoming signal, whether the signal refers to an existing Person or warrants minting a new one. How two Persons merge when they are discovered to be the same human. How consumers resolve references after a merge. This is the section that makes or breaks the identity contract, because wrong rules here either silently merge different humans into the same record (invisible until something breaks) or fragment a single human across duplicates (expensive to clean up later).
+
+Out of scope: business logic for the Lead cadence (lives in Sales), communications routing through Guardian (a Platform identity service endpoint that consumer domains call), role-record field definitions (in each domain's schema).
+
+## Normalization
+
+Every match decision runs against normalized forms, not raw input. Normalization rules:
+
+- **Phone:** E.164 format. Leading `+` and country code required; non-digit characters stripped. `(555) 123-4567` and `555-123-4567` and `5551234567` all normalize to `+15551234567` assuming US default. Intake capture layer is responsible for country-code resolution before the event is published.
+- **Email:** lowercased and whitespace-trimmed. Subaddressing is preserved: `foo+tag@bar.com` is distinct from `foo@bar.com` for match purposes. We do not treat `foo+anything@bar.com` as aliases of `foo@bar.com` because users genuinely distinguish them.
+- **Name:** case-preserved for display. Match uses a normalized form: lowercase, whitespace collapsed to single space, diacritics stripped, common titles and suffixes (Mr, Mrs, Dr, Jr, Sr, I, II, III) removed. Match is exact-on-normalized-form in v0.1; fuzzy scoring is out of scope for v1 and can be added additively to Tier 2 later.
+
+## Minting rule
+
+A canonical Person is minted when a signal arrives that does not auto-match an existing Person AND the signal includes a phone number. Phone is required; email alone is not sufficient. Email-only signals (newsletter subscribers, content-marketing sign-ups) do not mint a canonical Person; they live in a Growth-owned subscriber store until the contact provides a phone and enters the intake funnel.
+
+## Match decision tiers
+
+Every incoming signal runs through a three-tier decision.
+
+### Tier 1: Auto-match
+
+The signal attaches to an existing Person without human review. Auto-match triggers:
+
+- Exact match on phone AND compatible name (either an exact match on normalized family name, an exact match on normalized given name, or at least one side has both names null). Null-on-both-sides counts as compatible for this purpose.
+- Exact match on phone AND email simultaneously, regardless of name.
+- Exact match on an external provider ID (Square customer ID, etc.) that is already linked to a canonical Person via a Client Externals row.
+
+### Tier 2: Manual review
+
+The signal goes to a review queue surfaced by Platform's identity service. The queue is worked by operators in the consumer domain that surfaced the signal: Sales operators handle reviews triggered by intake or lead activity, Delivery operators handle reviews triggered by customer-side activity (manual entry, external-provider sync). A human decides whether to mint new, attach to existing, or trigger a merge. Manual review triggers:
+
+- Phone match but incompatible name (possible sibling sharing a household phone, possible phone reuse over time, or possible typo requiring merge).
+- Email match without phone match.
+- Name match (exact normalized) without phone or email match.
+- External provider ID match that does not resolve to a canonical Person (data-integrity edge case).
+
+### Tier 3: Mint new
+
+No signals match. A fresh Person is minted per the minting rule (phone required, ADR-0002 ID shape, status `active`, name fields nullable).
+
+## Merge workflow
+
+When two Person records are confirmed to be the same human, one becomes canonical and the other becomes an alias. Confirmation comes from manual review, from an ops-initiated correction, or from a Tier 1 auto-match that surfaces a pre-existing duplicate.
+
+### Canonical selection
+
+The Person with the oldest `created_at` wins. This is mechanical and non-negotiable; no tiebreakers required because `created_at` has sub-second resolution. Oldest wins because tenure, cohort, and funnel analytics all depend on the earliest capture date for the human, and promoting fresher data into the older record preserves that earliest date without losing information.
+
+### Field promotion
+
+Non-null fields on the canonical (older) record are preserved as-is. Null fields on the canonical are populated from the non-canonical record if that record has a value. Example: older Person has phone but null given_name; newer Person has phone plus given_name "Jamie"; after merge, the canonical record has phone plus given_name "Jamie". If both records have non-null values for the same field and they differ, the canonical's value wins and the merge log records the discarded value for audit.
+
+### Role record reconciliation
+
+- **Lead records (Sales):** union. Both Persons' Lead records attach to the canonical. Multiple Leads per Person is expected per ADR-0003 and preserves multi-touch acquisition history for Growth reporting.
+- **Participant records (Delivery):** per-Organization uniqueness applies. If both Persons hold a Participant in the same Organization, the Participant with the oldest `created_at` wins; the other archives with an `alias_of` pointer to the surviving Participant and emits `participant.merged`. If the Persons' Participants are in different Organizations, union.
+- **Coach records (Delivery):** same rule as Participant.
+- **Guardian relationships (Platform identity service):** union. If A was guardian of X, and A merges into B, B is now guardian of X. If A was the ward of Y, and A merges into B, B is the ward of Y.
+- **Client Externals rows (external provider links):** union, keyed by provider. If both Persons have a Client Externals row pointing to Square (same provider), the case is rare and requires manual resolution because Square itself does not know the two external IDs refer to one human. Flag, do not auto-resolve.
+
+### ID and status changes on merge
+
+- Non-canonical Person: `status` transitions to `merged`, `alias_of` populated with the canonical `person_id`.
+- Canonical Person: `updated_at` bumped; any promoted fields applied.
+- Events: `person.merged` emitted carrying `old_person_id`, `canonical_person_id`, `reason_code` (one of: `auto-phone-plus-email`, `auto-external-id`, `manual-operator-confirmed`, `ops-correction`), and the full merge context (promoted fields, archived role records).
+
+### Merge is not reversible
+
+If a merge is wrong, the remedy is to mint a new Person and manually reattach role records. We do not carry bidirectional merge state, because supporting un-merge would force every consumer to handle a reverse of every merge event, which is complexity without a clear benefit at Sguild's scale. Manual cleanup is expensive per incident but cheap overall because the error rate is low when Tier 2 review is strict.
+
+### Chained merges
+
+When a canonical Person is later merged into a third Person, the earliest Person's `alias_of` is updated to point at the terminal canonical. Consumers resolving a lookup on any merged ID reach the current canonical in a single hop, not through a chain. The `person.merged` event for the second merge includes the updated aliases in its payload so consumers can reconcile all affected references in one pass.
+
+## Consumer resolution protocol
+
+When a consumer looks up a Person by `person_id`:
+
+1. If the record has `status='merged'`, the Platform identity service API returns the canonical record (at `alias_of`) with the queried ID surfaced as an alias in the response.
+2. The consumer is expected to update its stored reference to the canonical `person_id` going forward. Leaving stale references in place is permitted in the short term (the API continues to resolve them), but accumulation of stale references across the four domains is a drift signal that surfaces in the contract-currency metric.
+3. `person.merged` events are the proactive reconciliation path: consumers subscribing to them can update references without waiting for a lookup to force it.
+
+## Specific cases
+
+### Lead converts to active customer
+
+Not a resolution problem. A Lead's pipeline state transitions inside Sales as the human progresses (qualified, scheduled, paid). The Sales-to-Delivery handoff fires when the first credit reservation lock confirms (`customer.handoff` event); Delivery begins owning the relationship at that moment. The Person record itself does not change; it gains an Delivery-internal customer-tracking record on handoff. No merge or identity work is required.
+
+### Coach is also a Customer
+
+Same Person, multiple role records simultaneously: Coach (Delivery, scoped per Org), possibly Participant (Delivery, scoped per Org) if the coach also takes lessons, Guardian relationships (Platform) if they have children in the program, plus implicit customer status by virtue of having Revenue records (Credit Account, Order, Invoice) keyed by `person_id`. ADR-0003 specifies this is supported and expected. No merge is needed; resolution ensures all signals pointing at this human route to the same `person_id`.
+
+### Two Leads turn out to be the same human
+
+Discovery path: two intakes months apart, same phone, incompatible names (typo, form filled differently by the same person, or partner filling out the form on their behalf). Tier 2 review flags the conflict; operator confirms same human and triggers merge. Both Lead records attach to the canonical Person, preserving multi-touch acquisition history for Growth's cost-per-conversion reporting.
+
+## Edge cases
+
+### Household phone shared across family members
+
+Common at Sguild. First intake mints Person A with the household phone. A second intake with the same phone but a different name drops into Tier 2 manual review. The operator either mints a new Person (sibling, with a Guardian relationship to the parent Person) or attaches to the existing Person (same human, different name variant). This friction is intentional because silent auto-merge across family members is the worst failure mode in this domain.
+
+### Phone number reuse over time
+
+Carrier reassigns a phone from Person A to Person B months or years later. Sguild does not attempt to auto-detect this. The case surfaces when B's intake hits Tier 2 (phone match, incompatible name). Operator recognizes the situation, mints a new Person for B; the old phone value on A is cleared or marked historical via a manual identity-service correction.
+
+### Anonymous intake with phone only
+
+Phone is required for mint; name is nullable. A Person exists with display_name null until intake cadence or subsequent contact fills in the name. Rendering consumers fall back to a placeholder ("Unknown (+15551234567)" or similar) until name is known.
+
+### Double-submission within a short window
+
+Two intake submissions from the same phone in a few minutes (double-click, two browser tabs, form retry after network error). This is deduped at the Growth form layer by the tuple (phone, form_id, submission window). Platform's identity service sees a single `intake.captured` event and does not need a resolution decision.
+
+### External-provider ID match without canonical link
+
+Square customer ID appears in a signal and matches a Client Externals row that is NOT linked to a canonical Person (data-integrity lag or prior bug). Tier 2 review. Operator establishes or corrects the link, then proceeds with the rest of the resolution.
+
+## Versioning
+
+Resolution rules are Platform-internal and can evolve freely; they are not part of the identity contract surface. What IS in the contract and follows its versioning discipline:
+
+- `alias_of` field semantics (additive-only within v1)
+- `person.merged` event shape and reason codes (additive for new reason codes; removal requires v2)
+- The consumer resolution protocol (behavior of the Platform identity service API when `status='merged'`)
+
+Changes to Tier 1 / Tier 2 / Tier 3 thresholds, addition of fuzzy matching, changes to normalization rules, or changes to the field-promotion logic are internal improvements and do not trigger contract version bumps.
+
+## Out of scope for v0.1
+
+- **Fuzzy name matching with a confidence score.** V1 is exact-on-normalized-form. Fuzzy matching can be added to Tier 2 in v1.x additively without changing the contract.
+- **Cross-tenant resolution.** Sguild is single-tenant today per ADR-0001. When tenant two arrives, resolution scope will need to be explicitly tenant-bounded; the implementation today does not need to handle the case but should accept `tenant_id` on every resolution call for forward-compatibility.
+- **Background merge job.** Periodic batch detection of duplicates that slipped through intake-time Tier 1 (e.g., a Person whose email was added later and now matches an older Person's email). Deferred to v1.x. Manual operator-initiated merge is the only path in v0.1.

package/contracts/identity/person-role-taxonomy.md

@@ -0,0 +1,120 @@
+# Person role taxonomy
+
+**Status:** v1.0.0
+**Date:** 2026-05-12
+**Owner:** Platform (identity service)
+**Feeds:** Identity contract v1.0.0 (see `README.md`)
+**Related:** ADR-0003 (Person as canonical entity with role records per domain), `person-canonical-fields.md`
+
+## Scope
+
+This document enumerates the **roles** a Person can hold across Sguild's domains and defines the closed taxonomy that the `role.assigned` and `role.retired` event types carry. It is the source-of-truth list that Platform's `person_role` projection consumes; producers SHALL emit only the role values listed here.
+
+A Person's role is the relationship that Person holds with a specific domain entity. The same human, represented by one canonical Person, can hold many roles simultaneously (a Coach who is also a Customer who used to be a Lead). Each role's lifecycle is owned by the domain whose entities back that role; Platform aggregates the projection but does not author the underlying state transitions.
+
+This document answers "what kinds of relationships does the org track between Persons and domain entities, and who owns each one." It does not answer "what stage is this Lead in" or "what does this Coach charge per hour" — those are domain-internal questions on the role-bearing entity.
+
+## Role enum
+
+Closed set. Adding a new role is a v1.x minor change per envelope contract §8.1; producers SHALL NOT emit values outside this set without a contract bump.
+
+### lead
+
+- **Source domain:** sales
+- **Source entity:** `sales.Lead`
+- **Assigned at:** Lead row creation (`Lead.createdAt`)
+- **Retired at:** Lead reaches a terminal stage (`lost`, `won`, or `archived` per Sales' lifecycle)
+- **Meaning:** This Person is currently being nurtured by Sales toward conversion. The role exists for the lifetime of the Lead entity in non-terminal stages.
+- **Multiplicity:** A Person can hold the `lead` role multiple times across history (each historical Lead row is its own retire/assign cycle), but only one `lead` row in the projection is active at a time per Lead entity. ADR-0003 acknowledges one Person may have many Leads over time; the projection holds them all keyed by `source_entity_id`.
+
+### customer
+
+- **Source domain:** revenue
+- **Source entity:** `revenue.credit_account` (or the canonical Customer record once Revenue's Customer migration lands)
+- **Assigned at:** First successful `credit.purchased` event for this Person
+- **Retired at:** `customer` role is sticky — once a Person has paid for credits, they are a Customer in perpetuity. Retirement reserved for compliance scenarios (right-to-be-forgotten requests, fraud reversals) and writes a `role.retired` event with `reason = 'compliance_purge'`.
+- **Meaning:** This Person has a paying economic relationship with Sguild. Used by Growth (to suppress acquisition-target cohorts), Sales (to know not to treat as a fresh Lead), and analytics (cohort definitions).
+- **Multiplicity:** One per Person. Re-purchase by an already-Customer Person does not emit a new `role.assigned`.
+
+### student
+
+- **Source domain:** delivery
+- **Source entity:** `delivery.participant`
+- **Assigned at:** First `participant` row created linking this Person to a coaching engagement
+- **Retired at:** `participant` row deactivates (lifecycle ends, customer churns out of active scheduling)
+- **Meaning:** This Person is actively receiving lessons. Distinct from Customer (who paid) and Lead (who is being courted); Student is the operational engagement state.
+- **Multiplicity:** One per Person at a time. A Person who churns and returns gets a new `participant` row and a fresh `role.assigned` cycle.
+- **Source map (2026-05-11 Delivery clarification):** Participant is the Student source per `2026-05-11-delivery-person-role-filter-source-map`.
+
+### coach
+
+- **Source domain:** coaching
+- **Source entity:** `coaching.coach`
+- **Assigned at:** Coach row transitions to `status = 'active'` (from `candidate` or `onboarding`)
+- **Retired at:** Coach row transitions to `status = 'retired'` or `status = 'inactive'`
+- **Meaning:** This Person is currently delivering coaching services. Coach lifecycle is Coaching-owned per ADR-0008; Platform mirrors the assignment state via the role event.
+- **Multiplicity:** One per Person. Coaches can re-activate (retire → re-onboard) which produces a new assign/retire cycle.
+
+### guardian
+
+- **Source domain:** platform (self-owned; no cross-domain emit needed)
+- **Source entity:** `platform.guardian`
+- **Assigned at:** `establishGuardianRelationship` is called
+- **Retired at:** `terminateGuardianRelationship` is called
+- **Meaning:** This Person is the legal/operational guardian of another Person (typically a minor). Drives comms routing through `getCommsRoutingTarget`. Platform writes its own projection entry in-process — no webhook fanout to itself for this role; the in-process write happens in the same transaction as the `guardian` row insert.
+- **Multiplicity:** A Person can be guardian of multiple wards; each ward relationship is its own `person_role` row with `source_entity_id = <guardian row id>` and `metadata = { ward_person_id }`.
+
+### operator
+
+- **Source domain:** platform (self-owned via Better-Auth)
+- **Source entity:** `platform.member` (the Better-Auth membership row joining a user to an organization)
+- **Assigned at:** Member row is created for a Person linked to a Sguild-internal Organization
+- **Retired at:** Member row is deleted or role downgraded out of operator-class roles
+- **Meaning:** This Person is internal Sguild staff with operator-tier access to one of Sguild's tools. Drives auth/admin visibility decisions in the Identity Console and the per-domain operator surfaces.
+- **Multiplicity:** A Person can be an operator for multiple orgs; each member row is its own row.
+
+## Lifecycle invariants
+
+- **Assignment is producer-transactional.** A `role.assigned` event SHALL be emitted in the same Prisma transaction as the underlying entity write that created the role-bearing relationship. Per ADR-0009 producer-transactional-guarantee.
+- **Retirement is producer-transactional.** Same rule for `role.retired`.
+- **Idempotent at the projection.** Platform's `person_role` table uses `(person_id, role, source_entity_id)` as the unique key. Re-delivery of `role.assigned` upserts the row; re-delivery of `role.retired` is a no-op if `retired_at` is already populated.
+- **The projection is eventually consistent.** Cursor lag and inbox dedup live between producer commit and projection read. Operator-visible lag in v1 is bounded by the dispatcher's 5-second polling cadence plus webhook RTT — typically sub-2-second per tonight's verified end-to-end timing on `person.updated`.
+- **Roles do not cascade.** Archiving a Person via `person.updated` does NOT automatically retire all their roles. Each producing domain decides whether to retire its role in response to a Person archive (Sales does — pauses Lead + emits `role.retired`; Coaching does — moves Coach to inactive + emits `role.retired`; Revenue does not — Customer is sticky).
+
+## Read API
+
+Platform exposes `GET /api/identity/v1/person/<person_id>/roles` returning the current active roles for a Person:
+
+```json
+{
+  "person_id": "per_019e1957-...",
+  "roles": [
+    {
+      "role": "lead",
+      "source_domain": "sales",
+      "source_entity_id": "led_019e1...",
+      "effective_at": "2026-05-10T14:23:11Z",
+      "metadata": null
+    },
+    {
+      "role": "customer",
+      "source_domain": "revenue",
+      "source_entity_id": "cac_019e1...",
+      "effective_at": "2026-04-12T09:00:00Z",
+      "metadata": null
+    }
+  ]
+}
+```
+
+Filter: `?include_retired=true` returns the full role history including retired rows. Default returns only `retired_at IS NULL` rows.
+
+## Backfill
+
+Each producing domain runs a one-shot script populating Platform's `person_role` table from its current entity state at the moment the projection ships. Backfill bypasses the dispatcher (direct upsert into `platform.person_role`) to avoid replaying historical role-creation events through every downstream consumer. After backfill, the domain enables the `role.assigned` / `role.retired` emit and any future role transitions flow through the event stream.
+
+## Open questions
+
+1. **Student role multiplicity.** Today a Person has at most one active `participant` row. If Delivery later splits Participant into per-org-engagement rows (a Person attending lessons at two service areas concurrently), the projection accommodates multiple active `student` rows because `(person_id, role, source_entity_id)` is the unique key, not `(person_id, role)`. Confirm with Delivery before the Student backfill.
+2. **Customer retirement reasons.** v1 reserves `compliance_purge` as the only retirement reason. If Revenue identifies operational reasons to retire a Customer (long-dormant accounts, account merges), add reason values additively.
+3. **Operator role granularity.** A future Sguild org structure may want sub-roles (operator-readonly, operator-admin, operator-billing). Today the `operator` role is a binary flag; sub-roles would either become separate role values or live in the `metadata` JSON.

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

@@ -82,6 +82,39 @@
           ],
           "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."
+        },
+        "student_age_group": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Submitted age bracket of the prospective student. Flexible string by design; Growth's form defines the enum values it collects (typical values include 'infant', 'toddler', 'preschool', 'early_elementary', 'late_elementary', 'teen', 'adult'). Sales reads this to route to the right cadence + lesson-type recommendation; Platform does NOT redistribute it on the canonical Person (Platform's own age_group enum on Person is identity-resolution-internal). Null when the form omitted the question."
+        },
+        "timeline": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "When the prospect wants to start lessons. Flexible string; typical values include 'asap', 'this_month', 'next_month', 'this_summer', 'this_fall', 'exploring', 'no_rush'. Sales prioritizes cadence sequencing on this signal. Null when the form omitted the question."
+        },
+        "lesson_setting": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Preferred lesson setting / format. Flexible string; typical values include 'group_class', 'semi_private', 'private', 'home_pool', 'facility_pool', 'swim_team'. Drives Sales' service-area + coach matching. Null when the form omitted the question."
+        },
+        "new_qualified": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "enum": [
+            "new",
+            "qualified",
+            null
+          ],
+          "description": "Stage hint for Sales' Lead opener. 'new' means the prospect is a fresh inbound with no prior screening; 'qualified' means upstream pre-screening (partner referral, operator manual capture with vetting, etc.) has confirmed fit and Sales can open the Lead in a later cadence stage. Closed enum: 'new' | 'qualified' | null (null treated as 'new' for back-compat with intakes that don't carry the discriminator)."
         }
       }
     },
@@ -109,6 +142,33 @@
       ],
       "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}$"
+    },
+    "ingestion_mode": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "enum": [
+        "live",
+        "backfill",
+        null
+      ],
+      "description": "How this event entered the system. 'live' = real-time capture from a production intake surface (web form, Meta lead webhook, partner integration). 'backfill' = historical row imported from a prior system (Airtable, exported CSV, replayed event log). Distinct from `source` which describes the original acquisition channel; the same Meta lead can be both source='meta_lead_ad' and ingestion_mode='backfill' if imported retroactively. Null treated as 'live' for back-compat with intakes emitted before this field landed. Producers emitting backfill events SHOULD also backdate `occurred_at` to the original submission timestamp so warehouse week-grouping naturally places historical events in their actual historical weeks."
+    },
+    "qualified_at": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "format": "date-time",
+      "description": "Wall-clock UTC at which this intake was qualified by an upstream process (partner referral marked it qualified, operator manual-capture entered the qualifying note, derived_match algorithm scored it as qualified, etc.). Populated only when submission.new_qualified === 'qualified'; null otherwise. Distinct from envelope.occurred_at (which carries the form-submission timestamp); allows analytics to measure time-to-qualification independent of time-to-capture, and lets Sales prioritize freshly-qualified leads ahead of older-qualified ones even when their original form submission dates differ."
+    },
+    "is_test_data": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "Producer-side test-data discriminator. True when Growth's lead_intake row has is_test_data=true (form-submission-time heuristic match: NANP fictional phones, obvious-test names, internal-IP submits, operator manual flag). Platform's matcher reads this and mints the resulting Person with is_test_data=true so the discriminator propagates downstream to Sales' Lead.is_test_data via intake.matched without each consumer needing to re-run the heuristic. Null treated as false for back-compat. Distinct from ingestion_mode (live vs backfill) — a test intake can be live-captured, and a real customer's intake can be backfilled."
     }
   }
 }

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

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/identity/schema/payloads/intake.matched-v2.json",
+  "title": "intake.matched payload v2",
+  "description": "Payload for the intake.matched event_type at schema_version 2. Platform emits this after running mintOrMatchPerson on an upstream intake.captured envelope. v2 adds a submission_summary block carrying through the operator-relevant fields downstream consumers (primarily Sales) need to open a Lead without a back-lookup against Growth's dispatcher_event. Adding submission_summary is a minor additive change per envelope-contract §8.1; v1 consumers continue to work on the unchanged top-level fields. v1 stays active during a transition window; producers MAY emit at v2 immediately, consumers SHOULD upgrade when they need the submission_summary fields.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenant_id",
+    "person_id",
+    "originating_event_id",
+    "form_submission_id",
+    "match_type",
+    "matched_at"
+  ],
+  "properties": {
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id."
+    },
+    "person_id": {
+      "type": "string",
+      "description": "Canonical Person id resolved by mintOrMatchPerson. per_<UUID v7> per ADR-0002. ALWAYS populated on intake.matched (in contrast with intake.captured where person_id may be null pre-match).",
+      "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_event_id": {
+      "type": "string",
+      "description": "Event id of the intake.captured envelope this matched event corresponds to. Lets consumers correlate back to the captured envelope for fields not forwarded here (dob, full submission, visitor_id, subscriber_row_id).",
+      "pattern": "^evt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "form_submission_id": {
+      "type": "string",
+      "description": "Growth's form_submission id (fsm_<UUID v7>). Same value carried as the envelope subject on intake.captured.",
+      "pattern": "^fsm_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "match_type": {
+      "type": "string",
+      "enum": ["auto_minted", "auto_matched", "manual_review_resolved"],
+      "description": "How Platform resolved the Person. auto_minted = Tier 3 (no phone match; new Person minted). auto_matched = Tier 1 (single phone match; existing Person returned). manual_review_resolved = a Tier 2 multi-match that an operator resolved into a single canonical Person. Sales reads this to decide opening behavior (new mint → open fresh Lead; matched → check for active Leads first)."
+    },
+    "matched_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC when mintOrMatchPerson resolved this Person."
+    },
+    "source": {
+      "type": ["string", "null"],
+      "description": "Growth intake source carried through from the originating intake.captured (website_form, meta_lead_ad, subscriber_promotion, partner_upload, manual_capture, derived_match). Null when the captured event omitted it. Same flexible-string discipline."
+    },
+    "campaign_code": {
+      "type": ["string", "null"],
+      "description": "Growth campaign code carried through from intake.captured. Null when no campaign attribution present."
+    },
+    "landing_url": {
+      "type": ["string", "null"],
+      "description": "Landing URL carried through from intake.captured. Null when unavailable."
+    },
+    "ingestion_mode": {
+      "type": ["string", "null"],
+      "enum": ["live", "backfill", null],
+      "description": "Carried through from intake.captured's ingestion_mode. Sales reads this to branch on backfilled vs live intakes (e.g., don't auto-call a 2-year-old historical Lead). Sales' Lead row stores the bool in `is_backfill` for hot-path filtering; warehouse models filter on the same to keep historical imports out of active-cohort metrics. Null treated as 'live' for back-compat."
+    },
+    "qualified_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Carried through from intake.captured's qualified_at. Populated only when submission_summary.new_qualified === 'qualified'. Distinct from matched_at (when Platform resolved the Person) and occurred_at on the envelope (when the form was originally submitted). Sales stores this in Lead.qualified_at so the operator queue can prioritize by qualification recency without conflating it with form-submission recency or backfill-arrival recency."
+    },
+    "is_test_data": {
+      "type": "boolean",
+      "description": "Snapshot of the resolved Person's is_test_data flag at match time. True for Persons created by automated tests, integration smokes, or operator QA flows (auto-flagged when phone is in the NANP fictional 1-555-0100-XXX block, or operator-flipped via PATCH). Sales stores the value in Lead.is_test_data so downstream Sales-side analytics filter test traffic out of conversion funnels and operator queues without needing to JOIN to Platform's Person table. Distinct from is_backfill (which describes the ingestion path) and from `lead` role analytics (which roll up active relationships); is_test_data describes the underlying human, is_backfill describes how the event arrived, and the lead role describes the Sales relationship state."
+    },
+    "submission_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Operator-relevant snapshot of the form submission, copied from intake.captured at match time so Sales can open a Lead without joining back to Growth's dispatcher_event. Identity-resolution-only fields (dob, email, raw phone display) stay on intake.captured and are NOT forwarded here.",
+      "required": [
+        "first_name",
+        "last_name",
+        "phone_normalized",
+        "zip"
+      ],
+      "properties": {
+        "first_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Submitted given name."
+        },
+        "last_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Submitted family name."
+        },
+        "phone_normalized": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Phone in Platform's normalized form (digits-only, no leading +, US prefix when applicable). Distinct from intake.captured's submission.phone which carries Growth's raw display format. Sales uses this for join-by-phone displays without re-normalizing."
+        },
+        "zip": {
+          "type": "string",
+          "pattern": "^[0-9]{5}$",
+          "description": "Submitted five-digit ZIP code."
+        },
+        "student_age_group": {
+          "type": ["string", "null"],
+          "description": "Submitted age bracket of the prospective student. Carried through from intake.captured's submission.student_age_group. Sales reads this to route to the right cadence + lesson-type recommendation."
+        },
+        "timeline": {
+          "type": ["string", "null"],
+          "description": "When the prospect wants to start lessons. Carried through from intake.captured's submission.timeline. Sales prioritizes cadence sequencing on this signal."
+        },
+        "lesson_setting": {
+          "type": ["string", "null"],
+          "description": "Preferred lesson setting / format. Carried through from intake.captured's submission.lesson_setting. Drives Sales' service-area + coach matching."
+        },
+        "new_qualified": {
+          "type": ["string", "null"],
+          "enum": ["new", "qualified", null],
+          "description": "Stage hint for Sales' Lead opener. Carried through from intake.captured's submission.new_qualified. 'new' opens in fresh cadence; 'qualified' opens in a later stage (pre-vetted partner referrals, operator manual capture). Null treated as 'new' for back-compat."
+        }
+      }
+    }
+  }
+}

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

@@ -26,10 +26,11 @@
         "family_name",
         "display_name",
         "is_minor",
+        "is_test_data",
         "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.",
+      "description": "The full post-update canonical Person, exactly matching the ten-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",
@@ -62,6 +63,10 @@
           "type": "boolean",
           "description": "Maintained as a Platform invariant by the daily runIsMinorInvariantJob; a flip from true to false fires its own person.updated."
         },
+        "is_test_data": {
+          "type": "boolean",
+          "description": "Test-data discriminator. True for Persons created by automated tests, integration smokes, or operator QA flows. Warehouse models filter on this so test traffic never pollutes active-cohort analytics. Distinct from status='archived' (real-customer opt-out). Set automatically at mint when phone is in the NANP fictional 1-555-0100-XXX block; operators flip via the PATCH route otherwise. A flip emits person.updated with changed_fields including 'is_test_data'."
+        },
         "created_at": {
           "type": "string",
           "format": "date-time",
@@ -86,7 +91,8 @@
           "family_name",
           "display_name",
           "status",
-          "is_minor"
+          "is_minor",
+          "is_test_data"
         ]
       }
     },

package/contracts/identity/schema/payloads/role.assigned-v1.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/identity/schema/payloads/role.assigned-v1.json",
+  "title": "role.assigned payload v1",
+  "description": "Payload for the role.assigned event_type at schema_version 1. Emitted by a role-owning producer-domain when a Person gains a role-bearing relationship with one of that domain's entities (Sales opens a Lead, Coaching activates a Coach, Revenue records first purchase, Delivery links a Participant, Platform establishes a Guardian or Operator). Producer SHALL emit inside the same Prisma transaction as the role-bearing entity write per ADR-0009 producer-transactional-guarantee. Platform's person_role projection consumes role.assigned + role.retired and exposes the aggregated role list at GET /api/identity/v1/person/<id>/roles. The closed enum of role values lives in contracts/identity/person-role-taxonomy.md; new values are minor additive contract changes.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenant_id",
+    "person_id",
+    "role",
+    "source_domain",
+    "source_entity_id",
+    "effective_at"
+  ],
+  "properties": {
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id."
+    },
+    "person_id": {
+      "type": "string",
+      "description": "The Person who has gained the role. 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}$"
+    },
+    "role": {
+      "type": "string",
+      "enum": ["lead", "customer", "student", "coach", "guardian", "operator"],
+      "description": "The role being assigned. Closed enum per the person-role-taxonomy contract. Each role's source domain is fixed (Sales owns lead, Coaching owns coach, Revenue owns customer, Delivery owns student, Platform owns guardian + operator). Producers SHALL emit only the role values their domain owns."
+    },
+    "source_domain": {
+      "type": "string",
+      "enum": ["sales", "growth", "delivery", "revenue", "coaching", "platform"],
+      "description": "The producer-domain that emitted this assignment. Matches the envelope's producer field; carried explicitly in the payload so Platform's projection can record source without parsing the envelope."
+    },
+    "source_entity_id": {
+      "type": "string",
+      "description": "The id of the role-bearing entity in the producer-domain (Lead.id, Coach.id, Participant.id, CreditAccount.id, Guardian.id, Member.id). Forms part of the projection's uniqueness key so a Person who has held the same role across multiple historical entities keeps each as a distinct row."
+    },
+    "effective_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC at which the role-bearing relationship became active. Typically equals the entity's createdAt, but producers MAY backdate when the operational meaning differs (e.g., a Lead manually reassigned from another rep keeps its original opening time)."
+    },
+    "metadata": {
+      "type": ["object", "null"],
+      "description": "Free-form domain-specific metadata. Guardian uses this to carry ward_person_id; operator uses this to carry organization_id. Most producers leave it null."
+    }
+  }
+}

package/contracts/identity/schema/payloads/role.retired-v1.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/identity/schema/payloads/role.retired-v1.json",
+  "title": "role.retired payload v1",
+  "description": "Payload for the role.retired event_type at schema_version 1. Emitted by a role-owning producer-domain when a Person's role-bearing relationship terminates (Lead reaches a terminal stage, Coach moves to inactive/retired, Participant lifecycle ends, Guardian relationship is terminated, Member row is deleted). Producer SHALL emit inside the same Prisma transaction as the entity's terminal-state write per ADR-0009 producer-transactional-guarantee. Idempotent: re-delivery of role.retired for an already-retired projection row is a no-op. The customer role is sticky — Revenue emits role.retired only for compliance scenarios (right-to-be-forgotten, fraud reversal).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "tenant_id",
+    "person_id",
+    "role",
+    "source_domain",
+    "source_entity_id",
+    "retired_at"
+  ],
+  "properties": {
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant discriminator. Mirrors the event envelope tenant_id."
+    },
+    "person_id": {
+      "type": "string",
+      "description": "The Person whose role is retiring. 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}$"
+    },
+    "role": {
+      "type": "string",
+      "enum": ["lead", "customer", "student", "coach", "guardian", "operator"],
+      "description": "The role being retired. Must match the role value carried on the prior role.assigned for the same (person_id, source_entity_id) tuple."
+    },
+    "source_domain": {
+      "type": "string",
+      "enum": ["sales", "growth", "delivery", "revenue", "coaching", "platform"],
+      "description": "The producer-domain emitting the retirement. Matches the envelope's producer."
+    },
+    "source_entity_id": {
+      "type": "string",
+      "description": "The id of the role-bearing entity that just retired. Forms the (person_id, role, source_entity_id) key used to locate the projection row to update."
+    },
+    "retired_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Wall-clock UTC at which the role-bearing relationship terminated. Typically the entity's terminal-state-transition timestamp (Lead.lost_at, Coach.retired_at, Participant.deactivated_at, etc.)."
+    },
+    "reason": {
+      "type": ["string", "null"],
+      "description": "Optional free-form reason for the retirement. Used by analytics + by the comms-routing layer when deciding whether to treat a retired role as 'churned' or 'archived'. customer role uses reserved value 'compliance_purge' for right-to-be-forgotten retirements."
+    },
+    "metadata": {
+      "type": ["object", "null"],
+      "description": "Free-form domain-specific metadata at retirement. Most producers leave it null."
+    }
+  }
+}