@voltro/runtime 0.65.0 → 0.66.0

package/CHANGELOG.md

@@ -39,6 +39,100 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.66.0] — 2026-09-06
+
+### ⚠ BREAKING
+
+- **@voltro/client, @voltro/cli** — Socket reconnects retry immediately, then after 500 ms with factor 1.5 and a 5 s cap; configure `web.api.recovery.retry: { initialMs, thenMs, factor, maxMs }` beside `graceMs` and rebuild the web app. Web and React Native share the policy, reset it on protocol readiness, preserve subscription bases/revisions and report every scheduled retry in client diagnostics. One transport loop owns retries, preventing competing supervisor rebuilds. Migration for custom `startApiSupervisor`/`BuildClient` adapters: own socket retries inside the transport (or use `buildApiRuntime`); `onSocketIssue` now reports health/backstop signals only, and `retryDelayMs` overrides construction failures only. Header resolvers are evaluated per runtime build, so do not rely on socket cuts to refresh a rotated token: the web host retains bounded auth-error refresh, and custom hosts can call `SupervisorHandle.refreshAuth()`. Explicit `refreshAuth()`/`reconnect()` still rebuild. Ordinary web/RN mounts require no adapter changes.
+
+  **`voltro update` carries you across this** — codemod `0.66.0/02_socket-retry-owner`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.66.0).
+- **@voltro/database, @voltro/runtime, @voltro/voltro** — `id({ scheme: 'numeric' })` declares the numeric row key it always emitted. The builder was typed `ColumnBuilder<string, 'id'>` for every scheme and the row decoder used `Schema.String` for every id, so a BIGSERIAL / AUTO_INCREMENT / IDENTITY column arrived in application code as a decimal string. It is now `number`, decoded as `Schema.Number`, and `InMemoryDataStore` allocates numbers so the in-memory store and a SQL store agree.
+
+  Migration — the codemod prints these, and they are ordered by how the failures surface. String operations on such an id stop compiling and the compiler names every one; wrap with `String(id)` at whatever boundary wants text. Equality against a quoted literal (`row.id === '4'`) is the half that keeps compiling and is now permanently false — drop the quotes. Seeds and fixtures spelling the id as a string fail to decode; write them as numbers. Template interpolation needs no change.
+
+  `reference(target, { storage: 'numeric' })` carries the same numeric type.
+
+  **`voltro update` carries you across this** — codemod `0.66.0/01_numeric-id-is-a-number`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.66.0).
+
+### Added
+
+- **@voltro/client, @voltro/protocol** — Add typed `useConnectionSetup(tag)` and `useMutation(tag).withConnectionSetup(handle)` for acknowledged connection-local setup before initial writes and replay. The Effect-scoped barrier follows physical sockets, restores acknowledged intent, shares concurrent setup attempts and clears on leave, unmount or subject/tenant change. Setup descriptors must explicitly declare connection-scoped idempotency; normal writes keep their keys and replay limits. This is not a durable outbox or an authorization grant. Existing mutation identity helpers retain their signatures.
+- **@voltro/cli** — Generated production Compose stacks run declared boot-lifecycle seeds in the migration job, after the reviewed schema plan has applied. Seeding is therefore one pre-deploy operation rather than something every serving replica repeats on boot.
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/voltro** — Mutations can declare `idempotencyScope: 'connection'` for native WebSocket side effects: repeat keys deduplicate within that server-owned connection but execute again on a replacement connection. HTTP RPCs fail with typed `MutationConnectionRequired`, including when dedup is disabled; internal, public REST and agent-tool projections are refused. The default subject-scoped replay behavior of ordinary business mutations is unchanged. This does not replace application authorization, reconnect ordering, durable pending writes or disconnect cleanup.
+- **@voltro/runtime, @voltro/cli, @voltro/testing** — `ctx.connectionState` keeps server-owned, structured-cloneable values for one native RPC connection: mutations defer writes/deletes to the existing commit queue, rollback/retry discards them, and transport close clears the state without allowing late commits to resurrect it. Dev, serve and `makeTestContext({ connection })` share the implementation; `withRpcConnection` selects another connection against the same test store and services. This is neither authentication nor durable membership storage.
+- **@voltro/database, @voltro/runtime, @voltro/sql-postgres, @voltro/sql-mysql, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/testing, @voltro/voltro** — `store.update(table, key, patch)`, `delete`, `patchJson` and `hardDelete` take EITHER an id string or the columns that identify the row:
+
+  await store.update('memberships', { userId: u, orgId: o }, { role: 'member' }) await store.delete('memberships', { userId: u, orgId: o })
+
+  A table declared `.primaryKey(['userId','orgId'])` — or with one explicit key column, which is how a one-to-one shares its parent's key — has no `id`, so it could not be reached by the keyed forms at all. Measured before this, against the in-memory store: `update('memberships', 'u1', …)` returned `null`, `delete('memberships', 'u1')` returned `false`, and the row was untouched. Those are the SAME values a missing row returns.
+
+  The five store implementations did not agree about it either. The SQL stores emitted `WHERE id = ?` literally — 3 sites in postgres, 8 in mysql, 3 in sqlite, 3 in mssql — so a dialect answered `column "id" does not exist`, while the in-memory store keys rows internally and simply missed. A suite on `makeTestApp` runs the quiet one, so it went green over a call that fails in production.
+
+  A key is resolved ONCE, by `rowKeyColumns` in `@voltro/database`, so the five implementations cannot drift about what a key is. A bare string still means the `id` column, unchanged; on a table that has none it is refused with the key columns named, rather than answering `null`.
+
+  Two further defects surfaced when a composite-key table joined the dialect parity harness, both of them older than this change and invisible while the feature had no users:
+
+  - **MySQL could not INSERT such a row.** A row arriving without an `id` was assumed to be an AUTO_INCREMENT table, so the store recovered the key via `LAST_INSERT_ID()` and failed with "is the primary key AUTO_INCREMENT?" — a question about a column the table never declared. It now reads the post-image back by the values just written when nothing was generated. - **MSSQL could not CREATE one over `text()` columns.** `text()` renders as `NVARCHAR(MAX)` there, which SQL Server refuses as a key column. The emitter already bounds indexed text to `NVARCHAR(450)` for exactly this reason; the primary key's own columns were missing from the set that drives it.
+
+  `runDialectParity` gained three composite-key scenarios, so all five dialects assert it — the harness that found both of the above.
+
+  `apiSurface: compatible` — the golden lines that are REPLACED rather than added are the three keyed signatures widening `primaryKey: string` to `primaryKey: RowKey`. A widened parameter accepts everything it did before, so no call site can fail; `@voltro/voltro` is named because the two aggregate goldens carry the same surface and a source package's own report does not pull them along.
+- **@voltro/cli** — `voltro create-project` can add multiple independently cloud-bound projects to one workspace. `add-app --to` and `cloud project link --project` select a target explicitly when needed, and default project port ranges never overlap. API apps now receive manifest/config ports alongside web apps. While the `compose` baseline is active, project/app changes and `voltro baseline sync` regenerate every service plus per-project PostgreSQL databases from those manifests. The generated stack pins PostgreSQL 18.6 and lets containerized web dev resolve its API proxy through `VOLTRO_API_ORIGIN` service DNS.
+- **@voltro/database** — `.primaryKey(['memberId'])` accepts a single explicit natural or reference column as well as a composite set. It previously refused one field and pointed the caller at `id()`, which made a one-to-one shared primary-key/foreign-key impossible to declare without inventing a second key column.
+- **@voltro/database** — `reference(target, { storage: 'numeric' })` declares a foreign key to a table whose primary key is numeric, without disguising it as a plain integer column: row schemas decode it as a number, every SQL renderer emits the dialect's 64-bit integer form, snapshots and introspection round-trip the storage kind, and the migration planner no longer churns it back to text.
+
+  `reference(target, { column: 'key' })` targets a unique alternate key instead of assuming `id`. Deferred cyclic constraints, subject graphs and test factories carry that target column through. The default remains text-and-`id`.
+- **@voltro/protocol, @voltro/cli, @voltro/testing** — Custom REST handlers receive the per-request application context as `ctx.app`. Development, production `serve` and `makeTestApp` bind the same surface, so a REST webhook can publish a typed event or reach cache, KV, workflows and webhooks exactly as an RPC handler does — without a protocol-to-runtime dependency and without stepping outside the framework to do it.
+- **@voltro/protocol** — Typed REST handlers can shape their own response. `response(body, { status, headers })` selects a status and headers, including repeated values such as the several `Set-Cookie` lines a login emits; `restError(status, body, headers)` preserves an application-defined JSON error contract instead of flattening it to the framework's shape; binary responses can pick status and headers the same way. `RestRouteContext` exposes the byte-exact request body alongside method, path and query, so a signed webhook or a multipart protocol no longer has to drop down to a raw plugin route to see the bytes it must verify.
+
+  `requireAuthenticated()` gives a protected REST route one consistent 401 path, distinct from the 403 a scope check produces.
+
+  `apiSurface: compatible` — the golden's one replaced line is the handler's return type widening from `Promise<O> | O` to `Promise<O | RestResponse<O>> | O | RestResponse<O>`. A handler that returns `O` is still assignable, so no declaration site breaks. The one place it is observable is a consumer who reads the descriptor's `handler` type and calls it directly, whose result is now the wider union; the supported way to exercise a route is `makeTestApp`, which is unaffected.
+- **@voltro/database, @voltro/runtime, @voltro/sql-postgres, @voltro/sql-mysql, @voltro/sql-mssql, @voltro/sql-sqlite, @voltro/sql-turso, @voltro/testing, @voltro/voltro** — Upserts accept `updateValues` for additional conflict-only assignments without modifying the INSERT row or changing native column-list upserts into read/compute callbacks. Defined values override the selected update projection; undefined is omitted and identity rewrites are refused. The typed, Effect, replication, transaction and codec surfaces preserve the option, including row-bound encryption. Covered by the shared live-dialect parity suite, including both Turso backends. Existing option fields and calls remain compatible; this is the persistence foundation, not activation of column `.onUpdate()` callbacks.
+
+### Fixed
+
+- **@voltro/client** — Keep a transport-interrupted mutation pending through repeated native `MutationInFlight` replies while its original replay window still permits it. Preserve one key, pending slot and optimistic patch; recheck identity, capability, transport and connection setup before each attempt. Do not renew the window, silently accept a failed write, retry other handler failures or busy-loop on malformed non-positive server delays.
+- **@voltro/client** — `useOutbox` drains online enqueues and restored writes, joins concurrent replay calls, includes writes appended during an acknowledgement, and stops at every failed predecessor without a render-driven retry loop. A subsequent explicit retry or reconnection can retry transient failures; conflicts still require resolution. This scheduling fix does not add a durable-save acknowledgement or cross-tab ownership.
+- **@voltro/client** — Keep late failures from ended physical mutation attempts from marking a healed replacement socket disconnected. Native mutation error events record `affectsTransport: false` when their lifetime evidence proves this distinction; the original failure, commit uncertainty and raw error reporting remain intact. Emitters without native lifetime evidence retain the conservative fallback.
+- **@voltro/database, @voltro/runtime, @voltro/sql-postgres, @voltro/sql-mysql, @voltro/sql-mssql, @voltro/sql-sqlite, @voltro/testing, voltro** — Request-scoped stores evaluate column `.onUpdate()` before validation and encryption for keyed/bulk updates, soft deletes, upsert conflicts and JSON patches. `patchJson` accepts optional companion assignments in the same database UPDATE; object merges are shallow and retain JSON nulls. SQLite-family escaped object keys are compared and preserved after exactly one decoding step, based on a constant in-statement engine probe. Raw stores do not run application callbacks. Scalar JSON roots on SQL Server remain a separate schema-validation limitation.
+- **@voltro/cli** — A generated multi-project Compose stack probes each API's declared port. The generator added one but probed the neighbouring web app's port instead, so an API could be marked healthy without ever being tested — and a web service that correctly waited for API readiness deadlocked behind a check that was never going to describe it.
+- **@voltro/cli** — Production serve/start and SSR bundles now resolve dependencies with the bundler's actual import/require conditions. Installed ESM-only transitive packages no longer become bare external imports that fail after strict-pnpm deployment or pruning. Missing required dependencies and broken installed exports fail the build instead of being reported as optional peers; only actually absent packages declared optional by their importer use that fallback. Native runtime shims remain intact. If this exposes a previously hidden missing dependency, install/fix it in its importing package rather than labelling a required import optional. Real esbuild and Vite tests cover conditional exports, strict transitive resolution, optional and required failures, and execution after relocation without node_modules.
+- **@voltro/cli** — `voltro doctor`'s `cron/bucket-on-wall-clock` follows value references into relative app helpers, including renamed imports, namespace members and re-exports. A `new Date()` in a called `midnightUtcForToday()` is now attributed to its cron in text and `--json` output. Unused helper exports, comments, strings and types do not supply either the wall clock or a clearing `scheduledAt` read. This remains a static advisory, not bucket-key data-flow proof; package imports, tsconfig aliases and dynamic imports are not followed.
+- **@voltro/i18n** — `placeholdersOf` is now exported from `@voltro/i18n`'s public entry, including the built JavaScript and declarations. The 0.64.0 changelog promised that export, but it existed only in the internal catalog module; its tests imported that module and missed the absent package export. Those tests now exercise the public entry. No application change is needed unless you want to use the helper.
+- **@voltro/runtime** — `InMemoryDataStore` keeps seeded rows from tables that deliberately have no `id` column — natural and composite primary keys — and inserts into those tables no longer fabricate one. The store assigns an internal map identity instead, which is what a SQL store does, rather than leaking an undeclared field into application rows.
+
+  Its numeric sequence now starts above the highest seeded id, so the first generated insert can no longer land on top of a seed row.
+- **@voltro/sql-turso** — File-backed libsql connections enable WAL at startup so readers from completed interactive transactions do not block subsequent writers' commits. Remote transports retain server-owned journal configuration. Local-file concurrent-transaction tests require no Turso Cloud account; network and replica synchronization still need separate live validation.
+- **@voltro/runtime** — The in-memory store now applies registered schema literal defaults (including timestamp `now`, JSON and arrays) and implicit nullable values on insert, including transactional, bulk, upsert-insert and insert-ignore-insert paths. Returned rows and change events contain the populated values; explicit values, seeded rows and conflict-update fields are preserved. Mutable defaults are copied per row. App-side factories/computed values remain owned by the shared mutation wrapper; this does not emulate generated SQL expressions or certify database-dialect parity.
+- **@voltro/sql-mssql** — Bind Date parameters as `DateTime2` and strings as `NVarChar`, matching the schema before values reach SQL Server. This preserves milliseconds, dates before 1753, Unicode text and JSON keys/values across row writes, predicates and raw SQL. Explicit NULL remains `NVarChar`. The direct `tedious` dependency uses the version already locked for the SQL client.
+- **@voltro/runtime, @voltro/cli, @voltro/protocol, @voltro/plugin-audit** — Every trace id now comes from one function, `newTraceId()` in `@voltro/runtime` — 128 random bits as 32 hex, the shape a `traceparent` parser, a collector and `voltro traces` all accept.
+
+  Seventeen call sites minted their own, and three of the shapes were not ids. `incoming:<webhookId>`, `reaction:<workflow>`, `schedule:<name>-<ms>` and the literal `'webhooks:trigger'` were CONSTANTS — five of them wrote the identical string into `traceId` and `source`, so the trace id was the caller's label wearing a second hat and every delivery a process handled shared one trace, with the waterfall merging unrelated work. Six more carried `public-`/`grpc-`/`rest-` plus eight base36 characters, about 41 bits, which collides well inside a busy day. One passed `randomUUID()` unstripped, 36 characters with dashes, which no `traceparent` parser accepts — including this framework's own.
+
+  The entry-point kind is not lost: it lives in the `source` field beside the id, which is where it was already being written.
+
+  Plugin HTTP routes now carry a real one too. `PluginHttpRouteEvent` gains `traceId` — the caller's `traceparent` where one arrived, freshly minted otherwise — and the audit trail records it instead of the empty string it wrote before, so an incident review can join a login to what it caused. `apiSurface: compatible`: an observer that ignores the new field is unaffected, and the framework is the only producer of the event.
+
+  A guard in `@voltro/runtime` now asks the question over the whole tree rather than per call site, because the previous test pinned exactly one of them and the same defect went on living at sixteen others.
+- **@voltro/database, @voltro/runtime** — Declarative migrations now retain partial-index predicates and partial uniqueness on new and existing tables, introspect native filters on PostgreSQL/SQLite/SQL Server, detect same-name predicate changes and invalid PostgreSQL online indexes, and include predicates in drift fingerprints. A partial unique index is never emitted as a full UNIQUE constraint. Existing qualifying duplicates refuse the apply without automatic data repair; a pre-DDL conflict check protects replacements when the current column shape supports it. MySQL/MariaDB uniqueActive lowering remains; unlowered partial indexes are refused by the declarative path. SQL normalization is conservative, not a general expression-equivalence prover.
+
+  Memory upsert now addresses matched rows through their actual conflict-column key instead of assuming an id column, both directly and transactionally. Natural/composite primary-key rows preserve independent fields, rollback and post-commit events. The schema/API spelling is unchanged and needs no source codemod; projects upgrading must review and apply the newly visible missing constraints, resolving conflicting historical data explicitly rather than deleting it automatically.
+- **@voltro/cli** — Production workspace WebSocket proxies preserve the browser's Host header, so the native same-origin guard accepts legitimate requests behind internal Docker or cluster hostnames while continuing to reject foreign and opaque origins.
+- **@voltro/protocol** — REST descriptors reject undeclared descendant paths before decoding, resolving identity or executing their handler, instead of accidentally serving parent data or performing parent writes. Named parameters, trailing slashes, explicit splats and raw plugin HTTP prefix routes keep their declared behavior.
+- **@voltro/runtime** — Isolate connection credentials across HTTP/WebSocket protocols and listeners, and deliver every disconnect to both runtime cleanup and the RPC core. Executors receive the server-owned `ctx.request.connection` identity, transport and close signal; numeric client IDs remain opaque process-local handles. Connection state is shared across bundled and external module copies.
+- **@voltro/cli** — `voltro prune-runtime` now preserves package-resolution metadata for rooted native dependencies, so packages such as `argon2` remain importable in pruned production images.
+- **@voltro/sql-sqlite, @voltro/sql-turso, @voltro/testing** — SQLite-family raw stores now encode registered JSON and array columns on every row-write path, including insertMany, updateMany, callback upserts and conflict-only updateValues. Previously objects could fail binding or reach Turso as invalid JSON when a request codec had not already serialized them. Shared live-dialect tests cover direct and transactional writes over SQLite and both Turso clients as well as the other SQL stores.
+- **@voltro/testing** — Declared events published by a mutation under `invoke` now use the transaction's commit queue, including subject/tenant re-scopes; rollback and deadlock replay discard failed-attempt notifications, while untransacted actions still publish immediately.
+- **@voltro/cli** — Apply the shared page-safe security-header policy to both web listeners, including streaming, assets and errors, with `security.headers` configuration and route-owned overrides. Do not derive HSTS from untrusted forwarded headers. Proxy native runtime capability discovery in production as well as dev: one public GET per configured workspace API, not the development inspect surface. Named and custom socket paths reach the actual server's replay capability; ambiguous custom socket parents fail explicitly instead of advertising the wrong API. No replay support or successful writes are synthesized by the proxy.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cli** — Building the CLI package now gives its declaration-rollup process a bounded 6144 MiB heap, and packing delegates to the same build script. The seven-entry rollup exhausted the default roughly 4 GiB heap even in an isolated Node 24 build; the measured build succeeds with the scoped allowance. This does not change the memory settings of application builds or serving processes, and does not disable declaration validation or increase build concurrency.
+- The local release gate now executes the CI test planner with all packages and both CLI projects, rather than skipping its GitHub-specific preparation and reading missing shard files. Missing filters or project selectors fail before tests start; the coverage verifier also refuses a missing expected-package plan. Selftests execute the workflow's actual producer/consumer handoff. MySQL test fixtures check authenticated TCP readiness and distinguish cold initialization from failed steady-state healthchecks. The Postgres partial-index contract creates and cleans up its own database on the regular fixture server, so all seven assertions run without an additional opt-in flag in both local and CI gates. Row-history test files run serially because their live fixtures install and write the same fixed-name Postgres table; parallel setup could deadlock before the history assertions ran when the schema was cold.
+
+---
+
 ## [0.65.0] — 2026-09-04
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -11,7 +11,7 @@ import { ConnectionCredential } from '@voltro/protocol';
 import { ConnectionInfo } from '@voltro/protocol';
 import { ConnectionInfoMiddleware } from '@voltro/protocol';
 import { ConnectionKind } from '@voltro/protocol';
-import { ConnectionState } from '@voltro/protocol';
+import { ConnectionState as ConnectionState_2 } from '@voltro/protocol';
 import { ConstraintFacts } from '@voltro/database';
 import { ConstraintKind } from '@voltro/database';
 import { ConstraintViolation } from '@voltro/protocol';
@@ -57,6 +57,7 @@ import { listRetentions } from '@voltro/database';
 import { Metric } from 'effect';
 import { MetricBoundaries } from 'effect';
 import { MetricReader } from '@opentelemetry/sdk-metrics';
+import { MutationIdempotencyScope } from '@voltro/protocol';
 import { NoRowFound } from '@voltro/protocol';
 import { PendingApproval } from '@voltro/protocol';
 import { PluginHttpRoute } from '@voltro/protocol';
@@ -72,6 +73,7 @@ import { RetentionSource } from '@voltro/database';
 import { RetentionSpec } from '@voltro/database';
 import { retentionTtlMsFromEnv } from '@voltro/database';
 import { Row } from '@voltro/database';
+import { RowKey } from '@voltro/database';
 import { RowPatch } from '@voltro/protocol';
 import { Rpc } from '@effect/rpc';
 import { RpcGroup } from '@effect/rpc';
@@ -103,6 +105,7 @@ import { TenantRowNotFound } from '@voltro/protocol';
 import { TenantScopeViolation } from '@voltro/protocol';
 import { Tracer } from 'effect';
 import { Unauthenticated } from '@voltro/protocol';
+import { UpsertOptions } from '@voltro/database';
 import { ValidationError } from '@voltro/protocol';
 import { ValidationErrors } from '@voltro/protocol';
 import { VersionConflict } from '@voltro/database';
@@ -1026,6 +1029,10 @@ export declare interface AppContext {
      */
     readonly storeForTenant: (tenantId: string) => FluentStore;
     readonly request: RuntimeContext;
+    /** Ephemeral server-owned state of this RPC connection. Absent for internal
+     * calls; mutation writes commit with the operation and disconnect clears it.
+     * It grants no authority until the app explicitly records its own decision. */
+    readonly connectionState?: ConnectionState;
     /** Typed authorization slice — the caller's effective scopes. Use
      *  `ctx.access.has(scope)` / `yield* ctx.access.require(scope)` instead of
      *  reaching into `ctx.request.subject.scopes`. Always present. */
@@ -1650,7 +1657,7 @@ export declare const bindMutation: <Input, Output, E = never>(execute: (input: I
  * schema keeps exactly the old behaviour rather than collapsing errors it
  * cannot classify.
  */
-declaredError?: Schema.Schema.All) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
+declaredError?: Schema.Schema.All, idempotencyScope?: MutationIdempotencyScope) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
 
 /**
  * Bind a non-reactive server→client stream (A3). The executor builds a
@@ -2296,7 +2303,7 @@ export declare interface ConnectionsFacade {
     tryGet(connectionId: string): Promise<ResolvedConnection | null>;
     /** Every declared connection with the caller's status — the same projection
      *  `__voltro.connections.list` serves, for server-side rendering. */
-    list(): Promise<ReadonlyArray<ConnectionState>>;
+    list(): Promise<ReadonlyArray<ConnectionState_2>>;
 }
 
 export declare interface ConnectionsFacadeDeps {
@@ -2305,6 +2312,19 @@ export declare interface ConnectionsFacadeDeps {
     readonly subject: Subject;
 }
 
+/** Server-local application state for ONE RPC connection. Not authentication,
+ * a presence roster or durable storage. Mutation writes become visible only
+ * after commit; reads always see committed state, including in the writer.
+ * Values must be structured-cloneable and are copied on write and read so a
+ * mutable alias cannot bypass the transaction boundary.
+ * Disconnect clears everything and a reconnect starts empty. */
+export declare interface ConnectionState {
+    readonly get: (key: string) => unknown;
+    readonly has: (key: string) => boolean;
+    readonly set: (key: string, value: unknown) => void;
+    readonly delete: (key: string) => void;
+}
+
 /** Test-only — number of streams currently registered for a client. */
 export declare const _connectionStreamCount: (clientId: number) => number;
 
@@ -3645,7 +3665,7 @@ export declare interface EffectStoreOps {
     readonly query: <R = Row>(descriptor: QueryDescriptor<R>) => Effect.Effect<ReadonlyArray<R>, StoreError>;
     readonly insert: (table: string, row: Row) => Effect.Effect<Row, StoreError>;
     readonly insertMany: (table: string, rows: ReadonlyArray<Row>) => Effect.Effect<ReadonlyArray<Row>, StoreError>;
-    readonly patchJson: (table: string, primaryKey: string, path: string, value: unknown) => Effect.Effect<Row | null, StoreError>;
+    readonly patchJson: (table: string, primaryKey: string, path: string, value: unknown, additionalPatch?: Readonly<Record<string, unknown>>) => Effect.Effect<Row | null, StoreError>;
     readonly update: (table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>) => Effect.Effect<Row | null, StoreError>;
     readonly updateMany: (table: string, patch: Readonly<Record<string, unknown>>, options: {
         readonly where: Predicate;
@@ -3654,10 +3674,7 @@ export declare interface EffectStoreOps {
     readonly deleteMany: (table: string, options: {
         readonly where: Predicate;
     }) => Effect.Effect<number, StoreError>;
-    readonly upsert: (table: string, row: Row, options: {
-        readonly conflictColumns: ReadonlyArray<string>;
-        readonly update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
-    }) => Effect.Effect<Row, StoreError>;
+    readonly upsert: (table: string, row: Row, options: UpsertOptions) => Effect.Effect<Row, StoreError>;
     readonly insertIgnore: (table: string, row: Row, options: {
         readonly conflictColumns: ReadonlyArray<string>;
     }) => Effect.Effect<Row, StoreError>;
@@ -4826,11 +4843,11 @@ export declare interface FluentStore extends Omit<MutationStore, 'update' | 'del
     /** Fluent predicate update: `update('notes').where('id', id).set({...})`. */
     update(table: string): UpdateBuilder;
     /** Keyed update by primary key — returns the post-image. */
-    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row_7 | null>;
+    update(table: string, primaryKey: RowKey, patch: Readonly<Record<string, unknown>>): Promise<Row_7 | null>;
     /** Fluent predicate delete: `delete('notes').where('id', id).soft()`. */
     delete(table: string): DeleteBuilder;
     /** Keyed delete by primary key. */
-    delete(table: string, primaryKey: string): Promise<boolean>;
+    delete(table: string, primaryKey: RowKey): Promise<boolean>;
     /**
      * Build an update patch from `input`, keeping ONLY the listed `keys` whose
      * value the caller actually PROVIDED (`!== undefined`). Collapses the
@@ -4955,6 +4972,10 @@ export declare const getResourcePolicy: (resourceType: string) => ResourcePolicy
 /** The registered row filter, or `undefined`. */
 export declare const getRowFilter: () => RowFilter<never> | undefined;
 
+/** Read the live server-owned connection for an opaque runtime clientId.
+ * Missing for internal invocations and after transport teardown. */
+export declare const getRpcConnection: (clientId: number) => RpcConnection | undefined;
+
 /**
  * Read the currently-registered process-wide handle (`undefined` when none
  * is registered — the state in which `runAsSystem` refuses).
@@ -5139,19 +5160,16 @@ export declare class InMemoryDataStore implements DataStore {
     query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
     insert(table: string, row: Row): Promise<Row>;
     insertMany(table: string, rows: ReadonlyArray<Row>): Promise<ReadonlyArray<Row>>;
-    patchJson(table: string, primaryKey: string, path: string, value: unknown): Promise<Row | null>;
-    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row | null>;
-    delete(table: string, primaryKey: string): Promise<boolean>;
+    patchJson(table: string, primaryKey: RowKey, path: string, value: unknown, additionalPatch?: Readonly<Record<string, unknown>>): Promise<Row | null>;
+    update(table: string, primaryKey: RowKey, patch: Readonly<Record<string, unknown>>): Promise<Row | null>;
+    delete(table: string, primaryKey: RowKey): Promise<boolean>;
     updateMany(table: string, patch: Readonly<Record<string, unknown>>, options: {
         where: Predicate;
     }): Promise<number>;
     deleteMany(table: string, options: {
         where: Predicate;
     }): Promise<number>;
-    upsert(table: string, row: Row, options: {
-        conflictColumns: ReadonlyArray<string>;
-        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
-    }): Promise<Row>;
+    upsert(table: string, row: Row, options: UpsertOptions): Promise<Row>;
     insertIgnore(table: string, row: Row, options: {
         conflictColumns: ReadonlyArray<string>;
     }): Promise<Row>;
@@ -5583,7 +5601,7 @@ export declare class LinearScanMatcher implements Matcher {
 }
 
 /** Every connection the app declares, projected for ONE subject. */
-export declare const listConnectionStates: (store: VaultStore, registry: ConnectionRegistry, subjectId: string) => Promise<ReadonlyArray<ConnectionState>>;
+export declare const listConnectionStates: (store: VaultStore, registry: ConnectionRegistry, subjectId: string) => Promise<ReadonlyArray<ConnectionState_2>>;
 
 export declare const listResourcePolicies: () => ReadonlyArray<ResourcePolicy>;
 
@@ -5817,6 +5835,12 @@ export declare const makeConnectionResolver: (deps: {
 
 export declare const makeConnectionsFacade: (deps: ConnectionsFacadeDeps) => ConnectionsFacade;
 
+/** Host seam shared by dev/serve and testing. Pass the mutation lifecycle's
+ * existing afterCommit collector; rolled-back/retried bodies must discard it.
+ * Outside a transaction writes are immediate. Values are server-owned; do not
+ * put a client payload here as an authority claim. */
+export declare const makeConnectionState: (connection: RpcConnection, afterCommit?: (work: () => Promise<unknown>) => void) => ConnectionState;
+
 /**
  * Factory the CLI binds into the plugin bind-ctx: closes over the
  * process-wide coordinator + replicaId so a plugin calls the ergonomic
@@ -5891,7 +5915,7 @@ export declare const makeIdleGate: (graceMs: number, now?: () => number) => Idle
 export declare const makeLazyWorkflowFacade: (resolve: () => WorkflowsAppContext | undefined) => WorkflowsAppContext;
 
 /** `__voltro.connections.list` — every declared connection, for the caller. */
-export declare const makeListConnectionsExecutor: (deps: ConnectionBuiltinDeps) => (_input: Record<string, never>, ctx: ConnectionExecutorCtx) => Promise<ReadonlyArray<ConnectionState>>;
+export declare const makeListConnectionsExecutor: (deps: ConnectionBuiltinDeps) => (_input: Record<string, never>, ctx: ConnectionExecutorCtx) => Promise<ReadonlyArray<ConnectionState_2>>;
 
 /**
  * Build the replay codec from a mutation's `descriptor.output` Schema (call it at
@@ -6489,7 +6513,7 @@ export declare interface MutationRunnerDeps {
 export declare interface MutationStore extends DataStore {
     /** Bypass auto-soft-delete. Hard-removes the row regardless of
      *  whether the table has `softDelete()` applied. */
-    hardDelete(table: string, primaryKey: string): Promise<boolean>;
+    hardDelete(table: string, primaryKey: RowKey): Promise<boolean>;
 }
 
 export declare type NegotiatedEncoding = 'br' | 'gzip';
@@ -6499,6 +6523,25 @@ export declare type NegotiatedEncoding = 'br' | 'gzip';
  *  (a client sending both accepts both). */
 export declare const negotiateEncoding: (acceptEncoding: string | undefined) => NegotiatedEncoding | undefined;
 
+/**
+ * A fresh trace id for work that has NO incoming span to continue — a webhook
+ * delivery, a schedule firing, a devtools invoke, a REST or gRPC entry point.
+ *
+ * 128 random bits as 32 lowercase hex, the shape `TRACEPARENT_RE` above accepts
+ * and the shape a collector, a log pipeline or `voltro traces` can join on.
+ *
+ * The reason this exists as ONE function: every entry point that minted its own
+ * had drifted somewhere different, and three of the shapes were not ids at all.
+ * `incoming:<webhookId>`, `reaction:<workflow>` and the literal
+ * `'webhooks:trigger'` are CONSTANTS — they were the caller's `source` label
+ * copied into the id field, so every delivery a process ever handled shared one
+ * trace and the waterfall merged unrelated work. `public-`/`grpc-`/`rest-` plus
+ * eight base36 characters carried ~41 bits, which collides long before a busy
+ * day is over. The entry-point kind is not lost by fixing this: it lives in the
+ * `source` field beside the id, which is where it was already being written.
+ */
+export declare const newTraceId: () => string;
+
 /**
  * The backoff curve, extracted so it can be asserted directly — a schedule
  * that backs off wrongly is otherwise only visible as a latency an integration
@@ -7089,7 +7132,7 @@ export declare interface PreviewStore {
 /** Project a stored row into the wire shape. Deliberately total over the
  *  columns the descriptor declares — and deliberately silent about the token
  *  columns, which have no wire representation at all. */
-export declare const projectConnectionState: (definition: ConnectionDefinition, row: AnyRow_2 | undefined) => ConnectionState;
+export declare const projectConnectionState: (definition: ConnectionDefinition, row: AnyRow_2 | undefined) => ConnectionState_2;
 
 /** Exact-match property filter. Values are AND'd. */
 export declare type PropertyFilter = Readonly<Record<string, string | number | boolean | null>>;
@@ -7646,6 +7689,17 @@ export declare interface RebacSubject {
 
 export declare const recordCoalesced: (label: string, collapsed: number) => void;
 
+/**
+ * The verified expiry of the credential a connection authenticated with, in
+ * unix SECONDS — recorded by the auth chain, read by `ConnectionInfo`.
+ *
+ * It lives here rather than being re-derived from headers because those are two
+ * different facts once more than one auth shape exists. The header derivation
+ * read the `voltro:session` cookie and nothing else, so an app on Bearer JWTs
+ * had no bound at all while the docs said every realtime primitive had one.
+ * The strategy that verified the token is the only place the expiry is known,
+ * and this is how it reaches the consumer without a second derivation.
+ */
 export declare const recordCredentialExpiry: (clientId: number, exp: number | undefined) => void;
 
 /** What the framework emit-seams (servePipeline / rpcServer / plugin wrappers)
@@ -7935,6 +7989,8 @@ export declare interface RegistryTableLike {
          * Distinct from `defaultValue` (literal landed in DDL).
          */
         readonly defaultFactory?: () => unknown;
+        /** Application-side value used when an UPDATE omits this column. */
+        readonly onUpdate?: 'now' | (() => unknown);
         /**
          * Computed field — re-evaluated on INSERT (AFTER defaults) and on
          * UPDATE (against the merged post-update row); the return value
@@ -7969,6 +8025,13 @@ export declare interface RegistryTableLike {
         readonly name: string;
         readonly fields: ReadonlyArray<string>;
     }>;
+    /**
+     * The columns of an EXPLICIT primary key (`.primaryKey([...])`). Absent or
+     * empty for the ordinary table whose `id()` column carries the key. The
+     * registry surfaces it so the keyed store forms can refuse a table they have
+     * no single string to address — see `SchemaInfo.declaredPrimaryKey`.
+     */
+    readonly appliedPrimaryKey?: ReadonlyArray<string>;
     /**
      * Optional `effect/Schema` the framework decodes a row against
      * BEFORE every INSERT. Set via `table().validate(schema)`. The
@@ -8118,7 +8181,7 @@ export declare class ReplicatedDataStore implements DataStore {
     private routeWaitMode;
     insert(table: string, row: Row): Promise<Row>;
     insertMany(table: string, rows: ReadonlyArray<Row>): Promise<ReadonlyArray<Row>>;
-    patchJson(table: string, primaryKey: string, path: string, value: unknown): Promise<Row | null>;
+    patchJson(table: string, primaryKey: string, path: string, value: unknown, additionalPatch?: Readonly<Record<string, unknown>>): Promise<Row | null>;
     update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row | null>;
     delete(table: string, primaryKey: string): Promise<boolean>;
     updateMany(table: string, patch: Readonly<Record<string, unknown>>, options: {
@@ -8127,10 +8190,7 @@ export declare class ReplicatedDataStore implements DataStore {
     deleteMany(table: string, options: {
         where: Predicate;
     }): Promise<number>;
-    upsert(table: string, row: Row, options: {
-        conflictColumns: ReadonlyArray<string>;
-        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
-    }): Promise<Row>;
+    upsert(table: string, row: Row, options: UpsertOptions): Promise<Row>;
     insertIgnore(table: string, row: Row, options: {
         conflictColumns: ReadonlyArray<string>;
     }): Promise<Row>;
@@ -8933,6 +8993,15 @@ export declare interface RowHistoryEntry {
     readonly traceId?: string | null;
 }
 
+/** Server-owned lifetime, not a user identity or a client-supplied claim.
+ * WebSockets retain it across calls; HTTP retains it only within one request.
+ * Reconnects and server restarts receive a new id. */
+export declare interface RpcConnection {
+    readonly id: string;
+    readonly transport: 'websocket' | 'http';
+    readonly signal: AbortSignal;
+}
+
 export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
     readonly group: RpcGroup.RpcGroup<Rpcs>;
     readonly handlersLayer: Layer.Layer<Rpc.ToHandler<Rpcs>>;
@@ -9210,14 +9279,15 @@ export declare interface RuntimeContext {
      *  build the outbound `traceparent` header for cross-api hops. */
     readonly spanId?: string;
     /**
-     * Per-connection identifier the rpc transport assigns to a
-     * WebSocket connection. Stable for the lifetime of that connection.
-     * Used by re-auth handlers (`auth.signin`) to write into the
-     * per-connection subject override map so subsequent calls on the
-     * same connection see the new subject. `undefined` for non-rpc
-     * call paths (workflows, smoke tests, internal invocations).
+     * Opaque process-wide identifier, distinct across RPC transports/listeners.
+     * Stable within a WebSocket or one HTTP request; never persist this number.
+     * Re-auth handlers use it to bind a credential, not a resolved subject.
+     * Undefined for non-RPC call paths (workflows, internal invocations).
      */
     readonly clientId?: number;
+    /** Server-owned transport identity and close signal. Not authentication;
+     * session membership remains an application's explicit access decision. */
+    readonly connection?: RpcConnection;
 }
 
 /**
@@ -9635,6 +9705,8 @@ export declare interface SchemaInfo {
      * on every UPDATE against the merged post-update row.
      */
     readonly computedFields: ReadonlyMap<string, (row: Readonly<Record<string, unknown>>) => unknown>;
+    /** Optional for custom registries; absent means no automatic update columns. */
+    readonly onUpdateFields?: ReadonlyMap<string, 'now' | (() => unknown)>;
     /** The column marked `.version()`, when the table declares one. */
     readonly versionColumn?: string;
     /**
@@ -9671,11 +9743,24 @@ export declare interface SchemaInfo {
     readonly validatePatchSchema?: Schema.Schema.Any;
     /**
      * Resolved id-scheme for the table's primary-key column. `undefined`
-     * for tables that have no `id`-typed column (rare; framework tables
-     * always have one). MutationStore reads this to decide whether to
-     * auto-generate a string id or omit the column for the DB to allocate.
+     * for tables that have no `id`-typed column — a natural or composite
+     * primary key, see `declaredPrimaryKey`. MutationStore reads this to decide
+     * whether to auto-generate a string id or omit the column for the DB to
+     * allocate.
      */
     readonly idScheme?: IdScheme;
+    /**
+     * The columns of an EXPLICIT primary key (`.primaryKey(['userId','orgId'])`,
+     * or one column for a shared key). Empty for the ordinary table whose `id()`
+     * column carries the key.
+     *
+     * Read by the keyed store forms — `update(table, pk, patch)` and
+     * `delete(table, pk)` address a row by a single string, which such a table
+     * has nothing to match against. Before this was carried here they answered
+     * `null` / `false`: the SAME values that mean "no such row", so a caller
+     * could not tell a missing row from a call that can never find one.
+     */
+    readonly declaredPrimaryKey: ReadonlyArray<string>;
 }
 
 /**
@@ -9714,6 +9799,11 @@ export declare interface SchemaRegistry {
      * hook in `./storeMiddleware.ts`.
      */
     idScheme(table: string): IdScheme | undefined;
+    /**
+     * The columns of the table's EXPLICIT primary key, or an empty array when
+     * its `id()` column carries the key. See {@link SchemaInfo.declaredPrimaryKey}.
+     */
+    declaredPrimaryKey(table: string): ReadonlyArray<string>;
     /**
      * Per-column app-side default factories for a table. Empty map if
      * none. Read by MutationStore.stampedForInsert to fill missing
@@ -11071,7 +11161,7 @@ export declare type TupleSource = (req: {
 export declare const TX_READ_VERSIONS_KEY: unique symbol;
 
 /**
- * Drop everything this connection accumulated. Called by the WS-close finalizer
+ * Drop everything this connection accumulated. Called by the transport finalizer
  * and by explicit sign-out flows. Idempotent.
  */
 export declare const unbindConnection: (clientId: number) => void;