@voltro/cli 0.20.2 → 0.22.0

package/templates/agent-docs/database/migrations.md

@@ -89,7 +89,8 @@ voltro db plan --against <url>    # diff vs a remote env's inspect endpoint (see
 voltro db apply                   # execute (dev only — refuses on NODE_ENV=production)
 voltro db apply --note '...'      # apply with a freeform note recorded in history
 voltro db plans [--limit 20]      # history from _voltro_migration_plans, newest first
-voltro db drift                   # live-vs-applied fingerprint check — exit 4 on drift
+voltro db drift                   # live-vs-baseline check — exit 0 match, 3 no baseline, 4 drift
+voltro db drift --accept          # record the CURRENT live schema as the baseline (refuses unless db plan is empty)
 voltro db squash --before <date>  # consolidate history into one snapshot
 voltro db restore-snapshot <id>   # restore VOLTRO_SOFT_DROP=1 columns from a plan
 
@@ -119,6 +120,21 @@ there is no `--json` or `--sql`, and `voltro db apply` takes only
 deploy step ([prod pipeline](./prod-pipeline.md)), not a pre-serialised
 plan file.
 
+## Framework tables ride the same differ
+
+The `_voltro_*` tables the framework owns are planned, classified and applied by
+exactly the same code as yours — on every dialect. A framework release that adds
+a table, adds a column or reshapes one lands on the boot that follows your
+upgrade, wherever your own schema changes land. There is no separate command and
+no dialect-specific step.
+
+One asymmetry is deliberate and worth knowing if you ever read a plan: a
+framework-owned table that **nobody declares** — `cluster_*` from the workflow
+engine, a plugin's table after you removed the plugin — is never planned for a
+drop. "Nobody declared it, so do not drop it" and "we declare it, so keep it
+current" are different rules; collapsing them is what once made framework tables
+evolve on postgres and nowhere else.
+
 ## Where to go next
 
 | Topic | Page |
@@ -367,6 +383,92 @@ If the live DB doesn't have a column called `firstName`, the marker is a no-op:
 
 The marker isn't validated against the live DB at schema-build time — it would have to introspect during type-checking, which is expensive. The runtime check fires at plan time.
 
+## The indexes come with it
+
+Renaming a column is a metadata-only operation. Its **indexes** used to not be: index names are derived (`<table>_<column>_idx`), and no dialect renames an index when the column under it is renamed — so the planner saw `users_firstName_idx` on one side and `users_givenName_idx` on the other, and planned `DROP INDEX` + `CREATE INDEX`. On a large table that is a full B-tree rebuild: minutes of IO, and without `CONCURRENTLY` a write lock, behind a rename that was supposed to be instant.
+
+The planner now folds that into a `rename-index` operation, which is a catalog-only statement everywhere it is emitted:
+
+```
+✓ rename-column users.firstName → users.givenName   # catalog-only
+✓ rename-index  users_firstName_idx → users_givenName_idx   # catalog-only, no rebuild
+```
+
+You do not annotate anything for this — it follows from the column rename you already declared.
+
+Four cases deliberately still plan as drop + create, because pairing an old index with a new one has no evidence to stand on in them:
+
+- **sqlite** — it has no rename statement at all. The plan you read matches what runs.
+- **UNIQUE indexes** — they are constraint objects, and the syntax to rename one diverges by dialect.
+- **Expression / json-path indexes** — the database normalises their key text, so there is no shape to compare; only the name, which is the thing that changed.
+- **Two same-shaped indexes renamed at once** — nothing says which became which. Rebuilding both is slower; renaming the wrong one is worse.
+
+## Renaming a TABLE
+
+The same problem one level up, and with more at stake: a table rename and a
+drop+create look identical to the differ — old table gone, new table present —
+except that guessing wrong costs every row. So it needs a marker too, and it
+reads like its column counterpart:
+
+```ts
+// Before:
+export const notes = table('notes', { id: id({ prefix: 'note' }), body: text() })
+
+// After — without the marker:
+export const notes = table('archive_notes', { id: id({ prefix: 'note' }), body: text() })
+// → planner sees DROP TABLE notes + CREATE TABLE archive_notes
+// → the DROP is `lossy` and blocked; nothing happens until you acknowledge it
+
+// With the marker:
+export const notes = table('archive_notes', { id: id({ prefix: 'note' }), body: text() })
+  .renamedFrom('notes')
+// → one `rename-table` op, classified `safe`
+// → `ALTER TABLE notes RENAME TO archive_notes` — catalog-only, the rows stay put
+```
+
+Unlike an index rename, every dialect has this statement — sqlite included — so
+there is no dialect on which this falls back to a rebuild.
+
+**Its indexes come with it.** The same derivation that bites a column rename bites
+harder here: `notes_pkey` and `notes_<col>_idx` are named after the table, and no
+dialect renames them when the table is renamed. The planner emits a `rename-index`
+for each so the catalog catches up:
+
+```
+✓ rename-table  notes → archive_notes
+✓ rename-index  notes_pkey → archive_notes_pkey
+```
+
+Without that the plan would try to drop the primary-key index and re-add it as a
+plain UNIQUE, which postgres refuses outright.
+
+**Three cases where the planner will NOT fold the rename**, each because folding
+it could destroy data rather than move it — and none of them is silent:
+
+- **The old name is still declared by something.** If your schema still has a
+  `notes` table, it is yours and stays put; the new table is created empty. This
+  is a legitimate outcome (it is what lets a framework plugin reclaim a name
+  without taking yours), so the plan runs — and the `create-table` line says why
+  the marker was not applied.
+- **The new name already exists in the database.** → **refuses to plan.** Both
+  tables exist and only you know which holds the real rows. The fix tells you to
+  move them and drop one, or drop the empty one so the rename can run. Until
+  then the old table is untouched.
+- **Two tables both claim the same old name.** → **refuses to plan.** Nothing
+  says which should receive the rows; remove the marker from all but one.
+
+The last two refuse rather than degrade, because the quiet outcome — an empty
+plan reading "schema up to date" while the old table still holds every row — is
+the one that loses data by inaction.
+
+**Lifecycle.** Same as `.renamedFrom()` on a column: a marker whose old table is
+not in the database is a silent no-op, so it stays in your source across a staged
+rollout and comes out once every environment has applied it.
+
+**One constraint worth knowing:** a table whose name starts with `_` cannot derive
+a typeid prefix, so it needs an explicit `id({ prefix: '…' })`. You will hear about
+it at declaration, not at runtime.
+
 ## Lifecycle — when to remove the marker
 
 Keep the marker until the rename has been applied in EVERY env you care about (dev, staging, prod). The framework tracks applied ops in `_voltro_migration_plans`:
@@ -2009,7 +2111,7 @@ Drift = the live database's schema doesn't match the fingerprint of the last app
 
 Three trigger paths:
 
-1. **Manual** — `voltro db drift` runs the check on demand, exits 4 on drift
+1. **Manual** — `voltro db drift` runs the check on demand: exit 0 match, 3 no baseline, 4 drift
 2. **On boot (dev)** — every `voltro dev` boot runs the planner, which detects drift implicitly (the plan will be non-empty)
 3. **Periodic (cloud)** — the cloud dashboard polls each app's `/_voltro/inspect/migrations` endpoint; drift state is in the response
 
@@ -2018,16 +2120,39 @@ All three paths produce the same `DriftSnapshot` shape:
 ```ts
 {
   isDrifted: boolean,
-  liveFingerprint: string,             // current introspected user-schema fingerprint
-  lastAppliedFingerprint?: string,     // newest _voltro_migration_plans row's fp
+  liveFingerprint: string,             // current introspected schema fingerprint
+  lastAppliedFingerprint?: string,     // the BASELINE the newest row recorded
   lastAppliedAt?: string,              // when it was applied
   lastAppliedId?: string,              // plan id
 }
 ```
 
-`isDrifted: false` ↔ `liveFingerprint === lastAppliedFingerprint`.
+`isDrifted: false` ↔ `liveFingerprint === lastAppliedFingerprint`, **or** no baseline was recorded — nothing compared is not the same as nothing changed, and it is never reported as drift.
+
+### What it compares, and what it does not
+
+The baseline is `_voltro_migration_plans.liveFingerprint`: the fingerprint of the **live** schema as it was immediately after the last `voltro db apply`. Not `fingerprint`, which is the **declared** snapshot's hash — introspection cannot recover everything a declaration carries (generated expressions, `maxLength`, sensitivity markers), so a live hash and a declared hash never agree and comparing them reports drift on every clean database.
+
+Both sides hash the **whole** live schema, framework tables included. A framework upgrade that adds a `_voltro_*` column therefore shows as drift until the next `db apply` records a new baseline — honest, since the live schema did change, and it self-heals on the apply the upgrade needs anyway.
+
+### No baseline yet
+
+A ledger row written before `liveFingerprint` existed has no baseline, and so does a database whose schema was already current when it upgraded. `voltro db drift` says so and **exits 3**:
+
+```sh
+$ voltro db drift
+db drift: no drift baseline recorded yet — cannot compare
+```
+
+Run `voltro db apply` once — a no-op apply backfills the baseline too. Until then use `voltro db plan`, which compares declared against live directly.
 
-User-schema only: the fingerprint excludes `_voltro_*` framework tables. Bookkeeping tables grow rows + change row counts as the app runs; including them in the fingerprint would make every boot look drifted.
+**Exit 3 is deliberately not 0.** "Did not compare" is not "clean", and a CI gate on the exit code has to be able to tell them apart — otherwise it passes vacuously on a stable schema, which is the failure drift detection exists to prevent.
+
+| exit | meaning |
+|---|---|
+| 0 | compared, live matches the baseline |
+| 3 | no baseline — did NOT compare |
+| 4 | compared, live diverged |
 
 ## Common causes
 
@@ -2038,16 +2163,30 @@ Someone ran `ALTER TABLE ...` or `CREATE INDEX ...` via psql / DataGrip / Admine
 ```sh
 $ voltro db drift
 db drift: live schema DIVERGED from last applied state
-  last applied: 8f507ba1e1aadad5  at 2026-06-15 14:32:00  (plan_mig_5k78)
-  live now:     a8f2c9d10b3f4e62
+  baseline:      8f507ba1e1aadad5  at 2026-06-15 14:32:00  (plan_mig_5k78)
+  live now:      a8f2c9d10b3f4e62
+
+Something changed the live schema after the last apply. This command can see
+THAT it changed, not what or who — the fingerprints are hashes, not a diff.
 
-Probable causes:
-  - manual DDL ran out-of-band (psql session, another tool)
-  - someone applied a plan but the row never made it into _voltro_migration_plans
+Your DECLARED schema is already satisfied — `voltro db plan` reports 0 operations
+against this database. So the live schema is not wrong, only unrecorded: something
+applied a change without going through the planner (a hand-run ALTER, a DBA
+window, a restored dump), or it touched a table your code does not declare.
 
-To reconcile, run `voltro db plan` to see what your code expects vs the live DB.
+If that was deliberate and the schema is right, record it:
+
+    voltro db drift --accept
+
+It updates the latest ledger row's baseline to the live schema and invents no
+history entry. Drift then measures from here.
 ```
 
+When `db plan` is NOT empty it says that instead, with the count — so the two
+cases are told apart by the command rather than left to you. It used to close by
+asserting that a zero-operation plan meant "a table your code does not declare",
+which is one of two possibilities and the less likely one.
+
 ### Out-of-band auto-applier
 
 Multiple tools applying to the same DB (the framework + a separate Flyway / Liquibase process / hand-written deploy script). The other tool's changes don't go through `_voltro_migration_plans`.
@@ -2062,31 +2201,36 @@ The drift detector ran against a read-replica that's lagging. Wait for the repli
 
 ## Reconciliation paths
 
-### Path 1 — adopt the live state by declaring it in TS
+### Path 1 — accept the live state
 
-When the live DB IS what you want (the manual DDL is correct, only
-bypassing the planner was sloppy), bring the declared schema up to the
-live shape: edit the `*.entity.ts` files so they describe exactly what
-the live DB now has. The next `voltro db plan` then diffs empty, and a
-`voltro db apply` records a fresh `_voltro_migration_plans` row at the
-new fingerprint — re-baselining history without any DDL.
+When the live DB IS what you want (the manual DDL is correct, only bypassing the
+planner was sloppy), first make sure your declaration says so: edit the
+`*.entity.ts` files until `voltro db plan` diffs empty. Then record the live
+schema as the baseline:
 
 ```sh
-voltro db plan    # confirm the diff is now empty (declared == live)
-voltro db apply --note 'accepting manual DDL from 2026-06-15 — see ticket #789'
+voltro db plan            # must report 0 operations — declared == live
+voltro db drift --accept
 ```
 
-`voltro db apply` with an empty plan writes no DDL; it just locks in
-the current fingerprint with your note. The history shows it:
+`--accept` writes the current live fingerprint onto the newest ledger row.
+Drift measures from there, and the next `voltro db drift` exits 0.
 
-```
-plan_mig_5k79  fp=a8f2c9d1  env=dev  src=auto-diff  0 op(s)  12ms  ...  by=alice
-  [note: accepting manual DDL from 2026-06-15 — see ticket #789]
-```
+**It refuses unless `db plan` is empty**, and that guard is the whole point.
+Accepting a schema with operations still outstanding would record "this is what
+we applied" over a state nobody applied, and every later drift check would
+measure against that fiction. If operations are pending, run `voltro db apply` —
+that applies them AND writes a real baseline of its own.
+
+It backfills the newest row rather than inserting one, because no migration ran
+and a history entry claiming otherwise would be worse than the gap it fills.
 
-There is no metadata-only `--reconcile` flag — re-baselining always
-goes through the declare-then-apply loop, so the TS schema stays the
-single source of truth.
+**An empty `voltro db apply` does NOT re-baseline an existing baseline.** It
+writes no DDL and no history row, so there is nothing for a `--note` to attach
+to — it will tell you the note was ignored rather than swallow it. (It does fill
+a baseline that is still NULL, which is a different case: a database that never
+had one.) `--accept` is the command whose job is to say "the live schema is
+right, the ledger just did not know".
 
 ### Path 2 — corrective plan against drift
 
@@ -2184,7 +2328,7 @@ The hardest part of drift response is figuring out **what** changed + **who** di
 ```
 Detect:    voltro db drift
 Fix code:  voltro db apply   (apply corrective plan from current diff)
-Adopt DB:  edit the *.entity.ts to match live, then voltro db apply (empty plan re-baselines)
+Adopt DB:  edit the *.entity.ts to match live until db plan is empty, then voltro db drift --accept
 Backup:    if data was lost, restore from your DB backup system — the framework can't help
 ```
 

package/templates/agent-docs/database/schema.md

@@ -73,6 +73,13 @@ Plain `text()` is **unbounded** — `TEXT` on Postgres/SQLite, `LONGTEXT` on MyS
 
 Reach for **`.maxLength(n)`** when the column is a short identifier (a kind, slug, external id, resource discriminator) that participates in a `.unique([...])` or composite `.index([...])`: an unbounded column can only back a HASH long-unique constraint (MariaDB) or a prefix index, whereas a bounded `VARCHAR(n)` takes a plain BTREE key. It's cross-dialect (`VARCHAR(n)` on Postgres/MySQL/MariaDB, `NVARCHAR(n)` on MSSQL, `TEXT` on SQLite) — unlike `raw('varchar(20)')`, which hardcodes one dialect's DDL.
 
+**Changing the bound on an EXISTING column is a real migration.** The differ compares `maxLength` on both sides, so `text()` → `text().maxLength(64)`, or 64 → 128, produces an operation:
+
+- **widening** (a larger bound, or dropping the bound) is `safe` — no value can be lost;
+- **narrowing** is `needs-backfill`: the `ALTER` fails at the database for any existing value longer than the new bound. The plan says so and gives you the query to run first.
+
+Not compared on SQLite, which has no length-enforced type — a declared bound there is real, the live column is always `TEXT`, and comparing them would re-plan the same ALTER on every boot.
+
 For **value** constraints (length ranges, regex, email, numeric min/max, cross-field invariants), use table-level `table().validate(Schema)` (see below) — that's the single validation surface, not a pile of per-column modifiers. There are no `.minLength()` / `.pattern()` column modifiers by design.
 
 ### `integer()`

package/templates/agent-docs/database/seedsdialects.md

@@ -996,7 +996,7 @@ If you write hand-rolled queries that read JSON columns through `unsafe()`, you'
 > then applies it. Idempotent, and a no-op on every other dialect. Without it,
 > workflow message/runner storage misbehaves on SQL Server.
 
-`@effect/cluster`'s mssql branch uses `sp_getapplock` for shard claims and `MERGE … WHEN NOT MATCHED THEN INSERT … OUTPUT INSERTED` for runner upserts. Four bugs in `@effect/cluster@0.59.0` mssql code paths fail under the framework's workflow stack; the framework carries a `pnpm patch` (shipped in the CLI at `packages/cli/templates/patches/@effect__cluster@0.59.0.patch`, written into your project by `voltro add mssql`):
+`@effect/cluster`'s mssql branch uses `sp_getapplock` for shard claims and `MERGE … WHEN NOT MATCHED THEN INSERT … OUTPUT INSERTED` for runner upserts. Four bugs in `@effect/cluster@0.60.0` mssql code paths fail under the framework's workflow stack; the framework carries a `pnpm patch` (shipped in the CLI at `packages/cli/templates/patches/@effect__cluster@0.60.0.patch`, written into your project by `voltro add mssql`):
 
 ### Patch 1 — SqlRunnerStorage shard-lock MERGE alias
 
@@ -1024,7 +1024,7 @@ MSSQL forbids subqueries inside OUTPUT clauses (Msg 10705). The original `insert
 
 The cluster's `deliver_at` column is BIGINT (storing millisecond epoch). Tedious binds JS `number` parameters as INT — which overflows for any post-2001 timestamp. The patch casts `deliver_at` to `BigInt` once at the top of `envelopeToRow` so all three message-kind switch arms emit `bigint | null`; other dialects accept bigint fine.
 
-All four patches are dialect-keyed (touch only the `mssql:` branch of `sql.onDialectOrElse`) so postgres / mysql / sqlite paths are bit-identical to upstream. The framework carries them and ships them to your project via `voltro add mssql` (see the note at the top of this section) — there is no newer `@effect/cluster` to bump to (0.59.0 is the latest), so the patch is how the fix reaches you.
+All four patches are dialect-keyed (touch only the `mssql:` branch of `sql.onDialectOrElse`) so postgres / mysql / sqlite paths are bit-identical to upstream. The framework carries them and ships them to your project via `voltro add mssql` (see the note at the top of this section) — the patch is how the fix reaches you. Upstream still carries these bugs on the current release — the framework re-verifies that on every bump (`git apply --check` against the new tarball) and re-keys the patch, because a `patchedDependencies` key is version-exact and a stale one fails the install.
 
 ## Read replicas — Always-On Availability Groups
 
@@ -1088,7 +1088,7 @@ For a full before-image or per-op fidelity, use **mariadb** (binlog CDC). For ze
 - `voltro/packages/sql-mssql/src/replicationAdapter.ts` — `end_of_log_lsn` / `last_hardened_lsn` compare for RYW
 - `voltro/packages/database/src/sqlCompiler.ts` — TOP / FETCH NEXT dispatch
 - `voltro/packages/database/src/migrate.ts` — mssql DDL branch (line 72)
-- `packages/cli/templates/patches/@effect__cluster@0.59.0.patch` — the four upstream patches (shipped in the CLI; `voltro add mssql` writes it into your project)
+- `packages/cli/templates/patches/@effect__cluster@0.60.0.patch` — the four upstream patches (shipped in the CLI; `voltro add mssql` writes it into your project)
 
 
 

package/templates/agent-docs/plugins.md

@@ -92,7 +92,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-openapi` | ✓ | OpenAPI 3.1 spec (`GET /openapi.json`) + Swagger-UI (`GET /docs`) generated from `defineRestRoute` descriptors AND (opt-in) rpc procedures (queries/mutations/actions/streams → `POST /rpc/<name>`) — input/output/error Schemas via `JSONSchema.make`. [→ details](/docs/plugins/openapi) |
 | `@voltro/plugin-versioning` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete on listed tables into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/versioning) |
 | `@voltro/plugin-presence` | ✓ | Ephemeral realtime presence — heartbeat roster per channel (`presence.heartbeat`/`list`/`leave` + `usePresence`), a `useTyping` typing indicator, swept `_voltro_presence` table, cross-instance. [→ details](/docs/plugins/presence) |
-| `@voltro/plugin-scim` | ✓ | SCIM 2.0 provisioning — Users + Groups REST at `/scim/v2` (bearer-gated) incl. group-membership PATCH/PUT + the RFC 7644 discovery trio (ServiceProviderConfig/Schemas/ResourceTypes), `userName`/`externalId`/`displayName eq` filters, pagination, unique `userName`, `active:false` deactivation; `scim_users`/`scim_groups`. [→ details](/docs/plugins/scim) |
+| `@voltro/plugin-scim` | ✓ | SCIM 2.0 provisioning — Users + Groups REST at `/scim/v2` (bearer-gated) incl. group-membership PATCH/PUT + the RFC 7644 discovery trio (ServiceProviderConfig/Schemas/ResourceTypes), `userName`/`externalId`/`displayName eq` filters, pagination, unique `userName`, `active:false` deactivation; `_voltro_scim_users`/`_voltro_scim_groups`. [→ details](/docs/plugins/scim) |
 | `@voltro/plugin-sso-saml` | ✓ | Enterprise SAML 2.0 SSO — SP-initiated login + Single Logout (both directions) + ACS + SP metadata under `/saml`; IdP-metadata-URL auto cert rotation, encrypted assertions, clock-skew, SP request signing. Signature verify via `@node-saml/node-saml` (optional+lazy), mints a framework session. [→ details](/docs/plugins/sso-saml) |
 
 API keys are **first-class** (not a plugin): `apiKeys: true` in `app.config.ts` → Bearer-key auth + admin-gated `/v1/api-keys` management, hash-only storage. [→ details](/docs/configuration/api-keys)

package/templates/agent-docs/schema-driven-ui.md

@@ -143,7 +143,7 @@ create-vs-update: they're *different mutations with different input schemas*, so
 they're naturally different forms — no "CRUD mode" switch.
 
 ```tsx
-import { AutoForm } from '@voltro/web'
+import { AutoForm } from '@voltro/ui'
 
 // fields from the mutation's input schema; client+server share the schema;
 // submits via the mutation with op-correct optimistic (insert prepends, etc.)
@@ -177,7 +177,7 @@ A combined create-or-edit screen is a three-line wrapper:
   object → a `custom` placeholder asking for a render-prop.
 - **Rung 1 — one custom widget** via a `<Field>` render-prop:
   ```tsx
-  import { AutoForm, Field, AsyncSelect } from '@voltro/web'
+  import { AutoForm, Field, AsyncSelect } from '@voltro/ui'
 
   <AutoForm api="app" mutation="todos.create">
     {() => (

package/templates/agent-docs/templates/apibackends.md

@@ -2056,7 +2056,7 @@ curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
 # → { "ok": false, "error": { "_tag": "EntitlementExceeded", "entitlement": "projects", "limit": 3, "used": 3 } }
 ```
 
-Each successful create also logs `[notify:project] → …: Project created` (console channel) and persists a `notification_inbox` row.
+Each successful create also logs `[notify:project] → …: Project created` (console channel) and persists a `_voltro_notification_inbox` row.
 
 ## Enable durable analytics