# 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:

1. **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.
2. **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` (where `platform.api` lives)