@voltro/cli 0.31.0 → 0.32.0

package/dist/serveEntry.js

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

package/dist/{start-CI2QdKy9.js → start-D1-8eKrO.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-BeEAnjqw.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-BqO4E9G0.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-BeEAnjqw.js";
-import { t } from "./start-CI2QdKy9.js";
+import { ct as e } from "./inspectMetrics-BqO4E9G0.js";
+import { t } from "./start-D1-8eKrO.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -55,6 +55,406 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "voltro": {
+    "codemods": [
+      {
+        "version": "0.10.0",
+        "id": "0.10.0/01_render-mode-client-to-spa",
+        "title": "renderMode is a closed set — `'client'` becomes `'spa'`",
+        "kind": "transform"
+      },
+      {
+        "version": "0.10.0",
+        "id": "0.10.0/02_router-state-carries-its-path",
+        "title": "`renderRouterStateScript` now requires the `path` it rendered",
+        "kind": "manual"
+      },
+      {
+        "version": "0.10.0",
+        "id": "0.10.0/03_workflow-caller-context-resolved",
+        "title": "workflow `buildContext` receives a RESOLVED caller context",
+        "kind": "manual"
+      },
+      {
+        "version": "0.10.0",
+        "id": "0.10.0/04_seed-run-status-skipped",
+        "title": "seed run status gained `skipped`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.10.0",
+        "id": "0.10.0/05_subscription-idle-state",
+        "title": "`useSubscription` gained an idle state for `skip`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.11.0",
+        "id": "0.11.0/01_step-options-type-params",
+        "title": "`StepOptions` takes the context type first",
+        "kind": "manual"
+      },
+      {
+        "version": "0.12.0",
+        "id": "0.12.0/01_outbound-http-ssrf-guard",
+        "title": "Outbound HttpClient blocks internal targets by default (add `http.allowHosts` if you call one)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.12.0",
+        "id": "0.12.0/02_api-key-revoke-tenant-scope",
+        "title": "apiKeyService.revoke/rotate now require the caller's tenantId",
+        "kind": "manual"
+      },
+      {
+        "version": "0.12.0",
+        "id": "0.12.0/03_api-key-on-behalf-of",
+        "title": "API keys: createdBy is provenance, onBehalfOf is ownership",
+        "kind": "manual"
+      },
+      {
+        "version": "0.12.0",
+        "id": "0.12.0/04_inspect-fail-closed",
+        "title": "The inspect surface requires VOLTRO_INSPECT_TOKEN (previously open when unset)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.13.0",
+        "id": "0.13.0/01_bearer-gates-fail-closed",
+        "title": "checkBearer is fail-closed; scimPlugin refuses an empty token",
+        "kind": "manual"
+      },
+      {
+        "version": "0.13.0",
+        "id": "0.13.0/02_storage-grants-owner-only",
+        "title": "storage.share / revoke / listGrants require ownership",
+        "kind": "manual"
+      },
+      {
+        "version": "0.13.0",
+        "id": "0.13.0/03_apply-plan-convergence-proof",
+        "title": "applyPlan requires a `replan` convergence proof",
+        "kind": "manual"
+      },
+      {
+        "version": "0.14.0",
+        "id": "0.14.0/01_resolve-scopes-store",
+        "title": "auth.resolveScopes receives the app DataStore",
+        "kind": "manual"
+      },
+      {
+        "version": "0.14.0",
+        "id": "0.14.0/02_reactive-by-default",
+        "title": "Reactivity is the default; .reactive() is removed",
+        "kind": "transform"
+      },
+      {
+        "version": "0.14.0",
+        "id": "0.14.0/03_pages-suffix",
+        "title": "Pages are declared with a .page.tsx suffix",
+        "kind": "transform"
+      },
+      {
+        "version": "0.14.0",
+        "id": "0.14.0/04_file-taxonomy",
+        "title": "Web files declare their contract (*.component.tsx / *.hook.ts / *.types.ts)",
+        "kind": "transform"
+      },
+      {
+        "version": "0.14.0",
+        "id": "0.14.0/05_typed-tracking",
+        "title": "Tracking catalogues are typed against the component props",
+        "kind": "manual"
+      },
+      {
+        "version": "0.14.0",
+        "id": "0.14.0/06_voltro-test-skips-e2e",
+        "title": "`voltro test` leaves `e2e/` to `voltro e2e`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.14.0",
+        "id": "0.14.0/07_dev-remote-file-migrations",
+        "title": "voltro dev refuses unattended file migrations against a remote database",
+        "kind": "manual"
+      },
+      {
+        "version": "0.15.0",
+        "id": "0.15.0/01_undo-mistaken-taxonomy-renames",
+        "title": "Undo the two file renames 0.14.0 got wrong (framework primitives, side-effect modules)",
+        "kind": "transform"
+      },
+      {
+        "version": "0.15.0",
+        "id": "0.15.0/02_error-tag-in-protocol",
+        "title": "`errorTag` is imported from @voltro/protocol",
+        "kind": "transform"
+      },
+      {
+        "version": "0.17.0",
+        "id": "0.17.0/01_pages-are-directories",
+        "title": "A directory is a route segment; its route is page.tsx",
+        "kind": "transform"
+      },
+      {
+        "version": "0.18.0",
+        "id": "0.18.0/01_where-like-removed",
+        "title": "the `'like'` where-operator is removed — pick `contains` or `startsWith`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.19.0",
+        "id": "0.19.0/01_server-only-gates-the-boot",
+        "title": "`.serverOnly()` now FAILS the boot under `voltro serve` — it used to only warn",
+        "kind": "manual"
+      },
+      {
+        "version": "0.19.0",
+        "id": "0.19.0/02_audit-redact-input-default",
+        "title": "`auditPlugin` now redacts mutation input by default (`redactInput: 'all'`)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.20.0",
+        "id": "0.20.0/01_write-recorder-port",
+        "title": "`WriteRecorder` takes a port (`{ append, maxOf }`) instead of a bare `append`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.21.0",
+        "id": "0.21.0/01_maxlength-now-migrates",
+        "title": "`text().maxLength(n)` now migrates EXISTING columns — plan before you apply",
+        "kind": "manual"
+      },
+      {
+        "version": "0.22.0",
+        "id": "0.22.0/01_rename-index-op",
+        "title": "`MigrationOperation` gained a `rename-index` kind",
+        "kind": "manual"
+      },
+      {
+        "version": "0.22.0",
+        "id": "0.22.0/02_plugin-tables-voltro-prefixed",
+        "title": "plugin-owned tables are `_voltro_`-prefixed (the rows move themselves)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.22.0",
+        "id": "0.22.0/03_cache-scope-gained-tenant",
+        "title": "`cache.scope` gained 'tenant' — an exhaustive switch over it needs a branch",
+        "kind": "manual"
+      },
+      {
+        "version": "0.22.0",
+        "id": "0.22.0/04_inspect-write-credential",
+        "title": "Mutating `/_voltro/inspect/*` endpoints need VOLTRO_INSPECT_WRITE_TOKEN",
+        "kind": "manual"
+      },
+      {
+        "version": "0.23.0",
+        "id": "0.23.0/01_versioning-is-opt-out",
+        "title": "versioningPlugin: `tables: string[]` → opt-out by default, `include` / `exclude` by value",
+        "kind": "manual"
+      },
+      {
+        "version": "0.24.0",
+        "id": "0.24.0/01_agent-tables-voltro-prefixed",
+        "title": "the two agent tables are `_voltro_`-prefixed (the rows move themselves)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.25.0",
+        "id": "0.25.0/01_events-emit-to-publish",
+        "title": "`ctx.events.emit(name, data)` → `ctx.events.publish(descriptor, key, payload)`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.25.0",
+        "id": "0.25.0/02_outgoing-event-to-define-event",
+        "title": "`defineOutgoingEvent` → `defineEvent({ …, webhook: { … } })`",
+        "kind": "transform"
+      },
+      {
+        "version": "0.25.0",
+        "id": "0.25.0/03_broadcast-channel-to-namespace",
+        "title": "`broadcast({ channel })` → `broadcast({ namespace })`",
+        "kind": "transform"
+      },
+      {
+        "version": "0.26.0",
+        "id": "0.26.0/01_event-webhook-retry-removed",
+        "title": "`defineEvent({ webhook: { retry } })` is gone — it never did anything",
+        "kind": "manual"
+      },
+      {
+        "version": "0.26.0",
+        "id": "0.26.0/02_step-retry-enforced",
+        "title": "workflow step `retry:` is now ENFORCED (was metadata) — drop any redundant manual retry",
+        "kind": "manual"
+      },
+      {
+        "version": "0.28.0",
+        "id": "0.28.0/01_notifications-resolve-subject-id-async",
+        "title": "`makeSubjectId` returns a Promise; `resolveSubjectId` may be async",
+        "kind": "manual"
+      },
+      {
+        "version": "0.28.0",
+        "id": "0.28.0/02_plugin-ref-change-event",
+        "title": "`PluginRefChange` is removed — the change channel's `ChangeEvent` is the one shape",
+        "kind": "manual"
+      },
+      {
+        "version": "0.28.0",
+        "id": "0.28.0/03_atlassian-credentials-context",
+        "title": "`credentialsResolver` receives `{ subject, store }` instead of a bare Subject",
+        "kind": "manual"
+      },
+      {
+        "version": "0.28.0",
+        "id": "0.28.0/04_audit-redacts-subject-metadata",
+        "title": "`auditPlugin` redacts `subject.metadata` by default",
+        "kind": "manual"
+      },
+      {
+        "version": "0.29.0",
+        "id": "0.29.0/01_loader-data-absence",
+        "title": "`useLoaderData()` throws at a level that declares no `loader`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.3.0",
+        "id": "0.3.0/01_prod-serve-requires-build",
+        "title": "Production `voltro serve` requires a precompiled bundle (build before serve)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.30.0",
+        "id": "0.30.0/01_locale-cookie-rename",
+        "title": "the language-preference cookie is `voltro:locale` (was `voltro:lang`)",
+        "kind": "transform"
+      },
+      {
+        "version": "0.30.0",
+        "id": "0.30.0/02_audit-purge-query-recheck",
+        "title": "re-run the credential-purge query — the 0.28.0 spelling under-reported on MySQL/MariaDB",
+        "kind": "manual"
+      },
+      {
+        "version": "0.30.0",
+        "id": "0.30.0/03_webhook-emit-durable-deferral",
+        "title": "a deferred `webhooks.emit` rides the transactional outbox; `{ immediate: true }` opts out",
+        "kind": "manual"
+      },
+      {
+        "version": "0.30.0",
+        "id": "0.30.0/04_workflow-run-handle-nullable-execution",
+        "title": "`WorkflowRunHandle.executionId` is `string | null`; `status` gains queued/dropped/skipped",
+        "kind": "manual"
+      },
+      {
+        "version": "0.31.0",
+        "id": "0.31.0/01_rerun-credential-scan",
+        "title": "re-run `voltro db scan-credentials` — on 0.30.0–0.30.2 it skipped the column credentials land in",
+        "kind": "manual"
+      },
+      {
+        "version": "0.32.0",
+        "id": "0.32.0/01_audit-redacts-outcome",
+        "title": "`auditPlugin` now redacts `outcome` by default — opt out if your trail reads it",
+        "kind": "manual"
+      },
+      {
+        "version": "0.4.0",
+        "id": "0.4.0/01_rbac-forbidden-to-scopeerror",
+        "title": "@voltro/plugin-rbac: `Forbidden` → protocol `ScopeError` (one denial tag)",
+        "kind": "transform"
+      },
+      {
+        "version": "0.4.0",
+        "id": "0.4.0/02_rbac-web-to-client-permissions",
+        "title": "@voltro/plugin-rbac/web removed — the UI gate lives in @voltro/client",
+        "kind": "transform"
+      },
+      {
+        "version": "0.5.0",
+        "id": "0.5.0/01_one-terminal-exactly-one",
+        "title": ".one() now fails on MORE than one row; NoRowFound is a declarable typed error",
+        "kind": "manual"
+      },
+      {
+        "version": "0.5.0",
+        "id": "0.5.0/02_typed-store-rows",
+        "title": "store.query() now returns the row type — casts on row fields may stop compiling",
+        "kind": "manual"
+      },
+      {
+        "version": "0.6.0",
+        "id": "0.6.0/01_no-dev-session-secret",
+        "title": "The built-in dev session secret is removed; VOLTRO_SESSION_SECRET is required",
+        "kind": "manual"
+      },
+      {
+        "version": "0.6.0",
+        "id": "0.6.0/02_subscription-state-union",
+        "title": "SubscriptionState is a discriminated union — `loading` now narrows `data`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.6.0",
+        "id": "0.6.0/03_billing-on-stripe-sdk",
+        "title": "Billing moved onto the Stripe SDK; proration + dunning are now Stripe’s",
+        "kind": "manual"
+      },
+      {
+        "version": "0.6.0",
+        "id": "0.6.0/04_relation-key-validation",
+        "title": "relation key options are validated at boot; `one` now fails on more than one match",
+        "kind": "manual"
+      },
+      {
+        "version": "0.6.0",
+        "id": "0.6.0/05_atlassian-avatar-mode",
+        "title": "atlassianPlugin's `avatar` config requires an explicit `mode: 'service' | 'perUser'`",
+        "kind": "transform"
+      },
+      {
+        "version": "0.6.0",
+        "id": "0.6.0/06_ui-strings-connect-account",
+        "title": "UiStrings gained a required `connectAccount` section",
+        "kind": "manual"
+      },
+      {
+        "version": "0.7.0",
+        "id": "0.7.0/01_row-filter-load-failure",
+        "title": "A row filter that fails to load now errors instead of returning zero rows",
+        "kind": "manual"
+      },
+      {
+        "version": "0.7.0",
+        "id": "0.7.0/02_testing-invoke-effect-handlers",
+        "title": "@voltro/testing: invoke() runs Effect handlers; executor types widened",
+        "kind": "manual"
+      },
+      {
+        "version": "0.8.0",
+        "id": "0.8.0/01_optional-password-hash",
+        "title": "`UserRecord.passwordHash` is optional — password-less identities are now first-class",
+        "kind": "manual"
+      },
+      {
+        "version": "0.8.0",
+        "id": "0.8.0/02_ssr-streams-and-loaderdata",
+        "title": "`ssr` pages stream; `useLoaderData<T>()` returns `LoaderData<T>`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.9.0",
+        "id": "0.9.0/01_ssr-layout-shell-for-spa",
+        "title": "A `renderMode:'spa'` page under a layout now server-renders that layout",
+        "kind": "manual"
+      }
+    ]
+  },
   "engines": {
     "node": ">=24.0.0"
   },
@@ -62,22 +462,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.31.0",
-    "@voltro/cache": "0.31.0",
-    "@voltro/data-transfer": "0.31.0",
-    "@voltro/database": "0.31.0",
-    "@voltro/env": "0.31.0",
-    "@voltro/kv": "0.31.0",
-    "@voltro/logger": "0.31.0",
-    "@voltro/plugin-auth": "0.31.0",
-    "@voltro/plugin-broadcast": "0.31.0",
-    "@voltro/plugin-mail": "0.31.0",
-    "@voltro/plugin-storage": "0.31.0",
-    "@voltro/plugin-webhooks": "0.31.0",
-    "@voltro/protocol": "0.31.0",
-    "@voltro/runtime": "0.31.0",
-    "@voltro/serverless": "0.31.0",
-    "@voltro/workflow": "0.31.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",
     "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.31.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.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. |
 | 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.31.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.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. |
 | 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/plugins/audit.md

@@ -104,6 +104,30 @@ auditPlugin({ sink: 'datastore', redactInput: (e) => pick(e) })  // field-level
 
 **Why it is not driven by `.serverOnly()` / `.sensitive()`,** which is the obvious design: those markers live on TABLE COLUMNS, and this is a mutation's INPUT. A `changePassword({ oldPassword, newPassword })` has no column to consult, so a marker-driven default would cover exactly 0% of the case it exists for — while reading, to whoever configured it, like protection. (`.sensitive()` is also the [export axis](/docs/database/sensitivity), not "unsafe to log"; treating one as the other is the category error that page warns about.) Pass a function once you know your own inputs.
 
+### `redactOutcome` — what the call RETURNED
+
+**The default is `'all'`: `outcome.value` on success and `outcome.error` on failure are replaced by `{ __redacted: 'all' }`.** `kind`, `durationMs` and the error's `_tag` survive.
+
+```ts
+auditPlugin({ sink: 'datastore', redactOutcome: 'none' })              // the outcome verbatim
+auditPlugin({ sink: 'datastore', redactOutcome: (e) => summarise(e) }) // field-level control
+```
+
+**This is `redactInput`'s reasoning applied to the field it structurally cannot cover.** For a credential-ISSUING call the secret is never in the input:
+
+```ts
+apiKeys.createPersonalApiKey({ name, scopes })  // input: nothing sensitive
+  → { keyValue: '<the plaintext key>' }          // outcome: the whole point
+webhooks.create({ url, subscribedEvents })      // input: nothing sensitive
+  → { signingSecret: '<live secret>' }           // outcome: returned once, by design
+```
+
+The option that existed covers the field those calls leave empty. Found by a team running `voltro db scan-credentials` on the first release where it read the json blobs: nine rows of `_voltro_audit_log.outcome` matched, four of them `webhooks.create` carrying a live 64-character signing secret in full — with `redactInput: 'all'` and `redactSubject: 'metadata'` both already on.
+
+**The error's `_tag` survives on purpose.** A trail that records "something failed" without saying what is not a trail, and a tag is a schema-declared discriminant that structurally cannot be a secret. A `record` predicate still sees the live outcome, so a filter keyed on what a call returned keeps working — redaction applies to what is *stored*.
+
+> **A FUNCTION sink gets neither the table nor the retention sweep.** Both are gated on `sink` being the literal `'datastore'`, so a function that redacts and then delegates to `dataStoreAuditSink` still writes rows on a database where `_voltro_audit_log` already exists — while creating the table nowhere and arming the TTL nowhere. It works where you tested it and fails on the next fresh database. If you want the durable trail with different redaction, use `sink: 'datastore'` plus the three `redact*` options: those compose, the sink does not.
+
 ### `redactSubject` — what of the CALLER is kept
 
 **The default is `'metadata'`: `subject.metadata` is replaced by `{ __redacted: 'all' }`.** `type`, `id`, `tenantId` and `scopes` survive, which is everything the trail is actually read for.

package/templates/agent-docs/security.md

@@ -106,6 +106,15 @@ By default it scans every column that can physically HOLD one:
 
 `input` and `outcome` are a procedure's arguments and result — the likeliest place of all for a token to arrive by accident, since nobody puts a credential on a subject on purpose and plenty of code passes one as an argument. `_voltro_row_history.data` is a full-row snapshot, so a credential column on *any* of your tables is in there, and it outlives deleting the source row.
 
+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
+       matched (rows per needle, may overlap): token (61), secret (12)
+```
+
+**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.
+
 > **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.