justin
abaa8efdd5
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>
81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
# 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).
|