# {{projectName}} / {{appName}}

Voltro API scaffold (template: **api-row-history**) — full row history +
time-travel with `@voltro/plugin-row-history`.

## Boot

```bash
pnpm install
pnpm --filter @{{projectName}}/{{appName}} dev
# → http://localhost:4000  (store: memory — zero infra)
```

## What this shows

- **Every change snapshotted** — `rowHistoryPlugin({ tables: ['documents'] })`
  rides the post-commit ChangeEvent tap and records a FULL snapshot of every
  insert/update/delete. No code in your handlers.
- **Read it back through handlers** —
  - `documents.history` → `rowHistory(ctx.store, 'documents', id)` — every
    version, oldest to newest.
  - `documents.asOf` → `rowAsOf(ctx.store, 'documents', id, at)` — the value as
    of a past instant (epoch ms), or `null` if it didn't exist then.
- **Distinct from audit** — `audit()` records WHO/WHEN a row changed; this
  records WHAT it changed to, so you can diff or restore a prior version.

## Try it

```bash
# create (v1), then edit (v2):
ID=$(curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
  -d '{"tag":"documents.create","input":{"title":"Spec","content":"draft v1"}}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
  -d "{\"tag\":\"documents.update\",\"input\":{\"id\":\"$ID\",\"content\":\"final v2\"}}" >/dev/null

# every version:
curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
  -d "{\"tag\":\"documents.history\",\"input\":{\"id\":\"$ID\"}}"
# → [ { version:1, op:"insert", content:"draft v1", changedAt }, { version:2, op:"update", content:"final v2", … } ]

# the value as of v1's timestamp → "draft v1" (time-travel):
curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
  -d "{\"tag\":\"documents.asOf\",\"input\":{\"id\":\"$ID\",\"at\":<v1.changedAt>}}"
```

## Production

The memory history store is single-process. With a SQL store, history persists
in `_voltro_row_history`. List the tables you want versioned — high-churn
tables grow history fast, so version what you need to diff/restore, not
everything.