@voltro/protocol 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2564 @@
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { Rpc } from '@effect/rpc';
+import { RpcMiddleware } from '@effect/rpc';
+import { Schema } from 'effect';
+import { SqlClient } from '@effect/sql';
+import { Stream } from '@effect/rpc/RpcSchema';
+
+export declare interface ActionProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+    readonly kind: 'action';
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error: Error;
+    /** Opt this action into a public REST endpoint (innovation/11). */
+    readonly publicApi: PublicApiSpec | undefined;
+    /** Opt this action into the auto-synthesized agent toolset (innovation/07). */
+    readonly exposeAsTool: ExposeAsTool | undefined;
+}
+
+export declare const actionToRpc: <Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: ActionProcedureDescriptor<Name, Input, Output, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Output, Schema.Schema.All, never>;
+
+export declare const ADMIN_SCOPE = "admin:full";
+
+export declare const anonymousSubject: (tenantId: string | null) => Subject;
+
+/**
+ * Apply a `RowPatch` to `prev`, producing `next`. Exact inverse of
+ * `diffRows`: `applyRowPatch(prev, diffRows(prev, next))` deep-equals
+ * `next` for adds, removes, replaces, and reorderings.
+ *
+ * Builds an id→row map from prev, applies `add` / `replace` (which set the
+ * id → next row), then materialises the result strictly in the patch's
+ * `order`. A `remove`d id simply isn't in `order`, so it drops out of the
+ * output naturally — no key-type juggling to delete it from the map. Any
+ * id in `order` that the map doesn't resolve (a desync — the client missed
+ * an `add`) is skipped rather than throwing, so one dropped frame degrades
+ * to a slightly stale set instead of a crash.
+ */
+export declare const applyRowPatch: (prev: ReadonlyArray<PatchRow>, patch: RowPatch) => ReadonlyArray<PatchRow>;
+
+/**
+ * Throws `Unauthenticated` when the resolved Subject is anonymous (no
+ * real user identity). Handlers that require a signed-in caller put
+ * this as the first line of their executor:
+ *
+ * ```ts
+ * const execute = async (input, ctx) => {
+ *   assertAuthenticated(ctx.request.subject)
+ *   …
+ * }
+ * ```
+ */
+export declare const assertAuthenticated: (subject: Subject, reason?: string) => void;
+
+/** Optional callback-route mount surface for strategies that handle
+ *  OAuth callbacks. Apps wire these via the framework's HTTP router
+ *  when the strategy declares `mountRoutes`. */
+export declare interface AuthCallbackRouter {
+    readonly get: (path: string, handler: AuthRouteHandler) => void;
+    readonly post: (path: string, handler: AuthRouteHandler) => void;
+}
+
+/**
+ * The framework's per-request auth middleware. Attach to an RpcGroup with
+ * `group.middleware(AuthMiddleware)` to require every call to flow through
+ * an auth resolver before reaching its handler. The application provides
+ * the resolver via `Layer.succeed(AuthMiddleware, AuthMiddleware.of(fn))`,
+ * where `fn` receives `{headers, payload, rpc, clientId}` and returns an
+ * `Effect<Subject>` — typically by inspecting headers / Bearer token and
+ * looking the caller up.
+ *
+ * `provides: SubjectService` means the resolver's return value is placed
+ * into the handler's context tagged as SubjectService; handlers read it
+ * with `yield* SubjectService`. Connections with no headers (or whatever
+ * the resolver requires) can fail the middleware — that becomes a
+ * mutationResult error / error frame for the caller.
+ *
+ * Apps that don't need per-request resolution can skip attaching this
+ * middleware and provide SubjectService directly with a static
+ * `Layer.succeed(SubjectService, anonymousSubject(tenantId))` instead.
+ */
+export declare class AuthMiddleware extends AuthMiddleware_base {
+}
+
+declare const AuthMiddleware_base: RpcMiddleware.TagClass<AuthMiddleware, "@voltro/AuthMiddleware", {
+    readonly provides: typeof SubjectService;
+}>;
+
+export declare type AuthRouteHandler = (req: AuthRouteRequest) => Promise<AuthRouteResponse>;
+
+export declare interface AuthRouteRequest {
+    readonly url: URL;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: () => Promise<string>;
+}
+
+export declare interface AuthRouteResponse {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+
+/** Pluggable auth strategy. Strategies are SYNC-fast on no-match
+ *  (cookie-name lookup) and cache any JWKS / DB roundtrips on match
+ *  so steady-state verification stays CPU-local. */
+export declare interface AuthStrategy {
+    /** Stable id (`'voltro-password'`, `'workos'`, `'kinde'`, …). Used
+     *  in logs + `Subject.metadata.provider`. */
+    readonly id: string;
+    readonly resolve: (input: AuthStrategyInput) => Promise<StrategyResolution> | StrategyResolution;
+}
+
+/** Per-call input the framework hands every strategy. */
+export declare interface AuthStrategyInput {
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    readonly clientId: number;
+}
+
+/** Strategies that need server-side callbacks (OAuth code-exchange,
+ *  magic-link landing, etc.) ALSO export this companion via the
+ *  `routes` factory below. Kept separate from `AuthStrategy.resolve`
+ *  so apps that only need pure JWT-verify strategies don't pay the
+ *  callback-wiring cost. */
+export declare interface AuthStrategyWithCallback extends AuthStrategy {
+    readonly mountRoutes: (router: AuthCallbackRouter) => void;
+}
+
+/**
+ * Decide what to do for an incoming (scope, key) in ONE atomic store call. On
+ * `fresh` the caller runs the handler then calls `finish`/`fail`; on
+ * `replay`/`conflict` it returns immediately without touching the handler.
+ */
+export declare const beginIdempotent: (store: IdempotencyStore, scope: string, key: string, ttlMs: number, now: number) => Promise<IdempotencyOutcome>;
+
+/**
+ * Validate `plugin.framework` (npm-semver range) against the running
+ * voltro version. Returns either `{ ok: true }` or
+ * `{ ok: false, reason }` so the boot path can log a clear warning.
+ *
+ * Intentionally NOT throwing — incompat is a soft signal in v1.
+ * Aborting boot on a missed minor would freeze ecosystem evolution.
+ * The framework logs WARN and proceeds; the operator gets visibility
+ * + decides whether to pin or upgrade.
+ *
+ * Supports the subset apps in the wild actually use:
+ *   - `^x.y.z`        — caret: same major
+ *   - `~x.y.z`        — tilde: same major+minor
+ *   - `>=x.y.z`       — minimum version
+ *   - `>=x.y <a.b`    — compound (AND)
+ *   - `x.y.z`         — exact
+ *   - `*`             — any
+ */
+export declare const checkFrameworkCompat: (pluginName: string, range: string | undefined, runningVersion: string) => {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+
+export declare interface ClientDescriptor {
+    readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'workflow';
+    /** Query only: table(s) the cache should match this subscription against. */
+    readonly source?: string | ReadonlyArray<string> | undefined;
+    /** Mutation only: tables this mutation writes, with op. */
+    readonly targets?: ReadonlyArray<ClientTarget> | undefined;
+    /** The procedure's input `Schema`, carried to the client so schema-driven
+     *  UI (forms, query-bound pickers) and the capability map can introspect
+     *  it with no extra fetch. Browser-safe: the schema is already loaded
+     *  value-level via the rpc group, so this is the same object by reference. */
+    readonly input?: Schema.Schema.Any | undefined;
+    /** The procedure's output `Schema` — carried so schema-driven tables
+     *  (`<DataTable>` derives its columns from it) + the capability map can
+     *  introspect it. Same browser-safety rationale as `input`. */
+    readonly output?: Schema.Schema.Any | undefined;
+}
+
+/**
+ * Client-side view of a target. Carries the same fields as `TargetSpec`
+ * but with input/row generics erased — the client sees concrete runtime
+ * row shapes, not Schema instances. Optional `shape`/`identify` flow
+ * through because the codegen references the live descriptor (rather
+ * than emitting JSON), so function refs survive the ES-module boundary.
+ */
+export declare interface ClientTarget {
+    readonly table: string;
+    readonly op: 'insert' | 'update' | 'delete';
+    readonly order?: 'prepend' | 'append' | undefined;
+    readonly shape?: ((input: Record<string, unknown>, optimisticIdOrCurrent?: unknown) => Record<string, unknown>) | undefined;
+    readonly identify?: ((input: Record<string, unknown>) => string) | undefined;
+}
+
+/** Compose multiple strategies into a single resolver function. The
+ *  composer evaluates them in declaration order; first `matched`
+ *  wins; first `failed` short-circuits to anonymous (does NOT fall
+ *  through — see StrategyResolution doc).
+ *
+ *  Apps wrap the return in `AuthMiddleware.of(...)` themselves so they
+ *  can inject the connection-override fast-path (`getConnectionSubject`)
+ *  ahead of the strategy chain — that path lives in `@voltro/runtime`
+ *  and the protocol package stays runtime-agnostic.
+ *
+ *  Returns an async resolver `(input) => Promise<Subject>`.
+ */
+export declare const composeAuthStrategies: (strategies: ReadonlyArray<AuthStrategy>, options?: {
+    /** Fallback when no strategy matched. Default: returns the input's
+     *  tenant from `x-tenant` header or null. */
+    readonly fallback?: (input: AuthStrategyInput) => Subject;
+    /** Hook for logging — called on every `failed` resolution. */
+    readonly onStrategyFailed?: (event: {
+        strategyId: string;
+        reason: string;
+    }) => void;
+    /**
+     * Reject anonymous callers that carry no tenant. When `true` and no
+     * strategy matched AND no `x-tenant` header is present, the resolver
+     * throws `Unauthenticated` instead of returning a null-tenant
+     * anonymous Subject. Use it on multi-tenant apps where every call —
+     * even an anonymous one — must be scoped to a tenant; without it a
+     * tenant-less anonymous Subject can read across the whole DB on
+     * tables that aren't `tenant()`-scoped. Ignored when a custom
+     * `fallback` is supplied (the fallback owns that decision).
+     */
+    readonly anonymousTenantRequired?: boolean;
+}) => ((input: AuthStrategyInput) => Promise<Subject>);
+
+/**
+ * Compose a list of Effect-native interceptors into ONE function the
+ * runtime calls. Reduces right-to-left so the array order reads
+ * naturally as outer → inner: `[A, B, C]` produces A(B(C(next))). The
+ * output is `undefined` when the list is empty so callers can skip the
+ * wrap entirely.
+ *
+ * Used for mutation / query / action chains alike.
+ */
+export declare const composeRpcInterceptors: (interceptors: ReadonlyArray<RpcInterceptor>) => RpcInterceptor | undefined;
+
+export declare class ConnectionInfo extends ConnectionInfo_base {
+}
+
+declare const ConnectionInfo_base: Context.TagClass<ConnectionInfo, "@voltro/ConnectionInfo", ConnectionInfoValue>;
+
+/**
+ * Second middleware on every RpcGroup that wants the
+ * `ConnectionInfo` service available to handlers. Resolves from the
+ * per-call `{clientId}` the @effect/rpc transport passes in. Handlers
+ * that re-bind the connection's subject (e.g. `auth.signin` writing
+ * an override after a successful credential check) read clientId
+ * from this service.
+ *
+ * Apps without a soft-reauth flow can skip attaching this middleware.
+ * The framework provides a default-live Layer in `@voltro/runtime`
+ * which the rpcServer wires alongside AuthMiddleware.
+ */
+export declare class ConnectionInfoMiddleware extends ConnectionInfoMiddleware_base {
+}
+
+declare const ConnectionInfoMiddleware_base: RpcMiddleware.TagClass<ConnectionInfoMiddleware, "@voltro/ConnectionInfoMiddleware", {
+    readonly provides: typeof ConnectionInfo;
+}>;
+
+export declare interface ConnectionInfoValue {
+    /** Per-connection identifier assigned by the rpc transport. Stable for the
+     *  lifetime of the underlying WebSocket connection; reused as the key for
+     *  the per-connection subject override map. */
+    readonly clientId: number;
+}
+
+/**
+ * A handle to a cluster-coordinated periodic task the plugin armed via
+ * `PluginBindContext.scheduleCoordinated`. Keep it to `stop()` the task
+ * in `onDeactivate` — though the framework also stops every task a plugin
+ * armed at shutdown, so an explicit `stop()` is only needed for tasks the
+ * plugin wants to cancel EARLY (before shutdown).
+ */
+export declare interface CoordinatedScheduleHandle {
+    /** Stop the periodic task. Idempotent. */
+    readonly stop: () => void;
+    /** The task name (for logging / dedup diagnostics). */
+    readonly name: string;
+}
+
+export declare const defineAction: <const Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All = typeof Schema.Never>(options: {
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error?: Error;
+    /** Project this action as a public REST endpoint (innovation/11). */
+    readonly publicApi?: PublicApiSpec;
+    /** Expose this action as an agent tool (innovation/07). */
+    readonly exposeAsTool?: ExposeAsTool;
+}) => ActionProcedureDescriptor<Name, Input, Output, Error>;
+
+export declare const defineMutation: <const Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All = typeof Schema.Never>(options: {
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error?: Error;
+    /** Optional declarative target(s) — drives auto-optimistic. */
+    readonly target?: Target<Schema.Schema.Type<Input>, Schema.Schema.Type<Output>>;
+    /** Project this mutation as a public REST endpoint (innovation/11). */
+    readonly publicApi?: PublicApiSpec;
+    /** Expose this mutation as an agent tool (innovation/07). */
+    readonly exposeAsTool?: ExposeAsTool;
+}) => MutationProcedureDescriptor<Name, Input, Output, Error>;
+
+/**
+ * Builder helper that returns the input object unchanged AT RUNTIME
+ * but enforces the `VoltroPlugin` shape at the TYPE level. Use over
+ * plain object literals when you want the type-checker to catch
+ * misnamed hooks or missing required fields at the plugin's
+ * declaration site rather than at the `app.config.ts` consumption
+ * site.
+ *
+ * ```ts
+ * export const myPlugin = (options: MyOptions): VoltroPlugin =>
+ *   definePlugin({
+ *     name: '@vendor/my-plugin',
+ *     framework: '^1.0.0',
+ *     interceptMutation: (next, ctx) =>
+ *       next.pipe(Effect.tap(() => recordAudit(ctx))),
+ *     onActivate:  (ctx) => Effect.sync(() => ctx.logger.info('warming caches')),
+ *     onDeactivate: () => Effect.void,
+ *   })
+ * ```
+ *
+ * Identity function — kept narrow so the compiler picks excess-property
+ * checks on the literal.
+ */
+export declare const definePlugin: (plugin: VoltroPlugin) => VoltroPlugin;
+
+/**
+ * Helper to declare one rpc route contributed by a plugin. Returns
+ * the input unchanged; exists for the type-level enforcement (plus
+ * symmetry with `defineMutation` / `defineQuery` user-side).
+ */
+export declare const definePluginRoute: (route: PluginRpcRoute) => PluginRpcRoute;
+
+/**
+ * Declarative builder for a plugin's `services` layer. Wraps the
+ * `Context.Tag` + `Layer.succeed` pair so a plugin author doesn't
+ * have to manage both. Use when a plugin's service interface is
+ * straightforward (a record of functions); reach for raw Layer when
+ * the implementation depends on other services (Layer.effect) or
+ * needs resource acquisition (Layer.scoped).
+ */
+export declare const definePluginService: <I, S>(identifier: string, implementation: S) => {
+    readonly Tag: Context.Tag<I, S>;
+    readonly Live: Layer.Layer<I, never, never>;
+};
+
+export declare const defineQuery: <const Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All = typeof Schema.Never>(options: {
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error?: Error;
+    /** Optional: the store table(s) this query reads. Declaring it enables
+     *  auto-optimistic patch routing from mutations targeting any of those
+     *  tables. For a COMPUTED query (handler returns a shaped value) it is the
+     *  reactive trigger set: the handler re-runs when ANY listed table changes
+     *  — pass an array to depend on several (e.g. a matrix joining two tables). */
+    readonly source?: string | ReadonlyArray<string>;
+    /** Opt into server-side snapshot caching with auto-invalidation. */
+    readonly cache?: QueryCacheConfig;
+    /** Project this query as a public REST endpoint (innovation/11). */
+    readonly publicApi?: PublicApiSpec;
+    /** Expose this query as an agent tool (innovation/07). */
+    readonly exposeAsTool?: ExposeAsTool;
+}) => QueryProcedureDescriptor<Name, Input, Output, Error>;
+
+/**
+ * Declare a non-reactive server→client stream. `handler(input, ctx)`
+ * returns a `Stream<Element>` (e.g. an agent run's `AgentEvent`s); the
+ * client consumes it via `useAgentStream`. Reusable for ANY push stream.
+ */
+export declare const defineStream: <const Name extends string, Input extends Schema.Schema.Any, Element extends Schema.Schema.Any, Error extends Schema.Schema.All = typeof Schema.Never>(options: {
+    readonly name: Name;
+    readonly input: Input;
+    readonly element: Element;
+    readonly error?: Error;
+}) => StreamProcedureDescriptor<Name, Input, Element, Error>;
+
+export declare interface DeleteTarget<Input = unknown> {
+    readonly table: string;
+    readonly op: 'delete';
+    /** Identify the row to remove. Default: `input.id`. */
+    readonly identify?: ((input: Input) => string) | undefined;
+}
+
+/**
+ * Compute the patch that turns `prev` into `next`, keyed by row id.
+ *
+ * Algorithm:
+ *   - Index both sides by id.
+ *   - For each id in next: not in prev → `add`; in prev but content
+ *     differs → `replace`; in prev and equal → no op.
+ *   - For each id in prev but not in next → `remove`.
+ *   - `order` is next's id sequence verbatim, so apply can reconstruct
+ *     the exact ordering (including a pure reorder, where `ops` is empty).
+ *
+ * Throws if any row lacks an `id` — the caller (dispatcher) only diffs
+ * id-keyed result sets; a result without ids must ship a full snapshot,
+ * not a patch.
+ */
+export declare const diffRows: (prev: ReadonlyArray<PatchRow>, next: ReadonlyArray<PatchRow>) => RowPatch;
+
+/** Normalize the `exposeAsTool` shorthand. `true` is only valid when the
+ *  descriptor carries a top-level `description`; callers pass that in. */
+export declare type ExposeAsTool = boolean | ExposeAsToolSpec;
+
+export declare interface ExposeAsToolSpec {
+    /** Shown to the model — REQUIRED to expose (a tool with no description is
+     *  unusable). What the tool does + when to call it. */
+    readonly description: string;
+    /** Require human confirmation of the concrete call before it executes.
+     *  Default posture: writes (mutation/action) confirm, reads don't. */
+    readonly confirm?: boolean;
+    /** Cap how many times the agent may call this tool per run. */
+    readonly maxPerRun?: number;
+}
+
+/**
+ * Cross-cutting error schemas a plugin contributes to EVERY procedure's
+ * wire error union (see `VoltroPlugin.errorSchemas`). Unioned into each
+ * rpc's `error:` so an interceptor that fails with one of these (e.g. a
+ * rate-limit `RateLimited`) decodes as a TYPED error on the client
+ * instead of crossing the wire as an untyped defect. Passed identically
+ * by the server group (cli/dev.ts) and the generated client group
+ * (cli/codegen.ts) so both ends agree on the wire shape.
+ */
+export declare type ExtraErrors = ReadonlyArray<Schema.Schema.All>;
+
+/** Release a claim after the handler errored, so a retry can re-process. */
+export declare const failIdempotent: (store: IdempotencyStore, scope: string, key: string) => Promise<void>;
+
+/** Record a completed response for replay. */
+export declare const finishIdempotent: (store: IdempotencyStore, scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
+
+export declare const hasCallbackRoutes: (s: AuthStrategy) => s is AuthStrategyWithCallback;
+
+/** True if the subject holds `scope` (or the `admin:full` bypass). */
+export declare const hasScope: (subject: Subject, scope: string) => boolean;
+
+/**
+ * Short-circuit response shape. Returning a `HttpInterceptResponse`
+ * from the interceptor halts the pipeline — the framework sends the
+ * response and never invokes the downstream handler.
+ *
+ * Returning `null` (or calling `next()` and returning its result)
+ * lets the request continue to the normal pipeline.
+ */
+export declare interface HttpInterceptResponse {
+    readonly status: number;
+    readonly body?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Per-call context passed to HTTP-request interceptors. Fires BEFORE
+ * auth-resolution, BEFORE rpc-routing, BEFORE inspect — at the very
+ * top of the HTTP pipeline. Use for pre-auth concerns: rate-limit
+ * (token bucket per IP), geo-block (451), bot-detection, header
+ * injection for downstream observability, CORS-override.
+ *
+ * The interceptor is NOT an auth replacement — `AuthMiddleware` still
+ * runs on the rpc path. If you need to GATE auth, wrap a different
+ * surface (`interceptAction` for unary calls, `interceptMutation` for
+ * writes). HTTP-interceptors run on EVERY HTTP request including
+ * inspect endpoints and the rpc websocket upgrade.
+ */
+export declare interface HttpRequestContext {
+    /** HTTP method (`'GET'`, `'POST'`, etc.). */
+    readonly method: string;
+    /** Request path (no query string). */
+    readonly path: string;
+    /** Lowercased request headers. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Best-effort remote address. `undefined` when running behind a
+     *  proxy without `x-forwarded-for`. */
+    readonly remoteAddr: string | undefined;
+}
+
+/**
+ * Wraps every HTTP request before the framework's auth + routing.
+ * Composed across plugins in declaration order — first listed =
+ * outermost. The chain short-circuits as soon as a plugin returns
+ * a `HttpInterceptResponse`; later plugins don't see the request.
+ *
+ * Plugin MUST declare the `http:intercept` permission or boot fails
+ * loudly. Plugins without that permission get their `onHttpRequest`
+ * hook stripped at activation (so the rest of the plugin still
+ * works).
+ */
+export declare type HttpRequestInterceptor = (next: () => Promise<HttpInterceptResponse | null>, ctx: HttpRequestContext) => Promise<HttpInterceptResponse | null>;
+
+export declare type IdempotencyOutcome = {
+    readonly kind: 'fresh';
+} | {
+    readonly kind: 'replay';
+    readonly response: IdempotencyResponse;
+} | {
+    readonly kind: 'conflict';
+};
+
+export declare interface IdempotencyRecord {
+    readonly scope: string;
+    readonly key: string;
+    readonly status: 'in_flight' | 'completed';
+    readonly response: IdempotencyResponse | null;
+    /** epoch ms */
+    readonly createdAt: number;
+}
+
+export declare interface IdempotencyResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+
+/** Build the scope key — keep keys from colliding across tenants + endpoints. */
+export declare const idempotencyScope: (tenantId: string | null | undefined, method: string, path: string) => string;
+
+export declare interface IdempotencyStore {
+    /** Current record for (scope, key), or null. Read-side (inspect/dashboard). */
+    readonly get: (scope: string, key: string) => Promise<IdempotencyRecord | null>;
+    /**
+     * Atomically claim (scope, key) IF absent OR stale (older than `ttlMs`):
+     * write a fresh `in_flight` row and return `'claimed'`. Otherwise return the
+     * EXISTING (still-fresh) record. The atomicity here is the whole game — two
+     * concurrent same-key requests both hit this, exactly one gets `'claimed'`,
+     * the loser reads the winner's record. In SQL this is one
+     * `INSERT … ON CONFLICT DO UPDATE … WHERE existing.createdAt < now - ttl`.
+     */
+    readonly claim: (scope: string, key: string, now: number, ttlMs: number) => Promise<'claimed' | IdempotencyRecord>;
+    /** Flip the claim to `completed` and store the response. */
+    readonly complete: (scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
+    /** Drop the claim (handler errored → a retry may re-process). */
+    readonly release: (scope: string, key: string) => Promise<void>;
+}
+
+/** `/<id>` — the op path for a row id. Ids are JSON-pointer-escaped
+ *  (`~` → `~0`, `/` → `~1`) so a slash or tilde inside a string id can't
+ *  corrupt the pointer. */
+export declare const idToPath: (id: RowId) => string;
+
+export declare interface InsertTarget<Input = unknown, Row = unknown> {
+    readonly table: string;
+    readonly op: 'insert';
+    readonly order?: 'prepend' | 'append' | undefined;
+    /**
+     * Build the optimistic row from the mutation input. The framework
+     * injects `id` (from `optimisticId`) and the `optimistic: true` flag
+     * around the return — your `shape` returns ONLY the user-controllable
+     * row body. Default when omitted: `{ ...input, id, optimistic: true }`.
+     *
+     * Return type intentionally excludes `id`: it's server-generated;
+     * the optimistic id placeholder is the framework's responsibility.
+     * Excluding `optimistic` (also framework-injected) follows the same
+     * principle — `Omit<Row, 'id' | 'optimistic'>` lets you describe
+     * EVERYTHING ELSE without re-stating the bookkeeping fields.
+     *
+     * The `optimisticId` parameter is exposed for rare cases where the
+     * shape function needs to reference it (e.g., setting a foreign key
+     * on a child row spread in the same optimistic insert).
+     */
+    readonly shape?: ((input: Input, optimisticId: string) => Omit<Row, 'id' | 'optimistic'>) | undefined;
+}
+
+/** True when every row in the set carries an `id`. The dispatcher uses
+ *  this to decide patch-vs-full-snapshot: a result whose rows aren't
+ *  id-keyed (rare — a custom projection that drops the id) can't be
+ *  diffed by id and falls back to shipping the full data. */
+export declare const isIdKeyed: (rows: ReadonlyArray<Readonly<Record<string, unknown>>>) => rows is ReadonlyArray<PatchRow>;
+
+export declare const isSystemSubject: (subject: Subject) => boolean;
+
+/** In-memory store — the default for single-process dev + the test double. */
+export declare const memoryIdempotencyStore: () => IdempotencyStore;
+
+export declare interface MutationProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+    readonly kind: 'mutation';
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error: Error;
+    /** Declarative target(s) — drives auto-optimistic on the client AND
+     *  surfaces which tables this mutation touches (debug, future
+     *  query-invalidation analytics). Mutations without a target run
+     *  normally but skip auto-optimistic. */
+    readonly target: Target | undefined;
+    /** Opt this mutation into a public REST endpoint (innovation/11). */
+    readonly publicApi: PublicApiSpec | undefined;
+    /** Opt this mutation into the auto-synthesized agent toolset (innovation/07). */
+    readonly exposeAsTool: ExposeAsTool | undefined;
+}
+
+export declare const mutationToRpc: <Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: MutationProcedureDescriptor<Name, Input, Output, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Output, Schema.Schema.All, never>;
+
+/**
+ * Project a runtime descriptor down to the subset the client needs.
+ * Functions (`shape`, `identify`) are passed through by reference —
+ * the client's auto-optimistic uses them as-is when present.
+ */
+export declare const normalizeDescriptor: (descriptor: ProcedureDescriptor) => ClientDescriptor;
+
+/**
+ * What a plugin contributes to the OTel layer via `contributeObservability`.
+ * The OTel types are intentionally `unknown` so this browser-safe protocol
+ * package never imports `@opentelemetry/*` (the cli casts to the concrete
+ * `SpanProcessor` / `MetricReader` / `Sampler` when wiring `buildTracingLayer`).
+ */
+export declare interface ObservabilityContribution {
+    /** Merged into the OTel Resource (e.g. `service.version`,
+     *  `deployment.environment`). */
+    readonly resourceAttributes?: Record<string, string>;
+    /** Additional OTel `SpanProcessor`s installed alongside the framework's
+     *  exporter + buffer sink (e.g. a vendor OTLP exporter or `SentrySpanProcessor`). */
+    readonly spanProcessors?: ReadonlyArray<unknown>;
+    /** Additional OTel `MetricReader`s (e.g. a vendor OTLP metric reader). */
+    readonly metricReaders?: ReadonlyArray<unknown>;
+    /** OTel `Sampler` (e.g. Sentry's `SentrySampler` honouring `tracesSampleRate`). */
+    readonly sampler?: unknown;
+}
+
+/** A single row in a subscription result. Must carry an `id`; everything
+ *  else is opaque to the patch layer. */
+export declare type PatchRow = Readonly<Record<string, unknown>> & {
+    readonly id: RowId;
+};
+
+/** Inverse of `idToPath` for the string case. Numeric ids round-trip via
+ *  the `order` array (which preserves the original type), so apply never
+ *  needs to re-parse a number out of a path. */
+export declare const pathToId: (path: string) => string;
+
+/**
+ * Called once at app boot, after `voltro dev` resolves the plugin
+ * list and before the rpc server starts accepting connections. Use
+ * for warming caches, opening connection pools, registering metrics,
+ * or any one-shot setup the plugin needs. Throws abort boot —
+ * malformed plugin config should surface as a clear, immediate error.
+ */
+export declare type PluginActivateHook = (ctx: PluginLifecycleContext) => Effect.Effect<void, unknown> | Promise<void> | void;
+
+/**
+ * Server-only context delivered to `bindDataStore`, ALONGSIDE the store,
+ * AFTER the framework has opened its store + pool. Gives a plugin the
+ * framework's ALREADY-OPEN handles so it never rebuilds a pg pool from
+ * raw env (the anti-pattern `@voltro/plugin-ratelimit` used to hand-roll)
+ * and never runs an un-coordinated per-replica `setInterval` sweep (what
+ * presence + governance used to do).
+ *
+ * These fields are SERVER-only — they are TYPES only in this browser-safe
+ * protocol package (the `DataStore` / `SqlClient` imports are erased), and
+ * the live values exist only inside the serve pipeline that calls
+ * `bindDataStore`. Nothing in the browser-loaded descriptor/schema graph
+ * touches them.
+ */
+export declare interface PluginBindContext {
+    /**
+     * The framework's already-open `SqlClient` (from `@effect/sql`) — the
+     * SAME pool the app's store uses. A plugin runs raw SQL through this
+     * instead of standing up its OWN `ManagedRuntime` + pool from env. Only
+     * present for SQL-backed stores; `undefined` on the in-memory store
+     * (there is no SQL engine) — guard with `if (ctx.sql)`.
+     */
+    readonly sql?: SqlClient.SqlClient;
+    /**
+     * Run `effect` every `intervalMs` on ONLY ONE replica per tick —
+     * cluster-coordinated via the framework's existing claim-table
+     * exactly-once gate (the same seam the cron scheduler uses). Replaces
+     * the hand-rolled `setInterval` a plugin used to run inside
+     * `bindDataStore`, which fired on EVERY replica un-coordinated. On a
+     * single-process / memory / sqlite deployment it simply runs every tick
+     * locally (correct — one process needs no fan-out dedup).
+     *
+     * `name` is the task's stable id (namespace it, e.g. `presence.sweep`);
+     * it becomes the claim key. Returns a handle whose `stop()` cancels the
+     * task early. The framework also stops every armed task at shutdown.
+     */
+    readonly scheduleCoordinated: (name: string, intervalMs: number, effect: () => void | Promise<void>) => CoordinatedScheduleHandle;
+}
+
+/**
+ * Post-commit change event delivered to a plugin's `onChangeEvent` tap.
+ * Minimal, browser-safe shape (protocol must not depend on the database
+ * package's concrete `ChangeEvent`) — the framework maps its internal event
+ * to this before fan-out.
+ */
+export declare interface PluginChangeEvent {
+    readonly table: string;
+    readonly op: 'insert' | 'update' | 'delete';
+    /** Row after the change — present on insert + update, null on delete. */
+    readonly new: Record<string, unknown> | null;
+    /** Row before the change — present on update + delete, null on insert. */
+    readonly old: Record<string, unknown> | null;
+    /** How the event reached this process: absent/'inline' = this process's
+     *  own write; 'injected' = delivered over a cross-instance transport
+     *  (broadcast bus / CDC consumer). Combine with `changeScope` to act
+     *  exactly once per change fleet-wide. */
+    readonly origin?: 'inline' | 'injected';
+    /** The store's change visibility (see `DataStore.changeScope`):
+     *  'local' — own writes inline (skip origin 'injected' for
+     *  exactly-once-on-the-writer); 'fleet' — every replica sees the full
+     *  stream (elect one worker instead). */
+    readonly changeScope: 'local' | 'fleet';
+}
+
+/**
+ * Plugin-supplied codegen contribution. Emitted into the user app's
+ * `rpcGroup.generated.ts` as an extra section AFTER the framework's
+ * own output. Use for typed bindings that don't fit the rpc wire —
+ * helper exports, type re-exports, accessor functions that wrap the
+ * plugin's runtime apis.
+ *
+ * The framework calls this function once per codegen run. Returns:
+ *   - a string  → emitted verbatim
+ *   - `null`    → contributes nothing
+ *
+ * The function MUST be pure: it gets the plugin name + the api name
+ * + the list of discovered rpc-tag-and-kind tuples (for plugins that
+ * want to emit per-rpc bindings). No filesystem / network access —
+ * codegen runs as a build step on every dev restart.
+ *
+ * Typical pattern: emit a typed accessor for the plugin's service Tag:
+ *
+ *   codegen: (ctx) => `
+ *     export const use${capitalize(ctx.pluginAlias)} = () =>
+ *       (ctx: AppContext) => ctx[${JSON.stringify(ctx.pluginAlias)}]
+ *   `
+ *
+ * The output is wrapped between `// <plugin:NAME>` / `// </plugin:NAME>`
+ * markers in the generated file so the user can identify the source.
+ */
+export declare type PluginCodegen = (ctx: PluginCodegenContext) => string | null;
+
+export declare interface PluginCodegenContext {
+    /** The plugin's full name (`@voltro/plugin-audit`). */
+    readonly pluginName: string;
+    /** The derived alias (`audit`). */
+    readonly pluginAlias: string;
+    /** The api app's name from `app.config.ts`. */
+    readonly apiName: string;
+    /** Flat list of rpc tags discovered in the app (user routes only). */
+    readonly rpcTags: ReadonlyArray<{
+        readonly kind: 'query' | 'mutation' | 'action' | 'stream' | 'workflow';
+        readonly tag: string;
+    }>;
+}
+
+/**
+ * A remote-mounted dashboard surface a plugin contributes. The
+ * dashboard-host (voltro-cloud / voltro-devtools) renders the mount
+ * by `import()`ing the ESM module at `bundleUrl` and calling the
+ * exported component with host-provided context (auth subject,
+ * routing, theme tokens).
+ *
+ * Not iframe — true in-process mount. Trade-offs:
+ *   - Plugin's bundle MUST be ESM with React/Effect as peerDeps; the
+ *     host pins the versions. Mismatch logs a warning + still mounts.
+ *   - No CSS isolation. Plugin authors are expected to use scoped
+ *     Tailwind classes (the dashboard ships the framework token set)
+ *     or CSS modules. Inline `style` on a top-level wrapper avoids
+ *     bleeding host styles in.
+ *   - Plugin code shares the host JS realm — honor-system sandboxing.
+ *     Mounts are gated by the `dashboard:mount` permission to keep
+ *     the operator's audit trail explicit.
+ *
+ * The framework surfaces declared mounts via
+ * `/_voltro/inspect/plugins/dashboard-mounts`. The actual mount
+ * runtime ships in voltro-cloud-dashboard + voltro-devtools.
+ */
+export declare interface PluginDashboardMount {
+    /** Stable id within the plugin (kebab-case). Full id surfaces as
+     *  `<plugin-alias>:<mount.id>` in the dashboard's mount registry. */
+    readonly id: string;
+    /**
+     * Where the dashboard host should mount this contribution:
+     *   - `'page'`   — full-page mount under `/plugins/<alias>/<route>`
+     *   - `'widget'` — card-shaped tile on the dashboard home
+     *   - `'nav'`    — sidebar nav item linking to a `page`-mount route
+     */
+    readonly slot: 'page' | 'widget' | 'nav';
+    /** Required for `slot: 'page'`. Path is mounted under
+     *  `/plugins/<plugin-alias>/<route>`. Ignored for widget/nav. */
+    readonly route?: string;
+    /** Human-readable label (nav text, page title, widget header). */
+    readonly label: string;
+    /** Optional icon — emoji or a `lucide-react` icon name. */
+    readonly icon?: string;
+    /**
+     * Absolute URL the host fetches at mount time. Must serve an ESM
+     * module. CDN-hosted or self-hosted (`https://my-plugin.example/v1/bundle.mjs`).
+     * The plugin author is responsible for HTTPS + immutable versioning.
+     */
+    readonly bundleUrl: string;
+    /** Export name to read from the imported module. Defaults to
+     *  `'default'`. The export must be a React component. */
+    readonly exportName?: string;
+    /** Optional dashboard-framework version range the mount supports
+     *  (npm-semver). Host logs a warning on mismatch but mounts. */
+    readonly dashboardVersion?: string;
+}
+
+/**
+ * Called once at graceful shutdown (SIGTERM in production; HMR-reload
+ * in dev). Mirror of `onActivate`: close connections, flush buffers,
+ * cancel timers. The framework waits up to 5s for `onDeactivate` to
+ * settle before SIGKILL falls through.
+ */
+export declare type PluginDeactivateHook = (ctx: PluginLifecycleContext) => Effect.Effect<void, unknown> | Promise<void> | void;
+
+/**
+ * An environment variable a plugin reads. DECLARATION ONLY — metadata, not a
+ * read path: the plugin still reads the value itself (typically
+ * `options.X ?? process.env.X`). Declaring it makes the plugin's env needs
+ * visible to the env manifest (`/_voltro/inspect/env`), the generated
+ * `.env.example`, and the dashboard Env panel — so an operator can see, before
+ * running, exactly what each plugin expects.
+ *
+ * Structurally identical to `@voltro/env`'s `DeclaredEnvVar` (kept local here
+ * to avoid a protocol → env package dependency).
+ */
+export declare interface PluginEnvVar {
+    /** The env var name, e.g. `DD_API_KEY`. */
+    readonly name: string;
+    /** True when the plugin cannot function without it (no sensible default). */
+    readonly required: boolean;
+    /** True for tokens / passwords / credential URLs — the manifest then
+     *  reports `isSet` only, never the value. */
+    readonly secret: boolean;
+    /** One-line description — shown in `.env.example` + the manifest. */
+    readonly description?: string;
+    /** Example value for `.env.example`. Never a real secret. */
+    readonly example?: string;
+}
+
+/**
+ * A cross-cutting error schema a plugin merges into EVERY procedure's
+ * wire error union. Use when a plugin interceptor can fail with a typed
+ * error (e.g. a rate-limit `RateLimited`) that must decode TYPED on the
+ * client rather than crossing as an untyped defect.
+ *
+ * Two halves because the error must be applied in two places that can't
+ * share a value:
+ *   - `schema`: the live `effect/Schema` — used at runtime when the cli
+ *     assembles the SERVER rpc group.
+ *   - `import`: where to import the same schema from — used by codegen to
+ *     emit the import into the generated CLIENT rpc group, so both ends
+ *     agree on the wire shape. `name` must be the exported identifier.
+ *
+ * Requires the plugin to ship the schema as a NAMED export from `module`.
+ */
+export declare interface PluginErrorSchema {
+    readonly schema: Schema.Schema.All;
+    readonly import: {
+        readonly module: string;
+        readonly name: string;
+    };
+}
+
+/** A public raw-HTTP route a plugin serves on the framework listener. */
+export declare interface PluginHttpRoute {
+    /** HTTP method, or `'*'` for any (the handler decides). */
+    readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Absolute path prefix, e.g. `/_voltro/storage`. Matches the path AND
+     *  any sub-path (`/_voltro/storage/abc123`). */
+    readonly path: string;
+    readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+}
+
+export declare interface PluginHttpRouteRequest {
+    readonly method: string;
+    /** Path WITHOUT query string. */
+    readonly path: string;
+    /** Query string WITHOUT the leading `?` (empty when absent). Parse with
+     *  `new URLSearchParams(req.query)`. */
+    readonly query: string;
+    readonly headers: Record<string, string>;
+    readonly rawBody: Uint8Array;
+}
+
+/**
+ * One HTTP endpoint a plugin contributes under the framework's
+ * `/_voltro/inspect/*` introspection surface. Plugins use this to
+ * surface tooling / dashboards that don't fit the rpc wire (e.g.
+ * Server-Sent-Event streams of plugin-internal state, on-demand
+ * health probes, plugin-specific debug dumps).
+ *
+ * Path convention: `/_voltro/inspect/plugins/<plugin-slug>/<route.path>`.
+ * The plugin slug (derived from `plugin.name` with `@scope/` +
+ * `plugin-` stripped, KEBAB-CASE — `plugin-cdc-out` → `cdc-out`,
+ * instance suffix `#x` → `--x`) is prepended by the framework so
+ * plugin endpoints never collide with the framework's own inspect
+ * endpoints OR with another plugin's. Kebab (not the camelCase rpc
+ * alias) because it's a URL every dashboard fetches. The dashboard
+ * lists every plugin's endpoints grouped by plugin in the manifest.
+ *
+ * Plugin endpoints inherit the SAME auth resolver the framework's
+ * own inspect endpoints use (`VOLTRO_INSPECT_TOKEN` by default;
+ * customisable by passing an `authResolver` at the http-handler
+ * layer). The plugin can NOT bypass auth — that's the framework's
+ * job, not the plugin's.
+ */
+/** What a plugin HTTP route returns. `body` may be bytes (e.g. a served
+ *  blob) or text; `headers` carries redirects (302 `location`) + cache
+ *  policy. */
+export declare interface PluginHttpRouteResult {
+    readonly status: number;
+    readonly body?: string | Uint8Array;
+    readonly contentType?: string;
+    readonly headers?: Record<string, string>;
+}
+
+export declare interface PluginInspectEndpoint {
+    /** HTTP method. */
+    readonly method: 'GET' | 'POST' | 'DELETE';
+    /**
+     * Path relative to the plugin's inspect prefix. Leading slash
+     * optional. `health` → `/_voltro/inspect/plugins/<slug>/health`.
+     */
+    readonly path: string;
+    /** Optional human-readable description; surfaced in the dashboard. */
+    readonly description?: string;
+    /**
+     * Effect-based handler. Receives the raw request + headers,
+     * returns the response shape. Body parsing is the handler's
+     * job — the framework just hands the string through. JSON/CORS
+     * are sugar on top: returning `{ json: ... }` from the response
+     * shape sets the right content-type + serialises.
+     *
+     * Long-running responses (SSE, streaming) are NOT supported in
+     * v1 — every endpoint returns one buffered response. SSE plugins
+     * can route to a separate path mounted by the plugin's own
+     * `routes:` array via the rpc layer, which DOES stream.
+     */
+    readonly handler: (request: PluginInspectRequest) => Effect.Effect<PluginInspectResponse, unknown, never>;
+}
+
+export declare interface PluginInspectRequest {
+    readonly method: 'GET' | 'POST' | 'DELETE';
+    /** Full URL the client requested (path + query). */
+    readonly url: string;
+    /** Lowercased headers. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Raw body (empty string on GET / DELETE). */
+    readonly body: string;
+}
+
+export declare type PluginInspectResponse = {
+    readonly kind: 'json';
+    readonly status?: number;
+    readonly data: unknown;
+} | {
+    readonly kind: 'text';
+    readonly status?: number;
+    readonly contentType?: string;
+    readonly body: string;
+};
+
+/**
+ * Called ONCE per host across the plugin's lifetime — the first time
+ * it's seen by the host. Used for one-time schema migrations + resource
+ * provisioning that survive across deactivate/activate cycles. Skipped
+ * on subsequent boots once the host has recorded the install.
+ *
+ * v1 model: install state is in-process only (in-memory marker keyed by
+ * plugin name + version). A future slice will persist it to
+ * `_voltro_plugin_installs` so install/uninstall idempotency survives
+ * process restarts. For now, treat `onInstall` as "what runs on a fresh
+ * dev process the first time this plugin is wired" — sufficient for the
+ * "create a schema table on first wire-up" use case.
+ */
+export declare type PluginInstallHook = (ctx: PluginLifecycleContext) => Effect.Effect<void, unknown> | Promise<void> | void;
+
+/**
+ * Per-app context handed to lifecycle hooks. The shape is intentionally
+ * thin — the framework's deeper services (DataStore, Logger, etc.) are
+ * available via the per-request `AppContext` plugins see in their rpc
+ * interceptors. Lifecycle hooks run OUTSIDE any request, so they
+ * receive a minimal slice:
+ *
+ *   - `app`: the resolved app-config metadata
+ *     (`{ name, type, voltroVersion }`).
+ *   - `logger`: a scoped `@voltro/logger` instance keyed to the
+ *     plugin's `name`, so log lines are attributable.
+ *   - `env`: the process env (alias of `process.env` for typing).
+ *   - `config`: the plugin's own validated config (if `configSchema`
+ *     declared) — already decoded against the plugin's Schema, ready
+ *     for the hook to consume. Unknown otherwise.
+ */
+export declare interface PluginLifecycleContext {
+    readonly app: {
+        readonly name: string;
+        readonly type: 'api' | 'web';
+        readonly voltroVersion: string;
+    };
+    readonly logger: {
+        info: (message: string, fields?: Record<string, unknown>) => void;
+        warn: (message: string, fields?: Record<string, unknown>) => void;
+        error: (message: string, fields?: Record<string, unknown>) => void;
+        debug: (message: string, fields?: Record<string, unknown>) => void;
+    };
+    readonly env: NodeJS.ProcessEnv;
+    /** Validated plugin config (if `configSchema` was declared). */
+    readonly config: unknown;
+}
+
+export declare interface PluginMigration {
+    readonly id: string;
+    readonly description?: string;
+    readonly up: (sql: PluginMigrationSqlClient) => Effect.Effect<void, unknown>;
+    readonly down?: (sql: PluginMigrationSqlClient) => Effect.Effect<void, unknown>;
+}
+
+/**
+ * A plugin-supplied custom migration. Runs ONCE per app DB, tracked in
+ * the framework's `_voltro_plugin_migrations` ledger so re-runs of
+ * `voltro dev` skip already-applied steps. Use for setup the
+ * declarative-tables path can't express: extension installs (`CREATE
+ * EXTENSION pgcrypto`), seed data, DDL for pre-existing /
+ * externally-owned tables the plugin wraps, etc.
+ *
+ * Ids are stable strings the plugin author owns. The framework
+ * namespaces them as `<plugin-alias>__<migration.id>` in the ledger
+ * so two plugins can each ship a `'001-init'` without collision.
+ *
+ * The `up` Effect runs against the live `SqlClient` after the
+ * framework's own schema apply. Failures abort boot (loud +
+ * recoverable: fix + restart). Down-migrations are optional and not
+ * auto-run — they exist for ops tooling.
+ */
+/**
+ * The `sql` parameter the framework hands the migration is the live
+ * `SqlClient.SqlClient` from `@effect/sql`. The reference is type-only,
+ * so it adds no runtime dependency — `@voltro/protocol` still ships
+ * without pulling `@effect/sql` into a plugin's bundle.
+ */
+export declare type PluginMigrationSqlClient = SqlClient.SqlClient;
+
+/**
+ * Declared permission scope. The framework gates hook surfaces on
+ * the declared set: plugins that ship `onHttpRequest` without
+ * declaring `'http:intercept'` are rejected at boot. Pattern-perms
+ * support a `:*` wildcard suffix (`'secrets:read:auth0:*'` covers
+ * `'secrets:read:auth0:clientSecret'`).
+ *
+ * The static surface is a typed union so plugin authors get autocomplete;
+ * pattern perms fall through the template-literal arm. Surfaced in the
+ * boot log + `/_voltro/inspect/plugins` so operators audit what each
+ * plugin asks for before installing.
+ */
+export declare type PluginPermission = 'rpc:intercept:mutation' | 'rpc:intercept:query' | 'rpc:intercept:action' | 'schedule:fire' | 'schedule:read' | 'workflow:step' | 'http:intercept' | 'inspect:read' | 'inspect:write' | 'dashboard:mount' | 'store:write' | 'migration:run' | 'store:changes:read' | `secrets:read:${string}` | `network:outbound:${string}` | `plugin:hook:${string}`;
+
+/**
+ * Per-call context handed to a plugin-contributed rpc route's
+ * executor. Mirror of the user-handler `AppContext` shape but typed
+ * loosely so the plugin doesn't need to depend on `@voltro/runtime`.
+ */
+export declare interface PluginRouteContext {
+    readonly request: {
+        readonly subject: Subject;
+        readonly traceId: string;
+    };
+}
+
+/**
+ * Client-facing declaration of a plugin RPC route's descriptor, so the codegen
+ * can emit it into the generated client rpc group (`appGroup` + `appDescriptors`)
+ * — without this, a plugin route is mounted server-side but the browser client
+ * can't resolve its tag ("not reachable on client").
+ *
+ * `import` MUST point at a BROWSER-SAFE module that exports the route's descriptor
+ * value (tag + input/output/error Schema, NO executor, NO `node:*`/server deps) —
+ * the same discipline `PluginErrorSchema.import` follows (e.g.
+ * `@voltro/plugin-storage/rpc`). The generated file is loaded value-level by the
+ * web client + guarded by `assertBrowserSafeRpcGroup`, so a server import here is
+ * a boot failure. `tag` is the route's EFFECTIVE tag (`<alias>.<name>`); `kind`
+ * selects `queryToRpc` / `mutationToRpc` / `actionToRpc`.
+ */
+export declare interface PluginRpcClientDescriptor {
+    readonly tag: string;
+    readonly kind: RpcKind;
+    readonly import: {
+        readonly module: string;
+        readonly name: string;
+    };
+}
+
+/**
+ * One descriptor + executor pair a plugin contributes to the host's
+ * rpc surface. Same shape as a user-authored mutation/query/action,
+ * but registered programmatically by the plugin instead of via file
+ * discovery.
+ *
+ * The plugin's name is prepended to the rpc tag at registration time
+ * unless the descriptor already carries a dot — e.g. a plugin named
+ * `@voltro/plugin-audit` exporting `route({ name: 'list' })` lands
+ * as `audit.list`; exporting `route({ name: 'admin.events' })` lands
+ * unchanged. This guarantees plugin routes never collide with
+ * user-authored routes (user routes don't ship the plugin prefix) and
+ * lets the dashboard show them grouped by plugin.
+ */
+export declare interface PluginRpcRoute {
+    /** 'mutation' | 'query' | 'action' — determines the runtime path. */
+    readonly kind: RpcKind;
+    /** RPC tag relative to the plugin (e.g. `'list'`, `'admin.events'`). */
+    readonly name: string;
+    /** Optional human-readable description; surfaced in the dashboard. */
+    readonly description?: string;
+    /** Input schema — same `effect/Schema` shape user routes use. */
+    readonly input: Schema.Schema.Any;
+    /** Output schema. */
+    readonly output: Schema.Schema.Any;
+    /** Optional typed-error schema (TaggedError union). */
+    readonly error?: Schema.Schema.All;
+    /**
+     * REACTIVE source table(s) — ONLY for `kind: 'query'`. When set, the
+     * framework drives the query REACTIVELY: it re-runs the executor and pushes
+     * a fresh result over the SAME subscription/WS transport app reactive
+     * queries use, every time one of the named tables changes. This makes a
+     * plugin query PUSH-DRIVEN — no client polling — by reusing the framework's
+     * computed-reactive-query machinery (the descriptor is browser-safe, the
+     * executor runs server-side).
+     *
+     * The executor returns the query's VALUE (an array / object) — the same
+     * shape it returns for a poll; the framework recomputes it on change. Omit
+     * for a plain (poll-only) plugin query, a mutation, or an action. For a
+     * query that mirrors a plugin table, set this to that table's name (e.g.
+     * `@voltro/plugin-presence` sets `_voltro_presence`, which is `.reactive()`).
+     *
+     * `| undefined` is explicit so a plugin can spread a browser-safe query
+     * DESCRIPTOR (which always carries `source: … | undefined`) into a route
+     * literal under `exactOptionalPropertyTypes` without a cast.
+     */
+    readonly source?: string | ReadonlyArray<string> | undefined;
+    /**
+     * Effect-only executor. The base layer is provided by the framework
+     * (DataStore, HttpClient, the plugin's own service Tags) — the
+     * executor declares its requirements through Effect's R channel like
+     * any other handler. Mutations land inside `store.transactional()`
+     * automatically; queries return a `QueryDescriptor`-shaped result;
+     * actions run without a transaction.
+     */
+    readonly execute: (input: never, ctx: PluginRouteContext) => Effect.Effect<unknown, unknown, never>;
+}
+
+/**
+ * What a plugin contributes to the host app's schema. `tables` join
+ * the user's table set + go through the same `applySchema()` path
+ * (idempotent CREATE TABLE IF NOT EXISTS). `migrations` run after
+ * `applySchema()` against the live SqlClient, tracked in
+ * `_voltro_plugin_migrations`.
+ *
+ * Plugin MUST declare `store:write` for `tables`, `migration:run`
+ * for `migrations`. Boot fails if the declared-permission set is
+ * insufficient.
+ */
+export declare interface PluginSchemaContribution {
+    readonly tables?: ReadonlyArray<unknown>;
+    readonly migrations?: ReadonlyArray<PluginMigration>;
+}
+
+/**
+ * A scaffold template a plugin contributes to `voltro init` /
+ * `voltro add-app`. Templates are listed under the plugin's name in
+ * `voltro list-templates`; the operator picks one and the CLI seeds
+ * the project tree.
+ *
+ * The framework keeps the template registry per-plugin scoped so two
+ * plugins can each ship an `auth` template without collision: the
+ * full template id is `<plugin-alias>:<template.id>`.
+ *
+ * v1 ships the registration shape + listing; the actual
+ * `voltro init --from-plugin` invocation lands once a real consumer
+ * needs it. Until then, templates are surfaced in
+ * `/_voltro/inspect/plugins` so the dashboard can preview them.
+ */
+export declare interface PluginTemplate {
+    /** Stable id within the plugin (kebab-case). The framework
+     *  prepends the plugin alias when surfacing — `audit:starter` /
+     *  `webhooks:stripe-receiver`. */
+    readonly id: string;
+    /** Human-readable label for the picker. */
+    readonly title: string;
+    /** One-line description; surfaced in `voltro list-templates`. */
+    readonly description: string;
+    /** Which kind of app this template scaffolds. */
+    readonly kind: 'api' | 'web' | 'fullstack';
+    /**
+     * Source directory inside the plugin's package. The CLI resolves
+     * it relative to the plugin's npm-resolved root. Files inside are
+     * copied verbatim into the target project; `package.json` is
+     * patched to point dependencies at the plugin.
+     */
+    readonly sourcePath: string;
+    /** Optional list of post-install hints surfaced after scaffolding. */
+    readonly postInstallSteps?: ReadonlyArray<string>;
+}
+
+/**
+ * Called ONCE when the host removes the plugin. Mirror of `onInstall`.
+ * Used to clean up the plugin's persisted resources (drop tables,
+ * delete queue topics) so an uninstall fully reverses an install.
+ *
+ * v1 model: triggered explicitly by `voltro plugins uninstall <name>`
+ * (CLI command — see manifest plan). NOT triggered on plain shutdown
+ * (that's `onDeactivate`). Plugins are responsible for making
+ * `onUninstall` idempotent — repeating it should be a no-op once the
+ * resources are gone.
+ */
+export declare type PluginUninstallHook = (ctx: PluginLifecycleContext) => Effect.Effect<void, unknown> | Promise<void> | void;
+
+export declare type ProcedureDescriptor = QueryProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | MutationProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | ActionProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | StreamProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All>;
+
+export declare const PROTOCOL_VERSION: 1;
+
+export declare type ProtocolVersion = typeof PROTOCOL_VERSION;
+
+export declare interface PublicApiSpec {
+    /** Derived by kind when omitted: query→GET, mutation/action→POST. */
+    readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Derived from the tag + version when omitted: `/<version>/<tag-as-path>`. */
+    readonly path?: string;
+    /** Path version segment; multiple versions coexist as separate descriptors. */
+    readonly version?: string;
+    /** Additional API-key scopes required ON TOP of the handler's RBAC. */
+    readonly scopes?: ReadonlyArray<string>;
+    /** Per-endpoint rate limit (rides @voltro/plugin-ratelimit when mounted). */
+    readonly rateLimit?: {
+        readonly limit: number;
+        readonly window: string;
+    };
+    /** Honor `Idempotency-Key` for mutating methods (existing HTTP idempotency). */
+    readonly idempotent?: boolean;
+    /** Replacement hint → `Deprecation: true` header. */
+    readonly deprecated?: string;
+    /** ISO date → `Sunset:` header, `410` past the date. */
+    readonly sunset?: string;
+    readonly summary?: string;
+    readonly description?: string;
+    /** Streaming queries over request/response: 'snapshot' (default — first
+     *  snapshot, like POST /rpc) | 'sse' (Server-Sent Events of snapshot+deltas). */
+    readonly stream?: 'snapshot' | 'sse';
+}
+
+/** Publish a server-primitive error. Cheap + sync; a broken reporter can
+ *  never break the caller (each listener is isolated). Safe no-op when
+ *  nothing is subscribed — primitives call it unconditionally. */
+export declare const publishServerError: (event: ServerErrorEvent) => void;
+
+/**
+ * Server-side snapshot caching for a query (see `defineQuery`). When set,
+ * the dispatcher caches the initial snapshot result and auto-invalidates it
+ * when a mutation writes any table the query depends on.
+ */
+export declare interface QueryCacheConfig {
+    /** Fresh window — seconds (number) or a duration string (`'30s'`,
+     *  `'5m'`, `'1h'`). */
+    readonly ttl: number | string;
+    /** Stale-while-revalidate window past `ttl` (same units). While stale,
+     *  the cached value is served immediately and refreshed in the
+     *  background. */
+    readonly swr?: number | string | undefined;
+    /**
+     * Cross-subject safety — REQUIRED, no default, because guessing wrong
+     * leaks rows. `'subject'` keys the cache by the caller's subject id
+     * (safe for tenant- or row-filtered queries). `'global'` shares ONE
+     * entry across every caller — legal ONLY when the resolved query is
+     * subject-independent (reference data). Rubric: does the resolved
+     * predicate depend on the caller? Yes → `subject`; no → `global`.
+     */
+    readonly scope: 'subject' | 'global';
+}
+
+export declare interface QueryProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+    readonly kind: 'query';
+    readonly name: Name;
+    readonly input: Input;
+    readonly output: Output;
+    readonly error: Error;
+    /** Which DataStore table(s) this query reads. Drives auto-optimistic patch
+     *  routing — mutations that target ANY of these tables patch caches keyed
+     *  to queries with a matching `source`. A computed query re-runs when ANY
+     *  listed table changes (pass an array to depend on several). Optional:
+     *  queries without a source never receive auto-patches (joins, aggregates). */
+    readonly source: string | ReadonlyArray<string> | undefined;
+    /** Server-side snapshot cache config. Absent → never cached (the
+     *  default; the dispatcher already keeps live subscriptions fresh). */
+    readonly cache: QueryCacheConfig | undefined;
+    /** Opt this query into a public REST endpoint (innovation/11). */
+    readonly publicApi: PublicApiSpec | undefined;
+    /** Opt this query into the auto-synthesized agent toolset (innovation/07). */
+    readonly exposeAsTool: ExposeAsTool | undefined;
+}
+
+export declare const queryToRpc: <Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: QueryProcedureDescriptor<Name, Input, Output, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["snapshot"]>;
+    revision: typeof Schema.Number;
+    data: Output;
+    computed: Schema.optional<typeof Schema.Boolean>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["delta"]>;
+    revision: typeof Schema.Number;
+    emittedAt: typeof Schema.Number;
+    patch: Schema.Struct<{
+        ops: Schema.Array$<Schema.Union<[Schema.Struct<{
+            op: Schema.Literal<["add"]>;
+            path: typeof Schema.String;
+            value: Schema.refine<{
+                readonly [x: string]: unknown;
+            } & Readonly<Record<string, unknown>> & {
+                readonly id: RowId;
+            }, Schema.Schema<{
+                readonly [x: string]: unknown;
+            }, {
+                readonly [x: string]: unknown;
+            }, never>>;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["replace"]>;
+            path: typeof Schema.String;
+            value: Schema.refine<{
+                readonly [x: string]: unknown;
+            } & Readonly<Record<string, unknown>> & {
+                readonly id: RowId;
+            }, Schema.Schema<{
+                readonly [x: string]: unknown;
+            }, {
+                readonly [x: string]: unknown;
+            }, never>>;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["remove"]>;
+            path: typeof Schema.String;
+        }>]>>;
+        order: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
+    }>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["error"]>;
+    error: typeof Schema.Unknown;
+    revision: Schema.optional<typeof Schema.Number>;
+}>]>, Schema.Schema.All>, typeof Schema.Never, never>;
+
+/** Gate a handler on a scope; fails with a typed `ScopeError` if missing. */
+export declare const requireScope: (subject: Subject, scope: string) => Effect.Effect<void, ScopeError>;
+
+/** The id of a row, addressed in op paths as `/<id>`. */
+export declare type RowId = string | number;
+
+/** The full delta payload: the per-row ops plus the authoritative id
+ *  ordering of the resulting set. */
+export declare interface RowPatch {
+    readonly ops: ReadonlyArray<RowPatchOp>;
+    /** Id sequence of the resulting (next) row set, in order. */
+    readonly order: ReadonlyArray<RowId>;
+}
+
+/**
+ * One RFC-6902-style op against an id-keyed row set. `path` is always
+ * `/<id>` (the row's id), NOT an array index — this is the deliberate
+ * departure that makes the diff reorder-stable.
+ *
+ *   - `replace` — the row with this id exists in both prev and next but
+ *                 its content changed; `value` is the full next row.
+ *   - `add`     — the row with this id is new in next; `value` is it.
+ *   - `remove`  — the row with this id is gone in next.
+ */
+export declare type RowPatchOp = {
+    readonly op: 'add';
+    readonly path: string;
+    readonly value: PatchRow;
+} | {
+    readonly op: 'replace';
+    readonly path: string;
+    readonly value: PatchRow;
+} | {
+    readonly op: 'remove';
+    readonly path: string;
+};
+
+export declare const rowPatchOpSchema: Schema.Union<[Schema.Struct<{
+    op: Schema.Literal<["add"]>;
+    path: typeof Schema.String;
+    value: Schema.refine<{
+        readonly [x: string]: unknown;
+    } & Readonly<Record<string, unknown>> & {
+        readonly id: RowId;
+    }, Schema.Schema<{
+        readonly [x: string]: unknown;
+    }, {
+        readonly [x: string]: unknown;
+    }, never>>;
+}>, Schema.Struct<{
+    op: Schema.Literal<["replace"]>;
+    path: typeof Schema.String;
+    value: Schema.refine<{
+        readonly [x: string]: unknown;
+    } & Readonly<Record<string, unknown>> & {
+        readonly id: RowId;
+    }, Schema.Schema<{
+        readonly [x: string]: unknown;
+    }, {
+        readonly [x: string]: unknown;
+    }, never>>;
+}>, Schema.Struct<{
+    op: Schema.Literal<["remove"]>;
+    path: typeof Schema.String;
+}>]>;
+
+export declare const rowPatchSchema: Schema.Struct<{
+    ops: Schema.Array$<Schema.Union<[Schema.Struct<{
+        op: Schema.Literal<["add"]>;
+        path: typeof Schema.String;
+        value: Schema.refine<{
+            readonly [x: string]: unknown;
+        } & Readonly<Record<string, unknown>> & {
+            readonly id: RowId;
+        }, Schema.Schema<{
+            readonly [x: string]: unknown;
+        }, {
+            readonly [x: string]: unknown;
+        }, never>>;
+    }>, Schema.Struct<{
+        op: Schema.Literal<["replace"]>;
+        path: typeof Schema.String;
+        value: Schema.refine<{
+            readonly [x: string]: unknown;
+        } & Readonly<Record<string, unknown>> & {
+            readonly id: RowId;
+        }, Schema.Schema<{
+            readonly [x: string]: unknown;
+        }, {
+            readonly [x: string]: unknown;
+        }, never>>;
+    }>, Schema.Struct<{
+        op: Schema.Literal<["remove"]>;
+        path: typeof Schema.String;
+    }>]>>;
+    order: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
+}>;
+
+/**
+ * Effect-native interceptor. Receives the rest of the chain as an
+ * `Effect`; the interceptor returns an `Effect` that wraps it (or
+ * substitutes a different one). Whatever the returned Effect produces
+ * becomes the final result.
+ *
+ * Typical patterns:
+ *
+ *   // Pre-only authz: short-circuit BEFORE the executor runs.
+ *   const guard: RpcInterceptor = (next, ctx) =>
+ *     ctx.tag.startsWith('admin.') && ctx.subject.type !== 'user'
+ *       ? Effect.fail(new Forbidden({ tag: ctx.tag }))
+ *       : next
+ *
+ *   // Post-only side effects: tap the success/failure channels.
+ *   const log: RpcInterceptor = (next, ctx) =>
+ *     next.pipe(
+ *       Effect.tap((result) => recordAudit(ctx.tag, ctx.input, result, ctx.subject)),
+ *       Effect.tapError((err) => recordAuditError(ctx.tag, err)),
+ *     )
+ *
+ *   // Tracing: wrap with a span; OTel spans nest automatically.
+ *   const trace: RpcInterceptor = (next, ctx) =>
+ *     next.pipe(Effect.withSpan(`plugin.audit.${ctx.kind}`, { attributes: { tag: ctx.tag } }))
+ *
+ * The `next` Effect MUST be flowed through somehow — either yielded,
+ * piped, or returned — for the executor to run. Returning a different
+ * Effect substitutes the result entirely (rare, e.g. cache hits).
+ */
+export declare type RpcInterceptor = (next: Effect.Effect<unknown, unknown>, context: RpcInterceptorContext) => Effect.Effect<unknown, unknown>;
+
+/**
+ * Per-call context passed to every rpc interceptor. The fields are
+ * deliberately shallow — plugins shouldn't need the full AppContext +
+ * DataStore to do their job. For runtime services (DataStore, custom
+ * Tags, etc.) declare them via `definePlugin({ services })` and read
+ * via `yield* MyTag` in the interceptor body; the framework provides
+ * them automatically.
+ */
+export declare interface RpcInterceptorContext {
+    /** Procedure tag, e.g. `todos.create`. */
+    readonly tag: string;
+    /** Discriminator — `'mutation' | 'query' | 'action'`. */
+    readonly kind: RpcKind;
+    /** The validated input the executor is about to (or already did) receive. */
+    readonly input: unknown;
+    /** The resolved subject (user / apiKey / serviceAccount / anonymous). */
+    readonly subject: Subject;
+    /** Per-call trace id (matches OTel spans + inspect events). */
+    readonly traceId: string;
+    /** Active OTel span id (16-hex), when tracing is on. Lets observability
+     *  plugins (Sentry/Datadog) attach an error to the exact span, not just
+     *  the trace. Absent when no tracer is installed. */
+    readonly spanId?: string;
+}
+
+/**
+ * Which kind of rpc the interceptor is wrapping. The runtime passes
+ * `kind: 'mutation'` to interceptors registered as `interceptMutation`,
+ * `kind: 'query'` to `interceptQuery`, and `kind: 'action'` to
+ * `interceptAction` — one plugin can implement any combination.
+ */
+export declare type RpcKind = 'mutation' | 'query' | 'action';
+
+/**
+ * Per-firing context passed to schedule-fire interceptors. Shape
+ * parallels `RpcInterceptorContext` so plugin authors can lift the
+ * same patterns across rpc + schedule surfaces.
+ */
+export declare interface ScheduleFireContext {
+    /** Schedule name (e.g. `'nightlyBilling'`). */
+    readonly name: string;
+    /** When the firing was scheduled by the cron expression. */
+    readonly scheduledAt: Date;
+    /** When the firing actually started. */
+    readonly firedAt: Date;
+    /** Run id recorded in `_voltro_schedule_runs` (`'unrecorded'` if
+     *  the run-row insert failed). */
+    readonly runId: string;
+    /** What triggered this firing. `'self'`/`'external'`/`'manual'`. */
+    readonly trigger: 'self' | 'external' | 'manual';
+}
+
+/**
+ * Wraps a single schedule firing. Receives `next` as a thunk so the
+ * interceptor can choose to skip the firing entirely (don't call
+ * `next()`), wrap it with side effects, or substitute behaviour.
+ * Throwing/rejecting propagates as a handler failure recorded in
+ * `_voltro_schedule_runs.status = 'failed'`. The watchdog
+ * (`maxRuntimeMs`) wraps the WHOLE chain — exceeding it aborts.
+ *
+ * Use for: per-schedule observability (custom metrics/traces beyond
+ * the framework's defaults), durable-lock extension, feature-flag-
+ * gated suppression, suspend/resume integration with external
+ * orchestrators.
+ *
+ * Typical pattern:
+ *
+ *   onScheduleFire: async (next, ctx) => {
+ *     if (await isFeatureKilled(ctx.name)) return  // suppress
+ *     const start = Date.now()
+ *     try {
+ *       await next()
+ *     } finally {
+ *       recordCustomMetric({ name: ctx.name, durationMs: Date.now() - start })
+ *     }
+ *   }
+ */
+export declare type ScheduleFireInterceptor = (next: () => Promise<void>, ctx: ScheduleFireContext) => Promise<void>;
+
+export declare class ScopeError extends ScopeError_base {
+}
+
+declare const ScopeError_base: Schema.TaggedErrorClass<ScopeError, "ScopeError", {
+    readonly _tag: Schema.tag<"ScopeError">;
+} & {
+    required: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
+export declare interface ServerErrorEvent {
+    /** The thrown value (Error | tagged error | anything). */
+    readonly error: unknown;
+    /** Which primitive caught it. */
+    readonly source: ServerErrorSource;
+    /** Human identifier: route path / aggregate name / schedule name /
+     *  workflow name / webhook id / startup id / subscriber table. */
+    readonly name?: string;
+    /** Distributed-trace id when one is in scope (workflows carry it). */
+    readonly traceId?: string;
+    /** Extra context — op, runId, executionId, http status, etc. */
+    readonly fields?: Record<string, unknown>;
+}
+
+declare type ServerErrorListener = (event: ServerErrorEvent) => void;
+
+export declare type ServerErrorSource = 'rest' | 'aggregate' | 'subscriber' | 'reaction' | 'schedule' | 'workflow' | 'webhook' | 'startup';
+
+/** A strategy's verdict on a request.
+ *  - `matched`: this strategy claims the request; here's the Subject.
+ *  - `skip`: not my request (e.g. cookie absent); try next strategy.
+ *  - `failed`: this IS my request BUT validation failed (signature
+ *    mismatch, expired JWT). Composer bails to anonymous + logs;
+ *    silently falling through would mask attacks. */
+export declare type StrategyResolution = {
+    readonly kind: 'matched';
+    readonly subject: Subject;
+} | {
+    readonly kind: 'skip';
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+
+/**
+ * A non-reactive server→client stream — the load-bearing distinction from
+ * a query: a query streams a reactive `SubscriptionEvent` (snapshot+delta)
+ * envelope over a table; a stream emits PLAIN `element`s (e.g. an agent
+ * run's `AgentEvent`s), one-shot, no table, no snapshot. Backs A3's
+ * agent runtime + any other server-push stream.
+ */
+export declare interface StreamProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Element extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+    readonly kind: 'stream';
+    readonly name: Name;
+    readonly input: Input;
+    readonly element: Element;
+    readonly error: Error;
+}
+
+export declare const streamToRpc: <Name extends string, Input extends Schema.Schema.Any, Element extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: StreamProcedureDescriptor<Name, Input, Element, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Element, Schema.Schema.All>, typeof Schema.Never, never>;
+
+export declare const Subject: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["user"]>;
+    id: typeof Schema.String;
+    tenantId: typeof Schema.String;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["apiKey"]>;
+    id: typeof Schema.String;
+    tenantId: typeof Schema.String;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["serviceAccount"]>;
+    id: typeof Schema.String;
+    tenantId: typeof Schema.String;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["anonymous"]>;
+    id: typeof Schema.Null;
+    tenantId: Schema.NullOr<typeof Schema.String>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["system"]>;
+    id: typeof Schema.String;
+    tenantId: typeof Schema.Null;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>]>;
+
+export declare type Subject = typeof Subject.Type;
+
+/** The subject's scopes (empty for anonymous / unscoped). */
+export declare const subjectScopes: (subject: Subject) => ReadonlyArray<string>;
+
+export declare class SubjectService extends SubjectService_base {
+}
+
+declare const SubjectService_base: Context.TagClass<SubjectService, "@voltro/Subject", {
+    readonly id: string;
+    readonly type: "user";
+    readonly tenantId: string;
+    readonly scopes?: readonly string[] | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+} | {
+    readonly id: string;
+    readonly type: "apiKey";
+    readonly tenantId: string;
+    readonly scopes?: readonly string[] | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+} | {
+    readonly id: string;
+    readonly type: "serviceAccount";
+    readonly tenantId: string;
+    readonly scopes?: readonly string[] | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+} | {
+    readonly id: null;
+    readonly type: "anonymous";
+    readonly tenantId: string | null;
+} | {
+    readonly id: string;
+    readonly type: "system";
+    readonly tenantId: null;
+    readonly scopes?: readonly string[] | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+}>;
+
+/** Subscribe to server-primitive errors. Returns an unsubscribe fn. */
+export declare const subscribeServerErrors: (listener: ServerErrorListener) => (() => void);
+
+export declare type SubscriptionEvent<T> = {
+    readonly _tag: 'snapshot';
+    readonly revision: number;
+    readonly data: T;
+    readonly computed?: boolean;
+} | {
+    readonly _tag: 'delta';
+    readonly revision: number;
+    readonly emittedAt: number;
+    readonly patch: RowPatch;
+} | {
+    readonly _tag: 'error';
+    readonly error: unknown;
+    readonly revision?: number;
+};
+
+export declare const subscriptionEvent: <D extends Schema.Schema.Any>(data: D) => Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["snapshot"]>;
+    revision: typeof Schema.Number;
+    data: D;
+    computed: Schema.optional<typeof Schema.Boolean>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["delta"]>;
+    revision: typeof Schema.Number;
+    emittedAt: typeof Schema.Number;
+    patch: Schema.Struct<{
+        ops: Schema.Array$<Schema.Union<[Schema.Struct<{
+            op: Schema.Literal<["add"]>;
+            path: typeof Schema.String;
+            value: Schema.refine<{
+                readonly [x: string]: unknown;
+            } & Readonly<Record<string, unknown>> & {
+                readonly id: RowId;
+            }, Schema.Schema<{
+                readonly [x: string]: unknown;
+            }, {
+                readonly [x: string]: unknown;
+            }, never>>;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["replace"]>;
+            path: typeof Schema.String;
+            value: Schema.refine<{
+                readonly [x: string]: unknown;
+            } & Readonly<Record<string, unknown>> & {
+                readonly id: RowId;
+            }, Schema.Schema<{
+                readonly [x: string]: unknown;
+            }, {
+                readonly [x: string]: unknown;
+            }, never>>;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["remove"]>;
+            path: typeof Schema.String;
+        }>]>>;
+        order: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
+    }>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["error"]>;
+    error: typeof Schema.Unknown;
+    revision: Schema.optional<typeof Schema.Number>;
+}>]>;
+
+export declare const systemSubject: (id: string, scopes?: ReadonlyArray<string>) => Subject;
+
+export declare type Target<Input = unknown, Row = unknown> = TargetSpec<Input, Row> | ReadonlyArray<TargetSpec<Input, Row>>;
+
+export declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
+
+export declare const toRpc: <Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: QueryProcedureDescriptor<Name, Input, Output, Err> | MutationProcedureDescriptor<Name, Input, Output, Err> | ActionProcedureDescriptor<Name, Input, Output, Err> | StreamProcedureDescriptor<Name, Input, Output, Err>) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["snapshot"]>;
+    revision: typeof Schema.Number;
+    data: Output;
+    computed: Schema.optional<typeof Schema.Boolean>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["delta"]>;
+    revision: typeof Schema.Number;
+    emittedAt: typeof Schema.Number;
+    patch: Schema.Struct<{
+        ops: Schema.Array$<Schema.Union<[Schema.Struct<{
+            op: Schema.Literal<["add"]>;
+            path: typeof Schema.String;
+            value: Schema.refine<{
+                readonly [x: string]: unknown;
+            } & Readonly<Record<string, unknown>> & {
+                readonly id: RowId;
+            }, Schema.Schema<{
+                readonly [x: string]: unknown;
+            }, {
+                readonly [x: string]: unknown;
+            }, never>>;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["replace"]>;
+            path: typeof Schema.String;
+            value: Schema.refine<{
+                readonly [x: string]: unknown;
+            } & Readonly<Record<string, unknown>> & {
+                readonly id: RowId;
+            }, Schema.Schema<{
+                readonly [x: string]: unknown;
+            }, {
+                readonly [x: string]: unknown;
+            }, never>>;
+        }>, Schema.Struct<{
+            op: Schema.Literal<["remove"]>;
+            path: typeof Schema.String;
+        }>]>>;
+        order: Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number]>>;
+    }>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["error"]>;
+    error: typeof Schema.Unknown;
+    revision: Schema.optional<typeof Schema.Number>;
+}>]>, Schema.Schema.All>, typeof Schema.Never, never> | Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Output, Schema.Schema.All, never> | Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Output, Schema.Schema.All>, typeof Schema.Never, never>;
+
+/**
+ * Coerce a timestamp read (`Date` / epoch-ms number / ISO string) to
+ * epoch milliseconds. Unrecognised inputs collapse to `0`.
+ */
+export declare const tsMs: (v: unknown) => number;
+
+/**
+ * Typed error every handler can throw to signal "you must be signed
+ * in to perform this action". The framework's @effect/rpc layer
+ * preserves the `_tag` across the wire, and `@voltro/client`'s error
+ * bus surfaces it to the consuming app so the dashboard can
+ * auto-redirect to the sign-in page (cleared session + UI swap).
+ *
+ * Distinct from TenantMismatch (which means "you ARE signed in but
+ * touching the wrong tenant"). Unauthenticated means "no real subject
+ * resolved at all" — anonymous, expired token, missing cookie, etc.
+ */
+export declare class Unauthenticated extends Unauthenticated_base {
+}
+
+declare const Unauthenticated_base: Schema.TaggedErrorClass<Unauthenticated, "Unauthenticated", {
+    readonly _tag: Schema.tag<"Unauthenticated">;
+} & {
+    /** Optional context — e.g. "auth.signin required", "session expired". */
+    reason: Schema.optional<typeof Schema.String>;
+}>;
+
+export declare const UNDO_APPLY_TAG: "__voltro.undo.apply";
+
+export declare const UNDO_LOG_TAG: "__voltro.undo.log";
+
+export declare const UNDO_REDO_TAG: "__voltro.undo.redo";
+
+/** `__voltro.undo.apply` — undo one invocation (synthesize + apply its inverse).
+ *  No `target` (it writes whatever tables the change-set touched — its effects
+ *  reach the client via those tables' own reactive deltas, not optimistic). */
+export declare const undoApplyDescriptor: MutationProcedureDescriptor<"__voltro.undo.apply", Schema.Struct<{
+    invocationId: typeof Schema.String;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, Schema.Union<[typeof UndoNotFound, typeof UndoForbidden, typeof UndoConflict]>>;
+
+/** The row changed since the action (a concurrent writer), OR the action
+ *  crossed an external side effect — a blind restore would clobber/lie, so
+ *  undo refuses. `reason` distinguishes the two (mirrors the engine's
+ *  UndoBoundaryError boundary). */
+export declare class UndoConflict extends UndoConflict_base {
+}
+
+declare const UndoConflict_base: Schema.TaggedErrorClass<UndoConflict, "UndoConflict", {
+    readonly _tag: Schema.tag<"UndoConflict">;
+} & {
+    invocationId: typeof Schema.String;
+    reason: Schema.Literal<["conflict", "action"]>;
+}>;
+
+/** The action belongs to a different subject — undo is per-actor. */
+export declare class UndoForbidden extends UndoForbidden_base {
+}
+
+declare const UndoForbidden_base: Schema.TaggedErrorClass<UndoForbidden, "UndoForbidden", {
+    readonly _tag: Schema.tag<"UndoForbidden">;
+} & {
+    invocationId: typeof Schema.String;
+}>;
+
+/** One undoable action in the calling subject's recent history. The heavy
+ *  `changes` payload is server-only — the client list needs only this. */
+export declare const UndoLogEntry: Schema.Struct<{
+    /** The invocation id (= the `_voltro_undo_log` row id) to pass to apply/redo. */
+    id: typeof Schema.String;
+    /** Rpc tag of the captured mutation (e.g. `todos.create`). */
+    tag: typeof Schema.String;
+    /** Human label ("create todo") — falls back to the tag. */
+    label: Schema.NullOr<typeof Schema.String>;
+    /** True once undone (so the UI shows it as redo-able). */
+    undone: typeof Schema.Boolean;
+    /** True when the action crossed an external side effect → not undoable. */
+    crossesAction: typeof Schema.Boolean;
+    /** Display-only creation time (stringified). */
+    createdAt: typeof Schema.String;
+}>;
+
+export declare type UndoLogEntry = Schema.Schema.Type<typeof UndoLogEntry>;
+
+/** `__voltro.undo.log` — the calling subject's recent undoable actions, newest
+ *  first. Reactive (source `_voltro_undo_log`) so the list updates live as the
+ *  subject makes + undoes changes. */
+export declare const undoLogQueryDescriptor: QueryProcedureDescriptor<"__voltro.undo.log", Schema.Struct<{
+    limit: Schema.optional<typeof Schema.Number>;
+}>, Schema.Array$<Schema.Struct<{
+    /** The invocation id (= the `_voltro_undo_log` row id) to pass to apply/redo. */
+    id: typeof Schema.String;
+    /** Rpc tag of the captured mutation (e.g. `todos.create`). */
+    tag: typeof Schema.String;
+    /** Human label ("create todo") — falls back to the tag. */
+    label: Schema.NullOr<typeof Schema.String>;
+    /** True once undone (so the UI shows it as redo-able). */
+    undone: typeof Schema.Boolean;
+    /** True when the action crossed an external side effect → not undoable. */
+    crossesAction: typeof Schema.Boolean;
+    /** Display-only creation time (stringified). */
+    createdAt: typeof Schema.String;
+}>>, typeof Schema.Never>;
+
+/** No undo-log row for that invocation (already pruned, or wrong id). */
+export declare class UndoNotFound extends UndoNotFound_base {
+}
+
+declare const UndoNotFound_base: Schema.TaggedErrorClass<UndoNotFound, "UndoNotFound", {
+    readonly _tag: Schema.tag<"UndoNotFound">;
+} & {
+    invocationId: typeof Schema.String;
+}>;
+
+/** `__voltro.undo.redo` — re-apply a previously-undone invocation's forward changes. */
+export declare const undoRedoDescriptor: MutationProcedureDescriptor<"__voltro.undo.redo", Schema.Struct<{
+    invocationId: typeof Schema.String;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, Schema.Union<[typeof UndoNotFound, typeof UndoForbidden, typeof UndoConflict]>>;
+
+export declare interface UpdateTarget<Input = unknown, Row = unknown> {
+    readonly table: string;
+    readonly op: 'update';
+    /** Identify the row to patch. Default: `input.id`. */
+    readonly identify?: ((input: Input) => string) | undefined;
+    /** Build the patch. Default: merges input over current. */
+    readonly shape?: ((input: Input, current: Row) => Row) | undefined;
+}
+
+export declare interface VoltroPlugin {
+    /**
+     * Plugin identifier — printed in `voltro dev` boot logs + surfaced in
+     * the inspect manifest. Use a stable string scoped to the package
+     * (e.g. `@voltro/audit`, `acme.invoicing`). Required so multiple
+     * instances of the same package can be disambiguated by suffix
+     * (`@voltro/audit#analytics`).
+     */
+    readonly name: string;
+    /**
+     * Plugin version — the package's own semver. Distinct from
+     * `framework` (the FRAMEWORK range the plugin works with). Used by
+     * the manifest endpoint + future signing + install/uninstall
+     * idempotency. Optional today; recommended.
+     */
+    readonly version?: string;
+    /** Optional human-readable description; surfaced by the dashboard. */
+    readonly description?: string;
+    /**
+     * Compatible framework version range, in npm-semver syntax
+     * (`'^1.0.0'`, `'>=2.3.0 <3'`). The runtime checks the running
+     * framework against this at boot — incompatible plugins log a
+     * boot-time warning naming the constraint + the running version,
+     * but DON'T abort boot. App author makes the call; surfacing the
+     * mismatch is the framework's job.
+     *
+     * Absent → no compat check (plugin opts out of versioning). Suitable
+     * for in-tree plugins that ship lockstep with the framework.
+     */
+    readonly framework?: string;
+    /**
+     * Declared permission scopes. v1 advisory; future slice enforces.
+     * Surfaced in the boot log + `/_voltro/inspect/plugins` endpoint
+     * so operators audit what each plugin is asking for before granting.
+     */
+    readonly permissions?: ReadonlyArray<PluginPermission>;
+    /**
+     * Environment variables this plugin reads (declaration only — metadata, not
+     * a read path). The plugin still reads its values directly (`options.X ??
+     * process.env.X`); declaring them here surfaces the plugin's env needs in the
+     * manifest (`/_voltro/inspect/env`), the generated `.env.example`, and the
+     * dashboard Env panel. Mirror exactly what the plugin reads.
+     */
+    readonly declaredEnv?: ReadonlyArray<PluginEnvVar>;
+    /**
+     * Optional `effect/Schema` describing the plugin's user-supplied
+     * config. When present the framework decodes the operator's config
+     * payload against this schema at boot — invalid config aborts boot
+     * with a typed error message. The decoded value lands in
+     * `PluginLifecycleContext.config` so lifecycle hooks consume the
+     * already-validated shape.
+     *
+     * For plugins that take options via a factory function (the
+     * idiomatic TS pattern), `configSchema` is optional — the factory
+     * already validates at the type level. Declare `configSchema` when
+     * the plugin will surface a config form in the dashboard, or when
+     * the plugin reads dynamic config from env / a config file.
+     */
+    readonly configSchema?: Schema.Schema.Any;
+    /**
+     * Wraps every MUTATION handler call. Composed in declaration order
+     * across the plugin list: outermost = first listed in app.config.ts.
+     * Absent → the plugin contributes nothing at the mutation boundary
+     * (schema-only / lifecycle-only plugins are fine).
+     */
+    readonly interceptMutation?: RpcInterceptor;
+    /**
+     * Wraps every QUERY (streaming subscription handler) call. Same
+     * composition semantics as `interceptMutation`. Most observability
+     * plugins want to install this AND `interceptMutation` so the audit
+     * trail covers both read + write.
+     */
+    readonly interceptQuery?: RpcInterceptor;
+    /**
+     * Wraps every ACTION (unary non-transactional handler) call. Same
+     * composition semantics as `interceptMutation`. Useful for plugins
+     * that need to govern outbound HTTP / file IO calls (rate limiting,
+     * tenant-scoped IO quotas).
+     */
+    readonly interceptAction?: RpcInterceptor;
+    /**
+     * Effect Layer that contributes services into the per-request
+     * context. Anything declared here is yieldable from any handler in
+     * the host app (`const myTag = yield* MyTag`). Use this when a
+     * plugin needs to expose APIs to handlers without forcing every
+     * handler to import the plugin directly — handlers depend on the
+     * Tag, the plugin owns the Live implementation.
+     *
+     * The layer is provided ONCE at boot — it must be self-contained
+     * (`RIn = never`). For per-call data, expose a `Service` whose
+     * methods return Effects that consume per-call inputs.
+     */
+    readonly services?: Layer.Layer<never, never, never>;
+    /**
+     * RPC routes the plugin contributes. Registered alongside the
+     * user-authored routes — same wire protocol, same dashboard
+     * surface. The plugin's name is prepended to each route's `name`
+     * field unless the name already carries a dot.
+     *
+     * Use for plugin-shaped endpoints the user app shouldn't have to
+     * re-implement: webhook ingestion targets, OAuth callbacks, plugin
+     * admin queries, etc.
+     */
+    readonly routes?: ReadonlyArray<PluginRpcRoute>;
+    /**
+     * Plugin-contributed inspect endpoints. Mounted under
+     * `/_voltro/inspect/plugins/<plugin-slug>/<path>` — see
+     * `PluginInspectEndpoint`. Use for plugin-specific tooling that
+     * doesn't fit the rpc wire (health probes, debug dumps,
+     * on-demand stats exports).
+     */
+    readonly inspectEndpoints?: ReadonlyArray<PluginInspectEndpoint>;
+    /**
+     * Public raw-HTTP routes the plugin serves directly (not rpc, not
+     * inspect). Mounted by BOTH `voltro dev` and the production `serveApi`
+     * on the same listener — so e.g. `@voltro/plugin-storage` can serve
+     * `GET /_voltro/storage/:id` (302-presigned or streamed bytes) in dev
+     * AND prod. The handler owns its own auth + returns a status, an
+     * optional body (string or bytes), content-type, and headers (so it can
+     * 302-redirect or set immutable cache headers).
+     */
+    readonly httpRoutes?: ReadonlyArray<PluginHttpRoute>;
+    /**
+     * Called once by the serve pipeline (dev + serveApi) AFTER the app's
+     * DataStore is built — earlier than this it doesn't exist (dev activates
+     * plugins before the store). Lets a plugin bind a DB-backed resource it
+     * couldn't construct from static config: e.g. `@voltro/plugin-storage`
+     * swaps its in-memory ref store for `dataStoreRefStore(store)` so blob
+     * metadata persists in `_voltro_storage_refs`.
+     *
+     * `store` is the framework `DataStore` — TYPED now (was `unknown`); a
+     * `(s) => s as DataStore` implementation still compiles (DataStore →
+     * DataStore is a no-op cast) so the tightening is additive. `ctx` is the
+     * post-store bind context: the framework's already-open `SqlClient`
+     * (`ctx.sql`) so a plugin reuses the app's pool instead of rebuilding one
+     * from env, and `ctx.scheduleCoordinated(name, intervalMs, effect)` for
+     * a cluster-coordinated sweep that runs on ONE replica per tick instead
+     * of an un-coordinated per-replica `setInterval`.
+     *
+     * `ctx` is OPTIONAL in the type so the tightening stays additive: the
+     * framework ALWAYS passes it, but existing single-arg call sites (a
+     * plugin's `bindDataStore(store)` in a unit test) still compile. A plugin
+     * that wants the enablers declares `(store, ctx)` and reads
+     * `ctx?.sql` / `ctx?.scheduleCoordinated(...)`; one that ignores `ctx`
+     * keeps working unchanged.
+     */
+    readonly bindDataStore?: (store: DataStore, ctx?: PluginBindContext) => void;
+    /**
+     * Post-commit ChangeEvent tap — an `Effect<void, E>` the runtime SUPERVISES.
+     * Fires for EVERY committed store change (insert/update/delete on any table),
+     * AFTER the transaction commits and AFTER the framework's own subscribers.
+     *
+     * The runtime forks the returned Effect under the plugin's supervision scope
+     * and routes its failure channel to the plugin-scoped logger — so a change-tap
+     * gets a REAL typed error channel (`Effect.retry`, `Effect.timeout`,
+     * `Effect.catchTag`, durable enqueue) instead of fire-and-forget
+     * `.catch(warn)` glue. The fork keeps the tap non-blocking: a slow or failing
+     * tap can't back-pressure or break the change stream, and a failure is logged
+     * scoped to the plugin, never a defect that crosses into the stream.
+     *
+     * Still NOT durable at the framework layer — a crash between commit and the
+     * fork loses the event; a durable consumer builds durability INSIDE the
+     * Effect (a `store.insert` into an outbox the way `@voltro/plugin-cdc-out`
+     * does, retried against the typed error channel). This is the seam
+     * `@voltro/plugin-search` uses to mirror tables into an external index
+     * without a user-authored `*.subscribe.ts`. Requires the
+     * `store:changes:read` permission.
+     *
+     * Exactly-once / change-scope semantics are unchanged: read
+     * `event.origin` + `event.changeScope` inside the Effect to act once per
+     * change fleet-wide (skip `origin:'injected'` on `'local'` scope; elect one
+     * worker on `'fleet'`).
+     */
+    readonly onChangeEvent?: (event: PluginChangeEvent) => Effect.Effect<void, unknown>;
+    /**
+     * Wraps every schedule firing. Composed across plugins in
+     * declaration order (first-in-array = outermost wrapper). Runs
+     * INSIDE the framework's `maxRuntimeMs` watchdog — the watchdog
+     * applies to the whole chain. See `ScheduleFireInterceptor`.
+     */
+    readonly onScheduleFire?: ScheduleFireInterceptor;
+    /**
+     * Wraps every `step()` (== `Activity.make`) invocation inside a
+     * workflow body. Composed across plugins. The interceptor sees
+     * the user's `execute` Effect AS an Effect — it can `Effect.tap`,
+     * `Effect.retry`, `Effect.withSpan`, etc. See
+     * `WorkflowStepInterceptor`. Bypassed on workflow REPLAY (only
+     * fires on the first execution per step).
+     */
+    readonly onWorkflowStep?: WorkflowStepInterceptor;
+    /**
+     * Plugin-supplied codegen contribution. The framework calls this
+     * during `voltro dev`'s codegen step and emits the returned string
+     * into `rpcGroup.generated.ts` as a marked section. Use for typed
+     * accessor bindings that wrap the plugin's runtime apis. See
+     * `PluginCodegen`.
+     */
+    readonly codegen?: PluginCodegen;
+    /**
+     * Templates this plugin contributes to `voltro init` / `voltro add-app`.
+     * Each entry is a self-contained directory tree the CLI seeds into
+     * a new project. The framework lists them under the plugin's name
+     * in `voltro list-templates`.
+     */
+    readonly templates?: ReadonlyArray<PluginTemplate>;
+    /**
+     * Pre-auth HTTP-pipeline interceptor. Fires at the very top of the
+     * HTTP request handler, BEFORE auth resolution, BEFORE rpc routing,
+     * BEFORE inspect. Use for rate-limit, geo-block, bot-detection,
+     * outbound header injection. See `HttpRequestInterceptor`.
+     *
+     * Requires `'http:intercept'` permission — boot fails loudly if
+     * the hook is declared without the matching permission.
+     */
+    readonly onHttpRequest?: HttpRequestInterceptor;
+    /**
+     * Dashboard mount contributions — remote-loaded ESM modules the
+     * dashboard host renders alongside framework pages. See
+     * `PluginDashboardMount` for the trade-offs vs iframe.
+     *
+     * Requires `'dashboard:mount'` permission. Surfaces under
+     * `/_voltro/inspect/plugins/dashboard-mounts`; the actual mount
+     * runtime lives in voltro-cloud-dashboard + voltro-devtools.
+     */
+    readonly dashboard?: ReadonlyArray<PluginDashboardMount>;
+    /**
+     * Schema + migration contribution. `tables` are merged with the
+     * user's table set and run through the same idempotent
+     * `applySchema()` path. `migrations` run after the schema apply
+     * against the live SqlClient and are tracked in
+     * `_voltro_plugin_migrations` so they execute exactly once per
+     * app database.
+     *
+     * `tables` requires `'store:write'`; `migrations` requires
+     * `'migration:run'`. Either one missing → boot fails with the
+     * specific permission name in the error.
+     */
+    readonly extendSchema?: PluginSchemaContribution;
+    /**
+     * Cross-cutting error schemas merged into every procedure's wire error
+     * union. Lets a plugin interceptor fail with a typed error (e.g.
+     * `RateLimited`) that decodes TYPED on the client instead of as an
+     * untyped defect. The cli applies these to the server rpc group; codegen
+     * emits the matching imports into the generated client group. See
+     * `PluginErrorSchema`.
+     */
+    readonly errorSchemas?: ReadonlyArray<PluginErrorSchema>;
+    /**
+     * Client-facing RPC route descriptors for `routes` the web client calls
+     * (e.g. `storage.mintUploadTicket` behind `useUpload`). The codegen emits each
+     * into the generated client rpc group so its tag resolves in the browser. Each
+     * `import` MUST resolve to a BROWSER-SAFE module (descriptor/schema only) — see
+     * `PluginRpcClientDescriptor`. Omit for routes only ever called server-side.
+     */
+    readonly rpcClientDescriptors?: ReadonlyArray<PluginRpcClientDescriptor>;
+    /**
+     * One-time setup invoked the FIRST time this plugin is seen by the
+     * host. Use for schema migrations + resource provisioning that
+     * survive across deactivate/activate cycles. See `PluginInstallHook`.
+     */
+    readonly onInstall?: PluginInstallHook;
+    /**
+     * One-time teardown invoked when the host removes the plugin
+     * (`voltro plugins uninstall <name>`). Mirror of `onInstall`.
+     */
+    readonly onUninstall?: PluginUninstallHook;
+    /**
+     * One-shot setup invoked at app boot. Throws abort boot.
+     * Lifecycle hooks run OUTSIDE any request — receive `PluginLifecycleContext`,
+     * not `AppContext`.
+     */
+    readonly onActivate?: PluginActivateHook;
+    /**
+     * One-shot teardown invoked at app shutdown. The framework waits
+     * up to 5s for it to resolve before SIGKILL.
+     */
+    readonly onDeactivate?: PluginDeactivateHook;
+    /**
+     * Contribute to the app's OpenTelemetry observability layer — extra
+     * span processors / metric readers / resource attributes / a sampler.
+     * Gathered at boot (before the tracer builds) and merged into the
+     * framework's NodeSdk ALONGSIDE its own exporter + buffer sink (the
+     * framework keeps owning the tracer — vendor SDKs run as OTel
+     * CONSUMERS, never the global provider, so the in-app Traces dashboard
+     * stays intact). This is how `@voltro/plugin-sentry` /
+     * `@voltro/plugin-datadog` route the framework's spans to the vendor
+     * with zero `OTEL_*` env. The hook may be async (lazy-init the vendor
+     * SDK here). Returns of `undefined`/empty are no-ops.
+     */
+    readonly contributeObservability?: (ctx: PluginLifecycleContext) => Promise<ObservabilityContribution | undefined> | ObservabilityContribution | undefined;
+}
+
+export declare const workflowCancelDescriptor: ActionProcedureDescriptor<"__voltro.workflow.cancel", Schema.Struct<{
+    workflowName: typeof Schema.String;
+    executionId: typeof Schema.String;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, typeof Schema.Never>;
+
+export declare const WorkflowControlInputSchema: Schema.Struct<{
+    workflowName: typeof Schema.String;
+    executionId: typeof Schema.String;
+}>;
+
+export declare type WorkflowDomainEventRow = Schema.Schema.Type<typeof WorkflowDomainEventRowSchema>;
+
+export declare const WorkflowDomainEventRowSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    payload: typeof Schema.Unknown;
+    source: typeof Schema.String;
+    subject: Schema.NullOr<typeof Schema.Unknown>;
+    traceId: Schema.NullOr<typeof Schema.String>;
+    occurredAt: typeof Schema.Date;
+}>;
+
+export declare const WorkflowDomainEventsInputSchema: Schema.Struct<{
+    name: Schema.optional<typeof Schema.String>;
+    limit: Schema.optional<typeof Schema.Number>;
+}>;
+
+export declare const workflowDomainEventsQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.domainEvents", Schema.Struct<{
+    name: Schema.optional<typeof Schema.String>;
+    limit: Schema.optional<typeof Schema.Number>;
+}>, Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    payload: typeof Schema.Unknown;
+    source: typeof Schema.String;
+    subject: Schema.NullOr<typeof Schema.Unknown>;
+    traceId: Schema.NullOr<typeof Schema.String>;
+    occurredAt: typeof Schema.Date;
+}>>, typeof Schema.Never>;
+
+export declare const WorkflowEventDeliveriesInputSchema: Schema.Struct<{
+    eventId: typeof Schema.String;
+}>;
+
+export declare const workflowEventDeliveriesQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.event.deliveries", Schema.Struct<{
+    eventId: typeof Schema.String;
+}>, Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    eventId: typeof Schema.String;
+    eventName: typeof Schema.String;
+    triggerId: typeof Schema.String;
+    workflowName: typeof Schema.String;
+    executionId: Schema.NullOr<typeof Schema.String>;
+    status: Schema.Literal<["starting", "started", "skipped", "failed"]>;
+    idempotencyKey: typeof Schema.String;
+    skipped: typeof Schema.Boolean;
+    errorMessage: Schema.NullOr<typeof Schema.String>;
+    createdAt: typeof Schema.Date;
+    completedAt: Schema.NullOr<typeof Schema.Date>;
+}>>, typeof Schema.Never>;
+
+export declare type WorkflowEventDeliveryRow = Schema.Schema.Type<typeof WorkflowEventDeliveryRowSchema>;
+
+export declare const WorkflowEventDeliveryRowSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    eventId: typeof Schema.String;
+    eventName: typeof Schema.String;
+    triggerId: typeof Schema.String;
+    workflowName: typeof Schema.String;
+    executionId: Schema.NullOr<typeof Schema.String>;
+    status: Schema.Literal<["starting", "started", "skipped", "failed"]>;
+    idempotencyKey: typeof Schema.String;
+    skipped: typeof Schema.Boolean;
+    errorMessage: Schema.NullOr<typeof Schema.String>;
+    createdAt: typeof Schema.Date;
+    completedAt: Schema.NullOr<typeof Schema.Date>;
+}>;
+
+export declare type WorkflowParentClosePolicy = Schema.Schema.Type<typeof WorkflowParentClosePolicySchema>;
+
+export declare const WorkflowParentClosePolicySchema: Schema.Literal<["cancel", "terminate", "abandon"]>;
+
+export declare const workflowResumeDescriptor: ActionProcedureDescriptor<"__voltro.workflow.resume", Schema.Struct<{
+    workflowName: typeof Schema.String;
+    executionId: typeof Schema.String;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, typeof Schema.Never>;
+
+export declare type WorkflowRunEventRow = Schema.Schema.Type<typeof WorkflowRunEventRowSchema>;
+
+export declare const WorkflowRunEventRowSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    runId: typeof Schema.String;
+    eventType: typeof Schema.String;
+    payload: Schema.NullOr<typeof Schema.Unknown>;
+    occurredAt: typeof Schema.Date;
+    stepName: Schema.NullOr<typeof Schema.String>;
+    attempt: Schema.NullOr<typeof Schema.Number>;
+}>;
+
+export declare const workflowRunEventsQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.run.events", Schema.Struct<{
+    /** `_voltro_workflow_runs.id`; step/event rows reference this id. */
+    runId: typeof Schema.String;
+}>, Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    runId: typeof Schema.String;
+    eventType: typeof Schema.String;
+    payload: Schema.NullOr<typeof Schema.Unknown>;
+    occurredAt: typeof Schema.Date;
+    stepName: Schema.NullOr<typeof Schema.String>;
+    attempt: Schema.NullOr<typeof Schema.Number>;
+}>>, typeof Schema.Never>;
+
+export declare type WorkflowRunHandle = Schema.Schema.Type<typeof WorkflowRunHandleSchema>;
+
+export declare const WorkflowRunHandleSchema: Schema.Struct<{
+    /** Stable handle callers pass to `useWorkflowRun(...)`; currently the durable execution id. */
+    id: typeof Schema.String;
+    /** Workflow tag, e.g. `notes.summarise`. */
+    workflowName: typeof Schema.String;
+    /** Deterministic durable id derived from workflow name + idempotency key. */
+    executionId: typeof Schema.String;
+    /** Starting is fire-and-return; waiting is explicit through workflow run APIs. */
+    status: Schema.Literal<["running"]>;
+}>;
+
+export declare const workflowRunQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.run", Schema.Struct<{
+    /** `_voltro_workflow_runs.id` OR durable `executionId`. */
+    id: typeof Schema.String;
+}>, Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    tag: typeof Schema.String;
+    executionId: typeof Schema.String;
+    status: Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>;
+    payload: typeof Schema.Unknown;
+    workflowVersion: Schema.NullOr<typeof Schema.String>;
+    workflowPatches: Schema.NullOr<typeof Schema.Unknown>;
+    output: Schema.NullOr<typeof Schema.Unknown>;
+    subject: Schema.NullOr<typeof Schema.Unknown>;
+    source: Schema.NullOr<typeof Schema.String>;
+    errorTag: Schema.NullOr<typeof Schema.String>;
+    errorMessage: Schema.NullOr<typeof Schema.String>;
+    cancelled: typeof Schema.Boolean;
+    startedAt: typeof Schema.Date;
+    completedAt: Schema.NullOr<typeof Schema.Date>;
+    durationMs: Schema.NullOr<typeof Schema.Number>;
+    traceId: Schema.NullOr<typeof Schema.String>;
+    parentExecutionId: Schema.NullOr<typeof Schema.String>;
+    parentClosePolicy: Schema.NullOr<Schema.Literal<["cancel", "terminate", "abandon"]>>;
+}>>, typeof Schema.Never>;
+
+export declare const WorkflowRunRefSchema: Schema.Struct<{
+    /** `_voltro_workflow_runs.id` OR durable `executionId`. */
+    id: typeof Schema.String;
+}>;
+
+export declare type WorkflowRunRow = Schema.Schema.Type<typeof WorkflowRunRowSchema>;
+
+export declare const WorkflowRunRowSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    tag: typeof Schema.String;
+    executionId: typeof Schema.String;
+    status: Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>;
+    payload: typeof Schema.Unknown;
+    workflowVersion: Schema.NullOr<typeof Schema.String>;
+    workflowPatches: Schema.NullOr<typeof Schema.Unknown>;
+    output: Schema.NullOr<typeof Schema.Unknown>;
+    subject: Schema.NullOr<typeof Schema.Unknown>;
+    source: Schema.NullOr<typeof Schema.String>;
+    errorTag: Schema.NullOr<typeof Schema.String>;
+    errorMessage: Schema.NullOr<typeof Schema.String>;
+    cancelled: typeof Schema.Boolean;
+    startedAt: typeof Schema.Date;
+    completedAt: Schema.NullOr<typeof Schema.Date>;
+    durationMs: Schema.NullOr<typeof Schema.Number>;
+    traceId: Schema.NullOr<typeof Schema.String>;
+    parentExecutionId: Schema.NullOr<typeof Schema.String>;
+    parentClosePolicy: Schema.NullOr<Schema.Literal<["cancel", "terminate", "abandon"]>>;
+}>;
+
+export declare type WorkflowRunsInput = Schema.Schema.Type<typeof WorkflowRunsInputSchema>;
+
+export declare const WorkflowRunsInputSchema: Schema.Struct<{
+    tag: Schema.optional<typeof Schema.String>;
+    status: Schema.optional<Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>>;
+    limit: Schema.optional<typeof Schema.Number>;
+}>;
+
+export declare const workflowRunsQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.runs", Schema.Struct<{
+    tag: Schema.optional<typeof Schema.String>;
+    status: Schema.optional<Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>>;
+    limit: Schema.optional<typeof Schema.Number>;
+}>, Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    tag: typeof Schema.String;
+    executionId: typeof Schema.String;
+    status: Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>;
+    payload: typeof Schema.Unknown;
+    workflowVersion: Schema.NullOr<typeof Schema.String>;
+    workflowPatches: Schema.NullOr<typeof Schema.Unknown>;
+    output: Schema.NullOr<typeof Schema.Unknown>;
+    subject: Schema.NullOr<typeof Schema.Unknown>;
+    source: Schema.NullOr<typeof Schema.String>;
+    errorTag: Schema.NullOr<typeof Schema.String>;
+    errorMessage: Schema.NullOr<typeof Schema.String>;
+    cancelled: typeof Schema.Boolean;
+    startedAt: typeof Schema.Date;
+    completedAt: Schema.NullOr<typeof Schema.Date>;
+    durationMs: Schema.NullOr<typeof Schema.Number>;
+    traceId: Schema.NullOr<typeof Schema.String>;
+    parentExecutionId: Schema.NullOr<typeof Schema.String>;
+    parentClosePolicy: Schema.NullOr<Schema.Literal<["cancel", "terminate", "abandon"]>>;
+}>>, typeof Schema.Never>;
+
+export declare type WorkflowRunStatus = Schema.Schema.Type<typeof WorkflowRunStatusSchema>;
+
+export declare const WorkflowRunStatusSchema: Schema.Literal<["running", "succeeded", "failed", "cancelled", "suspended"]>;
+
+export declare type WorkflowRunStepRow = Schema.Schema.Type<typeof WorkflowRunStepRowSchema>;
+
+export declare const WorkflowRunStepRowSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    runId: typeof Schema.String;
+    stepName: typeof Schema.String;
+    attempt: typeof Schema.Number;
+    status: Schema.Literal<["running", "succeeded", "failed"]>;
+    input: Schema.NullOr<typeof Schema.Unknown>;
+    retryPolicy: Schema.NullOr<typeof Schema.Unknown>;
+    output: Schema.NullOr<typeof Schema.Unknown>;
+    errorTag: Schema.NullOr<typeof Schema.String>;
+    errorMessage: Schema.NullOr<typeof Schema.String>;
+    errorCause: Schema.NullOr<typeof Schema.Unknown>;
+    startedAt: typeof Schema.Date;
+    completedAt: Schema.NullOr<typeof Schema.Date>;
+    durationMs: Schema.NullOr<typeof Schema.Number>;
+}>;
+
+export declare const workflowRunStepsQueryDescriptor: QueryProcedureDescriptor<"__voltro.workflow.run.steps", Schema.Struct<{
+    /** `_voltro_workflow_runs.id`; step/event rows reference this id. */
+    runId: typeof Schema.String;
+}>, Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    runId: typeof Schema.String;
+    stepName: typeof Schema.String;
+    attempt: typeof Schema.Number;
+    status: Schema.Literal<["running", "succeeded", "failed"]>;
+    input: Schema.NullOr<typeof Schema.Unknown>;
+    retryPolicy: Schema.NullOr<typeof Schema.Unknown>;
+    output: Schema.NullOr<typeof Schema.Unknown>;
+    errorTag: Schema.NullOr<typeof Schema.String>;
+    errorMessage: Schema.NullOr<typeof Schema.String>;
+    errorCause: Schema.NullOr<typeof Schema.Unknown>;
+    startedAt: typeof Schema.Date;
+    completedAt: Schema.NullOr<typeof Schema.Date>;
+    durationMs: Schema.NullOr<typeof Schema.Number>;
+}>>, typeof Schema.Never>;
+
+export declare const WorkflowRunTableRefSchema: Schema.Struct<{
+    /** `_voltro_workflow_runs.id`; step/event rows reference this id. */
+    runId: typeof Schema.String;
+}>;
+
+export declare const workflowSignalDescriptor: ActionProcedureDescriptor<"__voltro.workflow.signal", Schema.Struct<{
+    id: typeof Schema.String;
+    signalName: typeof Schema.String;
+    payload: Schema.optional<typeof Schema.Unknown>;
+}>, Schema.Struct<{
+    eventId: typeof Schema.String;
+}>, typeof Schema.Never>;
+
+export declare const WorkflowSignalInputSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    signalName: typeof Schema.String;
+    payload: Schema.optional<typeof Schema.Unknown>;
+}>;
+
+/**
+ * Per-step plugin interceptor. Wraps every `step()` (==
+ * `Activity.make`) invocation inside a workflow body. Composed
+ * across plugins at boot. The interceptor sees the user's `execute`
+ * Effect AS an Effect — it can wrap with `Effect.tap`,
+ * `Effect.retry`, `Effect.withSpan`, etc.
+ *
+ * Useful for: per-step audit beyond the framework's row-recorder,
+ * step-level retry-policy override, step-level resource scoping,
+ * external observability injection.
+ *
+ * The interceptor runs INSIDE `@effect/workflow`'s replay logic —
+ * on a workflow resume, the framework replays cached Activity
+ * outputs without re-running the user effect, and the interceptor
+ * is bypassed on replay (only fires on the first execution).
+ */
+export declare interface WorkflowStepContext {
+    /** Run id from `_voltro_workflow_runs` (`'unrecorded'` outside
+     *  the framework's wrapper, e.g. in unit tests). */
+    readonly runId: string;
+    /** Step name (== first arg of `Activity.make({ name })`). */
+    readonly stepName: string;
+    /** Attempt number — 1 on first try, 2+ on retry. */
+    readonly attempt: number;
+}
+
+export declare type WorkflowStepInterceptor = <Success, ErrorE, R>(next: Effect.Effect<Success, ErrorE, R>, ctx: WorkflowStepContext) => Effect.Effect<Success, ErrorE, R>;
+
+export declare const workflowUpdateDescriptor: ActionProcedureDescriptor<"__voltro.workflow.update", Schema.Struct<{
+    id: typeof Schema.String;
+    updateName: typeof Schema.String;
+    payload: Schema.optional<typeof Schema.Unknown>;
+    timeoutMs: Schema.optional<typeof Schema.Number>;
+}>, Schema.Struct<{
+    eventId: typeof Schema.String;
+    updateId: typeof Schema.String;
+    completedEventId: typeof Schema.String;
+    result: typeof Schema.Unknown;
+}>, typeof Schema.Never>;
+
+export declare const WorkflowUpdateInputSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    updateName: typeof Schema.String;
+    payload: Schema.optional<typeof Schema.Unknown>;
+    timeoutMs: Schema.optional<typeof Schema.Number>;
+}>;
+
+export declare type WorkflowUpdateResult = Schema.Schema.Type<typeof WorkflowUpdateResultSchema>;
+
+export declare const WorkflowUpdateResultSchema: Schema.Struct<{
+    eventId: typeof Schema.String;
+    updateId: typeof Schema.String;
+    completedEventId: typeof Schema.String;
+    result: typeof Schema.Unknown;
+}>;
+
+export { }