@voltro/runtime 0.79.1 → 0.80.0

package/CHANGELOG.md

@@ -39,6 +39,85 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.80.0] — 2026-09-24
+
+### ⚠ BREAKING
+
+- **The inspect stream's replica selection is decided before the response** — `@voltro/runtime`, `@voltro/voltro`
+
+  `InspectStream.select` returns `Effect<InspectStreamSelection | undefined>` instead of a `Stream`, where `InspectStreamSelection` is either `{ kind: 'stream', stream }` or `{ kind: 'refused', status, body }`. A stream response is committed as `200` from its first byte, so a refusal can only be expressed before it starts. The option is wired by `voltro dev`, `voltro serve` and `voltro start`; code that passes its own `inspectStream` to `startRpcServer` wraps its stream in `Effect.succeed({ kind: 'stream', stream })`. `voltro update` lists every line that sets `inspectStream`.
+- **`JiraService.listBoards` finds boards by project, name and type** — `@voltro/plugin-atlassian`
+
+  Every board method of `JiraService` took a board id, so a board picker had nothing to list and people looked ids up in Jira by hand. `listBoards({ projectKeyOrId?, name?, type? })` calls `GET /rest/agile/1.0/board`, follows the pages itself, and returns each board as `{ id, name, type, location? }`, where `location` names the project the board is located in. `name` is a contains match on Jira's side. It runs on the caller's own credentials like every other method, so a board the caller may not see is not listed. The break is for code that provides the service itself: a test stub written against the full `JiraServiceShape` needs the new method.
+
+  **`voltro update` carries you across this** — codemod `0.80.0/03_jira-service-lists-boards`. 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.80.0).
+- **A loader has `ctx.query` in the browser, so a clicked-to page keeps its title** — `@voltro/web`, `@voltro/client`, `@voltro/protocol`, `@voltro/cli`
+
+  `ctx.query` was `undefined` when a loader ran in the browser. A page whose loader resolved an entity's name for `meta` therefore showed it in the title on a fresh load and dropped it after a click inside the app: the same URL, two titles. The browser loader now gets `ctx.query` too. It reads through the page's own api client, so it carries the visitor's session. A query resolves to its first snapshot, as on the server, and an in-band error rejects with the typed error on `voltroError`. A newer navigation that replaces the one in flight now aborts the loader's `signal`, as `LoaderContext.signal` always promised, and that closes the read. What changes for existing code is a check on `query`'s presence: `if (query)`, `query ? … : …` and `query?.(…)` now take the resolving branch in the browser too. Branch on `ctx.isServer` where the check meant "this is the server". `voltro update` lists every such line in your pages and layouts.
+
+  Bundle size: the browser read path adds 1.6 KB gz to a web app's first load (194.6 → 196.2 KB gz on the framework's zero-procedure fixture). Because the router now imports the api client, the shared chunk that carries the Effect runtime is emitted as `router-*.js` instead of `index-*.js`; the bytes moved between the two files, they did not grow.
+- **No framework loading spinner; useNavigation() exposes navigation state** — `@voltro/web`
+
+  `FrameworkBoot` mounted a corner `NavigationIndicator` in every web app, in development and production, so a spinner appeared at the bottom right of pages whose design never included one — also in apps that had switched the devtools off. It is no longer mounted, and `NavigationIndicator` is removed from `@voltro/web`. In development the devtools button shows navigation progress as before. To build your own cue, read the new `useNavigation()` hook: `state` is `'loading'` while the router keeps the current page on screen for a target whose page module or loaders are not ready, and `pendingPathname` names that target; a server render is always `'idle'`. For a reconnecting api use `useConnectionStatus(apiName)` from `@voltro/client`. `voltro update` lists every file that still imports `NavigationIndicator`.
+- **DB_MAX_CONNECTIONS is what the whole process holds, not the size of each pool** — `@voltro/cli`, `@voltro/workflow`, `@voltro/database`
+
+  Every framework user of the database opened its own pool: the store, the plugin bind context, the workflow runtime, aggregates, analytics, and the boot steps that migrate or check the schema. Each was sized by `DB_MAX_CONNECTIONS`, so one process could hold several times the number its boot line printed. Measured on postgres at `DB_MAX_CONNECTIONS=3`: the line promised 4 and the database saw 8 connections from `voltro dev` and from `voltro serve`. Two pods budgeted at 5 against a pooler of 15 both failed to acquire in the same second.
+
+  The pools were built by dialect-independent code, and the repair is measured the same way on every dialect: under boot and a burst of concurrent requests, postgres, mariadb, mysql and mssql each hold exactly what the line prints.
+
+  In `voltro dev` and `voltro serve` they now share one pool per database target, so the boot line's number is what the process holds. Short-lived commands such as `voltro data restore` keep their own pool, because they close it to get fresh sessions. A value tuned per pool buys fewer connections in total. Read replicas, a separate migration URL (`DB_DIRECT_URL` / `DB_MIGRATE_URL`), a provisioned tenant's database and pools your own code builds stay separate.
+
+  The workflow runtime needs 3 connections at once (2 with `VOLTRO_WORKFLOW_RUNNER_STORAGE=memory`). Below that the boot now refuses and names the number; it used to wait out the acquire timeout and exit on `Failed to acquire connection`. `sqlPoolCapacity` is exported from `@voltro/database/sql` beside `registerSqlPoolCapacity`, an addition.
+
+  **`voltro update` carries you across this** — codemod `0.80.0/01_db-max-connections-is-the-process-budget`. 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.80.0).
+
+### Added
+
+- **security.clientAddressHeader reads a proxy's single-address header** — `@voltro/runtime`, `@voltro/cli`
+
+  `security.clientAddressHeader` (env `VOLTRO_CLIENT_ADDRESS_HEADER`) names a header a trusted proxy sets to the client's address, such as `cf-connecting-ip` or `x-real-ip`. It is believed only from a peer covered by `security.trustedProxies` and only when it holds one valid IP; otherwise `x-forwarded-for` applies as before. Naming a header without declaring a trusted proxy refuses the boot.
+- **Rate-limit rules can key on the caller's address** — `@voltro/plugin-ratelimit`, `@voltro/protocol`, `@voltro/runtime`, `@voltro/cli`
+
+  A rule can now use `by: 'ip'`, one bucket per client address. Before sign-in every caller is the same anonymous subject, so `'subject'` put them all in one bucket and one client could use up a sign-in or invite endpoint for everyone. The address is the one the listener resolves through `security.trustedProxies`, and plugin interceptors receive it as `RpcInterceptorContext.remoteAddr` on WebSocket, `POST /rpc` and `publicApi` REST calls; REST handlers get it as `RestRouteContext.remoteAddr`. A client cannot set it. Calls that do not arrive over the network share one `unknown` bucket. `KeyBy` gains the `'ip'` member: every value that type-checked before still does; only code that exhaustively switches over `KeyBy` needs the new case.
+
+### Changed
+
+- **Server-side rpc calls carry the visitor's address** — `@voltro/cli`
+
+  A loader's `ctx.query`, a page's `preload`, and the no-JavaScript form post now send `x-forwarded-for` to the api: the chain the request arrived with plus the address that delivered it to the web server. An api whose `security.trustedProxies` covers the web tier therefore rate-limits and audits these calls per visitor instead of counting every visitor against the web server. An api that trusts no proxy ignores the header, so its behaviour is unchanged. A visitor-written `x-forwarded-for` is never forwarded on its own.
+
+### Fixed
+
+- **The boot's database connection line names the dialect in use** — `@voltro/cli`
+
+  A database configured with `DB_HOST` and friends was logged as `db connection: postgres://…` whatever the dialect, so a SQL Server or MySQL connection read as a postgres one. The line now starts with the dialect's name.
+- **The dashboard's live streams share one browser connection** — `@voltro/cli`
+
+  The DevTools dashboard opened one event-stream connection per app. Over HTTP/1.1 a browser holds at most six connections per origin across all tabs, so with six apps — or three in two tabs — the logs and overview pages held every connection the dashboard had, and each later request waited indefinitely: a click on another page changed the URL, kept the old page on screen and left the navigation indicator spinning. Every stream a page holds now travels on one connection: the page posts its targets, each with its own app bearer, to `/api/dashboard/proxy/streams`, and `voltro dev` and `voltro start` fan the apps in behind it, each reconnecting on its own backoff. `/api/dashboard/proxy/stream` is removed; `@voltro/dashboard` of the same release uses the new route.
+- **`meta` keeps the rendered language after hydration without a locale cookie** — `@voltro/web`, `@voltro/cli`
+
+  In the browser, `meta` received the `voltro:locale` cookie's locale and otherwise a fixed `'en'`. A first visit carries no cookie, so the server rendered the title in the language it negotiated (`Accept-Language`, else `defaultLocale`), and after hydration the tab switched to English. `meta` now falls back to the locale the server rendered the document with, which it stamps on `<html lang>`, and the cookie still wins when a language switch has written one. A page `voltro serve` answers with the unrendered shell (a page the prerender did not produce) declared `lang="en"` in every app, and the client took that for the server's choice. The shell now declares the app's `defaultLocale`, or its first declared locale.
+- **The first `voltro dev` on a fresh SQL Server database boots with CDC on** — `@voltro/sql-mssql`
+
+  With `changeStrategy: 'cdc'`, the default, the Change Tracking reader started before auto-migrate created the schema and enabled tracking on tables that did not exist yet. The boot died on `Failed to execute statement`, so every new project on SQL Server failed its first `voltro dev`. The same database booted once with `CDC=0` worked afterwards.
+
+  The reader now enables tracking on the tables that exist and picks up the rest on the poll that first finds them, reading each from its own tracking floor. A table the migration creates during the boot is tracked from then on. `ensureChangeTracking` resolves to the tables it could not enable yet.
+- **Replica observations of ended processes are deleted after a day** — `@voltro/cli`, `@voltro/runtime`, `@voltro/database`
+
+  `_voltro_replica_observations` had no retention. A replica deletes its own rows on a graceful shutdown, but a process that crashed or was killed left them behind, and a replica ID that does not survive a restart — `dev-<pid>` under `voltro dev`, a pod replaced under a new name — never overwrites them. Every such row stayed listed as `departed` in each fleet read indefinitely. The retention sweep now deletes rows not rewritten for 24 hours on both boot paths and every dialect; live replicas rewrite theirs every 30 seconds. `VOLTRO_REPLICA_OBSERVATIONS_TTL_HOURS` changes the window, with a floor of one hour, and the boot line lists the policy with the others.
+- **A live stream for an ended replica is refused instead of reconnecting forever** — `@voltro/cli`, `@voltro/devtools-ui`
+
+  `/_voltro/inspect/stream?replica=<id>` now resolves the named replica and verifies its handshake before it answers, with the same refusals as a read: `404` for an unknown ID or one without a reachable address (no request leaves the process), `504` for a peer that does not accept the connection, `502` for a peer that answers with another process's feed. Previously the API answered `200 text/event-stream` first and found the missing peer inside the body, so a dashboard still naming a process from before a restart received a stream that closed at once, reconnected on backoff indefinitely, and left a `Fiber terminated with an unhandled error` in the target's log on every attempt. The replica selector in the local and Cloud dashboards now also removes a selected replica once the fleet no longer lists it — the process ended and its ID never answers again — names the removed IDs, and returns an emptied selection to All replicas. A replica that is only unavailable (stale, without a reachable address, or expected by the fleet without an answer) stays selected.
+- **A controlled workflow start without an acknowledgement returns its receipt** — `@voltro/runtime`, `@voltro/voltro`, `@voltro/workflow`, `@voltro/cli`, `@voltro/protocol`
+
+  When the engine dispatch of a start with flow controls failed without a definite answer, such as an exhausted database pool or an acknowledgement lost after the engine took the run, `start()` threw `Submission … remains unacknowledged`. The submission stayed durable and recovery retried it, so a caller that reported the failure could see the run happen anyway.
+
+  `start()` now returns `status: 'queued'` with `deferral.mode: 'unacknowledged'`, and `handle.id` is the receipt recovery binds to the resulting run. `start(…, { wait: true })` and `run(…)` follow it. A definite rejection still throws.
+
+  `WorkflowAdmissionOutcome`'s `accept` may now resolve to a `WorkflowQueuedAdmission` as well as an execution ID. Custom admission adapters only produce that outcome; the framework's facade is what calls `accept`, so adapter code keeps compiling. `isUnacknowledgedSubmission` is exported from `@voltro/workflow`.
+
+---
+
 ## [0.79.1] — 2026-09-24
 
 ### Changed

package/dist/index.d.ts

@@ -2245,6 +2245,8 @@ export declare interface ClientAddressInput {
     readonly socketAddress: string | undefined;
     /** Raw `x-forwarded-for` header, if present. */
     readonly xForwardedFor: string | undefined;
+    /** Raw value of `config.clientAddressHeader`, if the request carried it. */
+    readonly clientAddressHeader?: string | undefined;
     readonly config: TrustedProxyConfig;
 }
 
@@ -5453,13 +5455,12 @@ export declare const forbiddenColumnsForSubject: (tableName: string, subject: Su
 export declare const forgetCredential: (store: VaultStore, connectionId: string, subjectId: string) => Promise<boolean>;
 
 /**
- * Drop rows for a replica GENERATION that is gone.
+ * Drop this replica's rows on a graceful shutdown.
  *
- * Not a retention sweep — the table has no history to age out. This removes
- * the row of a process that restarted, because the replica's NEW row is
- * written under the same `(replicaId, kind)` key and the old generation is
- * simply overwritten. What this handles is a replica that went away for good
- * (a scale-down), whose row would otherwise be counted forever.
+ * A restart under the same replica ID overwrites its row anyway; this handles
+ * a replica that goes away for good (a scale-down). It cannot run for a process
+ * that crashed or was killed — those rows are aged out by the retention sweep
+ * on `writtenAt`, which every live replica refreshes each publish interval.
  */
 export declare const forgetReplicaObservations: (store: DataStore, replicaId: string) => Promise<void>;
 
@@ -5862,7 +5863,10 @@ export { InspectStore }
  */
 export declare interface InspectStream {
     readonly replicaId?: string;
-    readonly select?: (url: string, headers: Readonly<Record<string, string>>) => Stream.Stream<Uint8Array, unknown> | undefined;
+    /** Undefined serves this process's own feed. Decided before the response
+     *  starts: an event stream is a 200 from its first byte, so a refusal found
+     *  inside the body could only reach the client as a feed that closes. */
+    readonly select?: (url: string, headers: Readonly<Record<string, string>>) => Effect.Effect<InspectStreamSelection | undefined>;
     /** Same shape as the inspect auth resolver — returns ok or reason. */
     readonly authorize: (headers: Readonly<Record<string, string>>) => {
         readonly ok: true;
@@ -5884,6 +5888,16 @@ export declare interface InspectStream {
     readonly keepAliveMs?: number;
 }
 
+/** A named process's feed, or the reasoned refusal to open it. */
+export declare type InspectStreamSelection = {
+    readonly kind: 'stream';
+    readonly stream: Stream.Stream<Uint8Array>;
+} | {
+    readonly kind: 'refused';
+    readonly status: number;
+    readonly body: unknown;
+};
+
 export { inspectWorkflow }
 
 export declare const installApprovalGate: (gate: ApprovalGateApi) => void;
@@ -9425,6 +9439,14 @@ export declare const resolveReactiveConfig: (config?: ReactiveConfigInput | unde
 
 export declare const resolveRedirectUri: (definition: OAuth2ConnectionDefinition, publicUrl: string) => string;
 
+/** The client address of a request, read from its headers per `config`. The
+ *  one call every listener makes — which headers matter is decided here. */
+export declare const resolveRequestClientAddress: (input: {
+    readonly socketAddress: string | undefined;
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    readonly config: TrustedProxyConfig;
+}) => string | undefined;
+
 /**
  * Whether the request reached the app over TLS.
  *
@@ -9513,7 +9535,7 @@ export declare const resolveTransactionSubject: (subject: Subject, tenantId: str
  * rebuild; the config field exists because it is a tunable and tunables belong
  * in `app.config.ts`.
  */
-export declare const resolveTrustedProxies: (configured?: ReadonlyArray<string> | undefined, env?: Readonly<Record<string, string | undefined>>) => TrustedProxyConfig;
+export declare const resolveTrustedProxies: (configured?: ReadonlyArray<string> | undefined, env?: Readonly<Record<string, string | undefined>>, configuredHeader?: string | undefined) => TrustedProxyConfig;
 
 /** Per-resource-type policy. `actions` maps an action to the relations that
  *  grant it (ANY-of). `implies` is relation implication (owner ⇒ editor ⇒
@@ -9944,6 +9966,9 @@ export declare interface RowHistoryEntry {
     readonly traceId?: string | null;
 }
 
+/** Internal header name. Its value is meaningless without the process mark. */
+export declare const RPC_CLIENT_ADDRESS_HEADER = "x-voltro-client-address";
+
 /** 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. */
@@ -9951,6 +9976,11 @@ export declare interface RpcConnection {
     readonly id: string;
     readonly transport: 'websocket' | 'http';
     readonly signal: AbortSignal;
+    /** The caller's address, resolved by the rpc listener through
+     *  `security.trustedProxies` / `clientAddressHeader` — the same value its
+     *  per-IP shield counts. Absent when the call did not arrive through that
+     *  listener (an internal invocation, an embedder's own transport). */
+    readonly remoteAddr?: string;
 }
 
 export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
@@ -10250,6 +10280,9 @@ export declare interface RuntimeContext {
     /** Server-owned transport identity and close signal. Not authentication;
      * session membership remains an application's explicit access decision. */
     readonly connection?: RpcConnection;
+    /** `connection.remoteAddr`, lifted so the serve pipeline — which also serves
+     *  REST calls that have no connection — reads one field for both. */
+    readonly remoteAddr?: string;
 }
 
 /**
@@ -11099,6 +11132,11 @@ export declare interface ServeRequestContext {
     readonly surface?: 'rest';
     /** The descriptor's `publicApi` spec, on a projected call. */
     readonly publicApi?: PublicApiSpec;
+    /** The caller's address as the listener resolved it through
+     *  `security.trustedProxies` — carried to the plugin interceptor so a
+     *  per-endpoint limit can count per client. Absent for calls that did not
+     *  arrive over the network. */
+    readonly remoteAddr?: string;
     /**
      * Caller-side cancellation (the gRPC deadline / client-cancel path).
      * Honoured at the ONE place the executor effect runs to a promise, so an
@@ -11163,6 +11201,8 @@ export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown,
     /** See `ServeRequestContext.surface` — present on a REST-projected call. */
     readonly surface?: 'rest';
     readonly publicApi?: PublicApiSpec;
+    /** See `ServeRequestContext.remoteAddr`. */
+    readonly remoteAddr?: string;
 }) => Effect.Effect<unknown, unknown, never>;
 
 /** The published tracer, or `undefined` when tracing is off / no server booted. */
@@ -12182,6 +12222,12 @@ export declare interface TransportSecurityOptions {
      *  CIDRs, the presets `loopback` / `private`, a hop count (`['2']`), or
      *  `['*']` to trust any peer. Env override: `VOLTRO_TRUSTED_PROXIES`. */
     readonly trustedProxies?: ReadonlyArray<string>;
+    /** A header a trusted proxy SETS to the client's single address
+     *  (`'cf-connecting-ip'`, `'x-real-ip'`). Believed only from a peer
+     *  `trustedProxies` covers, and only when it holds one valid IP; otherwise
+     *  the `x-forwarded-for` chain applies. Env override:
+     *  `VOLTRO_CLIENT_ADDRESS_HEADER`. */
+    readonly clientAddressHeader?: string;
     /** Security response headers. Env override: `VOLTRO_SECURITY_HEADERS`
      *  (`off|default|strict`), plus `VOLTRO_CSP` / `VOLTRO_CSP_HTML` /
      *  `VOLTRO_HSTS`. */
@@ -12227,6 +12273,10 @@ export declare interface TrustedProxyConfig {
     readonly trustAll: boolean;
     /** Hop count (express's numeric `trust proxy`). `undefined` → not hop mode. */
     readonly hops?: number;
+    /** Lower-cased name of a single-address header a trusted proxy SETS
+     *  (`cf-connecting-ip`, `x-real-ip`). Preferred over the forwarded chain when
+     *  it holds one valid IP; `x-forwarded-for` remains the fallback. */
+    readonly clientAddressHeader?: string;
 }
 
 /**
@@ -12806,15 +12856,12 @@ export declare type WorkflowAdmissionOutcome = {
      *  that filled up on this arrival. */
     readonly payload: unknown;
     /** Dispatch the resident submission and return its durably acknowledged
-     * execution ID. Recovery owns retries; callers must not execute separately. */
-    readonly accept: () => Promise<string>;
-} | {
-    readonly kind: 'queued';
-    readonly receiptId: string;
-    readonly intentId: string;
-    readonly mode: string;
-    readonly dueAt: number;
-} | {
+     * execution ID — or, when the dispatch went unacknowledged, the receipt
+     * recovery completes it under (`mode: 'unacknowledged'`). That start may
+     * still run, so it is neither an execution ID nor a failure. Recovery owns
+     * retries; callers must not execute separately. */
+    readonly accept: () => Promise<string | WorkflowQueuedAdmission>;
+} | WorkflowQueuedAdmission | {
     readonly kind: 'dropped';
     readonly retryAfterMs: number;
 } | {
@@ -13118,6 +13165,15 @@ export declare class WorkflowPayloadError extends Error {
     missingFields: ReadonlyArray<string>, detail: string);
 }
 
+/** A start the caller follows through its receipt instead of an execution ID. */
+export declare interface WorkflowQueuedAdmission {
+    readonly kind: 'queued';
+    readonly receiptId: string;
+    readonly intentId: string;
+    readonly mode: string;
+    readonly dueAt: number;
+}
+
 export declare interface WorkflowQueuedControlOptions {
     readonly callerContext?: WorkflowCallerContext;
     readonly cause?: NonNullable<WorkflowControlRequest['cause']>;