@voltro/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1882 @@
+import { ClientDescriptor } from '@voltro/protocol';
+import { ClipboardEvent as ClipboardEvent_2 } from 'react';
+import { Context } from 'react';
+import { DragEvent as DragEvent_2 } from 'react';
+import { Effect } from 'effect';
+import { Fiber } from 'effect';
+import { ManagedRuntime } from 'effect';
+import { ReactNode } from 'react';
+import { Schema } from 'effect';
+import { Stream } from 'effect';
+import { SubscriptionEvent } from '@voltro/protocol';
+import { UIEvent as UIEvent_2 } from 'react';
+import { WorkflowDomainEventRow } from '@voltro/protocol';
+import { WorkflowEventDeliveryRow } from '@voltro/protocol';
+import { WorkflowRunEventRow } from '@voltro/protocol';
+import { WorkflowRunHandle } from '@voltro/protocol';
+import { WorkflowRunRow } from '@voltro/protocol';
+import { WorkflowRunStatus } from '@voltro/protocol';
+import { WorkflowRunStepRow } from '@voltro/protocol';
+import { WorkflowUpdateResult } from '@voltro/protocol';
+
+export declare interface ActionState<Input, Output> {
+    /** Invoke the action. Resolves the typed output or rejects (and sets
+     *  `.error` + emits on the api error bus). */
+    readonly run: (input: Input) => Promise<Output>;
+    /** True while a call is in flight. */
+    readonly pending: boolean;
+    /** The last rejection, or `undefined` if the most recent call succeeded
+     *  (or none has run yet). */
+    readonly error: unknown | undefined;
+    /** The most recent successful result, or `undefined`. */
+    readonly lastResult: Output | undefined;
+}
+
+/** Mirrors `@voltro/protocol/scopes` ADMIN_SCOPE — an admin satisfies any
+ *  required scope. Inlined so the client stays decoupled from server code. */
+export declare const ADMIN_SCOPE = "admin:full";
+
+export declare interface AgentChatMessage {
+    readonly id: string;
+    readonly role: string;
+    readonly content: string;
+    readonly streaming: boolean;
+    readonly order: number;
+    readonly stepOrder?: number;
+    readonly parts?: ReadonlyArray<AgentChatPart>;
+}
+
+/** One rendered segment of an assistant (or user) turn, persisted in the
+ *  agent_messages row's `parts` JSON. Structural — the client stays
+ *  AI-package-agnostic (mirrors @voltro/ai's part union). */
+export declare type AgentChatPart = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'reasoning';
+    readonly text: string;
+} | {
+    readonly type: 'tool';
+    readonly toolName: string;
+    readonly state?: string;
+    readonly input?: unknown;
+    readonly output?: unknown;
+} | {
+    readonly type: 'source';
+    readonly sourceType?: string;
+    readonly id?: string;
+    readonly url?: string;
+    readonly title?: string;
+} | {
+    readonly type: 'file';
+    readonly mediaType: string;
+    readonly data: string;
+} | {
+    readonly type: string;
+    readonly [k: string]: unknown;
+};
+
+export declare interface AgentChatState {
+    readonly messages: ReadonlyArray<AgentChatMessage>;
+    /** True while any row is `streaming:true` (the live typewriter turn). */
+    readonly streaming: boolean;
+    readonly loading: boolean;
+    readonly error: unknown | undefined;
+    /** Send a user turn; the assistant turn streams back into `messages`. */
+    readonly send: (prompt: string, extra?: Readonly<Record<string, unknown>>) => Promise<unknown>;
+    /** Re-run the last user prompt as a fresh turn. No-op if none. */
+    readonly regenerate: () => Promise<unknown> | undefined;
+    readonly sending: boolean;
+}
+
+export declare interface AgentControls {
+    /** The assistant text streamed so far for the in-flight run. */
+    readonly tokens: string;
+    /** Accumulated completed turns across runs. */
+    readonly history: ReadonlyArray<AgentTurn>;
+    readonly status: AgentStreamStatus;
+    readonly error: unknown | undefined;
+    /** Begin a run. When `input.message` is a string it's appended to history
+     *  on completion (paired with the assistant reply). */
+    readonly send: (input?: Readonly<Record<string, unknown>>) => void;
+    readonly cancel: () => void;
+}
+
+export declare interface AgentStreamControls<E> extends AgentStreamState<E> {
+    /** Begin a run with `input`. Resets prior events; replaces any in-flight run. */
+    readonly start: (input?: Readonly<Record<string, unknown>>) => void;
+    /** Interrupt the in-flight run (its server-side scope tears down). */
+    readonly cancel: () => void;
+}
+
+export declare interface AgentStreamState<E> {
+    /** Elements received so far, in order. */
+    readonly events: ReadonlyArray<E>;
+    readonly status: AgentStreamStatus;
+    /** Set when status === 'error'. */
+    readonly error: unknown | undefined;
+}
+
+export declare type AgentStreamStatus = 'idle' | 'streaming' | 'done' | 'error';
+
+export declare interface AgentTurn {
+    readonly role: 'user' | 'assistant';
+    readonly content: string;
+}
+
+export declare interface Analytics<E extends ReadonlyArray<EventDescriptor<string, unknown>>> {
+    /** Emit an event — name + payload typed by the catalog; validated at runtime. */
+    readonly track: <K extends keyof EventMap<E> & string>(name: K, payload: EventMap<E>[K]) => void;
+    readonly names: ReadonlyArray<string>;
+    readonly catalog: EventCatalog;
+}
+
+export declare type AnyRuntime = ManagedRuntime.ManagedRuntime<never, never>;
+
+export declare interface ApiHandle {
+    readonly runtime: AnyRuntime;
+    readonly cache: SubscriptionCache;
+    /** Resolved typed rpc client. Methods nest by tag (`todos.list` →
+     *  `client.todos.list`). Hooks walk by tag-segment (see `resolveByTag`)
+     *  to invoke, so the static type here is the erased `unknown`; the typed
+     *  view comes from `useAppClient<T>(name)` at the call site. */
+    readonly client: unknown;
+    /** Per-rpc-tag descriptor metadata. Drives auto-optimistic and source-
+     *  based cache routing. */
+    readonly descriptors: Readonly<Record<string, ClientDescriptor>>;
+    /**
+     * Base HTTP origin where the api's `/_voltro/inspect/*` endpoints
+     * live. Derived from `wsUrl` at mount time (`ws://host:port/ws` →
+     * `http://host:port`). DevTools and any inspect-consuming tooling
+     * use this for the metrics / subscriptions / events endpoints.
+     */
+    readonly inspectBaseUrl: string;
+    /** Per-api error bus. Mutations + subscription failures land here so
+     *  app-level listeners can react to typed errors globally (auto-logout
+     *  on `Unauthenticated`, network-error toasts, etc.). */
+    readonly errorBus: RpcErrorBus;
+}
+
+export declare interface AsyncValidationResult {
+    readonly status: ValidationStatus;
+    readonly valid: boolean | undefined;
+    readonly message: string | undefined;
+}
+
+/**
+ * Auto-apply target as seen from the client. Identical shape to the
+ * server's TargetSpec but with all schema generics erased (the client
+ * sees concrete row shapes at runtime, not Schema instances).
+ *
+ * Optional overrides:
+ *   - `shape`     for insert: build the row from input + optimistic id
+ *                 for update: build the patched row from (input, current)
+ *   - `identify`  for update/delete: extract the row id from input
+ *                 (defaults to `input.id`)
+ *   - `order`     for insert: 'prepend' (default) or 'append'
+ */
+export declare interface AutoApplyTarget {
+    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;
+}
+
+declare interface CacheEntry {
+    readonly key: string;
+    /** First element of the keyArr — the rpc tag (e.g. 'todos.list'). Used
+     *  by `forTag()` so callers can patch every sub-key for a tag without
+     *  knowing the inputs. Captured at create-time so updates without a
+     *  prior subscribe still work (stub entries get tag too). */
+    readonly tag: string | undefined;
+    state: EntryState<unknown>;
+    /** Subscriber re-render callbacks. */
+    subscribers: Set<() => void>;
+    /** Fiber running the underlying stream. */
+    fiber: Fiber.RuntimeFiber<unknown, unknown> | null;
+    /** Pending eviction (last subscriber gone, TTL countdown). */
+    evictionTimer: NodeJS.Timeout | null;
+    /** Source table(s) this entry reads (from the rpc descriptor). Used by
+     *  auto-optimistic to find which entries to patch when a mutation with
+     *  a matching `target.table` is invoked — an array matches if the target is
+     *  among the listed tables. May be undefined for queries whose source isn't
+     *  expressed as table(s) (joins, aggregates). */
+    source: string | ReadonlyArray<string> | undefined;
+    /** True once a server snapshot reported this query as COMPUTED (handler
+     *  returns a shaped value, not a table row-set). Auto-optimistic skips
+     *  blind INSERTs into computed entries — the client can't evaluate the
+     *  query's opaque server-side filter to know if a new row belongs, so it
+     *  defers to the authoritative recompute push. UPDATE/DELETE (matched by
+     *  id) still apply. Defaults false until the first snapshot resolves it. */
+    computed: boolean;
+    /** Saved `fetch` thunk from the first subscribe(). Used by `refreshAll()`
+     *  to re-issue the WS subscription after a connection-subject re-bind
+     *  (e.g. soft re-auth after login). Each subscriber's hook keeps its
+     *  own fetch closure, but only the first one's identity matters — the
+     *  server-side subscription is one per cache-entry key, not per
+     *  subscriber. */
+    fetch: (() => Stream.Stream<SubscriptionEvent<unknown>, unknown, never>) | null;
+    /** W3C trace id of the live stream, captured when the fiber starts.
+     *  Shared with the server (the subscription span propagates it) and
+     *  attached to error-bus events so a failure points at the right
+     *  `voltro logs --trace <id>`. */
+    traceId?: string;
+}
+
+/** Plain-data snapshot of a single cache entry for devtools / test
+ *  introspection. Doesn't carry the live fiber or React-subscriber
+ *  set — those are kept private. */
+export declare interface CacheEntrySnapshot {
+    readonly key: string;
+    readonly tag: string | undefined;
+    readonly source: string | ReadonlyArray<string> | undefined;
+    readonly subscriberCount: number;
+    /** True while the underlying stream's fiber is running. */
+    readonly hasFiber: boolean;
+    /** True after the last subscriber left and the eviction TTL is
+     *  counting down — a quick remount within the window resurrects. */
+    readonly evicting: boolean;
+    readonly snapshot: CacheSnapshot<unknown>;
+}
+
+export declare interface CacheSnapshot<T> {
+    /** Current visible data = base + all live patches applied in order. */
+    readonly data: T | undefined;
+    /** Most recent revision the server delivered. -1 if no snapshot yet. */
+    readonly revision: number;
+    /** Wall-clock ms when the most recent server delta was emitted; undefined for snapshots. */
+    readonly emittedAt: number | undefined;
+    /** Error from the underlying stream (if no snapshot has ever arrived). */
+    readonly error: unknown | undefined;
+    /** Number of live optimistic patches currently applied. */
+    readonly pendingPatches: number;
+}
+
+/** Does a subject with `subjectScopes` satisfy `required`? ADMIN bypasses;
+ *  an empty requirement is always allowed. Pure — the matcher core. */
+export declare const canCall: (subjectScopes: ReadonlyArray<string>, required: string | ReadonlyArray<string>) => boolean;
+
+/** Structural mirror of @voltro/cli's `CapabilityManifestTable` column — the
+ *  client stays decoupled from the (node-only) cli package. */
+export declare interface CapabilityColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+    /** Set when this column is a foreign key — the table it points at. */
+    readonly refersTo?: string;
+    /** Closed value set (`text().oneOf([...])`) → render a select. */
+    readonly enum?: ReadonlyArray<string>;
+}
+
+/** Structural mirror of @voltro/cli's `CapabilityManifest` (served at
+ *  `GET /_voltro/inspect/manifest`). */
+export declare interface CapabilityManifest {
+    readonly version: number;
+    readonly procedures: ReadonlyArray<CapabilityProcedure>;
+    readonly workflows: ReadonlyArray<{
+        readonly name: string;
+    }>;
+    readonly widgets: ReadonlyArray<string>;
+    readonly tables: ReadonlyArray<CapabilityTable>;
+}
+
+export declare interface CapabilityManifestState {
+    readonly manifest: CapabilityManifest | undefined;
+    readonly loading: boolean;
+    readonly error: unknown | undefined;
+}
+
+/** A procedure in the manifest. `source` is the table a query reads;
+ *  `targets` are the tables+ops a mutation writes. */
+export declare interface CapabilityProcedure {
+    readonly tag: string;
+    readonly kind: string;
+    readonly input?: Readonly<Record<string, unknown>>;
+    readonly output?: Readonly<Record<string, unknown>>;
+    readonly source?: string | ReadonlyArray<string>;
+    readonly targets?: ReadonlyArray<{
+        readonly table: string;
+        readonly op: string;
+    }>;
+}
+
+/** A user table in the manifest (framework `_voltro_*` tables are excluded). */
+export declare interface CapabilityTable {
+    readonly name: string;
+    readonly columns: ReadonlyArray<CapabilityColumn>;
+    readonly reactive: boolean;
+    readonly framework: boolean;
+}
+
+/** Clear the buffer (devtools "Clear" button). */
+export declare const clearMutations: () => void;
+
+/** Drop successfully-sent entries (call after a drain to compact the queue). */
+export declare const clearSent: (queue: Outbox) => Outbox;
+
+export declare const CLIENT_NAME: "framework-client";
+
+export declare interface ClientErrorEvent {
+    /** The thrown value (Error | anything). */
+    readonly error: unknown;
+    /** Where it came from. `route` = caught by the framework's route
+     *  ErrorBoundary (render OR loader); `manual` = app called a capture helper. */
+    readonly source: 'route' | 'manual';
+    /** React component stack, when the route boundary caught a render error. */
+    readonly componentStack?: string;
+    /** Active pathname at the time, for context. */
+    readonly pathname?: string;
+    /** Optional caller-supplied extra context (manual captures). */
+    readonly context?: Record<string, unknown>;
+}
+
+declare type ClientErrorListener = (event: ClientErrorEvent) => void;
+
+export declare interface ClientTraceEvent {
+    /** W3C trace id (32 hex) of the call the client just started. */
+    readonly traceId: string;
+    /** W3C span id (16 hex) of the client span — the parent the server
+     *  continues from. Lets a vendor integration (Sentry) place the
+     *  browser-side span in the SAME trace tree as the server transaction. */
+    readonly spanId: string;
+    /** `'mutation'` | `'action'` | `'subscription'` — which surface started it. */
+    readonly source: 'mutation' | 'action' | 'subscription';
+    /** RPC tag (e.g. `'todos.create'`). */
+    readonly tag: string;
+}
+
+declare type ClientTraceListener = (event: ClientTraceEvent) => void;
+
+/** Pure virtualization math: scroll position → the row window to fetch +
+ *  the spacer heights. `total` (when known) caps the window + sizes the bottom
+ *  spacer; without it, infinite-scroll (bottomSpacer 0). */
+export declare const computeWindow: (args: {
+    readonly scrollTop: number;
+    readonly viewportHeight: number;
+    readonly rowHeight: number;
+    readonly overscan?: number;
+    readonly total?: number;
+}) => WindowSpec;
+
+/**
+ * The wire shape a data-copilot action returns. Mirror it in the action's
+ * `output` schema — a refusal carries the human-readable `reason` (derived
+ * from the typed `CopilotRejected`), a success carries the result `rows`.
+ * Modelled as a successful response either way: a refused question is a
+ * normal answer with `ok: false`, NOT a thrown error (that's reserved for
+ * transport / execution failures).
+ */
+export declare type CopilotAnswer<Row = Record<string, unknown>> = {
+    readonly ok: true;
+    readonly rows: ReadonlyArray<Row>;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
+/**
+ * Build a typed analytics surface from a declared event list + a sink. `track`
+ * is typed against the catalog; on a payload that fails its Schema it logs a
+ * loud dev error (the "bad event shape is loud" rule) and still forwards (best-
+ * effort — losing the event would be worse than a slightly-off payload).
+ */
+export declare const createAnalytics: <const E extends ReadonlyArray<EventDescriptor<string, unknown>>>(events: E, sink: TrackingSink) => Analytics<E>;
+
+export declare interface DataCopilotState<Row = Record<string, unknown>> {
+    /** Ask a natural-language question. Resolves the typed answer (also stored
+     *  on `.answer`); rejects only on a transport / execution error. */
+    readonly ask: (question: string) => Promise<CopilotAnswer<Row>>;
+    /** The most recent answer (rows or refusal), or `undefined` before the
+     *  first `ask` (or after `reset`). */
+    readonly answer: CopilotAnswer<Row> | undefined;
+    /** True while a question is in flight. */
+    readonly pending: boolean;
+    /** The last transport / execution error, or `undefined`. A REFUSAL is not
+     *  an error — it arrives as `answer.ok === false`. */
+    readonly error: unknown | undefined;
+    /** Clear the stored answer. */
+    readonly reset: () => void;
+}
+
+export declare interface DataTableState<Row> {
+    /** Columns derived from the query's output Schema (or the explicit override). */
+    readonly columns: ReadonlyArray<FieldDescriptor>;
+    /** Live rows (sorted if a sort is active). */
+    readonly rows: ReadonlyArray<Row>;
+    readonly loading: boolean;
+    readonly error: unknown | undefined;
+    readonly sort: SortState | undefined;
+    /** Toggle/clear sort on a column (asc → desc → asc …). */
+    readonly toggleSort: (column: string) => void;
+    /** Grow the window by one page (only meaningful with `pageSize`). */
+    readonly loadMore: () => void;
+    /** True when the last window came back full — there may be more rows.
+     *  Always false without `pageSize`. */
+    readonly hasMore: boolean;
+}
+
+/** Declare a typed analytics event. */
+export declare const defineEvent: <const Name extends string, A, I>(name: Name, payload: Schema.Schema<A, I>) => EventDescriptor<Name, A>;
+
+/** Identity helper (like `defineTracking('CheckoutButton', { onMount: 'checkout.viewed' })`). */
+export declare const defineTracking: (name: string, map: TrackingMap) => TrackingSpec;
+
+/**
+ * Pure projection: turn a capability manifest into one `EntityAdminSpec` per
+ * user table, each joined to the query that lists it and the mutations that
+ * create/update/delete it. The auto-admin template maps over the result to
+ * render a live, permission-gated back-office; everything here is derived from
+ * what the app actually exposes, so an entity with no list query simply renders
+ * no table rather than binding to a tag that 404s.
+ */
+export declare const deriveEntityAdmins: (manifest: CapabilityManifest) => ReadonlyArray<EntityAdminSpec>;
+
+export declare const enqueueEntry: (queue: Outbox, id: string, tag: string, input: unknown) => Outbox;
+
+/** One entity's admin surface: the table + the procedures that read/write it,
+ *  plus the conventional scope strings the UI gates writes on. A tag is
+ *  `undefined` when the app exposes no procedure for that op (the admin then
+ *  renders that affordance read-only / hidden). */
+export declare interface EntityAdminSpec {
+    readonly table: string;
+    readonly columns: ReadonlyArray<CapabilityColumn>;
+    readonly reactive: boolean;
+    /** Query whose `source` is this table → drives <DataTable>. */
+    readonly listTag?: string;
+    /** Mutation targeting `{table, op:'insert'}` → drives the create <AutoForm>. */
+    readonly createTag?: string;
+    /** Mutation targeting `{table, op:'update'}` → row edit. */
+    readonly updateTag?: string;
+    /** Mutation targeting `{table, op:'delete'}` → row delete. */
+    readonly deleteTag?: string;
+    /** Conventional scope strings the admin gates on via `useCan`. The app maps
+     *  these to its real RBAC scopes; absent a scope registry in the manifest
+     *  this convention is the seam (gate at the action level — round-2/07 adds
+     *  row-level authority). */
+    readonly createScope: string;
+    readonly writeScope: string;
+    readonly deleteScope: string;
+}
+
+declare interface EntryState<T> {
+    /** Last server-delivered data (base for patches). */
+    base: T | undefined;
+    baseRevision: number;
+    baseEmittedAt: number | undefined;
+    baseError: unknown | undefined;
+    patches: Array<OptimisticPatch<T>>;
+    /** Cached optimistic snapshot — invalidated on every state change so
+     *  `getSnapshot` returns a stable reference between mutations. */
+    cachedSnapshot: CacheSnapshot<T> | null;
+}
+
+/** Helper: pattern-match the `_tag` field on a thrown error value. Works
+ *  on Schema.TaggedError instances + plain `{_tag: ..., …}` objects the
+ *  rpc wire emits. Returns undefined for non-tagged errors. */
+export declare const errorTag: (err: unknown) => string | undefined;
+
+export declare interface EventCatalog {
+    readonly names: ReadonlyArray<string>;
+    readonly get: (name: string) => EventDescriptor<string, unknown> | undefined;
+    /** Discovery inventory: every event's name + its JSON-Schema-able payload. */
+    readonly events: ReadonlyArray<EventDescriptor<string, unknown>>;
+}
+
+export declare const eventCatalog: (events: ReadonlyArray<EventDescriptor<string, unknown>>) => EventCatalog;
+
+export declare interface EventDescriptor<Name extends string, A> {
+    readonly name: Name;
+    /** The payload Schema, erased — `Schema` is INVARIANT in its decoded type, so
+     *  storing `Schema.Schema<A>` here would make `EventDescriptor` invariant in
+     *  `A` and break a heterogeneous catalog. The decoded type is carried by the
+     *  covariant phantom `_type` below instead, so `EventDescriptor<string,
+     *  unknown>` accepts every typed descriptor AND `track` stays typed. */
+    readonly payload: Schema.Schema.Any;
+    /** Phantom — never present at runtime; carries the decoded payload type for
+     *  `track`'s compile-time signature. Covariant (optional), so erasure works. */
+    readonly _type?: A;
+}
+
+/** Map a tuple of event descriptors → `{ name: payloadType }` for typing track.
+ *  The covariant `_type` phantom lets `EventDescriptor<string, unknown>` accept
+ *  every typed descriptor as a constraint while inference still recovers `A`. */
+declare type EventMap<E extends ReadonlyArray<EventDescriptor<string, unknown>>> = {
+    [D in E[number] as D['name']]: D extends EventDescriptor<string, infer A> ? A : never;
+};
+
+export declare interface EventValidation {
+    readonly valid: boolean;
+    /** `path` → message, empty when valid. */
+    readonly errors: Readonly<Record<string, string>>;
+}
+
+export declare interface FieldDescriptor {
+    /** Property name on the input object. */
+    readonly name: string;
+    /** Human label — the Schema `title` annotation, else the humanised name. */
+    readonly label: string;
+    /** The default widget kind. `'custom'` ⇒ supply a render-prop. */
+    readonly widget: WidgetKind;
+    /** True when the property must be present (in JSON-Schema `required`). */
+    readonly required: boolean;
+    /** True when the value may be `null` (e.g. `Schema.NullOr`). */
+    readonly nullable: boolean;
+    /** Present for closed value sets (a `Schema.Literal` union → `select`). */
+    readonly options?: ReadonlyArray<FieldOption>;
+    /** The resolved JSON-Schema node — carries `maxLength` / `pattern` /
+     *  `minimum` / `format` / `description` for widgets + validation hints. */
+    readonly jsonSchema: Readonly<Record<string, unknown>>;
+}
+
+export declare interface FieldErrors {
+    readonly [field: string]: string;
+}
+
+export declare interface FieldOption {
+    readonly value: string;
+    readonly label: string;
+}
+
+export declare interface FilterDescriptor {
+    readonly name: string;
+    readonly label: string;
+    readonly kind: FilterKind;
+    /** Present for `select` / `multi-select` (from an enum field). */
+    readonly options?: ReadonlyArray<FieldOption>;
+}
+
+export declare type FilterKind = 'text' | 'select' | 'multi-select' | 'number-range' | 'date-range' | 'boolean';
+
+/** Derive the filter controls from a query's input Schema. Each filterable
+ *  input field → one FilterDescriptor. Pure. */
+export declare const filtersFromSchema: (schema: Schema.Schema.Any) => ReadonlyArray<FilterDescriptor>;
+
+export declare interface FormBinding<Input, Output> {
+    /** Ordered, render-agnostic field list derived from the input schema. */
+    readonly fields: ReadonlyArray<FieldDescriptor>;
+    readonly values: Partial<Input>;
+    /** First error per field — populated on submit. */
+    readonly errors: FieldErrors;
+    /** True when the CURRENT values decode against the schema. */
+    readonly isValid: boolean;
+    readonly pending: boolean;
+    /** The mutation's typed failure, if the last submit threw. */
+    readonly submitError: unknown | undefined;
+    readonly data: Output | undefined;
+    readonly setValue: (name: string, value: unknown) => void;
+    readonly setValues: (patch: Partial<Input>) => void;
+    readonly reset: () => void;
+    /** Validate; if valid, run the mutation. Returns the output, or `undefined`
+     *  when validation blocked the submit. */
+    readonly submit: () => Promise<Output | undefined>;
+}
+
+export declare interface FrameworkRuntimes {
+    /** Look up an api handle (runtime + cache) by name. Throws if no such api was mounted. */
+    readonly get: (name: string) => ApiHandle;
+    /** Enumerate the names of currently-installed apis (for debug). */
+    readonly names: ReadonlyArray<string>;
+}
+
+export declare const FrameworkRuntimesContext: Context<FrameworkRuntimes | null>;
+
+export declare const FrameworkRuntimesProvider: ({ apis, children, }: FrameworkRuntimesProviderProps) => ReactNode;
+
+export declare interface FrameworkRuntimesProviderProps {
+    readonly apis: ReadonlyMap<string, ApiHandle>;
+    readonly children: ReactNode;
+}
+
+/** Read the current feed. Newest-first; up to MAX_MUTATIONS entries. */
+export declare const getMutations: () => ReadonlyArray<MutationEvent>;
+
+/**
+ * Non-fetching cache used as a LOADING baseline:
+ *   - during SSR (no runtime / no provider), and
+ *   - on the client's first render(s) before the api supervisor has
+ *     resolved a configured api's runtime + client.
+ *
+ * It subclasses the real cache so it carries the FULL method surface
+ * (`peek` / `peekAll` / `update` / `forTag` / `refreshAll` / …) — a
+ * hand-rolled partial stub broke the moment a consumer (e.g. devtools)
+ * called a method it didn't implement. The ONLY override is `subscribe`:
+ * it must NOT open a real stream, because the supplied runtime is a stub
+ * that can't fork fibers. It hands back an empty snapshot so the component
+ * renders its loading state; when the real client resolves, FrameworkBoot
+ * swaps in the real cache and the component re-subscribes for live data.
+ * Every other inherited method operates on an always-empty entry map, so
+ * they're inherently safe no-ops.
+ */
+export declare class LoadingSubscriptionCache extends SubscriptionCache {
+    subscribe(keyArr: ReadonlyArray<unknown>, _fetch: () => Stream.Stream<SubscriptionEvent<unknown>, unknown, never>, _runtime: AnyRuntime, _onChange: () => void, _options?: {
+        readonly source?: string | ReadonlyArray<string>;
+    }): {
+        readonly getSnapshot: () => CacheSnapshot<unknown>;
+        readonly unsubscribe: () => void;
+    };
+}
+
+/** Exported for tests: the inspect URL this hook fetches. */
+export declare const manifestUrl: (base: string) => string;
+
+export declare const markConflict: (queue: Outbox, id: string, error: unknown) => Outbox;
+
+export declare const markFailed: (queue: Outbox, id: string, error: unknown) => Outbox;
+
+export declare const markSent: (queue: Outbox, id: string) => Outbox;
+
+export declare interface MutationBuilder<Input, Output> extends MutationState<Input, Output> {
+    /** Override auto-optimistic with a custom reducer. */
+    readonly withOptimistic: (optimistic: OptimisticFn<Input>) => MutationBuilder<Input, Output>;
+    /** Disable auto-optimistic entirely (useful for mutations whose
+     *  effect must NOT preview locally — payments, sends, etc.). */
+    readonly withoutOptimistic: () => MutationBuilder<Input, Output>;
+}
+
+export declare interface MutationEvent {
+    /** Stable id of the mutation invocation. Matches the cache's
+     *  optimistic-patch mutationId so panels can correlate. */
+    readonly id: string;
+    /** Api name the mutation was dispatched on. */
+    readonly apiName: string;
+    /** Rpc tag (e.g. `'todos.create'`). */
+    readonly tag: string;
+    /** Status — published as 'pending' on start, transitions to
+     *  'success' or 'error' on settle. */
+    readonly status: MutationStatus;
+    /** Resolved input (after the descriptor's schema parse). */
+    readonly input: unknown;
+    /** Resolved output on success. */
+    readonly output?: unknown;
+    /** Thrown / rejected error on failure. */
+    readonly error?: unknown;
+    /** Wall-clock ms when the mutation started. */
+    readonly startedAt: number;
+    /** Wall-clock ms when the mutation settled. Undefined while pending. */
+    readonly settledAt?: number;
+    /** durationMs = settledAt - startedAt. Convenience field. */
+    readonly durationMs?: number;
+}
+
+export declare interface MutationState<Input, Output> {
+    readonly mutate: (input: Input) => Promise<Output>;
+    readonly pending: boolean;
+    readonly error: unknown | undefined;
+    readonly data: Output | undefined;
+}
+
+export declare type MutationStatus = 'pending' | 'success' | 'error';
+
+export declare interface OptimisticContext {
+    /** Stage an optimistic patch keyed by `queryKey` (same convention as
+     *  useSubscription's: `[rpcTag, input]`). The patch is automatically
+     *  reverted when the enclosing mutation resolves (success or failure).
+     *  Use when you know the EXACT input the subscription was opened with. */
+    readonly update: <T>(queryKey: ReadonlyArray<unknown>, reducer: (current: T) => T) => void;
+    /** Patch every cached entry whose rpc tag matches `rpcTag`, regardless
+     *  of input. Use for sourceless queries (joins, aggregates, custom
+     *  projections) where the auto-optimistic source-router can't see what
+     *  to patch — and you don't know what inputs are currently subscribed
+     *  to. Returns the number of patched entries (0 means no current
+     *  subscribers for that tag). */
+    readonly forTag: <T>(rpcTag: string, reducer: (current: T) => T) => {
+        readonly patchedCount: number;
+    };
+}
+
+export declare type OptimisticFn<Input> = (cache: OptimisticContext, input: Input) => void;
+
+declare interface OptimisticPatch<T = unknown> {
+    readonly id: string;
+    readonly mutationId: string;
+    readonly reducer: (current: T) => T;
+    /** Set once the mutation SUCCEEDED. A confirmed patch stays applied (so the
+     *  optimistic preview never blinks out) until a server snapshot/delta updates
+     *  `base` to reflect the committed write — only THEN is it dropped. Without
+     *  this, dropping the patch on mutation-resolve reveals a still-stale base
+     *  before the (CDC-latent) delta arrives → the on→off→on toggle flash. */
+    confirmed?: boolean;
+}
+
+export declare type Outbox = ReadonlyArray<OutboxEntry>;
+
+export declare interface OutboxControls {
+    readonly queue: Outbox;
+    readonly enqueue: (tag: string, input: unknown) => void;
+    readonly replay: () => Promise<void>;
+    readonly online: boolean;
+    readonly pending: number;
+    readonly conflicts: ReadonlyArray<OutboxEntry>;
+}
+
+export declare interface OutboxEntry {
+    readonly id: string;
+    readonly tag: string;
+    readonly input: unknown;
+    readonly status: OutboxStatus;
+    readonly attempts: number;
+    readonly error?: unknown;
+}
+
+export declare type OutboxStatus = 'pending' | 'sent' | 'failed' | 'conflict';
+
+/** Provide the current subject's scopes to `useCan`. Mount it once high in the
+ *  tree, fed by your session subscription so it updates on role changes. */
+export declare function PermissionProvider(props: PermissionProviderProps): ReactNode;
+
+export declare interface PermissionProviderProps {
+    /** The current subject's scopes (from your session query — reactive). */
+    readonly scopes: ReadonlyArray<string>;
+    readonly children: ReactNode;
+}
+
+declare interface PermissionState_2 {
+    readonly scopes: ReadonlyArray<string>;
+}
+export { PermissionState_2 as PermissionState }
+
+/** Structural mirror of @voltro/runtime's PreviewDiff (client stays decoupled). */
+export declare interface PreviewDiff {
+    readonly rows: ReadonlyArray<PreviewRowDiff>;
+    readonly summary: {
+        readonly inserts: number;
+        readonly updates: number;
+        readonly deletes: number;
+    };
+}
+
+export declare interface PreviewFieldChange {
+    readonly from: unknown;
+    readonly to: unknown;
+}
+
+export declare interface PreviewRowDiff {
+    readonly table: string;
+    readonly op: 'insert' | 'update' | 'delete';
+    readonly id: string | undefined;
+    readonly fields: Readonly<Record<string, PreviewFieldChange>>;
+}
+
+export declare interface PreviewState<Input> {
+    readonly preview: (input: Input) => Promise<PreviewDiff>;
+    readonly diff: PreviewDiff | undefined;
+    readonly pending: boolean;
+    readonly error: unknown | undefined;
+}
+
+export declare interface ProvenanceResult {
+    readonly table: string;
+    readonly id: string;
+    readonly column?: string;
+    readonly value: unknown;
+    readonly lastWrite: ProvenanceWrite | null;
+    readonly attribution: 'audit' | 'none';
+    readonly derived?: boolean;
+    readonly history?: ReadonlyArray<ProvenanceWrite>;
+    readonly found: boolean;
+}
+
+export declare interface ProvenanceState {
+    readonly data: ProvenanceResult | undefined;
+    readonly loading: boolean;
+    readonly error: unknown | undefined;
+}
+
+/** Exported for tests: the inspect URL this hook fetches. */
+export declare const provenanceUrl: (base: string, table: string, id: string, column?: string) => string;
+
+/** Structural mirror of @voltro/runtime's `ProvenanceResult` — the client
+ *  stays decoupled from the server package. */
+export declare interface ProvenanceWrite {
+    readonly actor: {
+        readonly id: string | null;
+        readonly kind?: string;
+        readonly via?: string;
+    } | null;
+    readonly at: string | null;
+    readonly traceId?: string | null;
+    readonly value?: unknown;
+}
+
+/** Publish a client error. Cheap + sync; a broken listener can't break the caller. */
+export declare const publishClientError: (event: ClientErrorEvent) => void;
+
+/** Publish a started client trace. Cheap + sync; safe on the hot path. */
+export declare const publishClientTrace: (event: ClientTraceEvent) => void;
+
+export declare interface QueryFieldState {
+    readonly options: ReadonlyArray<FieldOption>;
+    readonly loading: boolean;
+    readonly term: string;
+    readonly search: (term: string) => void;
+}
+
+export declare interface QueryFiltersState<Row> {
+    readonly filters: ReadonlyArray<FilterDescriptor>;
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly setFilter: (name: string, value: unknown) => void;
+    readonly clear: () => void;
+    /** Live result rows for the current filter values. */
+    readonly rows: ReadonlyArray<Row>;
+    /** Live result count (undefined until first snapshot). */
+    readonly count: number | undefined;
+    readonly loading: boolean;
+    readonly error: unknown | undefined;
+}
+
+export declare interface RecordState<R> {
+    readonly record: R | undefined;
+    readonly loading: boolean;
+    readonly error: unknown | undefined;
+}
+
+/**
+ * The entries to replay, in FIFO order, UP TO (not including) the first
+ * conflict — a conflicted write blocks everything after it (causality). Sent
+ * entries are skipped; pending + failed are replayable.
+ */
+export declare const replayable: (queue: Outbox) => Outbox;
+
+/** Report an error to every subscribed reporter (e.g. Sentry). Safe no-op
+ *  when nothing is subscribed. The ergonomic manual-capture entry point —
+ *  call it from a try/catch in an event handler, an async effect, anywhere
+ *  the route boundary won't catch the throw. */
+export declare const reportClientError: (error: unknown, context?: Record<string, unknown>) => void;
+
+/** Test-only: reset the one-time no-provider dev-warning state (the
+ *  module-global flags + any pending grace-period timer). */
+export declare const _resetFrameworkRuntimesWarning: () => void;
+
+export declare const resolveByTag: (client: unknown, tag: string) => unknown;
+
+/** Resolve one map entry against the props. Pure. */
+export declare const resolveTrackingEvent: (entry: TrackingEntry | undefined, props: Record<string, unknown>) => TrackingEvent | null;
+
+export declare interface ResourceCanInput {
+    /** The action being gated (e.g. `'read'`, `'write'`, `'delete'`). */
+    readonly action: string;
+    /** The resource's policy type (matches a `defineResourcePolicy` type). */
+    readonly resourceType: string;
+    /** The specific resource id. */
+    readonly resourceId: string;
+}
+
+/** The wire shape the server's single-resource can-query returns. */
+export declare interface ResourceCanResult {
+    readonly allowed: boolean;
+}
+
+export declare interface ResourceCansInput {
+    readonly action: string;
+    readonly resourceType: string;
+    /** The resource ids to check in ONE round-trip (e.g. a table page's rows). */
+    readonly resourceIds: ReadonlyArray<string>;
+}
+
+/** The wire shape the server's batch can-query returns — the SUBSET of the
+ *  input ids the subject may act on. */
+export declare interface ResourceCansResult {
+    readonly allowedIds: ReadonlyArray<string>;
+}
+
+export declare interface ResumableAgentStreamControls<E> extends ResumableAgentStreamState<E> {
+    /** Begin a run. `input` MUST carry the resume key (`streamId`) so reconnects
+     *  target the same server-side log; `fromSeq` is injected by the hook. */
+    readonly start: (input?: Readonly<Record<string, unknown>>) => void;
+    /** Stop the run + cancel any pending reconnect (its server scope tears down). */
+    readonly cancel: () => void;
+}
+
+export declare interface ResumableAgentStreamOptions<E> {
+    readonly maxReconnects?: number;
+    readonly backoffMs?: number;
+    readonly maxBackoffMs?: number;
+    /** Decide if an inner event is TERMINAL. Default: an `AgentEvent`-shaped
+     *  `{ _tag: 'done' | 'error' }`. */
+    readonly isTerminal?: (event: E) => boolean;
+}
+
+export declare interface ResumableAgentStreamState<E> {
+    /** The UNWRAPPED inner events received so far, in order (deduped by seq). */
+    readonly events: ReadonlyArray<E>;
+    readonly status: ResumableStreamStatus;
+    /** How many times the transport dropped + auto-reconnected this run. */
+    readonly reconnects: number;
+    /** Set when status === 'error'. */
+    readonly error: unknown | undefined;
+}
+
+export declare interface ResumableConsumeConfig<E> {
+    /** Max CONSECUTIVE reconnects WITHOUT progress before giving up. The counter
+     *  resets whenever a reconnect delivers at least one new event, so a long
+     *  stream survives any number of well-spaced drops. */
+    readonly maxReconnects: number;
+    /** Base backoff between reconnects in ms; grows exponentially, capped. */
+    readonly backoffMs: number;
+    readonly maxBackoffMs: number;
+    /** True when an inner event is TERMINAL (the run finished — do NOT reconnect). */
+    readonly isTerminal: (event: E) => boolean;
+}
+
+/**
+ * The pure resumable-consume loop as ONE Effect (no React). Opens the stream
+ * from the current cursor; on a drop BEFORE the terminal event it backs off and
+ * reopens with `fromSeq` = the last seq seen. Dedups by seq (replay overlap),
+ * unwraps each `SeqEvent` to its inner event, and reports through `sink`.
+ * Interruption (user cancel) ends it silently. Exported for direct testing.
+ */
+export declare const resumableConsumeProgram: <E>(method: ResumableStreamMethod<E>, baseInput: Readonly<Record<string, unknown>>, sink: ResumableSink<E>, config: ResumableConsumeConfig<E>) => Effect.Effect<void>;
+
+/** Where the consume loop reports progress. The hook wires these to React
+ *  state; tests wire a recorder. Kept separate from React so the resume logic
+ *  is unit-testable without rendering. */
+export declare interface ResumableSink<E> {
+    readonly onEvent: (event: E) => void;
+    readonly onStatus: (status: ResumableStreamStatus) => void;
+    /** A transport drop happened → a reconnect attempt is starting. */
+    readonly onReconnect: () => void;
+    readonly onError: (error: unknown) => void;
+}
+
+/** The rpc surface a resumable run is invoked through — `{ ...input, fromSeq }`
+ *  → a stream of seq-tagged elements. */
+export declare type ResumableStreamMethod<E> = (payload: unknown) => Stream.Stream<SeqElement<E>, unknown, never>;
+
+export declare type ResumableStreamStatus = 'idle' | 'streaming' | 'reconnecting' | 'done' | 'error';
+
+/** Pure: map source rows → `{ value, label }` options. Falls back to the value
+ *  when the label field is absent. Exported for direct testing + reuse. */
+export declare const rowsToOptions: (rows: ReadonlyArray<Record<string, unknown>>, labelField: string, valueField: string) => ReadonlyArray<FieldOption>;
+
+export declare interface RpcError {
+    /** Source — `'mutation'` for transactional unary calls, `'action'` for
+     *  non-transactional unary calls, `'subscription'` for streams. */
+    readonly source: 'mutation' | 'action' | 'subscription';
+    /** RPC tag (e.g. `'orgs.create'`, `'projects.list'`). */
+    readonly tag: string;
+    /** The raw error value. May be a Schema.TaggedError instance, a plain
+     *  Error, an unknown thrown value. Pattern-match on `_tag` for typed errors. */
+    readonly error: unknown;
+    /** Trace id of the failed call — the SAME id the server logged + the
+     *  dashboards show. Lets a listener (or `DefaultErrorFallback`) point at
+     *  `voltro logs --trace <id>`. Present when a client span was active
+     *  (always, in practice — Effect's native tracer is ambient). */
+    readonly traceId?: string;
+}
+
+export declare class RpcErrorBus {
+    #private;
+    /** Subscribe. Returns an unsubscribe function. */
+    on(listener: RpcErrorListener): () => void;
+    /** Emit. Pipeline code (useMutation / subscriptionCache) calls this. */
+    emit(event: RpcError): void;
+}
+
+export declare type RpcErrorListener = (event: RpcError) => void;
+
+/**
+ * Derive table COLUMNS from a query's output `Schema` — an
+ * `Schema.Array(Schema.Struct({...}))`. Drills into the array's element and maps
+ * its properties (same descriptor shape as `schemaToFields`, reused for
+ * `<DataTable>` cells). Returns `[]` if the output isn't an array of objects.
+ */
+export declare const schemaToColumns: (schema: Schema.Schema.Any) => ReadonlyArray<FieldDescriptor>;
+
+/**
+ * Derive the ordered field list for a `Schema.Struct` input. Returns `[]` for a
+ * schema with no object properties (a scalar, `Schema.Void`, or anything
+ * `JSONSchema.make` cannot represent).
+ */
+export declare const schemaToFields: (schema: Schema.Schema.Any) => ReadonlyArray<FieldDescriptor>;
+
+/** One persisted/wire element of a resumable stream. Mirrors `@voltro/ai`'s
+ *  `SeqEvent` without taking a dependency on it (the client stays AI-agnostic). */
+export declare interface SeqElement<E> {
+    readonly seq: number;
+    readonly event: E;
+}
+
+/**
+ * Transition a pending mutation to 'success' or 'error'. Updates the
+ * existing entry in-place (preserves order in the buffer) so the
+ * panel doesn't shuffle while the user is reading it.
+ *
+ * No-op if no pending entry matches `id` (e.g. the start event was
+ * dropped from the ring after a long session).
+ */
+export declare const settleMutation: (id: string, outcome: {
+    readonly status: "success";
+    readonly output: unknown;
+} | {
+    readonly status: "error";
+    readonly error: unknown;
+}) => void;
+
+/** Shallow element-wise array equality. Pure — the cache-invalidation core. */
+export declare const shallowArrayEqual: (a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>) => boolean;
+
+declare type SignalPayload<Messages extends WorkflowClientMessages, Name extends string> = NonNullable<Messages['signals']> extends Readonly<Record<Name, infer Payload>> ? Payload : unknown;
+
+export declare interface SortState {
+    readonly column: string;
+    readonly direction: 'asc' | 'desc';
+}
+
+/** Stable-key-ordered values of a sources record — the cache key for a derive. */
+export declare const sourceValues: (sources: Record<string, unknown>) => ReadonlyArray<unknown>;
+
+export declare const ssrClientProxy: unknown;
+
+export declare const ssrStubHandle: ApiHandle;
+
+/**
+ * Stable, deterministic string for an arbitrary key array. Object keys
+ * sort recursively so `{a:1,b:2}` and `{b:2,a:1}` map to the same string.
+ * Arrays preserve order (it matters). Used as the cache's `Map` key.
+ */
+export declare const stableKey: (key: ReadonlyArray<unknown>) => string;
+
+/**
+ * Publish a NEW (pending) mutation event. Caller is responsible for
+ * calling `settleMutation(id, ...)` later. Returns the id used to
+ * settle.
+ *
+ * If the buffer is at MAX_MUTATIONS, the oldest entry is dropped to
+ * make room.
+ */
+export declare const startMutation: (args: Pick<MutationEvent, "id" | "apiName" | "tag" | "input">) => void;
+
+/** Subscribe to client errors. Returns an unsubscribe fn. */
+export declare const subscribeClientErrors: (listener: ClientErrorListener) => (() => void);
+
+/** Subscribe to started client traces. Returns an unsubscribe fn. */
+export declare const subscribeClientTraces: (listener: ClientTraceListener) => () => void;
+
+export declare const subscribeMutations: (cb: () => void) => (() => void);
+
+export declare class SubscriptionCache {
+    private readonly entries;
+    private readonly inactiveTtlMs;
+    private readonly onChangeHook;
+    private readonly errorBus;
+    constructor(options?: SubscriptionCacheOptions);
+    /**
+     * Register a subscriber. The cache forks the underlying fiber on the
+     * first subscriber and re-uses it for the rest. Returns the snapshot
+     * getter, the per-subscriber notify-on-change hook, and an unsubscribe
+     * function.
+     *
+     * `fetch` is invoked at most once per cache-entry lifetime (it builds
+     * the Effect Stream against the runtime). Subsequent subscribers piggy-
+     * back on the same stream.
+     */
+    subscribe(keyArr: ReadonlyArray<unknown>, fetch: () => Stream.Stream<SubscriptionEvent<unknown>, unknown, never>, runtime: AnyRuntime, onChange: () => void, options?: {
+        readonly source?: string | ReadonlyArray<string>;
+    }): {
+        readonly getSnapshot: () => CacheSnapshot<unknown>;
+        readonly unsubscribe: () => void;
+    };
+    /**
+     * Stage an optimistic patch against `keyArr`. Subscribers see the
+     * patched value on the next snapshot read. Returns a handle for manual
+     * revert (the canonical revert is via `revertByMutation` once the
+     * mutation resolves).
+     *
+     * If the entry doesn't exist yet (mutation fires before its
+     * subscription mounts — uncommon but possible), we create a stub entry
+     * with no fiber. When a subscription later mounts for the same key,
+     * the patch is preserved and the fiber is forked normally.
+     */
+    update<T>(keyArr: ReadonlyArray<unknown>, reducer: (current: T) => T, mutationId: string): {
+        readonly revert: () => void;
+        readonly patchId: string;
+    };
+    /**
+     * Patch every cached entry whose rpc tag matches `tag`, regardless of
+     * the input the subscription was opened with. The escape hatch for
+     * sourceless queries — joins, aggregates, custom-projection routes —
+     * that the auto-optimistic source-router can't reach.
+     *
+     * Usage from `.withOptimistic`:
+     *
+     *   create.withOptimistic((cache, input) => {
+     *     cache.forTag('todos.summary', (current) => ({
+     *       ...(current as { count: number }),
+     *       count: (current as { count: number }).count + 1,
+     *     }))
+     *   })
+     *
+     * Returns the number of entries that were patched, so callers can warn
+     * if zero entries matched (probably means the tag is misspelt).
+     */
+    forTag<T>(tag: string, reducer: (current: T) => T, mutationId: string): {
+        readonly patchedCount: number;
+    };
+    /** Drop every patch owned by `mutationId` from EVERY entry. */
+    revertByMutation(mutationId: string): void;
+    /**
+     * Mark a SUCCEEDED mutation's optimistic patches as confirmed. Unlike
+     * `revertByMutation` (used on failure), this does NOT drop them — they stay
+     * visible until the next server snapshot/delta updates `base` (which then
+     * reflects the committed write and drops them, see the stream apply loop).
+     * This removes the on→off→on flash where dropping the patch on mutation
+     * resolve briefly exposes a stale base before the server delta lands.
+     */
+    confirmByMutation(mutationId: string): void;
+    /**
+     * Auto-derive optimistic patches from a mutation's declared target(s).
+     * Iterates every cache entry whose `source` table matches a target's
+     * table; applies the canonical patch for the op:
+     *
+     *   - insert : prepend (or append) a row derived from input + an
+     *              `optimistic: true` flag + a generated id.
+     *   - update : replace the row whose id matches `input.id` (or the
+     *              custom identify fn from the spec) by merging input
+     *              fields on top of the current row.
+     *   - delete : filter out the row whose id matches `input.id`.
+     *
+     * Specs with a custom `shape`/`identify`/`order` function override
+     * these defaults. All patches are tagged with `mutationId` for atomic
+     * revert.
+     */
+    autoApply(targets: ReadonlyArray<AutoApplyTarget>, input: Record<string, unknown>, mutationId: string): void;
+    /** Drop a specific patch by id. */
+    private revertPatch;
+    /**
+     * Read the current snapshot for a key WITHOUT subscribing. If the
+     * entry doesn't exist, returns the "empty" snapshot (data=undefined,
+     * revision=-1, no patches). Safe to call from `useSyncExternalStore`'s
+     * getSnapshot, which is invoked many times during a single render.
+     */
+    peek(keyArr: ReadonlyArray<unknown>): CacheSnapshot<unknown>;
+    /** Test / debug helper. */
+    getEntry(keyArr: ReadonlyArray<unknown>): CacheEntry | undefined;
+    /** Test / debug helper. */
+    size(): number;
+    /**
+     * Devtools introspection: snapshot every cache entry's wire state +
+     * metadata. Returns plain data (no live references) so consumers can
+     * render without worrying about React state-equality.
+     *
+     * The map is keyed by the cache's stable-key string (same one the
+     * fan-out invalidation uses). Entries appear in insertion order;
+     * sort at the call site if order matters.
+     */
+    peekAll(): ReadonlyArray<CacheEntrySnapshot>;
+    /** Tear down every entry (used on runtime dispose). */
+    destroy(runtime: AnyRuntime): void;
+    /**
+     * Re-issue every active subscription against the runtime. Used after
+     * a soft re-auth (login on the same WebSocket connection) so the
+     * server resolves the new subject for each subscription's tenant
+     * scope — without dropping the connection.
+     *
+     * For each entry with a saved fetch:
+     *   - interrupt the current fiber (stops the old WS subscription)
+     *   - clear the base state so the next snapshot fully replaces it
+     *   - re-fork via the saved fetch (new WS subscription with the
+     *     server's now-current subject for this connection)
+     *
+     * Subscribers' `onChange` callbacks fire when the new snapshot
+     * lands, prompting React to re-render with the post-reauth data.
+     *
+     * Stub entries (no fetch saved yet) are left alone — they'll
+     * promote naturally on their next subscriber.
+     */
+    refreshAll(runtime: AnyRuntime): void;
+    private create;
+    private createStub;
+    private freshState;
+    private startFiber;
+    private invalidate;
+    private getSnapshot;
+    private unsubscribe;
+}
+
+export declare interface SubscriptionCacheOptions {
+    /** Milliseconds to keep an entry alive after the last subscriber leaves.
+     *  Lets back-button / quick remount reuse the warm subscription. */
+    readonly inactiveTtlMs?: number;
+    /** Debug hook fired on every cache state change. */
+    readonly onChange?: (key: string) => void;
+    /** Optional error bus — when a subscription stream errors out, the
+     *  cache reports it to the bus so global listeners (e.g. auto-logout
+     *  on Unauthenticated) can react. */
+    readonly errorBus?: RpcErrorBus;
+}
+
+/**
+ * Subscribe to a streaming rpc by tag.
+ *
+ * @param apiName  The name under which the rpc client was mounted in
+ *                 `app.config.ts`.
+ * @param rpcTag   The rpc's tag (e.g. `'todos.list'`). Drives cache
+ *                 dedup AND descriptor lookup for auto-optimistic
+ *                 source-routing.
+ * @param input    The rpc payload. Stable serialisation is part of the
+ *                 cache key.
+ * @param options  `{ skip }` defers the subscription until inputs are
+ *                 ready — while skipped no ws subscription opens and
+ *                 `data` stays `undefined`. Flipping `skip` back to
+ *                 false subscribes with the current input. Mirrors
+ *                 Convex's `"skip"` sentinel without overloading the
+ *                 input argument.
+ */
+export declare interface SubscriptionOptions {
+    readonly skip?: boolean;
+}
+
+export declare interface SubscriptionState<T> {
+    /** Latest data (base + optimistic patches) — undefined until the
+     *  initial server snapshot arrives. */
+    readonly data: T | undefined;
+    /** Server revision counter; -1 before first snapshot. */
+    readonly revision: number;
+    /** Wall-clock ms when the most recent delta was emitted; undefined for snapshots / optimistic. */
+    readonly emittedAt: number | undefined;
+    /** Stream error (only surfaced when no snapshot has ever arrived). */
+    readonly error: unknown | undefined;
+    /** Number of live optimistic patches currently applied. Useful for
+     *  rendering a faint "syncing…" indicator when > 0. */
+    readonly pendingPatches: number;
+}
+
+/** A map entry: a bare event name, or a function of the component's props. */
+export declare type TrackingEntry = string | ((props: Record<string, unknown>) => TrackingEvent);
+
+/** A resolved analytics event: a name + arbitrary payload. */
+export declare type TrackingEvent = {
+    readonly event: string;
+} & Record<string, unknown>;
+
+/** The declarative map. `onMount`/`onUnmount` are lifecycle; every other key is
+ *  a CALLBACK PROP name to wrap (so calling `onClick` also fires its event). */
+export declare interface TrackingMap {
+    readonly onMount?: TrackingEntry;
+    readonly onUnmount?: TrackingEntry;
+    readonly [callback: string]: TrackingEntry | undefined;
+}
+
+/** Where resolved events go — the analytics sink (the client→server transport
+ *  provides this; tests provide a recorder). */
+export declare type TrackingSink = (event: TrackingEvent) => void;
+
+export declare interface TrackingSpec {
+    readonly name: string;
+    readonly map: TrackingMap;
+}
+
+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";
+
+export declare interface UndoController {
+    readonly entries: ReadonlyArray<UndoLogEntry>;
+    readonly loading: boolean;
+    /** True when there's a not-yet-undone, undoable (non-action-crossing) entry. */
+    readonly canUndo: boolean;
+    /** True when there's a previously-undone entry to redo. */
+    readonly canRedo: boolean;
+    /** Undo one invocation by id (the server synthesizes + applies its inverse). */
+    readonly undo: (invocationId: string) => Promise<void>;
+    /** Redo one previously-undone invocation by id. */
+    readonly redo: (invocationId: string) => Promise<void>;
+    /** Undo the newest undoable action (Ctrl-Z). No-op when none. */
+    readonly undoLast: () => Promise<void>;
+    /** Redo the newest undone action (Ctrl-Shift-Z). No-op when none. */
+    readonly redoLast: () => Promise<void>;
+}
+
+export declare interface UndoControls {
+    readonly record: (entry: UndoEntry) => void;
+    readonly undo: () => Promise<void>;
+    readonly redo: () => Promise<void>;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly stack: ReadonlyArray<UndoEntry>;
+    /** Set when the next undo would cross an action / hit a conflict — the UI
+     *  disables + explains instead of silently failing. */
+    readonly nextBlockedBy: 'action' | 'conflict' | undefined;
+}
+
+export declare interface UndoEntry {
+    /** The mutation invocation this entry can undo. */
+    readonly invocationId: string;
+    /** Human label from the mutation (e.g. "create todo") for "Undo 'create todo'". */
+    readonly label?: string;
+    /** Why the NEXT undo past here is blocked (an external action / a conflict). */
+    readonly blockedBy?: 'action' | 'conflict';
+}
+
+/** Structural mirror of `@voltro/protocol`'s UndoLogEntry — the client stays
+ *  decoupled from server packages (like useProvenance mirrors ProvenanceResult). */
+export declare interface UndoLogEntry {
+    readonly id: string;
+    readonly tag: string;
+    readonly label: string | null;
+    readonly undone: boolean;
+    readonly crossesAction: boolean;
+    readonly createdAt: string;
+}
+
+declare type UpdatePayload<Messages extends WorkflowClientMessages, Name extends string> = NonNullable<Messages['updates']> extends Readonly<Record<Name, infer Update>> ? Update extends {
+    readonly payload: infer Payload;
+} ? Payload : unknown : unknown;
+
+declare type UpdateResult<Messages extends WorkflowClientMessages, Name extends string> = NonNullable<Messages['updates']> extends Readonly<Record<Name, infer Update>> ? Update extends {
+    readonly result: infer Result;
+} ? Omit<WorkflowUpdateResult, 'result'> & {
+    readonly result: Result;
+} : WorkflowUpdateResult : WorkflowUpdateResult;
+
+export declare interface UploadHandle {
+    /** Upload one file. Resolves the stored asset or rejects (sets `.error`). */
+    readonly upload: (file: File | Blob, opts?: UploadOptions) => Promise<UploadResult>;
+    /** Upload many with bounded concurrency; resolves in input order. */
+    readonly uploadMany: (files: ReadonlyArray<File | Blob>, opts?: UploadOptions) => Promise<ReadonlyArray<UploadResult>>;
+    /** Aggregate progress across the in-flight batch, 0..1. */
+    readonly progress: number;
+    readonly status: UploadStatus;
+    readonly error: unknown | undefined;
+    /** Abort every in-flight upload (rejects their promises with AbortError). */
+    readonly cancel: () => void;
+    /** Clear status/error/progress back to idle. */
+    readonly reset: () => void;
+    /** Drop-handler: extracts files from a drag event + uploads them. Spread
+     *  `dropzoneProps` onto a container, or call this directly. */
+    readonly onDrop: (event: DragEvent_2, opts?: UploadOptions) => Promise<ReadonlyArray<UploadResult>>;
+    /** Paste-handler: uploads any files on the clipboard (screenshot paste, etc.). */
+    readonly onPaste: (event: ClipboardEvent_2, opts?: UploadOptions) => Promise<ReadonlyArray<UploadResult>>;
+    /** Spread onto a div for a zero-boilerplate dropzone (prevents default drag
+     *  nav + uploads dropped files with the hook's default options). */
+    readonly dropzoneProps: {
+        readonly onDragOver: (e: DragEvent_2) => void;
+        readonly onDrop: (e: DragEvent_2) => void;
+    };
+}
+
+export declare interface UploadOptions {
+    /** `'private'` (default) or `'public'`. Public objects get a cacheable URL. */
+    readonly visibility?: 'public' | 'private';
+    /** Fixed logical key (e.g. `avatars/<userId>.png`); else content-addressed. */
+    readonly key?: string;
+    /** App metadata stored on the ref (so no parallel `assets` table is needed). */
+    readonly folder?: string;
+    readonly tags?: ReadonlyArray<string>;
+    readonly alt?: string;
+    readonly caption?: string;
+    /** rpc tag of the ticket-minting action. Default `'storage.mintUploadTicket'`
+     *  — override for a namespaced storage plugin instance. */
+    readonly mintTag?: string;
+    /** Transport. `'through-app'` (default) POSTs the bytes through the app on
+     *  every provider. `'presign'` offloads the client→server leg: on a
+     *  presigning provider (s3/minio) it PUTs straight to the bucket, then the
+     *  server fetches the bytes back to scan + register (a non-degraded ref) —
+     *  and transparently falls back to through-app when the provider can't
+     *  presign. `'resumable'` splits the file into chunks and uploads them one at
+     *  a time (each retryable independently) — for large media over flaky links.
+     *  `'multipart'` PUTs each part DIRECTLY to the bucket (offloaded + resumable,
+     *  s3/minio) for multi-GB media, falling back to `'resumable'` when the
+     *  provider can't do multipart. */
+    readonly prefer?: 'through-app' | 'presign' | 'resumable' | 'multipart';
+    /** rpc tag of the presign-minting action. Default `'storage.mintPresignedUpload'`. */
+    readonly presignMintTag?: string;
+    /** rpc tag of the finalize action. Default `'storage.finalizeUpload'`. */
+    readonly finalizeTag?: string;
+    /** rpc tag of the resumable-begin action. Default `'storage.beginResumableUpload'`. */
+    readonly beginResumableTag?: string;
+    /** rpc tags for the multipart actions (defaults `'storage.beginMultipartUpload'` etc). */
+    readonly multipartBeginTag?: string;
+    readonly multipartSignTag?: string;
+    readonly multipartCompleteTag?: string;
+    readonly multipartAbortTag?: string;
+    /** Chunk/part size (bytes) for `prefer:'resumable'`/`'multipart'`. Server
+     *  default (5 MiB) if omitted; multipart clamps to the S3 5 MiB minimum. */
+    readonly chunkSize?: number;
+    /** Max parallel uploads for `uploadMany`. Default 3. */
+    readonly concurrency?: number;
+    /** Retry attempts per file on a network/5xx error. Default 1. */
+    readonly retries?: number;
+}
+
+/** The stored asset, shaped as a drop-in for the common CMS-upload contract. */
+export declare interface UploadResult {
+    readonly id: string;
+    readonly url: string;
+    readonly name: string;
+    readonly mime: string;
+    readonly size: number;
+    readonly width?: number;
+    readonly height?: number;
+}
+
+export declare type UploadStatus = 'idle' | 'uploading' | 'success' | 'error';
+
+/**
+ * Invoke a server `defineAction` procedure by tag. Unlike `useMutation`,
+ * an action has no optimistic / cache surface — it's a unary call whose
+ * effects (sends, captures, side-effecting writes the framework must NOT
+ * preview locally) only become visible when the server pushes a delta on
+ * an independent subscription.
+ */
+export declare const useAction: <Input = unknown, Output = unknown>(apiName: string, rpcTag: string) => ActionState<Input, Output>;
+
+export declare const useAgent: (apiName: string, rpcTag: string) => AgentControls;
+
+export declare const useAgentChat: (apiName: string, agent: string, options: UseAgentChatOptions) => AgentChatState;
+
+export declare interface UseAgentChatOptions {
+    /** The thread to read + append to. Mint one per chat (e.g. a useRef'd uuid). */
+    readonly threadId: string;
+}
+
+export declare const useAgentStream: <E = unknown>(apiName: string, rpcTag: string) => AgentStreamControls<E>;
+
+export declare const useAsyncValidation: (apiName: string, queryTag: string, value: string, options: UseAsyncValidationOptions) => AsyncValidationResult;
+
+export declare interface UseAsyncValidationOptions {
+    /** Map the input value → the validation query's input. Default `{ value }`. */
+    readonly input?: (value: string) => Readonly<Record<string, unknown>>;
+    /** Map the query result → a verdict. REQUIRED — only you know the shape. */
+    readonly interpret: (data: unknown) => {
+        readonly valid: boolean;
+        readonly message?: string;
+    };
+    readonly debounceMs?: number;
+    readonly skipEmpty?: boolean;
+}
+
+/** Reactively: may the current subject call something needing `required`
+ *  scope(s)? Use to gate UI. Defaults to false (deny) with no provider. */
+export declare const useCan: (required: string | ReadonlyArray<string>) => boolean;
+
+/**
+ * Fetch the api's capability manifest (procedures + tables + schemas) once.
+ * Browser-safe — imports only React + the runtime context, exactly like
+ * `useProvenance`. The inspect surface is default-open in dev; when a deploy
+ * sets an inspect token the manifest GET is bearer-gated, so a production admin
+ * pointed at a locked-down api must surface that token (a deploy concern, not
+ * this hook's).
+ */
+export declare const useCapabilityManifest: (apiName: string) => CapabilityManifestState;
+
+/**
+ * Bind a data-copilot action by api name + tag. The action's input is
+ * `{ question }` and its output is a {@link CopilotAnswer}. Generic over the
+ * row shape so a caller that knows its schema gets typed rows back.
+ */
+export declare const useDataCopilot: <Row = Record<string, unknown>>(apiName: string, actionTag: string) => DataCopilotState<Row>;
+
+export declare const useDataTable: <Row extends Record<string, unknown> = Record<string, unknown>>(apiName: string, queryTag: string, options?: UseDataTableOptions) => DataTableState<Row>;
+
+export declare interface UseDataTableOptions {
+    /** The query input (filters/pagination cursor). */
+    readonly input?: Readonly<Record<string, unknown>>;
+    /** Explicit columns — overrides the schema-derived ones. */
+    readonly columns?: ReadonlyArray<FieldDescriptor>;
+    readonly initialSort?: SortState;
+    /** Opt into "load more" pagination: the subscription input gets a growing
+     *  `limit` (the query applies `.limit(input.limit)`). This is LIVE
+     *  grow-the-window pagination — rows stay reactive as the window grows. Not
+     *  cursor-based (cursor + live is the windowed-subscriptions idea); use it
+     *  when O(window) is fine and you want the simple "Load more" UX. */
+    readonly pageSize?: number;
+}
+
+/** Debounce a value — returns the latest value after `ms` of quiet. Reusable. */
+export declare const useDebounced: <T>(value: T, ms?: number) => T;
+
+/**
+ * Compute a derived value from a record of reactive sources. Recomputes the
+ * reducer only when a source value changes (shallow compare); returns the
+ * cached (same-reference) result otherwise. The reducer should be pure.
+ */
+export declare const useDerived: <S extends Record<string, unknown>, T>(sources: S, reducer: (sources: S) => T) => T;
+
+export declare const useFormBinding: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(apiName: string, mutationTag: string, options: UseFormBindingOptions<Input>) => FormBinding<Input, Output>;
+
+export declare interface UseFormBindingOptions<Input> {
+    /** The mutation's input `Schema`. Optional: when omitted it is resolved from
+     *  the mounted client descriptor (`descriptors[tag].input`, the capability
+     *  map — innovation/06). Pass it explicitly to override, or when the
+     *  descriptor isn't on the client. */
+    readonly schema?: Schema.Schema.Any;
+    /** Initial field values. */
+    readonly defaults?: Partial<Input>;
+}
+
+/** The field shape a `<AutoForm mutation=…>` will render — from the mutation's
+ *  input Schema. Use it to render a matching skeleton while anything the form
+ *  depends on is still loading. */
+export declare const useFormSkeleton: (apiName: string, mutationTag: string) => ReadonlyArray<FieldDescriptor>;
+
+/** Lookup a single api's runtime + cache by name. */
+export declare const useFrameworkApi: (apiName: string) => ApiHandle;
+
+export declare const useFrameworkRuntimes: () => FrameworkRuntimes;
+
+/**
+ * Invoke a unary rpc by tag. The descriptor metadata (mounted via
+ * `app.config.ts`'s `apis` → emitted by codegen as `appDescriptors`)
+ * drives auto-optimistic patching.
+ */
+export declare const useMutation: <Input = unknown, Output = unknown>(apiName: string, rpcTag: string) => MutationBuilder<Input, Output>;
+
+export declare const useOnRpcError: (apiName: string, listener: RpcErrorListener) => void;
+
+export declare const useOutbox: (options: UseOutboxOptions) => OutboxControls;
+
+export declare interface UseOutboxOptions {
+    /** Perform one queued write (the real mutation). Throw to fail. */
+    readonly send: (entry: OutboxEntry) => Promise<void>;
+    /** Online override (defaults to navigator.onLine + online/offline events). */
+    readonly online?: boolean;
+    /** Classify a send error as a conflict (blocks replay) vs a transient
+     *  failure (retried). Default: an error with `conflict === true` or the
+     *  undo concurrency tag. */
+    readonly isConflict?: (error: unknown) => boolean;
+    readonly idFor?: () => string;
+}
+
+/** The current subject's scopes (defaults to none if no provider). */
+export declare const usePermissions: () => PermissionState_2;
+
+export declare const usePreview: <Input = Record<string, unknown>>(apiName: string, previewTag: string) => PreviewState<Input>;
+
+export declare const useProvenance: (apiName: string, table: string, id: string, column?: string) => ProvenanceState;
+
+export declare const useQueryField: (apiName: string, queryTag: string, options?: UseQueryFieldOptions) => QueryFieldState;
+
+export declare interface UseQueryFieldOptions {
+    /** Map the typed term → the source query's input. Default `{ q: term }`. */
+    readonly input?: (term: string) => Record<string, unknown>;
+    /** Row field used as the option label. Default `'name'`. */
+    readonly labelField?: string;
+    /** Row field used as the option value. Default `'id'`. */
+    readonly valueField?: string;
+    /** Debounce before the term reaches the query. Default 200ms. */
+    readonly debounceMs?: number;
+    readonly initialTerm?: string;
+    /** Don't open the subscription until the term is non-empty (typeahead). */
+    readonly skipUntilTerm?: boolean;
+}
+
+export declare const useQueryFilters: <Row = Record<string, unknown>>(apiName: string, queryTag: string, options?: UseQueryFiltersOptions) => QueryFiltersState<Row>;
+
+export declare interface UseQueryFiltersOptions {
+    readonly initial?: Readonly<Record<string, unknown>>;
+}
+
+export declare const useRecord: <R = Record<string, unknown>>(apiName: string, queryTag: string, input?: Readonly<Record<string, unknown>>) => RecordState<R>;
+
+export declare const useRefreshSubscriptions: (apiName: string) => (() => void);
+
+/**
+ * Reactively gate ONE resource action. Bind a server query (`source:
+ * '_voltro_rebac_tuples'`) that runs `can()` for the input and returns
+ * `{ allowed }`; this hook surfaces it fail-closed + live (revoke flips it).
+ */
+export declare const useResourceCan: (apiName: string, rpcTag: string, input: ResourceCanInput, options?: SubscriptionOptions) => UseResourceCanState;
+
+/**
+ * Reactively gate MANY resources of one (action, type) in a single
+ * subscription — the table-row case (one hook call, not one-per-row). Bind a
+ * server query returning `{ allowedIds }` (the permitted subset); this hook
+ * exposes it as a `Set` for membership tests, fail-closed + live.
+ */
+export declare const useResourceCans: (apiName: string, rpcTag: string, input: ResourceCansInput, options?: SubscriptionOptions) => UseResourceCansState;
+
+export declare interface UseResourceCansState {
+    /** The ids the subject may act on (membership test for per-row gating). A row
+     *  whose id is absent is denied. */
+    readonly allowedIds: ReadonlySet<string>;
+    readonly pending: boolean;
+}
+
+export declare interface UseResourceCanState {
+    /** Whether the subject may perform the action — fails CLOSED (false) until the
+     *  first verdict and whenever the subscription has no data. */
+    readonly allowed: boolean;
+    /** True before the first server verdict arrives. */
+    readonly pending: boolean;
+}
+
+export declare const useResumableAgentStream: <E = unknown>(apiName: string, rpcTag: string, options?: ResumableAgentStreamOptions<E>) => ResumableAgentStreamControls<E>;
+
+export declare const useSubscription: <T = unknown>(apiName: string, rpcTag: string, input?: Readonly<Record<string, unknown>>, options?: SubscriptionOptions) => SubscriptionState<T>;
+
+/** The column shape a `<DataTable query=…>` will render — from the query's
+ *  output Schema. */
+export declare const useTableSkeleton: (apiName: string, queryTag: string) => ReadonlyArray<FieldDescriptor>;
+
+/**
+ * Wire a component's tracking: fire `onMount`/`onUnmount` from an effect, and
+ * return the props with the spec's callback props wrapped. The component spreads
+ * the returned props. The sink is the analytics transport (injected, so the
+ * kernel stays transport-agnostic — and testable).
+ */
+export declare const useTracking: (spec: TrackingSpec, props: Record<string, unknown>, sink: TrackingSink) => Record<string, unknown>;
+
+export declare const useUndo: (options: UseUndoOptions) => UndoControls;
+
+export declare const useUndoLog: (apiName: string, options?: {
+    readonly limit?: number;
+}) => UndoController;
+
+export declare interface UseUndoOptions {
+    /** Apply the inverse of an invocation server-side (a synthesized mutation). */
+    readonly onUndo: (invocationId: string) => Promise<void> | void;
+    /** Replay an invocation forward server-side. */
+    readonly onRedo: (invocationId: string) => Promise<void> | void;
+}
+
+/**
+ * Reactive file upload for a mounted api's storage. Provider-agnostic
+ * (filesystem/dev, s3/r2/prod) and cross-origin-safe. See the file header.
+ */
+export declare const useUpload: (apiName: string, hookOpts?: UploadOptions) => UploadHandle;
+
+export declare const useWindowedSubscription: <Row = Record<string, unknown>>(apiName: string, queryTag: string, options: UseWindowedSubscriptionOptions) => WindowedSubscriptionState<Row>;
+
+export declare interface UseWindowedSubscriptionOptions {
+    readonly rowHeight: number;
+    /** Visible viewport height in px. */
+    readonly viewportHeight: number;
+    /** Extra rows fetched above/below the viewport (smoother scroll). Default 5. */
+    readonly overscan?: number;
+    /** Total row count, if known — enables an accurate scrollbar. */
+    readonly total?: number;
+    /** Extra query input merged with `{ offset, limit }`. */
+    readonly input?: Readonly<Record<string, unknown>>;
+}
+
+export declare const useWorkflow: <Payload = unknown, Messages extends WorkflowClientMessages = WorkflowClientMessages>(apiName: string, workflowName: string) => WorkflowState<Payload, Messages>;
+
+export declare const useWorkflowDomainEvents: (apiName: string, filters?: {
+    readonly name?: string;
+    readonly limit?: number;
+}, options?: SubscriptionOptions) => WorkflowDomainEventsState;
+
+export declare const useWorkflowEventDeliveries: (apiName: string, eventId: string | undefined) => WorkflowEventDeliveriesState;
+
+export declare const useWorkflowEvents: (apiName: string, runId: string | undefined) => WorkflowRunEventsState;
+
+export declare const useWorkflowRun: (apiName: string, id: string | undefined) => WorkflowRunState;
+
+export declare const useWorkflowRunEvents: (apiName: string, runId: string | undefined) => WorkflowRunEventsState;
+
+export declare const useWorkflowRuns: (apiName: string, filters?: WorkflowRunsFilter, options?: SubscriptionOptions) => WorkflowRunsState;
+
+export declare const useWorkflowRunState: (apiName: string, id: string | undefined) => WorkflowRunStateValue;
+
+export declare const useWorkflowRunSteps: (apiName: string, runId: string | undefined) => WorkflowRunStepsState;
+
+export declare const useWorkflowSignal: (apiName: string) => WorkflowSignalState;
+
+export declare const useWorkflowUpdate: (apiName: string) => WorkflowUpdateState;
+
+/** Validate a payload against an event descriptor's Schema. Pure. */
+export declare const validateEventPayload: (descriptor: EventDescriptor<string, unknown>, payload: unknown) => EventValidation;
+
+/**
+ * Validate `values` against an input `schema`, returning the first error per
+ * top-level field (`{ [field]: message }`) — the shape `<AutoForm>` and custom
+ * widgets render inline. Uses the same `decodeUnknownEither` + `ArrayFormatter`
+ * path the store's `.validate(...)` uses, so client and server speak ONE
+ * schema. `{ errors: 'all' }` collects every field's error in one pass.
+ *
+ * Client-side validation is non-authoritative UX — the server re-validates the
+ * same schema on the mutation; this just gives instant inline feedback.
+ */
+export declare const validateFields: (schema: Schema.Schema.Any, values: unknown) => ValidationResult;
+
+export declare interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: FieldErrors;
+}
+
+export declare type ValidationStatus = 'idle' | 'checking' | 'valid' | 'invalid';
+
+/** Pure state machine: empty → idle; still settling or query in flight →
+ *  checking; otherwise the interpreted verdict. Tested directly so the
+ *  async/debounce wiring around it stays thin. */
+export declare const validationStatus: (args: {
+    readonly value: string;
+    readonly debouncedValue: string;
+    /** Subscription result; `undefined` = in flight. */
+    readonly data: unknown;
+    readonly interpret: (data: unknown) => {
+        readonly valid: boolean;
+        readonly message?: string;
+    };
+    /** Empty value is `idle` (default true). */
+    readonly skipEmpty?: boolean;
+}) => AsyncValidationResult;
+
+/** The default widget kinds the framework can render from a schema. `'custom'`
+ *  means "no default widget" — the field needs a render-prop (a nested object,
+ *  an array of objects, or a multi-branch union). Mirrors innovation/01's set. */
+export declare type WidgetKind = 'text' | 'textarea' | 'number' | 'checkbox' | 'switch' | 'select' | 'radio' | 'async-select' | 'multi-select' | 'date' | 'datetime' | 'daterange' | 'file' | 'hidden' | 'custom';
+
+export declare interface WindowedSubscriptionState<Row> {
+    /** The in-window rows (live). */
+    readonly rows: ReadonlyArray<Row>;
+    readonly window: WindowSpec;
+    /** Wire to the scroll container's `onScroll`. */
+    readonly onScroll: (e: UIEvent_2<HTMLElement>) => void;
+    readonly topSpacer: number;
+    readonly bottomSpacer: number;
+    readonly loading: boolean;
+    readonly error: unknown | undefined;
+}
+
+export declare interface WindowSpec {
+    /** First row index in the window (incl. overscan). */
+    readonly startIndex: number;
+    /** Exclusive end index of the window. */
+    readonly endIndex: number;
+    /** Query offset = startIndex. */
+    readonly offset: number;
+    /** Query limit = window size. */
+    readonly limit: number;
+    /** Pixel height of the rows ABOVE the window (scrollbar fidelity). */
+    readonly topSpacer: number;
+    /** Pixel height of the rows BELOW the window (0 when total unknown). */
+    readonly bottomSpacer: number;
+}
+
+export declare interface WorkflowClientMessages {
+    readonly signals?: Readonly<Record<string, unknown>>;
+    readonly updates?: Readonly<Record<string, {
+        readonly payload: unknown;
+        readonly result: unknown;
+    }>>;
+    readonly queries?: Readonly<Record<string, {
+        readonly payload: unknown;
+        readonly result: unknown;
+    }>>;
+}
+
+export declare interface WorkflowDomainEventsState extends SubscriptionState<ReadonlyArray<WorkflowDomainEventRow>> {
+    readonly events: ReadonlyArray<WorkflowDomainEventRow>;
+}
+
+export declare interface WorkflowEventDeliveriesState extends SubscriptionState<ReadonlyArray<WorkflowEventDeliveryRow>> {
+    readonly deliveries: ReadonlyArray<WorkflowEventDeliveryRow>;
+}
+
+export declare interface WorkflowRunError {
+    readonly tag: string | null;
+    readonly message: string | null;
+    /** The step that failed, if a step (vs the run body) carried the error. */
+    readonly step: string | undefined;
+}
+
+export { WorkflowRunEventRow }
+
+export declare interface WorkflowRunEventsState extends SubscriptionState<ReadonlyArray<WorkflowRunEventRow>> {
+    readonly events: ReadonlyArray<WorkflowRunEventRow>;
+}
+
+export { WorkflowRunRow }
+
+export declare interface WorkflowRunsFilter {
+    readonly tag?: string;
+    readonly status?: WorkflowRunStatus;
+    readonly limit?: number;
+}
+
+export declare interface WorkflowRunsState extends SubscriptionState<ReadonlyArray<WorkflowRunRow>> {
+    readonly runs: ReadonlyArray<WorkflowRunRow>;
+}
+
+export declare interface WorkflowRunState extends SubscriptionState<ReadonlyArray<WorkflowRunRow>> {
+    readonly run: WorkflowRunRow | undefined;
+}
+
+export declare interface WorkflowRunStateValue {
+    readonly run: WorkflowRunRow | undefined;
+    readonly status: WorkflowRunStatus | undefined;
+    readonly steps: ReadonlyArray<WorkflowRunStepRow>;
+    readonly events: ReadonlyArray<WorkflowRunEventRow>;
+    /** The running step, else the most recently started one. */
+    readonly currentStep: WorkflowRunStepRow | undefined;
+    /** Present only while the run is parked on a signal/update wait. */
+    readonly waitingFor: WorkflowWaitingFor | undefined;
+    readonly error: WorkflowRunError | undefined;
+    readonly traceId: string | null | undefined;
+    readonly loading: boolean;
+    readonly cancel: () => Promise<void>;
+    readonly resume: () => Promise<void>;
+    readonly signal: (signalName: string, payload?: unknown) => Promise<{
+        readonly eventId: string;
+    }>;
+    readonly update: (updateName: string, payload?: unknown, options?: {
+        readonly timeoutMs?: number;
+    }) => Promise<WorkflowUpdateResult>;
+}
+
+export { WorkflowRunStatus }
+
+export { WorkflowRunStepRow }
+
+export declare interface WorkflowRunStepsState extends SubscriptionState<ReadonlyArray<WorkflowRunStepRow>> {
+    readonly steps: ReadonlyArray<WorkflowRunStepRow>;
+}
+
+export declare interface WorkflowSignalState {
+    readonly signal: (run: Pick<WorkflowRunHandle, 'id'>, signalName: string, payload?: unknown) => Promise<{
+        readonly eventId: string;
+    }>;
+    readonly pending: boolean;
+    readonly error: unknown | undefined;
+    readonly data: {
+        readonly eventId: string;
+    } | undefined;
+}
+
+export declare interface WorkflowState<Payload, Messages extends WorkflowClientMessages = WorkflowClientMessages> {
+    readonly start: (payload: Payload) => Promise<WorkflowRunHandle>;
+    readonly cancel: (run: Pick<WorkflowRunHandle, 'workflowName' | 'executionId'>) => Promise<void>;
+    readonly resume: (run: Pick<WorkflowRunHandle, 'workflowName' | 'executionId'>) => Promise<void>;
+    readonly signal: <Name extends string>(run: Pick<WorkflowRunHandle, 'id'>, signalName: Name, payload?: SignalPayload<Messages, Name>) => Promise<{
+        readonly eventId: string;
+    }>;
+    readonly update: <Name extends string>(run: Pick<WorkflowRunHandle, 'id'>, updateName: Name, payload?: UpdatePayload<Messages, Name>, options?: {
+        readonly timeoutMs?: number;
+    }) => Promise<UpdateResult<Messages, Name>>;
+    readonly pending: boolean;
+    readonly error: unknown | undefined;
+    readonly data: WorkflowRunHandle | undefined;
+}
+
+export { WorkflowUpdateResult }
+
+export declare interface WorkflowUpdateState {
+    readonly update: (run: Pick<WorkflowRunHandle, 'id'>, updateName: string, payload?: unknown, options?: {
+        readonly timeoutMs?: number;
+    }) => Promise<WorkflowUpdateResult>;
+    readonly pending: boolean;
+    readonly error: unknown | undefined;
+    readonly data: WorkflowUpdateResult | undefined;
+}
+
+/** A workflow parked on `awaitSignal`/`awaitUpdate` — the name + which kind,
+ *  derived from the run-events handshake. Drives ApprovalControls visibility. */
+export declare interface WorkflowWaitingFor {
+    readonly name: string;
+    readonly kind: 'signal' | 'update';
+}
+
+/**
+ * Return `props` with each callback the spec names wrapped so invoking it ALSO
+ * fires its resolved event to `sink` (the original callback still runs).
+ * Lifecycle keys (onMount/onUnmount) are skipped — those fire from effects.
+ * Pure: returns a new props object, mutates nothing.
+ */
+export declare const wrapTrackedCallbacks: (spec: TrackingSpec, props: Record<string, unknown>, sink: TrackingSink) => Record<string, unknown>;
+
+export { }