5 KiB
5 KiB
specialist-graph-resolver.contract
Subfeature: cross-provider-graph
Tier: P5 (operates above specialist-prospect-resolver)
Tenancy: Per-Person specialist instance; query-scoped to consented network.
API plane: platform.api (black, :3060). New routes prefixed /prospect-graph/*.
Scope
specialist-graph-resolver answers: given a subject-key derived from this Person's specialist-prospect-resolver output, what does the consented network know? It is read-mostly across the network, write-only within its own tenant.
Reads
| Source | Purpose |
|---|---|
prospect_subject_keys (new table, network-shared, anonymised) |
Map provider-local prospect rows → cross-provider subject-key. |
prospect_subject_aggregates (new, network-shared) |
Outcomes histogram, qualification fingerprint, velocity hints per subject-key. |
provider_graph_consents (new) |
Per-Person opt-in state for contribution + query. |
subject_opt_outs (new) |
Tombstone list of subject-keys excluded from all surfaces. |
prospects, prospect_touchpoints (existing, per-tenant) |
Resolve outbound subject-key from local row at query time. |
coop_peer_attestations (from N-provider-coop) |
Surface safety flags inline. |
Writes
| Target | Purpose |
|---|---|
prospect_subject_aggregates |
Append-only contributions on outcome events (booked, blocked, ghosted) for consented subjects. Differentially-private noise applied at contribution time, not query time. |
graph_query_audit (new) |
Every cross-provider query is auditable to both contributing and consuming Person. |
Never list
- Never return raw messages, per-provider conversation excerpts, or any free-text from another provider's tenant.
- Never attribute aggregate signal to a named provider unless that provider opted into attributed contribution for that specific subject-key.
- Never key on un-hashed PII (phone, email, name); always on the hash chain produced by
specialist-prospect-resolver. - Never re-surface signal from a Person who has revoked graph consent (their historical contributions remain in aggregates, but attribution and replay are denied).
- Never auto-merge prospect rows across providers (hard rule per
Y §Y4). - Never export aggregates outside the platform; the graph is a query interface, not a dataset.
Correction lens
The specialist consumes corrections from upstream peer specialists via mcp__quinn-prospector__* (correction-pattern store). Two correction classes:
- Subject-key collisions — provider corrects "this isn't the same person." Specialist down-weights the matching hash dimension for that subject-key and records the correction; if N≥3 providers correct the same collision, the key is split.
- Outcome mislabels — provider corrects "this wasn't a no-show, they rescheduled." Specialist updates the contribution and recomputes the velocity hint.
Inputs (MCP tools / endpoints)
mcp__platform-prospecting__graph_query(subject_key, scope)— returns aggregates + confidence band.mcp__platform-prospecting__graph_contribute(prospect_id, outcome)— emits a contribution event for the local prospect row (idempotent on(provider_id, prospect_id, outcome_version)).mcp__platform-prospecting__graph_consent(person_id, action)— toggle contribution/query consent.mcp__platform-prospecting__subject_opt_out(subject_key)— tombstone a subject (privileged; requires DSR provenance).
All endpoints are routes on platform.api. The MCP tools live under @ai/@skills/platform-prospecting/actions/ (upstream, not vendored here).
Outputs (to peer specialists)
- To
specialist-prospect-resolver: enriched confidence score on row creation. - To
specialist-auto-qualify: qualification fingerprint + outcomes histogram for the matched subject. - To
specialist-warm-intro: network reachability signal (is there a consented peer who has a positive outcome with this subject?). - To
specialist-strategist: aggregated graph-contribution metrics for the dashboard.
Failure modes
| Mode | Behaviour |
|---|---|
| Network partition from black | Specialist degrades to provider-local resolver; logs a degraded-mode breadcrumb (per degraded-mode.flow.md). Never silently returns stale aggregates. |
| Subject erasure mid-query | Query returns "subject opted out" sentinel; no aggregates leak. |
| Consent revoked mid-query | Same sentinel; query is denied for that subject only. |
| Differential-privacy budget exhausted for a subject | Aggregates return with widened confidence band; specialist must surface the band to the consuming copilot. |
Related docs
cross-provider-graph.brief.md(parent)cross-provider-graph.screen.md(web FE)@features/ai-copilot/docs/specialist-prospect-resolver.contract.md(upstream producer)@features/ai-copilot/docs/L-specialists-fleet.brief.md(fleet topology)@features/ai-copilot/docs/I-audit-trust-replay.brief.md(audit semantics)INFRA.md §4(whereplatform.apilives)