@voltro/runtime 0.78.0 → 0.79.0

package/CHANGELOG.md

@@ -39,6 +39,64 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.79.0] — 2026-09-23
+
+### ⚠ BREAKING
+
+- **Probes answer on the app port from the first moment, on every command** — `@voltro/cli`, `@voltro/runtime`, `@voltro/voltro`
+
+  `voltro dev`, `voltro serve` and `voltro start` now bind their app port as the FIRST thing they do once they know it, and answer `/internal/liveness` (200), `/internal/readiness` (503 until the app serves, then 200 with the dependency ping) and `/internal/startup` (JSON `{ phase, ready, elapsedMs, … }`, 503 → 200) there through the whole boot — a slow database connect, a fingerprint check or a cold migrate included. Every other request and every WebSocket upgrade gets `503 + Retry-After: 1` until ready, then the app serves on the same socket and the probe paths keep answering before routing. There is ONE server and ONE port, so a probe path means the same thing on every command; `voltro dev` no longer binds a second probe server on app port + 1 and no longer reads `VOLTRO_DEV_HEALTH_PORT`. Migration: point every probe of a pod running `voltro dev` at the app port and delete the variable — the codemod prints the exact steps and finds the variable in compose, Helm and CI files.
+
+  **`voltro update` carries you across this** — codemod `0.79.0/01_probes-on-the-app-port`. 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.79.0).
+- **A rejected credential is refused on the default tenant policy too** — `@voltro/cli`, `@voltro/protocol`, `@voltro/voltro`
+
+  A request whose credential a strategy rejects (an expired or malformed token, a revoked session or key) now ends with `Unauthenticated` (`credential rejected: <reason>`) on every anonymous-tenant policy. Until now that held under `auth: { anonymousTenantId }` and `auth: { anonymousTenantRequired: true }`, but not for an app that sets neither. There, a procedure without a guard served the caller as an anonymous one, and an open query answered public data to a token that had just been refused. A caller who sends no credential is unaffected: it still resolves to the tenant its `x-tenant` header names, or to the development tenant. `composeAuthStrategies` gains `anonymousTenantDefault` for that default tenant. Unlike a `fallback`, it does not take over the rejected-credential decision. A client that kept sending a stale cookie or token and relied on the anonymous answer now receives `Unauthenticated`, which the error bus reports and `wireAuthRefresh` acts on.
+
+  **`voltro update` carries you across this** — codemod `0.79.0/03_rejected-credentials-refused-on-the-default-policy`. 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.79.0).
+
+### Added
+
+- **A 1366 over a 4-byte character says which config field fixes it** — `@voltro/database`
+
+  When MySQL or MariaDB refuse a write with `Incorrect string value: '\xF0…'` (errno 1366 over a four-byte UTF-8 lead byte — an emoji into a `utf8mb3` column), the store's `detail:` line now carries a `hint:` naming the column and the remedy: declare `store: { dialect, charset: 'utf8mb4' }` in `app.config.ts` and run `voltro db plan`. A 1366 for any other reason gets no advice about character sets.
+- **The store's character set is declared once and every table follows it** — `@voltro/database`, `@voltro/cli`, `@voltro/devtools-ui`
+
+  On MySQL and MariaDB the framework's `CREATE TABLE` named no character set, so a `text()` column inherited whatever the database was created with while a `json()` column did not (MariaDB's `JSON` is `LONGTEXT CHARACTER SET utf8mb4`, MySQL's has none) — and on a `utf8mb3` database one table refused an emoji in its text column with errno 1366 and took it in its json column. `app.config.ts` now takes `store: { dialect: 'mariadb' | 'mysql', charset: 'utf8mb4' | 'utf8mb3' }`: every declared table is created with it as its default and, when a live table's string columns are stored otherwise, converted to it by a new `convert-charset` plan operation — a table rewrite that drops and re-creates the foreign keys touching the table, so a pair bound by a constraint converts together instead of one side failing with errno 150. Widening to `utf8mb4` is `safe`; narrowing to `utf8mb3` is `lossy` and waits for the destructive opt-in. json columns keep the engine's own charset (neither engine lets it be declared). Unset, nothing changes. A charset on any other dialect is refused at boot, and a `DB_DIALECT` override off the mysql family drops it with a logged line rather than silently.
+
+  The public signatures that changed only gain optional trailing parameters (`declaredSnapshot`, `emitNamespacedSchemaSql`, `emitNamespaceProvisionDdl`, the schema-emit options) and one union member (`convert-charset` in the migration operation kind), so existing calls compile unchanged. Only an exhaustive `switch` over that operation kind would need a new case.
+- **The plan and the doctor name tables whose text cannot hold what json can** — `@voltro/cli`, `@voltro/database`
+
+  Without a declared store charset, `voltro db plan` prints — under the plan — the MySQL / MariaDB tables whose text columns are stored in a character set narrower than their json columns' `utf8mb4`, and the tables whose string columns are not all in one character set (a column converted by hand). `voltro doctor` has the same section, reading `information_schema`, with three outcomes that never print alike: not applicable off the mysql family, not checked with the reason when no database is reachable, and the findings — against the declaration when one is set. A healthy `utf8mb4` database reports nothing; in `--json` the section is `storeCharset`.
+
+### Fixed
+
+- **A handler's own `Unauthenticated` reaches the client typed, on any procedure** — `@voltro/protocol`, `@voltro/cli`, `@voltro/runtime`
+
+  `Unauthenticated` and `ScopeError` are now members of every procedure's wire error union — queries, mutations, actions, streams and workflow starts, whether or not the descriptor declares a guard — and `Unauthenticated` of every event's. They used to ride only a procedure with an enforced `guards:` entry, on the reasoning that an open procedure cannot produce them. It can: the auth middleware refuses an open procedure with a rejected credential exactly as it refuses a guarded one, and a handler may refuse on its own with `assertAuthenticated` or `requireScope`. On a procedure without a guard the server judged that handler-side refusal undeclared and collapsed it, so the browser received `{ _tag: 'InternalError', message: 'Unauthenticated: …' }` — the typed error's name inside a defect that no `_tag` match and no credential-refresh policy could see — and the generated client had no schema to decode the middleware's own refusal with. Both ends now carry the same union, so the value arrives as `{ _tag: 'Unauthenticated' }` on the failure channel over `POST /rpc` and over the WebSocket, and a gRPC surface maps it to `UNAUTHENTICATED` rather than `FAILED_PRECONDITION`. Measured under `voltro dev` and `voltro serve` with a validly signed, expired JWT driven through the real client over the socket.
+- **`voltro build` walks an api app's module closure once, not once per handler file** — `@voltro/cli`
+
+  Each api artefact (`apiEntry.js`, the serve bundle) is preceded by a closure-discovery pass that only reads esbuild's metafile. It used to hand esbuild every discovery file as its own entry point, and without code splitting esbuild links every entry point separately, each on its own copy of the module graph, all at once. On a synthetic api app of 6,747 modules (4,514 handler files) that probe alone peaked at 4.3 GiB in the esbuild service — ten times the bundle it precedes — and it ran twice per build, so the whole build peaked at 5–6 GiB and could be refused by a shared host with less free memory than that. The probe now links one generated entry that imports every discovery file; the closure it finds is the same set. Measured on the same app the build's peak is under 2 GiB (esbuild 1.9 GiB, Node 0.5 GiB), at 3,048 modules 1.0 GiB, at 1,047 modules 0.9 GiB. The build page documents the expectation.
+- **The file-migration `phase` rewrite reaches aliased, held and nested specs** — `@voltro/cli`
+
+  For a project crossing 0.78.0, the `0.78.0/01_file-migration-phase` rewrite now also finds `migration` imported under another name, a spec held in a local `const`, and migrations in subdirectories of `migrations/`. All three are shapes the runner discovers, and the rewrite used to skip them without a word. A spec built outside the call (by a helper, or imported) is not rewritten, because the change would land in code other callers share. Instead the rewrite names it by file and line. `migration()` still refuses a spec without a phase when the file loads.
+- **A subscription refused in-band reaches the error bus and the refresh policy** — `@voltro/client`
+
+  A guard's refusal on a subscription travels in-band — a `{ _tag: 'error' }` event on that one stream, so a sibling subscription on the shared socket is not stalled. The subscription cache set the snapshot's error from it and told nobody else: the api's error bus, which `wireAuthRefresh` and `useOnRpcError` listen on, heard only streams that failed outright. So an expired credential on a read never asked the host for a fresh token and never reached an error reporter. The in-band value is now emitted to the bus with `source: 'subscription'` and `kind: 'handler'`, the same event a failed stream produces.
+- **`voltro support collect` no longer fails on a temporary directory under src/** — `@voltro/cli`
+
+  The conflict-key inventory in `voltro support collect` found its files with a glob that skips dot-directories, then loaded them through a call that walked the directories again. So a temporary directory that an editor, a test run or a build tool creates and removes under `src/` could fail the whole collection with `Directory not found`, and an unreadable dot-directory failed it with `EACCES`. Only the files the glob returned are loaded now. A file removed between the two steps is skipped.
+- **Tenant namespaces on MySQL / MariaDB provision without USE and take the charset** — `@voltro/database`, `@voltro/cli`
+
+  Provisioning a tenant namespace on the mysql family emitted `USE <database>` followed by unqualified DDL. MySQL 8.4 refuses `USE` in the prepared protocol (errno 1295), so under `tenancy.isolation: 'namespace'` no tenant could be provisioned on MySQL at all; on MariaDB the `USE` outlived its transaction on the pooled connection, which then served its next unqualified statement in the tenant database. The tenant DDL is now database-qualified, as the store's namespace view already was. The declared store charset reaches the tenant too: a new tenant database is created with it as its default and its tables carry it. A tenant provisioned before the declaration is named per namespace by `voltro db plan` and `voltro doctor` rather than silently left as it was.
+- **`voltro update` moves the `@voltro/*` pins in `pnpm-workspace.yaml` too** — `@voltro/cli`
+
+  `voltro update` used to bump only the package.json files. A pnpm workspace that also names framework versions in `pnpm-workspace.yaml` was left behind in two ways. `overrides:` entries held the tree on the old release. And `minimumReleaseAgeExclude:` entries (`'@voltro/<pkg>@<version>'`, which admit a release younger than pnpm's release-age window) went stale, so pnpm refused the new release for that whole window. Both blocks now move with the bump. An entry moves only when it names exactly the version being left; an entry at any other version is printed as `kept`. A block written as a flow list is named rather than rewritten. The packages named there count for `--wait`, and the file is restored along with the package.json files when an install fails before anything lands.
+- **`voltro update --wait` waits up to 45 minutes, longer than a release holds** — `@voltro/cli`
+
+  `voltro update --wait` polls the registry until every package it bumps is published at the target version, `@voltro/dashboard` included. It used to give up after 20 minutes. A release, though, holds `latest` for up to 30 minutes after its other packages finish uploading while `@voltro/dashboard` is still being built. So an update that started polling at the first upload could fail after a release that went on to complete normally. The ceiling is now 45 minutes, which covers the release's hold plus its upload phase. The update still reports the late packages while it waits, and on timeout it still restores the bumps byte for byte.
+
+---
+
 ## [0.78.0] — 2026-09-22
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -24,6 +24,7 @@ import { DataStore } from '@voltro/database';
 import { DeclaredAccess } from '@voltro/protocol';
 import { DialectId } from '@voltro/database';
 import { DialectReplicationAdapter } from '@voltro/database';
+import { Duplex } from 'node:stream';
 import { Duration } from 'effect';
 import { Effect } from 'effect';
 import { EventDeliverySemantics } from '@voltro/protocol';
@@ -44,6 +45,7 @@ import { HttpRequestInterceptor } from '@voltro/protocol';
 import { HttpRouteObserver } from '@voltro/protocol';
 import { IdempotencyStore } from '@voltro/protocol';
 import { IdScheme } from '@voltro/database';
+import { IncomingMessage } from 'node:http';
 import { InferInsertRow } from '@voltro/database';
 import { InferRow } from '@voltro/database';
 import { InMemoryMetricExporter } from '@opentelemetry/sdk-metrics';
@@ -94,6 +96,7 @@ import { Schema } from 'effect';
 import { ScopeError } from '@voltro/protocol';
 import { Server } from 'node:http';
 import { ServerOnlyColumnWrite } from '@voltro/protocol';
+import { ServerResponse } from 'node:http';
 import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { spawn } from 'node:child_process';
 import { SqlClient } from '@effect/sql';
@@ -868,6 +871,23 @@ export declare interface AnalyticsTopEntry {
     readonly value: number;
 }
 
+/**
+ * Answer one probe.
+ *
+ * A THROWN readiness check is `not-ready`, not a 500: an app's own probe
+ * throwing is exactly the state the probe exists to report, and a 500 would be
+ * read by some ingress configurations as an error page rather than a failed
+ * check.
+ *
+ * `startup` answers as JSON when the boot path can describe its phase (every
+ * path that binds the early listener), `503` until the boot finished and `200`
+ * from then on — so a `startupProbe` pointed at it holds liveness back for
+ * exactly as long as the boot takes, and a human reading it sees WHICH step it
+ * is on. A path with no phase to report (the web dev server, whose socket Vite
+ * owns) answers it as the readiness question.
+ */
+export declare const answerProbe: (health: ResolvedHealth, kind: ProbeKind, startup?: () => StartupSnapshot) => Promise<ProbeAnswer>;
+
 /**
  * Answer a `resumeFrom` for this identity. `fromRevision` is the last
  * revision the CLIENT materialised. Only revisions inside
@@ -1670,6 +1690,28 @@ export declare interface BeginOAuthResult {
     readonly state: string;
 }
 
+/**
+ * Bind the app port NOW and answer probes on it until the boot path hands
+ * over. Rejects when the bind fails (`EADDRINUSE`, `EACCES`): a serving
+ * process that cannot hold its port has nothing to do, and the caller
+ * reports the failure the same way it reported a late bind failure before.
+ */
+export declare const bindBootListener: (opts: BindBootListenerOptions) => Promise<BootListener>;
+
+export declare interface BindBootListenerOptions {
+    readonly port: number;
+    /** Absent → wildcard (dual-stack `::` on Linux), the production default and
+     *  what the rpc listener binds. */
+    readonly host?: string;
+    /** The app's `health` block — the prefix and the app's own answers. */
+    readonly health?: HealthConfigInput;
+    /** Deterministic "now" for `elapsedMs`; tests inject. */
+    readonly now?: () => number;
+    readonly log?: {
+        readonly info: (message: string, fields?: Record<string, unknown>) => void;
+    };
+}
+
 /** Exported for the backpressure suite — the production caller is `bindSubscription`. */
 export declare const bindComputedUntyped: (computed: ComputedQuery, dispatcher: Dispatcher, context: RuntimeContext, label: string, 
 /** Tunables override (tests); production reads the process-wide slot. */
@@ -1847,11 +1889,51 @@ export declare const bindSubscriptionUntyped: (descriptor: QueryDescriptor, disp
 
 export declare const BOOT_REFUSAL_NAME = "VoltroBootRefusal";
 
+export declare interface BootListener {
+    /** The bound server — the ONE socket this process serves on. */
+    readonly server: Server;
+    /** The port actually bound (differs from the requested one for `port: 0`). */
+    readonly port: number;
+    readonly state: BootState;
+    /** Advance the phase; the next probe reflects it immediately. */
+    readonly set: (patch: Partial<Omit<BootState, 'startedAt'>>) => void;
+    /** Boot complete — the phase alone, never the dependency ping. */
+    readonly isReady: () => boolean;
+    /** Hand over the real handlers. Consulted only once the phase is `ready`
+     *  (or `draining`); until then every non-probe request answers 503. */
+    readonly delegate: (to: BootListenerDelegate) => void;
+    /** The dependency probe readiness consults once ready — a DB `SELECT 1`.
+     *  Installed by the boot path when its store exists, which is after the
+     *  bind; an app-declared `health.readiness` replaces the whole check. */
+    readonly setDependencyPing: (ping: () => Promise<boolean>) => void;
+    /** Close the socket. Resolves once node reports the listener closed. */
+    readonly close: () => Promise<void>;
+}
+
+/** The real handlers, once the boot path has them. */
+export declare interface BootListenerDelegate {
+    readonly request: (request: IncomingMessage, response: ServerResponse) => void;
+    readonly upgrade: (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
+}
+
+export declare type BootPhase = 'booting' | 'migrating' | 'ready' | 'draining' | 'error';
+
 /** An error the boot path raised on purpose. The launcher prints its message
  *  once and exits 1 instead of degrading to a fallback path or printing a
  *  stack. */
 export declare const bootRefusal: (message: string) => Error;
 
+export declare interface BootState {
+    readonly phase: BootPhase;
+    /** Epoch ms when the listener bound — the base of `elapsedMs`. */
+    readonly startedAt: number;
+    /** Declared table count, set when a migrate phase begins, so a watcher can
+     *  gauge how much schema work a slow boot is doing. */
+    readonly tablesTotal?: number;
+    /** Present only in `error` — the boot failure message. */
+    readonly error?: string;
+}
+
 export declare interface BrandedScheduleDefinition extends ScheduleDefinition {
     readonly [SCHEDULE_BRAND]: true;
 }
@@ -5508,6 +5590,37 @@ export declare const hashUnitInterval: (s: string) => number;
 /** How much longer than `keepAliveTimeout` the headers deadline runs. */
 export declare const HEADERS_TIMEOUT_MARGIN_MS = 5000;
 
+/** The `health` block of `app.config.ts`. Every field optional. */
+export declare interface HealthConfigInput {
+    /**
+     * Path prefix for the probes. Default `/internal`, giving
+     * `/internal/liveness`, `/internal/readiness` and `/internal/startup`.
+     *
+     * Move it when your app owns a route there — two segments collide sooner than
+     * you would think, and on a web app the ROUTE wins today.
+     */
+    readonly path?: string;
+    /**
+     * "Is the process up at all" — restart me if not. Default: reaching this code
+     * IS the answer, so `true`.
+     *
+     * Keep it cheap and keep it independent of dependencies. A liveness probe that
+     * consults a database restarts pods when the database is slow, which is the
+     * one thing that makes an outage worse.
+     */
+    readonly liveness?: () => boolean | Promise<boolean>;
+    /**
+     * "Should I receive traffic" — pulled from the Service endpoints until this
+     * says yes. Default: the boot-complete flag the boot path supplies.
+     *
+     * This is the one worth writing yourself, and the answers genuinely differ: a
+     * dependency ping for an api, "the catalog is loaded" for an app that renders
+     * from one, `true` for a display that must keep showing its last frame while
+     * its upstream wobbles.
+     */
+    readonly readiness?: () => boolean | Promise<boolean>;
+}
+
 /** 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>;
 
@@ -7844,6 +7957,25 @@ export declare interface PreviewStore {
     transactional: <T>(fn: (tx: unknown) => Promise<T>) => Promise<T>;
 }
 
+export declare interface ProbeAnswer {
+    readonly status: number;
+    readonly body: string;
+    /** `text/plain` for the two yes/no probes; `application/json` for a startup
+     *  snapshot. */
+    readonly contentType: 'text/plain' | 'application/json';
+}
+
+/**
+ * Which probe a URL is, or `undefined`.
+ *
+ * `undefined` for anything else — including a path UNDER the prefix that names
+ * no probe. `/internal/nonsense` must not answer, or the surface stops being a
+ * set of three known questions.
+ */
+export declare const probeFor: (health: ResolvedHealth, cleanUrl: string) => ProbeKind | undefined;
+
+export declare type ProbeKind = 'liveness' | 'readiness' | 'startup';
+
 /** 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. */
@@ -9211,6 +9343,12 @@ export declare interface ResolvedDevice {
  */
 export declare const resolveDependentTables: (descriptor: QueryDescriptor) => ReadonlySet<string>;
 
+export declare interface ResolvedHealth {
+    readonly path: string;
+    readonly liveness: () => boolean | Promise<boolean>;
+    readonly readiness: () => boolean | Promise<boolean>;
+}
+
 export declare interface ResolvedReactiveConfig {
     readonly deliveryConcurrency: number;
     readonly rawReadTrackingLimit: number;
@@ -9258,6 +9396,16 @@ export declare interface ResolvedWorkflowCallerContext extends WorkflowCallerCon
     readonly rowFilter: RowFilterScope;
 }
 
+/**
+ * Resolve the app's health block against the boot path's own readiness flag.
+ *
+ * `isReady` is what the boot knows and the app cannot: the server is listening
+ * and the modules are loaded. An app-supplied `readiness` REPLACES it — the app
+ * is the more specific authority, and an app that wants to answer `true` while
+ * its upstream is down must be able to.
+ */
+export declare const resolveHealth: (config: HealthConfigInput | undefined, isReady: () => boolean) => ResolvedHealth;
+
 export declare const resolveKeepAlive: (config: KeepAliveConfig | null | undefined) => KeepAliveTimeouts;
 
 /**
@@ -9914,22 +10062,19 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
      */
     readonly pluginHttpInterceptor?: HttpRequestInterceptor;
     /**
-     * K8s health-probe surface for the API serve path. When supplied, the
-     * server answers `GET /internal/liveness` (always 200 `ok` — the process is
-     * up) and `GET /internal/readiness` (200 `ready` once `isReady()` is true
-     * AND the optional `ping()` dependency probe resolves truthy; 503 otherwise).
-     * Handled BEFORE the plugin interceptor + router, so a rate-limit/geo-block
-     * shield can never 503 a probe and a dead DB can't hide behind routing.
-     * Absent → the endpoints 404 (dev has no probes). `voltro serve` supplies it.
-     */
-    readonly healthCheck?: {
-        /** True once boot completed and the pod should receive traffic. */
-        readonly isReady: () => boolean;
-        /** Optional dependency probe (e.g. a DB `SELECT 1`). A `false` return or a
-         *  rejection flips readiness to 503 — so a pod whose DB connection died
-         *  stops taking traffic instead of erroring every request. */
-        readonly ping?: () => Promise<boolean>;
-    };
+     * The early listener (`bindBootListener`) that already holds the app port.
+     *
+     * Every serving command binds one as the first thing it does once it knows
+     * its port, so `/internal/…` answers from the first moment of the process
+     * and everything else gets `503 + Retry-After` until the boot path flips it
+     * to `ready`. This server's handlers are then reached THROUGH it, on the same
+     * socket: the platform never listens itself (`PlatformHandlerHost` below).
+     *
+     * Absent → this call binds `port`/`host` itself, with no probe surface — the
+     * shape a test harness wants when it boots a bare rpc listener. A boot path
+     * never omits it; `earlyListenerParity.test.ts` reads them.
+     */
+    readonly listener?: BootListener;
     /**
      * Max body size (bytes) accepted on the buffered `POST /rpc` JSON endpoint. A
      * JSON rpc mutation/action/query envelope is never legitimately large, so an
@@ -11280,6 +11425,20 @@ export declare interface StartupContext {
 /** The default export shape every `*.startup.ts` must provide. */
 export declare type StartupFn = (ctx: StartupContext) => void | Promise<void>;
 
+/**
+ * What `/internal/startup` reports when the boot path keeps a phase — the
+ * early listener's state (`bootListener.ts`). `ready` is the boot flag alone,
+ * never the dependency ping: a startup probe asks whether the boot FINISHED,
+ * and a database that wobbles afterwards is readiness's question.
+ */
+export declare interface StartupSnapshot {
+    readonly phase: string;
+    readonly ready: boolean;
+    readonly elapsedMs: number;
+    readonly tablesTotal?: number;
+    readonly error?: string;
+}
+
 /**
  * Write (or replace) the calling subject's credential, encrypted.
  *