@voltro/plugin-audit 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -39,6 +39,188 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.38.0] — 2026-08-14
+
+### ⚠ BREAKING
+
+- **@voltro/plugin-audit, @voltro/protocol, @voltro/plugin-auth** — An audit row now says when an action was taken through an IMPERSONATED session, on the default settings, and no redactor can take that away.
+
+  `AuditEvent` gained `impersonation`, and the datastore sink a nullable json column of the same name. The mark is lifted out of `subject.metadata` BEFORE the redaction chain runs, so `redactSubject` — including a custom function that erases the subject wholesale — never gets a say.
+
+  **The defect it closes.** `@voltro/plugin-auth` mints the mark into `subject.metadata`, and `auditPlugin`'s default `redactSubject: 'metadata'` replaces that whole bag. That default is right: the bag is where a per-user provider credential lands, and an audit table is the last place a live PAT should be. The consequence was that on defaults an impersonated action was recorded indistinguishably from the user's own — the one distinction an audit trail exists to make. The documented mitigation (`redactSubject: impersonationAuditRedactor()`) worked and was opt-in, and an audit property that depends on somebody wiring it is not a property.
+
+  The alternative fix — a keep-these-keys option on `redactSubject` — was rejected for the same reason: it leaves the default wrong, and "who really did this" is not the app's metadata to configure away. It is a property of the event, so it is now a field of the event.
+
+  **BREAKING: `IMPERSONATION_METADATA_KEY` moved from `@voltro/plugin-auth` to `@voltro/protocol`.** It names the one reserved key in `Subject.metadata`, and `Subject` is protocol's type. Two packages need it — plugin-auth writes the mark, plugin-audit reads it — and a plugin must not depend on another plugin, so spelling the string in both would have made it a second definition no guard is watching. Everything else stays: plugin-auth still exports `impersonationOf`, `isImpersonated`, `ImpersonationMark` and `impersonationAuditRedactor`. The codemod repoints the import, preserving an alias and the type-only form.
+
+  The redactor keeps working and is no longer load-bearing. Set `redactSubject: 'none'` or a custom function for your own reasons; the impersonation mark is recorded either way.
+
+  No migration is needed for the new column — a `_voltro_*` change rides the declarative differ on `voltro db apply` and on a `voltro dev` boot, on every dialect.
+- **@voltro/cli** — A `*.startup.ts` that fails now refuses the boot. It used to warn and let the server come up.
+
+  Measured, on a real `voltro dev` against postgres, while building the row-filter integration test in this same release. A startup reached for `ctx.store.select(...)` — a builder that lives on the request-scoped `MutationStore`, not on the `DataStore` a startup receives — and threw on its first line. The boot printed:
+
+  ```
+  warn   startup: function rejected
+  info   startup: registered      <- next line, same file
+  ```
+
+  and then served every request with no row filter registered. Two lines contradicting each other, the second asserting exactly the thing that had just failed, and an app that looked healthy while its access control was absent.
+
+  **The rule this overturns was right when it was written.** The header of `startupRunner.ts` read "Errors are logged but never fatal — a failing startup MUST NOT block the rest of the app", and for the startups it was written for — an SSE bridge, a sync loop, a metric aggregator — that is the correct call. It stopped being right when a startup became the documented seam for REGISTRATION: `setRowFilter` is installed from one.
+
+  The runner cannot tell a registration from a background loop, and the two failures are not symmetric. "The app refuses to boot" is fixed in seconds and is visible to everyone; "the app serves without its access control" is visible to nobody. So the default is the recoverable one, and an app that genuinely wants best-effort writes the `try`/`catch` inside its own startup — one line, at the site where somebody decided the failure was acceptable, where a reviewer can see it. Deliberately not a flag: a flag moves that decision away from the startup it applies to and makes it one setting for all of them.
+
+  **Two sibling silences went with it**, because fixing only the rejection would have left two more ways to reach the identical state — the per-seam shape this repo keeps paying for. A startup file that cannot be imported, and one with no default-exported function, used to warn and skip. Both refuse now. The second matters more than it sounds: the convention is a DEFAULT-exported function, a named export is discovered and never runs, and that is indistinguishable from a startup that ran and did nothing.
+
+  **And the 2-second race is gone, which is the half that made the rest reliable.** The old code did not wait for a startup to settle — it raced it against 2000 ms and let the boot win. A startup slower than that was reported as fine, so a rejection arriving afterwards had nothing left to refuse. The runner now waits for the startup to SETTLE, so every failure is catchable however slow it is.
+
+  That race existed to protect one shape: a startup that never returns because it holds a fiber until shutdown. Counted before changing it, that shape appears in ZERO of the four startups this framework ships — `warm.startup.tsx` (twice), `searchBackfill.startup.tsx` and the memory fixture's all return. So the race protected the shape we discourage and penalised the shape we teach, and the penalised one includes `searchBackfill`, our own example, which awaits a full-table query plus an index backfill and is the likeliest thing in the box to exceed two seconds. Slow AND failing put a consumer back in exactly the silent state this release removes.
+
+  **So a startup that never returns now refuses the boot too**, after `VOLTRO_STARTUP_TIMEOUT_MS` (60s default), with a message naming the file and showing the `onShutdown` shape to use instead. That makes a previously-documented capability illegal — "a fiber that resolves only on shutdown" — and it is the deliberate half of this change rather than a side effect. A startup that is merely SLOW is unaffected: it is waited for and registers when it finishes.
+
+  `startup: registered` is written only when the function actually returned. The old code printed it for a failed startup and for one still running.
+
+  Verified against a real process in every direction, not only in units: the reintroduced defect exits 1 and never listens; a never-returning startup exits 1 and never listens; a slow-but-successful one still registers; and the healthy fixture boots and serves all eight row-filter assertions. `startupRunner.test.ts` is new — there were no tests on this runner at all, which is part of why the contradiction survived.
+
+  **`voltro update` carries you across this** — codemod `0.38.0/02_startup-failure-refuses-boot`.
+
+### Fixed
+
+- **@voltro/cli** — A table declared through `databaseHandle({ … })` but not exported as a top-level table is now DISCOVERED — so its mixins apply.
+
+  Discovery kept whatever `isTable()` accepted out of a schema module's `Object.values`, which only ever sees tables the file exports DIRECTLY. A schema that builds its tables programmatically exports the builder's result:
+
+  ```ts
+  export const blogEntities = contentTypeToEntities(blogPost)   // { draft, published }
+  export const database = databaseHandle({ …, blogPostDrafts: blogEntities.draft })
+  ```
+
+  `isTable({ draft, published })` is false, so those tables never entered the schema registry — while `databaseHandle` had registered them for by-name lookup perfectly well.
+
+  **Two registries with different populations, read by different things.** `getTable()` found the table, so insert validation knew `tenantId` was NOT NULL. The schema registry is what drives the mixins, so nothing stamped it. Measured against a real `voltro dev` boot of the scaffolded `api-cms` template, over real RPC:
+
+  ```
+  TableValidationFailed: { "table": "blogPost_drafts", "summary":
+    "missing required column 'tenantId' — NOT NULL with no default and not auto-stamped" }
+  ```
+
+  Every `content.saveDraft` in that template, since it shipped. Its own unit test could not see it, because the test builds its schema registry by hand — the one step the running app does not perform.
+
+  **The write failing was the lucky half.** Reads do not announce themselves: `makeQueryFinalizer` AND-merges `tenantId` from this same registry, so a table missing from it is a table nobody scopes. The visible symptom was a broken mutation; the invisible one was tenant isolation quietly not applied to those tables.
+
+  The fix takes the by-name registry's DELTA across each schema module's import, so a handle-declared table is attributed to the file that declared it — rather than reading the whole global registry, which by then also holds framework tables that this set deliberately excludes. It lives in `loadDiscovered`, which `voltro dev` and `voltro serve` both call, so the two cannot disagree about it.
+
+  No app change is needed; the idiomatic `databaseHandle` declaration now works as its documentation always said.
+- **@voltro/database, @voltro/cli** — A migration that fails because `DB_SCHEMA` names a schema that does not exist now says so.
+
+  Postgres answers `3F000 no schema has been selected to create in`, and the only thing that puts a non-default schema on the connection's `search_path` here is `DB_SCHEMA`. The error mentions neither the variable nor the schema, so the FIRST `CREATE TABLE` of the boot fails with a message about SQL and the reader goes looking at the DDL — for a typo in an environment variable.
+
+  Found while building the row-filter integration test below: the boot aborted, the log named `_voltro_migrations` and a postgres routine, and nothing in it pointed at the one line of configuration that caused it. Same shape as a 403 that says nothing about `VOLTRO_INSPECT_TOKEN`, fixed in the same release.
+
+  The remedy also states what the framework will NOT do: Voltro creates tables, never the schema itself. That is a namespace decision, and inventing one from a typo puts a migration somewhere nobody is looking.
+
+  `remedyFor` is deliberately a one-entry map and the test asserts the empty case as well as the full one. A remedy is worth printing only where the mapping from driver code to cause is exact; a list of maybes is how a reader learns to skip the section.
+
+  **Alongside it: the row filter is now driven under `voltro dev` against a real postgres.** Both defects that reached consumers lived between layers that were each individually covered — a module-local `let` that split per instance, then a query producer that built its context from an unscoped request — and three consumer documents carried "we have not run this against a real database" as an honest caveat. `rowFilterDevPostgres.integration.test.ts` boots the fixture twice: handlers with no predicate of their own, a filter registered from a `*.startup.tsx`, and a NEGATIVE CONTROL run with the registration skipped that asserts the same queries return BOTH owners. Without the control, "the caller saw one owner" is equally consistent with a database that only ever held one.
+- **@voltro/cli** — A shard that cannot be released no longer spins a fiber at full speed. Upstream `@effect/cluster` releases shards through `Effect.eventually` — retry until success, zero delay, logged at DEBUG — so a shard whose storage was unreachable retried as fast as the event loop allowed, in the one place nobody watches.
+
+  Our patch replaces it with `Effect.retry(Schedule.exponential(100) ∪ Schedule.spaced(5000))`. `union` takes the MINIMUM of the two delays, so the 5s spacing caps the backoff instead of compounding with it, and both schedules recur forever — attempts stay unbounded, which is what the original intended. The persistence was always correct; only the missing delay was the defect.
+
+  This entry exists because the change would otherwise have shipped undocumented. The patch lives in `packages/cli/templates/patches/`, and the changelog gate requires an entry for `packages/*/src` — so nothing would have demanded one, even though the file is installed into every user project that runs cluster. A rule that cannot see a path is not the same as a path with nothing on it.
+
+---
+
+## [0.37.0] — 2026-08-13
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/runtime, @voltro/cli** — A field a procedure's input schema does not declare now REJECTS the call. It used to be discarded and the call ran with what was left.
+
+  The measurement, from a consumer's root layout:
+
+  ```ts
+  query?.('userSettings.list', { employeeId })
+  ```
+
+  That procedure declares `userId` / `userIdIn`. Effect's default `onExcessProperty: 'ignore'` decoded the payload to `{}` — not reasoned, measured:
+
+  ```ts
+  decodeUnknownSync(Struct({ userId: optional(String) }))({ employeeId: 'e' })  // → {}
+  ```
+
+  An empty input to a LIST query is not a narrower filter, it is the ABSENCE of one. Their admin, signed in as `2d0add2c…`, was served the settings row of `4410c2f8…` — another user's language and theme in the first paint, with nothing in any log to say so.
+
+  **Why refuse rather than warn.** The decoder cannot tell a projection field from a FILTER field, and that asymmetry is the whole risk: dropping an unknown `include` costs a caller some data, dropping an unknown `tenantId` hands them somebody else's. Nothing at decode time distinguishes the two, so the safe direction is the only one available — the same fail-closed reasoning as the row filter's refusal, one layer up. A warning would have to be read by someone, in a log, after the wrong rows were already served.
+
+  The typed loader query that shipped in 0.36.0 closes the same hole for callers we compile. This closes it for the ones we do not: a plain `fetch`, a curl, a still-cached bundle after a field rename, and every untyped caller.
+
+  Three things measured rather than assumed, because none follows from the annotation's name: it propagates into NESTED structs, through every member of a UNION, and leaves a non-struct payload (`Schema.Void`, a scalar) alone.
+
+  **`Schema.Struct({})` needed a filter, and only a real process showed it.** The fixture's `notes.list` declares an empty input; `POST /rpc` with `{ employeeId }` came back `200` with a snapshot, which for twenty minutes read as the whole change having failed. An empty `TypeLiteral` has no property signatures, so Effect has no expected key set for a key to be excess OF — self-consistent, and the wrong answer here, because `input: Schema.Struct({})` is the STRONGEST declaration a procedure can make and it was the one shape that accepted everything. It gets an explicit predicate now; `Schema.Record` keeps its open key set, because there the openness is declared.
+
+  **Verified against a running `voltro serve`, not only in units.** A declared input succeeds and inserts its row; an undeclared field is refused naming the key and the accepted set. The refusal arrives on the channel a payload decode failure ALREADY used — a missing required field produces the same `Die` with a `ParseError` message — so this adds no new error shape for a client to handle, it moves one case onto the channel the sibling case was always on.
+
+  `strictInput` lives in one module and every `Rpc.make` payload in `@voltro/protocol` goes through it — query, mutation, action, stream, event, plus the workflow start on both the server lifter and the browser-loaded rpc group. `strictInput.test.ts` asserts that SET by scanning the source, not the five lifters somebody remembered: a rule applied at the sites you can list is the shape that let `bootStoreCodec` be fixed twice and break a third time.
+
+  **`voltro update` carries you across this** — codemod `0.37.0/01_procedure-input-rejects-undeclared-fields`, a written note. A transform would have to guess which declared field a stray one meant, which is the same guess that produced the defect.
+
+### Added
+
+- **@voltro/plugin-audit** — `redactInput` / `redactOutcome` gained `'shape'`, and `redactSubject` gained `'metadata-shape'`: the payload's STRUCTURE survives, no value from it.
+
+  ```json
+  { "__redacted": { "jiraToken": "string(113)", "attempts": "number" } }
+  ```
+
+  Requested by the consumer who had asked for the redaction one round earlier, and both requests were right. They spent a day on a bug their own audit trail could have ended in seconds — a value arrived as 113 characters where 44 were due, and the row that would have said so read `{"__redacted":"all"}`. `'all'` remains the default on every field; this is opt-in.
+
+  The rules, and the two that are decisions rather than details:
+
+  - A string reports its LENGTH. Never a prefix, never a hash — `enc:v1:` is a prefix and so is the first byte of a private key, so there is no prefix length that is safe for every credential format. - A number, boolean or date reports its TYPE only. A number can BE the secret. - **A key can be the value.** An object keyed by user data puts a datum where a schema name belongs, so a key is reproduced only when it looks like a declared field — a short plain identifier. The first version truncated long keys and documented the weakness instead; this module's own test caught 62 characters of a secret surviving on the first run. A leak with a footnote is still a leak. - **A string's length is a real disclosure, and a small one.** Stated in the docs rather than buried: for a fixed-format credential it carries nothing, for a human-chosen password it is a weak hint. `'all'` stays the default for anyone that matters to.
+
+  The `'shape'` outcome describes the payload it REPLACES — the value on success, the error on failure — rather than the event. Describing the event would report `{ kind, value, durationMs }` and hide the field, which is the failure the option exists to end. An error's `_tag` still survives, as it does under `'all'`.
+
+### Fixed
+
+- **@voltro/cli** — `voltro db --help` listed fifteen of eighteen subcommands. `adopt`, `scan-credentials` and `encrypt-column` shipped and never joined the hand-written string.
+
+  A consumer wrote both halves of that gap into a requirements document, as separate items, neither of them about help text:
+
+  - **`voltro db encrypt-column` "does not exist"** — filed as a feature request, quoting the fifteen names they saw as evidence. It shipped in 0.33.0, and enabling `.encrypted()` on a populated column by hand is exactly the migration they were about to write themselves. - **`scan-credentials` "no longer exists"** — filed as CLOSED, a credential scanner struck off their list as removed. It had not moved.
+
+  A quoted enumeration is read as exhaustive, and the more careful the reader the more thoroughly they act on the missing entry. Same lesson a boot refusal in `procedureAccessGate` had already taught us, in a place nobody thought of as a message.
+
+  The usage line is now GENERATED from the dispatch table's key type (`Record<DbSubcommand, Handler>` in `dbCommand.ts`, names in `subcommandNames.ts`), so a handler with no name or a name with no handler fails to compile. `voltro privacy` is keyed the same way. The prose summary beside it cannot be generated — it carries per-command annotations — so a test asserts it mentions every name, because it carried the identical three omissions and it is what `voltro --help` prints first.
+
+  `subcommandHelpParity.test.ts` also NAMES the six commands whose subcommand menus have no dispatch table behind them (`webhooks`, `evolve`, `new`, `data`, `storage`, `add`). They dispatch through a switch and are unchecked; a silently-unchecked command reads exactly like a checked one.
+- **@voltro/cli** — A 401 or 403 from the inspect surface now names `VOLTRO_INSPECT_TOKEN` and says which side is missing.
+
+  `voltro db plan --against <url>` printed `remote returned 403` and stopped. A consumer read that as a DATABASE permission problem — the natural reading of a 403 from a command whose entire subject is a database — and went looking at grants. The cause is one unset environment variable, which the command reads four lines above the message.
+
+  `voltro probe access` had half of it: it named the variable on 401 and not on 403, while classifying both as `refused`. So the two commands somebody needs during an access migration were the two that would not say what was wrong, and one of them said something misleading instead.
+
+  `inspectGateHint` is shared by both call sites and distinguishes the two statuses, because they call for different actions: a 401 means no credential was sent (set the variable), a 403 means the one sent was not accepted (the two values differ). Both halves of the sentence name the server AND the calling shell — naming one side produces a second failed attempt.
+- **@voltro/cli** — `VOLTRO_TEMPLATES_DIR` is authoritative when set. It used to be a HINT: if the path it named held no `apps/` (or no `baselines/`), both resolvers fell through to the sibling-checkout walk-up and quietly used a different tree — or none.
+
+  A pointer that silently isn't followed is worse than a wrong one. A CI job aimed at the wrong path scaffolded from whatever it happened to find, and a job whose checkout had failed reported an empty template catalogue with nothing connecting that emptiness to the variable it was given. `scripts/lib/docsSite.mjs` states the same rule for `VOLTRO_DOCS_DIR`, and arrived at it the same way: you said where it is; it is not there.
+
+  Behaviourally this only changes the misconfigured case — a correct `VOLTRO_TEMPLATES_DIR` resolved to the same place before and after. What changes is that a wrong one now shows up as "not found, here is the path I was told" at the first thing that reads it, instead of as a different tree three steps later.
+
+  The unbundled resolution order is otherwise untouched: sibling `voltro-templates` → `.voltro-templates` → the bundled `templates/` a published CLI ships.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/plugin-ai-flows** — Two comments in the flow engine cited task records from a plans tracker that has since been deleted. Comment-only; no behavior, no API, nothing a consumer can observe.
+
+  Worth writing down because of HOW it surfaced. The tracker was retired in the META repo, and the gate that went red was in THIS one — `check-stale-task-comments.mjs` resolves a comment's `task #NN` against `../plans`, so deleting a plan document in one repo can only be half a change, and the other half is in a repo the deleting commit never touched.
+
+  Neither comment was WRONG, which is the part that makes the rule earn its keep. The first claims `@voltro/ai` has first-class media generation — true: `generateImage`, `generateSpeech`, `generateVideo` all ship in `packages/ai/src/media.ts`. It now names those three instead of a record number, which is checkable without the deleted document. The second only quoted the retired id inside its own account of a defect (a `"not yet wired (task #35)"` message that outlived the shipped HITL park and misled an audit into filing it as unbuilt); the quote lost the number and kept the whole lesson.
+
+  The check's own failure text is the reasoning: a plan is retired for exactly two reasons — the work shipped, or it was dropped without shipping — and a comment still citing it asserts the second while usually meaning the first.
+
+---
+
 ## [0.36.0] — 2026-08-13
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -127,6 +127,27 @@ export declare interface AuditEvent {
     readonly scope?: unknown;
     /** The app's own note about what happened. Opaque, never interpreted. */
     readonly metadata?: unknown;
+    /**
+     * The impersonation mark, when the acting session was an impersonated one —
+     * absent otherwise.
+     *
+     * **A FIRST-CLASS FIELD, on purpose, and no redactor can reach it.** The mark
+     * is minted into `subject.metadata` by `@voltro/plugin-auth`, and the audit
+     * default `redactSubject: 'metadata'` replaces that whole bag — correctly, it
+     * is where a per-user provider credential lands. The consequence was that on
+     * DEFAULTS an impersonated action was indistinguishable from the user's own,
+     * which is the one distinction an audit trail exists to make.
+     *
+     * Fixing that with a keep-these-keys option would have left it opt-in, and
+     * "who really did this" is not the app's metadata to configure away — it is a
+     * property of the event. So it is lifted out of the subject BEFORE any
+     * redaction runs, and `redactSubject` is not given a say.
+     *
+     * Opaque here (`unknown`): `@voltro/plugin-audit` copies the mark, it does not
+     * interpret it. `impersonationOf()` from `@voltro/plugin-auth` is what turns
+     * it back into a typed `ImpersonationMark`.
+     */
+    readonly impersonation?: unknown;
     readonly traceId: string;
     readonly input: unknown;
     readonly outcome: {
@@ -325,6 +346,10 @@ export declare interface AuditPluginOptions {
      *
      *   - `'all'` (DEFAULT) — the payload is replaced by `{ __redacted: 'all' }`.
      *     The row still proves a payload existed; it just does not carry it.
+     *   - `'shape'` — the payload's STRUCTURE, no value from it:
+     *     `{ __redacted: { token: 'string(113)', limit: 'number' } }`. See
+     *     `redactionShape.ts` for the rules and for the one real trade (a
+     *     string's LENGTH is disclosed).
      *   - `'none'` — the raw input, verbatim. What every sink did before this
      *     option existed.
      *   - a function — `(event) => unknown`, for field-level control.
@@ -345,13 +370,17 @@ export declare interface AuditPluginOptions {
      * row; leaking a credential is not visible at all. Opt in per app with a
      * function once you know your own inputs.
      */
-    readonly redactInput?: 'all' | 'none' | ((event: AuditEvent) => unknown);
+    readonly redactInput?: 'all' | 'shape' | 'none' | ((event: AuditEvent) => unknown);
     /**
      * What happens to `AuditEvent.subject` before it is handed to the sink.
      *
      *   - `'metadata'` (DEFAULT) — `subject.metadata` is replaced by
      *     `{ __redacted: 'all' }`. `type`, `id`, `tenantId` and `scopes` survive,
      *     which is everything the trail is actually read for.
+     *   - `'metadata-shape'` — the same, but `metadata`'s STRUCTURE survives
+     *     instead of nothing. Useful for the case this whole option exists for:
+     *     seeing THAT a credential-shaped value sits in the bag, and how long it
+     *     is, without recording it.
      *   - `'none'` — the subject verbatim. What every sink did before this option
      *     existed.
      *   - a function — `(subject) => unknown`, for field-level control.
@@ -379,8 +408,18 @@ export declare interface AuditPluginOptions {
      * `resolveScope` still sees the LIVE subject, so a scope derived from
      * `metadata` keeps working — redaction applies to what is STORED, not to what
      * the plugin can compute.
+     *
+     * KNOWN DEBT, on the DEFAULT. An impersonation mark lives in `metadata`, so
+     * under `'metadata'` a durable trail records an impersonated action
+     * indistinguishably from the user's own — the one distinction an audit trail
+     * exists to make. `impersonationAuditRedactor()` plus an always-on grant row
+     * mitigates it, and `'metadata-shape'` narrows it further (the KEY survives,
+     * so the row at least says an impersonation mark was there). Neither is the
+     * fix. The fix is a keep-these-keys option, or a first-class
+     * `AuditEvent.impersonation` field that the redactors cannot reach — because
+     * "who really did this" is not app-controlled metadata, it is the event.
      */
-    readonly redactSubject?: 'metadata' | 'none' | ((subject: Subject) => unknown);
+    readonly redactSubject?: 'metadata' | 'metadata-shape' | 'none' | ((subject: Subject) => unknown);
     /**
      * What happens to `AuditEvent.outcome`'s payload before it is handed to the
      * sink.
@@ -388,6 +427,10 @@ export declare interface AuditPluginOptions {
      *   - `'all'` (DEFAULT) — `outcome.value` on success, and `outcome.error` on
      *     failure, are replaced by `{ __redacted: 'all' }`. `kind`, `durationMs`
      *     and the error's TAG survive, which is what the trail is read for.
+     *   - `'shape'` — the STRUCTURE survives instead of nothing. This is the
+     *     option a consumer asked for after a day spent on a bug their own trail
+     *     could have ended: a value arrived as 113 characters where 44 were due,
+     *     and the row that would have said so read `{"__redacted":"all"}`.
      *   - `'none'` — the outcome verbatim. What every sink did before this
      *     option existed.
      *   - a function — `(event) => unknown`, for field-level control.
@@ -419,7 +462,7 @@ export declare interface AuditPluginOptions {
      * A `record` predicate still sees the LIVE outcome, so a filter that keys on
      * the result keeps working — redaction applies to what is STORED.
      */
-    readonly redactOutcome?: 'all' | 'none' | ((event: AuditEvent) => unknown);
+    readonly redactOutcome?: 'all' | 'shape' | 'none' | ((event: AuditEvent) => unknown);
 }
 
 /** The narrow read surface the entry points need. */

package/dist/index.js

@@ -1,11 +1,29 @@
 import { audit as e } from "./mixin.js";
 import { Effect as t } from "effect";
-import { definePlugin as n, pluginInstanceName as r } from "@voltro/protocol";
-import { createLogger as i } from "@voltro/logger";
-import { and as a, eq as o, id as s, integer as c, json as l, registerRetention as u, resolveActorSnapshot as d, retentionTtlMsFromEnv as f, table as p, text as m, timestamp as h } from "@voltro/database";
-import { createHash as g, createHmac as _, randomBytes as v } from "node:crypto";
-//#region src/tableName.ts
-var y = "_voltro_audit_log", b = [
+import { definePlugin as n, pluginInstanceName as r, rawImpersonationMark as i } from "@voltro/protocol";
+import { createLogger as a } from "@voltro/logger";
+import { and as o, eq as s, id as c, integer as l, json as u, registerRetention as d, resolveActorSnapshot as f, retentionTtlMsFromEnv as p, table as m, text as h, timestamp as g } from "@voltro/database";
+import { createHash as _, createHmac as v, randomBytes as y } from "node:crypto";
+//#region src/redactionShape.ts
+var b = 4, x = 32, S = 64, C = /^[A-Za-z_$][A-Za-z0-9_$]*$/, w = (e) => e.length <= S && C.test(e) ? e : `<key:string(${e.length})>`, T = (e, t = 0) => {
+	if (e === null) return "null";
+	if (e === void 0) return "undefined";
+	let n = typeof e;
+	if (n === "string") return `string(${e.length})`;
+	if (n === "number" || n === "boolean" || n === "bigint" || n === "symbol" || n === "function") return n;
+	if (e instanceof Date) return "date";
+	if (t >= b) return Array.isArray(e) ? "array(…)" : "object(…)";
+	if (Array.isArray(e)) {
+		let n = e.slice(0, x).map((e) => T(e, t + 1));
+		return e.length > x ? [...n, `…${e.length - x} more`] : n;
+	}
+	if (n === "object") {
+		let n = Object.entries(e), r = {};
+		for (let [e, i] of n.slice(0, x)) r[w(e)] = T(i, t + 1);
+		return n.length > x && (r["…"] = `${n.length - x} more key(s)`), r;
+	}
+	return n;
+}, E = (e) => ({ __redacted: T(e) }), D = "_voltro_audit_log", O = [
 	"tag",
 	"at",
 	"subjectId",
@@ -20,26 +38,26 @@ var y = "_voltro_audit_log", b = [
 	"input",
 	"outcome",
 	"errorTag"
-], x = (e) => {
+], k = (e) => {
 	if (e == null) return "null";
 	if (e instanceof Date) return JSON.stringify(e.toISOString());
 	let t = typeof e;
-	return t === "number" || t === "boolean" || t === "string" ? JSON.stringify(e) : t === "bigint" ? JSON.stringify(String(e)) : Array.isArray(e) ? `[${e.map(x).join(",")}]` : t === "object" ? `{${Object.entries(e).filter(([, e]) => e !== void 0).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, t]) => `${JSON.stringify(e)}:${x(t)}`).join(",")}}` : JSON.stringify(String(e));
-}, S = (e) => e instanceof Date ? e.toISOString() : e, C = (e) => x(Object.fromEntries(b.map((t) => [t, S(e[t] ?? null)]))), w = (e) => {
+	return t === "number" || t === "boolean" || t === "string" ? JSON.stringify(e) : t === "bigint" ? JSON.stringify(String(e)) : Array.isArray(e) ? `[${e.map(k).join(",")}]` : t === "object" ? `{${Object.entries(e).filter(([, e]) => e !== void 0).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, t]) => `${JSON.stringify(e)}:${k(t)}`).join(",")}}` : JSON.stringify(String(e));
+}, A = (e) => e instanceof Date ? e.toISOString() : e, j = (e) => k(Object.fromEntries(O.map((t) => [t, A(e[t] ?? null)]))), M = (e) => {
 	let t = process.env.VOLTRO_AUDIT_CHAIN_SECRET;
-	return t ? _("sha256", t).update(e, "utf8").digest("hex") : g("sha256").update(e, "utf8").digest("hex");
-}, T = (e, t) => w(JSON.stringify([
+	return t ? v("sha256", t).update(e, "utf8").digest("hex") : _("sha256").update(e, "utf8").digest("hex");
+}, N = (e, t) => M(JSON.stringify([
 	t.chainId,
 	t.seq,
 	t.prevHash,
-	C(e)
-])), E = (e = v(12).toString("base64url")) => {
+	j(e)
+])), P = (e = y(12).toString("base64url")) => {
 	let t = 0, n = null;
 	return {
 		chainId: e,
 		link: (r) => {
 			t += 1;
-			let i = T(r, {
+			let i = N(r, {
 				chainId: e,
 				seq: t,
 				prevHash: n
@@ -53,9 +71,9 @@ var y = "_voltro_audit_log", b = [
 			return n = i, a;
 		}
 	};
-}, D = async (e, t = {}) => {
-	let n = t.chainId === void 0 ? void 0 : o("chainId", t.chainId), r = await e.query({
-		table: y,
+}, F = async (e, t = {}) => {
+	let n = t.chainId === void 0 ? void 0 : s("chainId", t.chainId), r = await e.query({
+		table: D,
 		...n ? { predicate: n } : {},
 		order: [{
 			column: "chainId",
@@ -65,7 +83,7 @@ var y = "_voltro_audit_log", b = [
 			direction: "asc"
 		}],
 		...t.limit === void 0 ? {} : { take: t.limit }
-	}), i = [], a = [], s = 0, c = 0, l = null, u = () => {
+	}), i = [], a = [], o = 0, c = 0, l = null, u = () => {
 		l &&= (a.push({
 			chainId: l.chainId,
 			from: l.from,
@@ -77,16 +95,16 @@ var y = "_voltro_audit_log", b = [
 	for (let e of r) {
 		let t = e.chainId, n = e.hash, r = e.seq;
 		if (typeof t != "string" || typeof n != "string" || r == null) {
-			s += 1;
+			o += 1;
 			continue;
 		}
-		let a = Number(r), o = typeof e.prevHash == "string" ? e.prevHash : null, d = typeof e.id == "string" ? e.id : void 0;
+		let a = Number(r), s = typeof e.prevHash == "string" ? e.prevHash : null, d = typeof e.id == "string" ? e.id : void 0;
 		c += 1, !l || l.chainId !== t ? (u(), l = {
 			chainId: t,
 			from: a,
 			last: a,
 			tip: n
-		}) : (a === l.last + 1 ? o !== l.tip && i.push({
+		}) : (a === l.last + 1 ? s !== l.tip && i.push({
 			kind: "broken-link",
 			chainId: t,
 			seq: a,
@@ -97,10 +115,10 @@ var y = "_voltro_audit_log", b = [
 			chainId: t,
 			seq: l.last + 1,
 			detail: `chain jumps from seq ${l.last} to ${a} — ${a - l.last - 1} row(s) missing`
-		}), l.last = a, l.tip = n), T(e, {
+		}), l.last = a, l.tip = n), N(e, {
 			chainId: t,
 			seq: a,
-			prevHash: o
+			prevHash: s
 		}) !== n && i.push({
 			kind: "tampered",
 			chainId: t,
@@ -112,31 +130,32 @@ var y = "_voltro_audit_log", b = [
 	return u(), {
 		ok: i.length === 0,
 		rowsChecked: c,
-		unchainedRows: s,
+		unchainedRows: o,
 		chains: a,
 		issues: i,
 		keyed: !!process.env.VOLTRO_AUDIT_CHAIN_SECRET
 	};
-}, O = p(y, {
-	id: s({ prefix: "audit" }),
-	tag: m(),
-	at: h(),
-	subjectId: m().nullable(),
-	tenantId: m().nullable(),
-	traceId: m(),
-	status: m(),
-	durationMs: m(),
-	subject: l(),
-	actor: l().nullable(),
-	scope: l().nullable(),
-	metadata: l().nullable(),
-	input: l(),
-	outcome: l(),
-	errorTag: m().nullable(),
-	chainId: m().nullable(),
-	seq: c().nullable(),
-	prevHash: m().nullable(),
-	hash: m().nullable()
+}, I = m(D, {
+	id: c({ prefix: "audit" }),
+	tag: h(),
+	at: g(),
+	subjectId: h().nullable(),
+	tenantId: h().nullable(),
+	traceId: h(),
+	status: h(),
+	durationMs: h(),
+	subject: u(),
+	actor: u().nullable(),
+	scope: u().nullable(),
+	metadata: u().nullable(),
+	impersonation: u().nullable(),
+	input: u(),
+	outcome: u(),
+	errorTag: h().nullable(),
+	chainId: h().nullable(),
+	seq: l().nullable(),
+	prevHash: h().nullable(),
+	hash: h().nullable()
 }).index("byAuditTag", ["tag"]).index("byAuditTrace", ["traceId"]).index("byAuditSubjectStatus", [
 	"subjectId",
 	"status",
@@ -145,7 +164,7 @@ var y = "_voltro_audit_log", b = [
 	"tenantId",
 	"status",
 	"at"
-]).index("byAuditChain", ["chainId", "seq"]), k = [O], A = (e) => ({
+]).index("byAuditChain", ["chainId", "seq"]), L = [I], R = (e) => ({
 	tag: e.tag,
 	at: new Date(e.ts),
 	subjectId: e.subject.id ?? null,
@@ -157,45 +176,46 @@ var y = "_voltro_audit_log", b = [
 	actor: e.actor ?? null,
 	scope: e.scope ?? null,
 	metadata: e.metadata ?? null,
+	impersonation: e.impersonation ?? null,
 	input: e.input,
 	outcome: e.outcome,
-	errorTag: e.outcome.kind === "error" ? j(e.outcome.error) : null
-}), j = (e) => {
+	errorTag: e.outcome.kind === "error" ? z(e.outcome.error) : null
+}), z = (e) => {
 	if (typeof e != "object" || !e) return null;
 	let t = e._tag;
 	return typeof t == "string" && t !== "" ? t : null;
-}, M = async (e, t) => e.query({
-	table: y,
-	predicate: o("traceId", t),
+}, B = async (e, t) => e.query({
+	table: D,
+	predicate: s("traceId", t),
 	order: [{
 		column: "at",
 		direction: "asc"
 	}]
-}), N = async (e, t, n = {}) => {
-	let r = o("subjectId", t);
+}), V = async (e, t, n = {}) => {
+	let r = s("subjectId", t);
 	return e.query({
-		table: y,
-		predicate: n.status === void 0 ? r : a(r, o("status", n.status)),
+		table: D,
+		predicate: n.status === void 0 ? r : o(r, s("status", n.status)),
 		order: [{
 			column: "at",
 			direction: "desc"
 		}],
 		take: n.limit ?? 100
 	});
-}, P = (e) => {
-	let t = E();
+}, H = (e) => {
+	let t = P();
 	return async (n) => {
 		let r = n.actor !== void 0 || typeof e.query != "function" ? n : {
 			...n,
-			actor: await d(e, n.subject.id ?? null, n.subject.type)
+			actor: await f(e, n.subject.id ?? null, n.subject.type)
 		};
-		await e.insert(y, t.link(A(r)));
+		await e.insert(D, t.link(R(r)));
 	};
-}, F = i({ scope: "@voltro/plugin-audit" }), I = 1e3, L = [], R = () => [...L], z = () => {
-	L.length = 0;
-}, B = (e) => {
-	L.push(e), L.length > I && L.splice(0, L.length - I);
-}, V = (e) => {
+}, U = a({ scope: "@voltro/plugin-audit" }), W = 1e3, G = [], K = () => [...G], q = () => {
+	G.length = 0;
+}, J = (e) => {
+	G.push(e), G.length > W && G.splice(0, G.length - W);
+}, Y = (e) => {
 	let t = e.subject.id ? `${e.subject.type}:${e.subject.id}` : e.subject.type, n = e.outcome.kind === "ok" ? "ok" : "error", r = {
 		subject: t,
 		tenant: e.subject.tenantId ?? null,
@@ -203,8 +223,8 @@ var y = "_voltro_audit_log", b = [
 		durationMs: e.outcome.durationMs,
 		traceId: e.traceId
 	};
-	n === "error" ? F.warn(e.tag, r) : F.info(e.tag, r);
-}, H = (e, n) => typeof e == "function" ? (n) => t.suspend(() => {
+	n === "error" ? U.warn(e.tag, r) : U.info(e.tag, r);
+}, X = (e, n) => typeof e == "function" ? (n) => t.suspend(() => {
 	let r = e(n);
 	return r === void 0 ? t.void : t.isEffect(r) ? r : t.tryPromise({
 		try: () => Promise.resolve(r),
@@ -216,7 +236,7 @@ var y = "_voltro_audit_log", b = [
 		try: () => r(e),
 		catch: (e) => e
 	}) : t.void;
-}) : e === "memory" ? (e) => t.sync(() => B(e)) : (e) => t.sync(() => V(e)), U = (e) => {
+}) : e === "memory" ? (e) => t.sync(() => J(e)) : (e) => t.sync(() => Y(e)), Z = (e) => {
 	let t = [], n = [], r = (e) => {
 		if (e._tag !== "Empty") {
 			if (e._tag === "Fail") {
@@ -240,46 +260,52 @@ var y = "_voltro_audit_log", b = [
 		}
 	};
 	return r(e), t[0] ?? n[0] ?? e;
-}, W = "@voltro/plugin-audit", G = (e = {}) => {
-	let i = e.sink === "datastore";
-	i && u({
+}, Q = "@voltro/plugin-audit", $ = (e = {}) => {
+	let a = e.sink === "datastore";
+	a && d({
 		source: "plugin",
-		table: y,
+		table: D,
 		timeColumn: "at",
-		ttlMs: f(process.env.VOLTRO_AUDIT_LOG_TTL_HOURS, 24 * 365)
+		ttlMs: p(process.env.VOLTRO_AUDIT_LOG_TTL_HOURS, 24 * 365)
 	});
-	let a, o = H(e.sink, () => a), s = (e) => e === void 0 || !e.global && !e.sticky ? e : new RegExp(e.source, e.flags.replace(/[gy]/g, "")), c = s(e.exclude), l = s(e.include), d = (e) => !(c?.test(e) || l && !l.test(e)), p = (t) => {
+	let o, s = X(e.sink, () => o), c = (e) => e === void 0 || !e.global && !e.sticky ? e : new RegExp(e.source, e.flags.replace(/[gy]/g, "")), l = c(e.exclude), u = c(e.include), f = (e) => !(l?.test(e) || u && !u.test(e)), m = (t) => {
 		let n = e.record ?? "all";
 		return n === "all" ? !0 : n === "errors" ? t.outcome.kind === "error" : n(t);
-	}, m = { __redacted: "all" }, h = (t) => {
+	}, h = { __redacted: "all" }, g = (t) => {
 		let n = e.redactInput ?? "all";
-		return n === "none" ? t : {
+		return n === "none" ? t : n === "all" ? {
+			...t,
+			input: h
+		} : n === "shape" ? {
 			...t,
-			input: n === "all" ? m : n(t)
+			input: E(t.input)
+		} : {
+			...t,
+			input: n(t)
 		};
-	}, g = (t) => {
+	}, _ = (t) => {
 		let n = e.redactOutcome ?? "all";
 		if (n === "none") return t;
-		let r = n === "all" ? m : n(t), i = t.outcome;
-		if (i.kind === "ok") return {
+		let r = t.outcome, i = n === "all" ? h : n === "shape" ? ((e) => E(e))(r.kind === "ok" ? r.value : r.error) : n(t);
+		if (r.kind === "ok") return {
 			...t,
 			outcome: {
-				...i,
-				value: r
+				...r,
+				value: i
 			}
 		};
-		let a = i.error, o = typeof a == "object" && a ? a._tag : void 0;
+		let a = r.error, o = typeof a == "object" && a ? a._tag : void 0;
 		return {
 			...t,
 			outcome: {
-				...i,
-				error: o === void 0 ? r : {
+				...r,
+				error: o === void 0 ? i : {
 					_tag: o,
-					...r
+					...i
 				}
 			}
 		};
-	}, _ = (t) => {
+	}, v = (t) => {
 		let n = e.redactSubject ?? "metadata";
 		if (n === "none") return t;
 		if (typeof n == "function") return {
@@ -288,23 +314,29 @@ var y = "_voltro_audit_log", b = [
 		};
 		let r = t.subject;
 		if (r.metadata === void 0) return t;
-		let { metadata: i, ...a } = r;
+		let { metadata: i, ...a } = r, o = n === "metadata-shape" ? E(i) : h;
 		return {
 			...t,
 			subject: {
 				...a,
-				metadata: m
+				metadata: o
 			}
 		};
-	}, v = (e) => p(e) ? o(g(_(h(e)))) : t.void, b = (t) => {
+	}, y = (e) => {
+		let t = i(e.subject);
+		return t === null ? e : {
+			...e,
+			impersonation: t
+		};
+	}, b = (e) => m(e) ? s(_(v(g(y(e))))) : t.void, x = (t) => {
 		if (e.resolveScope !== void 0) try {
 			return e.resolveScope(t);
 		} catch {
 			return;
 		}
-	}, x = (e, n) => d(n.tag) ? t.suspend(() => {
-		let r = Date.now(), i = b(n);
-		return e.pipe(t.tap((e) => v({
+	}, S = (e, n) => f(n.tag) ? t.suspend(() => {
+		let r = Date.now(), i = x(n);
+		return e.pipe(t.tap((e) => b({
 			ts: r,
 			tag: n.tag,
 			subject: n.subject,
@@ -316,7 +348,7 @@ var y = "_voltro_audit_log", b = [
 				value: e,
 				durationMs: Date.now() - r
 			}
-		}).pipe(t.catchAllCause(() => t.void))), t.tapErrorCause((e) => v({
+		}).pipe(t.catchAllCause(() => t.void))), t.tapErrorCause((e) => b({
 			ts: r,
 			tag: n.tag,
 			subject: n.subject,
@@ -325,34 +357,34 @@ var y = "_voltro_audit_log", b = [
 			input: n.input,
 			outcome: {
 				kind: "error",
-				error: U(e),
+				error: Z(e),
 				durationMs: Date.now() - r
 			}
 		}).pipe(t.catchAllCause(() => t.void))));
-	}) : e, S = x, C = x, w = x;
+	}) : e, C = S, w = S, T = S;
 	return n({
 		name: r({
-			base: W,
+			base: Q,
 			alias: e.alias
 		}),
-		baseName: W,
+		baseName: Q,
 		description: "Records every mutation invocation; ships an audit() schema mixin for row-level metadata.",
 		permissions: [
 			"rpc:intercept:mutation",
 			"rpc:intercept:action",
-			...i ? ["store:write"] : [],
+			...a ? ["store:write"] : [],
 			...e.recordQueries === !0 ? ["rpc:intercept:query"] : []
 		],
-		...i ? {
-			...e.tables === !1 ? {} : { extendSchema: { tables: k } },
+		...a ? {
+			...e.tables === !1 ? {} : { extendSchema: { tables: L } },
 			bindDataStore: (e) => {
-				a = P(e);
+				o = H(e);
 			}
 		} : {},
-		interceptMutation: S,
-		interceptAction: C,
-		...e.recordQueries === !0 ? { interceptQuery: w } : {}
+		interceptMutation: C,
+		interceptAction: w,
+		...e.recordQueries === !0 ? { interceptQuery: T } : {}
 	});
 };
 //#endregion
-export { y as AUDIT_LOG_TABLE, e as audit, N as auditBySubject, M as auditByTrace, A as auditEventToRow, O as auditLogTable, k as auditLogTables, G as auditPlugin, T as auditRowHash, z as clearAuditBuffer, P as dataStoreAuditSink, E as makeAuditChain, R as readAuditBuffer, D as verifyAuditChain };
+export { D as AUDIT_LOG_TABLE, e as audit, V as auditBySubject, B as auditByTrace, R as auditEventToRow, I as auditLogTable, L as auditLogTables, $ as auditPlugin, N as auditRowHash, q as clearAuditBuffer, H as dataStoreAuditSink, P as makeAuditChain, K as readAuditBuffer, F as verifyAuditChain };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-audit",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Audit plugin — ships the `audit()` schema mixin (createdAt/updatedAt/createdBy/updatedBy → Actor) plus an optional mutation interceptor that records every call to a configurable sink (console / memory / custom function).",
   "keywords": [
     "voltro",
@@ -38,9 +38,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.36.0",
-    "@voltro/logger": "0.36.0",
-    "@voltro/protocol": "0.36.0"
+    "@voltro/database": "0.38.0",
+    "@voltro/logger": "0.38.0",
+    "@voltro/protocol": "0.38.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"