Fix #214: ChangeProposal (propose-then-confirm)

Implements non-negotiable #1: the AI assistant never writes autonomously. Every
assistant/contributor "write" emits a ChangeProposal — a structured diff a human
approves, edits, or rejects. Design: docs/design/change-proposal.md.

Structural guarantee: a proposal's operations reach the DB ONLY via
change_proposal_service.apply(), which requires the actor be an editor and
dispatches each op through the normal editing services (person/name/event/
relationship/source/citation create/update/delete) — so every change passes the
privacy engine and is audited as the approving human. propose() only inserts a
pending row; it performs no domain mutation. Model providers stay read-only, so
no model response can mutate tree data.

- ChangeProposal model + migration (status pending|applied|rejected, origin
  assistant|contributor, JSONB operations, reviewer + apply_error).
- Service: propose / list / get / apply (with optional edited ops) / reject /
  delete; a dispatcher mapping ops → editing services. v1 applies ops in order,
  not cross-op transactional (single-op is atomic; documented).
- API /trees/{id}/proposals + a frontend review page (approve/reject; editor-
  gated) and sidebar entry.

Tests: proposal doesn't apply until approved; reject doesn't apply; non-editor
member can see but not apply; multi-op; approve-with-edits; apply-error keeps it
pending. Full suite 87 passed; single alembic head.

Closes #214

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

docs/design/change-proposal.md

@@ -0,0 +1,80 @@
+# Design note: ChangeProposal (propose-then-confirm)
+
+Status: **in progress**. 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 any failure, rolls back and records `apply_error`.
+- `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).