@voltro/cli 0.32.0 → 0.33.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { ct as e } from "./inspectMetrics-BqO4E9G0.js";
+import { ct as e } from "./inspectMetrics-1xzTKAFx.js";
 import { c as t } from "./seedRunner-Bqxgp7HZ.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-PxMmn96o.js";
+import { t as r } from "./serveCommand-DdaM4Hup.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-D1-8eKrO.js → start-C0koT0UO.js}

@@ -1,4 +1,4 @@
-import { $ as e, C as t, Ct as n, D as r, E as i, G as a, J as o, K as s, L as c, P as l, Q as u, S as d, St as ee, Tt as f, V as p, W as m, _ as h, _t as g, a as _, b as v, bt as y, c as b, dt as te, f as x, ft as S, g as C, h as w, i as T, k as E, m as D, mt as O, o as ne, p as re, pt as k, q as ie, r as A, s as j, t as M, ut as N, v as ae, wt as oe, x as P, y as F } from "./inspectMetrics-BqO4E9G0.js";
+import { $ as e, C as t, Ct as n, D as r, E as i, G as a, J as o, K as s, L as c, P as l, Q as u, S as d, St as ee, Tt as f, V as p, W as m, _ as h, _t as g, a as _, b as v, bt as y, c as b, dt as te, f as x, ft as S, g as C, h as w, i as T, k as E, m as D, mt as O, o as ne, p as re, pt as k, q as ie, r as A, s as j, t as M, ut as N, v as ae, wt as oe, x as P, y as F } from "./inspectMetrics-1xzTKAFx.js";
 import { A as se, E as I, O as ce, a as le, k as L, m as ue } from "./inspect-BUUjt773.js";
 import { t as de } from "./bootTiming-BdyP9nYw.js";
 import { dirname as fe, extname as pe, join as R, resolve as z } from "node:path";

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { ct as e } from "./inspectMetrics-BqO4E9G0.js";
-import { t } from "./start-D1-8eKrO.js";
+import { ct as e } from "./inspectMetrics-1xzTKAFx.js";
+import { t } from "./start-C0koT0UO.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -50,7 +50,8 @@
       "types": "./dist/startEntry.d.ts",
       "import": "./dist/startEntry.js",
       "default": "./dist/startEntry.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -363,6 +364,18 @@
         "title": "`auditPlugin` now redacts `outcome` by default — opt out if your trail reads it",
         "kind": "manual"
       },
+      {
+        "version": "0.33.0",
+        "id": "0.33.0/01_opentelemetry-optional-peer",
+        "title": "`@effect/opentelemetry` is now an optional peer — install it if you use tracing",
+        "kind": "manual"
+      },
+      {
+        "version": "0.33.0",
+        "id": "0.33.0/02_coordinated-handle-gained-wake",
+        "title": "`CoordinatedScheduleHandle` gained `wake()`, `currentIntervalMs()` and `isArmed()` — update hand-written test doubles",
+        "kind": "manual"
+      },
       {
         "version": "0.4.0",
         "id": "0.4.0/01_rbac-forbidden-to-scopeerror",
@@ -462,22 +475,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.32.0",
-    "@voltro/cache": "0.32.0",
-    "@voltro/data-transfer": "0.32.0",
-    "@voltro/database": "0.32.0",
-    "@voltro/env": "0.32.0",
-    "@voltro/kv": "0.32.0",
-    "@voltro/logger": "0.32.0",
-    "@voltro/plugin-auth": "0.32.0",
-    "@voltro/plugin-broadcast": "0.32.0",
-    "@voltro/plugin-mail": "0.32.0",
-    "@voltro/plugin-storage": "0.32.0",
-    "@voltro/plugin-webhooks": "0.32.0",
-    "@voltro/protocol": "0.32.0",
-    "@voltro/runtime": "0.32.0",
-    "@voltro/serverless": "0.32.0",
-    "@voltro/workflow": "0.32.0",
+    "@voltro/ai": "0.33.0",
+    "@voltro/cache": "0.33.0",
+    "@voltro/data-transfer": "0.33.0",
+    "@voltro/database": "0.33.0",
+    "@voltro/env": "0.33.0",
+    "@voltro/kv": "0.33.0",
+    "@voltro/logger": "0.33.0",
+    "@voltro/plugin-auth": "0.33.0",
+    "@voltro/plugin-broadcast": "0.33.0",
+    "@voltro/plugin-mail": "0.33.0",
+    "@voltro/plugin-storage": "0.33.0",
+    "@voltro/plugin-webhooks": "0.33.0",
+    "@voltro/protocol": "0.33.0",
+    "@voltro/runtime": "0.33.0",
+    "@voltro/serverless": "0.33.0",
+    "@voltro/workflow": "0.33.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -652,7 +652,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.32.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.33.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.32.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.33.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

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

@@ -225,6 +225,43 @@ Precedence, exactly:
 3. **`.safe()`** on an encrypted column suppresses the implied secret and copies
    it verbatim — say this only when you have genuinely reviewed the plaintext.
 
+## Encrypting a column that already has rows
+
+`.encrypted()` encrypts on **write**. Adding it to a populated column converts
+nothing that is already stored — those rows stay plaintext until something
+rewrites them, which for a credential column may be never.
+
+```sh
+voltro db encrypt-column integrations.webhookSecret --dry-run
+voltro db encrypt-column integrations.webhookSecret employees.meilisearchKey --yes
+```
+
+It reads `FIELD_ENCRYPTION_KEY` (or `--key-env NAME`) and must be **the same key
+your app runs with** — the one you pass to
+`governancePlugin({ fieldEncryption: { key } })`.
+
+**Order does not matter.** A read returns a non-ciphertext value unchanged, so
+the column may hold a mix while you deploy: run the command before or after the
+release that adds `.encrypted()`, and run it again afterwards to catch anything
+written in between. It skips what is already encrypted, which also means an
+interrupted run is resumed by running it again.
+
+Five things it refuses to do, each of them a way a hand-written `UPDATE` goes
+wrong quietly:
+
+| It checks | Because |
+|---|---|
+| already-ciphertext values are skipped | double encryption cannot be undone without the key history |
+| the value decrypts back before the write | a broken cipher otherwise fails on the first *read*, when the plaintext is gone |
+| the key matches what the column already holds | a *different* key round-trips fine; resuming with one leaves a column readable with neither key alone |
+| the column is wide enough | ciphertext is `49 + 4×ceil(bytes/3)` characters — a 64-char key needs 137, and a `varchar(100)` fails partway through |
+| `--yes` is present | it rewrites a column in place |
+
+The width figure is in **bytes**, not characters: `'ä'.repeat(10)` is 10
+characters and 20 bytes, and encrypts to 77.
+
+No value — plaintext or ciphertext — is ever printed. The report is counts.
+
 ## `.serverOnly()` — never to a client
 
 A THIRD, independent axis. `.sensitive()` / `.safe()` are about **data export

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

@@ -748,9 +748,11 @@ ctx.store.select('inviteLinks').includeExpired()
 | | where | when |
 | --- | --- | --- |
 | **Invisible to reads** | every dialect | immediately, the instant it passes |
-| **Physically deleted** | postgres only | eventually, by the retention sweep |
+| **Physically deleted** | every dialect | eventually, by the retention sweep |
 
-So an expired row is **invisible everywhere and still present in the database on four of five dialects**. That is the right trade — making visibility depend on the sweep would mean a row that vanished on postgres and kept serving on MariaDB — but it is a surprising one, and it matters: *do not treat an expired row as unreachable*. If the value must actually be gone, delete it, or do not store it in a row at all.
+So an expired row is **invisible immediately and still present in the database for a while**. That is the right trade — making visibility depend on the sweep would mean a row that vanished on postgres and kept serving on MariaDB — but it matters: *do not treat an expired row as unreachable*. If the value must actually be gone, delete it, or do not store it in a row at all.
+
+The second row of that table used to say **postgres only**, and it was accurate: the sweep was registered behind a `dialect !== 'postgres'` early return, so on mariadb, mysql, mssql and sqlite nothing was ever deleted and the boot printed no armed-policies line to say so. What is postgres-specific is the fast set-based DELETE, not the policy — the sweep falls back to a bounded read plus one set-based delete per batch elsewhere. Fixed in 0.33.0; on those dialects the first boot after upgrading will have a backlog to work through.
 
 ## See also
 

package/templates/agent-docs/deployment.md

@@ -1168,13 +1168,38 @@ scaled. An operator's second pod died on `Connection timed out` for exactly
 this. `voltro serve` now prints the number and the arithmetic at boot:
 
 ```
-db pool: max=10 per replica (DB_MAX_CONNECTIONS) × 4 replicas = up to 40 connections.
+db pool: max=10 per replica (DB_MAX_CONNECTIONS) + 1 = 11 × 4 replicas = up to 44 connections.
+Check that against your database's limit. PLUS 1 outside the pool (CDC LISTEN consumer) —
+those do not come out of the pool budget, they come out of the DATABASE's.
 ```
 
 Set `REPLICA_COUNT` from your deployment (Helm: `{{ .Values.replicaCount }}`) and
 the line does the multiplication for you; without it the line still names the
 formula. `voltro dev` deliberately does not print it — one process, no replicas.
 
+**Some connections are not in the pool, and the count is per process.** A
+connection running `LISTEN` cannot be returned to a pool, so the driver opens a
+standalone one. There are three such places and a full deployment can hold all
+three:
+
+| Process | Connection | When |
+|---|---|---|
+| api `voltro serve` | CDC `LISTEN` consumer | `changeStrategy: 'cdc'` (the default on postgres) |
+| web `voltro start` | ISR invalidator `LISTEN` | any page declares `cacheInvalidatesOn` |
+| web `voltro start` | postgres ISR cache client | `SSR_CACHE=postgres` |
+
+The third is not a `LISTEN` at all, which is why counting `LISTEN` rows in
+`pg_stat_activity` undercounts. Each process prints its own number in the boot
+line above — including `No connections outside the pool in this process` when
+there are none, so "counted, zero" is distinguishable from "not counted".
+
+**And a rolling update needs the surge pod's connections too.** A budget sized
+for `replicaCount` is exactly full at steady state and short during every
+deploy: `maxSurge` adds a pod that opens a full pool of its own. If that pod
+cannot connect it never becomes ready, so the rollout does not complete and the
+cluster stays at the higher pod count — the deploy cannot free itself. Size for
+`(replicaCount + maxSurge) × (DB_MAX_CONNECTIONS + out-of-pool)`.
+
 **`POD_IP` is each replica's identity, not only a workflow setting.**
 
 ```yaml
@@ -1203,6 +1228,67 @@ operator's own guidance, and better than ours was: a value taken from the
 release namespace cannot be left out of one environment's config file, because
 there is no file to forget.
 
+### The framework's own background pollers
+
+Two framework tasks ride the coordinated scheduler and write a row into
+`_voltro_schedule_claims` on every tick they win: the workflow **admission
+drainer** and the offloaded-**inference dispatcher**.
+
+**Where a peer replica's write is visible here, they do not poll at all.** Each
+runs one tick at startup — not optional; it is what finds work a previous
+process left behind — and then stops until something arrives. The wake comes
+from the change events their queue tables already emit, which is the same
+mechanism the rest of the framework's reactivity runs on. Measured against a
+real Postgres on a deployment that never uses either queue: **2 claim rows in
+five minutes**, one per task, both written at boot.
+
+That "where" is the whole condition, and it is satisfied by Postgres
+LISTEN/NOTIFY or by a broadcast broker (Redis/NATS — which a multi-replica
+deployment already runs for cross-replica reactivity). Without either, a
+*remote* replica's enqueue produces no local event, so stopping would mean
+sleeping through it. There the tasks back off to a ceiling instead:
+
+```sh
+VOLTRO_POLL_CEILING_MS=30000   # how long an arrival can wait when NOTHING woke the task
+```
+
+Nothing is lost in that case either — the replica that enqueued always sees its
+own write inline and drains it itself. What the ceiling covers is the narrower
+case of a *crashed* writer's lease being reclaimed by someone else.
+
+A number worth knowing before you tune anything: on a two-replica deployment
+that had never enqueued into either queue, these two tasks accounted for **99.3 %
+of the claim ledger** — 2 506 rows an hour against 18 from the app's own eight
+schedules. A fixed interval has no way to learn a queue is empty. That is what
+changed; the ceiling is the fallback, not the fix.
+
+### Tuning the cadence
+
+The intervals are declarable, with defaults most apps never change:
+
+```ts
+// app.config.ts
+export default {
+  scheduling: {
+    admissionDrainMs: 1000,   // workflow admission drainer
+    inferenceTickMs:  250,    // offloaded-inference dispatcher
+    cancelSweepMs:    2000,   // cancelOn sweep
+    pollCeilingMs:    30000,  // idle ceiling, where nothing can wake a task
+  },
+}
+```
+
+Each has a matching env var — `VOLTRO_ADMISSION_DRAIN_MS`,
+`VOLTRO_INFERENCE_TICK_MS`, `VOLTRO_CANCEL_SWEEP_MS`, `VOLTRO_POLL_CEILING_MS` —
+which **overrides** the config field, the same way `VOLTRO_TENANT_ISOLATION`
+overrides `tenancy.isolation`. The config is what a project declares; the env var
+is what an operator changes on a running deployment without a rebuild.
+
+Lowering an interval does **not** make anything more responsive: an arrival
+already wakes the task at once. It only bounds the case where nothing announced
+the work. A value of `0` or a non-number is ignored rather than honoured — a
+zero interval would turn an idle task into a spin.
+
 ### Workflow failover across replicas
 
 On a **SQL store** (postgres / mysql / mariadb / mssql), durable workflows survive a replica crash: completed `step({...})` activities are checkpointed in the cluster journal, so when a replica dies mid-run, a **surviving replica takes over the run and continues it from the last completed step** — it replays the completed steps rather than re-running them. (On sqlite the engine is single-process — durable within one replica, no cross-replica failover.) Two requirements:

package/templates/agent-docs/plugins.md

@@ -967,6 +967,56 @@ framework's ALREADY-OPEN handles so it never rebuilds them:
   one process needs no fan-out dedup). Returns a handle whose `stop()`
   cancels the task; the framework also stops every armed task at shutdown.
 
+  Each tick claims one row in `_voltro_schedule_claims`, so the interval you
+  pick is also a write rate: `250` is four rows per second, per task, fleet-wide.
+
+  **The interval is a floor, not a cadence — if you report idleness.** Return
+  `{ idle: true }` from the effect on a tick that found nothing to do, and the
+  runner backs off toward a 30 s ceiling (`VOLTRO_POLL_CEILING_MS`) instead of
+  ticking at your interval forever. Return nothing and the tick keeps its fixed
+  interval, which is the safe default for a task that cannot tell.
+
+  **Or stop it entirely.** Pass `{ disarmWhenIdle: true }` as a fourth argument
+  and an idle tick with nothing pending stops the timer altogether — the task
+  runs once at startup and then only when `wake()` says so. That is the
+  difference between a cheaper poller and no poller, and it is what the
+  framework's own two background tasks do.
+
+  Only pass it when an arrival is **guaranteed** to call `wake()`. That is a
+  claim about the deployment, not the task: with Postgres LISTEN/NOTIFY or a
+  broadcast broker every replica sees every write, so it holds. Without either,
+  a peer replica's enqueue produces no local event and a disarmed task would
+  sleep through it — the backoff ceiling is the correct choice there.
+
+  Two more fields make that affordable rather than a latency tax:
+
+  - `handle.wake()` runs a tick **now**. Wire it to whatever announces work —
+    a `store.onChange` on the queue table your plugin drains — and the work
+    starts on arrival rather than up to one interval later. Calls are coalesced
+    to at most one extra tick per interval, so calling it per row is fine.
+  - `{ idle: true, nextDueInMs }` caps the backoff. Return it when the task is
+    idle right now but already knows something is coming (a window closing, a
+    lease expiring); the next tick lands on that instant instead of on the
+    ceiling.
+
+```ts
+const outbox = ctx?.scheduleCoordinated('vendor.outbox', 1_000, async () => {
+  const sent = await drainOutbox()
+  return { idle: sent === 0 }
+}, { disarmWhenIdle: true })
+
+store.onChange((event) => {
+  if (event.table === 'vendor_outbox' && event.op === 'insert') outbox?.wake()
+})
+```
+
+  Why this exists: two framework tasks polled permanently-empty queues on a
+  consumer's deployment and wrote **2 506 claim rows an hour** between them,
+  against 18 from the app's own eight schedules. A fixed interval has no way to
+  learn that a queue is empty. Without a `wake()` source the ceiling is your
+  worst-case latency, so a task whose arrivals cannot announce themselves should
+  keep reporting nothing.
+
 ```ts
 import { definePlugin } from '@voltro/protocol'
 

package/templates/agent-docs/scheduling.md

@@ -346,7 +346,10 @@ replica B ─┼─ same bucket, same key ─┤
 replica C ─┘                          └─ PK conflict → stands down (no run row)
 ```
 
-- **Self-expiring.** The key includes the firing instant, so a crashed winner doesn't block the next firing — the next firing instant is a new key. Stale rows are pruned lazily.
+- **Self-expiring.** The key includes the firing instant, so a crashed winner doesn't block the next firing — the next firing instant is a new key.
+- **A claim does not outlive its bucket.** When a replica wins a claim it deletes that schedule's own older rows in the same pass, so the table's steady-state size is a small multiple of the number of schedules rather than a function of uptime. How far back it prunes scales with how far apart that caller's buckets are — a cron keeps roughly an hour of predecessors, a 250 ms coordinated task about a minute. The grace exists because deleting a claim too early is a **double fire**: a replica that is running late must still find the row that says its bucket was taken.
+- **Swept, on the scale it fills — on every dialect.** `_voltro_schedule_claims` gets a retention policy on both boot paths: rows older than **24 hours** by `claimedAt` are deleted, tunable with `VOLTRO_SCHEDULE_CLAIMS_TTL_HOURS`. The announcement at boot names it (`retention: N policy(ies) armed`). 24 h rather than the 30 days the framework's *history* tables get, because this is a lock ledger — a claim row answers a question about one firing instant, and nothing reads yesterday's. One row per (schedule, second-bucket) adds up faster than people expect: a deployment with a handful of sub-minute schedules measured 1 557 rows/hour, which a 30-day window would have let reach a million before the first row aged out. If you raise it, the number to reason about is the longest a replica may be paused and still be trusted not to re-fire a bucket it already lost. The sweep is the **backstop**, not the main bound — it is what cleans up after a schedule you renamed or deleted, which the per-schedule prune above can never revisit. (Through 0.32.0 the whole sweep was registered behind a postgres-only gate, so on the other four dialects it never ran and the boot said nothing about it. Fixed in 0.33.0.)
+- **Looked up by primary key.** The existence check the coordinator runs before its `INSERT` is a single-row read on `id`, which *is* the claim key — so the table's size does not enter the firing path.
 - **Pool-safe.** Unlike a session-level `pg_advisory_lock` (tied to a connection a pool may reassign), a claims row is durable and connection-independent.
 - **Fail-closed.** If the claims table is unreachable, the coordinator logs a warning and declines to fire rather than risk a double-fire. A missing run is recoverable via [backfill](/docs/scheduling/overlap-and-backfill); a double-fire (two charge emails) often isn't.
 

package/templates/agent-docs/security.md

@@ -95,7 +95,7 @@ voltro db scan-credentials
 voltro db scan-credentials --table my_events:actor
 ```
 
-Counts rows carrying a credential-shaped key — `token`, `secret`, `password`, `apikey`, `credential`, `privatekey` — plus any table you name with `--table <name>[:<column>]`. Exit code `1` on a hit, so CI can gate on it.
+Counts rows in which a credential-shaped **name** appears anywhere in the stored value — `token`, `secret`, `password`, `apikey`, `credential`, `privatekey` — plus any table you name with `--table <name>[:<column>]`. Exit code `1` on an unexplained hit, so CI can gate on it.
 
 By default it scans every column that can physically HOLD one:
 
@@ -109,12 +109,31 @@ By default it scans every column that can physically HOLD one:
 Every hit line names the needles that matched, with the number of rows each appears in:
 
 ```
-✗  _voltro_audit_log.outcome — 69 of 149 row(s) match a credential-shaped key
+✗  _voltro_audit_log.outcome — 69 of 149 row(s) contain a credential-shaped NAME (anywhere in the value)
        matched (rows per needle, may overlap): token (61), secret (12)
+       examined 69 of 69 matched row(s): 61 as a JSON KEY, 8 only inside a redaction marker
 ```
 
 **Those counts overlap and do not sum to the hit count** — a row holding both a token and a secret is counted by both needles. Without the breakdown the advice underneath (*purge them AND rotate the credentials*) is neither executable — purge what, rotate which — nor refutable: a column mentioning the word `token` in prose reads identically to one holding a live one.
 
+### Hits are explained, not just counted
+
+The predicate is a substring match over the whole serialized column, so a match is a match on a *name*, wherever it sits. The third line above is a bounded second pass that reads the matched rows back and says what actually matched — a JSON **key**, or only a **redaction marker**. Values are never printed and never logged.
+
+A redaction marker is the framework's own record that a credential was deliberately *not* stored: `_omitted` (`@voltro/plugin-versioning`, the column names left out of a row snapshot) and `__redacted` (`@voltro/plugin-audit`). A target whose every matched row is one of those is reported as explained, and does **not** fail CI:
+
+```
+~  _voltro_row_history.data — 69 of 149 row(s) contain a credential-shaped NAME (anywhere in the value)
+       matched (rows per needle, may overlap): token (69)
+       examined 69 of 69 matched row(s): 0 as a JSON KEY, 69 only inside a redaction marker
+       EXPLAINED — every match is `_omitted` / `__redacted`, the framework's own
+       record that a `.sensitive()` column was left OUT. Nothing to purge, nothing to rotate.
+```
+
+The bar for that is deliberately high: **every** matched row examined, **every** one of them a marker and nothing else. A target where the read-back was capped (at 500 rows), or where one row is a real key, or where one row is not parseable as JSON, stays a finding and still exits `1`. A partially-explained target is still a target.
+
+> **Why this exists.** A team with `.serverOnly().sensitive('secret')` columns and correctly-redacting plugins got 69 rows flagged, with *purge them AND rotate the credentials* underneath, against the framework's own proof that nothing was stored. The shape mattered more than the one key name: the more columns an app classifies correctly, the more markers it writes, and the redder the scan turns. A false-positive rate that rises with the care you take gets the tool muted — and a muted scan is worth less than none, because its silence still reads as evidence.
+
 > **If you ran this on 0.30.0, 0.30.1 or 0.30.2, run it again.** Those releases scanned `subjectId` on both tables — a flat opaque id that cannot hold a credential — and none of the blob columns above. The command ran cleanly, printed a scanned count beside a hit count, and exited `0` having never looked where credentials are. It came from fixing a crash: the default column had been the literal `subject` for every table, `_voltro_row_history` has no such column, and the fix replaced the name on *both* tables instead of the one that was wrong. A clean answer from a scan that looked in the wrong place is worse than the crash it replaced. `voltro update` prints this as a manual step on the way to 0.31.0.
 
 **It is a command and not a documented query on purpose.** The same check once shipped as SQL you were asked to run yourself, in its postgres spelling (`subject::text ILIKE '%token%'`). On MySQL/MariaDB the natural translation is a bare `LIKE` — and against the `utf8mb4_bin` collation the migrator emits for a `json()` column, `LIKE` is case-**sensitive**. So `'%token%'` does not match `jiraToken`, and almost every JSON key that carries a credential is camelCase. A team ran the translated query over 141 rows, got `0`, and nearly reported themselves clean; 117 of those rows held a working credential. Every dialect now casts to its own text type before lowering, in code you do not have to translate.
@@ -125,6 +144,8 @@ Run it on every environment. A development database is not a sample of productio
 
 If it finds something: purge the rows **and** rotate the credentials — assume anything written to a log table has been read — then move the credential off the Subject entirely with `connectionCredentials(...)`, which keeps it in the framework vault.
 
+If the finding is a credential column of your own sitting in plaintext, `.encrypted()` only protects rows written *after* you add it — [`voltro db encrypt-column`](/docs/database/sensitivity) converts the ones already there.
+
 ## Supply-chain assurance
 
 Every release passes automated supply-chain gates in CI before a single package is published: