@voltro/database 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -39,6 +39,140 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.11.1] — 2026-07-23
+
+### Added
+
+- **@voltro/runtime** — `defineExecutor(descriptor, fn)` type-checks a query/mutation/action handler's return against the descriptor's `output` schema Type — so returning a `number` where `output` is `timestampMs` (Type = `Date`) is a COMPILE error at the handler, not a runtime encode failure that Dies the subscription. The gap it closes: the executor is a separate default export whose return was never tied to `output`, so a handler that builds a plain object with a leftover `.getTime()` compiled green and only threw `Expected DateFromSelf, actual 1784…` at encode time — invisible while a nullable date was null, exploding the instant it became non-null.
+
+  Opt-in and zero-cost: it's a runtime identity (returns `fn` unchanged, so the codegen wires it exactly as the bare default export), and the compile check is the whole value. Wrap the handler and import the descriptor into its `*.server.ts`:
+
+  ```ts
+  export default defineExecutor(getRoadmapsByYear, (input, ctx) => …)
+  ```
+
+  The Effect error and requirement channels stay inferred from the handler; only the success value is constrained. A reactive query that returns a `{ descriptor }` builder is allowed through unchecked — the store produces its rows, so a value-level return type can't express that row-vs-output check.
+- **@voltro/database, @voltro/runtime** — An `.encrypted()` column that can't be decrypted with the active key now fails as a typed, readable `FieldDecryptionError` naming the `table.column`, instead of a raw `Error: field cipher: malformed ciphertext` with no context. It carries a `_tag` (the same tagged shape `storeErrors` uses, so `Effect.catchTag` matches), and never includes the ciphertext. The common trigger is restoring a prod/staging snapshot into a dev DB whose `VOLTRO_FIELD_ENCRYPTION_KEY` differs.
+
+  New dev/migration escape hatch: `VOLTRO_FIELD_DECRYPT_ON_ERROR=null` degrades an undecryptable column to `null` (with one deduped warning per `table.column`, scope `store.fieldEncryption`) instead of letting one bad row nuke the whole read — its readable siblings still decrypt. Default stays `'throw'`; never set `null` in production, where a key mismatch must fail loud. `decryptFieldsOnRead` gains an optional `{ onError, warn }` argument (additive); the raw throw is replaced by the typed one, which existing `catch (e: Error)` handlers still catch.
+- **@voltro/i18n** — `assertCatalogParity({ en, de })` checks every locale uses the SAME ICU `{var}` set per key. `defineLocale` enforces KEY parity but not PLACEHOLDER parity — a translation that drops or renames a `{var}` (`'Published on {date}'` → `'Veröffentlicht'`) compiles and boots, then throws `The intl string context variable "date" was not provided` only in that locale, only when the message renders. Call it in a test or at boot; it throws listing every drift (or warns with `onMismatch: 'warn'`). Plural argument names are extracted; a plural's inner `{# item}` branches are not mistaken for placeholders.
+- **@voltro/i18n** — `createTypedMessages<typeof en>()` binds a catalog's LITERAL message types to `useT` / `useTFn` / `<T>`, so a missing ICU placeholder is a COMPILE error instead of a runtime throw at format time. Until now `defineCatalog` / `defineLocale` enforced key PARITY across locales, but the call site `t('key', values)` was untyped — a message like `'Published on {date}'` called as `t('roadmap.publishedAt')` (or via the `t('key').replace('{{date}}', …)` idiom from other i18n systems) threw `The intl string context variable "date" was not provided` only when it rendered. Now `useT('roadmap.publishedAt')` demands `{ date }` at compile time, and a wrong/missing key is caught too.
+
+  Opt-in and purely additive: call `createTypedMessages` once with your base catalog (`as const`) and re-export the returned `useT`/`useTFn`/`T`; the bare hooks keep their existing loose signatures. Scope: simple `{name}` and single-argument `{count, number}` forms are extracted; messages with nested inline ICU (`{n, plural, one {…} other {…}}` / `select`) accept a loose values bag rather than a wrong strict one — apps that pluralise in JS over simple `{count}` messages stay fully typed. `<T>` gets a typed key with loose values, because its rich-text `<tag>` renderers can't be modelled by `{var}` extraction.
+- **@voltro/plugin-ai-flows** — An AI-flow `MediaGenerator` (and the `makeMediaGenerator` persistence seam) now receives the run it executes within — `run: { runId, tenantId }` — resolved from the durable run row rather than the caller subject. This is what a resume needs: a BOOTSTRAP/crash resume runs under a tenant-less `SYSTEM_SUBJECT`, so a host that persists artifacts per tenant could not read the tenant from `ctx.request.subject` (it isn't there) and would either fail closed or, under an old anonymous fallback, write into the wrong tenant. The engine already loads the run row (for `ownerId`); it now reads `tenantId` from the same row and hands it down to both the deterministic and agentic media steps, and `MediaPersist.put` / `ingestUrl` forward it to `storage.put` / `ingestUrl` so persistence continues in the run's own tenant on replay.
+
+  Additive: `run` is appended to the generator/persist arguments, so a host that ignores it keeps compiling; the tenant is simply available when it doesn't. No `@voltro/web` change — the engine is server-only and not re-exported to the browser surface.
+- **@voltro/client, @voltro/web** — A sequence step's `undo` now receives the accumulated context as a second argument — `undo: (result, ctx) => …` — alongside the step's own result. An inverse usually needs an id from an EARLIER step as well as this one's (`deleteJiraDraftTicket({ jiraKey: created.key, draftId: ctx.draft.id })`), and until now the only way to reach it was to re-return that id from the step purely so the undo could read it back. `ctx` is typed as of the step's definition — the steps before it, the same context `covers` and `when` already see — so a later step's result is deliberately not visible (it is rolled back before this one).
+
+  Additive, not breaking: `StepUndo<Result>` became `StepUndo<Result, Ctx = Record<string, unknown>>` with the context parameter defaulted and appended, so a named `StepUndo<T>` still resolves and an existing single-argument `undo: (r) => …` stays assignable. `@voltro/web` re-exports the client surface, which is why it moves too.
+- **@voltro/cli** — SSR `ctx.query` now has a first-class, server-only api origin for split web/api deployments (#18). Previously, a `renderMode:'ssr'` page reloaded in a split deployment 500'd: the web pod's `POST <origin>/rpc` fell back to the DEV proxy target (`http://localhost:4000`), which nothing serves in production → `ECONNREFUSED` buried in a render error. Browser-reachability and SSR-reachability were conflated into the one `url` field.
+
+  New `apis.<name>.serverUrl` (and env overrides `VOLTRO_API_ORIGIN_<NAME>` / `VOLTRO_API_ORIGIN`) set the origin the WEB POD uses for SSR — the api's internal cluster DNS (`http://api.<ns>.svc.cluster.local`) — distinct from the browser's relative wsPath, and NEVER emitted into the browser bundle. Resolution: env > `serverUrl` > (dev only) the vite proxy target > an external api's absolute url. Under `voltro start` a package api with none resolves to `undefined` and the loader query FAILS LOUD naming the api and the config to set — it never dials the dev localhost port. A transport failure is wrapped naming the api and the origin attempted, instead of a bare `fetch failed`.
+- **@voltro/database, @voltro/runtime** — `store.insert` / `upsert` / `insertIgnore` now raise a clear, typed `TableValidationFailed` naming the column when the payload omits one that is NOT NULL, has no default, and isn't auto-stamped — instead of a raw dialect `SqlError: Failed to execute statement` (`Field '…' doesn't have a default value`) surfaced only on the INSERT path (so it lay dormant until the first row with no existing cache entry). An upsert / insertIgnore whose payload is missing one of its own `conflictColumns` is likewise named at the call (an absent conflict key can't match its target). The check runs AFTER stamping, so auto-id / tenant / audit columns never trip it, and skips nullable, defaulted, and id (`idScheme`) columns — exactly the ones a caller may legitimately omit.
+
+  Two pure helpers back it — `missingRequiredColumns(table, row)` and `missingConflictColumns(conflictColumns, row)` (exported from `@voltro/database`). This is the runtime half of the "handler data silently disagrees with the schema" class; a compile-time payload type needs the column DSL to track `hasDefault` at the type level, which is a separate change.
+- **@voltro/database, @voltro/plugin-ai-flows, @voltro/plugin-audit, @voltro/plugin-deactivation, @voltro/plugin-soft-delete** — Compile-time payload typing for writes (#15) — the type-level half that the runtime `TableValidationFailed` guard flagged as a separate change. `insertRow` / `upsertRow` take the TABLE OBJECT (not a string name), so the payload is checked against `InferInsertRow<T>`: every column is required EXCEPT nullable ones, columns with a default, and the framework-filled id/tenant/audit columns. A missing NOT-NULL-no-default column — the exact `lastRefreshedAt` / `teamId` omission from the report — is now a COMPILE error at the call, not a runtime SqlError only on the INSERT path; `upsertRow`'s `conflictColumns` are constrained to the table's own columns too.
+
+  import { insertRow } from '@voltro/database' await insertRow(ctx.store, roadmapEpicStats, { teamId, lastRefreshedAt: new Date() })
+
+  Enabled by a type-level default flag: `ColumnDefinition` / `ColumnBuilder` gained a third `HasDefault` parameter that `.default()` narrows to `true`. It defaults to `boolean`, so every existing `ColumnDefinition<unknown>` (mixins, query builder, migrate, plugins) is unaffected — the only golden churn is the additive third parameter rendering (e.g. an audit mixin's defaulted `createdAt` now shows `ColumnDefinition<Date, "timestamp", true>`). The string-keyed `store.insert` / `upsert` are unchanged; the typed seam is opt-in.
+- **@voltro/runtime, @voltro/cli** — `voltro dev` now warns, once per tenant-scoped table, when a request reads it with the empty-string tenant sentinel — an authenticated subject that has no resolved org (`tenantId === ''`). The auto-merged tenant filter becomes `eq('tenantId', '')`, which matches no real row, so every such read returns empty WITH NO ERROR — indistinguishable, from the response alone, between "no such row", "filtered by an empty tenant", and "auth half-resolved". The warning names the cause and the fix. `voltro serve` deliberately stays silent (a prod diagnostic on every scoped read is noise). The decision is a pure predicate, `isEmptyTenantScopedRead`, exported from `@voltro/runtime` so it is unit-tested apart from the 6k-line dev boot; `applyTenantScope` itself stays pure.
+- **@voltro/runtime, @voltro/cli** — `voltro dev` now warns once, the first time an authenticated subject resolves with NO active org (a `user` carrying the empty-string tenant sentinel) — "authenticated, but no active org → all tenant-scoped reads will be empty". Broader and earlier than the per-table empty-tenant read warning: it catches the whole class at the door instead of on a specific read. Backed by the pure `isOrglessUserSubject` predicate in `@voltro/runtime`; dev owns the one-time log.
+- **@voltro/cli** — `voltro start` (web) now reports boot timing, matching `voltro serve`. It always logs a structured `start: ready in <n>ms` line (with `bootMs`), counted from PROCESS start so the module-graph load — the phase that dominates a scale-to-zero cold start — is included instead of being missed by a mid-boot baseline; the banner's `bootMs` uses the same total. Under `VOLTRO_BOOT_TIMING=1` the line also carries a per-phase `phases` breakdown (`modules`, `config`, `scan`, `provider`, `routes`, `cdc`, `ready`). Because the total is a structured log record, it is retrievable from the container's `/_voltro/inspect/logs` endpoint, not only from stdout.
+- **@voltro/cli** — Production web images are now self-contained and dramatically smaller. `voltro build` makes every runtime artefact framework-inlined + tree-shaken — the SSR bundle (vite `noExternal: true`), the start bundle, and the precompiled `appConfig` — so a booted `voltro start` needs from `node_modules` only the runtime-external NATIVE leaves it actually reaches (a SQL driver an ISR/config path touches). A new hidden `voltro prune-runtime <deploy-dir>` command (`@vercel/nft`, a new build-time optionalDependency) traces the real reachable set from those bundles + the app's installed native leaves and drops the rest — the whole `@voltro`/effect/react tree that's now dead weight. The standalone web Dockerfiles run it after `pnpm --prod deploy`; for a static/SSR site with no native runtime dep, `node_modules` collapses to nothing. Measured on a real marketing app: the app tree drops from ~210 MB to ~65 MB (node_modules ~145 MB → 0) and still boots + renders. Fully automatic — a used native driver is traced + kept, an unused one dropped, no per-app allow-list — and non-fatal: any trace failure keeps the fuller tree (a bigger image, never a broken one). The appConfig `@voltro/*` imports are now inlined (were external); this is safe because `runEnvGate` consumes the env schema structurally (`isEnvContract` duck-types `{ vars }`, no `instanceof`/Symbol), so a schema built by the config's inlined `@voltro/env` still validates.
+- **@voltro/cli** — `voltro build` now precompiles the web START runtime into a single bundle (`.framework/dist-web/startBundle/startEntry.js`, framework inlined) — the web counterpart to the api serve bundle. `bin/voltro.mjs`'s `voltro start` fast path prefers it, so a cold scale-from-zero web boot loads ONE artefact instead of resolving the whole `@voltro`/effect module graph. Measured on the web-spa-shell fixture: the `modules` boot phase collapses from ~1130 ms to ~67 ms (~17×), directly cutting the phase measured to dominate a scale-to-zero web cold start. Non-fatal — if the bundle build or its import fails, `voltro start` falls back to the per-module CLI entry (correct, just slower). No app or Dockerfile change is needed; the bundle rides in `.framework`, which `pnpm deploy` already copies.
+
+### Fixed
+
+- **@voltro/runtime** — An undeclared infra error no longer reaches the browser as an `ExitEncoded` schema-tree dump (a wall of text that leaks internals and no client can pattern-match). `FieldDecryptionError` — a `.encrypted()` column that can't be decrypted with the active key — now collapses to a generic `InternalError` on both the unary and the subscription paths (it was previously only `SqlError` / `ResultLengthMismatch`, and only on the unary path). Its message names an internal `table.column`, so this also stops that leak; the real cause is logged server-side with the traceId. `TableValidationFailed` is deliberately left through — its summary/issues are meant to be shown to a user. Typed app errors are untouched.
+- **@voltro/cli** — Security: the `/_voltro/inspect/logs` endpoint no longer bypasses the inspect gate. It dumps the process LogBuffer (request URLs + error payloads), but it returned early — above the `isInspectDisabled` / `VOLTRO_INSPECT_TOKEN` checks — so `VOLTRO_INSPECT=off` closed the manifest and metrics (503) while leaving the log buffer publicly readable, and a configured `VOLTRO_INSPECT_TOKEN` was ignored for it. The gate now lives inside `handleLogsRequest`, single-sourced across the three call sites (`voltro start` / `voltro dev` / the web-dev server) that each drifted (start ungated, dev gated nothing, web-dev gated disabled-but-not-token): disabled → 503, missing/bad bearer → 401.
+
+---
+
+## [0.11.0] — 2026-07-22
+
+### ⚠ BREAKING
+
+- **@voltro/client, @voltro/web** — **@voltro/client** — `useSequence` steps gain **`covers`** and **`when`**, and the undo contract that was implicit is now written down.
+
+  **`covers` — overlapping undos.** Every succeeded step's undo runs, and the runner has no idea whether two of them reverse the same thing. Reported from a Jira rollback: `deleteJiraDraftTicket` deletes the issue *and* discards the draft, so the earlier `discardDraft` undo ran on something already gone. It worked only because discarding is idempotent — and **nothing said that was load-bearing**. For a refund or a cancellation email the double-run is a defect, not a nuisance.
+
+  ```tsx
+  .step('draft', createDraft, { undo: discardDraft })
+  .step('jira',  createTicket, { undo: deleteJiraDraftTicket, covers: ['draft'] })
+  ```
+
+  `covers` is static rather than a runtime signal on purpose: "this reverse also reverses that one" is a property of the operation, legible where it is defined and checkable against the step names in scope.
+
+  **When the covering undo FAILS**, the covered steps are neither run nor claimed. Whether the cascade got that far is genuinely unknown — running the covered undo risks the double reverse, skipping it risks an orphan — so both guesses are refused and the steps come back in `compensationUncertain` with the step that was supposed to cover them. Same principle as never compensating the step that failed: surface the ambiguity, don't resolve it by assumption.
+
+  **`when` — one optional step.** 13 multi-await blocks in one app; only 5 could migrate. Several of the rest were linear *except* for one conditional step ("schedule the summary only if the set changed", `if (assigneeKey) assign else unassign`) and fell back to `try/catch` entirely, though 80% of the flow was a clean pipeline. An optional step is a different shape from a loop, and the scoping was treating them the same.
+
+  ```tsx
+  .step('summary', (c) => scheduleSummary.run({ id: c.save.id }), { when: (c) => c.save.changed })
+  ```
+
+  A skipped step contributes `undefined` to the context — the overload says so, so a later step has to acknowledge it — and gets no undo, since it had no effect to reverse. Loops and real branches still keep their `try/catch`; this deliberately does not widen to them.
+
+  **The break:** `StepOptions` gained a type parameter — `StepOptions<Result>` became `StepOptions<Ctx, Result>`, because `covers` and `when` both need to see the accumulated context (`covers` is checked against the step names in scope; `when` receives it). Call sites that pass an object literal to `.step()` are unaffected — the type is inferred — but anyone who *named* the type explicitly gets a compile error. Filed BREAKING rather than Added for the same reason a widened union is: the test is "can this turn code that compiled into code that does not", and it can. `@voltro/web` is listed because it re-exports the client surface — the third time in this round that coupling has decided where a change lands.
+
+### Added
+
+- **@voltro/cli** — **Repo gate** — a new `Claimed-wiring check` (`scripts/check-claimed-wirings.mjs`, wired into CI and therefore into `pnpm gate`): a doc comment that says something wires a symbol up must be telling the truth.
+
+  `setSystemStoreHandle`'s comment read *"Process-wide handle, registered by the runtime boot (dev.ts / start.ts)"*. Nothing registered it, in either path, through an entire release — so `runAsSystem` threw for every consumer, and the comment was the only evidence anyone had that it should work. The shape is not rare: a comment gets written when the wiring is planned, the wiring gets deferred, and the comment never finds out. It then reads as documentation of behaviour rather than of intention, and the more confidently it is phrased the less likely anyone is to check it.
+
+  Two things it does that the obvious version does not, both learned by watching it report the bug as clean:
+
+  - **it counts real call expressions, not text.** The first version matched regexes and found `setSystemStoreHandle({ … })` inside `runAsSystem`'s own error-message string — a text match cannot tell a call from a sentence about a call. (Precisely the defect fixed in the hand-roll detector one commit earlier, repeated one file later.) - **it checks the NAMED caller, not any caller.** The second version asked "does anything call this"; `@voltro/testing` calls it from a test harness, so the bug read clean again. A claim that the runtime boot registers something is not satisfied by a test helper registering it.
+
+  Verified the only way this kind of check can be: by removing the wiring and confirming it fails, with the diagnosis that would have saved the original investigation — `called by: packages/testing/src/testContext.ts ← none of these is the boot`.
+
+### Fixed
+
+- **@voltro/database, @voltro/runtime, @voltro/sql-postgres, @voltro/sql-mysql, @voltro/sql-sqlite, @voltro/sql-mssql** — **@voltro/database + every store** — a row inserted into a table that declares an `id()` scheme now gets one **at the store**, not only when the caller happened to go through `wrapStoreWithMixinBehaviour`.
+
+  Id generation was sitting one layer too high. It is the single stamped field that needs no subject — the scheme is a property of the declared table — yet it lived in the subject-aware wrapper. So every insert through an unwrapped store reached the database with `id: null`:
+
+  ```
+  null value in column "id" of relation "_voltro_seeds" violates not-null constraint
+  ```
+
+  That was a real shipped bug in the seed ledger (the runner holds the raw store), and a survey found the same shape waiting elsewhere: `plugin-rbac/userRoleStore.ts`, `plugin-governance/consent.ts`, and `plugin-sso-saml/saml-cache.ts` all insert without an id into tables that declare one. Whether any of them broke came down to how their caller happened to obtain its store — and *"depends on how the caller obtained its store"* is not a contract, it is a coin flip with a NOT NULL constraint on the other side.
+
+  `stampGeneratedId` now runs in every store's insert path (all four dialects plus the in-memory store, at the private `executeInsert` / `executeInsertMany` / `executeInsertIgnore` choke points that every public and namespace-view path funnels through). It preserves the semantics the wrapper had: an explicit id is never overwritten, a `numeric` scheme deletes the key so the dialect's SERIAL fires, and an unregistered table is passed through untouched rather than guessed at.
+
+  The wrapper still stamps — it holds the schema registry and does the subject-derived fields in the same pass — and now finds the id already set. That is a floor, not a second implementation of a rule: the invariant is "a row that reaches the database has an id when its table declares a generating scheme", and only the store can promise that for *every* caller, including a `DataStore` someone implemented themselves.
+- **@voltro/cli** — **Repo tests** — the liveness backstop for real-listener / real-child-process suites goes from 60s to 120s, in `vitest.config.ts` and the CI flag that overrides it.
+
+  Worth stating plainly what this number is, because raising a timeout is the classic way to bury a problem: it asserts nothing about performance. A real `serveApi` boot is ~0.2s in isolation. The value is pure headroom against residual starvation that the four existing mitigations — the unit/integration project split, group ordering, `fileParallelism: false`, per-package mssql databases — cannot reach, because the remaining contention is turbo running two *packages* concurrently alongside the docker stack.
+
+  60s tripped twice in one session, on two different files (`connectionServe.test.ts`, then `serveApi.test.ts`), each passing in ~2s alone. Different file each time, always in the same family, never reproducible in isolation: that is the signature of starvation rather than of a slow test, and it cost two full gate runs.
+
+  What would not be honest is treating a green run afterwards as evidence the contention is gone. It is not. If a third file trips this, the answer is to stop running two heavy packages concurrently — not to raise it again.
+- **@voltro/cli, @voltro/database** — **@voltro/cli, @voltro/database** — two fixes to the 0.10.0 seed ledger, both reported from its first real use, both mine.
+
+  **The ledger never wrote.** `store.insert('_voltro_seeds', …)` ran against the RAW store, and auto-id lives in `wrapStoreWithMixinBehaviour` — so the row reached postgres with `id: null` and died on the NOT NULL constraint. Every boot reported `ran=1 skipped=0` regardless of fingerprint: the feature shipped doing nothing. The ledger now stamps its own id, derived from `_voltroSeedsTable`'s declared scheme rather than a hardcoded prefix, so it no longer depends on how a caller happens to have wrapped its store.
+
+  **Worse than the bug was the logging.** I put the failure on `debug` and swallowed it, reasoning that "it degrades to re-running, which is only a performance regression". That reasoning is exactly what made it undiagnosable: a silently unwritten ledger looks identical to a working one whose seeds all changed — no symptom, nothing to grep, and the reporter had to read the error out of a debug stream to find it. Both the write and the read path now warn, naming the table and the consequence.
+
+  **And the reason it shipped:** the test fake *invented an id* when the row lacked one, making it more permissive than any database. A fake that supplies what the subject under test forgot is not a test — it is the subject testing itself. It now rejects an id-less insert with the real constraint's message; reintroducing the bug fails five cases.
+
+  **A seed step could not reach a usable store.** `SeedStore` exposed only `query`/`insert`/`update`/`delete`, and `query` took just `{ table, predicate }`. A restore of 1361 rows across 167 tables, multi-pass for FK order, needs an idempotent insert and a read it can page — and `upsertByUnique` is neither: a read per row, and it overwrites what it finds, which is wrong whenever the live row is newer than the snapshot. `SeedStore` now carries **`insertIgnore`** (one statement per row, native on every dialect) and a full descriptor read (`order` / `take` / `skip` / `projection`).
+
+  Seed reads are unscoped and include soft-deleted rows *by construction* — a seed runs at boot with no request and therefore no subject, so nothing applies a tenant filter or the `deletedAt IS NULL` predicate. That is now documented on the type rather than left to be discovered, since the absence of `.unscoped()` / `.withDeleted()` reads as a missing feature until you know why they cannot exist here.
+
+  *(`apiSurface: compatible`: the golden churn in `@voltro/database` is two `(undocumented)` markers disappearing because `SeedStore` and its new member gained TSDoc — a comment cannot break a caller. The added `insertIgnore` member is additive for consumers, which is everyone: a `SeedStore` is what `ctx.store` IS, handed to you by the runner. Nobody constructs one, so nobody can be missing a member.)*
+- **@voltro/cli** — **@voltro/cli** — `runAsSystem` now works. The process-wide system store is registered at boot by **both** `voltro dev` and `voltro serve`; until now neither did, so every call threw `no data store available — register one at boot via setSystemStoreHandle`.
+
+  `setSystemStoreHandle`'s own doc comment reads "registered by the runtime boot (dev.ts / start.ts)". It describes wiring that was never written: the only callers in the repo were its unit test and a note in `@voltro/testing`. So the failure was not a lifecycle-ordering subtlety — the handle was never set at any point, in any command, and `runAsSystem` was unusable for every consumer.
+
+  Surfaced by someone reporting it as "not registered *yet* at seed time", which implied it worked later. Checking that framing rather than the symptom is what turned a scheduling question into a missing-wiring one. It is registered before the seed runner in dev, since seeds are the earliest thing that can plausibly want it.
+
+  Same class as the seed lifecycle table and the `@voltro/web` re-export: a documented behaviour with nothing behind it, where the doc is the only evidence anyone has.
+
+---
+
 ## [0.10.0] — 2026-07-22
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -82,6 +82,9 @@ export declare interface AnnClause {
 
 export declare type AnyMixin = MixinDefinition<Record<string, ColumnDefinition<unknown>>>;
 
+/** Any table — the loose shape these helpers accept structurally. */
+declare type AnyTable = Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>;
+
 /**
  * Array column — wraps another column constructor to declare an
  * array of that element type. Postgres-native (`text[]`, `integer[]`,
@@ -173,6 +176,12 @@ export declare const auditAllTableIndexes: (tables: ReadonlyArray<Table<string,
  */
 export declare const auditTableIndexes: (table: Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>) => ReadonlyArray<IndexAuditIssue>;
 
+/** Columns the framework fills on write (auto-id floor + tenant/audit mixins),
+ *  so an insert need not supply them. Name-based on purpose: a hand-declared
+ *  `createdAt` with no default reads as optional here (the lenient direction —
+ *  never rejects valid code), while the mixin-managed ones are always filled. */
+declare type AutoFilledColumn = 'id' | 'tenantId' | 'createdAt' | 'updatedAt' | 'createdBy' | 'updatedBy' | 'deletedAt' | 'deletedBy';
+
 export declare const avg: (column: string, alias?: string) => AggregateColumn;
 
 export declare const avgOver: (column: string, alias?: string) => WindowBuilder;
@@ -223,7 +232,7 @@ export declare interface BackfillSpec<TsType = unknown> {
  * bytesStored: bigint().default('0'),
  * ```
  */
-export declare const bigint: () => ColumnBuilder<string, "bigint">;
+export declare const bigint: () => ColumnBuilder<string, "bigint", boolean>;
 
 /**
  * Bind the request to the store for the subject's home region. `stores` is the
@@ -238,7 +247,7 @@ export declare const bindResidentStore: <S>(subject: ResidencySubject, config: R
     readonly placement: ResidentPlacement;
 };
 
-export declare const boolean: () => ColumnBuilder<boolean, "boolean">;
+export declare const boolean: () => ColumnBuilder<boolean, "boolean", boolean>;
 
 export declare type BranchEvent = 'provision' | 'provisioned' | 'fail' | 'destroy' | 'destroyed';
 
@@ -387,7 +396,7 @@ export declare class BranchTransitionInvalid extends Error {
  *  (mysql/mariadb) / `VARBINARY(MAX)` (mssql). Values round-trip as
  *  `Uint8Array`. Use for storing bytes IN the database (e.g. the
  *  `database` storage provider); keep large blobs in object storage. */
-export declare const bytes: () => ColumnBuilder<Uint8Array<ArrayBufferLike>, "bytes">;
+export declare const bytes: () => ColumnBuilder<Uint8Array<ArrayBufferLike>, "bytes", boolean>;
 
 export declare type CaughtUpVerdict = 'caught-up' | 'behind';
 
@@ -504,9 +513,9 @@ export declare const collectSubqueries: (predicate: Predicate) => Generator<{
  */
 export declare const column: <T = string | number | boolean | Date | null>(columnName: string, alias?: string) => AggregateColumn<T>;
 
-export declare class ColumnBuilder<TsType, Type extends ColumnType> {
+export declare class ColumnBuilder<TsType, Type extends ColumnType, HasDefault extends boolean = boolean> {
     private readonly definition;
-    constructor(definition: ColumnDefinition<TsType, Type>);
+    constructor(definition: ColumnDefinition<TsType, Type, HasDefault>);
     /**
      * `raw(ddl)` columns reject any modifier that would add a second
      * source of truth for nullability / default / uniqueness. The DDL
@@ -516,7 +525,7 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType> {
      * the error site is the schema file.
      */
     private rejectIfRaw;
-    nullable(): ColumnBuilder<TsType | null, Type>;
+    nullable(): ColumnBuilder<TsType | null, Type, HasDefault>;
     /**
      * Encrypt this column's value at rest (AES-256-GCM). The runtime
      * store middleware transparently encrypts on write + decrypts on
@@ -601,7 +610,7 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType> {
      * SQL-side fill (legacy seeds, raw inserts); factory wins for
      * framework-routed inserts.
      */
-    default(value: TsType | 'now' | (() => TsType)): this;
+    default(value: TsType | 'now' | (() => TsType)): ColumnBuilder<TsType, Type, true>;
     /**
      * Mark this column as computed from other row fields. The function
      * runs on INSERT AFTER defaults are applied, and again on every
@@ -754,7 +763,7 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType> {
      * Pass `as const` or a `const`-typed array — the TS inference
      * preserves the literals only when the array is a tuple of literals.
      */
-    oneOf<const Values extends readonly [string, ...string[]]>(this: ColumnBuilder<TsType, 'text'>, values: Values): ColumnBuilder<null extends TsType ? Values[number] | null : Values[number], 'text'>;
+    oneOf<const Values extends readonly [string, ...string[]]>(this: ColumnBuilder<TsType, 'text', HasDefault>, values: Values): ColumnBuilder<null extends TsType ? Values[number] | null : Values[number], 'text', HasDefault>;
     /**
      * Cap a text column's length → `VARCHAR(n)` (postgres / mysql / mariadb) /
      * `NVARCHAR(n)` (mssql), instead of the unbounded `LONGTEXT` / `TEXT`
@@ -777,7 +786,7 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType> {
      * Method only resolves on `text()` builders (the `Type extends 'text'`
      * guard), like `oneOf`. `n` is a character count.
      */
-    maxLength(this: ColumnBuilder<TsType, 'text'>, n: number): ColumnBuilder<TsType, 'text'>;
+    maxLength(this: ColumnBuilder<TsType, 'text', HasDefault>, n: number): ColumnBuilder<TsType, 'text', HasDefault>;
     /**
      * Attach a raw SQL `CHECK` to this column — a DB-ENFORCED invariant
      * that holds regardless of which client writes the row (defense-in-
@@ -804,11 +813,12 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType> {
     __definition(): ColumnDefinition<TsType, Type>;
 }
 
-export declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType> {
+export declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType, HasDefault extends boolean = boolean> {
     readonly type: Type;
     readonly nullable: boolean;
     readonly unique: boolean;
     readonly hasDefault: boolean;
+    /* Excluded from this release type: __hasDefault */
     readonly defaultValue?: unknown;
     /**
      * Application-side default factory. When set, the MutationStore
@@ -1128,6 +1138,15 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
     readonly __tsType?: TsType;
 }
 
+/** `true` when the column's declared default flag is `true` (`.default()` narrows
+ *  it; a plain column reads `boolean`, which is NOT `[true]`). Tuple-wrapped so
+ *  `boolean` does not distribute. */
+declare type ColumnHasDefault<D> = D extends ColumnDefinition<unknown, ColumnType, infer HD> ? ([HD] extends [true] ? true : false) : false;
+
+/** A column may be omitted from an insert when it is auto-filled, has a default,
+ *  or is nullable. */
+declare type ColumnOptionalForInsert<K extends PropertyKey, D> = K extends AutoFilledColumn ? true : ColumnHasDefault<D> extends true ? true : null extends InferColumn<D> ? true : false;
+
 /**
  * The per-column mapping, over a column DEFINITION — what `table.fields` holds.
  *
@@ -1562,7 +1581,7 @@ export declare interface DataStore {
 }
 
 /** Calendar date without time. */
-export declare const date: () => ColumnBuilder<Date, "date">;
+export declare const date: () => ColumnBuilder<Date, "date", boolean>;
 
 export declare const dbEnum: <const Values extends ReadonlyArray<string>>(name: string, values: Values) => DbEnumHandle<Values>;
 
@@ -1670,7 +1689,17 @@ export declare const decodeRowsFromSchema: <T extends Record<string, unknown>>(r
  * through untouched, so turning encryption on doesn't break reads of
  * rows written before it. Operates per-row on shallow copies.
  */
-export declare const decryptFieldsOnRead: (rows: ReadonlyArray<Row>, table: TableLike | undefined, cipher: FieldCipher | undefined) => ReadonlyArray<Row>;
+export declare const decryptFieldsOnRead: (rows: ReadonlyArray<Row>, table: TableLike | undefined, cipher: FieldCipher | undefined, options?: {
+    /** Default `'throw'` — see `OnDecryptError`. */
+    readonly onError?: OnDecryptError;
+    /** Called once per undecryptable column when `onError: 'null'`, so the
+     *  degraded read leaves a trace naming the `table.column`. */
+    readonly warn?: (info: {
+        readonly table: string;
+        readonly column: string;
+        readonly reason: string;
+    }) => void;
+}) => ReadonlyArray<Row>;
 
 export declare const defineMigration: (input: MigrationDefinitionInput) => MigrationDefinition;
 
@@ -2002,8 +2031,31 @@ export declare interface FieldCipher {
     readonly decrypt: (ciphertext: string) => string;
 }
 
+/**
+ * An `.encrypted()` column could not be decrypted with the ACTIVE cipher —
+ * almost always a value encrypted under a DIFFERENT key (a prod/staging snapshot
+ * restored into a dev DB whose key differs). Typed and `_tag`-carrying (the same
+ * shape `storeErrors.ts` uses, deliberately NOT `Data.TaggedError` — that trips
+ * TS2742 on the `.d.ts` and drags `effect/Cause` into this browser-safe codec) so
+ * it is `catchTag`-matchable and, above all, READABLE: the message names the
+ * `table.column` and the reason instead of surfacing a raw
+ * `field cipher: malformed ciphertext` with no context. The ciphertext itself is
+ * NEVER included.
+ */
+export declare class FieldDecryptionError extends Error {
+    readonly _tag = "FieldDecryptionError";
+    readonly table: string;
+    readonly column: string;
+    readonly reason: string;
+    constructor(info: {
+        readonly table: string;
+        readonly column: string;
+        readonly reason: string;
+    });
+}
+
 export declare type FieldDefinitions<F extends FieldsInput> = {
-    [K in keyof F]: F[K] extends ColumnBuilder<infer T, infer Type> ? ColumnDefinition<T, Type> : never;
+    [K in keyof F]: F[K] extends ColumnBuilder<infer T, infer Type, infer HD> ? ColumnDefinition<T, Type, HD> : never;
 };
 
 export declare type FieldsInput = Record<string, ColumnBuilder<unknown, ColumnType>>;
@@ -2069,6 +2121,11 @@ export declare interface FileMigrationContext {
     readonly appliedAt: string;
 }
 
+/** Flatten an intersection into a single object type for readable errors/hovers. */
+declare type Flatten<O> = {
+    [K in keyof O]: O[K];
+};
+
 /**
  * Multi-line pretty block for the terminal. Tries to teach, not just
  * complain — labels every section (`table` / `redundant` / `covered
@@ -2218,7 +2275,7 @@ export declare interface HybridSearchOptions {
  * `row.id`; for `numeric` the key is omitted so the dialect's
  * SERIAL/AUTO_INCREMENT/IDENTITY clause fires.
  */
-export declare const id: (options?: IdSchemeInput) => ColumnBuilder<string, "id">;
+export declare const id: (options?: IdSchemeInput) => ColumnBuilder<string, "id", boolean>;
 
 /**
  * Fully-resolved scheme stored on the `id` column definition AFTER
@@ -2390,6 +2447,12 @@ export declare const inferForeignKey: (target: TableLike, sourceTableName: strin
  */
 export declare type InferIndexNames<T> = T extends Table<string, Record<string, ColumnDefinition<unknown>>, boolean, infer N> ? N : never;
 
+export declare type InferInsertRow<T> = T extends Table<string, infer F, boolean, string> ? Flatten<{
+    readonly [K in keyof F as ColumnOptionalForInsert<K, F[K]> extends true ? never : K]: InferColumn<F[K]>;
+} & {
+    readonly [K in keyof F as ColumnOptionalForInsert<K, F[K]> extends true ? K : never]?: InferColumn<F[K]>;
+}> : never;
+
 /** Row type for the table — useful for typing application code. */
 export declare type InferRow<T> = T extends Table<string, infer F, boolean, string> ? InferRowFromFields<F> : never;
 
@@ -2400,11 +2463,18 @@ export declare type InferRowFromFields<F extends Record<string, ColumnDefinition
 /** Row type for a view — mirrors `InferRow` for tables. */
 export declare type InferViewRow<V> = V extends View<string, infer F> ? InferRowFromFields<F> : never;
 
+/**
+ * Insert a row, typed against the table: the payload must carry every required
+ * column (NOT NULL, no default, not auto-filled) or it is a compile error.
+ * Returns the stored row typed as `InferRow<T>`.
+ */
+export declare const insertRow: <T extends AnyTable>(store: TypedInsertStore, table: T, row: InferInsertRow<T>) => Promise<InferRow<T>>;
+
 export declare const inSet: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, values: ReadonlyArray<RowOf[K]>) => PredicateLeaf;
 
 export declare const inSubquery: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, subquery: QueryWithDescriptor | QueryDescriptor) => SubqueryInPredicate;
 
-export declare const integer: () => ColumnBuilder<number, "integer">;
+export declare const integer: () => ColumnBuilder<number, "integer", boolean>;
 
 /** `INTERSECT` — rows present in EVERY input. */
 export declare const intersect: (...queries: ReadonlyArray<QueryWithDescriptorAny>) => Query<Row, string>;
@@ -2419,7 +2489,7 @@ export declare const intersect: (...queries: ReadonlyArray<QueryWithDescriptorAn
  * slaDeadline: interval()
  * ```
  */
-export declare const interval: () => ColumnBuilder<string, "interval">;
+export declare const interval: () => ColumnBuilder<string, "interval", boolean>;
 
 /** Is this namespace one of ours? (so a teardown sweep never touches a real
  *  tenant namespace). */
@@ -2427,6 +2497,8 @@ export declare const isBranchNamespace: (namespace: string) => boolean;
 
 export declare const isEncrypted: (value: unknown) => value is string;
 
+export declare const isFieldDecryptionError: (e: unknown) => e is FieldDecryptionError;
+
 /** Type-guard for the discovery walker. */
 export declare const isFileMigration: (value: unknown) => value is FileMigration;
 
@@ -2494,7 +2566,7 @@ export declare const isView: (t: TableLike) => t is View<string, Record<string,
 export declare type JoinsMap = Record<string, Record<string, unknown>>;
 
 /** Typed JSON column. Pass the type parameter to record the expected shape. */
-export declare const json: <T = unknown>() => ColumnBuilder<T, "json">;
+export declare const json: <T = unknown>() => ColumnBuilder<T, "json", boolean>;
 
 export declare const jsonField: (column: string, ...path: ReadonlyArray<string | number>) => JsonFieldFilter;
 
@@ -2760,6 +2832,21 @@ export declare interface MigrationStepContext {
 
 export declare const min: (column: string, alias?: string) => AggregateColumn;
 
+/**
+ * The `conflictColumns` an upsert names that are absent from its payload. An
+ * upsert keyed on a column the row doesn't set can't match a conflict target —
+ * the dialect fails obscurely (or worse, inserts a duplicate). Naming it at the
+ * call is the difference between a one-line fix and reading a driver error.
+ */
+export declare const missingConflictColumns: (conflictColumns: ReadonlyArray<string>, row: Row) => ReadonlyArray<string>;
+
+/**
+ * Columns the row must carry but doesn't. Empty when the row is complete.
+ * `null` counts as missing for a NOT NULL column — the dialect would reject it
+ * just the same, and a clear message beats a driver error either way.
+ */
+export declare const missingRequiredColumns: (table: TableLike, row: Row) => ReadonlyArray<string>;
+
 export declare const mixin: <const Input extends FieldsInput>(options: MixinOptions<Input>) => MixinDefinition<MaterializedMixinFields<Input>>;
 
 export declare interface MixinDefinition<F extends Record<string, ColumnDefinition<unknown>>> {
@@ -2887,6 +2974,17 @@ export declare interface NotPredicate {
  */
 export declare const numeric: (precision: number, scale?: number) => ColumnBuilder<string, "decimal">;
 
+/**
+ * What a decrypt failure does. `'throw'` (default, and the ONLY safe production
+ * behaviour) surfaces a typed `FieldDecryptionError`. `'null'` degrades the one
+ * unreadable column to `null` and warns — for DEV / a data migration where a
+ * snapshot carries ciphertext bound to another key: one undecryptable row must
+ * not nuke every read (and its siblings that WOULD decrypt), it should surface as
+ * "re-enter this credential", not a 500. Never enable `'null'` in production — it
+ * silently hides a real key mismatch.
+ */
+export declare type OnDecryptError = 'throw' | 'null';
+
 export declare const one: (target: TableRef, options?: {
     readonly foreignKey?: string;
     readonly sourceKey?: string;
@@ -3867,7 +3965,7 @@ declare interface RawSqlFragment {
  *  mssql `FLOAT`, sqlite `REAL`. Drivers return JS numbers — no codec. Use for
  *  fractional values (ratings, percentages, measurements) where `integer()`
  *  would truncate. */
-export declare const real: () => ColumnBuilder<number, "real">;
+export declare const real: () => ColumnBuilder<number, "real", boolean>;
 
 /**
  * Foreign-key reference to another table's id column.
@@ -4279,12 +4377,45 @@ export declare interface SeedStepResult {
     readonly rowsTouched?: number;
 }
 
+/**
+ * The store a seed step gets.
+ *
+ * **Reads are unscoped and include soft-deleted rows**, by construction rather
+ * than by flag: a seed runs at boot with no request and no subject, so there is
+ * no tenant to filter by and nothing applies the `deletedAt IS NULL` predicate.
+ * A restore therefore sees the whole table, which is what a restore needs — and
+ * why there is no `.unscoped()` / `.withDeleted()` to reach for here. If a seed
+ * wants only one tenant's rows, it says so in its own predicate.
+ */
 export declare interface SeedStore {
+    /** Full descriptor read — `order` / `take` / `skip` / `projection` are
+     *  accepted so a large restore can page and sort rather than pulling every
+     *  row of every table into memory. */
     query(descriptor: {
         table: string;
         predicate?: Predicate;
+        order?: ReadonlyArray<{
+            column: string;
+            direction: 'asc' | 'desc';
+        }>;
+        take?: number;
+        skip?: number;
+        projection?: ReadonlyArray<string>;
     }): Promise<ReadonlyArray<Record<string, unknown>>>;
     insert(table: string, row: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Insert, or do nothing when a row already conflicts on `conflictColumns`.
+     *
+     * The primitive an idempotent restore is actually built on: `upsertByUnique`
+     * costs a read per row and OVERWRITES what it finds, which is wrong when the
+     * live row is newer than the snapshot. This is one statement per row and
+     * leaves an existing row alone. Reported by a consumer restoring 1361 rows
+     * across 167 tables in multiple passes for FK order — with only
+     * `upsertByUnique` available, every pass re-read and re-wrote everything.
+     */
+    insertIgnore(table: string, row: Record<string, unknown>, options: {
+        conflictColumns: ReadonlyArray<string>;
+    }): Promise<Record<string, unknown>>;
     update(table: string, primaryKey: string, patch: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     delete(table: string, primaryKey: string): Promise<boolean>;
 }
@@ -4412,6 +4543,25 @@ export declare interface SqlDialect {
     readonly retryFilter: (error: unknown) => RetryDecision;
 }
 
+/**
+ * Fill `row.id` from the table's declared scheme when it is absent.
+ *
+ * Three behaviours worth stating, because each has bitten somewhere:
+ *
+ *   - an explicit id is NEVER overwritten (tests pin deterministic ids, and
+ *     signup self-stamps before a subject exists);
+ *   - a `numeric` scheme DELETES the key instead of generating, so the
+ *     dialect's SERIAL / AUTO_INCREMENT / IDENTITY fires and the store's
+ *     RETURNING path hands the assigned value back;
+ *   - an UNREGISTERED table is left alone. The row is passed through
+ *     untouched rather than guessed at — a table we do not know is one whose
+ *     id column we cannot reason about.
+ */
+export declare const stampGeneratedId: <T extends Record<string, unknown>>(table: string, row: T) => T;
+
+/** `stampGeneratedId` over a batch. */
+export declare const stampGeneratedIds: <T extends Record<string, unknown>>(table: string, rows: ReadonlyArray<T>) => ReadonlyArray<T>;
+
 /**
  * Stream every row of a table as a lazy `Stream<Row>`, keyset-paginated so
  * memory stays flat regardless of table size. Backpressure is inherent: a
@@ -5009,9 +5159,9 @@ export declare class TenantResidencyUnresolved extends Error {
     constructor(message: string);
 }
 
-export declare const text: () => ColumnBuilder<string, "text">;
+export declare const text: () => ColumnBuilder<string, "text", boolean>;
 
-export declare const timestamp: () => ColumnBuilder<Date, "timestamp">;
+export declare const timestamp: () => ColumnBuilder<Date, "timestamp", boolean>;
 
 /**
  * The timestamp mapping as a STANDALONE field schema: `Date` in the
@@ -5054,6 +5204,19 @@ export declare const timestampMs: Schema.Schema<Date, number>;
  */
 export declare const timestampMsOrNull: Schema.Schema<Date | null, number | null>;
 
+/** The minimal store surface `insertRow` needs — satisfied by `ctx.store`. */
+export declare interface TypedInsertStore {
+    readonly insert: (table: string, row: Row) => Promise<Row>;
+}
+
+/** The minimal store surface `upsertRow` needs. */
+export declare interface TypedUpsertStore {
+    readonly upsert: (table: string, row: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }) => Promise<Row>;
+}
+
 /**
  * `(SELECT ...) UNION (SELECT ...) ...` — dedup-merge. Q6.
  *
@@ -5087,6 +5250,15 @@ export declare interface UniqueSpec {
     readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
 }
 
+/**
+ * Upsert a row, typed the same way. `conflictColumns` is constrained to the
+ * table's own column names, so a typo'd conflict key is a compile error too.
+ */
+export declare const upsertRow: <T extends AnyTable>(store: TypedUpsertStore, table: T, row: InferInsertRow<T>, options: {
+    readonly conflictColumns: ReadonlyArray<keyof InferRow<T> & string>;
+    readonly update?: ReadonlyArray<keyof InferRow<T> & string> | ((existing: InferRow<T>) => Readonly<Partial<InferRow<T>>>);
+}) => Promise<InferRow<T>>;
+
 /**
  * Validate one column-name key on a table's fields map. Throws on
  * empty / invalid characters / > 63 bytes. Records a WARN above 50.