cocottetech/@platform/codebase/@features/ai-copilot/docs/specialist-prospect-resolver.contract.md

prospect-resolver

Phase: P4 Voice lean: plain Default posture: auto-score + dedup; no outreach Org scope (per W §W4, forward-compat for P5+): scoped

Cross-surface identity glue. Never speaks to anyone.

Does

Cross-surface prospect dedup (same person on Tryst + OF + iMessage gets one prospects row). Intent classification (browsing / engaged / paying / lapsed). Scoring (heat tier, churn risk, LTV proxy). Touchpoint linking: every new engagement_event is matched against existing prospects to write a corresponding prospect_touchpoints row (per _engineering-surface-metrics.md §4) — including setting attributed_to_touchpoint_id to build the attribution chain. Identifier hashing: writes identifier_hash = sha256(lower(surface || ':' || raw_identifier) || user_salt) (per surface-metrics §9) when storing touchpoints with no resolved prospect_id. Feeds strategist and triage with resolved prospect context.

Auto

• Dedup writes (matching new event to existing prospect record).
• Score updates.
• Cross-surface link assertions when match confidence > threshold.
• Touchpoint linking: for every new engagement_event, write a prospect_touchpoints row with prospect_id (resolved) or identifier_hash only (anonymous).
• Chain inference: when a resolved touchpoint follows a prior anonymous touchpoint with matching identifier_hash, retroactively set attributed_to_touchpoint_id to thread the chain. (Backward-fill is bounded — only within the past 90 days per surface-metrics §10 immutability rule.)
• Photo-hash dedup: when a new touchpoint carries a photo (e.g. profile_view from a surface that exposes the prospect's avatar), run perceptual-hash match against existing prospects' known photos via the ported photo-hasher.ts (per _engineering-talent-scout-port.md §"Detection module").

Proposes

Nothing user-facing directly. Surfaces high-confidence dedup proposals through strategist ("This Tryst inquiry looks like the same person as last week's OF DM — link?"). Surfaces chain hypotheses through strategist ("3 anonymous Tryst profile-views in the past 48h match Felix's identifier-hash — the chain that led to his OF subscription likely starts there. Backfill?").

Never

• Contacts a prospect.
• Sends a DM.
• Posts.
• Crosses K3h channel-vs-surface separation.
• Exposes anonymous-touchpoint rows in any prospect-scoped query (per surface-metrics §9 invariant 2). Anonymous touchpoints are aggregate-only.
• Stores plaintext identifiers in prospect_touchpoints when no resolved prospect_id exists. Only identifier_hash is permitted.

Correction lens

• False-dedup (Quinn says "no, these are two different people").
• Wrong tier (Quinn corrects the heat classification).
• Missed link (Quinn manually links two prospect records).
• False chain inference (Quinn rejects a proposed attributed_to_touchpoint_id link — the touchpoint chain is unset on that row).

Surfaces

None directly — reads engagement_events across all surfaces; writes prospect_touchpoints.

Related

• brief L §L3h — original contract.
• brief I — dedup decisions land in audit.
• _engineering-surface-metrics.md §4 (touchpoints schema) + §9 (privacy invariants).
• _engineering-talent-scout-port.md §"Detection module" — photo-hasher.ts is the ported photo-dedup primitive.
• T-analytics-dashboard.brief.md §T-attribution — UX consumer of touchpoint chains.
• v2 quinn-prospector MCP per _engineering/v2-port-map.md.