@voltro/cli 0.22.1 → 0.24.0

package/templates/agent-docs/deployment.md

@@ -918,6 +918,44 @@ under `NODE_ENV=production` (it refuses unless both fingerprints still match the
 reviewed plan). A Job runs **once per release** vs an `initContainer`'s once per
 replica, so it's the better fit for a multi-replica rollout.
 
+### Expand/contract — the migration that's safe while old pods still serve
+
+The pre-deploy Job applies the schema **before the new pods roll** — so during a
+rolling update, old pods (old code) run against the already-migrated schema for
+the length of the rollout. A migration that DROPS or RENAMES a column, NARROWS a
+type, or ADDS a constraint breaks those old pods mid-rollout: they 500 reading a
+column that's gone, or their writes are rejected by the new constraint. The
+migration "succeeded" and the app served errors anyway.
+
+`voltro db plan` flags these — the operations unsafe under a rolling deploy are
+listed with a `⚠`, separately from the data-safety (lossy / blocked) gate, since
+the two are orthogonal: a `dropped()` column is blessed for data loss and *still*
+breaks an old reader.
+
+```text
+⚠ 1 operation(s) UNSAFE under a rolling deploy
+  (old + new instances overlap → old code breaks against the new schema):
+    • drop-column: old instances still SELECT/INSERT "orders"."legacy_total"; …
+      → stop reading the column in code and deploy that first; drop it in a LATER deploy
+```
+
+Two ways to handle it:
+
+1. **No overlap window** — a maintenance-window or **scale-to-zero** deploy (old
+   pods gone before new ones start) has no simultaneous old code, so a single-step
+   drop/rename is fine. The advisory doesn't apply; ignore it.
+2. **Zero-downtime rollout** — split the breaking change into two releases, each
+   of which keeps *both* code versions working (**expand/contract**):
+   - **Expand** (release N): add the new shape — a nullable column, a new table,
+     a backfill, dual-write from the new code. Old code ignores it.
+   - **Cut over**: the new code reads/writes the new shape; deploy it.
+   - **Contract** (release N+1): once no pod runs the old code, drop/rename/narrow
+     the now-unused old shape. This step's `db plan` is clean.
+
+Renaming `orders.total` → `orders.amount` under zero downtime is: add `amount`
+(expand) → backfill + dual-write → cut reads over → drop `total` (contract) — three
+releases, never one, so no in-flight pod ever references a column that isn't there.
+
 ### If you DO run `voltro dev` in a cluster (dev / staging only)
 
 `voltro dev` binds a small **boot-health surface** on its own port so a probe can
@@ -1059,6 +1097,33 @@ that route to a terminating pod before k8s finishes removing it from the Service
 endpoints. With it, that window is drained. `terminationGracePeriodSeconds` must
 be larger than the sleep plus the app's own teardown, or k8s SIGKILLs mid-drain.
 
+**Bound the app's own teardown with `VOLTRO_SHUTDOWN_GRACE_MS`.** After
+`SIGTERM`, the runtime runs its finalizers (pool close, plugin `onDeactivate`,
+analytics flush, trace persist) and then exits — but installing the signal
+handler removes node's default kill, so a finalizer that *never* completes (a
+pool drain against a database that is already gone, a wedged `onDeactivate`)
+would otherwise hang the process forever. A hard deadline caps that: teardown
+gets until the deadline, then the process exits regardless. It defaults to
+**10s**; set `VOLTRO_SHUTDOWN_GRACE_MS` (clamped to 1s–5min) to sit JUST UNDER
+your `terminationGracePeriodSeconds` minus the preStop sleep — so the app drains
+and exits *cleanly on its own* before k8s SIGKILLs it mid-drain:
+
+```yaml
+spec:
+  terminationGracePeriodSeconds: 30
+  containers:
+    - name: api
+      env:
+        # preStop sleep (5s) + app teardown (≤22s) < 30s grace, with headroom.
+        - name: VOLTRO_SHUTDOWN_GRACE_MS
+          value: "22000"
+```
+
+The close is clean on the client side too: on shutdown each live WebSocket is
+closed with a proper close frame (not an abrupt socket drop), and the web
+client's supervisor reconnects on any close — so an open dashboard re-attaches
+to a healthy replica across a rolling deploy without a page reload.
+
 ## 8. Multiple replicas
 
 Cache and KV default to **in-process** (per-replica). For a shared backend across replicas:
@@ -1087,7 +1152,7 @@ Schedules and aggregates auto-coordinate via an advisory lock on SQL stores —
 - [ ] `auth.anonymousTenantRequired: true` (unless the app serves anonymous public data)
 - [ ] `OTEL_EXPORTER_OTLP_ENDPOINT` + `OTEL_SERVICE_NAME` pointed at your collector
 - [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors
-- [ ] `terminationGracePeriodSeconds` generous for graceful drain
+- [ ] `terminationGracePeriodSeconds` generous for graceful drain; `VOLTRO_SHUTDOWN_GRACE_MS` set just under it (minus the preStop sleep)
 - [ ] `CACHE_BACKEND` / `KV_BACKEND` + a cross-replica change bus when running >1 replica
 
 

package/templates/agent-docs/plugins.md

@@ -132,6 +132,48 @@ Order matters: the framework composes outer→inner, so the rate-limit intercept
 | `onInstall` / `onActivate` / `onDeactivate` / `onUninstall` | Lifecycle hooks at first-install, boot, shutdown, and removal. |
 | Schema mixins (`defineMixin`) | The OTHER plugin shape — `audit()`, `tenant()`, `softDelete()` — declared in `@voltro/database`, not via the runtime contract. |
 
+## Pointing YOUR table at a plugin's row
+
+Every table-carrying plugin exports its table handles, so a column in your schema
+can reference one exactly like it references your own:
+
+```ts
+import { aiFlowsTable } from '@voltro/plugin-ai-flows'
+import { id, reference, table, text } from '@voltro/database'
+
+export const flowFavourites = table('flow_favourites', {
+  id:       id({ prefix: 'fav' }),
+  employeeId: reference(() => employees, { onDelete: 'cascade' }),
+  // A real foreign key across the plugin boundary. Deleting the flow removes
+  // the favourite; the DATABASE enforces it, so no cleanup subscriber exists to
+  // forget.
+  flowId:   reference(() => aiFlowsTable, { onDelete: 'cascade' }),
+  note:     text().nullable(),
+})
+```
+
+This is not a special primitive — it is `reference()`, with the same
+`onDelete` semantics and the same index defaults. `plugin-storage`'s `assetRef()`
+has always been exactly this under the hood: a `reference(() => _voltroStorageRefsTable,
+{ onDelete: 'setNull' })`.
+
+**Referencing the table as a VALUE rather than its name as a string is what makes
+this safe across a plugin's own migrations.** When ten plugin tables moved into
+the `_voltro_` namespace in 0.22.0, a `reference(() => table)` followed the rename
+(catalog-only, the constraint travels with the table); a hand-written
+`text()` column holding ids would not have told you anything had changed.
+
+**`fk: false`-style decoupling is still available** — declare a plain `text()`
+column instead. Choose it when you deliberately want the app schema independent
+of the plugin's, and accept that nothing then enforces the link. What you should
+NOT do is reach for it by default: an unenforced id column plus a hand-written
+`defineSubscriber` that cleans up on delete is referential integrity re-implemented
+per app, and it is silently wrong the first time somebody forgets it.
+
+**`orphanPolicy` is not part of this.** It is migration metadata — how existing
+orphan rows are cleaned up *before* the FK constraint is added — and has no
+runtime semantics. Runtime behaviour comes from `onDelete`.
+
 ## When NOT to write a plugin
 
 - **One-off side effect** — just call it from the mutation directly.

package/templates/agent-docs/routing.md

@@ -961,6 +961,7 @@ React alone.
 export const loader = async (ctx: {
   readonly params:   Readonly<Record<string, string>>  // URL params from [name] segments
   readonly pathname: string                             // matched path (no query string)
+  readonly search:   string                             // raw query string incl. `?`, or '' — filled on every path
   readonly signal:   AbortSignal                        // Aborts if the client disconnects mid-render
   readonly headers?: Readonly<Record<string, string>>  // Request headers (SSR/ISR only — empty for SSG/client)
   // Call the backend rpc directly — present ONLY when the loader runs
@@ -970,7 +971,28 @@ export const loader = async (ctx: {
 }) => Promise<unknown>
 ```
 
-The loader context carries `pathname`, not a `request` object. For the query string during SSR, read it from `useServerRequest().url` inside the component.
+The loader context carries `pathname` and `search`, not a `request` object.
+
+`pathname` is deliberately query-free — a loader keyed on `?tab=2` would cache badly. `search` carries the raw query string (with its leading `?`, or `''`), filled identically on client navigation, `voltro dev` SSR and `voltro start` SSR. Parse it with `new URLSearchParams(ctx.search)`.
+
+**Reach for `search` when the loader makes a decision, not when it fetches data.** The case it exists for is a redirect target that depends on a parameter:
+
+```ts
+import { RedirectError } from '@voltro/web'
+
+export const loader = async (ctx) => {
+  const player = await ctx.query('players.byCode', { code: ctx.params['playerCode'] })
+  if (!player) {
+    // Preserve kiosk mode across the redirect — otherwise a kiosk terminal
+    // drops back to normal mode after every failed scan.
+    const mode = new URLSearchParams(ctx.search).get('mode')
+    throw new RedirectError(`/?error=${ctx.params['playerCode']}${mode ? `&mode=${mode}` : ''}`)
+  }
+  return { player }
+}
+```
+
+Do not reconstruct this from `window.location.search`: that exists only on the client-navigation path, so a fresh SSR request loses the value — which is the bug the field was added to remove.
 
 Use `signal` for any fetch that could outlive the request — pass it to `fetch(url, { signal })` so cancelled requests don't waste CPU.
 

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

@@ -2850,7 +2850,7 @@ voltro create-project acme --api=api-versioning
 // app.config.ts
 import { versioningPlugin } from '@voltro/plugin-versioning'
 export default { type: 'api', name: 'AcmeVer', store: 'memory',
-  plugins: [versioningPlugin({ tables: ['documents'] })] }
+  plugins: [versioningPlugin({})] }
 ```
 
 The snapshotting is automatic. The point is to **read history through handlers** — the template ships two actions:
@@ -2898,7 +2898,7 @@ The memory history store is single-process. With a SQL store, history persists i
 
 ## Anti-patterns
 
-- **Listing `versioningPlugin({ tables })` and stopping there.** That records history but never shows it. The value is in the READS — wire `rowHistory` / `rowAsOf` into a handler (or the dashboard) like this template does.
+- **Listing `versioningPlugin()` and stopping there.** That records history but never shows it. The value is in the READS — wire `rowHistory` / `rowAsOf` into a handler (or the dashboard) like this template does.
 - **Versioning every table.** Snapshots cost storage proportional to write volume. Pick the tables whose past values you actually need.