# Research consent and access

## Principles

Access to another person's conversation data is granted by that person, for a
stated purpose, at a stated scope, for a stated period, and can be withdrawn at
any moment. Nothing about the system's design should make withdrawal feel
theoretical.

## Grants

```bash
curl -X POST "$BASE/api/v1/threads/$THREAD/grants" \
  -H "Authorization: Bearer $OWNER_TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "researcherId": "researcher-1",
    "projectId": "irb_2026_114",
    "scopes": ["aggregate_metrics", "turn_metrics", "speech_acts", "iccc_curves"],
    "consentVersion": "consent-2026-01",
    "purpose": "Dialogue-repair coding study, IRB 2026-114",
    "expiresAt": "2026-12-31T23:59:59.000Z"
  }'
```

Only the data owner may create a grant. Every grant records who created it, the
consent version it was given under, and its purpose.

## Scopes

Grant the narrowest set that answers the research question.

| Scope | Grants |
|---|---|
| `aggregate_metrics` | Thread-level production, participation, trajectory |
| `turn_metrics` | Per-participant summaries and the latency regression |
| `timestamps` | Timing fields and latency distributions |
| `token_usage` | Provider usage, model and provider |
| `speech_acts` | Classified acts |
| `pseudonymized_text` | Text with emails, phone numbers and URLs masked |
| `raw_text` | Verbatim contribution text |
| `lcc_curves` | RN/RO/IN/IO and R/N |
| `lcc_expectation_matches` | Expectation-level evidence |
| `lcc_misconception_matches` | Misconception-level evidence |
| `iccc_curves` | The six measures |
| `iccc_contribution_scores` | Contribution-level evidence identifiers |
| `semantic_units` | Extracted units |
| `semantic_representations` | Embeddings |
| `export` | Bulk export of the permitted fields |

Two rules deserve emphasis. **Access to a curve never implies access to the
embedding behind it** — `semantic_representations` is separate because an
embedding carries far more than the number derived from it. And **a curve scope
never exposes the LCC reference model**, which is proprietary instructional
content belonging to its author rather than to the thread.

## Revocation

```bash
curl -X DELETE "$BASE/api/v1/threads/$THREAD/grants/$GRANT" -H "Authorization: Bearer $OWNER_TOKEN"
```

Effective on the researcher's next request. No grace period, no cached decision.
The integration test suite asserts this directly.

## Transparency

Owners can list every grant on a thread and read the full access history:

```bash
curl "$BASE/api/v1/threads/$THREAD/grants"          -H "Authorization: Bearer $OWNER_TOKEN"
curl "$BASE/api/v1/threads/$THREAD/access-history"  -H "Authorization: Bearer $OWNER_TOKEN"
```

Every research read and export is audited, including denials — a denied attempt
is often more informative than an allowed one.

## Multi-party threads

Version 1 assumes one primary human data owner per owner-scoped thread. In a
multi-human discussion each human remains a data subject. **One participant's
ownership is not consent to disclose another participant's private data**, and
if your study involves multi-party threads your consent process must cover every
human in them. Participant-level consent metadata is stored so a multi-owner
policy can be added later without changing analytical identifiers.

## What the data will and will not support

The measures describe interaction patterns. They do not establish learning,
mastery, cognitive effort, engagement, trust, factual quality, intelligence,
personality or causal influence. A study design that treats an ICCC curve as an
outcome variable needs external validation of that curve first. See
[`evaluation.md`](evaluation.md).