Files

T

justin 447daf7fa8 docs: bring all documentation current with shipped work

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>

2026-06-10 21:05:29 -04:00

4.4 KiB

Raw Blame History

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

4.4 KiB Raw Blame History