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
2026-07-21 00:53:55 -04:00
parent 8a12069118
commit b4f3181aef
15 changed files with 1902 additions and 15 deletions
@@ -0,0 +1,53 @@
+-- Revision history: the undo substrate (#48).
+--
+-- The unit of undo is the OPERATION, not the row. "Empty the garlic bed and
+-- plant cucumbers" touches one object and many plantings; undoing half of that
+-- is worse than useless. So a change_set groups the row-level revisions it
+-- produced, and revert replays their inverses.
+--
+-- Two properties this schema is built around:
+--   * Revert is itself a change set (reverts_id points at its target). History is
+--     append-only and never rewritten, so an undo can be undone. git revert, not
+--     git reset.
+--   * Every revision carries full JSON row snapshots INCLUDING version, which is
+--     what the revert guard compares against so a later edit is reported as a
+--     conflict rather than silently clobbered.
+--
+-- JSON snapshots rather than a shadow table per entity: the rows are small,
+-- household scale makes storage a non-issue, and one code path covers all three
+-- entity types.
+--
+-- Deliberate gap: garden DELETION is not revertible. Dropping a garden cascades
+-- its objects and plantings without the service ever seeing them, and the
+-- ON DELETE CASCADE below would take the history with it. The history UI says so
+-- rather than pretending otherwise.
+CREATE TABLE change_sets (
+    id           INTEGER PRIMARY KEY,
+    garden_id    INTEGER NOT NULL REFERENCES gardens (id) ON DELETE CASCADE,
+    actor_id     INTEGER NOT NULL REFERENCES users (id) ON DELETE CASCADE,
+    source       TEXT    NOT NULL CHECK (source IN ('ui', 'agent', 'api')),
+    summary      TEXT    NOT NULL DEFAULT '',
+    agent_run_id TEXT,                                   -- executus run id when source='agent'
+    reverts_id   INTEGER REFERENCES change_sets (id),    -- set when this change set reverts another
+    created_at   TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+-- The history panel's only query: one garden, newest first.
+CREATE INDEX idx_change_sets_garden ON change_sets (garden_id, created_at DESC);
+
+-- "Has this change set been reverted?" — the list marks reverted entries, so the
+-- lookup by target must not be a scan.
+CREATE INDEX idx_change_sets_reverts ON change_sets (reverts_id) WHERE reverts_id IS NOT NULL;
+
+CREATE TABLE revisions (
+    id            INTEGER PRIMARY KEY,
+    change_set_id INTEGER NOT NULL REFERENCES change_sets (id) ON DELETE CASCADE,
+    seq           INTEGER NOT NULL,                      -- order within the change set
+    entity_type   TEXT    NOT NULL CHECK (entity_type IN ('garden', 'object', 'planting')),
+    entity_id     INTEGER NOT NULL,
+    op            TEXT    NOT NULL CHECK (op IN ('create', 'update', 'delete')),
+    before        TEXT,                                  -- JSON row snapshot; NULL for create
+    after         TEXT                                   -- JSON row snapshot; NULL for delete
+);
+
+CREATE INDEX idx_revisions_change_set ON revisions (change_set_id, seq);
@@ -61,6 +61,33 @@ func (d *DB) CreateObject(ctx context.Context, o *domain.GardenObject) (*domain.
 	return created, nil
 }

+// RestoreObject re-inserts a deleted object under its ORIGINAL id, preserving
+// version and timestamps — the inverse of a delete, for reverting a change set
+// (#48). SQLite allows an explicit INTEGER PRIMARY KEY insert once the row is
+// gone; if the id has been taken again the insert fails on the primary key, which
+// is the correct outcome (the service checks first and reports a conflict).
+//
+// Deliberately not routed through objectInsert: that omits id/version/timestamps
+// because a normal create must let the database assign them.
+func (d *DB) RestoreObject(ctx context.Context, o *domain.GardenObject) (*domain.GardenObject, error) {
+	restored, err := scanObject(d.sql.QueryRowContext(ctx,
+		`INSERT INTO garden_objects
+		   (id, garden_id, kind, name, shape, points, x_cm, y_cm, width_cm, height_cm,
+		    rotation_deg, z_index, plantable, color, props, grid_size_cm, snap_to_grid, notes,
+		    version, created_at, updated_at)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
+		         strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+		 RETURNING `+objectColumns,
+		o.ID, o.GardenID, o.Kind, o.Name, o.Shape, o.Points, o.XCM, o.YCM, o.WidthCM, o.HeightCM,
+		o.RotationDeg, o.ZIndex, boolToInt(o.Plantable), o.Color, o.Props,
+		o.GridSizeCM, boolToInt(o.SnapToGrid), o.Notes, o.Version, o.CreatedAt,
+	))
+	if err != nil {
+		return nil, fmt.Errorf("store: restore object: %w", err)
+	}
+	return restored, nil
+}
+
 // GetObject returns the object with the given id, or domain.ErrNotFound.
 func (d *DB) GetObject(ctx context.Context, id int64) (*domain.GardenObject, error) {
 	o, err := scanObject(d.sql.QueryRowContext(ctx,
@@ -71,6 +71,37 @@ func (d *DB) ListActivePlantingsForObject(ctx context.Context, objectID int64) (
 		objectID)
 }

+// ListPlantingsForObject returns every plop in an object, removed ones included.
+// Used when an object is deleted: the FK cascades its plantings away without the
+// service seeing them, so they are snapshotted first or the delete would not be
+// revertible. Always a non-nil slice.
+func (d *DB) ListPlantingsForObject(ctx context.Context, objectID int64) ([]domain.Planting, error) {
+	return queryPlantings(ctx, d.sql,
+		`SELECT `+plantingColumns+` FROM plantings WHERE object_id = ? ORDER BY id`,
+		objectID)
+}
+
+// RestorePlanting re-inserts a deleted plop under its ORIGINAL id, preserving
+// version and timestamps — the plop counterpart of RestoreObject, and subject to
+// the same reasoning. Its parent object must exist again first, or the FK
+// rejects it; the revert orders object restores ahead of planting restores.
+func (d *DB) RestorePlanting(ctx context.Context, p *domain.Planting) (*domain.Planting, error) {
+	restored, err := scanPlanting(d.sql.QueryRowContext(ctx,
+		`INSERT INTO plantings
+		   (id, object_id, plant_id, x_cm, y_cm, radius_cm, count, label, planted_at, removed_at,
+		    version, created_at, updated_at)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
+		         strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+		 RETURNING `+plantingColumns,
+		p.ID, p.ObjectID, p.PlantID, p.XCM, p.YCM, p.RadiusCM, p.Count, p.Label,
+		p.PlantedAt, p.RemovedAt, p.Version, p.CreatedAt,
+	))
+	if err != nil {
+		return nil, fmt.Errorf("store: restore planting: %w", err)
+	}
+	return restored, nil
+}
+
 // ClearObjectPlantings soft-removes every active plop in an object in one UPDATE
 // (sets removed_at=date, bumps version) and returns how many rows it affected.
 func (d *DB) ClearObjectPlantings(ctx context.Context, objectID int64, date string) (int, error) {
@@ -0,0 +1,192 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/domain"
+)
+
+// changeSetColumns lists change_sets columns in the order scanChangeSet expects.
+const changeSetColumns = `id, garden_id, actor_id, source, summary, agent_run_id, reverts_id, created_at`
+
+func scanChangeSet(s scanner) (*domain.ChangeSet, error) {
+	var cs domain.ChangeSet
+	if err := s.Scan(
+		&cs.ID, &cs.GardenID, &cs.ActorID, &cs.Source, &cs.Summary,
+		&cs.AgentRunID, &cs.RevertsID, &cs.CreatedAt,
+	); err != nil {
+		return nil, err
+	}
+	return &cs, nil
+}
+
+// revisionColumns lists revisions columns in the order scanRevision expects.
+const revisionColumns = `id, change_set_id, seq, entity_type, entity_id, op, before, after`
+
+func scanRevision(s scanner) (*domain.Revision, error) {
+	var r domain.Revision
+	if err := s.Scan(
+		&r.ID, &r.ChangeSetID, &r.Seq, &r.EntityType, &r.EntityID, &r.Op, &r.Before, &r.After,
+	); err != nil {
+		return nil, err
+	}
+	return &r, nil
+}
+
+// WriteChangeSet inserts a change set and all of its revisions in one
+// transaction, so history never records half an operation. The service buffers
+// revisions while the operation runs and calls this once it has succeeded —
+// which is also why an operation that fails partway leaves no change set behind.
+// seq is assigned from the slice order. Returns the stored change set.
+func (d *DB) WriteChangeSet(ctx context.Context, cs *domain.ChangeSet, revs []domain.Revision) (*domain.ChangeSet, error) {
+	tx, err := d.sql.BeginTx(ctx, nil)
+	if err != nil {
+		return nil, fmt.Errorf("store: begin change set: %w", err)
+	}
+	defer func() { _ = tx.Rollback() }()
+
+	created, err := scanChangeSet(tx.QueryRowContext(ctx,
+		`INSERT INTO change_sets (garden_id, actor_id, source, summary, agent_run_id, reverts_id)
+		 VALUES (?, ?, ?, ?, ?, ?)
+		 RETURNING `+changeSetColumns,
+		cs.GardenID, cs.ActorID, cs.Source, cs.Summary, cs.AgentRunID, cs.RevertsID))
+	if err != nil {
+		return nil, fmt.Errorf("store: insert change set: %w", err)
+	}
+
+	for i := range revs {
+		r := &revs[i]
+		if _, err := tx.ExecContext(ctx,
+			`INSERT INTO revisions (change_set_id, seq, entity_type, entity_id, op, before, after)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+			created.ID, int64(i+1), r.EntityType, r.EntityID, r.Op, r.Before, r.After,
+		); err != nil {
+			return nil, fmt.Errorf("store: insert revision: %w", err)
+		}
+	}
+
+	if err := tx.Commit(); err != nil {
+		return nil, fmt.Errorf("store: commit change set: %w", err)
+	}
+	return created, nil
+}
+
+// ListChangeSets returns a garden's change sets newest-first, one page at a time.
+// Each carries its actor's display name, the id of the change set that reverted
+// it (if any), and per-(entity,op) counts — everything the history list renders,
+// without a second round-trip per row. Always a non-nil slice.
+func (d *DB) ListChangeSets(ctx context.Context, gardenID int64, limit, offset int) ([]domain.ChangeSet, error) {
+	rows, err := d.sql.QueryContext(ctx,
+		`SELECT `+qualifyColumns("cs", changeSetColumns)+`, u.display_name, rev.id
+		   FROM change_sets cs
+		   JOIN users u ON u.id = cs.actor_id
+		   LEFT JOIN change_sets rev ON rev.reverts_id = cs.id
+		  WHERE cs.garden_id = ?
+		  ORDER BY cs.id DESC
+		  LIMIT ? OFFSET ?`,
+		gardenID, limit, offset)
+	if err != nil {
+		return nil, fmt.Errorf("store: list change sets: %w", err)
+	}
+	defer rows.Close()
+
+	sets := []domain.ChangeSet{}
+	ids := []any{}
+	byID := map[int64]int{}
+	for rows.Next() {
+		var cs domain.ChangeSet
+		if err := rows.Scan(
+			&cs.ID, &cs.GardenID, &cs.ActorID, &cs.Source, &cs.Summary,
+			&cs.AgentRunID, &cs.RevertsID, &cs.CreatedAt, &cs.ActorName, &cs.RevertedByID,
+		); err != nil {
+			return nil, fmt.Errorf("store: scan change set: %w", err)
+		}
+		byID[cs.ID] = len(sets)
+		ids = append(ids, cs.ID)
+		sets = append(sets, cs)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("store: iterate change sets: %w", err)
+	}
+	if len(sets) == 0 {
+		return sets, nil
+	}
+
+	// One grouped query for the whole page rather than N per-row counts.
+	countRows, err := d.sql.QueryContext(ctx,
+		`SELECT change_set_id, entity_type, op, COUNT(*)
+		   FROM revisions
+		  WHERE change_set_id IN (`+placeholders(len(ids))+`)
+		  GROUP BY change_set_id, entity_type, op
+		  ORDER BY change_set_id, entity_type, op`,
+		ids...)
+	if err != nil {
+		return nil, fmt.Errorf("store: count revisions: %w", err)
+	}
+	defer countRows.Close()
+	for countRows.Next() {
+		var csID int64
+		var c domain.ChangeCount
+		if err := countRows.Scan(&csID, &c.EntityType, &c.Op, &c.N); err != nil {
+			return nil, fmt.Errorf("store: scan revision count: %w", err)
+		}
+		if i, ok := byID[csID]; ok {
+			sets[i].Counts = append(sets[i].Counts, c)
+		}
+	}
+	if err := countRows.Err(); err != nil {
+		return nil, fmt.Errorf("store: iterate revision counts: %w", err)
+	}
+	return sets, nil
+}
+
+// GetChangeSet returns one change set with its revisions loaded in seq order, or
+// domain.ErrNotFound.
+func (d *DB) GetChangeSet(ctx context.Context, id int64) (*domain.ChangeSet, error) {
+	cs, err := scanChangeSet(d.sql.QueryRowContext(ctx,
+		`SELECT `+changeSetColumns+` FROM change_sets WHERE id = ?`, id))
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, domain.ErrNotFound
+	}
+	if err != nil {
+		return nil, fmt.Errorf("store: get change set: %w", err)
+	}
+
+	rows, err := d.sql.QueryContext(ctx,
+		`SELECT `+revisionColumns+` FROM revisions WHERE change_set_id = ? ORDER BY seq`, id)
+	if err != nil {
+		return nil, fmt.Errorf("store: list revisions: %w", err)
+	}
+	defer rows.Close()
+
+	cs.Revisions = []domain.Revision{}
+	for rows.Next() {
+		r, err := scanRevision(rows)
+		if err != nil {
+			return nil, fmt.Errorf("store: scan revision: %w", err)
+		}
+		cs.Revisions = append(cs.Revisions, *r)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("store: iterate revisions: %w", err)
+	}
+	return cs, nil
+}
+
+// placeholders returns "?, ?, …" for an IN clause of n values.
+func placeholders(n int) string {
+	if n <= 0 {
+		return "NULL"
+	}
+	b := make([]byte, 0, n*3)
+	for i := 0; i < n; i++ {
+		if i > 0 {
+			b = append(b, ',', ' ')
+		}
+		b = append(b, '?')
+	}
+	return string(b)
+}