justin
447daf7fa8
A multi-agent audit of every doc against the code surfaced ~50 stale/missing
items (the roadmap/status docs and the backlog had fallen behind the code).
This catches them up:
- CLAUDE.md: phase status was ~3 phases stale ("Phase 1 is next" while Phase 1 +
chunks of 2 & 4 shipped). Rewrote the status list; added a model-provider
tech-stack entry; updated repo-layout (integrations objectstore/models,
deploy backup.sh/dev compose).
- ARCHITECTURE.md: §6 privacy engine described 3 visibility levels — corrected to
the shipped 4 (adds site_members); documented per-tree AI policy on Tree,
LLMProvider/EmbeddingProvider split + registry, ChangeProposal origin/status/
operations, verified-email session gate, instance-owner role, schema-drift
guard, and the env_file config model.
- PRD.md: 4-level visibility in US-040/§5.5, instance-owner role (§5.1/§5.11),
per-tree AI policy (§5.8), §8 sequencing annotated with shipped status, header
date/status bumped.
- README.md: 4-level privacy; softened "Full GEDCOM 7" to the 5.5.1/7 common
subset; noted backups + instance-owner admin; moved property/land to an
explicit "where it's headed" (no property models exist yet).
- BACKLOG.md: flipped ~15 shipped-but-open rows to Have (ChangeProposal, provider
abstraction, GEDCOM citation export, membership management, operator backup,
email-verification gate, per-tree AI policy, instance owner, the whole
visibility/public-viewing/child-resource-redaction cluster #41-#51/#46), and
reconciled the executive summary, "current defects" list, quick wins, and
differentiators. Left genuinely-open items (citation/source redaction, sitemap,
per-tree noindex, scoped-token API) accurately open.
- .env.example: dropped "SMTP wired in a later phase"; documented the worker
purge knobs, S3_PRESIGN_TTL, COOKIE_NAME; removed a stray duplicate line.
- design/: tree-visibility.md and change-proposal.md marked Shipped; corrected
the redaction approach (reuses member schemas, not a separate PublicPersonRead)
and the apply() rollback claim (v1 is not cross-op transactional), and marked
rate-limiting/sitemap/noindex as deferred.
No code changes.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>
85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
# 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).
|