@voltro/runtime 0.11.3 → 0.11.4

package/CHANGELOG.md

@@ -39,6 +39,179 @@ _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

package/dist/index.d.ts

@@ -954,6 +954,14 @@ export declare interface AttachAnalyticsMirrorOptions {
     readonly run?: (effect: Effect.Effect<void, unknown>) => Promise<unknown>;
 }
 
+/** The descriptor shape the audit needs — a `defineQuery` result carries it. */
+export declare interface AuditableQuery {
+    readonly name: string;
+    readonly output: Schema.Schema.Any;
+    /** Declared source table(s) — the tables whose serverOnly columns must not leak. */
+    readonly source?: string | ReadonlyArray<string> | undefined;
+}
+
 /**
  * Resolve once a server returned by {@link startRpcServer} has actually
  * bound its port (node `'listening'` event). REJECTS on `'error'`
@@ -1525,10 +1533,14 @@ export declare const countRunningWorkflows: (store: DataStore) => Promise<number
  * `(input, ctx) => …` executor for a `*.server.ts` default export.
  */
 export declare const crud: {
-    /** Tenant-scoped list of every row, redacted. */
-    list: (table: string, options?: CrudReadOptions) => (_input: unknown, ctx: AppContext) => Promise<ReadonlyArray<Row>>;
-    /** One row by id, or `null` when absent — never throws. Redacted. */
-    getById: (table: string, options?: CrudReadOptions) => (input: {
+    /** Tenant-scoped list, redacted — with optional filter / sort / pagination from
+     *  the request input, so a real list view doesn't have to be hand-written. */
+    list: (table: string, options?: CrudListOptions) => (input: unknown, ctx: AppContext) => Promise<ReadonlyArray<Row>>;
+    /** One row by id, or `null` when absent — never throws. Redacted, with optional
+     *  eager-loaded relations (`include`). */
+    getById: (table: string, options?: CrudReadOptions & {
+        readonly include?: CrudInclude;
+    }) => (input: {
         readonly id: string;
     }, ctx: AppContext) => Promise<Row | null>;
     /** Insert the input as a new row (id / tenant / audit auto-stamped). The echoed
@@ -1539,6 +1551,16 @@ export declare const crud: {
     update: (table: string, options?: CrudWriteOptions) => (input: {
         readonly id: string;
     } & Record<string, unknown>, ctx: AppContext) => Promise<Row | null>;
+    /**
+     * Tenant-scoped COUNT of the matching rows — the total a page-based UI needs to
+     * render "page 3 of 12". Takes the SAME `filter` as `list` (share the option
+     * object so the two can't disagree about which rows they mean) and ignores
+     * paging: it counts the whole filtered set, not the current page. A real
+     * `COUNT(*)` aggregate, not a fetch-and-length.
+     *
+     *     export default crud.count('absenceRequests', { filter: (i) => ({ status: i.status }) })
+     */
+    count: (table: string, options?: Pick<CrudListOptions, "filter">) => (input: unknown, ctx: AppContext) => Promise<number>;
     /** Delete a row by id; returns `{ deleted }`. Guard the DESCRIPTOR. */
     remove: (table: string) => (input: {
         readonly id: string;
@@ -1547,6 +1569,76 @@ export declare const crud: {
     }>;
 };
 
+/** The eager-load spec `.with()` accepts — nested relations, each branch taking
+ *  its own `where` / `orderBy` / `limit` (nested filtering + sort). Reused as-is
+ *  so `crud.list`'s `include` is exactly what a hand-written `.with(...)` takes. */
+export declare type CrudInclude = Parameters<SelectBuilder['with']>[0];
+
+/**
+ * Options for `crud.list` — the read ergonomics every real list view needs, so a
+ * generated list isn't limited to "all rows". All optional and additive: a bare
+ * `crud.list('t')` still returns every (tenant-scoped, redacted) row.
+ */
+export declare interface CrudListOptions extends CrudReadOptions {
+    /**
+     * Build a WHERE from the request input — return a column→value map. Only
+     * entries whose value is not `undefined` are applied, so an absent filter field
+     * is simply ignored (`{ employeeId: input.employeeId, status: input.status }`).
+     * The descriptor's `input` schema declares those fields; this maps them to a
+     * scoped `.where(column, value)` on the store query.
+     */
+    readonly filter?: (input: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
+    /**
+     * Page the result from the request. BOTH styles are accepted, so a caller uses
+     * whichever its UI thinks in:
+     *
+     *   - **page-based** — `input.page` (1-based) + `input.pageSize` (default 100).
+     *     A table UI showing "page 3 of 12" sends `?page=3&pageSize=20`.
+     *   - **offset-based** — `input.limit` / `input.offset` (defaults 100 / 0).
+     *
+     * `page` wins when both are present. Pair with `crud.count` for the total a
+     * page-based UI needs to render the last-page number.
+     */
+    readonly paginate?: boolean;
+    /**
+     * Upper bound on the rows ONE request may ask for (default 1000). The page
+     * size is caller-controlled, so without a cap `?limit=1000000` on a
+     * `publicApi` list is a one-request resource-exhaustion lever for anyone who
+     * can reach the endpoint. Raise it deliberately for an export-style endpoint;
+     * a `limit`/`pageSize` above it is clamped, not rejected.
+     */
+    readonly maxPageSize?: number;
+    /** Multi-column sort, applied in order (`[{ column: 'createdAt', direction:
+     *  'desc' }, …]`). */
+    readonly sort?: ReadonlyArray<CrudSort>;
+    /**
+     * Eager-load related rows via `.with(...)` — the SAME spec a hand-written query
+     * takes, so nested relations, and per-branch `where` / `orderBy` / `limit`
+     * (nested filtering + sort) all work:
+     *
+     *     include: { employee: { with: { team: true } }, tags: { orderBy: 'name' } }
+     */
+    readonly include?: CrudInclude;
+    /**
+     * SQL column projection — narrow the `SELECT` so wide columns are never READ,
+     * not merely dropped at the wire boundary. The output schema already strips
+     * undeclared columns on encode (so nothing extra ships either way); this is the
+     * PERFORMANCE half: a table with a large `json()` blob or a long text body that
+     * a list view never shows shouldn't cost the read, the transfer from the DB, or
+     * the decode.
+     *
+     *     columns: ['id', 'title', 'createdAt']   // the big `body` is never read
+     *
+     * `.serverOnly()` columns are removed from the projection automatically — they
+     * are stripped from the response anyway, so reading them is pure waste.
+     *
+     * TRAP with `include`: an eager 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`.
+     */
+    readonly columns?: ReadonlyArray<string>;
+}
+
 /** Options common to a generated READ. */
 export declare interface CrudReadOptions {
     /** Columns stripped from every returned row — a secret/credential a generated
@@ -1556,6 +1648,12 @@ export declare interface CrudReadOptions {
     readonly redact?: ReadonlyArray<string>;
 }
 
+/** A single sort term for `crud.list`. */
+export declare interface CrudSort {
+    readonly column: string;
+    readonly direction?: 'asc' | 'desc';
+}
+
 /** Options for a generated WRITE — `redact` applies to the row the write echoes. */
 export declare interface CrudWriteOptions {
     readonly redact?: ReadonlyArray<string>;
@@ -2103,6 +2201,9 @@ export declare interface FluentStoreBackend {
 /** Forget the calling subject's credential. Returns whether a row was removed. */
 export declare const forgetCredential: (store: VaultStore, connectionId: string, subjectId: string) => Promise<boolean>;
 
+/** A boot-ready message for a set of leaks (empty → `undefined`, i.e. clean). */
+export declare const formatServerOnlyLeaks: (leaks: ReadonlyArray<ServerOnlyLeak>) => string | undefined;
+
 /** Serialise a span's context as a `traceparent` header value. */
 export declare const formatTraceparent: (ctx: TraceContext) => string;
 
@@ -2532,6 +2633,22 @@ export declare interface JunctionLinks {
     add(targetIds: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
     /** Unlink `targetIds` that are currently linked. Returns the ids actually removed. */
     remove(targetIds: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+    /**
+     * Reconcile links that carry PER-ROW PAYLOAD — a junction with business columns
+     * (a membership `role`, a `capacity` value). 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 — one whose payload
+     * is unchanged is left untouched, so a reactive consumer sees a change only
+     * where the payload differs (the `set(targetIds)` form can't express payload;
+     * this is the drop+reinsert replacement for a junction that carries data).
+     * Payload is compared by strict equality per column (scalars — capacity, role).
+     */
+    setRows(rows: ReadonlyArray<Readonly<Record<string, unknown>>>): Promise<{
+        readonly added: ReadonlyArray<string>;
+        readonly removed: ReadonlyArray<string>;
+        readonly updated: ReadonlyArray<string>;
+    }>;
 }
 
 export declare interface KvFacade {
@@ -2794,6 +2911,24 @@ export declare const makeListConnectionsExecutor: (deps: ConnectionBuiltinDeps)
  */
 export declare const makeMutationRunner: (deps: MutationRunnerDeps) => (mutation: MutationLike, input: unknown, requestContext: ServeRequestContext) => Promise<unknown>;
 
+/**
+ * Run a QUERY once and resolve its value — the read counterpart to
+ * `makeMutationRunner` / `makeActionRunner`, for callers that have no
+ * subscription: a descriptor projected to a public REST endpoint.
+ *
+ * It is deliberately built ON TOP of `makeQueryDescriptorProducer` rather than
+ * beside it. That producer is where the declarative `guards:` gate, the
+ * per-request row-filter resolution and the tenant-scoping `finalize` live, so
+ * reusing it makes the one-shot path enforce EXACTLY what the WS path enforces.
+ * A second implementation here would be an authorization bypass waiting to
+ * happen — the REST projection of a guarded query must fail the same way the
+ * socket does, and it does because it runs the same code.
+ *
+ * Both handler shapes resolve: a descriptor-returning (reactive) query is
+ * finalized and executed to rows; a computed query yields its value.
+ */
+export declare const makeOneShotQueryRunner: <D>(deps: OneShotQueryRunnerDeps<D>) => (query: MutationLike, input: unknown, requestContext: ServeRequestContext) => Promise<unknown>;
+
 export declare const makeOutboxFacade: (deps: OutboxFacadeDeps) => OutboxFacade;
 
 export declare const makePostCommitWorkflowFacade: (base: WorkflowsAppContext, afterCommit: (work: () => Promise<unknown>) => void) => WorkflowsAppContext;
@@ -2837,6 +2972,25 @@ export declare const makeQueryDescriptorProducer: <D>(deps: QueryProducerDeps<D>
  */
 export declare const makeQueryReauthorizer: (query: MutationLike, input: unknown) => (subject: Subject) => () => Promise<unknown>;
 
+/**
+ * Subscribe a QUERY and stream its events to a non-rpc consumer — the SSE
+ * projection of a `publicApi` query. Like `makeOneShotQueryRunner`, it runs the
+ * shared `makeQueryDescriptorProducer`, so the declarative `guards:`, the row
+ * filter and tenant scoping are the same code the socket path runs: an SSE
+ * endpoint is exactly as gated as the WebSocket one.
+ *
+ * Returns an unsubscribe SYNCHRONOUSLY (the HTTP layer needs one immediately)
+ * while the subscription opens in the background; unsubscribing before it
+ * finishes tears it down as soon as it exists, so a client that disconnects
+ * mid-setup cannot leak a subscription. A setup failure — including a guard
+ * denial — is emitted as one `error` event rather than thrown, because by then
+ * the response headers are already on the wire.
+ */
+export declare const makeQuerySubscriber: <D>(deps: QuerySubscriberDeps<D>) => (query: MutationLike, input: unknown, requestContext: ServeRequestContext, emit: (event: {
+    readonly _tag: string;
+    readonly [k: string]: unknown;
+}) => void) => (() => void);
+
 export declare const makeRouterActivity: () => RouterActivity;
 
 /**
@@ -3225,6 +3379,15 @@ export declare interface OAuth2ConnectionDefinition extends ConnectionDefinition
  */
 export declare const onBindConnectionSubject: (listener: (clientId: number, subject: Subject) => void) => () => void;
 
+export declare interface OneShotQueryRunnerDeps<D> extends QueryProducerDeps<D> {
+    /**
+     * Execute a FINALIZED (tenant-scoped) descriptor → rows. On the WS path the
+     * dispatcher owns this step; a ONE-SHOT read (a `publicApi` REST GET, where
+     * there is no subscription to drive) needs it inline.
+     */
+    readonly queryRows: (descriptor: D) => Promise<ReadonlyArray<unknown>>;
+}
+
 /** Thrown by `.expectVersion(n).set(...)` when the optimistic-lock guard
  *  matched no row (the row was concurrently updated or deleted). */
 export declare class OptimisticLockError extends OptimisticLockError_base {
@@ -3529,6 +3692,13 @@ export declare interface QueryProducerDeps<D> {
     readonly interceptor?: ServeRpcInterceptor;
 }
 
+export declare interface QuerySubscriberDeps<D> extends QueryProducerDeps<D> {
+    /** Open a dispatcher subscription for a finalized descriptor. */
+    readonly subscribeDescriptor: (descriptor: D, emit: (event: unknown) => void, context: ServeRequestContext) => Promise<() => void>;
+    /** Open a dispatcher subscription for a COMPUTED query (re-runs on source change). */
+    readonly subscribeComputed: (computed: ComputedQuery, emit: (event: unknown) => void, context: ServeRequestContext) => Promise<() => void>;
+}
+
 /** What a reaction does when it fires — run an agent or start a workflow. Both
  *  identified by name; the serve layer resolves + runs them as `agentActor`. */
 export declare type ReactionAct = {
@@ -4846,6 +5016,14 @@ export declare interface SchedulerHandle {
 export declare interface SchedulerLogger {
     info: (msg: string, fields?: Record<string, unknown>) => void;
     warn: (msg: string, fields?: Record<string, unknown>) => void;
+    /**
+     * Failures. This channel did not exist, which is why a schedule whose handler
+     * failed on EVERY firing was only ever a `warn` — invisible to `voltro logs
+     * --level error`, and a schedule fires unattended, so that log line is the
+     * whole discovery channel. Optional so an embedder passing a two-method logger
+     * still compiles; it falls back to `warn` at the call site.
+     */
+    error?: (msg: string, fields?: Record<string, unknown>) => void;
     /** Optional debug channel for high-frequency expected events
      *  (lost coordination claims on sub-minute schedules etc.). */
     debug?: (msg: string, fields?: Record<string, unknown>) => void;
@@ -4914,6 +5092,13 @@ export declare interface SchemaInfo {
     readonly idScheme?: IdScheme;
 }
 
+/**
+ * Every property NAME that appears anywhere in a schema's shape. Recursive over
+ * the common composition nodes so a column nested under `{ refs: [{ … }] }` or
+ * behind a `NullOr` is still seen. Cycle-guarded via a seen-set on Suspend.
+ */
+export declare const schemaPropertyNames: (schema: Schema.Schema.Any) => ReadonlySet<string>;
+
 export declare interface SchemaRegistry {
     readonly tables: ReadonlyMap<string, SchemaInfo>;
     /** True iff the table was composed with the named mixin id. */
@@ -5061,6 +5246,20 @@ export declare interface ServeRequestContext {
     readonly rowFilter?: RowFilterScope;
 }
 
+/** One leak: a wire query that declares a serverOnly column in its output. */
+export declare interface ServerOnlyLeak {
+    readonly query: string;
+    readonly table: string;
+    readonly column: string;
+}
+
+/**
+ * Every serverOnly column a query's output declares. `serverOnlyByTable` maps a
+ * table name to its `.serverOnly()` column names. A query with no `source`, or
+ * whose source has no serverOnly columns, yields nothing.
+ */
+export declare const serverOnlyLeaks: (query: AuditableQuery, serverOnlyByTable: ReadonlyMap<string, ReadonlyArray<string>>) => ReadonlyArray<ServerOnlyLeak>;
+
 /** A plugin interceptor — wraps the base run Effect (Effect-native chain). */
 export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown, never>, meta: {
     readonly tag: string;
@@ -6193,6 +6392,32 @@ export declare interface WorkflowLayerOptions<Context> {
     readonly resolveStartContext?: (workflowName: string, executionId: string) => WorkflowCallerContext | undefined | Promise<WorkflowCallerContext | undefined>;
 }
 
+/**
+ * A start whose PAYLOAD does not match the workflow's schema.
+ *
+ * Distinct from a workflow that ran and failed, and the distinction is the whole
+ * point: `ctx.workflows.start(name, payload)` is typed `(string, unknown)` — the
+ * name is not checked against the registry and the payload is not checked against
+ * anything — so a caller that drifts from the workflow's schema produces a failure
+ * DEEP inside the engine, where it reads like the workflow itself misbehaved.
+ *
+ * A cron firing such a start hit that every single time and looked like a flaky
+ * job. Naming the workflow, the missing fields, and the fact that the payload
+ * (not the workflow) is what's wrong turns it into a one-read fix.
+ */
+export declare class WorkflowPayloadError extends Error {
+    readonly workflowName: string;
+    /** Top-level property names the schema requires and the payload omitted.
+     *  Empty when the mismatch is a type error rather than a missing key. */
+    readonly missingFields: ReadonlyArray<string>;
+    readonly detail: string;
+    readonly _tag = "WorkflowPayloadError";
+    constructor(workflowName: string, 
+    /** Top-level property names the schema requires and the payload omitted.
+     *  Empty when the mismatch is a type error rather than a missing key. */
+    missingFields: ReadonlyArray<string>, detail: string);
+}
+
 /** Options for {@link WorkflowsAppContext.retry}. */
 export declare interface WorkflowRetryOptions {
     /** Re-run the workflow against this payload instead of the original