provenance/docs/design/change-proposal.md

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).