@prometheus-ags/prometheus-entity-management 1.2.3 → 2.0.0

package/dist/index.d.mts

@@ -5,6 +5,77 @@ import React$1, { ReactNode } from 'react';
 import { ColumnDef as ColumnDef$1 } from '@tanstack/react-table';
 import { PersistStorage } from 'zustand/middleware';
 
+/**
+ * Typed errors used throughout 2.0 to drive retry policy and consumer
+ * UI decisions.
+ *
+ * Why two classes (not a discriminator field):
+ * - `instanceof` checks are zero-cost at runtime and survive bundler
+ *   minification of property names.
+ * - Consumers can write `if (error instanceof TerminalError) renderInline()`
+ *   without importing a type-narrowing helper.
+ * - The engine's retry policy is one `instanceof TransientError` check.
+ *
+ * 4xx → `TerminalError` (no retry — the request is structurally wrong:
+ * unauthorized, not-found, schema mismatch, validation failure).
+ *
+ * 5xx + network failures → `TransientError` (engine retries with
+ * exponential backoff up to `maxRetries`).
+ *
+ * Custom transports can throw either class. The default REST helper
+ * (`makeRestTransport`) maps HTTP status codes to the appropriate
+ * class automatically.
+ *
+ * Both classes preserve the original error via the standard
+ * `cause` option so stack traces survive the boundary.
+ */
+interface EntityErrorOptions {
+    /** HTTP status if the underlying transport was HTTP. */
+    status?: number;
+    /** Original thrown value (`Error`, `Response`, anything). */
+    cause?: unknown;
+}
+/**
+ * Permanent failure — do not retry. The request will not succeed by
+ * trying again with the same inputs.
+ *
+ * Typical sources: HTTP 4xx, missing tables, validation errors,
+ * permission denied, schema mismatches.
+ */
+declare class TerminalError extends Error {
+    readonly kind: "terminal";
+    readonly status?: number;
+    constructor(message: string, opts?: EntityErrorOptions);
+}
+/**
+ * Temporary failure — safe to retry. The engine will retry with
+ * exponential backoff up to the configured `maxRetries`.
+ *
+ * Typical sources: HTTP 5xx, network timeouts, fetch rejections,
+ * dropped sockets.
+ */
+declare class TransientError extends Error {
+    readonly kind: "transient";
+    readonly status?: number;
+    constructor(message: string, opts?: EntityErrorOptions);
+}
+/**
+ * Union of every typed error the library raises. Use on consumer-side
+ * `error` props when both classes are possible.
+ */
+type EntityError = TerminalError | TransientError;
+/**
+ * Convert an unknown thrown value into a typed entity error.
+ *
+ * - Already-typed errors pass through.
+ * - HTTP-status-bearing errors become Terminal (4xx) or Transient (5xx).
+ * - `AbortError` / `DOMException` "AbortError" → Terminal (caller
+ *   cancelled; not worth retrying).
+ * - Everything else → Transient (assume retryable; better than
+ *   accidentally permanently failing on a one-off network blip).
+ */
+declare function toEntityError(err: unknown): EntityError;
+
 /** Logical entity kind (e.g. `"Post"`). Used to partition the normalized graph. */
 type EntityType = string;
 /** Primary key for an entity within its `type`. Lists and relations reference this, not row copies. */
@@ -20,7 +91,7 @@ interface EntitySyncMetadata {
     updatedAt: number | null;
 }
 /** Snapshot shape returned by sync-aware reads and graph-native query helpers. */
-type EntitySnapshot<T extends Record<string, unknown>> = T & {
+type EntitySnapshot<T extends object> = T & {
     $synced: boolean;
     $origin: SyncOrigin;
     $updatedAt: number | null;
@@ -49,6 +120,14 @@ interface ListState {
     isFetching: boolean;
     isFetchingMore: boolean;
     error: string | null;
+    /**
+     * Typed error instance for 2.0 hooks (`useEntities`, `useEntityQuery`).
+     * Carries `TerminalError` / `TransientError` so consumers can
+     * `instanceof`-check the failure mode without parsing the string in
+     * `error`. Both fields are written together by `setListError`; the
+     * string `error` field remains for back-compat with 1.x consumers.
+     */
+    lastError: EntityError | null;
     lastFetched: number | null;
     stale: boolean;
     currentPage: number | null;
@@ -131,8 +210,13 @@ interface GraphState {
     setListFetching: (key: QueryKey, fetching: boolean) => void;
     /** Pagination / “load more” in progress for the same list key. */
     setListFetchingMore: (key: QueryKey, fetchingMore: boolean) => void;
-    /** Record list fetch failure; clears both fetching flags. */
-    setListError: (key: QueryKey, error: string | null) => void;
+    /**
+     * Record list fetch failure; clears both fetching flags.
+     * The optional `typed` argument is the typed `EntityError` instance
+     * (used by 2.0 hooks); when omitted only the string `error` field is
+     * populated (back-compat with 1.x callers).
+     */
+    setListError: (key: QueryKey, error: string | null, typed?: EntityError | null) => void;
     /** Mark a list query stale so hooks can refetch without discarding current ids (stale-while-revalidate). */
     setListStale: (key: QueryKey, stale: boolean) => void;
     /**
@@ -210,6 +294,21 @@ declare const useGraphStore: zustand.UseBoundStore<Omit<Omit<zustand.StoreApi<Gr
                 isFetching: boolean;
                 isFetchingMore: boolean;
                 error: string | null;
+                lastError: {
+                    kind: "terminal";
+                    status?: number | undefined;
+                    name: string;
+                    message: string;
+                    stack?: string | undefined;
+                    cause?: unknown;
+                } | {
+                    kind: "transient";
+                    status?: number | undefined;
+                    name: string;
+                    message: string;
+                    stack?: string | undefined;
+                    cause?: unknown;
+                } | null;
                 lastFetched: number | null;
                 stale: boolean;
                 currentPage: number | null;
@@ -239,7 +338,7 @@ declare const useGraphStore: zustand.UseBoundStore<Omit<Omit<zustand.StoreApi<Gr
         insertIdInList: (key: QueryKey, id: EntityId, position: "start" | "end" | number) => void;
         setListFetching: (key: QueryKey, fetching: boolean) => void;
         setListFetchingMore: (key: QueryKey, fetchingMore: boolean) => void;
-        setListError: (key: QueryKey, error: string | null) => void;
+        setListError: (key: QueryKey, error: string | null, typed?: EntityError | null) => void;
         setListStale: (key: QueryKey, stale: boolean) => void;
         invalidateEntity: (type: EntityType, id?: EntityId) => void;
         invalidateLists: (matcher: string | ((key: QueryKey) => boolean)) => void;
@@ -288,6 +387,21 @@ declare const useGraphStore: zustand.UseBoundStore<Omit<Omit<zustand.StoreApi<Gr
                 isFetching: boolean;
                 isFetchingMore: boolean;
                 error: string | null;
+                lastError: {
+                    kind: "terminal";
+                    status?: number | undefined;
+                    name: string;
+                    message: string;
+                    stack?: string | undefined;
+                    cause?: unknown;
+                } | {
+                    kind: "transient";
+                    status?: number | undefined;
+                    name: string;
+                    message: string;
+                    stack?: string | undefined;
+                    cause?: unknown;
+                } | null;
                 lastFetched: number | null;
                 stale: boolean;
                 currentPage: number | null;
@@ -317,7 +431,7 @@ declare const useGraphStore: zustand.UseBoundStore<Omit<Omit<zustand.StoreApi<Gr
         insertIdInList: (key: QueryKey, id: EntityId, position: "start" | "end" | number) => void;
         setListFetching: (key: QueryKey, fetching: boolean) => void;
         setListFetchingMore: (key: QueryKey, fetchingMore: boolean) => void;
-        setListError: (key: QueryKey, error: string | null) => void;
+        setListError: (key: QueryKey, error: string | null, typed?: EntityError | null) => void;
         setListStale: (key: QueryKey, stale: boolean) => void;
         invalidateEntity: (type: EntityType, id?: EntityId) => void;
         invalidateLists: (matcher: string | ((key: QueryKey) => boolean)) => void;
@@ -327,6 +441,481 @@ declare const useGraphStore: zustand.UseBoundStore<Omit<Omit<zustand.StoreApi<Gr
     }) => void), shouldReplace: true): void;
 }>;
 
+/**
+ * Compiles a {@link FilterSpec} into a Prisma `where` object (plain JSON-serializable shape).
+ *
+ * Operator mapping matches common Prisma filter APIs: `eq` → `equals`, string ops use `mode: "insensitive"`,
+ * `nin` → `notIn`, `arrayContains` → `has`, `isNull` uses `null` / `{ not: null }` per `value`, and `isNotNull` → `{ not: null }`.
+ * Unsupported ops (`between`, `arrayOverlaps`, `matches`, `custom`) are omitted from the result.
+ *
+ * Top-level clause arrays are combined with `AND`. {@link FilterGroup} uses `AND` / `OR` to match `group.logic`.
+ */
+declare function toPrismaWhere(filter: FilterSpec): Record<string, unknown>;
+/**
+ * Compiles a {@link SortSpec} into Prisma `orderBy` form: `[{ fieldName: "asc" | "desc" }, …]`.
+ * `nulls` and `comparator` on {@link SortClause} are ignored (local-only); extend callers if your Prisma version supports null ordering.
+ */
+declare function toPrismaOrderBy(sort: SortSpec): Record<string, string>[];
+
+/**
+ * Transport-agnostic comparison operators. Same spec can compile to REST, SQL, GraphQL, or local JS (`evaluator`).
+ * `custom` opts out of automatic serialization — use for predicates only the client can evaluate.
+ */
+type FilterOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "contains" | "startsWith" | "endsWith" | "isNull" | "isNotNull" | "between" | "arrayContains" | "arrayOverlaps" | "matches" | "custom";
+/** Atomic filter: field path, operator, optional value, and optional JS predicate for `custom`. */
+interface FilterClause {
+    field: string;
+    op: FilterOperator;
+    value?: unknown;
+    predicate?: (fieldValue: unknown, entity: Record<string, unknown>) => boolean;
+}
+type FilterLogic = "and" | "or";
+/** Nested boolean group so you can express `(A AND B) OR C` without losing structure when compiling to backends. */
+interface FilterGroup {
+    logic: FilterLogic;
+    clauses: Array<FilterClause | FilterGroup>;
+}
+/** Top-level filter: flat AND list of clauses, or a recursive `FilterGroup`. */
+type FilterSpec = FilterGroup | FilterClause[];
+type SortDirection = "asc" | "desc";
+/** Single sort key with optional null ordering and custom comparator for local sort parity with remote semantics. */
+interface SortClause {
+    field: string;
+    direction: SortDirection;
+    nulls?: "first" | "last";
+    comparator?: (a: unknown, b: unknown) => number;
+}
+/** Ordered multi-key sort (stable application in `compareEntities`). */
+type SortSpec = SortClause[];
+/**
+ * Everything `useEntityView` needs to describe a virtualized collection: filters, sorts, and simple multi-field search.
+ * One descriptor can drive local evaluation, remote query compilation, or hybrid mode.
+ */
+interface ViewDescriptor {
+    filter?: FilterSpec;
+    sort?: SortSpec;
+    search?: {
+        query: string;
+        fields: string[];
+        minChars?: number;
+    };
+}
+/**
+ * How complete local graph data is relative to the view: **local** (all in memory), **remote** (server must filter/sort), **hybrid** (show local fast + remote reconcile).
+ */
+type CompletenessMode = "local" | "remote" | "hybrid";
+/**
+ * Compile a view to flat REST query params (`sort`, `q`, and `field[op]=value` keys). Skips `custom` clauses — those cannot be expressed as strings.
+ */
+declare function toRestParams(view: ViewDescriptor): Record<string, string>;
+/**
+ * Compile a view to parameterized SQL fragments for server-side filtering/sorting. Unknown ops become `TRUE` — validate or restrict ops at the edge.
+ */
+declare function toSQLClauses(view: ViewDescriptor): {
+    where: string;
+    orderBy: string;
+    params: unknown[];
+};
+/**
+ * Produce a GraphQL-variable-shaped object from a view (Hasura/Postgraphile-style `_op` maps). Intended as a starting point — wire to your actual schema.
+ */
+declare function toGraphQLVariables(view: ViewDescriptor): {
+    where?: Record<string, unknown>;
+    orderBy?: Array<Record<string, unknown>>;
+    search?: string;
+};
+
+/**
+ * Normalize nested `FilterGroup` trees to a flat clause list for compilers that only understand atomic predicates.
+ */
+declare function flattenClauses(filter: FilterSpec): FilterClause[];
+/** True if any clause requires client-side `predicate` logic — forces local/hybrid evaluation paths that cannot be pushed to generic REST/SQL. */
+declare function hasCustomPredicates(filter: FilterSpec): boolean;
+
+/**
+ * 2.0 transport contract.
+ *
+ * Why this exists: in 1.x each call site of `useEntityList` /
+ * `useEntityView` passed its own `fetch` closure + `normalize`
+ * callback. That leaked the transport contract to every consumer and
+ * was the structural cause of the Quick Stats trap — each widget could
+ * (and did) reinvent the same retry-loop bug.
+ *
+ * In 2.0 the transport is registered ONCE per entity type at app boot
+ * via `registerEntityTransport(type, transport)`. Hooks
+ * (`useEntities`, `useEntityQuery`) look up the registered transport
+ * by entity type — consumers never pass a fetcher.
+ *
+ * Transports are pluggable: a built-in `makeRestTransport` covers
+ * PostgREST / Supabase; future helpers can cover GraphQL, PGlite-direct,
+ * mock-in-memory, etc. The contract is intentionally tiny.
+ */
+
+/**
+ * Transport-agnostic list query passed by `useEntities` / `useEntityQuery`
+ * down to the registered transport.
+ *
+ * The transport is responsible for compiling this into the
+ * transport-specific wire format (HTTP query string, GraphQL variables,
+ * SQL WHERE, in-memory predicate, etc.).
+ */
+interface ListQuery {
+    /** Optional filter; transport-agnostic, see `FilterSpec`. */
+    filter?: FilterSpec | null;
+    /** Optional sort spec; transport-agnostic. */
+    sort?: SortSpec | null;
+    /** Free-text search string; transport decides which fields to match. */
+    search?: string;
+    /** Page size hint. Transport may cap or ignore. */
+    limit?: number;
+    /** Opaque cursor for pagination (cursor or numeric offset). */
+    cursor?: string | number | null;
+    /** Aborts the request when fired. Transports MUST honour this. */
+    signal?: AbortSignal;
+}
+/**
+ * Page of results returned by `EntityTransport.list`.
+ *
+ * `total` is `null` when the backend doesn't report it cheaply
+ * (consumers should treat as "unknown" rather than "zero").
+ *
+ * `nextCursor` is `null`/`undefined` when there are no more pages.
+ */
+interface ListResult<T> {
+    rows: T[];
+    total: number | null;
+    nextCursor?: string | number | null;
+}
+/**
+ * Operation flavour for a realtime change event.
+ */
+type ChangeOp = "insert" | "update" | "delete";
+/**
+ * Realtime change event emitted by a transport's `subscribe`.
+ *
+ * For `delete` only `id` is meaningful; `row` MAY be omitted.
+ */
+interface ChangeEvent<T> {
+    op: ChangeOp;
+    id: string;
+    row?: T;
+}
+/**
+ * The full per-entity transport contract.
+ *
+ * One transport per entity type, registered at app boot. The hooks
+ * (`useEntities`, `useEntityQuery`) look it up via `getEntityTransport(type)`.
+ *
+ * Required: `identify`, `authoritative`, `list`.
+ * Optional: `get` (for single-row fetches), `subscribe` (for realtime),
+ * `staleTime` (hint for SWR).
+ */
+interface EntityTransport<T extends object> {
+    /**
+     * Derive the stable string id of a row. Used by the engine to write
+     * into the entity graph under the right id key.
+     */
+    identify: (row: T) => string;
+    /**
+     * `true` when the local copy is considered authoritative (e.g. PGlite
+     * + Electric Tier-A sync) — consumers can render from cache without
+     * a remote round-trip on every mount.
+     *
+     * `false` when the remote is authoritative (Tier-B REST hybrid) — the
+     * cache is a hint, not the truth.
+     */
+    authoritative: boolean;
+    /**
+     * Stale-time hint in ms. The engine SWR logic refetches when
+     * `Date.now() - lastFetched > staleTime`. Omit to inherit the engine
+     * default (30s).
+     */
+    staleTime?: number;
+    /** Fetch a list. The signal in `q.signal` MUST be honoured. */
+    list: (q: ListQuery) => Promise<ListResult<T>>;
+    /** Fetch a single row by id. Optional. */
+    get?: (id: string, signal?: AbortSignal) => Promise<T | null>;
+    /**
+     * Subscribe to realtime change events for this entity type. Optional.
+     *
+     * Called by `useEntities` / `useEntityQuery` exactly once per
+     * subscriber-bearing key. The returned function MUST tear down all
+     * underlying resources (sockets, channels, intervals).
+     */
+    subscribe?: (onChange: (ev: ChangeEvent<T>) => void) => () => void;
+}
+
+/**
+ * Process-global registry of `EntityTransport` instances by entity type.
+ *
+ * Why global state: every consumer of `useEntities("Client")` must
+ * resolve the SAME transport. Threading a registry through React
+ * context would require every test, every isolated story, every
+ * non-React caller (engine internals) to plumb the context — a tax
+ * that buys nothing. The 1.x library already used module-global state
+ * for the `useGraphStore` Zustand store; this follows the same shape.
+ *
+ * The registry is mutable: re-registering a type silently replaces the
+ * prior transport (tests rely on this; production code should only
+ * register once at app boot).
+ */
+
+/**
+ * Register the transport for an entity type. Called once per type at
+ * app boot, typically from `src/shared/db/entity-transports.ts` in the
+ * consuming application.
+ *
+ * Re-registering REPLACES the prior transport — useful for tests, a
+ * footgun for production code. If you find yourself re-registering at
+ * runtime, you almost certainly want a different design.
+ */
+declare function registerEntityTransport<T extends object>(type: EntityType, transport: EntityTransport<T>): void;
+/**
+ * Look up the transport for an entity type. Throws if none is
+ * registered — there is no "default" transport, by design.
+ *
+ * The cast to `EntityTransport<T>` is the API ergonomic
+ * compromise that lets call sites stay generic; the registry stores
+ * `EntityTransport<object>` because TypeScript can't otherwise unify
+ * heterogeneous rows in one map.
+ */
+declare function getEntityTransport<T extends object>(type: EntityType): EntityTransport<T>;
+/**
+ * Test-only: clear ALL registered transports. Production code should
+ * never need this; tests use it to reset between specs.
+ */
+declare function __resetEntityTransports(): void;
+/**
+ * Introspection: how many transports are currently registered.
+ * Useful for asserting in tests that boot wiring ran exactly once.
+ */
+declare function getRegisteredEntityTypes(): EntityType[];
+
+/**
+ * `makeRestTransport` — built-in helper for the most common case: a
+ * Supabase / PostgREST backend reached through a `SupabaseClient`-like
+ * object.
+ *
+ * Why a helper (not a class): consumers stay declarative —
+ *   registerEntityTransport("Client",
+ *     makeRestTransport<Client>({ supabase, table: "client" }));
+ * — and the library never imports `@supabase/supabase-js` directly
+ * (peer-dep-free).
+ *
+ * The transport:
+ * - Compiles `ListQuery` (filter / sort / search / cursor / limit)
+ *   into a PostgREST query via the supabase-js builder.
+ * - Maps HTTP status to `TerminalError` (4xx) or `TransientError`
+ *   (5xx / network).
+ * - Honours `AbortSignal` via supabase-js `.abortSignal(signal)`.
+ * - Returns `total` from PostgREST `count: 'exact'` when requested.
+ */
+
+/**
+ * Minimal slice of the `@supabase/supabase-js` `SupabaseClient` we use.
+ * Declared structurally so the library does not need to import the
+ * package as a dependency (peer-dep-free).
+ */
+interface SupabaseLike {
+    from: (table: string) => SupabaseQueryBuilderLike;
+}
+/**
+ * Subset of the supabase-js builder we exercise. Each call returns the
+ * same builder for chaining; `then`-able at the end resolves to
+ * `{ data, error, count, status }`.
+ */
+interface SupabaseQueryBuilderLike {
+    select: (columns: string, opts?: {
+        count?: "exact" | "planned" | "estimated";
+        head?: boolean;
+    }) => SupabaseQueryBuilderLike;
+    eq: (col: string, val: unknown) => SupabaseQueryBuilderLike;
+    neq: (col: string, val: unknown) => SupabaseQueryBuilderLike;
+    gt: (col: string, val: unknown) => SupabaseQueryBuilderLike;
+    gte: (col: string, val: unknown) => SupabaseQueryBuilderLike;
+    lt: (col: string, val: unknown) => SupabaseQueryBuilderLike;
+    lte: (col: string, val: unknown) => SupabaseQueryBuilderLike;
+    in: (col: string, vals: readonly unknown[]) => SupabaseQueryBuilderLike;
+    ilike: (col: string, pattern: string) => SupabaseQueryBuilderLike;
+    is: (col: string, val: null | boolean) => SupabaseQueryBuilderLike;
+    or: (filter: string) => SupabaseQueryBuilderLike;
+    order: (col: string, opts?: {
+        ascending?: boolean;
+        nullsFirst?: boolean;
+    }) => SupabaseQueryBuilderLike;
+    range: (from: number, to: number) => SupabaseQueryBuilderLike;
+    limit: (n: number) => SupabaseQueryBuilderLike;
+    abortSignal?: (signal: AbortSignal) => SupabaseQueryBuilderLike;
+    then: <TResult1 = unknown, TResult2 = never>(onfulfilled?: ((value: {
+        data: unknown;
+        error: unknown;
+        count?: number | null;
+        status?: number;
+    }) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null) => Promise<TResult1 | TResult2>;
+}
+/** Options for `makeRestTransport`. */
+interface MakeRestTransportOptions<T extends object> {
+    /** A `@supabase/supabase-js` client (or any structurally-compatible thing). */
+    supabase: SupabaseLike;
+    /** PostgREST table name. */
+    table: string;
+    /** Columns to select (default `"*"`). */
+    select?: string;
+    /** Stable id derivation. Defaults to `(row) => String(row.id)`. */
+    identify?: (row: T) => string;
+    /** Whether the local cache is treated as authoritative. */
+    authoritative?: boolean;
+    /** Stale-time hint in ms. */
+    staleTime?: number;
+    /** Free-text search column list (compiled to `or=col.ilike.*query*,…`). */
+    searchColumns?: string[];
+    /** Default page size when `ListQuery.limit` is absent. */
+    defaultLimit?: number;
+}
+/**
+ * Build an `EntityTransport<T>` from a Supabase client + a table name.
+ *
+ * The returned transport:
+ * - Maps `ListQuery.filter` clauses to PostgREST operators (`eq`, `gt`,
+ *   `in`, `ilike`, `is null`, etc.).
+ * - Compiles `ListQuery.search` into an `or=` clause across
+ *   `searchColumns`.
+ * - Uses `count: 'exact'` on first page to surface `total`.
+ * - Throws `TerminalError` on 4xx (no retry); `TransientError` on 5xx
+ *   or network failure.
+ * - Honours `signal` via `.abortSignal(signal)` (supabase-js >= 2.39).
+ */
+declare function makeRestTransport<T extends object>(opts: MakeRestTransportOptions<T>): EntityTransport<T>;
+
+/**
+ * `useEntities` — thin 2.0 hook (5-field API).
+ *
+ * Replaces the `useEntityList(opts)` pattern where each call site carried
+ * its own `fetch` closure, query-key shape, and retry logic. Instead:
+ *
+ *   1. Register a transport once at app boot:
+ *      `registerEntityTransport("Invoice", makeRestTransport({ supabase, table: "invoice" }))`
+ *
+ *   2. Consume anywhere:
+ *      `const { items, isLoading, isError, error } = useEntities<Invoice>("Invoice")`
+ *
+ * - 4xx from transport → `TerminalError`, no retry, `isError: true`, `isLoading: false`
+ * - 5xx/network → `TransientError`, up to `maxRetries` with exponential back-off
+ * - `enabled: false` → no fetch, `isLoading: false` immediately
+ * - SWR: within `staleTime` (from transport or engine default) → cached rows, no refetch
+ * - AbortController per fetch; aborted on unmount, key change, or `refetch()`
+ * - Transport `subscribe` wired on mount, torn down on unmount
+ */
+
+/** Subset of `ListQuery` that callers may pass alongside `enabled`. */
+interface UseEntitiesOptions {
+    filter?: FilterSpec | null;
+    sort?: SortSpec | null;
+    search?: string;
+    limit?: number;
+    cursor?: string | number | null;
+    enabled?: boolean;
+}
+/** Five-field return — the entirety of what a list consumer needs for the common case. */
+interface UseEntitiesResult<T> {
+    /** Resolved entity rows in the graph for this query, in server order. */
+    items: T[];
+    /** True only while the very first attempt is in-flight with no cached rows yet. */
+    isLoading: boolean;
+    /** True when the last attempt ended with any error (terminal or transient). */
+    isError: boolean;
+    /** Typed error instance — `instanceof TerminalError` (4xx) or `instanceof TransientError` (5xx/network). */
+    error: TerminalError | TransientError | null;
+    /** Manually trigger a fresh fetch (bypasses staleTime). */
+    refetch: () => void;
+}
+/**
+ * Thin replacement for `useEntityList`.
+ * Looks up the registered `EntityTransport<T>` for `type` and drives a
+ * Zustand-backed SWR cycle. Returns `{ items, isLoading, isError, error, refetch }`.
+ */
+declare function useEntities<T extends object>(type: EntityType, options?: UseEntitiesOptions): UseEntitiesResult<T>;
+
+/**
+ * `useEntityQuery` — rich 2.0 hook (replaces `useEntityView`).
+ *
+ * Same feature surface as `useEntityView` (view descriptor, hybrid mode,
+ * pagination, realtime sorted insertion, toolbar setters) but transport is
+ * looked up from the registry — callers no longer pass `remoteFetch`.
+ *
+ * Usage:
+ *   registerEntityTransport("Client", makeRestTransport({ supabase, table: "client" }));
+ *
+ *   const { items, setFilter, setSort, setSearch, fetchNextPage, error } =
+ *     useEntityQuery<Client>("Client", { view: defaultView });
+ */
+
+interface UseEntityQueryOptions {
+    /** Initial view descriptor (filter/sort/search). */
+    view?: ViewDescriptor;
+    /** Force a completeness mode instead of auto-detecting. */
+    mode?: CompletenessMode;
+    /** Skip all fetching when false. `isLoading` is immediately `false`. */
+    enabled?: boolean;
+    /** SSR-seed ids for the base list slot (avoids flash-of-empty-state). */
+    initialIds?: EntityId[];
+    /** SSR-seed total for completeness heuristics. */
+    initialTotal?: number;
+    /** Debounce delay (ms) for view changes before a remote re-fetch fires. */
+    remoteDebounce?: number;
+}
+interface UseEntityQueryResult<T> {
+    /** Projected entity rows visible through the current view. */
+    items: T[];
+    /** All ids in the projected view (for virtualised renderers). */
+    viewIds: EntityId[];
+    /** Server-reported total or local count if complete, else null. */
+    viewTotal: number | null;
+    /** True while the very first page is loading with zero cached rows. */
+    isLoading: boolean;
+    /** True while any fetch (initial or page) is in-flight. */
+    isFetching: boolean;
+    /** True while a paginated "load more" fetch is in-flight. */
+    isFetchingMore: boolean;
+    /** True when the last attempt ended with any error. */
+    isError: boolean;
+    /**
+     * Typed error — `instanceof TerminalError` (4xx) or
+     * `instanceof TransientError` (5xx/network). `null` on success.
+     */
+    error: TerminalError | TransientError | null;
+    /** True when there are more pages to load. */
+    hasNextPage: boolean;
+    /** Load the next page of results. */
+    fetchNextPage: () => void;
+    /** True when `completenessMode === "hybrid"` and remote is still in-flight while local rows are displayed. */
+    isShowingLocalPending: boolean;
+    /** Whether local graph data is complete for the current view. */
+    isLocallyComplete: boolean;
+    /** Resolved completeness mode for the current view. */
+    completenessMode: CompletenessMode;
+    /** Merge partial view descriptor updates. */
+    setView: (v: Partial<ViewDescriptor>) => void;
+    /** Replace the active filter spec. */
+    setFilter: (f: FilterSpec | null) => void;
+    /** Replace the active sort spec. */
+    setSort: (s: SortSpec | null) => void;
+    /** Update free-text search query. */
+    setSearch: (q: string) => void;
+    /** Reset view to the initial descriptor. */
+    clearView: () => void;
+    /** Force a fresh fetch (bypasses staleTime). */
+    refetch: () => void;
+}
+/**
+ * Rich list hook: view descriptor, local/remote/hybrid completeness, pagination,
+ * realtime sorted insertion, typed errors — all backed by the transport registry.
+ *
+ * @param type - Registered entity type key (e.g. `"Client"`)
+ * @param opts - View descriptor, mode override, SSR seeds, enabled gate
+ */
+declare function useEntityQuery<T extends object>(type: EntityType, opts?: UseEntityQueryOptions): UseEntityQueryResult<T>;
+
 type GraphStore = ReturnType<typeof useGraphStore.getState>;
 type GraphIncludeMap = Record<string, GraphIncludeRelation>;
 type GraphIncludeRelation = {
@@ -358,7 +947,7 @@ type GraphIncludeRelation = {
     };
     include?: GraphIncludeMap;
 };
-interface GraphQueryOptions<TEntity extends Record<string, unknown>> {
+interface GraphQueryOptions<TEntity extends object> {
     type: EntityType;
     id?: EntityId;
     ids?: EntityId[];
@@ -369,10 +958,10 @@ interface GraphQueryOptions<TEntity extends Record<string, unknown>> {
     select?: ((entity: Record<string, unknown>) => unknown) | string[];
 }
 type ProjectedRow = Record<string, unknown>;
-declare function queryOnce<TEntity extends Record<string, unknown>>(opts: GraphQueryOptions<TEntity> & {
+declare function queryOnce<TEntity extends object>(opts: GraphQueryOptions<TEntity> & {
     id: EntityId;
 }): ProjectedRow | null;
-declare function queryOnce<TEntity extends Record<string, unknown>>(opts: GraphQueryOptions<TEntity>): ProjectedRow[];
+declare function queryOnce<TEntity extends object>(opts: GraphQueryOptions<TEntity>): ProjectedRow[];
 declare const selectGraph: typeof queryOnce;
 
 interface GraphDataSnapshot {
@@ -445,97 +1034,6 @@ interface GraphEffectHandle {
 }
 declare function createGraphEffect<T>(opts: GraphEffectOptions<T>): GraphEffectHandle;
 
-/**
- * Compiles a {@link FilterSpec} into a Prisma `where` object (plain JSON-serializable shape).
- *
- * Operator mapping matches common Prisma filter APIs: `eq` → `equals`, string ops use `mode: "insensitive"`,
- * `nin` → `notIn`, `arrayContains` → `has`, `isNull` uses `null` / `{ not: null }` per `value`, and `isNotNull` → `{ not: null }`.
- * Unsupported ops (`between`, `arrayOverlaps`, `matches`, `custom`) are omitted from the result.
- *
- * Top-level clause arrays are combined with `AND`. {@link FilterGroup} uses `AND` / `OR` to match `group.logic`.
- */
-declare function toPrismaWhere(filter: FilterSpec): Record<string, unknown>;
-/**
- * Compiles a {@link SortSpec} into Prisma `orderBy` form: `[{ fieldName: "asc" | "desc" }, …]`.
- * `nulls` and `comparator` on {@link SortClause} are ignored (local-only); extend callers if your Prisma version supports null ordering.
- */
-declare function toPrismaOrderBy(sort: SortSpec): Record<string, string>[];
-
-/**
- * Transport-agnostic comparison operators. Same spec can compile to REST, SQL, GraphQL, or local JS (`evaluator`).
- * `custom` opts out of automatic serialization — use for predicates only the client can evaluate.
- */
-type FilterOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "contains" | "startsWith" | "endsWith" | "isNull" | "isNotNull" | "between" | "arrayContains" | "arrayOverlaps" | "matches" | "custom";
-/** Atomic filter: field path, operator, optional value, and optional JS predicate for `custom`. */
-interface FilterClause {
-    field: string;
-    op: FilterOperator;
-    value?: unknown;
-    predicate?: (fieldValue: unknown, entity: Record<string, unknown>) => boolean;
-}
-type FilterLogic = "and" | "or";
-/** Nested boolean group so you can express `(A AND B) OR C` without losing structure when compiling to backends. */
-interface FilterGroup {
-    logic: FilterLogic;
-    clauses: Array<FilterClause | FilterGroup>;
-}
-/** Top-level filter: flat AND list of clauses, or a recursive `FilterGroup`. */
-type FilterSpec = FilterGroup | FilterClause[];
-type SortDirection = "asc" | "desc";
-/** Single sort key with optional null ordering and custom comparator for local sort parity with remote semantics. */
-interface SortClause {
-    field: string;
-    direction: SortDirection;
-    nulls?: "first" | "last";
-    comparator?: (a: unknown, b: unknown) => number;
-}
-/** Ordered multi-key sort (stable application in `compareEntities`). */
-type SortSpec = SortClause[];
-/**
- * Everything `useEntityView` needs to describe a virtualized collection: filters, sorts, and simple multi-field search.
- * One descriptor can drive local evaluation, remote query compilation, or hybrid mode.
- */
-interface ViewDescriptor {
-    filter?: FilterSpec;
-    sort?: SortSpec;
-    search?: {
-        query: string;
-        fields: string[];
-        minChars?: number;
-    };
-}
-/**
- * How complete local graph data is relative to the view: **local** (all in memory), **remote** (server must filter/sort), **hybrid** (show local fast + remote reconcile).
- */
-type CompletenessMode = "local" | "remote" | "hybrid";
-/**
- * Compile a view to flat REST query params (`sort`, `q`, and `field[op]=value` keys). Skips `custom` clauses — those cannot be expressed as strings.
- */
-declare function toRestParams(view: ViewDescriptor): Record<string, string>;
-/**
- * Compile a view to parameterized SQL fragments for server-side filtering/sorting. Unknown ops become `TRUE` — validate or restrict ops at the edge.
- */
-declare function toSQLClauses(view: ViewDescriptor): {
-    where: string;
-    orderBy: string;
-    params: unknown[];
-};
-/**
- * Produce a GraphQL-variable-shaped object from a view (Hasura/Postgraphile-style `_op` maps). Intended as a starting point — wire to your actual schema.
- */
-declare function toGraphQLVariables(view: ViewDescriptor): {
-    where?: Record<string, unknown>;
-    orderBy?: Array<Record<string, unknown>>;
-    search?: string;
-};
-
-/**
- * Normalize nested `FilterGroup` trees to a flat clause list for compilers that only understand atomic predicates.
- */
-declare function flattenClauses(filter: FilterSpec): FilterClause[];
-/** True if any clause requires client-side `predicate` logic — forces local/hybrid evaluation paths that cannot be pushed to generic REST/SQL. */
-declare function hasCustomPredicates(filter: FilterSpec): boolean;
-
 /**
  * Process-wide defaults for stale times, retries, and background revalidation.
  * Keeps hook signatures small: `useEntity` / `useEntityList` merge these with per-query overrides.
@@ -555,7 +1053,7 @@ interface EngineOptions {
  * Declarative **instruction** for loading one entity: wire transport (`fetch`), normalization, and graph writes.
  * Hooks pass this to `fetchEntity`; the graph remains source of truth after success.
  */
-interface EntityQueryOptions<TRaw, TEntity extends Record<string, unknown>> {
+interface EntityQueryOptions<TRaw, TEntity extends object> {
     type: EntityType;
     id: EntityId | null | undefined;
     fetch: (id: EntityId) => Promise<TRaw>;
@@ -579,8 +1077,8 @@ interface ListFetchParams {
  */
 interface ListResponse<T> {
     items: T[];
-    total?: number;
-    nextCursor?: string;
+    total?: number | null;
+    nextCursor?: string | null;
     prevCursor?: string;
     hasNextPage?: boolean;
     hasPrevPage?: boolean;
@@ -591,7 +1089,7 @@ interface ListResponse<T> {
  * Declarative **instruction** for a collection query: stable `queryKey`, fetcher, and per-row normalization into the graph.
  * `mode` controls whether a fetch replaces ids or appends (infinite scroll) when used with load-more.
  */
-interface ListQueryOptions<TRaw, TEntity extends Record<string, unknown>> {
+interface ListQueryOptions<TRaw, TEntity extends object> {
     type: EntityType;
     queryKey: unknown[];
     fetch: (params: ListFetchParams) => Promise<ListResponse<TRaw>>;
@@ -633,12 +1131,12 @@ declare function configureEngine(opts: EngineOptions): void;
  * Run a single-entity fetch with dedupe, retries, normalization, and graph updates.
  * Call from hooks/adapters — not from presentational components.
  */
-declare function fetchEntity<TRaw, TEntity extends Record<string, unknown>>(opts: EntityQueryOptions<TRaw, TEntity>, engineOpts: Required<EngineOptions>): Promise<void>;
+declare function fetchEntity<TRaw, TEntity extends object>(opts: EntityQueryOptions<TRaw, TEntity>, engineOpts: Required<EngineOptions>): Promise<void>;
 /**
  * Fetch a list page: upserts all rows, writes ids to the list key, supports append mode for pagination.
  * @param isLoadMore - When true, uses a separate dedupe key and `appendListResult` / `setListFetchingMore`.
  */
-declare function fetchList<TRaw, TEntity extends Record<string, unknown>>(opts: ListQueryOptions<TRaw, TEntity>, params: ListFetchParams, engineOpts: Required<EngineOptions>, isLoadMore?: boolean): Promise<void>;
+declare function fetchList<TRaw, TEntity extends object>(opts: ListQueryOptions<TRaw, TEntity>, params: ListFetchParams, engineOpts: Required<EngineOptions>, isLoadMore?: boolean): Promise<void>;
 
 /**
  * Precompiled transport payloads for one view snapshot — pass to REST, GraphQL, or SQL backends without re-deriving from `ViewDescriptor`.
@@ -653,7 +1151,7 @@ interface ViewFetchParams {
  * Configure a **live view** over a base list: filter/sort/search in JS when data is complete, or compile the same spec to remote params when not.
  * `baseQueryKey` identifies the underlying id list in the graph; the hook may create additional keys for remote result sets.
  */
-interface UseEntityViewOptions<TEntity extends Record<string, unknown>> {
+interface UseEntityViewOptions<TEntity extends object> {
     type: EntityType;
     baseQueryKey: unknown[];
     view: ViewDescriptor;
@@ -661,7 +1159,7 @@ interface UseEntityViewOptions<TEntity extends Record<string, unknown>> {
     remoteFetch?: (params: ViewFetchParams) => Promise<ListResponse<TEntity>>;
     normalize?: (raw: TEntity) => {
         id: EntityId;
-        data: Record<string, unknown>;
+        data: TEntity;
     };
     remoteDebounce?: number;
     staleTime?: number;
@@ -683,7 +1181,14 @@ interface UseEntityViewResult<TEntity> {
     isFetching: boolean;
     isRemoteFetching: boolean;
     isShowingLocalPending: boolean;
+    /**
+     * Last error message from the remote fetcher (or the cached base
+     * list state). `null` when the latest attempt succeeded or no
+     * attempt has been made.
+     */
     error: string | null;
+    /** Convenience for `error !== null`. TanStack-Query-style. */
+    isError: boolean;
     hasNextPage: boolean;
     fetchNextPage: () => void;
     isLocallyComplete: boolean;
@@ -714,7 +1219,13 @@ interface UseEntityViewResult<TEntity> {
  * });
  * ```
  */
-declare function useEntityView<TEntity extends Record<string, unknown>>(opts: UseEntityViewOptions<TEntity>): UseEntityViewResult<TEntity>;
+/**
+ * @deprecated Use `useEntityQuery` from `"@prometheus-ags/prometheus-entity-management"` instead.
+ * Register a transport: `registerEntityTransport("Foo", makeRestTransport({ supabase, table: "foo" }))`
+ * Then consume: `const { items, setFilter, setSort } = useEntityQuery<Foo>("Foo", { view })`
+ * `useEntityView` will be removed in a future major version.
+ */
+declare function useEntityView<TEntity extends object>(opts: UseEntityViewOptions<TEntity>): UseEntityViewResult<TEntity>;
 
 /** UI mode for a single CRUD surface: drives which panels/forms are active without scattering boolean flags. */
 type CRUDMode = "list" | "detail" | "edit" | "create";
@@ -722,7 +1233,7 @@ type CRUDMode = "list" | "detail" | "edit" | "create";
  * Wire one entity type into list+detail+forms: remote list via `useEntityView`, optional detail fetch, and create/update/delete callbacks.
  * Mutations call `cascadeInvalidation` on success so related lists/entities refresh per registered schemas.
  */
-interface CRUDOptions<TEntity extends Record<string, unknown>> {
+interface CRUDOptions<TEntity extends object> {
     type: EntityType;
     listQueryKey: unknown[];
     listFetch: (params: ViewFetchParams) => Promise<ListResponse<TEntity>>;
@@ -744,9 +1255,9 @@ interface CRUDOptions<TEntity extends Record<string, unknown>> {
     clearSelectionAfterDelete?: boolean;
 }
 /** Public field input for CRUD setters: supports classic `keyof T` calls and dotted nested paths for JSON-backed forms. */
-type EntityFieldPath<TEntity extends Record<string, unknown>> = keyof TEntity | string;
+type EntityFieldPath<TEntity extends object> = keyof TEntity | string;
 /** Tracks which fields diverge from loaded detail — edit buffer stays in React state so other views keep showing canonical graph data until save. */
-interface DirtyFields<TEntity extends Record<string, unknown>> {
+interface DirtyFields<TEntity extends object> {
     changed: ReadonlySet<EntityFieldPath<TEntity>>;
     isDirty: boolean;
 }
@@ -754,7 +1265,7 @@ interface DirtyFields<TEntity extends Record<string, unknown>> {
  * Everything a CRUD screen needs: composed `list` view, selection, detail subscription, relation joins, edit/create buffers, and mutating actions.
  * `applyOptimistic` is the escape hatch to mirror the buffer into `patches` for instant sliders/toggles without committing `save` yet.
  */
-interface CRUDState<TEntity extends Record<string, unknown>> {
+interface CRUDState<TEntity extends object> {
     mode: CRUDMode;
     setMode: (mode: CRUDMode) => void;
     list: UseEntityViewResult<TEntity>;
@@ -797,7 +1308,7 @@ interface CRUDState<TEntity extends Record<string, unknown>> {
  * @param opts - `CRUDOptions` for type, list key/fetch, normalization, lifecycle callbacks
  * @returns `CRUDState` with list/detail/edit/create controls
  */
-declare function useEntityCRUD<TEntity extends Record<string, unknown>>(opts: CRUDOptions<TEntity>): CRUDState<TEntity>;
+declare function useEntityCRUD<TEntity extends object>(opts: CRUDOptions<TEntity>): CRUDState<TEntity>;
 
 type FieldType = "text" | "textarea" | "number" | "email" | "url" | "date" | "boolean" | "enum" | "json" | "markdown" | "custom";
 interface FieldDescriptor<TEntity> {
@@ -826,7 +1337,7 @@ declare function Sheet({ open, onClose, title, subtitle, children, footer, width
     footer?: React$1.ReactNode;
     width?: string;
 }): react_jsx_runtime.JSX.Element;
-declare function EntityDetailSheet<TEntity extends Record<string, unknown>>({ crud, fields, title, description, children, showEditButton, showDeleteButton, deleteConfirmMessage }: {
+declare function EntityDetailSheet<TEntity extends object>({ crud, fields, title, description, children, showEditButton, showDeleteButton, deleteConfirmMessage }: {
     crud: CRUDState<TEntity>;
     fields: FieldDescriptor<TEntity>[];
     title?: string | ((e: TEntity) => string);
@@ -836,7 +1347,7 @@ declare function EntityDetailSheet<TEntity extends Record<string, unknown>>({ cr
     showDeleteButton?: boolean;
     deleteConfirmMessage?: string;
 }): react_jsx_runtime.JSX.Element;
-declare function EntityFormSheet<TEntity extends Record<string, unknown>>({ crud, fields, createTitle, editTitle }: {
+declare function EntityFormSheet<TEntity extends object>({ crud, fields, createTitle, editTitle }: {
     crud: CRUDState<TEntity>;
     fields: FieldDescriptor<TEntity>[];
     createTitle?: string;
@@ -849,11 +1360,12 @@ interface JsonSchemaObject {
     description?: string;
     type?: string | string[];
     format?: string;
-    enum?: unknown[];
+    enum?: readonly unknown[];
     default?: unknown;
     properties?: Record<string, JsonSchemaObject>;
     items?: JsonSchemaObject;
     required?: string[];
+    additionalProperties?: boolean | JsonSchemaObject;
     ["x-a2ui-component"]?: string;
     ["x-display-order"]?: number;
     ["x-field-type"]?: string;
@@ -872,7 +1384,7 @@ interface GetEntityJsonSchemaOptions {
     schemaId?: string;
     field?: string;
 }
-interface SchemaFieldDescriptor<TEntity extends Record<string, unknown> = Record<string, unknown>> extends FieldDescriptor<TEntity> {
+interface SchemaFieldDescriptor<TEntity extends object = Record<string, unknown>> extends FieldDescriptor<TEntity> {
     schemaPath: string;
     schema: JsonSchemaObject;
     componentHint?: string;
@@ -890,11 +1402,11 @@ interface GraphSnapshotWithSchemasOptions {
 declare function registerEntityJsonSchema(config: EntityJsonSchemaConfig): void;
 declare function registerRuntimeSchema(config: EntityJsonSchemaConfig): void;
 declare function getEntityJsonSchema(opts: GetEntityJsonSchemaOptions): EntityJsonSchemaConfig | null;
-declare function useSchemaEntityFields<TEntity extends Record<string, unknown> = Record<string, unknown>>(opts: GetEntityJsonSchemaOptions & {
+declare function useSchemaEntityFields<TEntity extends object = Record<string, unknown>>(opts: GetEntityJsonSchemaOptions & {
     schema?: JsonSchemaObject;
     rootField?: string;
 }): SchemaFieldDescriptor<TEntity>[];
-declare function buildEntityFieldsFromSchema<TEntity extends Record<string, unknown> = Record<string, unknown>>(opts: BuildEntityFieldsFromSchemaOptions): SchemaFieldDescriptor<TEntity>[];
+declare function buildEntityFieldsFromSchema<TEntity extends object = Record<string, unknown>>(opts: BuildEntityFieldsFromSchemaOptions): SchemaFieldDescriptor<TEntity>[];
 declare function exportGraphSnapshotWithSchemas(opts: GraphSnapshotWithSchemasOptions): string;
 declare function renderMarkdownToHtml(value: string): string;
 declare function MarkdownFieldRenderer({ value, className }: {
@@ -966,6 +1478,26 @@ interface HydrateGraphFromStorageOptions {
     storage: GraphPersistenceAdapter;
     key: string;
 }
+/**
+ * Retry-with-backoff policy for replaying pending offline actions.
+ *
+ * The replay loop tracks per-action attempt counts. After `maxAttempts`
+ * failed attempts the action is considered "poisoned" — it is removed from
+ * the in-memory pending queue (so it won't block other actions) and the
+ * optional `poisonHandler` is invoked. Consumers typically log the action,
+ * surface a UI prompt, or persist it to a dead-letter store.
+ *
+ * Defaults: 5 attempts, starting at 500ms, doubling up to 30s, with
+ * "equal" jitter (random in `[delay/2, delay]`).
+ */
+interface ReplayRetryPolicy {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffFactor?: number;
+    jitter?: "full" | "equal" | "none";
+    poisonHandler?: (action: GraphActionRecord, error: unknown) => void | Promise<void>;
+}
 interface StartLocalFirstGraphOptions {
     storage: GraphPersistenceAdapter;
     key?: string;
@@ -975,6 +1507,8 @@ interface StartLocalFirstGraphOptions {
         subscribe: (listener: (online: boolean) => void) => () => void;
     };
     persistDebounceMs?: number;
+    /** Retry-with-backoff policy for offline action replay. */
+    retryPolicy?: ReplayRetryPolicy;
 }
 interface LocalFirstGraphRuntime {
     ready: Promise<void>;
@@ -1008,6 +1542,26 @@ declare function hydrateGraphFromStorage(opts: HydrateGraphFromStorageOptions):
     error?: undefined;
 }>;
 declare function startLocalFirstGraph(opts: StartLocalFirstGraphOptions): LocalFirstGraphRuntime;
+interface ResolvedRetryPolicy {
+    maxAttempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffFactor: number;
+    jitter: "full" | "equal" | "none";
+    poisonHandler?: (action: GraphActionRecord, error: unknown) => void | Promise<void>;
+}
+/**
+ * Attempt to replay an action up to `maxAttempts` times. On exhaustion the
+ * action goes to "poison" — the optional handler is invoked and the function
+ * resolves. Exposed for unit testing.
+ */
+declare function replayActionWithRetry(action: GraphActionRecord, policy: ResolvedRetryPolicy): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    poisoned: true;
+    error: unknown;
+}>;
 
 /**
  * Debug-time snapshot of entity graph health: counts, list queries, patches, staleness,
@@ -1071,7 +1625,7 @@ interface UseEntityResult<T> {
  * });
  * ```
  */
-declare function useEntity<TRaw, TEntity extends Record<string, unknown>>(opts: EntityQueryOptions<TRaw, TEntity>): UseEntityResult<TEntity>;
+declare function useEntity<TRaw, TEntity extends object>(opts: EntityQueryOptions<TRaw, TEntity>): UseEntityResult<TEntity>;
 /**
  * Resolved rows for a list query: **`items` joins `ids` to the graph** at render time so shared entities update everywhere.
  */
@@ -1081,7 +1635,14 @@ interface UseEntityListResult<TEntity> {
     isLoading: boolean;
     isFetching: boolean;
     isFetchingMore: boolean;
+    /**
+     * Last error message from the underlying fetcher, or `null` when
+     * the latest attempt succeeded / no attempt has been made.
+     * Combined with `isError` for TanStack-Query-style ergonomics.
+     */
     error: string | null;
+    /** Convenience for `error !== null`. TanStack-Query-style. */
+    isError: boolean;
     hasNextPage: boolean;
     hasPrevPage: boolean;
     total: number | null;
@@ -1107,12 +1668,18 @@ interface UseEntityListResult<TEntity> {
  * });
  * ```
  */
-declare function useEntityList<TRaw, TEntity extends Record<string, unknown>>(opts: ListQueryOptions<TRaw, TEntity>): UseEntityListResult<TEntity>;
+/**
+ * @deprecated Use `useEntities` from `"@prometheus-ags/prometheus-entity-management"` instead.
+ * Register a transport: `registerEntityTransport("Foo", makeRestTransport({ supabase, table: "foo" }))`
+ * Then consume: `const { items } = useEntities<Foo>("Foo")`.
+ * `useEntityList` will be removed in a future major version.
+ */
+declare function useEntityList<TRaw, TEntity extends object>(opts: ListQueryOptions<TRaw, TEntity>): UseEntityListResult<TEntity>;
 /**
  * Options for graph-aware mutations: API call + optional normalization into `entities`, optimistic patches, and targeted invalidation.
  * Prefer `invalidateLists` prefixes / `invalidateEntities` over ad-hoc store calls so list UIs stay coherent.
  */
-interface MutationOptions<TInput, TRaw, TEntity extends Record<string, unknown>> {
+interface MutationOptions<TInput, TRaw, TEntity extends object> {
     type: EntityType;
     mutate: (input: TInput) => Promise<TRaw>;
     normalize?: (raw: TRaw, input: TInput) => {
@@ -1156,7 +1723,7 @@ interface UseMutationResult<TInput, TRaw> {
  * });
  * ```
  */
-declare function useEntityMutation<TInput, TRaw, TEntity extends Record<string, unknown>>(opts: MutationOptions<TInput, TRaw, TEntity>): UseMutationResult<TInput, TRaw>;
+declare function useEntityMutation<TInput, TRaw, TEntity extends object>(opts: MutationOptions<TInput, TRaw, TEntity>): UseMutationResult<TInput, TRaw>;
 /**
  * Read/write **UI-only** fields for one entity (`patches` layer) so selection, hover, or transient state is visible in every view that reads that id.
  * Does not replace `useEntityCRUD`’s edit buffer for form drafts — patches are for shared, non-persisted overlays.
@@ -1165,7 +1732,7 @@ declare function useEntityMutation<TInput, TRaw, TEntity extends Record<string,
  * @param id - Entity id (no-ops when null/undefined)
  * @returns Current patch slice and helpers `augment` / `unaugment` / `clear`
  */
-declare function useEntityAugment<TEntity extends Record<string, unknown>>(type: EntityType, id: EntityId | null | undefined): {
+declare function useEntityAugment<TEntity extends object>(type: EntityType, id: EntityId | null | undefined): {
     patch: Partial<TEntity> | null;
     augment: (fields: Partial<TEntity>) => void;
     unaugment: (keys: (keyof TEntity)[]) => void;
@@ -1181,7 +1748,7 @@ declare function useEntityAugment<TEntity extends Record<string, unknown>>(type:
  * @throws Promise while loading (caught by the nearest Suspense boundary)
  * @throws Error if the fetch fails with no data, if `id` is missing when required, or if the entity never resolves
  */
-declare function useSuspenseEntity<TRaw, TEntity extends Record<string, unknown>>(opts: EntityQueryOptions<TRaw, TEntity>): {
+declare function useSuspenseEntity<TRaw, TEntity extends object>(opts: EntityQueryOptions<TRaw, TEntity>): {
     data: TEntity;
     isFetching: boolean;
     isStale: boolean;
@@ -1196,7 +1763,7 @@ declare function useSuspenseEntity<TRaw, TEntity extends Record<string, unknown>
  * @throws Promise while initially loading (caught by the nearest Suspense boundary)
  * @throws Error if the fetch fails while the list is still empty
  */
-declare function useSuspenseEntityList<TRaw, TEntity extends Record<string, unknown>>(opts: ListQueryOptions<TRaw, TEntity>): Omit<UseEntityListResult<TEntity>, "isLoading">;
+declare function useSuspenseEntityList<TRaw, TEntity extends object>(opts: ListQueryOptions<TRaw, TEntity>): Omit<UseEntityListResult<TEntity>, "isLoading">;
 
 /**
  * Evaluate `FilterSpec` against one in-memory entity — mirrors remote semantics as closely as plain JS allows.
@@ -1413,14 +1980,14 @@ declare function createSupabaseRealtimeAdapter(client: SupabaseClient$1, opts?:
 interface ConvexClient {
     onUpdate<T>(query: unknown, args: Record<string, unknown>, handler: (result: T) => void): UnsubscribeFn$1;
 }
-interface ConvexChannelConfig<T extends Record<string, unknown>> {
+interface ConvexChannelConfig<T extends object> {
     type: string;
     query: unknown;
     args?: Record<string, unknown>;
     extractId?: (record: T) => string;
     normalize?: (record: T) => Record<string, unknown>;
 }
-declare function createConvexAdapter<T extends Record<string, unknown>>(opts: {
+declare function createConvexAdapter<T extends object>(opts: {
     client: ConvexClient;
     channels: ConvexChannelConfig<T>[];
 }): RealtimeAdapter;
@@ -1436,7 +2003,7 @@ interface GQLWsClient {
         complete: () => void;
     }): UnsubscribeFn$1;
 }
-interface GQLSubscriptionConfig<T extends Record<string, unknown>> {
+interface GQLSubscriptionConfig<T extends object> {
     type: string;
     document: string;
     variables?: Record<string, unknown>;
@@ -1447,7 +2014,7 @@ interface GQLPayload {
     node?: Record<string, unknown>;
     id?: string;
 }
-declare function createGraphQLSubscriptionAdapter<T extends Record<string, unknown>>(opts: {
+declare function createGraphQLSubscriptionAdapter<T extends object>(opts: {
     client: GQLWsClient;
     subscriptions: GQLSubscriptionConfig<T>[];
     extractId?: (node: Record<string, unknown>, type: string) => string;
@@ -1457,7 +2024,7 @@ declare function createGraphQLSubscriptionAdapter<T extends Record<string, unkno
 /**
  * Options for {@link createPrismaEntityConfig}: one REST-backed resource aligned with Prisma-style `where` / `orderBy` / `include` payloads.
  */
-interface PrismaEntityConfigOptions<TEntity extends Record<string, unknown>> {
+interface PrismaEntityConfigOptions<TEntity extends object> {
     /** Graph entity type key (e.g. `"Task"`). */
     type: string;
     /** Base REST URL for the collection (list) and detail as `${endpoint}/:id`. */
@@ -1490,7 +2057,7 @@ declare function prismaRelationsToSchema(type: string, relations: PrismaEntityCo
  * - {@link PrismaEntityConfigOptions.endpoint `endpoint`} — GET list; GET `${endpoint}/:id` for detail.
  * - List/CRUD fetchers send `where` and `orderBy` as JSON query strings unless you override via {@link ListFetchParams.params}.
  */
-declare function createPrismaEntityConfig<TEntity extends Record<string, unknown>>(config: PrismaEntityConfigOptions<TEntity>): {
+declare function createPrismaEntityConfig<TEntity extends object>(config: PrismaEntityConfigOptions<TEntity>): {
     /**
      * Builds {@link EntityQueryOptions} for {@link useEntity} (GET `${endpoint}/:id`).
      */
@@ -1516,14 +2083,14 @@ declare function createPrismaEntityConfig<TEntity extends Record<string, unknown
     schemas: () => EntitySchema[];
 };
 
-interface PGlite {
+interface PGlite$1 {
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
         rows: T[];
     }>;
-    exec(sql: string): Promise<void>;
+    exec(sql: string): Promise<unknown>;
     listen(channel: string, handler: (payload: string) => void): Promise<() => void>;
 }
-interface ShapeMessage<T = Record<string, unknown>> {
+interface ShapeMessage$1<T = Record<string, unknown>> {
     headers: {
         operation: "insert" | "update" | "delete";
     };
@@ -1531,21 +2098,21 @@ interface ShapeMessage<T = Record<string, unknown>> {
     value: T;
     key: string;
 }
-interface ShapeStream<T = Record<string, unknown>> {
-    subscribe(onMsg: (msgs: ShapeMessage<T>[]) => void, onErr?: (e: Error) => void): () => void;
+interface ShapeStream$1<T = Record<string, unknown>> {
+    subscribe(onMsg: (msgs: ShapeMessage$1<T>[]) => void, onErr?: (e: Error) => void): () => void;
     isUpToDate: boolean;
     lastOffset: string;
 }
-interface ElectricTableConfig<T extends Record<string, unknown>> {
+interface ElectricTableConfig<T extends object> {
     type: EntityType;
     table: string;
     where?: string;
     idColumn?: string;
     normalize?: (row: T) => Record<string, unknown>;
-    shapeStream: ShapeStream<T>;
+    shapeStream: ShapeStream$1<T>;
 }
 interface ElectricAdapterOptions {
-    pglite: PGlite;
+    pglite: PGlite$1;
     tables: ElectricTableConfig<Record<string, unknown>>[];
     onSynced?: () => void;
 }
@@ -1556,7 +2123,7 @@ interface UseLocalFirstResult {
     execute: (sql: string, params?: unknown[]) => Promise<void>;
 }
 declare function useLocalFirst(adapter: SyncAdapter): UseLocalFirstResult;
-declare function usePGliteQuery<T extends Record<string, unknown>>(opts: {
+declare function usePGliteQuery<T extends object>(opts: {
     adapter: SyncAdapter;
     type: EntityType;
     sql: string;
@@ -1569,6 +2136,280 @@ declare function usePGliteQuery<T extends Record<string, unknown>>(opts: {
     error: string | null;
 };
 
+/**
+ * adapters/electricsql-tenant.ts
+ *
+ * Tenant-scoped Electric adapter — the safety primitive that enforces
+ * **RULE 5 — Shape predicates ⊆ RLS** (see hotseaters constraints).
+ *
+ * PGlite has no row-level security. The only way to guarantee a client
+ * never sees cross-tenant data through Electric is to refuse to attach
+ * any shape that lacks a tenant predicate. This wrapper does exactly that:
+ *
+ *   - Validates the tenant claim (currently `{ companyId }`) is a UUID.
+ *   - Refuses to attach a shape whose `tenantColumn` is `undefined`. We
+ *     accept explicit `null` for the company root itself (filtered by `id`).
+ *   - Builds the `where` clause from `tenantColumn` and the validated
+ *     companyId so individual shape factories cannot drift from RLS.
+ *   - Delegates to the existing `createElectricAdapter` for the actual
+ *     sync wiring.
+ *
+ * This also fulfils Change 13 item 11 (auth-claim-aware shape registration):
+ * the `tenantClaim` is the typed seam where authn meets shape registration.
+ *
+ * Self-hosted Supabase only. Local stack and `https://electricsql.prometheusags.ai`
+ * are the only acceptable Electric endpoints — this module does not
+ * hard-code either; it only governs the predicate.
+ */
+
+interface PGlite {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    exec(sql: string): Promise<unknown>;
+    listen(channel: string, handler: (payload: string) => void): Promise<() => void>;
+}
+interface ShapeMessage<T = Record<string, unknown>> {
+    headers: {
+        operation: "insert" | "update" | "delete";
+    };
+    offset: string;
+    value: T;
+    key: string;
+}
+interface ShapeStream<T = Record<string, unknown>> {
+    subscribe(onMsg: (msgs: ShapeMessage<T>[]) => void, onErr?: (e: Error) => void): () => void;
+    isUpToDate: boolean;
+    lastOffset: string;
+}
+/** Auth claim required to register tenant-scoped shapes. */
+interface TenantClaim {
+    companyId: string;
+}
+interface TenantScopedTableConfig<T extends object = Record<string, unknown>> {
+    type: EntityType;
+    table: string;
+    /**
+     * Column used for tenant filtering.
+     *
+     * - A string (`"company_id"`) yields `WHERE company_id = '<companyId>'`.
+     * - Explicit `null` means the table IS the tenant root and is filtered by
+     *   `id = '<companyId>'`. Only the `company` table qualifies.
+     * - `undefined` is **rejected** — this is the safety gate.
+     */
+    tenantColumn: string | null;
+    primaryKey?: string[];
+    /**
+     * Factory invoked with the constructed `where` clause and the tenant claim.
+     * Consumers wire their preferred Electric `ShapeStream` builder here. The
+     * factory must use the supplied `where` verbatim (no widening).
+     */
+    shapeStreamFactory: (params: {
+        table: string;
+        where: string;
+        tenantClaim: TenantClaim;
+    }) => ShapeStream<T>;
+    normalize?: (row: T) => Record<string, unknown>;
+}
+interface TenantScopedAdapterOptions {
+    pglite: PGlite;
+    tenantClaim: TenantClaim;
+    tables: TenantScopedTableConfig[];
+    onSynced?: () => void;
+}
+/**
+ * Build the `where` clause for a single shape. Exposed for tests.
+ *
+ * - `tenantColumn === null` → `id = '<companyId>'` (company-root case)
+ * - `tenantColumn === string` → `<tenantColumn> = '<companyId>'`
+ *
+ * Throws if `tenantColumn` is `undefined` or `companyId` is not a UUID.
+ */
+declare function buildTenantWhere(tenantColumn: string | null | undefined, companyId: string, tableLabel: string): string;
+/**
+ * Build a tenant-scoped {@link SyncAdapter}.
+ *
+ * For each table in `tables`:
+ *   1. Validates `tenantColumn` is defined (string or explicit null).
+ *   2. Validates `companyId` is a UUID.
+ *   3. Builds the predicate and calls `shapeStreamFactory(...)` to get the
+ *      actual `ShapeStream`.
+ *   4. Hands the resulting list off to `createElectricAdapter` for wiring.
+ *
+ * @throws if any table lacks `tenantColumn`, or the company id is not a UUID.
+ */
+declare function createTenantScopedElectricAdapter(opts: TenantScopedAdapterOptions): SyncAdapter;
+
+/**
+ * adapters/pglite-persistence.ts
+ *
+ * PGlite-backed implementation of {@link GraphPersistenceAdapter}.
+ *
+ * Stores the local-first runtime's graph snapshot inside a PGlite table
+ * (`_graph_snapshot` by default) instead of `localStorage`/`IndexedDB`.
+ *
+ * Why this exists:
+ *   - The app already has a PGlite handle for ElectricSQL sync.
+ *   - Putting the graph snapshot alongside synced data means one storage
+ *     surface to back up, clear, and reason about.
+ *   - Works in Tauri WebView + Node (PGlite is a WASM Postgres) without
+ *     pulling in browser-only storage.
+ *
+ * Contract:
+ *   - `get(key)`    -> returns the stored string or null
+ *   - `set(key, v)` -> upserts (insert-or-replace), stamping `updated_at`
+ *   - `remove(key)` -> deletes the row (no-op if absent)
+ *
+ * The function lazily ensures the storage table exists on first call.
+ * That `CREATE TABLE IF NOT EXISTS` is idempotent so it's safe to retry.
+ *
+ * Self-hosted Supabase only. HotSeatersMVP is the bible. This module does
+ * not import `@electric-sql/pglite` — consumers pass a PGlite-shaped handle.
+ */
+
+interface PGlitePersistenceClient {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    exec(sql: string): Promise<unknown>;
+}
+interface CreatePGlitePersistenceAdapterOptions {
+    /** Name of the snapshot table. Defaults to `_graph_snapshot`. */
+    tableName?: string;
+}
+/**
+ * Returns a {@link GraphPersistenceAdapter} that reads/writes the graph
+ * snapshot through a PGlite-shaped client.
+ *
+ * @example
+ * ```ts
+ * import { PGlite } from "@electric-sql/pglite";
+ * import { startLocalFirstGraph, createPGlitePersistenceAdapter } from "@prometheus-ags/prometheus-entity-management";
+ *
+ * const pglite = await PGlite.create("idb://hotseaters");
+ * const storage = await createPGlitePersistenceAdapter(pglite);
+ * const runtime = startLocalFirstGraph({ storage, key: "hotseaters:graph" });
+ * ```
+ */
+declare function createPGlitePersistenceAdapter(pglite: PGlitePersistenceClient, options?: CreatePGlitePersistenceAdapterOptions): Promise<GraphPersistenceAdapter>;
+
+/**
+ * schema-from-sql.ts
+ *
+ * Generates a JSON Schema (and registers it via `registerEntityJsonSchema`)
+ * directly from a Postgres `CREATE TABLE` statement. Lets a consumer keep
+ * `latest-data/supabase/migrations/*.sql` as the single source of truth for
+ * column shapes — no hand-maintained TypeScript schema duplicates.
+ *
+ * Deliberately regex-based: a real SQL parser is overkill for the slice of
+ * DDL we care about, and would add a non-trivial runtime dep.
+ *
+ * Type mapping
+ * ------------
+ *   UUID, TEXT, VARCHAR(*)             -> { type: "string" }
+ *   INTEGER, INT, BIGINT, SMALLINT     -> { type: "integer" }
+ *   NUMERIC(*), DECIMAL(*)             -> { type: "number" }
+ *   BOOLEAN, BOOL                      -> { type: "boolean" }
+ *   TIMESTAMPTZ, TIMESTAMP             -> { type: "string", format: "date-time" }
+ *   DATE                               -> { type: "string", format: "date" }
+ *   JSONB, JSON                        -> { type: "object" }
+ *   TEXT[]                             -> { type: "array", items: { type: "string" } }
+ *   anything else                      -> { type: "string" } + "x-warning"
+ *
+ * `required` is populated from `NOT NULL` columns that lack a `DEFAULT`.
+ * Callers can pass `overrides` to deep-merge a partial config (typically to
+ * narrow a JSONB column to an array, or to add `enum`/`format` hints).
+ */
+
+interface RegisterEntityFromSqlOptions {
+    entityType: string;
+    /** A single `CREATE TABLE` statement (extra DDL around it is ignored). */
+    createTableSql: string;
+    /** Optional deep-merge overrides (overrides win). */
+    overrides?: Partial<EntityJsonSchemaConfig>;
+}
+interface ParsedColumn {
+    name: string;
+    sqlType: string;
+    notNull: boolean;
+    hasDefault: boolean;
+}
+interface ParsedTable {
+    tableName: string;
+    columns: ParsedColumn[];
+}
+/**
+ * Parse a `CREATE TABLE` block. Exposed for tests and for callers who need
+ * the intermediate representation.
+ */
+declare function parseCreateTable(sql: string): ParsedTable;
+/**
+ * Map a normalized (uppercased, whitespace-stripped) SQL type to a JSON
+ * schema fragment.
+ *
+ * Returns `{ schema, warning }` so the caller can surface "unmapped type"
+ * notes via `x-warning` on the property.
+ */
+declare function sqlTypeToJsonSchema(sqlType: string): {
+    schema: JsonSchemaObject;
+    warning?: string;
+};
+/**
+ * Build (and register) an `EntityJsonSchemaConfig` from a CREATE TABLE
+ * statement. Returns the registered config so callers can introspect it.
+ */
+declare function registerEntityFromSql(opts: RegisterEntityFromSqlOptions): EntityJsonSchemaConfig;
+
+/**
+ * table/use-entity-list-as-table.ts
+ *
+ * Adapter hook that shapes a `useEntityList` result for TanStack Table (or
+ * any data-grid that wants a plain `data` array + `rowCount`).
+ *
+ * It deliberately does NOT bring `@tanstack/react-table` as a dependency.
+ * Consumers wire the table; this helper only stabilizes the array reference
+ * so the table doesn't re-render unnecessarily, and exposes the same
+ * loading/error surface as `useEntityList`.
+ *
+ * @example
+ * ```tsx
+ * const tableProps = useEntityListAsTable({
+ *   type: "Client",
+ *   fetch: (params) => api.listClients(params),
+ *   normalize: (raw) => ({ id: raw.id, data: raw }),
+ * });
+ *
+ * const table = useReactTable({
+ *   data: tableProps.data,
+ *   rowCount: tableProps.rowCount,
+ *   columns,
+ *   getCoreRowModel: getCoreRowModel(),
+ * });
+ * ```
+ */
+
+interface UseEntityListAsTableOptions<TRaw, TEntity extends object> extends Omit<ListQueryOptions<TRaw, TEntity>, "type" | "queryKey"> {
+    type: EntityType;
+    /** Optional override for the cache key. Defaults to `["entity-list-as-table", type]`. */
+    queryKey?: unknown[];
+}
+interface UseEntityListAsTableResult<TEntity> {
+    data: TEntity[];
+    rowCount: number;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+/**
+ * Wraps `useEntityList` for table consumers.
+ *
+ * Returns a referentially-stable `data` array (replaced only when items
+ * actually change). TanStack Table treats `data` by identity for memoization,
+ * so this is essential to avoid blowing away row state on every render.
+ */
+declare function useEntityListAsTable<TRaw, TEntity extends object>(opts: UseEntityListAsTableOptions<TRaw, TEntity>): UseEntityListAsTableResult<TEntity>;
+
 interface GQLClientConfig {
     url: string;
     headers?: () => Record<string, string>;
@@ -1587,7 +2428,7 @@ interface GQLResponse<T> {
     data: T | null;
     errors?: GQLError[];
 }
-interface EntityDescriptor<TNode, TEntity extends Record<string, unknown>> {
+interface EntityDescriptor<TNode, TEntity extends object> {
     type: EntityType;
     path: string;
     extractId?: (node: TNode) => EntityId;
@@ -1602,13 +2443,13 @@ declare function normalizeGQLResponse<T>(data: T, descriptors: EntityDescriptor<
 declare class GQLClient {
     private cfg;
     constructor(cfg: GQLClientConfig);
-    query<TData, TEntity extends Record<string, unknown>>(opts: {
+    query<TData, TEntity extends object>(opts: {
         document: string;
         variables?: Record<string, unknown>;
         descriptors: EntityDescriptor<unknown, TEntity>[];
         cacheKey?: string;
     }): Promise<GQLResponse<TData>>;
-    mutate<TData, TEntity extends Record<string, unknown>>(opts: {
+    mutate<TData, TEntity extends object>(opts: {
         document: string;
         variables?: Record<string, unknown>;
         descriptors?: EntityDescriptor<unknown, TEntity>[];
@@ -1627,7 +2468,7 @@ declare class GQLClient {
 }
 declare function createGQLClient(cfg: GQLClientConfig): GQLClient;
 
-interface GQLEntityOptions<TData, TEntity extends Record<string, unknown>> {
+interface GQLEntityOptions<TData, TEntity extends object> {
     client: GQLClient;
     document: string;
     variables?: Record<string, unknown>;
@@ -1640,7 +2481,7 @@ interface GQLEntityOptions<TData, TEntity extends Record<string, unknown>> {
     onSuccess?: (data: TData) => void;
     onError?: (err: Error) => void;
 }
-declare function useGQLEntity<TData, TEntity extends Record<string, unknown>>(opts: GQLEntityOptions<TData, TEntity>): {
+declare function useGQLEntity<TData, TEntity extends object>(opts: GQLEntityOptions<TData, TEntity>): {
     data: TEntity | null;
     isLoading: boolean;
     isFetching: boolean;
@@ -1648,7 +2489,7 @@ declare function useGQLEntity<TData, TEntity extends Record<string, unknown>>(op
     isStale: boolean;
     refetch: () => void;
 };
-interface GQLListOptions<TData, TEntity extends Record<string, unknown>> {
+interface GQLListOptions<TData, TEntity extends object> {
     client: GQLClient;
     document: string;
     variables?: Record<string, unknown>;
@@ -1668,7 +2509,7 @@ interface GQLListOptions<TData, TEntity extends Record<string, unknown>> {
     staleTime?: number;
     enabled?: boolean;
 }
-declare function useGQLList<TData, TEntity extends Record<string, unknown>>(opts: GQLListOptions<TData, TEntity>): {
+declare function useGQLList<TData, TEntity extends object>(opts: GQLListOptions<TData, TEntity>): {
     items: TEntity[];
     ids: string[];
     isLoading: boolean;
@@ -1681,7 +2522,7 @@ declare function useGQLList<TData, TEntity extends Record<string, unknown>>(opts
     fetchNextPage: () => void;
     refetch: () => void;
 };
-declare function useGQLMutation<TData, TEntity extends Record<string, unknown>>(opts: {
+declare function useGQLMutation<TData, TEntity extends object>(opts: {
     client: GQLClient;
     document: string;
     type: string;
@@ -1722,7 +2563,7 @@ declare function InlineCellEditor$1({ initialValue, onCommit, onCancel, classNam
     onCancel: () => void;
     className?: string;
 }): react_jsx_runtime.JSX.Element;
-interface EntityTableProps<T extends Record<string, unknown>> {
+interface EntityTableProps<T extends object> {
     viewResult: UseEntityViewResult<T>;
     columns: ColumnDef$1<T>[];
     getRowId?: (row: T) => string;
@@ -1739,7 +2580,7 @@ interface EntityTableProps<T extends Record<string, unknown>> {
     emptyState?: React$1.ReactNode;
     className?: string;
 }
-declare function EntityTable<T extends Record<string, unknown>>({ viewResult, columns, getRowId, selectedId, onRowClick, onCellEdit, onBulkAction, paginationMode, pageSize, searchPlaceholder, searchFields, toolbarChildren, showToolbar, emptyState, className }: EntityTableProps<T>): react_jsx_runtime.JSX.Element;
+declare function EntityTable<T extends object>({ viewResult, columns, getRowId, selectedId, onRowClick, onCellEdit, onBulkAction, paginationMode, pageSize, searchPlaceholder, searchFields, toolbarChildren, showToolbar, emptyState, className }: EntityTableProps<T>): react_jsx_runtime.JSX.Element;
 
 type ColumnFilterType = "text" | "number" | "date" | "dateRange" | "boolean" | "enum" | "relation" | "none";
 interface EntityColumnMeta<TEntity> {
@@ -2256,7 +3097,7 @@ interface GalleryColumns {
     xl?: number;
 }
 
-declare function useTable<TData extends Record<string, unknown>>(options: TableOptions<TData>): TableInstance<TData>;
+declare function useTable<TData extends object>(options: TableOptions<TData>): TableInstance<TData>;
 
 /**
  * table/row-models.ts
@@ -2650,7 +3491,7 @@ declare function TableStorageProvider({ adapter, realtimeMode, children, }: Tabl
 declare function useTableStorageAdapter(): TableStorageAdapter;
 declare function useTableRealtimeMode(): "auto-apply" | "notify";
 
-interface EntityListViewProps<TData extends Record<string, unknown>> {
+interface EntityListViewProps<TData extends object> {
     data?: TData[];
     viewResult?: {
         items: TData[];
@@ -2685,9 +3526,9 @@ interface EntityListViewProps<TData extends Record<string, unknown>> {
     onRefresh?: () => void;
     className?: string;
 }
-declare function EntityListView<TData extends Record<string, unknown>>(props: EntityListViewProps<TData>): react_jsx_runtime.JSX.Element;
+declare function EntityListView<TData extends object>(props: EntityListViewProps<TData>): react_jsx_runtime.JSX.Element;
 
-interface DataTableProps<TData extends Record<string, unknown>> {
+interface DataTableProps<TData extends object> {
     table: TableInstance<TData>;
     actions?: ActionDef<TData>[];
     enableInlineEdit?: boolean;
@@ -2697,9 +3538,9 @@ interface DataTableProps<TData extends Record<string, unknown>> {
     getRowId?: (row: TData) => string;
     className?: string;
 }
-declare function DataTable<TData extends Record<string, unknown>>({ table, actions, enableInlineEdit, onInlineSave, selectionStore, enableMultiSelect, getRowId, className, }: DataTableProps<TData>): react_jsx_runtime.JSX.Element;
+declare function DataTable<TData extends object>({ table, actions, enableInlineEdit, onInlineSave, selectionStore, enableMultiSelect, getRowId, className, }: DataTableProps<TData>): react_jsx_runtime.JSX.Element;
 
-interface GalleryViewProps<TData extends Record<string, unknown>> {
+interface GalleryViewProps<TData extends object> {
     rows: Row<TData>[];
     columns: ColumnDef<TData>[];
     itemDescriptor?: ItemDescriptor<TData>;
@@ -2713,9 +3554,9 @@ interface GalleryViewProps<TData extends Record<string, unknown>> {
     galleryColumns?: GalleryColumns;
     className?: string;
 }
-declare function GalleryView<TData extends Record<string, unknown>>({ rows, columns, itemDescriptor, renderCard, actions, enableInlineEdit, onInlineSave, selectionStore, enableMultiSelect, getRowId, galleryColumns, className, }: GalleryViewProps<TData>): react_jsx_runtime.JSX.Element;
+declare function GalleryView<TData extends object>({ rows, columns, itemDescriptor, renderCard, actions, enableInlineEdit, onInlineSave, selectionStore, enableMultiSelect, getRowId, galleryColumns, className, }: GalleryViewProps<TData>): react_jsx_runtime.JSX.Element;
 
-interface ListViewProps<TData extends Record<string, unknown>> {
+interface ListViewProps<TData extends object> {
     rows: Row<TData>[];
     columns: ColumnDef<TData>[];
     itemDescriptor?: ItemDescriptor<TData>;
@@ -2728,7 +3569,7 @@ interface ListViewProps<TData extends Record<string, unknown>> {
     getRowId?: (row: TData) => string;
     className?: string;
 }
-declare function ListView<TData extends Record<string, unknown>>({ rows, columns, itemDescriptor, renderItem, actions, enableInlineEdit, onInlineSave, selectionStore, enableMultiSelect, getRowId, className, }: ListViewProps<TData>): react_jsx_runtime.JSX.Element;
+declare function ListView<TData extends object>({ rows, columns, itemDescriptor, renderItem, actions, enableInlineEdit, onInlineSave, selectionStore, enableMultiSelect, getRowId, className, }: ListViewProps<TData>): react_jsx_runtime.JSX.Element;
 
 interface ViewModeSwitcherProps {
     mode: ViewMode;
@@ -2813,7 +3654,7 @@ interface InlineCellEditorProps<TData> {
     ariaLabel?: string;
 }
 declare function InlineCellEditor<TData>({ value: initialValue, columnDef, onSave, onCancel, className, inputId, ariaLabel, }: InlineCellEditorProps<TData>): react_jsx_runtime.JSX.Element;
-interface InlineItemEditorProps<TData extends Record<string, unknown>> {
+interface InlineItemEditorProps<TData extends object> {
     item: TData;
     columns: ColumnDef<TData>[];
     itemDescriptor?: ItemDescriptor<TData>;
@@ -2821,7 +3662,7 @@ interface InlineItemEditorProps<TData extends Record<string, unknown>> {
     onCancel: () => void;
     className?: string;
 }
-declare function InlineItemEditor<TData extends Record<string, unknown>>({ item, columns, itemDescriptor: _itemDescriptor, onSave, onCancel, className, }: InlineItemEditorProps<TData>): react_jsx_runtime.JSX.Element;
+declare function InlineItemEditor<TData extends object>({ item, columns, itemDescriptor: _itemDescriptor, onSave, onCancel, className, }: InlineItemEditorProps<TData>): react_jsx_runtime.JSX.Element;
 
 interface MultiSelectBarProps {
     store: StoreApi<SelectionStoreState>;
@@ -2935,4 +3776,4 @@ declare const TableHead: React$1.ForwardRefExoticComponent<React$1.ThHTMLAttribu
 declare const TableCell: React$1.ForwardRefExoticComponent<React$1.TdHTMLAttributes<HTMLTableCellElement> & React$1.RefAttributes<HTMLTableCellElement>>;
 declare const TableCaption: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLTableCaptionElement> & React$1.RefAttributes<HTMLTableCaptionElement>>;
 
-export { type AccessorFn, ActionButtonRow, type ActionDef, ActionDropdown, type ActionItem, type ActivePresets, type AdapterStatus, type AggregationFn, type BatchActionDef, type BelongsToRelation, type BuildEntityFieldsFromSchemaOptions, type CRUDMode, type CRUDOptions, type CRUDState, type CascadeContext, type Cell, type CellContext, type CellRenderer, type ChangeOperation, type ChangeSet, type ChannelConfig, type Column, type ColumnFilterType, type ColumnFiltersState, type ColumnOrderState, type ColumnPinningState, type ColumnPreset, ColumnPresetDialog, type ColumnPresetEntry, type ColumnSizingState, type ColumnVisibilityState, type CompletenessMode, DataTable, DataTableColumnHeader, DataTableFilter, DataTablePagination, DataTableToolbar, type DirtyFields, type ElectricAdapterOptions, ElectricSQLAdapter as ElectricSQLPresetAdapter, type ElectricSQLAdapterOptions as ElectricSQLPresetAdapterOptions, type ElectricTableConfig, EmptyState, type EmptyStateConfig, type EngineOptions, type EntityChange, type EntityColumnMeta, type EntityDescriptor, EntityDetailSheet, EntityFormSheet, type EntityId, type EntityJsonSchemaConfig, EntityListView, type EntityListViewProps, type EntityQueryOptions, type EntitySchema, type EntitySnapshot, type EntityState, type EntitySyncMetadata, EntityTable, type EntityType, type ExpandedState, type FieldDescriptor, type FieldType, type FilterClause, type FilterFn, type FilterGroup, type FilterOperator, type FilterPreset, FilterPresetDialog, type FilterSpec, GQLClient, type GQLClientConfig, type GQLEntityOptions, type GQLError, type GQLListOptions, type GQLResponse, type GalleryColumns, GalleryView, type GraphActionEvent, type GraphActionOptions, type GraphActionRecord$1 as GraphActionRecord, type GraphEffectEvent, type GraphEffectHandle, type GraphEffectOptions, type GraphIncludeMap, type GraphIncludeRelation, type GraphPersistenceAdapter, type GraphQueryOptions, type GraphSnapshotExportOptions, type GraphSnapshotPayload, type GraphSnapshotWithSchemasOptions, type GraphState, type GraphSyncStatus, type GraphToolContext, type GraphTransaction, type GroupingState, type HasManyRelation, type Header, type HeaderContext, type HeaderGroup, type HeaderRenderer, InlineCellEditor$1 as InlineCellEditor, InlineItemEditor, type ItemDescriptor, type ItemDescriptorBadge, type ItemDescriptorMeta, type ItemRenderContext, type JsonSchemaObject, type ListFetchParams, type ListQueryOptions, type ListResponse, type ListState, ListView, type LocalFirstGraphRuntime, type ManagerOptions, type ManyToManyRelation, MarkdownFieldEditor, MarkdownFieldRenderer, MemoryAdapter, MultiSelectBar, type PaginationState, type GraphActionRecord as PersistedGraphActionRecord, type PresetChangeEvent, type PresetChangeOperation, PresetPicker, type PresetStoreState, type UnsubscribeFn as PresetUnsubscribeFn, type PrismaEntityConfigOptions, type ColumnDef as PureColumnDef, type ColumnMeta as PureColumnMeta, InlineCellEditor as PureInlineCellEditor, type QueryKey, type RealtimeAdapter, RealtimeManager, type RelationDescriptor, type RestAdapterOptions, RestApiAdapter, type Row, type RowModel, type RowSelectionState, type SchemaFieldDescriptor, type SchemaGraphToolContext, SelectionContext, type SelectionStoreState, Sheet, type SortClause, type SortDirection, SortHeader, type SortSpec, type SortingFn, type SortingState, type StartLocalFirstGraphOptions, type SubscriptionConfig, type SupabaseAdapterOptions$1 as SupabaseAdapterOptions, SupabaseRealtimeAdapter as SupabasePresetAdapter, type SupabaseAdapterOptions as SupabasePresetAdapterOptions, type SyncAdapter, type SyncOrigin, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableInstance, type TableOptions, type TablePresetSlice, TableRow, type TableState, type TableStorageAdapter, TableStorageProvider, type TableStorageProviderProps, type UnsubscribeFn$1 as UnsubscribeFn, type Updater, type UseEntityViewOptions, type UseEntityViewResult, type UseLocalFirstResult, type UseTablePresetsOptions, type UseTablePresetsResult, type ViewDescriptor, type ViewFetchParams, type ViewMode, ViewModeSwitcher, type WebSocketAdapterOptions, type ZustandAdapterOptions, ZustandPersistAdapter, actionsColumn$1 as actionsColumn, applyView, booleanColumn$1 as booleanColumn, buildEntityFieldsFromSchema, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createConvexAdapter, createElectricAdapter, createGQLClient, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphTool, createGraphTransaction, createPresetStore, createPrismaEntityConfig, createRow, createSchemaGraphTool, createSelectionStore, createSupabaseRealtimeAdapter, createWebSocketAdapter, dateColumn$1 as dateColumn, dedupe, deleteAction, editAction, enumColumn$1 as enumColumn, executeGQL, exportGraphSnapshot, exportGraphSnapshotWithSchemas, fetchEntity, fetchList, flattenClauses, getCoreRowModel, getEntityJsonSchema, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGroupedRowModel, getPaginatedRowModel, getRealtimeManager, getSchema, getSelectedRowModel, getSortedRowModel, hasCustomPredicates, hydrateGraphFromStorage, matchesFilter, matchesSearch, normalizeGQLResponse, numberColumn$1 as numberColumn, persistGraphToStorage, prismaRelationsToSchema, actionsColumn as pureActionsColumn, booleanColumn as pureBooleanColumn, dateColumn as pureDateColumn, enumColumn as pureEnumColumn, numberColumn as pureNumberColumn, selectionColumn as pureSelectionColumn, textColumn as pureTextColumn, queryOnce, readRelations, registerEntityJsonSchema, registerRuntimeSchema, registerSchema, renderMarkdownToHtml, resetRealtimeManager, selectGraph, selectionColumn$1 as selectionColumn, serializeKey, startGarbageCollector, startLocalFirstGraph, stopGarbageCollector, textColumn$1 as textColumn, toGraphQLVariables, toPrismaInclude, toPrismaOrderBy, toPrismaWhere, toRestParams, toSQLClauses, useEntity, useEntityAugment, useEntityCRUD, useEntityList, useEntityMutation, useEntityView, useGQLEntity, useGQLList, useGQLMutation, useGQLSubscription, useGraphDevTools, useGraphStore, useGraphSyncStatus, useLocalFirst, usePGliteQuery, useSchemaEntityFields, useSelectionContext, useSelectionStore, useSuspenseEntity, useSuspenseEntityList, useTable, useTablePresets, useTableRealtimeMode, useTableStorageAdapter, viewAction };
+export { type AccessorFn, ActionButtonRow, type ActionDef, ActionDropdown, type ActionItem, type ActivePresets, type AdapterStatus, type AggregationFn, type BatchActionDef, type BelongsToRelation, type BuildEntityFieldsFromSchemaOptions, type CRUDMode, type CRUDOptions, type CRUDState, type CascadeContext, type Cell, type CellContext, type CellRenderer, type ChangeEvent, type ChangeOp, type ChangeOperation, type ChangeSet, type ChannelConfig, type Column, type ColumnFilterType, type ColumnFiltersState, type ColumnOrderState, type ColumnPinningState, type ColumnPreset, ColumnPresetDialog, type ColumnPresetEntry, type ColumnSizingState, type ColumnVisibilityState, type CompletenessMode, type CreatePGlitePersistenceAdapterOptions, DataTable, DataTableColumnHeader, DataTableFilter, DataTablePagination, DataTableToolbar, type DirtyFields, type ElectricAdapterOptions, ElectricSQLAdapter as ElectricSQLPresetAdapter, type ElectricSQLAdapterOptions as ElectricSQLPresetAdapterOptions, type ElectricTableConfig, EmptyState, type EmptyStateConfig, type EngineOptions, type EntityChange, type EntityColumnMeta, type EntityDescriptor, EntityDetailSheet, type EntityError, type EntityErrorOptions, EntityFormSheet, type EntityId, type EntityJsonSchemaConfig, EntityListView, type EntityListViewProps, type EntityQueryOptions, type EntitySchema, type EntitySnapshot, type EntityState, type EntitySyncMetadata, EntityTable, type EntityTransport, type EntityType, type ExpandedState, type FieldDescriptor, type FieldType, type FilterClause, type FilterFn, type FilterGroup, type FilterOperator, type FilterPreset, FilterPresetDialog, type FilterSpec, GQLClient, type GQLClientConfig, type GQLEntityOptions, type GQLError, type GQLListOptions, type GQLResponse, type GalleryColumns, GalleryView, type GraphActionEvent, type GraphActionOptions, type GraphActionRecord$1 as GraphActionRecord, type GraphEffectEvent, type GraphEffectHandle, type GraphEffectOptions, type GraphIncludeMap, type GraphIncludeRelation, type GraphPersistenceAdapter, type GraphQueryOptions, type GraphSnapshotExportOptions, type GraphSnapshotPayload, type GraphSnapshotWithSchemasOptions, type GraphState, type GraphSyncStatus, type GraphToolContext, type GraphTransaction, type GroupingState, type HasManyRelation, type Header, type HeaderContext, type HeaderGroup, type HeaderRenderer, InlineCellEditor$1 as InlineCellEditor, InlineItemEditor, type ItemDescriptor, type ItemDescriptorBadge, type ItemDescriptorMeta, type ItemRenderContext, type JsonSchemaObject, type ListFetchParams, type ListQuery, type ListQueryOptions, type ListResponse, type ListResult, type ListState, ListView, type LocalFirstGraphRuntime, type MakeRestTransportOptions, type ManagerOptions, type ManyToManyRelation, MarkdownFieldEditor, MarkdownFieldRenderer, MemoryAdapter, MultiSelectBar, type PGlitePersistenceClient, type PaginationState, type GraphActionRecord as PersistedGraphActionRecord, type PresetChangeEvent, type PresetChangeOperation, PresetPicker, type PresetStoreState, type UnsubscribeFn as PresetUnsubscribeFn, type PrismaEntityConfigOptions, type ColumnDef as PureColumnDef, type ColumnMeta as PureColumnMeta, InlineCellEditor as PureInlineCellEditor, type QueryKey, type RealtimeAdapter, RealtimeManager, type RegisterEntityFromSqlOptions, type RelationDescriptor, type ReplayRetryPolicy, type RestAdapterOptions, RestApiAdapter, type Row, type RowModel, type RowSelectionState, type SchemaFieldDescriptor, type SchemaGraphToolContext, SelectionContext, type SelectionStoreState, Sheet, type SortClause, type SortDirection, SortHeader, type SortSpec, type SortingFn, type SortingState, type StartLocalFirstGraphOptions, type SubscriptionConfig, type SupabaseAdapterOptions$1 as SupabaseAdapterOptions, type SupabaseLike, SupabaseRealtimeAdapter as SupabasePresetAdapter, type SupabaseAdapterOptions as SupabasePresetAdapterOptions, type SupabaseQueryBuilderLike, type SyncAdapter, type SyncOrigin, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableInstance, type TableOptions, type TablePresetSlice, TableRow, type TableState, type TableStorageAdapter, TableStorageProvider, type TableStorageProviderProps, type TenantClaim, type TenantScopedAdapterOptions, type TenantScopedTableConfig, TerminalError, TransientError, type UnsubscribeFn$1 as UnsubscribeFn, type Updater, type UseEntitiesOptions, type UseEntitiesResult, type UseEntityListAsTableOptions, type UseEntityListAsTableResult, type UseEntityQueryOptions, type UseEntityQueryResult, type UseEntityViewOptions, type UseEntityViewResult, type UseLocalFirstResult, type UseTablePresetsOptions, type UseTablePresetsResult, type ViewDescriptor, type ViewFetchParams, type ViewMode, ViewModeSwitcher, type WebSocketAdapterOptions, type ZustandAdapterOptions, ZustandPersistAdapter, __resetEntityTransports, actionsColumn$1 as actionsColumn, applyView, booleanColumn$1 as booleanColumn, buildEntityFieldsFromSchema, buildTenantWhere, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createConvexAdapter, createElectricAdapter, createGQLClient, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphTool, createGraphTransaction, createPGlitePersistenceAdapter, createPresetStore, createPrismaEntityConfig, createRow, createSchemaGraphTool, createSelectionStore, createSupabaseRealtimeAdapter, createTenantScopedElectricAdapter, createWebSocketAdapter, dateColumn$1 as dateColumn, dedupe, deleteAction, editAction, enumColumn$1 as enumColumn, executeGQL, exportGraphSnapshot, exportGraphSnapshotWithSchemas, fetchEntity, fetchList, flattenClauses, getCoreRowModel, getEntityJsonSchema, getEntityTransport, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGroupedRowModel, getPaginatedRowModel, getRealtimeManager, getRegisteredEntityTypes, getSchema, getSelectedRowModel, getSortedRowModel, hasCustomPredicates, hydrateGraphFromStorage, makeRestTransport, matchesFilter, matchesSearch, normalizeGQLResponse, numberColumn$1 as numberColumn, parseCreateTable, persistGraphToStorage, prismaRelationsToSchema, actionsColumn as pureActionsColumn, booleanColumn as pureBooleanColumn, dateColumn as pureDateColumn, enumColumn as pureEnumColumn, numberColumn as pureNumberColumn, selectionColumn as pureSelectionColumn, textColumn as pureTextColumn, queryOnce, readRelations, registerEntityFromSql, registerEntityJsonSchema, registerEntityTransport, registerRuntimeSchema, registerSchema, renderMarkdownToHtml, replayActionWithRetry, resetRealtimeManager, selectGraph, selectionColumn$1 as selectionColumn, serializeKey, sqlTypeToJsonSchema, startGarbageCollector, startLocalFirstGraph, stopGarbageCollector, textColumn$1 as textColumn, toEntityError, toGraphQLVariables, toPrismaInclude, toPrismaOrderBy, toPrismaWhere, toRestParams, toSQLClauses, useEntities, useEntity, useEntityAugment, useEntityCRUD, useEntityList, useEntityListAsTable, useEntityMutation, useEntityQuery, useEntityView, useGQLEntity, useGQLList, useGQLMutation, useGQLSubscription, useGraphDevTools, useGraphStore, useGraphSyncStatus, useLocalFirst, usePGliteQuery, useSchemaEntityFields, useSelectionContext, useSelectionStore, useSuspenseEntity, useSuspenseEntityList, useTable, useTablePresets, useTableRealtimeMode, useTableStorageAdapter, viewAction };