@voltro/client 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -24,6 +24,10 @@ import { WorkflowRunStatus } from '@voltro/protocol';
 import { WorkflowRunStepRow } from '@voltro/protocol';
 import { WorkflowUpdateResult } from '@voltro/protocol';
 
+/** Can the current caller invoke something? `unknown` = only the server knows
+ *  (a per-resource guard, or an undeclared decision). */
+export declare type AccessDecision = 'allowed' | 'denied' | 'unknown';
+
 export declare interface ActionState<Input, Output> {
     /** Invoke the action.
      *
@@ -54,6 +58,8 @@ export declare interface ActionState<Input, Output> {
     readonly lastResult: Output | undefined;
 }
 
+declare type ActionTag<P extends ProcedureTypeMap> = TagsOfKind<P, 'action'>;
+
 /** 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";
@@ -179,6 +185,39 @@ export declare interface ApiHandle {
     readonly errorBus: RpcErrorBus;
 }
 
+/**
+ * The typed hooks for one api. Overload ORDER mirrors the untyped
+ * `useSubscription` exactly, because that order is the design: a `fallback` /
+ * `initialSnapshot` call gets the non-union result and never narrows, a literal
+ * `skip: false` keeps the two-state union, and only a DYNAMIC `skip` is handed
+ * the third {@link SubscriptionIdle} state. Re-deriving that here rather than
+ * widening it would un-narrow every migrated call site.
+ */
+export declare interface ApiHooks<P extends ProcedureTypeMap> {
+    readonly useSubscription: {
+        /** No input needed — the procedure declares no required input field. */
+        <Tag extends QueryTag<P> & OptionalInputTag<P>>(tag: Tag): SubscriptionState<QueryData<P, Tag>>;
+        /** SSR seed: `data` is present from the first paint, `loading` is false. */
+        <Tag extends QueryTag<P>>(tag: Tag, input: ProcedureInput<P[Tag]>, options: SubscriptionOptions<QueryData<P, Tag>> & {
+            readonly initialSnapshot: QueryData<P, Tag>;
+        }): SubscriptionStateWithFallback<QueryData<P, Tag>>;
+        /** `fallback`: `data` is always present, `loading` still tells the truth. */
+        <Tag extends QueryTag<P>>(tag: Tag, input: ProcedureInput<P[Tag]>, options: SubscriptionOptions<QueryData<P, Tag>> & {
+            readonly fallback: QueryData<P, Tag>;
+        }): SubscriptionStateWithFallback<QueryData<P, Tag>>;
+        /** The two-state union — `!loading` proves `data` is present. */
+        <Tag extends QueryTag<P>>(tag: Tag, input: ProcedureInput<P[Tag]>, options?: SubscriptionOptions<QueryData<P, Tag>> & {
+            readonly skip?: false;
+        }): SubscriptionState<QueryData<P, Tag>>;
+        /** Dynamic `skip` — "deliberately not asking" becomes a real outcome. */
+        <Tag extends QueryTag<P>>(tag: Tag, input: ProcedureInput<P[Tag]>, options: SubscriptionOptions<QueryData<P, Tag>> & {
+            readonly skip?: boolean;
+        }): SubscriptionState<QueryData<P, Tag>> | SubscriptionIdle;
+    };
+    readonly useMutation: <Tag extends MutationTag<P>>(tag: Tag) => MutationBuilder<ProcedureInput<P[Tag]>, ProcedureOutput<P[Tag]>>;
+    readonly useAction: <Tag extends ActionTag<P>>(tag: Tag) => ActionState<ProcedureInput<P[Tag]>, ProcedureOutput<P[Tag]>>;
+}
+
 /**
  * Apply preload seeds from the hydration payload, BEFORE the first client
  * render. Idempotent (a Map upsert) so a re-hydration or a repeated key is
@@ -243,7 +282,9 @@ export declare interface AutoApplyTarget {
  * The returned `runtime` owns the socket; dispose it (`runtime.dispose()`, after
  * `cache.destroy(runtime)`) to tear the connection down. A fresh cache is bound
  * per resolved runtime — cross-runtime cache reuse is unsafe (its fibers
- * reference the old runtime).
+ * reference the old runtime). Carrying the previous cache's DATA forward is a
+ * different thing and is safe: see `SubscriptionCache.seedStaleFrom`, which
+ * copies rows (never fibers) and is gated by the caller to same-subject swaps.
  *
  * Rejects if the runtime fails to resolve the client (e.g. the socket never
  * opens); the caller's reconnect logic decides what to do with that.
@@ -352,8 +393,8 @@ export declare const canCall: (subjectScopes: ReadonlyArray<string>, required: s
  *  An empty requirement is allowed (nothing is being demanded). Pure. */
 export declare const canCallAny: (subjectScopes: ReadonlyArray<string>, required: ReadonlyArray<string>) => boolean;
 
-/** Structural mirror of @voltro/cli's `CapabilityManifestTable` column — the
- *  client stays decoupled from the (node-only) cli package. */
+/** Structural mirror of @voltro/cli's manifest column — the client stays
+ *  decoupled from the (node-only) cli package. */
 export declare interface CapabilityColumn {
     readonly name: string;
     readonly type: string;
@@ -362,6 +403,26 @@ export declare interface CapabilityColumn {
     readonly refersTo?: string;
     /** Closed value set (`text().oneOf([...])`) → render a select. */
     readonly enum?: ReadonlyArray<string>;
+    /**
+     * `.serverOnly()` — this column never crosses ANY wire, and the runtime
+     * REFUSES a mutation input that sets it (`assertNoServerOnlyInput`). The one
+     * axis of the three that is a statement about wire exposure, and therefore
+     * the only one a schema-driven UI may act on by omitting a field.
+     */
+    readonly serverOnly?: boolean;
+    /**
+     * `.encrypted()` — ciphertext at rest. Ordinary wire data to the app's own
+     * procedures, which read it decrypted. NEVER treat this as a reason to hide
+     * a field: encryption-at-rest and wire exposure are different questions, and
+     * conflating them hides columns the user is meant to edit.
+     */
+    readonly encrypted?: boolean;
+    /**
+     * `.sensitive(class)` — the declared class. The EXPORT-masking axis: the
+     * value is real wire data the app renders normally; what has to mask it is a
+     * bulk export / CSV / copy-out affordance.
+     */
+    readonly sensitive?: string;
 }
 
 /** Structural mirror of @voltro/cli's `CapabilityManifest` (served at
@@ -374,6 +435,9 @@ export declare interface CapabilityManifest {
     }>;
     readonly widgets: ReadonlyArray<string>;
     readonly tables: ReadonlyArray<CapabilityTable>;
+    /** Every scope the installed plugins DECLARE. Empty means "not declared" —
+     *  never "no scopes exist". */
+    readonly scopes?: ReadonlyArray<string>;
 }
 
 export declare interface CapabilityManifestState {
@@ -394,6 +458,14 @@ export declare interface CapabilityProcedure {
         readonly table: string;
         readonly op: string;
     }>;
+    /**
+     * The authorization this procedure declares. `undefined` means the descriptor
+     * declared NEITHER `guards:` nor `openAccess:` — undecided, which is not the
+     * same as open. Under `security.defaultDeny` such a procedure cannot boot, so
+     * it is a narrow case in a running app; it is still reported honestly rather
+     * than guessed at.
+     */
+    readonly guards?: ReadonlyArray<ManifestGuard>;
 }
 
 /** A user table in the manifest (framework `_voltro_*` tables are excluded). */
@@ -402,6 +474,11 @@ export declare interface CapabilityTable {
     readonly columns: ReadonlyArray<CapabilityColumn>;
     readonly reactive: boolean;
     readonly framework: boolean;
+    /** The single primary-key column, when the table has one. */
+    readonly pkColumn?: string;
+    /** False when no single primary key exists — a row-keyed update/delete
+     *  cannot address a row, so the entity is list-only. */
+    readonly editable?: boolean;
 }
 
 /** Clear the buffer (devtools "Clear" button). */
@@ -562,6 +639,19 @@ export declare type CopilotAnswer<Row = Record<string, unknown>> = {
  */
 export declare const createAnalytics: <const E extends ReadonlyArray<EventDescriptor<string, unknown>>>(events: E, sink: TrackingSink) => Analytics<E>;
 
+/**
+ * Bind the typed hook surface of ONE api.
+ *
+ * `Procedures` is the generated `AppProcedures` map from that api's
+ * `rpcGroup.generated.ts`; `apiName` is the key this web app registered it under
+ * in `app.config.ts`.
+ *
+ * Call it ONCE, at module scope, and destructure the result — see the file
+ * header for why the destructured form is the one that keeps the React lint
+ * rules working.
+ */
+export declare const createHooks: <Procedures extends ProcedureTypeMap>(apiName: string) => ApiHooks<Procedures>;
+
 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. */
@@ -595,6 +685,19 @@ export declare interface DataTableState<Row> {
     readonly hasMore: boolean;
 }
 
+/**
+ * Decide, from the DECLARED access and the subject's global scopes, whether the
+ * caller may invoke a procedure. Pure — the matcher core, mirroring the
+ * server's `checkGuards`: entries are ANDed, `mode` controls AND/OR within one
+ * entry, and `admin:full` satisfies anything.
+ *
+ * `guards === undefined` (neither `guards:` nor `openAccess:`) is `unknown`,
+ * not `allowed`: an undeclared procedure is refused outright under
+ * `security.defaultDeny`, so calling it callable would be a guess in the
+ * dangerous direction.
+ */
+export declare const decideAccess: (guards: ReadonlyArray<ManifestGuard> | undefined, subjectScopes: ReadonlyArray<string>) => AccessDecision;
+
 /** All defined stores, in definition order. */
 export declare const definedStores: () => ReadonlyArray<StoreHandle<never>>;
 
@@ -621,38 +724,76 @@ export declare const defineTracking: <P = Record<string, unknown>>(name: string,
 /**
  * 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.
+ * create/update/delete it, and each carrying the access those procedures
+ * DECLARE.
+ *
+ * Everything here is derived from what the app actually exposes: an entity with
+ * no list query renders no table rather than binding to a tag that does not
+ * resolve, and an action's gate comes from the procedure's own declaration
+ * rather than a scope string this function invented.
+ *
+ * The invented ones were the bug worth naming. Gating on `<table>:create` hides
+ * the create form from every caller of every app that did not happen to name
+ * its scope that way — a total outage of the affordance, wearing a permission
+ * check's clothes, and invisible in any demo that seeds `admin:full`.
  */
 export declare const deriveEntityAdmins: (manifest: CapabilityManifest) => ReadonlyArray<EntityAdminSpec>;
 
 export declare const enqueueEntry: (queue: Outbox, id: string, tag: string, input: unknown) => Outbox;
 
+/**
+ * One operation of an entity's admin surface.
+ *
+ * `tag` is `undefined` when the app exposes NO procedure for that op — the
+ * affordance does not exist and must not be rendered. When it does exist,
+ * `guards` is that procedure's own declaration, so the UI gate and the server
+ * check read the same data.
+ */
+export declare interface EntityAction {
+    /** The procedure to invoke, when one exists. */
+    readonly tag?: string;
+    /** The access that procedure DECLARES. `undefined` = undeclared (or no
+     *  procedure at all). Feed to `useAccessDecision` / `decideAccess`. */
+    readonly guards?: ReadonlyArray<ManifestGuard>;
+}
+
 /** 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). */
+ *  each carrying the access the SERVER declares for it. */
 export declare interface EntityAdminSpec {
     readonly table: string;
+    /**
+     * The columns an admin may render. `.serverOnly()` columns are EXCLUDED —
+     * they never cross the wire, so a column header for one is always blank and a
+     * form field for one is refused by the runtime. `.sensitive()` and
+     * `.encrypted()` columns ARE present: neither axis is about the wire, and
+     * dropping them would hide data the operator is meant to see and edit.
+     */
     readonly columns: ReadonlyArray<CapabilityColumn>;
+    /**
+     * The `.serverOnly()` column names, reported so a UI can say WHY a column is
+     * absent — and so a hand-written form never binds one. The runtime's
+     * `assertNoServerOnlyInput` refuses them at the mutation boundary; this is
+     * the same rule one layer earlier, where it can be a design affordance
+     * instead of a runtime error.
+     */
+    readonly serverOnlyColumns: ReadonlyArray<string>;
+    /** Columns carrying `.sensitive(class)` — real wire data, but a bulk-export
+     *  affordance has to mask them. */
+    readonly sensitiveColumns: ReadonlyArray<string>;
     readonly reactive: boolean;
+    /** The primary-key column row-keyed actions target. `undefined` → no single
+     *  pk, so the entity is list-only. */
+    readonly pkColumn?: string;
+    /** Can a row be addressed for update/delete at all? */
+    readonly editable: boolean;
     /** Query whose `source` is this table → drives <DataTable>. */
-    readonly listTag?: string;
-    /** Mutation targeting `{table, op:'insert'}` → drives the create <AutoForm>. */
-    readonly createTag?: string;
+    readonly list: EntityAction;
+    /** Mutation targeting `{table, op:'insert'}` → the create <AutoForm>. */
+    readonly create: EntityAction;
     /** Mutation targeting `{table, op:'update'}` → row edit. */
-    readonly updateTag?: string;
+    readonly update: EntityAction;
     /** 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;
+    readonly delete: EntityAction;
 }
 
 declare interface EntryState<T> {
@@ -872,6 +1013,31 @@ export declare const makePreloadSeedBag: () => PreloadSeedBag;
 
 export declare const makeStoreSeedBag: () => StoreSeedBag;
 
+/**
+ * The access a procedure DECLARES, as data — the same declaration the server
+ * enforces, mirrored from @voltro/cli's `SerialisedGuard`.
+ *
+ * Three variants for the three states an access decision has. `open` is the
+ * erased form of `openAccess: '<why>'`; it is a DECISION, and distinguishing it
+ * from "nobody declared anything" is the whole reason it travels.
+ */
+export declare type ManifestGuard = {
+    readonly kind: 'scope';
+    readonly scope: ReadonlyArray<string>;
+    /** `all` — every scope; `any` — at least one. */
+    readonly mode: 'all' | 'any';
+    /** The guard carries a `resource` extractor, so the REAL check is per-row
+     *  and a global scope answer is incomplete by construction. */
+    readonly resourceScoped: boolean;
+} | {
+    readonly kind: 'policy';
+    readonly action: string;
+    readonly resourceType: string;
+} | {
+    readonly kind: 'open';
+    readonly reason: string;
+};
+
 /** Exported for tests: the inspect URL this hook fetches. */
 export declare const manifestUrl: (base: string) => string;
 
@@ -957,6 +1123,18 @@ export declare interface MutationState<Input, Output> {
 
 export declare type MutationStatus = 'pending' | 'success' | 'error';
 
+declare type MutationTag<P extends ProcedureTypeMap> = TagsOfKind<P, 'mutation'>;
+
+/**
+ * The reason a procedure declared itself open, or `undefined` if it did not.
+ *
+ * A helper rather than a `.find(...)` at each call site because `Array.find`
+ * does NOT narrow a discriminated union — it hands back `ManifestGuard`, so
+ * reading `.reason` off it is a type error, and the obvious workaround
+ * (`as`-casting) would read a field that may not be there.
+ */
+export declare const openAccessReason: (guards: ReadonlyArray<ManifestGuard> | undefined) => string | undefined;
+
 export declare interface OptimisticContext {
     /** Stage an optimistic patch keyed by `queryKey` (same convention as
      *  useSubscription's: `[rpcTag, input]`). The patch is automatically
@@ -988,6 +1166,15 @@ declare interface OptimisticPatch<T = unknown> {
     confirmed?: boolean;
 }
 
+/**
+ * The tags whose input has no REQUIRED field, so the input argument may be
+ * omitted. Everything else must pass one — which is what makes a forgotten
+ * required input a compile error rather than a runtime `undefined`.
+ */
+export declare type OptionalInputTag<P extends ProcedureTypeMap> = {
+    [T in keyof P]: Record<string, never> extends ProcedureInput<P[T]> ? T : never;
+}[keyof P] & keyof P;
+
 export declare type Outbox = ReadonlyArray<OutboxEntry>;
 
 export declare interface OutboxControls {
@@ -1100,6 +1287,43 @@ export declare interface PreviewState<Input> {
     readonly error: unknown | undefined;
 }
 
+/** The value a procedure's `input` schema decodes to on the client. */
+export declare type ProcedureInput<D> = D extends {
+    readonly input: infer I extends Schema.Schema.Any;
+} ? Schema.Schema.Type<I> : never;
+
+/**
+ * The value a procedure resolves to on the client.
+ *
+ * `output` for a query / mutation / action; `element` for a stream, whose
+ * per-element schema is named differently in its descriptor.
+ */
+export declare type ProcedureOutput<D> = D extends {
+    readonly output: infer O extends Schema.Schema.Any;
+} ? Schema.Schema.Type<O> : D extends {
+    readonly element: infer E extends Schema.Schema.Any;
+} ? Schema.Schema.Type<E> : never;
+
+/**
+ * The shape `createHooks` needs from ONE generated procedure entry: enough to
+ * tell queries from mutations from actions. Deliberately structural — the
+ * generated map hands over the real descriptor types (`QueryProcedureDescriptor`
+ * & co.), and this package must not import them value-level to say so.
+ */
+export declare interface ProcedureTypeLike {
+    readonly kind: string;
+}
+
+/**
+ * The generated tag → descriptor-type map. Emitted by the codegen as
+ * `AppProcedures` in `rpcGroup.generated.ts`.
+ *
+ * It is emitted as a type ALIAS, not an interface, on purpose: an interface has
+ * no implicit index signature, so `interface AppProcedures { … }` would not
+ * satisfy this constraint and every binding would fail to compile.
+ */
+export declare type ProcedureTypeMap = Readonly<Record<string, ProcedureTypeLike>>;
+
 export declare interface ProvenanceResult {
     readonly table: string;
     readonly id: string;
@@ -1140,6 +1364,9 @@ 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;
 
+/** What `useSubscription` hands back as `data` for one tag. */
+declare type QueryData<P extends ProcedureTypeMap, Tag extends keyof P> = WithOptimistic<ProcedureOutput<P[Tag]>>;
+
 export declare interface QueryFieldState {
     readonly options: ReadonlyArray<FieldOption>;
     readonly loading: boolean;
@@ -1160,6 +1387,8 @@ export declare interface QueryFiltersState<Row> {
     readonly error: unknown | undefined;
 }
 
+declare type QueryTag<P extends ProcedureTypeMap> = TagsOfKind<P, 'query'>;
+
 /**
  * The preloaded snapshot for `(api, rpcTag, input)`, or `undefined` when none was
  * seeded. On the SERVER it reads the current request's bag directly, so the SSR
@@ -1190,6 +1419,10 @@ export declare const replayable: (queue: Outbox) => Outbox;
  *  the route boundary won't catch the throw. */
 export declare const reportClientError: (error: unknown, context?: Record<string, unknown>) => void;
 
+/** The scope strings a procedure's guards require, flattened for display.
+ *  Empty for an open / policy-only / undeclared procedure. */
+export declare const requiredScopes: (guards: ReadonlyArray<ManifestGuard> | undefined) => ReadonlyArray<string>;
+
 /** 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;
@@ -1865,6 +2098,45 @@ export declare class SubscriptionCache {
      * promote naturally on their next subscriber.
      */
     refreshAll(runtime: AnyRuntime): void;
+    /**
+     * Seed this (fresh) cache with the last-known-good rows held by the cache it
+     * REPLACES, so a transport rebuild degrades to STALE DATA rather than to
+     * skeletons.
+     *
+     * A reconnect builds an entirely new client stack — new runtime, new socket,
+     * new cache — and the new cache starts empty, so every live `useSubscription`
+     * went `data: undefined` → `loading: true` and the whole app blanked until
+     * each stream's first snapshot round-tripped. Carrying the previous `base`
+     * over is the same trick `initialSnapshot` plays for SSR: render real (if
+     * momentarily old) data now, let the first server snapshot replace it.
+     *
+     * What is carried and what is NOT:
+     *
+     *   - Only entries that actually HOLD server data (`base !== undefined`).
+     *     A pending or cold-start-failed entry has nothing better than the
+     *     loading state it is already in.
+     *   - `baseError` is dropped: the new transport gets to re-establish the
+     *     truth, and a stale error banner over live data is worse than neither.
+     *   - Optimistic patches are dropped. They belong to mutations that were in
+     *     flight on the transport that just died; their success/failure — and so
+     *     their revert — is resolved against the OLD cache. Carrying them here
+     *     would strand a preview no mutation can ever retract.
+     *   - Seeded entries carry no fiber and no fetch, exactly like the stub
+     *     entries a pre-mount optimistic patch creates. The first `subscribe()`
+     *     promotes one: it saves the fetch and forks the stream, with the seeded
+     *     `base` still in place, so the component never sees `undefined`.
+     *
+     * **Caller contract — this must only be used for a SAME-SUBJECT swap.** The
+     * caller (the api supervisor) gates it on the rebuild being transport-driven.
+     * A rebuild that exists to re-resolve WHO the connection is (login, logout,
+     * tenant switch) must NOT seed: the next subject may be entitled to strictly
+     * less, and painting the previous subject's rows into their screens is a data
+     * exposure, not a UX win. That is also why `refreshAll` above clears `base`
+     * outright — same reasoning, same boundary.
+     *
+     * Returns the number of entries seeded (diagnostics / tests).
+     */
+    seedStaleFrom(previous: SubscriptionCache): number;
     private create;
     private createStub;
     private freshState;
@@ -1872,6 +2144,10 @@ export declare class SubscriptionCache {
     private invalidate;
     private getSnapshot;
     private unsubscribe;
+    /** Start (or restart) the inactive-TTL countdown for `entry`: unless
+     *  something subscribes first, interrupt its fiber and drop it. Shared by
+     *  the last-subscriber-out path and by `seedStaleFrom`'s unclaimed seeds. */
+    private scheduleEviction;
 }
 
 export declare interface SubscriptionCacheOptions {
@@ -2039,6 +2315,13 @@ export declare interface SubscriptionStateWithFallback<T> extends SubscriptionMe
     readonly isEmpty: boolean;
 }
 
+/** The tags in `P` whose procedure is of kind `K`. */
+export declare type TagsOfKind<P extends ProcedureTypeMap, K extends string> = {
+    [T in keyof P]: P[T] extends {
+        readonly kind: K;
+    } ? T : never;
+}[keyof P] & keyof P;
+
 /** A map entry: a bare event name, or a function of the component's props.
  *
  *  `P` is the component's prop type. It defaults to an untyped bag so a
@@ -2238,6 +2521,10 @@ export declare interface UploadResult {
 
 export declare type UploadStatus = 'idle' | 'uploading' | 'success' | 'error';
 
+/** Reactively decide access for one declaration, against the scopes fed to
+ *  `<PermissionProvider>`. The hook form of `decideAccess`. */
+export declare const useAccessDecision: (guards: ReadonlyArray<ManifestGuard> | undefined) => AccessDecision;
+
 export declare const useAction: <Input = unknown, Output = unknown>(apiName: string, rpcTag: string) => ActionState<Input, Output>;
 
 export declare const useAgent: (apiName: string, rpcTag: string) => AgentControls;
@@ -2702,16 +2989,31 @@ export declare interface WindowSpec {
  *  them. The server mutation funnel reads it to dedupe a retried mutation. */
 export declare const withIdempotencyKey: <A, E, R>(call: Effect.Effect<A, E, R>, key: string) => Effect.Effect<A, E, R>;
 
+/**
+ * What a subscription's `data` actually holds: the query's output, with the
+ * auto-optimistic marker the CLIENT adds.
+ *
+ * `SubscriptionCache` stamps `optimistic: true` on every row it stages on a
+ * mutation's behalf (insert prepends one, update merges one), so a live list
+ * carries a field the SERVER schema does not declare and never will. That is
+ * precisely why every hand-annotated call site wrote its own row mirror with
+ * `readonly optimistic?: boolean` bolted on — inferring the output alone would
+ * have made `row.optimistic` a type error at the exact sites the framework's
+ * headline feature is used.
+ *
+ * Only ARRAY outputs are widened, because only rows are staged. A scalar or
+ * object output is returned as the server declared it.
+ */
+export declare type WithOptimistic<T> = T extends ReadonlyArray<infer Element> ? ReadonlyArray<Element extends object ? Element & {
+    readonly optimistic?: boolean;
+} : Element> : T;
+
 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 type WorkflowDomainEventsState = (SubscriptionState<ReadonlyArray<WorkflowDomainEventRow>> | SubscriptionIdle) & {