@voltro/testing 0.80.0 → 0.81.0

package/CHANGELOG.md

@@ -39,6 +39,96 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.81.0] — 2026-09-25
+
+### ⚠ BREAKING
+
+- **The compose baseline gives each api app its own database** — `@voltro/cli`
+
+  `voltro baseline sync` now gives every api app in a `project.json` its own database, login and migrate service. The primary api (the app named `api`, else the first api app) keeps the project's database; every other api app connects to `<project>_<app>` with `<PROJECT>_<APP>_DB_PASSWORD`, and each api app gets `VOLTRO_API_<APP>_URL` for its sibling api apps by service name. Migration: sync, move each secondary app's own tables into its new database, and set the new password variables in production.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/03_compose-baseline-one-database-per-api-app`. 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.81.0).
+- **A crashed process blocks its idempotency key for 30 seconds, not a day** — `@voltro/protocol`, `@voltro/runtime`, `@voltro/client`, `@voltro/voltro`
+
+  A process that died inside an idempotent mutation left its key `in_flight` for the whole replay window — 24 hours by default — so every retry with that key was refused with `MutationInFlight` (REST: `409`), including the retry of a workflow step whose callee had simply restarted. A running claim now holds on a 30-second lease that the server renews while the handler runs, over the socket and on REST alike; a dead process stops renewing, and the next send with the key takes over and runs the mutation once — the dead call's transaction never committed. A completed response still replays for the whole window. A takeover is conditional on the claim still being stale, so a claim renewed a moment earlier is never taken from a live handler. `ctx.apis` calls treat `MutationInFlight` as no answer yet: the same key is re-sent when the callee says, until it answers or the call's deadline passes (then `ApiUnavailable`). BREAKING only for an app that implements `IdempotencyStore` itself: `claim` takes the lease, and `renew(scope, key, now)` is required.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/05_idempotency-store-renews-its-lease`. 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.81.0).
+- **Each api app owns its database schema; a second app on it refuses to boot** — `@voltro/database`, `@voltro/cli`
+
+  The first boot that migrates a database records which app owns it (`_voltro_schema_owner`). A different app booting against the same database and schema now refuses — naming both apps — before it plans anything, under `voltro dev`, `voltro serve` and `VOLTRO_AUTO_MIGRATE=0` alike; `voltro db apply` refuses the same way and claims an unclaimed database — as its first write, after every other check has passed, so an apply refused for drift or a blocked operation leaves the database as it found it. `voltro data` export and import treat the owner row as the deployment's own: it never travels to another database. Two apps on one schema each diffed it against their own declarations and planned to drop the other's tables. Migration: give every api app its own database (`DB_URL`) or schema (`DB_SCHEMA`) and reach the other app's data through `apis:` and `service:` procedures; `voltro doctor` lists api apps of a project that resolve the same target. `voltro db claim --yes` hands a schema to a RENAMED app.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/01_one-database-per-app`. 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.81.0).
+- **ReactionDefinition is the union of the table form and the query form** — `@voltro/runtime`, `@voltro/voltro`
+
+  With reactions that watch a live query's rows, `ReactionDefinition` is now `EdgeReactionDefinition | LevelReactionDefinition`. Code holding a value of that type and reading a member only the table form has — `watch.table`, `watch.on`, `guards.dedupeKey`, `when(event)` — no longer compiles: type it `EdgeReactionDefinition`, or narrow with `isLevelReaction(def)` first. `defineReaction({ … })` is unchanged: an object literal resolves to its own form, and a value typed as the union is still accepted and validated by its `watch`.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/04_reaction-definition-is-a-union`. 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.81.0).
+- **Store calls on a table the app does not declare now fail** — `@voltro/runtime`, `@voltro/cli`
+
+  Every store verb — in handlers, startups, schedules and workflows — now fails with `UndeclaredTableAccess` on a table that is neither declared by the app (its `table()`s, a plugin's `extendSchema.tables`) nor framework-owned (`_voltro_*`), in every environment. A string table name used to reach another app's table past its guards, audit and tenant rules. `store.raw(sql)` is unchanged. Migration: call the owning app through `apis:` and a `service:` procedure, or declare the table if it is this app's own.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/02_store-refuses-undeclared-tables`. 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.81.0).
+
+### Added
+
+- **A plugin can bring app-shaped building blocks with `sources`** — `@voltro/protocol`, `@voltro/cli`
+
+  `definePlugin({ sources: fileURLToPath(new URL('./app', import.meta.url)) })` points at a directory of the same file conventions an app uses — queries and mutations with their executors, `schema.ts` tables, `*.workflow.tsx`, `*.cron.tsx`, subscribers, reactions — and every app that installs the plugin discovers them exactly as it discovers its own: the same codegen, browser-safety guard, access gate, migrations, and both boot paths. A reusable building block (a ledger, an audit trail, an approval flow) is shared between apps of a project without copying it; each installing app gets its own copy of the block's tables in its own database. `voltro build` keys the block's modules by plugin and path, so the serve bundle finds them wherever the block lives after a deploy.
+- **A reaction can watch the rows of a live query, including another app's** — `@voltro/runtime`, `@voltro/cli`
+
+  `defineReaction({ watch: { query: 'deployments.pending', api: 'cloud' }, key: (row) => row.id, act: { kind: 'workflow', workflow: 'deploy.run' } })` reacts to every ROW of a live query's current result — the set of open work — instead of to each change of a table. Every delivery is the whole set, so a row that appeared while the reacting process was down, restarting or deploying is acted on when it comes back; nothing is lost. The workflow's `idempotencyKey` makes each row's act exactly-once across every replica, so no claim table is involved and a start that failed is tried again on the next delivery or on `resync` (default 5 minutes). `resync` and `stuckAfter` take milliseconds or a duration from `'30s'` to `'8 days'`. With `api:` the query is another app's `service:` query, subscribed over `ctx.apis` — push without the watched app knowing its watcher; without it, one of this app's own queries, read through the same guards and row filter as its REST projection. A row still in the set long after its workflow started is reported as `stuck` and never restarted. `voltro_reaction_pending`, `voltro_reaction_oldest_seconds` and `voltro_reaction_connected` expose the queue per reaction. The table form (`watch: { table }`) is unchanged; `runReaction` now takes the table form's type, `EdgeReactionDefinition`.
+- **Apps of one project call each other through typed service procedures** — `@voltro/voltro`, `@voltro/protocol`, `@voltro/runtime`, `@voltro/client`, `@voltro/cli`, `@voltro/testing`, `@voltro/workflow`
+
+  An api app can now call another app of the same project, typed, over the socket, without touching its tables. The called app declares `service: { callers: ['worker'] }` on a query, mutation or action and lists the caller under `serviceCallers: { worker: {} }`; codegen emits those procedures into `serviceGroup.generated.ts` and never into the browser's `rpcGroup.generated.ts`. The calling app binds it under `apis: { cloud: { package: '@acme/api' } }` and calls `ctx.apis.cloud.deployments.activate(input)` (Promise) or `.effect(input)` (Effect), with every input, output and typed error inferred from the callee's declarations. A service authenticates with a per-edge credential (`VOLTRO_API_<BINDING>_TOKEN` on the caller, `VOLTRO_SERVICE_CALLER_<CALLER>_TOKEN` on the callee, `_NEXT` for rotation); `voltro dev` derives and mints it into both apps' `.env.local`, production supplies it (`voltro secret generate service`) and a missing one fails boot. A caller name is letters, digits and dashes, at most 56 characters, so its `service:<name>` identity fits an `id()` column. The called app plants an `actors` row for each accepted caller at boot (`service:<name>`, `kind: 'serviceAccount'`), so `audit()`-stamped writes name the calling app instead of failing on the foreign key. A service subject holds no scopes: it reaches exactly the procedures that name it, is refused everywhere else — framework built-ins included — and no user, API key or `admin:full` session reaches a service procedure. A write made inside a workflow step carries an idempotency key derived from the step, so a step retried after a lost reply replays instead of writing twice; an app with `serviceCallers` deduplicates mutations by default. A call without an answer fails with `ApiUnavailable` within a deadline (10 s by default); calls are measured as `voltro_api_call_duration_seconds` and `voltro_api_call_errors_total`. `voltro doctor` reports a caller listed without a procedure, a procedure naming an unlisted caller and a binding the callee does not accept. `@voltro/testing` adds `makeServiceApiMock`, which decodes every input and output through the callee's real schemas.
+
+  `apiSurface: compatible` — the replaced golden lines in `@voltro/protocol` (and the `@voltro/voltro` aggregate re-exporting it) are `AnyCheckSpec` and `DeclaredAccess` gaining the member `ServiceAccessSpec`. Every existing member is unchanged and an app keeps writing the guards it wrote; the framework is the only producer of the new member, which it normalises from `service:`. Only a switch exhaustive over guard specs needs an arm.
+- **startTestApps boots several apps of one project, each service edge wired** — `@voltro/testing`
+
+  `startTestApps({ apps, edges })` from `@voltro/testing` boots the apps of one project as real `voltro` processes (`dev` by default, `serve` with `mode: 'serve'`), each on a free port — every callee before its callers, because a caller imports the contract its callee's codegen writes — and resolves once every app answers `/internal/readiness`; a cycle of edges is refused before anything starts. Every listed edge gets a freshly minted credential written to both ends, under the variables the apps read (`VOLTRO_API_<BINDING>_TOKEN` / `_URL` on the caller, `VOLTRO_SERVICE_CALLER_<CALLER>_TOKEN` on the callee); `apps.token(caller, callee)` returns it so a test can call the callee as the caller. An app that exits or is not ready in time stops the others and the call rejects with its log. Processes rather than one process, because apps with their own tables cannot share one process's table registry.
+- **makeTestApp requests carry the caller's address** — `@voltro/testing`
+
+  A route that reads `ctx.remoteAddr` (a per-client rate limit, an audit field) could not be tested per client: every `makeTestApp` request arrived without an address. A request's options now take `remoteAddr`, the address the connection comes from, defaulting to `127.0.0.1`. The route sees it as `ctx.remoteAddr`, resolved by the function the server's listener uses, and a `publicApi` procedure's plugin interceptors see the same address, as on the server. `makeTestApp({ security: { trustedProxies, clientAddressHeader } })` takes the api's own settings, so a forwarding header is believed in a test exactly when it would be in production.
+
+  `markRestInvocation` takes the request's address as an optional third argument, and `restInvocationOf` returns it beside the spec; both only gain an optional member, so existing calls and reads are unchanged.
+
+### Fixed
+
+- **Codegen removes an rpc group the app no longer has procedures for** — `@voltro/cli`
+
+  An app whose last client-reachable procedure went away — deleted, or marked `internal: true` — kept its `rpcGroup.generated.ts`: codegen reported "no rpc primitives found — nothing to write" and left the old file, a typed contract for procedures the server no longer served. The next `voltro dev` or `voltro codegen` now removes it, as it already removed an empty `serviceGroup.generated.ts` and `apis.generated.ts`. A hand-written file of that name is left alone.
+- **The auto-launched dashboard binds `VOLTRO_DASHBOARD_PORT`** — `@voltro/cli`
+
+  `VOLTRO_DASHBOARD_PORT` was read by `voltro dashboard` only. The dashboard that `voltro dev` and `voltro start` launch on their own — api and web app alike — always came up on `:5179`, and the launcher wrote `5179` into the child's `VOLTRO_DASHBOARD_PORT`, overriding the value the developer had set. The launcher and `voltro dashboard` now resolve the port through one reader: the variable, else `5179`. A value that is not a port (`1..65535`) is refused with a warning naming it instead of silently becoming `5179`.
+- **The db pool boot line counts a connection outside the pool once** — `@voltro/cli`
+
+  With change data capture on, the line read `max=5 … + 1 = 6` and then, separately, `PLUS 1 outside the pool (CDC LISTEN consumer)`, which reads as 7 when the process holds 6. The outside connection is now named once, inside the sum it belongs to: `max=5 per replica (DB_MAX_CONNECTIONS) + 1 outside the pool (CDC LISTEN consumer) = 6 per process`.
+- **A declared `utf8mb4` store reaches the workflow engine's tables** — `@voltro/database`, `@voltro/workflow`, `@voltro/cli`
+
+  `store: { charset: 'utf8mb4' }` converted every table the app declares and left the tables the framework creates without declaring them in the database default: the durable workflow engine's `cluster_*` storage, which holds every workflow call's input and result as JSON text, and the deploy runner's `_voltro_deploys` / `_voltro_migration_ops`. On a `utf8mb3` database a workflow whose input carried an emoji was refused there. Every table the framework creates is now created in the declared charset: the runner's ledgers directly, and the workflow engine's tables by the process that creates them on its first boot, while they are still empty. A workflow table a booting process finds is never rewritten at boot; tables from before the declaration are converted by `voltro db apply` (also when the plan has nothing to do, and with `--plan`) once the deploy has closed and by the `voltro dev` auto-migrate, keeping type, nullability and column CHECKs, and `voltro db plan` lists them beside the plan (under `--json` too, on the log, never in the plan file). The database's own default is left alone. The step only ever widens, and a deploy that fails and is undone never runs it.
+- **The MySQL/MariaDB pool keeps its connections instead of reconnecting** — `@voltro/sql-mysql`
+
+  The driver pool was created with `maxIdle: 0`, so every connection released to it was closed within a second. A process reconnected after each second of quiet: a TCP handshake per burst, plus a TLS one where configured. Measured on MySQL and MariaDB: a query after two quiet seconds ran on a new connection. The pool now keeps the connections it opened, up to the limit.
+- **Workflows started by a reaction or an incoming webhook start again** — `@voltro/cli`
+
+  A workflow started by a `*.reaction.ts` act or an incoming `*.webhook.tsx` was refused with `Workflow placement requires explicit caller identity`, under `voltro dev` and `voltro serve`: neither path named a caller, and placement refuses a start without one. Both now start as the framework itself, placed in the changed row's tenant when it has one.
+- **The first boot on an empty database no longer warns about replica observations** — `@voltro/cli`
+
+  `voltro dev` started publishing this replica's observations before its auto-migrate, so the first write on an empty database hit a table that did not exist yet and printed `could not record this replica's observation — fleet views will report this replica as stale` on the first boot of every new project. The publisher now writes its first observation once the schema is applied — at once on `voltro serve`, whose fingerprint check runs before it — and never when the boot stops earlier.
+- **A 405 on a shared REST path names every method the path serves** — `@voltro/protocol`
+
+  A `DELETE` to a path served by `GET` and `POST` answered `405` with `Allow: POST`: each route refused with its own method, and the last refusal won. `Allow` and the error body's `allow` now list every method declared on the path, `GET, POST`, as the REST documentation already promised.
+- **A large REST surface no longer holds the boot for seconds registering routes** — `@voltro/runtime`, `@voltro/protocol`
+
+  Every REST route used to be mounted for all 34 HTTP methods the router knows, at its path and at its sub-path, and each insert compares itself against every entry already held. A public REST surface of about 1000 procedures therefore held about 34 000 router entries, and building them kept the thread busy for over a second after the port was bound — long enough for a liveness probe to time out. A path is now mounted for exactly the methods its routes declare: the same 1000 procedures hold 4 000 entries. Behaviour is unchanged. A method the path does not declare still reaches its routes and gets the precise `405` with `Allow`, a path nobody declared is still a `404`, and `HEAD` still answers from `GET`. For this, a REST route now declares its real `method` instead of `'*'` and sets the new `PluginHttpRoute.answersOtherMethods: true`. A plugin route that declares one method without that flag never sees another method, as before. A server of your own that mounts `restRoutesToHttpRoutes` output by method must hand the other methods to routes with `answersOtherMethods`, or they become `404` instead of `405`.
+- **The testing guide's tsconfig example no longer sets baseUrl** — `@voltro/cli`
+
+  The `paths` alias example in the testing guide set `"baseUrl": "."`, an option TypeScript 7 removed. It now maps `paths` alone, which resolves against the tsconfig's own directory. `voltro test` still reads a `baseUrl` an older config sets.
+- **voltro update lists a note's code and config lines before prose** — `@voltro/cli`
+
+  A manual note lists the lines it found in code and config first, under `── found in code or config (N lines)`. Lines in Markdown and text files follow in their own `── mentioned in prose (N lines)` block, and a note that matched only prose says `nothing in code or config matched`. Past the lines shown, the rest are named by file with a count instead of a bare `… and N more`. Before, the lines were sorted by path, and 40 lines of documentation hid a Helm env entry, the one line to change. The guide `voltro agents-md` copies into `agent-docs/` is no longer searched. It names every change of a release, so refreshing it made notes report "found" for changes the project never used.
+
+---
+
 ## [0.80.0] — 2026-09-24
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -27,6 +27,7 @@ import { RpcInterceptor } from '@voltro/protocol';
 import { RpcKind } from '@voltro/protocol';
 import { Schema } from 'effect';
 import { Scope } from 'effect';
+import { ServiceApi } from '@voltro/protocol';
 import { Subject } from '@voltro/protocol';
 import { SubscribeContext } from '@voltro/runtime';
 import { SyncLogger } from '@voltro/logger';
@@ -223,6 +224,17 @@ export declare const fixtureRow: (table: TableLike, overrides?: Row) => Row;
  */
 export declare const frozenTime: (at: Date | number | string | MockClock) => Effect.Effect<MockClock, never, Scope.Scope>;
 
+declare type HandlerFor<D> = D extends {
+    readonly input: infer I;
+    readonly output: infer O;
+} ? (input: I extends {
+    readonly Type: infer T;
+} ? T : never) => Promise<O extends {
+    readonly Type: infer T;
+} ? T : never> | (O extends {
+    readonly Type: infer T;
+} ? T : never) : never;
+
 /**
  * What `invoke` resolves to for a handler returning `Result`: an `Effect`'s
  * SUCCESS value, an awaited `Promise`, or the value itself.
@@ -287,6 +299,10 @@ export declare const invoke: <D extends Pick<ProcedureDescriptor, "input">, Resu
 /** Can we open a TCP connection to `host:port` within `timeoutMs`? */
 export declare const isTcpReachable: (target: ReachableTarget) => Promise<boolean>;
 
+export declare const makeServiceApiMock: <P>(descriptors: Readonly<Record<string, MockDescriptor>>, handlers: ServiceApiMockHandlers<P>, options?: {
+    readonly name?: string;
+}) => ServiceApiMock<P>;
+
 /**
  * A `SubscribeContext` typed as the real one.
  *
@@ -361,6 +377,18 @@ export declare interface MakeTestAppOptions {
     /** The api's `publicApi:` config — the REST profile the projections speak,
      *  the same object `app.config.ts` declares. Absent → `'rpc'`. */
     readonly publicApiProfile?: PublicApiProfileConfig;
+    /**
+     * The api's `security` settings that decide the caller's address — the same
+     * fields `app.config.ts` declares. `ctx.remoteAddr` is resolved from a
+     * request's `remoteAddr` and headers through them, by the function the
+     * server's listener calls, so a forwarding header is believed here exactly
+     * when it would be in production. `VOLTRO_TRUSTED_PROXIES` applies as it does
+     * there. Absent → no proxy is trusted.
+     */
+    readonly security?: {
+        readonly trustedProxies?: ReadonlyArray<string>;
+        readonly clientAddressHeader?: string;
+    };
 }
 
 export declare const makeTestContext: <RowFilterCtx = unknown>(options?: MakeTestContextOptions<RowFilterCtx>) => TestContext;
@@ -369,6 +397,13 @@ export declare interface MakeTestContextOptions<RowFilterCtx = unknown> {
     /** The acting subject. Default: anonymous, no tenant. Read it back at
      *  `ctx.request.subject` (the same place a live handler reads it). */
     readonly subject?: Subject;
+    /**
+     * `ctx.apis` — the apps this handler calls. Pass a fake per binding, usually
+     * `makeServiceApiMock<ServiceProcedures>({ … })` from `@voltro/testing`, which
+     * decodes every input and output against the callee's real schemas. Absent →
+     * the empty object, as for an app with no `apis:`.
+     */
+    readonly apis?: AppContext['apis'];
     /** Optional connection fixture, or the actual RuntimeContext.connection from
      * a listener test. Shared by transaction/subject re-scopes, never invented by
      * the harness; omitting it models an internal invocation. */
@@ -517,7 +552,7 @@ export declare interface MakeWorkflowRunnerOptions {
     readonly workflows?: ReadonlyArray<WorkflowEntry>;
 }
 
-export declare const markRestInvocation: (ctx: TestContext, publicApi: PublicApiSpec) => void;
+export declare const markRestInvocation: (ctx: TestContext, publicApi: PublicApiSpec, remoteAddr?: string) => void;
 
 /** Minimal AI mock surface. The full `mockAi({...})` helper is owned by
  *  the AI package (plan 05); typed here as an optional injected interface
@@ -560,6 +595,12 @@ export declare class MockClock {
     uninstall(): void;
 }
 
+declare interface MockDescriptor {
+    readonly kind: string;
+    readonly input: unknown;
+    readonly output: unknown;
+}
+
 export declare class MockLLM {
     private readonly queue;
     readonly calls: MockLLMCall[];
@@ -702,9 +743,19 @@ export declare const reportEngineVersion: (label: string, probe: () => Promise<s
  */
 export declare const resetAfterCommit: (ctx: TestContext) => void;
 
-export declare const restInvocationOf: (ctx: TestContext) => {
+/** A context that is running ONE `publicApi`-projected request — `invoke`
+ *  reads it to put `surface: 'rest'` and the spec on the interceptor meta,
+ *  exactly as the serve pipeline does for a `/v1` call. Set by `makeTestApp`
+ *  on the per-request scoped context; never on the one a test holds. */
+export declare interface RestInvocation {
     readonly publicApi: PublicApiSpec;
-} | undefined;
+    /** The request's resolved address — the serve pipeline hands it to the
+     *  interceptors of a projected call (`projectedRequest`), so a per-address
+     *  limit reads it there and must read it here. */
+    readonly remoteAddr?: string | undefined;
+}
+
+export declare const restInvocationOf: (ctx: TestContext) => RestInvocation | undefined;
 
 export { Row }
 
@@ -752,6 +803,27 @@ export declare const runInStoreTransaction: <T>(ctx: TestContext, work: (txCtx:
  *  `storeForTenant` view). NOT the cross-tenant `system()` below. */
 export declare const serviceAccount: (id: string, options?: TestSubjectOptions) => Subject;
 
+export declare interface ServiceApiMock<P> {
+    /** Pass this as `makeTestContext({ apis: { <name>: mock.api } })`. */
+    readonly api: ServiceApi<P>;
+    /** Every call made, in order — optionally for one tag. */
+    readonly calls: (tag?: keyof P & string) => ReadonlyArray<ServiceApiMockCall>;
+    /** Push a new value to every open subscription of a query. */
+    readonly emit: (tag: keyof P & string, input: unknown, value: unknown) => void;
+}
+
+export declare interface ServiceApiMockCall {
+    readonly tag: string;
+    readonly input: unknown;
+    readonly idempotencyKey: string | undefined;
+}
+
+/** Per tag: what the fake callee answers. A tag with no handler answers
+ *  `ApiUnavailable` — the honest outcome of calling an app that is not there. */
+export declare type ServiceApiMockHandlers<P> = {
+    readonly [K in keyof P]?: HandlerFor<P[K]>;
+};
+
 /**
  * The handler service layer for this context — every registered plugin's
  * `services:` layer, then the app's own `layers:`, merged in that order.
@@ -774,6 +846,45 @@ export declare const serviceAccount: (id: string, options?: TestSubjectOptions)
  */
 export declare const serviceLayerFor: (ctx: TestContext) => Layer.Layer<never, never, never> | undefined;
 
+export declare interface StartedTestApp {
+    readonly name: string;
+    readonly port: number;
+    /** `http://127.0.0.1:<port>` — the app's HTTP origin. */
+    readonly url: string;
+    /** `ws://127.0.0.1:<port>/ws` — the socket a service client connects to. */
+    readonly wsUrl: string;
+    /** Everything the process printed so far. */
+    readonly log: () => string;
+    readonly stop: () => Promise<void>;
+}
+
+export declare interface StartedTestApps<Name extends string> {
+    readonly apps: Readonly<Record<Name, StartedTestApp>>;
+    /** The credential of an edge — what a test presents to call the callee AS the caller. */
+    readonly token: (caller: Name, callee: Name) => string;
+    /** Stops every app; safe to call twice. */
+    readonly stop: () => Promise<void>;
+}
+
+/**
+ * Boot the apps — every callee before its callers — wait until each answers
+ * `/internal/readiness`, and return their ports, logs and edge credentials. A
+ * process that exits or does not become ready in time stops every other one
+ * and rejects with its log.
+ */
+export declare const startTestApps: <Name extends string>(options: StartTestAppsOptions<Name>) => Promise<StartedTestApps<Name>>;
+
+export declare interface StartTestAppsOptions<Name extends string> {
+    readonly apps: Readonly<Record<Name, TestAppSpec>>;
+    readonly edges?: ReadonlyArray<TestAppEdge<Name>>;
+    /** `dev` (codegen, migrations, minted secrets — the default) or `serve`. */
+    readonly mode?: 'dev' | 'serve';
+    /** Path to `voltro.mjs`. Default: `@voltro/cli` as the first app resolves it. */
+    readonly cli?: string;
+    /** How long EACH app may take to answer `/internal/readiness`. Default 5 minutes. */
+    readonly bootTimeoutMs?: number;
+}
+
 /**
  * The CROSS-TENANT machine actor — cron, workflows, backfills. `tenantId` is
  * `null` by construction and the tenant read-scope mixin reads that as "every
@@ -811,6 +922,22 @@ export declare interface TestApp {
     readonly paths: ReadonlyArray<string>;
 }
 
+export declare interface TestAppEdge<Name extends string> {
+    /** The calling app (its `name`). */
+    readonly caller: Name;
+    /** The called app (its `name`). */
+    readonly callee: Name;
+    /** The caller's `apis:` key for the callee. */
+    readonly binding: string;
+}
+
+export declare interface TestAppSpec {
+    /** The app's directory (the one holding `app.config.ts`). */
+    readonly root: string;
+    /** Extra environment for this app — its `DB_URL`, feature flags, … */
+    readonly env?: Readonly<Record<string, string>>;
+}
+
 /** The test context IS an `AppContext` (store + request + cache), plus the
  *  deterministic doubles and the subject/tenant re-scopers. Because it
  *  extends `AppContext`, you can pass it straight into an executor typed
@@ -939,6 +1066,14 @@ export declare interface TestRequestOptions {
      *  `withHeaders`) headers. Names are lowercased, as the transport delivers
      *  them. */
     readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * The address the connection comes from — the socket peer. With no trusted
+     * proxy declared (the default) it is `ctx.remoteAddr`; behind a declared
+     * proxy, `x-forwarded-for` from that peer decides, as on the server.
+     * Defaults to `127.0.0.1`. Two values are two clients, which is how a route
+     * test shows a per-address limit.
+     */
+    readonly remoteAddr?: string;
 }
 
 export declare interface TestResponse {

package/dist/index.js

@@ -1,15 +1,19 @@
 import { AUTO_FILLED_COLUMNS as e, allRegisteredTables as t, changeDelete as n, changeInsert as r, changeSoftDelete as i, changeUpdate as a, clearRelationsRegistry as o, missingRequiredColumns as s, registerRelations as c } from "@voltro/database";
 import { Cause as l, Effect as u, Either as d, Exit as f, Layer as p, Schema as m } from "effect";
-import { SubjectService as h, anonymousSubject as g, checkGuardsEffect as _, composeAuthStrategies as v, composeRpcInterceptors as y, eventRoute as b, systemSubject as x, tenantScopedSubject as ee } from "@voltro/protocol";
-import { EventBus as S, InMemoryDataStore as te, NO_ROW_FILTER as C, appValidation as ne, applyRowFilterToDescriptor as re, clearSystemStoreHandle as ie, getRowFilter as w, getSystemStoreHandle as ae, makeAppAccess as oe, makeConnectionState as se, makeDataLoader as ce, makeEffectStoreLayer as T, makeEventPublisher as le, makeFieldCipher as ue, makeOutboxFacade as de, makeSchemaRegistry as fe, publishEvent as pe, resolveRowFilterScopeFor as me, resolveTransactionSubject as he, runProvidedEffect as E, runWithDeadlockRetry as ge, setFieldCipher as _e, setSystemStoreHandle as D, wrapStoreWithMixinBehaviour as O } from "@voltro/runtime";
-import { installEnvSnapshot as ve } from "@voltro/env";
-import ye from "node:net";
-import { describe as be } from "vitest";
-import { collectPublicApiRoutes as xe, dispatchSharedPath as Se, restRoutesToHttpRoutes as Ce } from "@voltro/protocol/rest";
-import { createLogger as we } from "@voltro/logger";
-import { CurrentWorkflowRunId as Te, inMemoryWorkflowEngineLayer as Ee, makeInMemoryRecorder as De } from "@voltro/workflow";
+import { ApiUnavailable as h, SubjectService as g, anonymousSubject as _, checkGuardsEffect as v, composeAuthStrategies as y, composeRpcInterceptors as b, eventRoute as x, systemSubject as S, tenantScopedSubject as ee } from "@voltro/protocol";
+import { EventBus as te, InMemoryDataStore as ne, NO_ROW_FILTER as C, apiBindingTokenEnv as re, apiBindingUrlEnv as ie, appValidation as ae, applyRowFilterToDescriptor as oe, clearSystemStoreHandle as se, getRowFilter as w, getSystemStoreHandle as ce, makeAppAccess as le, makeConnectionState as ue, makeDataLoader as de, makeEffectStoreLayer as fe, makeEventPublisher as pe, makeFieldCipher as me, makeOutboxFacade as he, makeSchemaRegistry as ge, mintServiceToken as _e, publishEvent as ve, resolveRequestClientAddress as ye, resolveRowFilterScopeFor as be, resolveTransactionSubject as xe, resolveTrustedProxies as Se, runProvidedEffect as T, runWithDeadlockRetry as Ce, serviceCallerTokenEnv as we, setFieldCipher as Te, setSystemStoreHandle as E, wrapStoreWithMixinBehaviour as D } from "@voltro/runtime";
+import { installEnvSnapshot as Ee } from "@voltro/env";
+import O from "node:net";
+import { describe as De } from "vitest";
+import { collectPublicApiRoutes as Oe, dispatchSharedPath as ke, restRoutesToHttpRoutes as Ae } from "@voltro/protocol/rest";
+import { createLogger as je } from "@voltro/logger";
+import { CurrentWorkflowRunId as Me, inMemoryWorkflowEngineLayer as Ne, makeInMemoryRecorder as Pe } from "@voltro/workflow";
+import { spawn as Fe } from "node:child_process";
+import { randomBytes as Ie } from "node:crypto";
+import { createRequire as Le } from "node:module";
+import { dirname as Re, join as ze } from "node:path";
 //#region src/fixtureRow.ts
-var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
+var Be = new Set(e), k = 0, Ve = () => ++k, He = (e, t) => {
 	if (t.oneOf && t.oneOf.length > 0) return t.oneOf[0];
 	if (t.enumValues && t.enumValues.length > 0) return t.enumValues[0];
 	let n = t.unique === !0;
@@ -27,38 +31,38 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		case "date": return /* @__PURE__ */ new Date(0);
 		default: throw Error(`fixtureRow: column '${e}' is a required '${t.type}' with no default, and fixtureRow can't synthesize a safe placeholder for that type. Pass it explicitly: fixtureRow(table, { ${e}: … }).`);
 	}
-}, j = (e, t = {}) => {
+}, A = (e, t = {}) => {
 	let n = {};
-	for (let r of s(e, t)) Oe.has(r) || (n[r] = ke(r, e.fields[r]));
+	for (let r of s(e, t)) Be.has(r) || (n[r] = He(r, e.fields[r]));
 	return {
 		...n,
 		...t
 	};
-}, M = m.decodeUnknownEither(m.DateFromString), Ae = /^\d{4}-\d{2}-\d{2}$/, je = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/, Me = (e, t) => {
-	if (typeof e != "string" || !je.test(e) && !(t === "date" && Ae.test(e))) return !1;
-	let n = e.slice(0, 10), r = M(n);
+}, j = m.decodeUnknownEither(m.DateFromString), Ue = /^\d{4}-\d{2}-\d{2}$/, We = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/, Ge = (e, t) => {
+	if (typeof e != "string" || !We.test(e) && !(t === "date" && Ue.test(e))) return !1;
+	let n = e.slice(0, 10), r = j(n);
 	return d.isRight(r) && Number.isFinite(r.right.getTime()) && r.right.toISOString().slice(0, 10) === n;
-}, Ne = (e, t) => {
+}, Ke = (e, t) => {
 	let n = Object.entries(e.fields).filter(([, e]) => e.type === "timestamp" || e.type === "date");
 	return t.map((t, r) => {
 		let i = { ...t };
 		for (let [a, o] of n) {
 			let n = t[a];
 			if (n == null || n instanceof Date && Number.isFinite(n.getTime())) continue;
-			let s = M(n);
-			if (!Me(n, o.type) || d.isLeft(s) || !Number.isFinite(s.right.getTime())) throw TypeError(`hydrateFixtureRows: table '${e.tableName}', row ${r}, column '${a}' requires a valid Date or ISO date-time with Z or an offset${o.type === "date" ? " (YYYY-MM-DD is also accepted as UTC midnight)" : ""}.`);
+			let s = j(n);
+			if (!Ge(n, o.type) || d.isLeft(s) || !Number.isFinite(s.right.getTime())) throw TypeError(`hydrateFixtureRows: table '${e.tableName}', row ${r}, column '${a}' requires a valid Date or ISO date-time with Z or an offset${o.type === "date" ? " (YYYY-MM-DD is also accepted as UTC midnight)" : ""}.`);
 			i[a] = s.right;
 		}
 		return i;
 	});
-}, Pe = (e) => {
+}, qe = (e) => {
 	let t = {};
-	for (let [n, r] of Object.entries(e)) t[n] = typeof r == "function" ? r(A()) : r;
+	for (let [n, r] of Object.entries(e)) t[n] = typeof r == "function" ? r(Ve()) : r;
 	return t;
-}, Fe = (e) => {
+}, Je = (e) => {
 	for (let [t, n] of Object.entries(e.fields)) if (n.type === "id") return t;
 	return "id";
-}, Ie = async (e, t, n, r, i) => {
+}, Ye = async (e, t, n, r, i) => {
 	let a = {};
 	for (let o of s(t, n)) {
 		let n = t.fields[o];
@@ -66,29 +70,29 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		let s = n.references();
 		if (i.includes(s.tableName)) throw Error(`defineFactory: creating '${t.tableName}' requires '${s.tableName}' via '${o}', and that reference is cyclic (${[...i, s.tableName].join(" → ")}). Insert one side first and pass the id: create(store, { ${o}: existing.id }).`);
 		let c = r[o];
-		a[o] = (c === void 0 ? await N(e, s, {}, {}, [...i, s.tableName]) : await c.create(e, {}))[n.referenceColumn ?? Fe(s)];
+		a[o] = (c === void 0 ? await M(e, s, {}, {}, [...i, s.tableName]) : await c.create(e, {}))[n.referenceColumn ?? Je(s)];
 	}
 	return a;
-}, N = async (e, t, n, r, i) => {
+}, M = async (e, t, n, r, i) => {
 	let a = {
-		...await Ie(e, t, n, r, i),
+		...await Ye(e, t, n, r, i),
 		...n
 	};
-	return e.insert(t.tableName, j(t, a));
-}, P = (e, t) => typeof e == "function" ? e(t) : e ?? {}, Le = (e, t = {}) => {
+	return e.insert(t.tableName, A(t, a));
+}, N = (e, t) => typeof e == "function" ? e(t) : e ?? {}, Xe = (e, t = {}) => {
 	let n = t.traits ?? {}, r = t.associations ?? {}, i = (t) => {
 		let a = (e = {}) => ({
-			...Pe(t),
+			...qe(t),
 			...e
-		}), o = (t = {}) => j(e, a(t));
+		}), o = (t = {}) => A(e, a(t));
 		return {
 			table: e,
 			build: o,
-			buildList: (e, t) => Array.from({ length: e }, (e, n) => o(P(t, n))),
-			create: (t, n = {}) => N(t, e, a(n), r, [e.tableName]),
+			buildList: (e, t) => Array.from({ length: e }, (e, n) => o(N(t, n))),
+			create: (t, n = {}) => M(t, e, a(n), r, [e.tableName]),
 			createList: async (t, n, i) => {
 				let o = [];
-				for (let s = 0; s < n; s++) o.push(await N(t, e, a(P(i, s)), r, [e.tableName]));
+				for (let s = 0; s < n; s++) o.push(await M(t, e, a(N(i, s)), r, [e.tableName]));
 				return o;
 			},
 			with: (...r) => {
@@ -110,19 +114,19 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		};
 	};
 	return i(t.defaults ?? {});
-}, F = Symbol.for("voltro/testing/mockClock.installed"), I = () => globalThis, Re = (e, t) => new Proxy(e, {
+}, P = Symbol.for("voltro/testing/mockClock.installed"), F = () => globalThis, Ze = (e, t) => new Proxy(e, {
 	construct: (e, n, r) => Reflect.construct(e, n.length === 0 ? [t()] : n, r),
 	apply: () => new e(t()).toString(),
 	get: (e, n, r) => n === "now" ? () => t() : Reflect.get(e, n, r)
-}), L = (e) => {
+}), Qe = (e) => {
 	if (typeof e == "number") return e;
 	let t = e instanceof Date ? e.getTime() : Date.parse(e);
 	if (Number.isNaN(t)) throw Error(`mockClock: cannot read an instant from '${String(e)}'`);
 	return t;
-}, R = class {
+}, I = class {
 	currentMs;
 	constructor(e = "2026-01-01T00:00:00Z") {
-		this.currentMs = L(e);
+		this.currentMs = Qe(e);
 	}
 	now() {
 		return this.currentMs;
@@ -131,47 +135,47 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		return new Date(this.currentMs);
 	}
 	advance(e) {
-		this.currentMs += typeof e == "number" ? e : He(e);
+		this.currentMs += typeof e == "number" ? e : nt(e);
 	}
 	set(e) {
-		this.currentMs = L(e);
+		this.currentMs = Qe(e);
 	}
 	get installed() {
-		return I()[F]?.clock === this;
+		return F()[P]?.clock === this;
 	}
 	install() {
-		let e = I(), t = e[F];
+		let e = F(), t = e[P];
 		if (t !== void 0) throw Error("mockClock: global time is already faked" + (t.clock === this ? " by this same clock" : " by another MockClock") + ". Uninstall it before installing again — a nested install restores the outer fake on the way out, which leaves the realm frozen with nothing pointing at why. `withFrozenTime` always restores, including on a throw.");
 		let n = globalThis.Date;
-		return e[F] = {
+		return e[P] = {
 			realDate: n,
 			clock: this
-		}, globalThis.Date = Re(n, () => this.currentMs), () => {
+		}, globalThis.Date = Ze(n, () => this.currentMs), () => {
 			this.uninstall();
 		};
 	}
 	uninstall() {
-		let e = I(), t = e[F];
-		t !== void 0 && t.clock === this && (globalThis.Date = t.realDate, delete e[F]);
+		let e = F(), t = e[P];
+		t !== void 0 && t.clock === this && (globalThis.Date = t.realDate, delete e[P]);
 	}
-}, ze = (e) => typeof e == "object" && !!e && typeof e.then == "function", Be = (e, t) => {
-	let n = e instanceof R ? e : new R(e);
+}, $e = (e) => typeof e == "object" && !!e && typeof e.then == "function", et = (e, t) => {
+	let n = e instanceof I ? e : new I(e);
 	n.install();
 	let r = !1;
 	try {
 		let e = t(n);
-		return ze(e) ? (r = !0, e.then((e) => (n.uninstall(), e), (e) => {
+		return $e(e) ? (r = !0, e.then((e) => (n.uninstall(), e), (e) => {
 			throw n.uninstall(), e;
 		})) : e;
 	} finally {
 		r || n.uninstall();
 	}
-}, Ve = (e) => u.acquireRelease(u.sync(() => {
-	let t = e instanceof R ? e : new R(e);
+}, tt = (e) => u.acquireRelease(u.sync(() => {
+	let t = e instanceof I ? e : new I(e);
 	return t.install(), t;
 }), (e) => u.sync(() => {
 	e.uninstall();
-})), He = (e) => {
+})), nt = (e) => {
 	let t = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/.exec(e);
 	if (!t) throw Error(`mockClock: cannot parse duration '${e}'`);
 	let n = Number(t[1]), r = t[2];
@@ -183,7 +187,7 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		case "d": return n * 864e5;
 		default: throw Error(`mockClock: unknown unit '${r}'`);
 	}
-}, z = class {
+}, L = class {
 	emitted = [];
 	async emit(e, t) {
 		let n = typeof e == "string" ? e : e.id ?? e.event ?? "(unnamed event)";
@@ -202,14 +206,14 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 	clear() {
 		this.emitted.length = 0;
 	}
-}, B = (e = {}) => {
-	let t = e.tenantId ?? null, n = new S({
+}, R = (e = {}) => {
+	let t = e.tenantId ?? null, n = new te({
 		origin: e.origin ?? "test",
 		...e.ringSize === void 0 ? {} : { ringSize: e.ringSize }
 	});
 	return {
 		publish: async (e, r, i) => {
-			let a = await u.runPromise(u.either(pe({
+			let a = await u.runPromise(u.either(ve({
 				bus: n,
 				tenantId: t
 			}, e, r, i)));
@@ -258,7 +262,7 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		},
 		skipSerials: (e, r, i, a) => {
 			let o = a?.tenantId ?? t, s = {
-				route: b(o, e.name, r),
+				route: x(o, e.name, r),
 				event: e.name,
 				origin: "test-gap",
 				n: i + 1,
@@ -272,7 +276,7 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 			n.clear();
 		}
 	};
-}, V = class {
+}, z = class {
 	queue;
 	calls = [];
 	constructor(e) {
@@ -287,38 +291,41 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 	remaining() {
 		return this.queue.length;
 	}
-}, Ue = (e) => e, H = "00000000000000000000000000000000", U = /* @__PURE__ */ new WeakMap(), W = /* @__PURE__ */ new WeakMap(), We = (e, t) => {
-	let n = W.get(e);
+}, rt = (e) => e, B = "00000000000000000000000000000000", V = /* @__PURE__ */ new WeakMap(), H = /* @__PURE__ */ new WeakMap(), it = (e, t) => {
+	let n = H.get(e);
 	if (n === void 0) throw Error("withRpcConnection requires a context created by makeTestContext");
 	return n(t);
-}, G = /* @__PURE__ */ new WeakMap(), K = /* @__PURE__ */ new WeakMap(), q = /* @__PURE__ */ new WeakMap(), J = (e) => q.get(e) ?? [], Y = /* @__PURE__ */ new WeakMap(), X = (e, t) => {
-	Y.set(e, { publicApi: t });
-}, Ge = (e) => Y.get(e), Ke = /* @__PURE__ */ new WeakMap(), qe = (e, t) => {
-	let n = q.get(e) ?? [], r = t === "mutation" ? "interceptMutation" : t === "query" ? "interceptQuery" : "interceptAction", i = [];
+}, U = /* @__PURE__ */ new WeakMap(), W = /* @__PURE__ */ new WeakMap(), G = /* @__PURE__ */ new WeakMap(), K = (e) => G.get(e) ?? [], q = /* @__PURE__ */ new WeakMap(), J = (e, t, n) => {
+	q.set(e, {
+		publicApi: t,
+		...n === void 0 ? {} : { remoteAddr: n }
+	});
+}, Y = (e) => q.get(e), X = /* @__PURE__ */ new WeakMap(), at = (e, t) => {
+	let n = G.get(e) ?? [], r = t === "mutation" ? "interceptMutation" : t === "query" ? "interceptQuery" : "interceptAction", i = [];
 	for (let e of n) {
 		let t = e[r];
 		typeof t == "function" && i.push(t);
 	}
-	return y(i);
-}, Je = (e) => {
-	let t = (q.get(e) ?? []).map((e) => e.services).filter((e) => e !== void 0), n = Ke.get(e) ?? [], r = [...t, ...n];
+	return b(i);
+}, ot = (e) => {
+	let t = (G.get(e) ?? []).map((e) => e.services).filter((e) => e !== void 0), n = X.get(e) ?? [], r = [...t, ...n];
 	if (r.length !== 0) return p.mergeAll(...r);
-}, Ye = (e) => {
-	let t = G.get(e);
+}, st = (e) => {
+	let t = U.get(e);
 	t !== void 0 && (t.length = 0);
 }, Z = async (e) => {
-	let t = G.get(e);
+	let t = U.get(e);
 	if (t === void 0 || t.length === 0) return;
 	let n = [...t];
 	t.length = 0;
 	for (let e of n) await e();
-}, Xe = (e) => K.get(e) ?? [], Ze = async (e, t) => {
-	let n = U.get(e);
+}, ct = (e) => W.get(e) ?? [], lt = async (e, t) => {
+	let n = V.get(e);
 	return n === void 0 ? e.store.transactional(async (n) => t({
 		...e,
 		store: n
 	})) : n(t);
-}, Qe = (e) => {
+}, ut = (e) => {
 	let t = /* @__PURE__ */ new Map(), n = /* @__PURE__ */ new Map(), r = (n) => {
 		let r = t.get(n);
 		return r === void 0 ? !1 : r.expiresAt !== null && r.expiresAt <= e() ? (t.delete(n), !1) : !0;
@@ -357,7 +364,7 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 			return i(e, o, n.ttlMs, n.tags), o;
 		}
 	};
-}, $e = (e) => {
+}, dt = (e) => {
 	let t = /* @__PURE__ */ new Map(), n = (n) => {
 		let r = t.get(n);
 		return r === void 0 ? !1 : r.expiresAt !== null && r.expiresAt <= e() ? (t.delete(n), !1) : !0;
@@ -385,47 +392,47 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 			t.clear();
 		}
 	};
-}, et = async (e, t) => {
-	let n = ae();
-	D(e);
+}, ft = async (e, t) => {
+	let n = ce();
+	E(e);
 	try {
 		return await t();
 	} finally {
-		n === void 0 ? ie() : D(n);
+		n === void 0 ? se() : E(n);
 	}
-}, tt = /* @__PURE__ */ new Set(), nt = (e) => {
-	tt.has(e) || (tt.add(e), console.warn(e));
-}, rt = (e, t, n) => {
-	let r = it, i;
+}, pt = /* @__PURE__ */ new Set(), mt = (e) => {
+	pt.has(e) || (pt.add(e), console.warn(e));
+}, ht = (e, t, n) => {
+	let r = gt, i;
 	return () => {
 		let a = t ?? w();
-		return t !== void 0 && w() !== void 0 && t !== w() && nt("[voltro:testing] this test passes `rowFilter:` while a DIFFERENT filter is registered via `setRowFilter`. The option wins, so this test does not exercise your app's registration. Drop `rowFilter:` to run the real process-global one."), (i === void 0 || a !== r) && (r = a, i = et(n, () => E(me(a, e, (e) => {
+		return t !== void 0 && w() !== void 0 && t !== w() && mt("[voltro:testing] this test passes `rowFilter:` while a DIFFERENT filter is registered via `setRowFilter`. The option wins, so this test does not exercise your app's registration. Drop `rowFilter:` to run the real process-global one."), (i === void 0 || a !== r) && (r = a, i = ft(n, () => T(be(a, e, (e) => {
 			console.error("[voltro:testing] row filter failed to load — reads refused for this subject", e);
 		})))), i;
 	};
-}, it = Symbol("unresolved"), at = (e, t) => new Proxy(e, { get: (e, n) => {
-	if (n === "query") return async (n) => e.query(re(await t(), n));
+}, gt = Symbol("unresolved"), Q = (e, t) => new Proxy(e, { get: (e, n) => {
+	if (n === "query") return async (n) => e.query(oe(await t(), n));
 	let r = Reflect.get(e, n, e);
 	return typeof r == "function" ? r.bind(e) : r;
-} }), ot = (e = {}) => {
-	if (ve({
+} }), _t = (e = {}) => {
+	if (Ee({
 		...process.env,
 		...e.env ?? {}
-	}), e.fieldEncryptionKey !== void 0 && _e(ue(e.fieldEncryptionKey)), e.relations !== void 0) {
+	}), e.fieldEncryptionKey !== void 0 && Te(me(e.fieldEncryptionKey)), e.relations !== void 0) {
 		o();
 		for (let t of e.relations) c(t);
 	}
-	let n = e.tables ?? t(), r = fe(n), i = new te(e.store ?? {}), a = {
+	let n = e.tables ?? t(), r = ge(n), i = new ne(e.store ?? {}), a = {
 		dataStore: i,
 		schemaRegistry: r
 	};
-	D(a);
-	let s = new R(e.clockStart), l = new z(), u = B(), d = new V(e.llmResponses ?? []), f = Qe(() => s.now()), p = $e(() => s.now()), m = (t, n, o = i, c, h = !1) => {
+	E(a);
+	let s = new I(e.clockStart), l = new L(), u = R(), d = new z(e.llmResponses ?? []), f = ut(() => s.now()), p = dt(() => s.now()), m = (t, n, o = i, c, h = !1) => {
 		let g = {
 			subject: t,
-			traceId: H,
+			traceId: B,
 			...n === void 0 ? {} : { connection: n }
-		}, _ = c?.queued ?? [], v = c?.nudges ?? [], y = le({
+		}, _ = c?.queued ?? [], v = c?.nudges ?? [], y = pe({
 			bus: u.bus,
 			tenantId: t.tenantId ?? null,
 			...o === i ? {} : { deferToCommit: (e) => {
@@ -433,9 +440,10 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 					e();
 				});
 			} }
-		}), b = ce({ store: o }), x = h ? async () => C : rt(t, e.rowFilter, a), S = {
+		}), b = de({ store: o }), x = h ? async () => C : ht(t, e.rowFilter, a), S = {
+			apis: e.apis ?? Object.freeze({}),
 			transaction: async (e, r) => {
-				let a = he(t, r?.tenantId, o !== i);
+				let a = xe(t, r?.tenantId, o !== i);
 				if (a !== t) return m(a, n, i, void 0, !0).transaction(e);
 				if (o !== i) return e(S);
 				let s, c = await o.transactional(async (r) => {
@@ -445,7 +453,7 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 					}, h), a = await e(i);
 					return s = i, a;
 				});
-				return s !== void 0 && (await Z(s), v.push(...Xe(s))), c;
+				return s !== void 0 && (await Z(s), v.push(...ct(s))), c;
 			},
 			clock: s,
 			webhooks: l,
@@ -454,29 +462,29 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 			llm: d,
 			...e.ai === void 0 ? {} : { ai: e.ai },
 			request: g,
-			...n === void 0 ? {} : { connectionState: se(n, o === i ? void 0 : (e) => {
+			...n === void 0 ? {} : { connectionState: ue(n, o === i ? void 0 : (e) => {
 				_.push(e);
 			}) },
-			validation: ne,
-			access: oe(t),
+			validation: ae,
+			access: le(t),
 			cache: f,
 			kv: p,
-			store: O(at(o, x), {
+			store: D(Q(o, x), {
 				subject: t,
 				schemaRegistry: r,
 				rowFilter: C
 			}),
-			storeForTenant: (e) => O(at(o, x), {
+			storeForTenant: (e) => D(Q(o, x), {
 				subject: ee(t, e),
 				schemaRegistry: r,
 				rowFilter: C
 			}),
-			outbox: de({
+			outbox: he({
 				store: o,
 				subject: t,
-				traceId: H,
+				traceId: B,
 				nudge: () => {
-					v.push(H);
+					v.push(B);
 				},
 				afterCommit: (e) => {
 					_.push(e);
@@ -507,37 +515,37 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 				nudges: v
 			})
 		};
-		return G.set(S, _), W.set(S, (e) => m(t, e, o, {
+		return U.set(S, _), H.set(S, (e) => m(t, e, o, {
 			queued: _,
 			nudges: v
-		})), K.set(S, v), q.set(S, e.plugins ?? []), Ke.set(S, e.layers ?? []), U.set(S, (e) => o.transactional((r) => e(m(t, n, r, {
+		})), W.set(S, v), G.set(S, e.plugins ?? []), X.set(S, e.layers ?? []), V.set(S, (e) => o.transactional((r) => e(m(t, n, r, {
 			queued: _,
 			nudges: v
 		})))), S;
 	};
-	return m(e.subject ?? g(null), e.connection);
-}, st = (e, t) => {
-	let n = Je(t);
-	return (n === void 0 ? e : u.provide(e, n)).pipe(u.provide(T(t.store)), u.provideService(h, t.request.subject));
-}, ct = async (e, t, n, r) => {
+	return m(e.subject ?? _(null), e.connection);
+}, vt = (e, t) => {
+	let n = ot(t);
+	return (n === void 0 ? e : u.provide(e, n)).pipe(u.provide(fe(t.store)), u.provideService(g, t.request.subject));
+}, yt = async (e, t, n, r) => {
 	let i = e.input, a = await m.decodeUnknownPromise(i)(n), o = e.kind, s = async (e) => {
 		let n = t(a, e);
-		return u.isEffect(n) ? E(st(n, e)) : n;
+		return u.isEffect(n) ? T(vt(n, e)) : n;
 	}, c = async () => {
 		let t = e.guards;
 		if (t !== void 0 && t.length > 0) {
-			let e = await u.runPromise(_(r.request.subject, t, a));
+			let e = await u.runPromise(v(r.request.subject, t, a));
 			if (e !== null) throw e;
 		}
 		if (o !== "mutation") return s(r);
-		let n = await ge(async () => Ze(r, async (e) => (Ye(r), s(e))), { delay: () => Promise.resolve() });
+		let n = await Ce(async () => lt(r, async (e) => (st(r), s(e))), { delay: () => Promise.resolve() });
 		return await Z(r), n;
-	}, d = o === "mutation" || o === "query" || o === "action" ? o : void 0, p = d === void 0 ? void 0 : qe(r, d);
+	}, d = o === "mutation" || o === "query" || o === "action" ? o : void 0, p = d === void 0 ? void 0 : at(r, d);
 	if (p === void 0 || d === void 0) return await c();
 	let h = u.tryPromise({
 		try: () => c(),
 		catch: (e) => e
-	}), g = Ge(r), v = p(h, {
+	}), g = Y(r), _ = p(h, {
 		tag: e.name ?? "",
 		kind: d,
 		input: a,
@@ -547,16 +555,17 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		...g === void 0 ? {} : {
 			surface: "rest",
 			publicApi: g.publicApi
-		}
-	}), y = await u.runPromiseExit(v);
+		},
+		...g?.remoteAddr === void 0 ? {} : { remoteAddr: g.remoteAddr }
+	}), y = await u.runPromiseExit(_);
 	if (f.isSuccess(y)) return y.value;
 	throw l.squash(y.cause);
-}, lt = (e) => new Promise((t) => {
-	let n = new ye.Socket(), r = (e) => {
+}, bt = (e) => new Promise((t) => {
+	let n = new O.Socket(), r = (e) => {
 		clearTimeout(i), n.destroy(), t(e);
 	}, i = setTimeout(() => r(!1), e.timeoutMs ?? 750);
 	n.once("connect", () => r(!0)), n.once("error", () => r(!1)), n.connect(e.port, e.host);
-}), ut = async (e, t, n, r) => {
+}), xt = async (e, t, n, r) => {
 	if (typeof t != "string" || typeof n != "function" || typeof r != "function") throw TypeError(`describeIfAvailable('${e}', ...): expected (label, dependency, probe, suite) — got dependency: ${typeof t}, probe: ${typeof n}, suite: ${typeof r}. Three arguments means the suite body is being used as the probe: it would run at file scope, unconditionally, and the skip would silently do nothing.`);
 	let i = !1;
 	try {
@@ -564,21 +573,21 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 	} catch {
 		i = !1;
 	}
-	be.skipIf(!i)(i ? e : `${e} [SKIPPED: needs ${t}]`, r);
-}, dt = async (e, t, n) => {
-	await ut(e, `${t.name} at ${t.host}:${t.port}`, () => lt(t), n);
-}, ft = async (e, t) => {
+	De.skipIf(!i)(i ? e : `${e} [SKIPPED: needs ${t}]`, r);
+}, St = async (e, t, n) => {
+	await xt(e, `${t.name} at ${t.host}:${t.port}`, () => bt(t), n);
+}, Ct = async (e, t) => {
 	try {
 		let n = await t();
 		n !== void 0 && n !== "" && console.log(`[engine] ${e}: ${n}`);
 	} catch {}
-}, pt = "test-tenant", Q = (e, t, n) => ({
+}, wt = "test-tenant", $ = (e, t, n) => ({
 	type: e,
 	id: t,
 	tenantId: n.tenantId ?? "test-tenant",
 	scopes: n.scopes ?? [],
 	...n.metadata === void 0 ? {} : { metadata: n.metadata }
-}), mt = (e, t = {}) => Q("user", e, t), ht = (e, t = {}) => Q("apiKey", e, t), gt = (e, t = {}) => Q("serviceAccount", e, t), _t = (e = null) => g(e), vt = (e = "job:test", t) => t === void 0 ? x(e) : x(e, t), yt = (e) => {
+}), Tt = (e, t = {}) => $("user", e, t), Et = (e, t = {}) => $("apiKey", e, t), Dt = (e, t = {}) => $("serviceAccount", e, t), Ot = (e = null) => _(e), kt = (e = "job:test", t) => t === void 0 ? S(e) : S(e, t), At = "127.0.0.1", jt = (e) => {
 	let t = e.indexOf("?");
 	return t === -1 ? {
 		path: e,
@@ -587,105 +596,110 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		path: e.slice(0, t),
 		query: e.slice(t + 1)
 	};
-}, bt = (e, t) => {
+}, Mt = (e, t) => {
 	let n = e.split("/").filter((e) => e.length > 0), r = t.split("/").filter((e) => e.length > 0);
 	return n.length === r.length && n.every((e, t) => e.startsWith(":") || e === r[t]);
-}, $ = (e) => {
+}, Nt = (e) => {
 	let t = {};
 	for (let [n, r] of Object.entries(e)) t[n.toLowerCase()] = r;
 	return t;
-}, xt = (e) => e === void 0 ? /* @__PURE__ */ new Uint8Array() : new TextEncoder().encode(JSON.stringify(e)), St = (e) => e === void 0 ? "" : typeof e == "string" ? e : new TextDecoder().decode(e), Ct = (e) => {
-	let { ctx: t } = e, n = xe((e.publicApi ?? []).map((e) => ({
+}, Pt = (e) => e === void 0 ? /* @__PURE__ */ new Uint8Array() : new TextEncoder().encode(JSON.stringify(e)), Ft = (e) => e === void 0 ? "" : typeof e == "string" ? e : new TextDecoder().decode(e), It = (e) => {
+	let t = Se(e.security?.trustedProxies, process.env, e.security?.clientAddressHeader), { ctx: n } = e, r = Oe((e.publicApi ?? []).map((e) => ({
 		descriptor: e.descriptor,
-		invoke: (n, r) => t.withSubject(r.subject, (t) => (e.descriptor.publicApi !== void 0 && X(t, e.descriptor.publicApi), ct(e.descriptor, e.handler, n, t)))
+		invoke: (t, r) => n.withSubject(r.subject, (n) => (e.descriptor.publicApi !== void 0 && J(n, e.descriptor.publicApi, r.remoteAddr), yt(e.descriptor, e.handler, t, n)))
 	})), {
-		pluginErrors: J(t).flatMap((e) => e.errorSchemas ?? []),
+		pluginErrors: K(n).flatMap((e) => e.errorSchemas ?? []),
 		...e.publicApiProfile === void 0 ? {} : { profile: e.publicApiProfile }
-	}), r = [...e.restRoutes ?? [], ...n], i = v(e.strategies ?? [], {
+	}), i = [...e.restRoutes ?? [], ...r], a = y(e.strategies ?? [], {
 		...e.anonymousTenantRequired === void 0 ? {} : { anonymousTenantRequired: e.anonymousTenantRequired },
-		getStore: () => t.store
-	}), a = (n, o) => {
-		let s = {
-			store: t.store,
-			buildContext: () => t,
-			resolveSubject: n === void 0 ? async (e) => (await i({
+		getStore: () => n.store
+	}), o = (r, s) => {
+		let c = {
+			store: n.store,
+			buildContext: () => n,
+			resolveSubject: r === void 0 ? async (e) => (await a({
 				headers: e,
 				clientId: -1
-			})).subject : () => n,
+			})).subject : () => r,
 			...e.idempotency === void 0 ? {} : { idempotency: e.idempotency }
-		}, c = Ce(r, s).map((e, t) => ({
-			pattern: r[t].path,
+		}, l = Ae(i, c).map((e, t) => ({
+			pattern: i[t].path,
 			route: e
-		})), l = async (e, n, i = {}) => {
-			let { path: a, query: s } = yt(n), l = c.filter((e) => bt(e.pattern, a)).map((e) => e.route);
-			if (l.length === 0) return {
+		})), u = async (e, r, a = {}) => {
+			let { path: o, query: c } = jt(r), u = l.filter((e) => Mt(e.pattern, o)).map((e) => e.route);
+			if (u.length === 0) return {
 				status: 404,
 				headers: {},
 				text: "",
 				body: {
 					error: "No route mounted for this path",
-					mounted: r.map((e) => e.path)
+					mounted: i.map((e) => e.path)
 				},
 				stream: !1
 			};
-			let u = {
+			let d = {
+				...Nt(s),
+				...Nt(a.headers ?? {})
+			}, f = ye({
+				socketAddress: a.remoteAddr ?? At,
+				headers: d,
+				config: t
+			}), p = {
 				method: e.toUpperCase(),
-				path: a,
-				query: s,
-				headers: {
-					...$(o),
-					...$(i.headers ?? {})
-				},
-				rawBody: xt(i.body),
-				store: t.store
-			}, d = await Se(l, u), f = {};
-			for (let [e, t] of Object.entries(d.headers ?? {})) f[e.toLowerCase()] = t;
-			d.contentType !== void 0 && (f["content-type"] = d.contentType);
-			let p = St(d.body), m = (d.contentType ?? "").includes("json");
+				path: o,
+				query: c,
+				headers: d,
+				rawBody: Pt(a.body),
+				store: n.store,
+				...f === void 0 ? {} : { remoteAddr: f }
+			}, m = await ke(u, p), h = {};
+			for (let [e, t] of Object.entries(m.headers ?? {})) h[e.toLowerCase()] = t;
+			m.contentType !== void 0 && (h["content-type"] = m.contentType);
+			let g = Ft(m.body), _ = (m.contentType ?? "").includes("json");
 			return {
-				status: d.status,
-				headers: f,
-				text: p,
-				body: m && p !== "" ? JSON.parse(p) : void 0,
-				stream: d.stream !== void 0
+				status: m.status,
+				headers: h,
+				text: g,
+				body: _ && g !== "" ? JSON.parse(g) : void 0,
+				stream: m.stream !== void 0
 			};
 		};
 		return {
-			actingAs: (e) => a(e, o),
-			withHeaders: (e) => a(n, {
-				...o,
+			actingAs: (e) => o(e, s),
+			withHeaders: (e) => o(r, {
+				...s,
 				...e
 			}),
-			get: (e, t) => l("GET", e, t ?? {}),
-			delete: (e, t) => l("DELETE", e, t ?? {}),
-			post: (e, t, n) => l("POST", e, {
+			get: (e, t) => u("GET", e, t ?? {}),
+			delete: (e, t) => u("DELETE", e, t ?? {}),
+			post: (e, t, n) => u("POST", e, {
 				...n ?? {},
 				body: t
 			}),
-			put: (e, t, n) => l("PUT", e, {
+			put: (e, t, n) => u("PUT", e, {
 				...n ?? {},
 				body: t
 			}),
-			patch: (e, t, n) => l("PATCH", e, {
+			patch: (e, t, n) => u("PATCH", e, {
 				...n ?? {},
 				body: t
 			}),
-			request: (e, t, n) => l(e, t, n ?? {}),
-			paths: r.map((e) => e.path)
+			request: (e, t, n) => u(e, t, n ?? {}),
+			paths: i.map((e) => e.path)
 		};
 	};
-	return a(void 0, {});
-}, wt = (e = {}) => {
+	return o(void 0, {});
+}, Lt = (e = {}) => {
 	let t = e.id ?? "test", n = e.store ?? new Proxy({}, { get: (e, t) => {
 		throw Error(`makeSubscribeContext: this subscriber reached ctx.store.${String(t)} and the test passed no store. Pass \`{ store: makeTestContext().store }\` so the subscriber and the code under test share one — an empty stand-in would let a read of the wrong table pass.`);
 	} });
 	return {
 		id: t,
-		log: e.log ?? we({ scope: `subscribe:${t}` }),
+		log: e.log ?? je({ scope: `subscribe:${t}` }),
 		store: n,
 		...e.publish === void 0 ? {} : { publish: e.publish }
 	};
-}, Tt = (e) => {
+}, Rt = (e) => {
 	let t = /* @__PURE__ */ new Map();
 	for (let n of e) {
 		let e = t.get(n.stepName);
@@ -711,13 +725,13 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		});
 	}
 	return n.sort((e, t) => e._startedAt - t._startedAt), n.map(({ _startedAt: e, ...t }) => t);
-}, Et = (e) => {
+}, zt = (e) => {
 	let t = e.workflows ?? [], n = /* @__PURE__ */ new Map(), r = 0;
 	return {
 		start: async (i, a) => {
 			let o = t.find((e) => e.workflow.name === i);
 			if (o === void 0) throw Error(`makeWorkflowRunner: no workflow named '${i}' — pass it in makeWorkflowRunner({ ctx, workflows: [{ workflow, execute }] }).`);
-			let s = `wfrun_test_${++r}`, c = De(), l = o.workflow.toLayer(o.execute).pipe(p.provideMerge(Ee)), d = /* @__PURE__ */ new Date(), f = o.workflow.execute(a).pipe(u.locally(Te, s), u.provide(c.layer), u.provide(l)), m = (e.ctx.store === void 0 ? f : u.provide(f, T(e.ctx.store))).pipe(u.either), h = await u.runPromise(m), g = Tt(c.readSteps()), _ = /* @__PURE__ */ new Date(), v;
+			let s = `wfrun_test_${++r}`, c = Pe(), l = o.workflow.toLayer(o.execute).pipe(p.provideMerge(Ne)), d = /* @__PURE__ */ new Date(), f = o.workflow.execute(a).pipe(u.locally(Me, s), u.provide(c.layer), u.provide(l)), m = (e.ctx.store === void 0 ? f : u.provide(f, fe(e.ctx.store))).pipe(u.either), h = await u.runPromise(m), g = Rt(c.readSteps()), _ = /* @__PURE__ */ new Date(), v;
 			if (h._tag === "Right") v = {
 				status: "succeeded",
 				output: h.right,
@@ -757,6 +771,154 @@ var Oe = new Set(e), k = 0, A = () => ++k, ke = (e, t) => {
 		},
 		inspect: async (e) => n.get(e) ?? null
 	};
-}, Dt = 1;
+}, Bt = (e, t, n = {}) => {
+	let r = n.name ?? "mock", i = [], a = /* @__PURE__ */ new Map(), o = (e, t) => `${e}\u0000${JSON.stringify(t)}`, s = async (n, a, o) => {
+		let s = e[n];
+		if (s === void 0) throw Error(`makeServiceApiMock: '${n}' is not a service procedure of this api`);
+		let c = s.input, l = m.encodeUnknownSync(c)(a), u = m.decodeUnknownSync(c)(l);
+		i.push({
+			tag: n,
+			input: u,
+			idempotencyKey: o?.idempotencyKey
+		});
+		let d = t[n];
+		if (d === void 0) throw new h({
+			api: r,
+			tag: n,
+			reason: "transport",
+			message: "no handler in makeServiceApiMock"
+		});
+		let f = await d(u), p = s.output;
+		return m.decodeUnknownSync(p)(m.encodeUnknownSync(p)(f));
+	}, c = (e) => {
+		let t = e.join("."), n = Object.assign((e, n) => s(t, e, n), {
+			effect: (e, n) => u.tryPromise({
+				try: () => s(t, e, n),
+				catch: (e) => e
+			}),
+			subscribe: (e, n) => {
+				let r = o(t, e), i = a.get(r) ?? /* @__PURE__ */ new Set();
+				return a.set(r, i), i.add(n.onValue), s(t, e).then(n.onValue, (e) => n.onError?.(e)), { unsubscribe: () => {
+					i.delete(n.onValue);
+				} };
+			}
+		});
+		return new Proxy(n, { get: (t, n) => {
+			if (typeof n == "string") {
+				if (n === "effect" || n === "subscribe") return t[n];
+				if (n !== "then") return c([...e, n]);
+			}
+		} });
+	};
+	return {
+		api: new Proxy({}, { get: (e, t) => typeof t == "string" && t !== "then" ? c([t]) : void 0 }),
+		calls: (e) => e === void 0 ? [...i] : i.filter((t) => t.tag === e),
+		emit: (t, n, r) => {
+			let i = e[t], s = i === void 0 ? r : m.decodeUnknownSync(i.output)(m.encodeUnknownSync(i.output)(r));
+			for (let e of a.get(o(t, n)) ?? []) e(s);
+		}
+	};
+}, Vt = () => new Promise((e, t) => {
+	let n = O.createServer();
+	n.once("error", t), n.listen(0, "127.0.0.1", () => {
+		let t = n.address(), r = typeof t == "object" && t ? t.port : 0;
+		n.close(() => e(r));
+	});
+}), Ht = async (e) => {
+	try {
+		return (await fetch(`http://127.0.0.1:${e}/internal/readiness`)).status === 200;
+	} catch {
+		return !1;
+	}
+}, Ut = (e) => ze(Re(Le(ze(e, "package.json")).resolve("@voltro/cli/package.json")), "bin", "voltro.mjs"), Wt = 1e4, Gt = (e) => new Promise((t) => {
+	if (e.exitCode !== null || e.signalCode !== null) return t();
+	let n = setTimeout(() => {
+		e.kill("SIGKILL");
+	}, Wt);
+	e.once("exit", () => {
+		clearTimeout(n), t();
+	}), e.kill("SIGTERM");
+}), Kt = async (e) => {
+	let t = Object.keys(e.apps);
+	if (t.length === 0) throw Error("startTestApps: no apps given");
+	let n = e.mode ?? "dev", r = e.bootTimeoutMs ?? 3e5, i = e.cli ?? Ut(e.apps[t[0]].root), a = /* @__PURE__ */ new Map();
+	for (let e of t) a.set(e, await Vt());
+	let o = /* @__PURE__ */ new Map(), s = new Map(t.map((e) => [e, {}]));
+	for (let n of e.edges ?? []) {
+		for (let e of [n.caller, n.callee]) if (!t.includes(e)) throw Error(`startTestApps: edge names '${e}', which is not among the apps (${t.join(", ")})`);
+		let e = _e();
+		o.set(`${n.caller}\u0000${n.callee}`, e), Object.assign(s.get(n.caller), {
+			[re(n.binding)]: e,
+			[ie(n.binding)]: `ws://127.0.0.1:${a.get(n.callee)}/ws`
+		}), Object.assign(s.get(n.callee), { [we(n.caller)]: e });
+	}
+	let c = [], l = /* @__PURE__ */ new Set(), u = (t) => {
+		if (!c.includes(t)) {
+			if (l.has(t)) throw Error(`startTestApps: the edges form a cycle through '${t}' — no app can boot first`);
+			l.add(t);
+			for (let n of e.edges ?? []) n.caller === t && u(n.callee);
+			l.delete(t), c.push(t);
+		}
+	};
+	for (let e of t) u(e);
+	let d = [], f = /* @__PURE__ */ new Map(), p = async () => {
+		await Promise.all(d.map(Gt));
+	};
+	for (let t of c) {
+		let o = e.apps[t], c = a.get(t), l = "", u = Fe(process.execPath, [
+			i,
+			n,
+			...n === "serve" ? ["."] : []
+		], {
+			cwd: o.root,
+			env: {
+				...process.env,
+				...n === "serve" ? { VOLTRO_SESSION_SECRET: Ie(32).toString("base64url") } : {},
+				...o.env,
+				...s.get(t),
+				PORT: String(c)
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		d.push(u), u.stdout?.on("data", (e) => {
+			l += e.toString();
+		}), u.stderr?.on("data", (e) => {
+			l += e.toString();
+		}), u.on("exit", (e, t) => {
+			l += `\n[exited] code=${String(e)} signal=${String(t)}`;
+		});
+		let m = {
+			name: t,
+			port: c,
+			url: `http://127.0.0.1:${c}`,
+			wsUrl: `ws://127.0.0.1:${c}/ws`,
+			log: () => l,
+			stop: () => Gt(u)
+		};
+		f.set(t, m);
+		let h = Date.now() + r;
+		for (; !await Ht(c);) {
+			if (u.exitCode !== null || u.signalCode !== null || Date.now() > h) {
+				await p();
+				let e = u.exitCode !== null || u.signalCode !== null ? "exited before it was ready" : `was not ready within ${r} ms`;
+				throw Error(`startTestApps: '${t}' ${e}\n${m.log().slice(-4e3)}`);
+			}
+			await new Promise((e) => setTimeout(e, 250));
+		}
+	}
+	return {
+		apps: Object.fromEntries(f),
+		token: (e, t) => {
+			let n = o.get(`${e}\u0000${t}`);
+			if (n === void 0) throw Error(`startTestApps: no edge ${e} → ${t}`);
+			return n;
+		},
+		stop: p
+	};
+}, qt = 1;
 //#endregion
-export { R as MockClock, V as MockLLM, z as MockWebhooks, Dt as TESTING_PRESET_VERSION, pt as TEST_TENANT_ID, _t as anonymous, ht as apiKey, n as changeDelete, r as changeInsert, i as changeSoftDelete, a as changeUpdate, Le as defineFactory, ut as describeIfAvailable, dt as describeIfReachable, j as fixtureRow, Ve as frozenTime, Ne as hydrateFixtureRows, ct as invoke, lt as isTcpReachable, wt as makeSubscribeContext, Ct as makeTestApp, ot as makeTestContext, Et as makeWorkflowRunner, X as markRestInvocation, Ue as mockStore, A as nextSequence, Xe as outboxNudgesOf, J as pluginsOf, ft as reportEngineVersion, Ye as resetAfterCommit, Ge as restInvocationOf, qe as rpcInterceptorFor, Z as runAfterCommit, Ze as runInStoreTransaction, gt as serviceAccount, Je as serviceLayerFor, vt as system, B as testEventBus, mt as user, Be as withFrozenTime, We as withRpcConnection };
+export { I as MockClock, z as MockLLM, L as MockWebhooks, qt as TESTING_PRESET_VERSION, wt as TEST_TENANT_ID, Ot as anonymous, Et as apiKey, n as changeDelete, r as changeInsert, i as changeSoftDelete, a as changeUpdate, Xe as defineFactory, xt as describeIfAvailable, St as describeIfReachable, A as fixtureRow, tt as frozenTime, Ke as hydrateFixtureRows, yt as invoke, bt as isTcpReachable, Bt as makeServiceApiMock, Lt as makeSubscribeContext, It as makeTestApp, _t as makeTestContext, zt as makeWorkflowRunner, J as markRestInvocation, rt as mockStore, Ve as nextSequence, ct as outboxNudgesOf, K as pluginsOf, Ct as reportEngineVersion, st as resetAfterCommit, Y as restInvocationOf, at as rpcInterceptorFor, Z as runAfterCommit, lt as runInStoreTransaction, Dt as serviceAccount, ot as serviceLayerFor, Kt as startTestApps, kt as system, R as testEventBus, Tt as user, et as withFrozenTime, it as withRpcConnection };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/testing",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "description": "Test utilities for Voltro apps — deterministic clock, subject and row factories, a handler-level invoke and a request-level app harness, queued LLM responses, scoped subject/tenant runners, and a cross-dialect parity harness.",
   "keywords": [
     "voltro",
@@ -43,16 +43,16 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.80.0",
-    "@voltro/env": "0.80.0",
-    "@voltro/logger": "0.80.0",
-    "@voltro/protocol": "0.80.0",
-    "@voltro/runtime": "0.80.0",
-    "@voltro/workflow": "0.80.0"
+    "@voltro/database": "0.81.0",
+    "@voltro/env": "0.81.0",
+    "@voltro/logger": "0.81.0",
+    "@voltro/protocol": "0.81.0",
+    "@voltro/runtime": "0.81.0",
+    "@voltro/workflow": "0.81.0"
   },
   "peerDependencies": {
     "@effect/sql": "^0.52.1",
-    "@voltro/client": "0.80.0",
+    "@voltro/client": "0.81.0",
     "effect": "^3.22.2",
     "react": "^19.0.0"
   },