@voltro/plugin-auth-auth0 0.11.2 → 0.11.4

package/CHANGELOG.md

@@ -39,6 +39,234 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.11.4] — 2026-07-25
+
+### Added
+
+- **@voltro/protocol** — **`ApiKeyRecord.metadata` — an app-defined binding carried onto the Subject.** `tenantId` is ONE level of key ownership. A product whose keys belong to a TEAM, a project or an environment needs a second, and the record had no slot for it — so the only safe way to authorize was a DB lookup on every check, on the auth hot path. Reported from an app whose `requireScope` could not see the team, so a key minted for team A authorized org-wide until they patched it with a per-check query.
+
+  ```ts
+  resolveKey: async (hash) => {
+    const row = await findKey(hash)
+    return row && { ...row, metadata: { keyType: row.keyType, teamId: row.teamId } }
+  }
+  // a guard then reads subject.metadata.teamId — no second query
+  ```
+
+  Merged UNDER the framework's own claims: `provider` and `userId` are the strategy's attribution of the request and are applied last, so an app's bag cannot overwrite who the framework thinks made the call (tested). A record without `metadata` behaves exactly as before.
+- **@voltro/cli** — `voltro db generate [name]` now scaffolds a fresh, heavily-commented `migrations/<timestamp>_<name>.migration.ts` (the imperative path for data backfills / transforms the declarative differ can't express — for plain schema shape changes prefer `voltro db apply`). The name is slugified; `--name` overrides the positional, `--root` sets where `migrations/` lives. Replaces the old "not yet implemented" stub, and `db generate` is back in the command summary. `voltro db migrate --dry-run` is implemented too — it lists the pending migrations (querying the ledger for what's applied) without applying them, instead of erroring as unimplemented.
+- **@voltro/runtime** — `crud.list(table, { columns })` — SQL column projection, so a wide column a list view never shows is **never read**, not merely dropped at the wire boundary:
+
+  ```ts
+  export default crud.list('articles', { columns: ['id', 'title', 'createdAt'] })
+  // the large `body` / json blob is never SELECTed, transferred, or decoded
+  ```
+
+  This is the performance half of projection. The output schema already strips undeclared columns on encode (so nothing extra ever shipped either way) — `columns` additionally saves the read, the DB→app transfer, and the decode.
+
+  `.serverOnly()` columns are removed from the projection automatically: they are stripped from the response regardless, so SELECTing them is pure waste.
+
+  Trap worth knowing: an eager `include` branch joins on a foreign key, so a projection that omits that FK column breaks the relation — keep the FK in `columns` when you also pass `include`. Additive: a new optional `columns` on `CrudListOptions`; omitting it reads the full row exactly as before.
+- **@voltro/runtime** — `crud.list(table, options)` gains the read ergonomics a real list view needs, so a generated list isn't limited to "all rows" (the reason a rich hand-written list couldn't move to `crud.*`):
+
+  ```ts
+  export default crud.list('absenceRequests', {
+    filter:   (input) => ({ employeeId: input.employeeId, status: input.status }), // → WHERE
+    paginate: true,                                        // input.limit / input.offset (100 / 0)
+    sort:     [{ column: 'createdAt', direction: 'desc' }], // multi-column
+    include:  { employee: { with: { team: true } } },      // eager relations, nested filter/sort
+    redact:   ['internalNote'],
+  })
+  ```
+
+  - **`filter`** maps request input to a `WHERE` — a column→value map; an `undefined` field is ignored (so an absent filter param is a no-op). Applied through the tenant-scoped `.where`. - **`paginate`** reads `input.limit` / `input.offset` (defaults 100 / 0). - **`sort`** is a multi-column `orderBy`, applied in order. - **`include`** is the SAME spec `.with(...)` takes, so nested relations and per-branch `where` / `orderBy` / `limit` (nested filtering + sort) all work. `getById` takes `include` too.
+
+  All optional and additive: `CrudListOptions extends CrudReadOptions`, so a bare `crud.list('t')` or `crud.list('t', { redact })` is unchanged. The descriptor's `input` schema declares the filter/pagination fields, and its `output` schema stays hand-written (deriving the projection from the output schema is a codegen concern — a table value can't enter a browser-loaded descriptor).
+- **@voltro/runtime** — `crud.list`'s `paginate` now accepts **page-based** paging beside offset-based, and `crud.count` gives a page-based UI the total it needs:
+
+  ```ts
+  // list: ?page=3&pageSize=20   (or ?limit=20&offset=40 — both work)
+  export default crud.list('absenceRequests', { paginate: true, filter, sort })
+  // total for "page 3 of 12"
+  export default crud.count('absenceRequests', { filter })
+  ```
+
+  - **`page`** is **1-based** (what a UI shows) and pairs with **`pageSize`** (default 100); `offset` is computed as `(page - 1) * pageSize`. A `page` below 1 clamps to the first page rather than producing a negative OFFSET. - **`limit` / `offset`** still work unchanged. `page` wins when a caller sends both. - **`crud.count(table, { filter })`** is a real `COUNT(*)` aggregate over the same tenant-scoped, filtered set — it ignores paging fields on the input, so the total describes the whole result, not the current page. Pass it the SAME `filter` as the list (share the option object) so the count and the pages can't disagree about which rows they mean.
+
+  Additive: paging style is detected from the request input, so an existing `paginate: true` list is unchanged.
+- **@voltro/cli** — **`voltro inspect schedules --failing`** — roll up each schedule's recent runs and report only the broken ones, exiting **1** when anything is failing.
+
+  A schedule fires unattended, so a broken one is discovered by someone going to look — and the only thing to look at was the REGISTRATION (which cron exists, when it fires next), never whether it works. That is how three nightly jobs in a downstream app stayed dead for months after a port: each was registered, each fired on time, each threw.
+
+  The exit code is the point: it makes this usable as a post-deploy gate (`voltro inspect schedules --failing || exit 1`) rather than something a human has to remember. Needed no new endpoint — `/schedules/runs` already returns the recorded firings; the roll-up is a client-side join, which keeps the cost on the diagnostic command instead of on every dashboard poll.
+
+  A trailing success ends a streak (a recovered job is not reported) and `skipped`/`missed` runs are ignored — those are coordination outcomes, not handler verdicts. Pairs with the schedule failure now logging at `error`.
+- **@voltro/runtime** — `ctx.store.links(junction, anchor).setRows(rows)` — a diff-based reconcile for a many-to-many junction that carries PER-ROW PAYLOAD (a membership `role`, a `capacity` value), the case `set(targetIds)` couldn't model. Each row is `{ [targetColumn]: id, …payload }`; the diff is on the (source, target) pair — an added row is inserted with its payload, a removed row deleted, and a SURVIVING row whose payload actually changed is UPDATED. A row whose payload is unchanged is left untouched, so a reactive consumer sees a change only where the payload differs — the drop+reinsert replacement for a data-carrying junction. Returns `{ added, removed, updated }`. Payload is compared by strict per-column equality (scalars). Additive: a new `setRows` method on `JunctionLinks`.
+- **@voltro/runtime, @voltro/cli** — **A query can now be projected to a public REST endpoint.** `publicApi` on a descriptor was only ever mounted for mutations and actions — a QUERY carrying it produced no route at all, silently. Both boot paths now mount queries too, so offering an API you don't consume from your own frontend is a one-line annotation:
+
+  ```ts
+  export default defineQuery({
+    name: 'absenceRequests.list',
+    input: Schema.Struct({ status: Schema.optional(Schema.String), limit: Schema.optional(Schema.Number) }),
+    output: Schema.Array(AbsenceRequest),
+    guards: [requireScope('absences:read')],
+    publicApi: {},          // → GET /v1/absenceRequests/list?status=open&limit=20
+  })
+  ```
+
+  A query derives **GET**, and its `input` schema binds to the **query string** (`publicApi.ts` wraps it as `{ query }` for GET) — so filter and pagination parameters work as plain URL params. Eager relations work too: `include` is resolved server-side by the executor, so the transport makes no difference. This pairs with `crud.list`'s `filter` / `paginate` / `sort` / `include`, which is what makes a REST list endpoint a single declaration.
+
+  The one-shot execution is `makeOneShotQueryRunner` (`@voltro/runtime`), built ON TOP of the existing `makeQueryDescriptorProducer` rather than beside it — so the declarative `guards:` gate, the per-request row filter and the tenant/soft-delete scoping are literally the same code the socket path runs. A second implementation would have been an authorization bypass on exactly the reads `publicApi` exposes; the tests pin that a guarded query rejects on the REST path with the executor never running and no read issued. Both handler shapes resolve: a descriptor-returning (reactive) query is finalized and executed to rows, a computed query yields its value. Wired identically in `voltro dev` and `voltro serve` (the dev/serve parity rule) from one shared deps object per path.
+- **@voltro/protocol, @voltro/runtime, @voltro/cli** — **`publicApi: { stream: 'sse' }` on a query now streams.** The field was declared but unimplemented — a query annotated with it silently served the first snapshot as JSON. It now mounts a Server-Sent-Events endpoint: the initial `snapshot`, then a `delta` per change, until the client disconnects.
+
+  ```ts
+  export default defineQuery({
+    name: 'orders.live',
+    input: Schema.Struct({ status: Schema.optional(Schema.String) }),
+    output: Schema.Array(Order),
+    guards: [requireScope('orders:read')],
+    publicApi: { stream: 'sse' },   // → GET /v1/orders/live?status=open  (text/event-stream)
+  })
+  ```
+
+  ```js
+  const es = new EventSource('/v1/orders/live?status=open')
+  es.addEventListener('snapshot', (e) => setRows(JSON.parse(e.data).data))
+  es.addEventListener('delta',    (e) => applyDelta(JSON.parse(e.data)))
+  ```
+
+  Each event's `_tag` becomes the SSE `event:` name, so a client listens per kind rather than switch-ing on a payload field. Framing splits embedded newlines across `data:` lines (a raw `\n` would truncate the event), sends `retry: 5000`, and emits a keep-alive comment every 15s so proxies don't drop an idle stream (`cache-control: no-transform` + `x-accel-buffering: no` for the same reason).
+
+  Three things this deliberately does NOT do differently from the socket: authorization (the subscription runs through the same `makeQueryDescriptorProducer`, so the declarative `guards:`, the row filter and tenant scoping are the same code), leak handling (the client's disconnect runs the route's own unsubscribe through the response scope's finalizer, and a disconnect DURING setup tears the late-arriving subscription down), and error reporting (a guard denial arrives as one `error` EVENT — by then the response headers are on the wire, so throwing is not available).
+
+  New building blocks, useful beyond publicApi: `PluginHttpRouteResult.stream` lets ANY plugin HTTP route stream, with `sse()` / `sseFrame()` helpers in `@voltro/protocol/rest` for a hand-written `defineRestRoute`; `makeQuerySubscriber` (`@voltro/runtime`) is the shared dispatcher binding both boot paths use. Wired identically in `voltro dev` and `voltro serve`. A `stream: 'sse'` annotation on a mutation/action is ignored (nothing to subscribe to), and a query whose boot layer supplies no subscribe binding falls back to the snapshot response rather than mounting a route that never emits.
+- **@voltro/runtime, @voltro/cli** — Boot audit for the `.serverOnly()` marker (#22): `voltro dev` now warns, naming the query + column, when a wire-reachable query's `output` schema DECLARES a `.serverOnly()` column of its `source` table. The `crud.*` read helpers strip these automatically, but a hand-written output can only be caught here — this is what would have flagged the reported dead `apiKeys.getByKeyId` query that shipped a `keyHash`.
+
+  Backed by pure, unit-tested helpers exported from `@voltro/runtime`: `serverOnlyLeaks` (a query's output vs its source's serverOnly columns) and `schemaPropertyNames` (best-effort field introspection over the output Schema AST — Struct / Array-of-Struct / NullOr / nested). Detection under-covers rather than false-positives: a shape it can't read yields no field names. The fix it points you at is to omit the column from the output schema (a runtime strip would fail the encode against a schema that still declares the field — the reason this is an audit, not a strip).
+- **@voltro/database, @voltro/runtime** — `.serverOnly()` column marker + `serverOnlyColumns(table)` (#22) — the wire-EXPOSURE axis, declared explicitly at the schema and distinct from `.encrypted()` (storage at rest) and `.sensitive()` (export masking). A `.serverOnly()` column is read normally by server code but must never be serialized to a client:
+
+  ```ts
+  keyHash: text().serverOnly(),          // an auth middleware verifies it; a client never sees it
+  apiToken: text().encrypted().serverOnly(), // a column can carry both axes, or either
+  ```
+
+  The [`crud.*` read helpers](#) strip `.serverOnly()` columns from every returned row AUTOMATICALLY — declare the exposure policy once at the schema and every crud read respects it, so you can't forget it on a handler (the single-source form of the per-call `redact` option, which still works for anything not worth a marker).
+
+  Why a NEW axis rather than reusing `.encrypted()`: encryption at rest says nothing about who may receive the plaintext — decrypting a private note *for its owner* is a valid case, so treating "encrypted" as "never to a client" would be wrong. Exposure is stated explicitly. Default stays exposed to both server and client; `.serverOnly()` opts a column out of the client.
+
+  Additive: a `serverOnly()` builder method + a `serverOnly?` flag on `ColumnDefinition` + the `serverOnlyColumns` helper. Enforcement beyond the `crud.*` path — a runtime strip at the rpc wire boundary and a `serverOnly: true` whole-query primitive — is a planned follow-on (see `plans/framework-serverOnly-exposure.md`).
+
+### Fixed
+
+- **@voltro/cli** — Machine output is now consistent across the CLI. `--json` works everywhere it should: the inspect-family commands (inspect/logs/traces/cluster/check) accept `--json` (and `--format=json`) as an alias for `--format json` — `voltro inspect app --json` silently produced pretty output before; and cloud/capabilities/doctor accept both spellings too. All `--json` payloads route through one `printJson` helper, and `bin.ts` now drains stdout before `process.exit`, so a large payload piped to a file / `| jq` is no longer truncated (only `voltro db --json` was safe before). A user-invocation mistake (no app.config here, a memory dialect where a real one is needed) now prints a clean one-line error instead of a stack trace (new `CliError`, rendered by bin.ts).
+- **@voltro/cli** — `voltro version` now prints the real installed version (was a hardcoded `v0.0.0 (scaffold)` placeholder); usage / unknown-command / version output say "voltro" instead of "framework". `voltro <command> --help` (and `-h`) now prints the command summary and returns 0 for EVERY command instead of, in several cases, running the command — `voltro env --help` used to run the env check and could exit 1. Commands with their own richer help (inspect/logs/doctor/secret) still show it. Honest command summaries: `db` now lists its declarative-workflow subcommands (plan/apply/plans/drift/squash/restore-snapshot/files/…) and drops the never-implemented `generate`; `serverless` lists `dev`/`serve` and the `node` default target; `workflows` lists `start`. `voltro cloud deploy`/`rollback`, which are not yet implemented, now fail (non-zero, stderr) instead of printing a message and returning success, and are marked "coming soon" in help.
+- **@voltro/cli** — Security: the inspect API's CORS now reflects the request `Origin` and allows credentials ONLY for loopback origins (localhost / 127.0.0.0/8 / ::1). Previously it echoed ANY origin with `access-control-allow-credentials: true`, so a website a developer visited could issue a credentialed cross-origin `fetch` and read the (default-open) inspect surface — DB rows, logs, schema, drift — and POST to fire schedules / start workflows. A non-loopback origin now gets no `access-control-allow-origin`, so the browser blocks the read; curl / same-origin / the local dashboard are unaffected. Also: the dashboard proxy (`/api/dashboard/proxy?target=`) now requires a loopback target (it forwards the caller's bearer, so an arbitrary target was an SSRF + bearer-harvest), and `~/.voltro/credentials.json` is written 0600 in a 0700 dir instead of world-readable.
+- **@voltro/cli** — `voltro serverless serve`/`dev` now exits non-zero when the server fails to bind or crashes at boot (it returned 0 = success, so a CI/deploy wrapper read a dead server as up). The production `voltro serve` shutdown chain gained a terminal `.catch` + a 10s force-exit safety net, so a rejected/hung drain step (plugin deactivate, pool close) no longer strands the process until the container's SIGKILL grace timer. `voltro e2e` cleanup now escalates SIGTERM→SIGKILL for a child that ignores SIGTERM (was lingering on :4000/:5190 and EADDRINUSE-ing the next run). `voltro migrate` now warns when it falls back to the default `localhost:5432` DB with no DB_URL/DB_HOST set.
+- **@voltro/cli** — CLI flag parsing is now shared (`src/cliArgs.ts`: `flagValue` / `takeFlag` / `hasFlag` / `positionals`) instead of each command hand-rolling its own `indexOf('--x'); args[i+1]`. Adopted across data, serve, cloud, db (14 sites), baseline, and secret — so every command accepts `--name value` AND `--name=value` uniformly. Group-command exit codes are standardized too: an unknown subcommand exits 2, a missing subcommand exits 1 (was a mix of 0/1/1-vs-1 including a dead `? 1 : 1` ternary in storage).
+- **@voltro/runtime** — **`crud.list` now caps the page size (default 1000).** The page size is CALLER-controlled — `input.limit` / `input.pageSize` — and nothing anywhere clamped it, so `?limit=1000000000` was a one-request read of the whole table. That was already unwelcome over the WebSocket; it became a genuine exposure the moment a query could be projected to a public REST endpoint (`publicApi`), where the caller is anyone who can reach the URL.
+
+  - `limit` / `pageSize` above the cap are **clamped, not rejected** (a caller asking for too much gets the maximum page, not a 400). - `maxPageSize` raises it deliberately for an export-style endpoint. - A zero/negative `limit` clamps to 1 row, and a negative `offset` / `page < 1` clamps to 0 rather than producing a negative OFFSET (which dialects reject or treat oddly). Non-integers are floored.
+
+  Found by auditing the paging code introduced in this same series — the cap was missing from the start, so this is a fix, not a behaviour change anyone relied on.
+- **@voltro/plugin-ai-flows** — **An AI-flow `MediaGenerator` can now require services.** Its type pinned the Effect requirement channel to `never`, so the common implementation — generate, then persist through `StorageService` — was untypeable while working perfectly at runtime. A type that forbids what the program does is a type lying about the program; the host was left carrying a documented cast.
+
+  `MediaGenerator` and its `EngineDeps` siblings (`resolveAgent`, `onEvent`, `memoryPrefix`) now declare `R = unknown`, the same shape `@voltro/ai` uses for tool bodies (`execute?: (input) => Effect<O, never, unknown>`). The engine runs inside the host's runtime, which HAS those services, and states that fact once in a `callDep` bridge rather than at every call site — mirroring `callBody` in `@voltro/ai`.
+
+  `apiSurface: compatible` — the change WIDENS the requirement channel on callbacks the app IMPLEMENTS. An existing implementation that requires nothing (`Effect<A, E, never>`) stays assignable to the widened type, so no downstream implementation breaks; the only consumer of the narrow form was the engine itself, which now bridges it. Verified by a full repo typecheck.
+- **@voltro/cli** — **Four discovered conventions were missing from the serve bundle — a prod-only boot crash waiting for an app to use them.** `voltro build` bundles the modules matching `API_ENTRY_PATTERN`; `voltro serve` resolves every app module from that bundle, and a convention the pattern misses falls back to loading `.ts` SOURCE, which a plain-node boot cannot do. `*.outbox.ts`, `*.connection.ts`, `*.email.tsx` and `*.migration.ts` were all absent — and all four are loaded at serve time (`serveCommand` filters outbox handlers explicitly, noting that without them the transactional outbox enqueues rows in production that nothing delivers). Fixed, and the lockstep is now a TEST (`apiEntryPatternLockstep.test.ts`) that asserts a representative filename for every convention matches — it found these four the moment it was written.
+
+  **The file conventions are now single-sourced** (`fileConventions.ts`). They were declared in five modules — dev discovery, plugin codegen, framework-table assembly, migrate, the db command — and copies of a rule that IS the rule drift silently, because each copy is internally consistent. `WORKFLOW_PATTERN` had already drifted into two shapes: strict `\.workflow\.tsx$` in discovery, loose `\.workflow\.tsx?$` in table assembly. So a file named `orders.workflow.ts` got `_voltro_workflow_*` TABLES (the loose copies counted it) but was never registered as a workflow (the strict copy skipped it) — no error, no warning, just a workflow that did nothing.
+
+  The two copies were answering DIFFERENT questions, and conflating them is what made the bug invisible, so both are now named: `WORKFLOW_DESCRIPTOR_PATTERN` (strict — the executor is paired by rewriting that exact suffix, so `.ts` could never work) and `WORKFLOW_PRESENCE_PATTERN` (loose on purpose — over-provisioning a table is harmless, missing one breaks a boot). `voltro dev` now WARNS on the gap between them, naming the file and the one-character fix, instead of skipping in silence.
+- **@voltro/database** — **A `.sensitive()` / `.safe()` marker no longer moves the schema fingerprint.** They emit no DDL and introspection never reads them back, yet they fed the hash — so adding a classification flipped the boot fast-path to "the declaration changed" and forced a full diff. A classification sweep over a few hundred tables therefore triggered a migration run, and any drift that had accumulated silently since the last real change surfaced THERE, triggered by an edit with nothing to do with it. Reported from a boot that then REFUSED and crash-looped on 31 pending ops, none of which came from the change that moved the hash.
+
+  They join `idScheme` in `stripFingerprintHints`, which already existed for exactly this class. The rule, now written down where the next field gets added: **if introspection cannot read it back, it does not belong in the fingerprint** — the hash answers "does the database match the declaration?", not "did any character of the declaration change?".
+
+  Tested including the control case (a real DDL change must still move the hash, or the test would pass against a hash that ignores everything).
+- **@voltro/i18n** — `createTypedMessages` (#16) now collects a REAL var nested inside a plural/select branch (#21). Previously `'{count, plural, one {# blocker in {discipline}} other {# blockers in {discipline}}}'` required only `count` — `discipline`, which lives inside the branches, was not extracted, so `t('key', { count })` compiled and then threw `The intl string context variable "discipline" was not provided` when it rendered. Now both `count` AND `discipline` are required at the call site.
+
+  `ICUVars` was rewritten to SCAN every `{` and classify what follows it (an arg name / a bare placeholder / a structural branch to skip) rather than match a "body up to the matching `}`", which a nested `{var}` broke. It handles arbitrary nesting, and a branch's literal text (`# days`) is still never mistaken for a var.
+
+  `apiSurface: compatible` — the `ICUVars<S>` signature is unchanged (only its body). The stricter extraction cannot break WORKING code: a call that omitted the nested var was already throwing at render (that is the bug this fixes); code that passed it — the documented workaround — keeps compiling.
+- **@voltro/protocol, @voltro/plugin-openapi** — **A streaming route is now visible on the descriptor, and OpenAPI documents it as one.** When `publicApi: { stream: 'sse' }` shipped, the streaming-ness lived inside the handler closure — so anything that INSPECTS a route without running it couldn't tell a stream from a buffered response. The OpenAPI generator therefore emitted `content: { 'application/json': <output schema> }` for an SSE endpoint: a spec that generates clients which try to parse the whole event stream as one JSON value.
+
+  `RestRouteDescriptor` gains `streaming?: boolean`, `publicApiRoute` sets it for a `stream: 'sse'` query, and the generator emits `text/event-stream` (with no JSON response schema) for such a route.
+
+  Worth stating as a rule, since it is the second time this shape has cost something: a fact that tooling must act on belongs on the DESCRIPTOR, not in the closure that implements it. A wrong spec is worse than a missing one — clients are generated from it.
+- **@voltro/runtime, @voltro/cli** — **A failing schedule handler is now an ERROR, not a warn.** A schedule fires unattended — there is no user watching a request fail — so the log line IS the discovery channel. It was `warn`, which `voltro logs --level error` does not show, and the only other surface is a dashboard nobody has open on staging.
+
+  The root cause was structural rather than a bad choice: `SchedulerLogger` had no error channel at all (`info` / `warn` / optional `debug`), so the level was not expressible. It now has one — optional, so an embedder passing a two-method logger still compiles, falling back to `warn` — and BOTH boot paths (`voltro dev`, `voltro serve`) wire it, since a channel nothing supplies would have changed nothing.
+
+  Reported from an app where three nightly jobs had been dead since a port — one of them an entire feature that never wrote a single row — each failing on EVERY firing, for months, at `warn`. The failure was already recorded in `_voltro_schedule_runs` (`status: 'failed'`) and published on the server-error bus; the log level was the one place that disagreed with both.
+- **@voltro/runtime** — **`ctx.workflows.start` now validates the payload against the workflow's schema, and says so when it doesn't match.** The signature is `(workflowName: string, payload: unknown)` — the name was not checked against the registry and the payload was not checked against anything — so a caller that drifted from the workflow's schema failed DEEP inside the engine, where the message reads like the workflow itself misbehaved.
+
+  A mismatch now throws a `WorkflowPayloadError` carrying `workflowName`, `missingFields`, and the formatted parse error, and an unknown name lists the workflows that ARE registered (so a rename reads differently from a deletion). `run()` and `executionId()` validate too — `start` is not the only entry point.
+
+  Validation is on the DECODED side (`Schema.validate`, not `decodeUnknown`): a `Schema.Date` payload accepts a `Date`. Using `decodeUnknown` here would have rejected valid calls — the check meant to protect the caller breaking them.
+
+  Reported from an app where a cron fired such a start on every tick: three nightly jobs dead since a port, one of them an entire feature that never wrote a row. The payload was the bug and nothing in the failure said so. Pairs with the schedule failure now logging at `error`.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cli** — Test-only: cover the migrationRunner SQL apply/rollback path (the report's top coverage gap). `migrationRunnerApply.test.ts` runs real defineMigration steps against Postgres — CREATE/DROP via the SqlClient, asserting the DDL ran, the `_voltro_migrations` ledger recorded it, re-run skips, and rollback reverts — gated on a reachable Postgres (docker-compose `postgres-test` on :55432, or DB_URL) and skipped when down, per the dialect-parity convention. (The runner's ledger upsert uses `now()` + `ON CONFLICT`, so it is genuinely not sqlite-testable.)
+
+---
+
+## [0.11.3] — 2026-07-24
+
+### Added
+
+- **@voltro/runtime** — `crud.*` secure-default CRUD handler helpers + `redactColumns` (A1 core). Each returns an executor you export as a `*.query.server.ts` / `*.mutation.server.ts` default — the descriptor (schemas + `guards`) stays hand-written and browser-safe:
+
+  ```ts
+  // accounts.list.query.server.ts
+  import { crud } from '@voltro/runtime'
+  export default crud.list('accounts', { redact: ['apiSecret'] })
+  ```
+
+  They bake in the invariants a hand-rolled CRUD generator kept getting wrong (the leak class was in the HANDLERS, not the schemas):
+
+  - **Tenant scope** — `list` / `getById` read through `ctx.store`, which auto-scopes a `tenant()` table; they never `.unscoped()`, so a cross-tenant read is impossible. - **Redaction** — `redact` columns are stripped from every returned row (a credential / secret / salary a read must never ship), on reads AND on the row a `create` / `update` echoes. `redactColumns(rows, cols)` is exported standalone for a hand-written handler that isn't plain CRUD. - **`getById` returns `null`, never throws** — a reactive getter that throws stalls its shared-WS siblings (pairs with the per-subscription error isolation).
+
+  What they deliberately DON'T do is authorize: a guard runs before the executor, so gating stays on the DESCRIPTOR (`guards: [...]`) — an executor can't gate itself. Keep write descriptors guarded.
+
+  Scope note: this is the browser-safe, codegen-free core. Deriving the descriptor SCHEMAS from a table (to drop the hand-written `Schema.Struct`) is structurally a codegen concern — a table VALUE can't be imported into a browser-loaded descriptor (it drags the store into the bundle; `rowSchema` is server-only for exactly this reason) — so full schema-derivation + a `.crud()` boot audit for the scope/gating discipline are a separate, planned pass. See `plans/framework-a1-defineCrud.md`.
+- **@voltro/runtime** — `ctx.store.links(junctionTable, anchor)` — a diff-based writer for a many-to-many JUNCTION table (A2). It reconciles the links from one anchor row against a target-id list by writing only the DIFFERENCE:
+
+  ```ts
+  await ctx.store.links('post_tags', { postId: post.id }).set(tagIds) // add missing, remove surplus
+  await ctx.store.links('post_tags', { postId: post.id }).add([tagId]) // idempotent
+  await ctx.store.links('post_tags', { postId: post.id }).remove([tagId])
+  await ctx.store.links('post_tags', { postId: post.id }).list()      // current target ids
+  ```
+
+  Why it belongs in the framework rather than every app: a drop-all-then-reinsert `setLinks` loses data when two writers overlap and makes a reactive subscription on the junction churn every row (flicker) even when nothing changed. `links().set()` touches only the rows that actually differ — the added are inserted, the removed deleted, the unchanged left in place — so a reactive consumer sees a change only for what changed, and `set()` returns `{ added, removed }`. `add`/`remove` are likewise idempotent (they read first and act only on the genuine delta).
+
+  `anchor` names the source column and its id (`{ postId: 'p1' }`); the target column is the junction's OTHER `reference()` column, auto-detected. A junction with anything but exactly two reference columns is refused with a message naming what it found — use plain `insertMany`/`deleteMany` for a non-standard junction. The writes go through the normal stamped/tenant-scoped store path, so tenant and audit columns are filled as usual. Additive: a new `links` method on `FluentStore` + the `JunctionLinks` interface.
+- **@voltro/client, @voltro/web** — `useSubscription(..., { initialSnapshot })` — the last mile of "SSR-correct first paint, then live" (A5). Pass the value an SSR loader already fetched with `ctx.query` (read it in the component with `useLoaderData()`) and the subscription shows it at the first paint with `loading: false` — it IS real server data — then swaps to the live stream the instant its first snapshot arrives:
+
+  ```tsx
+  const seed = useLoaderData<Employee>()
+  const { data } = useSubscription('app', 'employees.me', {}, { initialSnapshot: seed })
+  ```
+
+  The SSR markup and the hydration render read the same loader value, so they match (no hydration flicker), and the app no longer hand-builds a seed store to bridge loader data into the first render. This is the difference from `fallback`, whose value never came from the server and so keeps `loading: true`; use exactly one of the two. Like `fallback`, `initialSnapshot` guarantees `data` is present, so the call gets the non-union result and needs no `loading` branch. Additive: a new `initialSnapshot` field on `SubscriptionOptions` + an overload; `@voltro/web` re-exports the client surface.
+- **@voltro/cli** — `apis.<name>.authHeaders` in a web `app.config.ts` — a declarative per-reconnect auth-header resolver, so an authenticated split-origin web app no longer hand-mounts `VoltroRuntimeProvider` just to inject a rotating-token thunk (A4). The framework owns the client mount, the reconnect re-resolve, and the SSR-null case (the resolver runs browser-only — it never fires on the server):
+
+  ```ts
+  // app.config.ts
+  apis: {
+    api: {
+      package: '@app/api',
+      authHeaders: async () => ({ authorization: `Bearer ${await getToken()}` }),
+    },
+  }
+  ```
+
+  Because it's a FUNCTION, the codegen imports it from `app.config.ts` into the client bundle rather than serializing it — so a config that declares `authHeaders` must stay browser-safe (no `node:*` / server-only value imports; a pure env schema is fine, and tree-shakes out). It supersedes a static `headers` on the same api. The provider already resolved a `ResolvableHeaders` thunk fresh per connection generation; this just lets you declare it in config instead of hand-writing a `mount()` call.
+
+---
+
 ## [0.11.2] — 2026-07-24
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-auth-auth0",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Auth0-backed AuthStrategy for the Voltro framework. Verifies Auth0-issued JWTs via the tenant's JWKS endpoint. Conforms to @voltro/protocol AuthStrategy so it composes with other IdP plugins.",
   "keywords": [
     "voltro",
@@ -32,7 +32,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/protocol": "0.11.2"
+    "@voltro/protocol": "0.11.4"
   },
   "peerDependencies": {
     "effect": "^3.21.4"