Revision history: change sets, revisions, and revert (#48)

The undo substrate. The agent is going to act freely — "empty the garlic bed and
plant cucumbers" runs without a confirmation prompt — and that is only a
defensible default if the result is easy to roll back. So undo lands before the
agent write path, not after it.

The unit of undo is the OPERATION, not the row. A change set groups the
row-level revisions it produced; revert replays their inverses. Emptying a bed
and replanting it touches one object and many plantings, and undoing half of
that is worse than useless.

Two properties shape the rest:

Revert is itself a change set (reverts_id names its target), so history is
append-only and an undo can be undone. git revert, not git reset.

Revert is version-guarded per entity. Every snapshot carries the row's version;
if something edited that row after the change set being reverted, restoring the
old snapshot would silently discard the newer edit, so it is reported as a
conflict and left alone while the rest of the change set still reverts.

The auto-scope is what keeps this invasive but shallow. Service mutations call
record(), which joins the change set on the context if one is open and otherwise
opens a single-op one on the spot. REST handlers needed no edits at all and
every UI mutation lands in history for free; only the agent wraps a whole turn.
Multi-row operations (FillRegion, ClearObject) pass all their changes in one
record call, so a 12-plop fill is one change set with 12 revisions and one undo.

Revisions are buffered and written with their change set in a single
transaction, so an operation that fails partway leaves no half-recorded history.
Recording is best-effort after the fact: the row is already written, so failing
the caller there would report a failure that didn't happen and invite a
duplicate retry. A gap is logged loudly instead.

Two sharp edges handled explicitly rather than by luck:

Deleting an object cascades its plantings away at the FK level, where the
service never sees them. deleteObjectRecording snapshots them first, or the
delete would be listed in history and not actually be undoable.

Restoring deleted rows reuses their ids, and a restored plop needs its object
back first. planRevert runs three explicit passes — restore parents then
children, then updates, then delete created children before their parents —
instead of trusting reverse-seq ordering to happen to be right.

Garden deletion stays out of scope, as designed: the cascade is invisible to the
service and ON DELETE CASCADE would take the history with it. The history UI
will say so rather than pretend otherwise.

Closes #48

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01H3zbym8Doka2d7D48maSgZ

internal/domain/domain.go

@@ -93,6 +93,97 @@ const (
 	CategoryFruit     = "fruit"
 	CategoryTreeShrub = "tree_shrub"
 	CategoryCover     = "cover"
+
+	// Where a change set came from. SourceAgent is what the history UI badges
+	// differently, so an autonomous edit is never mistaken for a hand edit.
+	SourceUI    = "ui"
+	SourceAgent = "agent"
+	SourceAPI   = "api"
+
+	// The entity types a revision can snapshot. Garden covers metadata edits
+	// only — garden creation and deletion are deliberately not revertible.
+	EntityGarden   = "garden"
+	EntityObject   = "object"
+	EntityPlanting = "planting"
+
+	OpCreate = "create"
+	OpUpdate = "update"
+	OpDelete = "delete"
+)
+
+// ChangeSet groups the revisions produced by one logical operation — the unit of
+// undo. A revert is itself a change set (RevertsID names its target), so history
+// is append-only and an undo can be undone.
+type ChangeSet struct {
+	ID         int64   `json:"id"`
+	GardenID   int64   `json:"gardenId"`
+	ActorID    int64   `json:"actorId"`
+	Source     string  `json:"source"`
+	Summary    string  `json:"summary"`
+	AgentRunID *string `json:"agentRunId,omitempty"`
+	RevertsID  *int64  `json:"revertsId,omitempty"`
+	CreatedAt  string  `json:"createdAt"`
+
+	// Computed by the service for the history list, never persisted.
+	ActorName string `json:"actorName,omitempty"`
+	// RevertedByID is the change set that reverted this one, if any — what lets
+	// the list mark an entry as already undone.
+	RevertedByID *int64 `json:"revertedById,omitempty"`
+	// Counts tallies the revisions by (entity type, op) so the list can say
+	// "3 plops added, 1 bed moved" without loading every revision.
+	Counts []ChangeCount `json:"counts,omitempty"`
+	// Revisions is populated only when a single change set is loaded in full.
+	Revisions []Revision `json:"revisions,omitempty"`
+}
+
+// ChangeCount is one (entity type, op) tally within a change set.
+type ChangeCount struct {
+	EntityType string `json:"entityType"`
+	Op         string `json:"op"`
+	N          int    `json:"n"`
+}
+
+// Revision is one row-level change within a change set. Before/After are JSON
+// row snapshots (nil for create/delete respectively) and include the row's
+// version, which the revert guard compares against.
+type Revision struct {
+	ID          int64   `json:"id"`
+	ChangeSetID int64   `json:"changeSetId"`
+	Seq         int64   `json:"seq"`
+	EntityType  string  `json:"entityType"`
+	EntityID    int64   `json:"entityId"`
+	Op          string  `json:"op"`
+	Before      *string `json:"before,omitempty"`
+	After       *string `json:"after,omitempty"`
+}
+
+// RevertConflict reports one entity a revert deliberately left alone, because
+// reverting it would have discarded a change made after the change set being
+// reverted. The rest of the change set still reverts.
+type RevertConflict struct {
+	EntityType string `json:"entityType"`
+	EntityID   int64  `json:"entityId"`
+	// Reason is one of the ConflictReason* values below.
+	Reason string `json:"reason"`
+	// Name is a human label for the entity where one exists (an object's name),
+	// so the UI can say "the north bed" rather than "object 41".
+	Name string `json:"name,omitempty"`
+}
+
+// Why a revert skipped an entity.
+const (
+	// ConflictChanged: the row was edited after the change set being reverted, so
+	// restoring the old snapshot would silently discard that edit.
+	ConflictChanged = "changed"
+	// ConflictMissing: the row is gone, so there is nothing to revert to.
+	ConflictMissing = "missing"
+	// ConflictExists: a row with that id exists again, so restoring the deleted
+	// snapshot would overwrite it.
+	ConflictExists = "exists"
+	// ConflictUnsupported: this kind of change has no inverse the revert knows how
+	// to apply. Reported rather than silently skipped, so a change recorded by a
+	// later feature that revert wasn't taught about is visible instead of quiet.
+	ConflictUnsupported = "unsupported"
 )
 
 // User is a pansy account. It may have a local password, OIDC identity, or both.