feat(api): undo an agent write by proposing its inverse (ADR-0031) #355

Merged

james merged 1 commit from 352-agent-write-undo into main 2026-06-29 12:46:19 +00:00

Conversation 1 Commits 1 Files changed 9 +691 -1

james commented 2026-06-29 12:31:19 +00:00

Owner

Copy link

Closes the last core exit criterion of epic #47 — every agent-driven write is now undoable. Backend + design; the activity-screen undo button is a follow-up.

Design — ADR-0031 (in this PR)

An undo is not a new mutator path. It loads an audit event, computes the inverse tool + input, and runs that tool's execute, which persists a normal agent_proposals row. The client confirms it through the existing proposal read (#342) + commit/reject (#51) flow. So an undo is itself confirmed, audited, and undoable, and gets conflict re-validation for free at commit time — no second mutator, no per-entity reversal code.

Inverse keyed by entity_type + the original action class (the tool name isn't a clean verb_noun — add_note_to_person has entityType person_note; the factory names CRUD tools delete_<entityType>/update_<entityType>, so the inverse resolves by that key):

• safe_create → delete_<entityType>({ id })
• safe_update / destructive_update → update_<entityType>({ id, ...changed fields restored to before }) (the update tool's zod parse strips server-managed keys like updated_at)
• destructive_delete → not undoable → 409 not_undoable (the snapshot doesn't capture the cascading children a delete removed, and the original id can't be restored through create — deferred until subtree-capture lands)

What's in it

• docs/adr/0031-agent-write-undo.md
• lib/agent/undo.ts (buildUndoProposal) + AuditEventsRepository.findById
• POST /api/agent/audit/{id}/undo → returns the inverse proposal as ProposalDto; per-user 404; 409 not_undoable
• zod/openapi + api-client types regenerated

Verification (local)

• typecheck ✓ · lint ✓
• test against both engines (ephemeral Postgres): 1230 passed, 0 skipped (+13). Dual-engine undo suite drives the real note tools + commit: undo a create → delete (and committing it removes the note); undo an update → restore the changed fields (and committing puts the value back); delete refused (not_undoable); missing/cross-user → 404; and the undo round-trips — it writes its own audit event, and undoing that re-applies. Plus HTTP route tests (401, 201→ProposalDto, cross-user 404).
• @carol/api-client test ✓ 42 · openapi:check ✓ · openapi:coverage 118 → 119 · api-client check ✓
• semgrep (CI pack set) ✓ 0 findings on the new files

Out of scope (follow-ups)

• The activity-screen undo button + confirmation UI (consumes this endpoint; reuses the proposal confirmation card). Will also update the activity lede that currently says "nothing here can be undone".
• Undoing deletes (full-subtree audit capture + restore-by-id).

Part of epic #47.

Closes #354

🤖 Generated with Claude Code

Closes the last core exit criterion of epic #47 — every agent-driven write is now undoable. Backend + design; the activity-screen undo button is a follow-up. ## Design — ADR-0031 (in this PR) An undo is **not a new mutator path**. It loads an audit event, computes the inverse tool + input, and runs that tool's `execute`, which persists a normal `agent_proposals` row. The client confirms it through the existing proposal read (#342) + commit/reject (#51) flow. So an undo is itself **confirmed, audited, and undoable**, and gets conflict re-validation for free at commit time — no second mutator, no per-entity reversal code. Inverse keyed by `entity_type` + the original `action` class (the tool name isn't a clean `verb_noun` — `add_note_to_person` has entityType `person_note`; the factory names CRUD tools `delete_<entityType>`/`update_<entityType>`, so the inverse resolves by that key): - `safe_create` → `delete_<entityType>({ id })` - `safe_update` / `destructive_update` → `update_<entityType>({ id, ...changed fields restored to before })` (the update tool's zod parse strips server-managed keys like `updated_at`) - `destructive_delete` → **not undoable** → 409 `not_undoable` (the snapshot doesn't capture the cascading children a delete removed, and the original id can't be restored through create — deferred until subtree-capture lands) ## What's in it - `docs/adr/0031-agent-write-undo.md` - `lib/agent/undo.ts` (`buildUndoProposal`) + `AuditEventsRepository.findById` - `POST /api/agent/audit/{id}/undo` → returns the inverse proposal as `ProposalDto`; per-user 404; 409 `not_undoable` - zod/openapi + api-client types regenerated ## Verification (local) - `typecheck` ✓ · `lint` ✓ - `test` against **both engines** (ephemeral Postgres): **1230 passed, 0 skipped** (+13). Dual-engine undo suite drives the real note tools + commit: undo a create → delete (and committing it removes the note); undo an update → restore the changed fields (and committing puts the value back); delete refused (`not_undoable`); missing/cross-user → 404; and the undo **round-trips** — it writes its own audit event, and undoing that re-applies. Plus HTTP route tests (401, 201→`ProposalDto`, cross-user 404). - `@carol/api-client test` ✓ 42 · `openapi:check` ✓ · `openapi:coverage` 118 → **119** · api-client `check` ✓ - semgrep (CI pack set) ✓ 0 findings on the new files ## Out of scope (follow-ups) - The activity-screen **undo button** + confirmation UI (consumes this endpoint; reuses the proposal confirmation card). Will also update the activity lede that currently says "nothing here can be undone". - Undoing deletes (full-subtree audit capture + restore-by-id). Part of epic #47. Closes #354 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-29 12:31:19 +00:00

feat(api): undo an agent write by proposing its inverse (ADR-0031) ... 9a6a34e414

Closes the last core exit criterion of epic #47: every agent-driven write
is now undoable. An undo is NOT a new mutator path — it loads an audit
event, computes the inverse tool + input, and runs that tool's execute,
which persists a normal agent_proposals row. The client confirms it
through the existing proposal read (#342) + commit/reject (#51) flow, so
an undo is itself confirmed, audited, and undoable, and gets conflict
re-validation for free at commit time.

- docs/adr/0031-agent-write-undo.md: the design + the rationale for the
  inverse-proposal approach and why deletes aren't undoable yet.
- lib/agent/undo.ts (buildUndoProposal): inverse keyed by entity_type +
  the original action class (the tool name isn't a clean verb_noun).
  safe_create → delete_<entityType>; safe/destructive_update →
  update_<entityType> restoring changed fields; destructive_delete →
  409 not_undoable (snapshot lacks cascading children; original id can't
  be restored through create).
- POST /api/agent/audit/{id}/undo → returns the inverse proposal as
  ProposalDto (the shape the confirmation UI consumes); per-user 404.
- AuditEventsRepository.findById; zod/openapi + api-client regenerated.

Dual-engine tests drive the real note tools + commit: undo a create →
delete; undo an update → restore; deletes refused; cross-user 404; and
the undo round-trips (it's itself audited + undoable).

Activity-screen undo button is a follow-up.

Closes #354

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

forgejo-actions commented 2026-06-29 12:37:15 +00:00

Copy link

📊 Test coverage

Patch coverage: no testable lines changed.

Overall (app/, lib/, db/, excluding UI per ADR-0019):

Metric	Value	Soft target
Lines	79.3% ✅	≥ 50%
Branches	71.1% ⚠️	≥ 75%
Functions	80.5%	informational

Soft thresholds per ADR-0019. Coverage is informational and does not block merge.

<!-- coverage-comment --> ## 📊 Test coverage **Patch coverage:** no testable lines changed. **Overall** (`app/`, `lib/`, `db/`, excluding UI per ADR-0019): | Metric | Value | Soft target | |---|---|---| | Lines | 79.3% ✅ | ≥ 50% | | Branches | 71.1% ⚠️ | ≥ 75% | | Functions | 80.5% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.

james merged commit dcb1e19f0a into main 2026-06-29 12:46:19 +00:00

james deleted branch 352-agent-write-undo 2026-06-29 12:46:19 +00:00

james referenced this pull request from a commit 2026-06-29 12:46:20 +00:00

Merge pull request 'feat(api): undo an agent write by proposing its inverse (ADR-0031)' (#355) from 352-agent-write-undo into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!355

No description provided.