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
Closes#44. Two independent grids (garden + per-bed), each with a size and a snap toggle; snapping defaults off. See PR #45 for details.
Co-authored-by: Steve Dudenhoeffer <[email protected]>
Fixes from the PR #26 adversarial review (graded 18 real / 0 false positive).
Correctness / security
- maxGardenCM fixed to 10_000 (100 m), matching its comment — it was
100_000 cm (1 km), 10x too lax (5 models flagged this).
- Dimension validation now rejects NaN/Inf (which slip past naive
comparisons) and subnormal-tiny positives, via a finite [1cm, 100m]
check. Name (200) and notes (10_000) are length-capped so untrusted
input can't balloon storage.
- Update version binding is `required,min=1`, so a negative/zero version
is a 400, not a 409.
Maintainability / performance
- One unified writeServiceError (new errors.go) maps every auth + resource
sentinel; writeResourceError removed. writeVersionConflict and
parseIDParam moved to errors.go (shared, not in the gardens feature file).
- Request structs share an embedded gardenFields (one toInput).
- CreateGarden uses INSERT ... RETURNING (one round-trip).
- ListGardensForOwner has a defensive LIMIT (pagination is post-v1).
Tests: name/notes length, NaN/Inf/subnormal dims, dimension-at-cap valid,
negative/zero version -> 400.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01JdQpdYYsTgtkJBxbcpAszi
Establishes the patterns every later backend issue copies: the actor
parameter, centralized role checks, and the version-guard/409 sync
protocol. The service layer is the seam both REST handlers and future
agent tools call, so permissions live here, not in handlers.
- service/gardens.go: Service methods take (ctx, actorID, args).
requireGardenRole(ctx, actor, gardenID, min) is THE authorization point
— owner is implicit via owner_id now; #16 extends it to consult
garden_shares. A user with no role gets ErrNotFound (existence masked),
not ErrForbidden. Create/Get/List/Update/Delete with input validation
(name required, 0 dims default to 10 m on create / rejected on update,
negatives always rejected, unit metric|imperial, 100 m cap).
- store/gardens.go: version-guarded UPDATE ... WHERE id=? AND version=?
RETURNING; a no-match re-reads to return (current row,
ErrVersionConflict) vs ErrNotFound. ListGardensForOwner returns a
non-nil slice.
- api/gardens.go: GET,POST /gardens and GET,PATCH,DELETE /gardens/:id
behind requireAuth. writeVersionConflict documents the 409 envelope
({error:{code,message}, current:{...}}) — the contract for every
mutable resource. writeResourceError maps ErrNotFound/Forbidden/
InvalidInput/VersionConflict; parseIDParam guards path ids.
Tests: service (defaults, validation, owned-only list, version
conflict returns current + retry, cross-user ErrNotFound, delete) and
api (full CRUD flow, 409 envelope shape, cross-user 404, auth required,
create validation). Verified against the running binary: create stores
imperial 122x244 cm and list returns it.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01JdQpdYYsTgtkJBxbcpAszi
steveandClaude Opus 4.8