# Design note: ChangeProposal (propose-then-confirm)

Status: **Shipped (#214/#236)** — model, service, API, and review UI landed; the
assistant producer and cross-op transactional apply remain as follow-ups (see
Out of scope). Implements non-negotiable #1 (CLAUDE.md): *the AI
assistant never writes autonomously.* Every assistant "write" emits a
**ChangeProposal** — a structured diff a human approves, edits, or rejects.

## The invariant, structurally

There must be **no code path where a model response mutates tree data**. We get
this by construction, not convention:

- Model providers (`app/integrations/models/*`) are read-only text/vector
  producers — they never import a repository or session-mutating service.
- The assistant's tools, when they land, will call `change_proposal_service.propose(...)`,
  which only **inserts a pending ChangeProposal**. It performs no domain mutation.
- A ChangeProposal's operations are executed **only** by
  `change_proposal_service.apply(...)`, which:
  1. requires the actor be an **editor/owner** of the tree (`privacy.can_edit_tree`),
  2. dispatches each operation through the **normal editing services**
     (`person_service`, `event_service`, …) — so every change passes the privacy
     engine and writes an `AuditEntry` with the **human** as `actor`,
  3. flips the proposal to `applied`.

So an assistant can *suggest* anything, but a change reaches the database only
when a human with edit rights approves it, and only via the same services a human
edit uses.

## Data model

`ChangeProposal` (`TenantScoped` tree_id, `Timestamps`, `SoftDelete`):

| field | notes |
|---|---|
| `tree_id` | tenant boundary |
| `status` | `pending` \| `applied` \| `rejected` |
| `origin` | `assistant` \| `contributor` — who proposed it (the contributor case also moderates untrusted human edits) |
| `created_by_user_id` | the user on whose behalf the assistant acted, or the contributor |
| `summary` | one-line human description ("Add birth 1850 to John Smith") |
| `rationale` | the assistant's reasoning / sources (text) |
| `operations` | JSONB list of ops (the structured diff) |
| `reviewed_by_user_id`, `reviewed_at`, `review_note` | set on approve/reject |
| `apply_error` | populated if application failed (proposal stays `pending`) |

An **operation** is `{op, entity_type, entity_id?, payload}`:
- `op` ∈ `create` | `update` | `delete`
- `entity_type` ∈ `person` | `name` | `event` | `relationship` | `source` | `citation`
- `entity_id` — null for `create`; the target id for `update`/`delete`
- `payload` — proposed field values (`create`/`update`); ignored for `delete`

A proposal may carry several operations (e.g. "add a person and link them as a
child" = create person + create relationship), applied **in order**. The editing
services each commit, so v1 application is **not transactional across ops** — if
op N fails, ops 1..N-1 are already applied and the proposal stays `pending` with
`apply_error` set so the reviewer can fix and re-apply the remainder. Single-op
proposals (the common near-term case) are effectively atomic. Cross-op atomicity
is a follow-up (it needs the services to accept a no-commit mode).

## Service surface

- `propose(session, *, tree, origin, created_by, summary, rationale, operations) -> ChangeProposal`
  — inserts a `pending` proposal. The **only** thing the assistant can call.
- `list_proposals` / `get_proposal` — visible to tree members.
- `apply(session, *, actor, tree, proposal_id, edited_operations=None) -> ChangeProposal`
  — editor-only. Optional `edited_operations` lets the reviewer tweak the diff
  before applying ("edit" in approve/edit/reject). Dispatches each op through the
  editing services; on failure it records `apply_error` and leaves the proposal
  pending — it does **not** roll back ops already committed by earlier dispatches
  (v1 is not cross-op transactional; see Data model).
- `reject(session, *, actor, tree, proposal_id, note=None)` — editor-only.

## API

`/trees/{id}/proposals`: `GET` (list, `?status=`), `POST` (create — used by tests
and the future contributor flow), `GET /{pid}`, `POST /{pid}/apply`,
`POST /{pid}/reject`, `DELETE /{pid}`.

## Out of scope (follow-ups)

- The assistant itself (it will be the primary producer; #-future).
- A rich diff/edit UI — v1 ships a review list with approve/reject; "edit before
  apply" is supported in the API and can get UI later.
- Dispatch for media/place/tree-settings ops (added when a producer needs them).