Design: staged drafts on published records

[npflood]

Design record only. No code, no schema, no behaviour change.

Problem

Today visibility: draft means "hidden", and there is exactly one copy of a
record. An editor who starts a translation and cannot finish it has one lever:
mark the whole record draft. It vanishes from public view, taking its finished
locales with it, because every locale lives in one Mobility container blob on
one row.

Families have the inverse problem: no visibility enum at all and
FamilyPolicy#show? returning true unconditionally, so every save to a family
description is instantly world-visible with no way to stage it.

Approach

The live row is never touched by editing. A polymorphic record_drafts row
holds the working copy; publishing replays it through the normal update path,
producing exactly one PaperTrail version whose changeset is the real
before/after.

Reads use a perspective lens (PUBLISHED | DRAFT, default PUBLISHED) —
the Contentful/Sanity shape. Same schema, no new per-entity types, and
anonymous or mobile callers never pass the argument, so they cannot receive
draft content. This is the codebase's second read lens; language: setting
Mobility.locale is the first.

Writes reuse the existing mutations via saveAsDraft: Boolean, plus
publishDraft and discardDraft.

Why not PaperTrail, which is what prompted this

The idea came from noticing PaperTrail already stores what looks like a draft.
Recorded in full in the spec, but in short: versions.object holds the state
before a change, so a draft would have to be written as a version that never
corresponded to a real saved state — a lie in an append-only audit log. It would
also fill the recordHistory drawer (live since 2026-08-06) with edits that
never happened, and restorePlantVersion would happily restore something never
published. The payload is unqueryable YAML, and association tracking is not
installed.

PaperTrail is used here, correctly, for conflict detection: the versions since
a draft's base_updated_at, intersected with the draft's changed keys, answer
"did live move under this draft?" precisely enough not to fire on every
SourceSynchronizer run.

paper_trail-association_tracking was evaluated and rejected on its own merits
— its README recommends active_snapshot instead, and it documents breakage on
transactional tests and STI, both of which we have. VersionedUnderRoot already
surfaces relation, common-name and image changes in recordHistory.

Scope

Plant, Variety, Family, Category (selected by "has translatable fields and an
editing surface worth staging"). The record's own columns, including the
translations jsonb — which covers the originating complaint in full. Relations,
common names and images are deliberately deferred, with the reasoning for why
that is not a one-way door.

Note that "live is only touched by Publish" is an editing-UI policy, not an
API restriction. SourceSynchronizer, the importers and the mobile app keep
writing live directly, and the frozen mobile contract is unchanged.

Sequencing

1. Category detail-page promotion — done, shipped as plant_data_admin_interface#24
2. Draft and publish — this design

🤖 Generated with Claude Code

https://claude.ai/code/session_01RnYLUscETuPwsQzU9nCSxu

[npflood]

Landed via #109's squash merge (the design doc is in master). Closing.