@voltro/runtime 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -39,6 +39,117 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.24.0] — 2026-08-02
+
+### ⚠ BREAKING
+
+- **@voltro/ai, @voltro/cli** — **`agent_threads` and `agent_messages` are `_voltro_agent_threads` and `_voltro_agent_messages`.** The last two framework-owned tables sitting in the user's namespace; the other ten moved in 0.22.0 and these were not in that set.
+
+  The collision it ends is the obvious half. The half that cost a consumer something is `versioningPlugin`: its "framework and plugin tables are out of the default" keys on the `_voltro_` prefix, so `agent_messages` was IN the default versioned set — and `runAssistant` patches the streaming assistant row about every 100 ms while it types. Under `timing: 'in-transaction'` that is a row-history write per throttle tick, on the hottest path in the app. They found it while adopting the versioning inversion and excluded both tables by hand; that `exclude:` entry can go now.
+
+  **The rows move themselves.** `.renamedFrom()` on both, so the next `db apply` or auto-migrate boot emits a catalog-only `ALTER TABLE … RENAME TO` on every dialect — no copy, no row rewrite. `AGENT_THREADS_TABLE` / `AGENT_MESSAGES_TABLE` are exported and carry the new names, and the synthesized `<agent>.messages` query moved with them, so typed code is unaffected.
+
+  The codemod is `manual` for the same reason the 0.22.0 one was: what a transform cannot see is raw SQL written by hand against those names.
+
+### Added
+
+- **@voltro/plugin-auth** — Brute-force account lockout. After 5 failed credential attempts (wrong password OR wrong MFA code) within 15 minutes, sign-in for that email is refused with a `429 account_locked` for 15 minutes; a completed login clears the counter. The counter is keyed by email — an unknown address locks exactly like a real one, so the lock can't be used to probe which accounts exist. **On by default** (a security default); tune or disable via `authRoutesPlugin({ lockout: { maxAttempts, windowSeconds, lockSeconds } })`. Apps that spread `authTables` get the new `loginAttempts` table automatically on the next `voltro db apply` / `voltro dev` boot — it rides the declarative differ, no codemod.
+- **@voltro/cli** — Backup provenance stamp. `voltro data backup` now writes a `voltro-backup-stamp.json` sidecar next to the native dump recording the dialect, the authoritative live-schema fingerprint, the `@voltro/cli` version, and the timestamp — a native `pg_dump`/`mariadb-dump` artifact is otherwise opaque about what it is. `voltro data restore` reads the stamp BEFORE touching the DB and acts on two failures that are silent until they corrupt: a CROSS-DIALECT restore (postgres dump into a mysql DB) is REFUSED (override with `--force`), and a SCHEMA/CODE fingerprint skew WARNS to run `voltro db apply` after the restore. A backup with no stamp (older/hand-made) restores with a caution, not a hard stop. Docs additionally clarify that point-in-time recovery (PITR) is a database/provider concern (WAL/binlog archiving) the framework deliberately does not reimplement, and that a backup you have never restored is a hypothesis. `codemod: none` — new CLI output + a restore-time guard; no user-authored code is affected.
+- **@voltro/database, @voltro/sql-postgres, @voltro/runtime, @voltro/cli** — Per-statement query timeout via `DB_STATEMENT_TIMEOUT_MS` (or `ConnectionConfig.statementTimeoutMs`). A runaway query — a missing index, an accidental cartesian join — no longer pins a pooled connection indefinitely: it is cancelled once it outlasts the deadline, its connection returns to the pool, and the caller gets a normal error instead of a hang that, under load, exhausts the pool and stalls the whole app. Applies to the **runtime query path only** — migrations (`voltro db apply`) run legitimately long statements and are never cancelled by it. **Wired for postgres today** (the default dialect), where it maps to the server-side `statement_timeout` — a real server-enforced cancel (SQLSTATE `57014`), not a client-side disconnect that leaves the query running. Other dialects accept the field but currently ignore it (mssql's driver exposes no per-request timeout, MySQL/MariaDB's `max_execution_time` bounds SELECTs only, SQLite has no pool to protect). New `isQueryTimeout` classifier in `@voltro/runtime` recognises a timeout cancel across dialects. Off by default (unset = no timeout — unchanged behaviour). `codemod: none` — a new opt-in env var / config field; no user-authored code is affected.
+- **@voltro/database, @voltro/cli** — Rolling-deploy safety classifier + `voltro db plan` advisory. A migration can be fully data-safe (every op auto-applies) and still break a zero-downtime rollout: during the overlap window old pods run the previous code against the already-migrated schema, so a dropped/renamed column, a narrowed type, or an added constraint makes those old pods 500 on reads or have their writes rejected. This is an axis ORTHOGONAL to the lossy/blocked data-safety gate — a `dropped()` column is blessed for data loss and still breaks an old reader.
+
+  `classifyRollingDeploySafety(op)` (a pure function in `@voltro/database`) returns a per-operation verdict with a reason + an expand/contract remedy; `voltro db plan` now lists the unsafe operations under a `⚠`, separately from the lossy/blocked summary. Advisory, NOT a refusal — the framework can't know the deploy strategy, and a maintenance-window / scale-to-zero deploy has no overlap window. The classifier is consumed by both the self-hosted advisory and (later) the cloud managed-hosting migration wall. Docs bless the expand/contract pattern. `codemod: none` — new API + CLI output only; no user-authored code is affected.
+- **@voltro/runtime** — Configurable graceful-shutdown deadline via `VOLTRO_SHUTDOWN_GRACE_MS` (milliseconds, clamped to 1s–5min, default 10s). After `SIGTERM`/`SIGINT` the runtime runs its finalizers (connection-pool close, plugin `onDeactivate`, analytics flush, trace persist) and then exits — but installing the signal handler removes node's default kill, so a finalizer that never completes would otherwise hang the process forever; the deadline caps that. Operators set it to sit just under their orchestrator's hard kill (k8s `terminationGracePeriodSeconds` minus the preStop sleep, ECS `stopTimeout`) so the app drains and exits cleanly on its own before SIGKILL truncates it mid-drain. A non-numeric / non-positive value falls back to the 10s default (never a `NaN` deadline that fires immediately). `codemod: none` — a new opt-in env var; no user-authored code is affected.
+- **@voltro/client, @voltro/runtime, @voltro/cli, @voltro/protocol** — WS-rpc mutation idempotency. A retried mutation carrying the same `idempotency-key` is deduplicated at the server: the first result is replayed and the handler does NOT run twice — so a network-blip retry, a reconnect resend, or (with a stable key) a double-click can't create a duplicate order / double charge. It reuses the same engine + `_voltro_idempotency` table as the REST path, so setting `idempotency` in `app.config.ts` now protects BOTH surfaces. `useMutation` / `useAction` mint a per-call key automatically and attach it to the rpc frame (over `RpcClient.currentHeaders`, merged with the auth headers) — pass `mutate(input, { idempotencyKey })` with a stable key for higher-level dedup. The key is scoped by `(tenant, subject, mutation)` so one subject's key can never replay for another, and the stored output is round-tripped through the mutation's output Schema so a `Date`-bearing replay reproduces the original exactly. Off by default (no `idempotency` config → no dedup). `@voltro/client` now peer-depends on `@effect/rpc` + `@effect/platform` (already transitive via `effect`).
+
+### Fixed
+
+- **@voltro/runtime, @voltro/cli** — **A `*.schedule.ts` or `*.subscribe.ts` body written as an Effect silently did nothing.** Not "was rejected" — ran, recorded a success, and never executed.
+
+  ```ts
+  export const handler: ScheduleHandler = () =>
+    Effect.gen(function* () { yield* reconcileInvoices() })   // never ran
+  ```
+
+  Both call sites accepted the value and dropped it. `scheduler.ts` did `await def.handler(ctx)`, and an Effect is not a thenable, so `await` returned it unchanged. `subscriberRunner.ts` tested `result instanceof Promise`, which an Effect is not, so the branch was skipped. Neither raised anything. In an Effect-first framework the natural thing to write was the thing that quietly did nothing — worse than a type error, because a type error is visible.
+
+  Both handler types now accept sync, Promise **and** Effect forms, and one shared `settleHandlerBody` decides what a body IS, so the two call sites can no longer disagree about it. They keep their different DISPOSAL, deliberately: a schedule AWAITS its body (a firing that failed must not record as a success), a subscriber does not (a slow body must not back-pressure the change stream).
+
+  Reported four releases ago. It sat because it was listed as "open" at the bottom of a feedback round and never entered the backlog — the register that now holds that tail is `plans/open/framework/consumer-reported-tail.md`.
+- **@voltro/plugin-auth** — **Brute-force lockout could be entirely inert, on by default, with nothing in the log to say so.** The postgres store fails OPEN on a store error — correct, a DB hiccup must not lock every user out of an app — but it failed open in silence: `recordLoginFailure` swallowed its write error, `isLockedOut` then read "not locked", and the security control that the release notes describe as **on by default** counted nothing at all.
+
+  The reachable case is not a hiccup. An app that enumerates its tables by hand instead of spreading `authTables` never migrates `loginAttempts`, so every write fails with `relation "loginAttempts" does not exist` — permanently, invisibly.
+
+  Behaviour is unchanged: still open, still no throw into the login flow. What is new is that each failure logs `[auth] lockout … failed — brute-force protection is not counting`, which also separates the two cases by hand: a transient error logs once, a missing table logs on every failed sign-in.
+
+  Found by the release gate, and the finding is uncomfortable in a useful way — the contract suite that runs against a LIVE postgres had been extended for lockout, and its hand-written fixture DDL was never given the new table. The fail-open then converted "relation does not exist" into a plain assertion failure, which is the only reason it was visible at all. The fixture now asserts that it covers every table the plugin declares, in both directions, and that assertion runs without postgres so the drift cannot be introduced on a machine where the pg half skips.
+- **@voltro/cli, @voltro/database** — **`voltro db apply` now installs the change triggers the boot diagnostic tells you to install.** It did not, and said it did.
+
+  0.23.0 added a check that compares declared reactivity against the triggers actually in the database, and it works — a consumer's first boot on 0.23.0 reported 500 of their 525 tables as having no change trigger. The remedy it named was `voltro db apply`, and `db apply` answered:
+
+  ```text
+  schema diff: 0 operations, 0 blocked
+    (schema is up to date)
+  db apply: schema is up to date — nothing to apply
+  ```
+
+  Both were telling the truth. Reactive triggers are emitted only by the two FULL-schema emitters — the CREATE-everything path for a fresh database, and the framework bootstrap — so every table an existing app has added through the PLANNER since it was created never got one. The planner has no trigger dimension to notice with, so `db plan` correctly reports zero operations while 500 tables sit untriggered. Their database had 27 triggers, all 27 on framework tables.
+
+  The consequence is the one the diagnostic describes: a single instance is unaffected (its own writes reach its own subscribers in-process), so this stays invisible until you scale out, and then subscriptions quietly stop seeing other instances' writes.
+
+  `db apply` and `db apply --plan` now converge triggers as an explicit, reported step — **including when the schema diff is empty**, which is not an edge case here but the reported one. It is deliberately NOT a planner operation: a trigger carries no data, its DDL is idempotent, and it is derived entirely from `isReactive`, so it converges rather than diffs.
+
+  **A second defect found while fixing the first: a custom `cdcChannel` made the check report every reactive table as missing.** The detector derived the trigger name itself (`framework_changes_<table>`) while the emitter puts the channel in the name on any non-default channel — two derivations of one name, disagreeing exactly where nobody looks. They read one function now.
+
+  Also: **`_voltro_schedule_claims` had no retention.** One row per (schedule, minute-bucket), append-only, and the only table of its family without a sweep — `_voltro_schedule_runs` (the OUTCOME of a firing) had one; its coordination twin (the RACE for the same firing) did not. Measured by the same consumer at 35,128 rows in 14 days across 31 schedules. Now pruned at 30 days by default (`VOLTRO_SCHEDULE_CLAIMS_TTL_HOURS`), which is safe because a claim only ever answers a question about one minute bucket and the scheduler asks about the current one.
+- **@voltro/cli, @voltro/database** — **`voltro serve` could not boot from its own bundle on any app with binlog CDC enabled**, and reported it as a build problem.
+
+  ```text
+  [voltro] serve bundle failed to load: n7 is not a constructor
+  [voltro] FATAL: production `voltro serve` requires a precompiled serve bundle …
+    Run `voltro build` before serving
+  ```
+
+  The bundle was neither missing nor unloadable. `@vlasky/zongji` — the binlog reader — sat on `NATIVE_RUNTIME_LEAVES`, the list of packages routed through a runtime CJS shim instead of being inlined, under a comment describing it as a leaf with "a compiled `.node` binding". It has none: it is a pure-JS ESM package. Through the shim its consumer broke, from the opposite direction to the `pg` regression the same list already documents — the shim's `module.exports` IS the ESM namespace `{ default: ctor }`, esbuild's `__toESM` wraps it again, and `(await import('@vlasky/zongji')).default` came back as the namespace object. Measured both ways:
+
+  ```text
+  shimmed:  typeof mod.default === 'object'   → `is not a constructor`
+  inlined:  typeof mod.default === 'function' → constructs
+  ```
+
+  Inlining it removes the shim's interop from the path. A new guard asserts the RULE rather than the list: every entry on `NATIVE_RUNTIME_LEAVES` must actually carry a compiled binding, or be one of the two documented dynamic-import cases.
+
+  **And the message that hid it is fixed.** The launcher wrapped the bundle's IMPORT and its RUN in one `try`, so every runtime fault the app's boot could raise came out as "serve bundle failed to load … Run `voltro build`", with the stack discarded. The reporter had just run it. The two are separated now: an import that throws is still a build problem, and an import that succeeds followed by a `runServe` throw is reported as itself, with its stack, and does not fall through to a second execution path.
+
+  **`voltro db files` ran a migration and could not record it, on MariaDB.** The file-migration writer passed an ISO-8601 string into `_voltro_migration_plans.appliedAt`, a `DATETIME`, which MariaDB rejects (`ER_TRUNCATED_WRONG_VALUE`). The INSERT runs AFTER `up()`, so the side effects landed and the bookkeeping did not: a probe migration inserting one row grew 1 → 2 → 3 → 4 across four invocations with zero `source='file'` ledger entries, and the deploy could never complete — `db apply` refuses while a file migration is pending and nothing could ever record it.
+
+  The PLANNER's writer had the conversion, inline, with a comment describing this exact rejection. The file writer was a second copy without it, so the common path worked and the escape hatch was broken exactly where it is reached for. One `appliedAtValue` now, shared, covered against a live MariaDB. A ledger write that fails after a successful `up()` also gets its own error type: the recovery is the opposite of the ordinary one — do NOT re-run — and it used to surface as a generic `Failed to execute statement`.
+
+  **`voltro build` never removed output from earlier builds.** Content-hashed chunks mean every build writes new names and nothing overwrites the old ones; nothing reads them either, so they accumulate and ship in the image. Measured by a consumer at 11,048 files where a clean build produces 2,131. Now pruned after the build, keyed on mtime — deliberately not a wipe before it, which opens a window in which the bundle does not exist.
+
+  **A completed drain now says so** (`drained in 80ms`), and one cut at the deadline says that instead. Previously the only trace of either was whatever a shutdown hook happened to log, so "drained in 80 ms" and "was cut at 10 s" looked identical.
+- **@voltro/runtime** — **A request the SSRF policy blocks is now a catchable failure instead of an uncatchable defect.**
+
+  It was `Effect.die(new SsrfBlockedError(...))`. A blocked outbound request is a decision the policy made about a URL the CALLER supplied — and as a defect the caller could not do anything about it: the fiber collapsed, it surfaced as an untagged 500, and a handler that wanted to fall back to a queue, return a typed error to the client, or skip an optional enrichment had no way to.
+
+  It rides inside `HttpClientError.RequestError` rather than being raised on its own, because `HttpClient.HttpClient`'s error channel IS `HttpClientError` — failing with a foreign type would not typecheck for any consumer. So `catchTag('RequestError')` and `catchAll` both see it, `description` names the policy, and the `SsrfBlockedError` survives as `cause` for a caller that wants the specific reason.
+
+  Not breaking: the error channel already carried `HttpClientError`. What changed is that the failure now arrives on it.
+
+  Reported three releases ago. It sat because it was listed as open at the bottom of a feedback round and never entered the backlog — see `plans/open/framework/consumer-reported-tail.md`.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/database** — `VOLTRO_SOFT_DROP=1` convergence is now proven against a live postgres, not argued.
+
+  The planner-side fix — treating `<name>__dropped_<YYYYMMDDHHMMSS>` as framework-managed so an undeclared snapshot is never re-proposed for dropping — shipped some releases ago. What never existed was the assertion, and a consumer had told us so: *"still not testable from a host without the DB"*. That was their constraint, read as ours. The docker stack is exactly what it needed.
+
+  The test soft-drops a COLUMN and a TABLE for real, asserts the data survives under the snapshot name, and asserts the **re-plan is EMPTY** — the property, not the statements. Verified red by disabling the planner's snapshot awareness: both cases then die in `applyPlan`'s convergence check, which is the original defect.
+
+  Two harness mistakes are recorded in the file because each produced a failure that reads exactly like the framework defect under test: an unscoped re-plan against a SHARED database proposes dropping every table in it, and a file-wide scope puts the first test's table into the second test's residue.
+
+---
+
 ## [0.23.0] — 2026-08-02
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -1117,7 +1117,7 @@ export declare interface BeginOAuthResult {
  */
 export declare const bindConnectionSubject: (clientId: number, subject: Subject) => void;
 
-export declare const bindMutation: <Input, Output, E = never>(execute: (input: Input, context: RuntimeContext) => Output | Promise<Output> | Effect.Effect<Output, E, never>, input: Input, spanName?: string) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
+export declare const bindMutation: <Input, Output, E = never>(execute: (input: Input, context: RuntimeContext) => Output | Promise<Output> | Effect.Effect<Output, E, never>, input: Input, spanName?: string, codec?: MutationOutputCodec<unknown>, idempotency?: IdempotencyBinding) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
 
 /**
  * Bind a non-reactive server→client stream (A3). The executor builds a
@@ -2170,6 +2170,13 @@ export declare const drainForShutdown: (options: {
     readonly hooks: ReadonlyArray<() => void | Promise<void>>;
     readonly deadlineMs: number;
     readonly exit: () => void;
+    /** How the drain ended, for the caller to report. A completed drain and one
+     *  CUT at the deadline are different incidents and were indistinguishable in
+     *  the log — asked for by a consumer who could see neither. */
+    readonly onOutcome?: (outcome: {
+        readonly reason: "drained" | "deadline";
+        readonly ms: number;
+    }) => void;
 }) => void;
 
 /**
@@ -2504,6 +2511,9 @@ export declare interface GroupState {
     readonly extreme?: number;
 }
 
+/** What a user handler may return. */
+export declare type HandlerBody = void | Promise<unknown> | Effect.Effect<unknown, unknown, never>;
+
 /** Define a histogram. `boundaries` default to the framework duration buckets. */
 export declare const histogramMetric: (name: string, boundaries?: MetricBoundaries.MetricBoundaries, description?: string) => Metric.Metric.Histogram<number>;
 
@@ -2530,6 +2540,21 @@ export declare interface HttpSecretsOptions {
     readonly ttlMs?: number;
 }
 
+/**
+ * WS-rpc idempotency store + TTL, passed to `bindMutation` as a closure param by
+ * the boot path (`serveApi`/`dev`) — NOT a service. @effect/rpc runs a handler in
+ * a NARROWED context (only the middleware `provides` + declared deps), so a plain
+ * merged service is invisible to `Effect.serviceOption` inside the handler; the
+ * store+ttl are boot-time constants the bind site already holds, so a closure is
+ * both correct and simpler. Omitted → WS mutation dedup is off (the default).
+ * Reuses the SAME `dataStoreIdempotencyStore` + `_voltro_idempotency` table as
+ * the REST path — enable once, protect both.
+ */
+export declare interface IdempotencyBinding {
+    readonly store: IdempotencyStore;
+    readonly ttlMs: number;
+}
+
 export declare interface IdleCheckOptions {
     readonly store: DataStore;
     readonly signals: ActivitySignals;
@@ -2775,6 +2800,15 @@ export declare const isOrglessUserSubject: (subject: {
     readonly tenantId?: string | null;
 } | null | undefined) => boolean;
 
+/** A query cancelled for exceeding the `statementTimeoutMs` deadline, across
+ *  dialects: pg `57014` (query_canceled — what `statement_timeout` raises),
+ *  MySQL `3024` (ER_QUERY_TIMEOUT), MariaDB `1969` (ER_STATEMENT_TIMEOUT), mssql
+ *  `ETIMEOUT` (tedious request timeout), sqlite `SQLITE_INTERRUPT`. NOT a
+ *  transient error — a re-run just repeats the runaway, so it must not retry
+ *  (`servePipeline`'s transient set deliberately excludes it). Lets a consumer /
+ *  observability layer name the failure instead of reading an opaque SqlError. */
+export declare const isQueryTimeout: (dbCause: Record<string, unknown>) => boolean;
+
 /**
  * Optimistic-concurrency guard: an undo is safe only when the row still looks
  * like what the forward mutation left (`next`). If another writer changed it
@@ -3143,6 +3177,14 @@ export declare const makeLazyWorkflowFacade: (resolve: () => 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>>;
 
+/**
+ * Build the replay codec from a mutation's `descriptor.output` Schema (call it at
+ * the bind site). Both directions fall back to the raw value if the Schema can't
+ * round-trip it — a guard for exotic schemas; for a value the handler actually
+ * produced, `encodeUnknownSync` never throws. `undefined` schema → no codec.
+ */
+export declare const makeMutationOutputCodec: (outputSchema: Schema.Schema.AnyNoContext | undefined) => MutationOutputCodec<unknown> | undefined;
+
 /**
  * Build the shared mutation runner. Used by BOTH the rpc WS handler and
  * the `/_voltro/inspect/invoke` endpoint (and the prod entrypoint) so they
@@ -3438,6 +3480,20 @@ export declare interface MutationLike {
     executor(input: unknown, ctx: unknown): unknown;
 }
 
+/**
+ * Encode/decode a mutation's output for idempotent replay. On a FRESH call the
+ * WIRE form (`encode`) is stored, so a later replay `decode`s it back to the exact
+ * Output the handler would have returned and the rpc layer re-encodes it
+ * identically. Storing the DECODED Output directly would corrupt `Date`/etc.
+ * fields through the store's JSON round-trip (encode there expects a `Date`, not
+ * the ISO string a round-trip produced). Built from `descriptor.output` at the
+ * call site; both fns fall back to the raw value if the Schema can't round-trip.
+ */
+export declare interface MutationOutputCodec<Output> {
+    readonly encode: (output: Output) => unknown;
+    readonly decode: (stored: unknown) => Output;
+}
+
 export declare interface MutationRunnerDeps {
     readonly store: TransactionalStore;
     /** Build the per-call `AppContext` bound to the transactional `tx`. */
@@ -5340,7 +5396,20 @@ export declare interface ScheduleFireContext {
  */
 export declare type ScheduleFireInterceptor = (next: () => Promise<void>, ctx: ScheduleFireContext) => Promise<void>;
 
-export declare type ScheduleHandler = (ctx: ScheduleContext) => void | Promise<void>;
+/**
+ * A schedule body. Promise-form or Effect-form; both run.
+ *
+ * The Effect arm is not sugar. Before it existed the call site was
+ * `await def.handler(ctx)`, and an Effect is not a thenable — so `await`
+ * returned it unchanged, the body never executed, and the firing was recorded
+ * as a success. In an Effect-first framework the natural thing to write was the
+ * thing that silently did nothing. Same bridge a file-based migration's `up`
+ * has carried since it shipped.
+ *
+ * `R = never`: the effect must carry its own requirements. Everything a
+ * schedule needs is on `ctx.app`.
+ */
+export declare type ScheduleHandler = (ctx: ScheduleContext) => void | Promise<void> | Effect.Effect<unknown, unknown, never>;
 
 /** What happens when a firing arrives while the previous run of the
  *  same schedule is still in flight. */
@@ -5698,6 +5767,14 @@ export declare const setSystemStoreHandle: (handle: SystemStoreHandle) => void;
 /** Test seam — swap (or reset with `undefined`) the process recorder. */
 export declare const setTimelineRecorderForTest: (recorder: TimelineRecorder | undefined) => void;
 
+/**
+ * Normalise a handler's return value to "a promise, or nothing to wait for".
+ *
+ * `undefined` means the body was synchronous and has already run. Anything else
+ * is a promise the caller disposes of as its context requires.
+ */
+export declare const settleHandlerBody: (body: HandlerBody) => Promise<unknown> | undefined;
+
 /**
  * Register (or clear) the process-global tuple source. Last write wins.
  *
@@ -5716,6 +5793,18 @@ export declare type ShapeClassification = {
     readonly reason: string;
 };
 
+/**
+ * The teardown deadline, from `VOLTRO_SHUTDOWN_GRACE_MS` (milliseconds), clamped
+ * to `[1s, 5min]`. Operators set it to sit JUST UNDER their orchestrator's hard
+ * kill — k8s `terminationGracePeriodSeconds`, ECS `stopTimeout` — so the process
+ * drains in-flight work and exits cleanly on its own BEFORE SIGKILL truncates it
+ * mid-drain (which would strand exactly the finalizers this path exists to run:
+ * connection-pool close, plugin `onDeactivate`, analytics flush, trace persist).
+ * A non-numeric / non-positive value falls back to the 10s default rather than
+ * producing a `setTimeout(…, NaN)` that fires immediately and defeats the drain.
+ */
+export declare const shutdownGraceMsFromEnv: () => number;
+
 /** No-coordination gate for single-instance deployments (PM2,
  *  single pod, dev). */
 export declare const singleCoordinator: Coordinator;
@@ -5973,7 +6062,18 @@ export declare interface SubscribeContext {
  *  framework's CDC `ChangeEvent` re-exported for ergonomics. */
 export declare type SubscribeEvent = ChangeEvent;
 
-export declare type SubscribeHandler = (event: SubscribeEvent, ctx: SubscribeContext) => void | Promise<void>;
+/**
+ * A subscriber body. Promise-form or Effect-form; both run.
+ *
+ * The Effect arm is not sugar — see `ScheduleHandler`. The runner tested
+ * `result instanceof Promise`, an Effect is not one, so the branch was skipped
+ * and the body never executed. No error, no log line, the change event handled
+ * "successfully".
+ *
+ * `R = never`: the effect must carry its own requirements. Everything a
+ * subscriber needs is on `ctx`.
+ */
+export declare type SubscribeHandler = (event: SubscribeEvent, ctx: SubscribeContext) => void | Promise<void> | Effect.Effect<unknown, unknown, never>;
 
 /** Which row op(s) the subscriber listens on. `'any'` matches every
  *  op; an array enumerates the concrete ops. */