@prometheus-ags/entity-graph-core 3.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,2913 @@
+import * as zustand from 'zustand';
+import React from 'react';
+
+/**
+ * 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. */
+type EntityId = string;
+/** Stable string key for a list query (often `JSON.stringify`-shaped). Lists store IDs only under this key. */
+type QueryKey = string;
+/** Provenance of the latest known entity state. */
+type SyncOrigin = "server" | "client" | "optimistic";
+/** Optional sync-facing metadata kept outside canonical entity payloads. */
+interface EntitySyncMetadata {
+    synced: boolean;
+    origin: SyncOrigin;
+    updatedAt: number | null;
+}
+/** Snapshot shape returned by sync-aware reads and graph-native query helpers. */
+type EntitySnapshot<T extends object> = T & {
+    $synced: boolean;
+    $origin: SyncOrigin;
+    $updatedAt: number | null;
+};
+/**
+ * Fetch/cache metadata for a single entity instance (`type:id`).
+ * Separates transport concerns from canonical `entities` data so hooks can show spinners and stale-while-revalidate without mutating server-shaped fields.
+ */
+interface EntityState {
+    isFetching: boolean;
+    lastFetched: number | null;
+    error: string | null;
+    stale: boolean;
+}
+/**
+ * Ordered **IDs** for a list query plus pagination metadata — never embedded entity payloads.
+ * Cross-view reactivity depends on this: when `entities[type][id]` updates, every list containing that id re-resolves rows from the graph.
+ */
+interface ListState {
+    ids: EntityId[];
+    total: number | null;
+    nextCursor: string | null;
+    prevCursor: string | null;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    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;
+    pageSize: number | null;
+}
+/**
+ * Stable fallbacks for missing `lists[key]` / `entityStates[key]` slots.
+ * Inline `?? { ... }` defaults allocate new objects every `getSnapshot` call and trigger React 19
+ * “getSnapshot should be cached” / maximum update depth errors with `useSyncExternalStore`.
+ */
+declare const EMPTY_IDS: EntityId[];
+declare const EMPTY_ENTITY_STATE: EntityState;
+declare const EMPTY_SYNC_METADATA: EntitySyncMetadata;
+declare const EMPTY_LIST_STATE: ListState;
+/**
+ * Canonical Zustand store: **entities** (server truth), **patches** (UI-only overlay), **lists** (id order + list meta), and **entityStates** (per-entity fetch state).
+ * Prefer hooks for React reads; use `useGraphStore.getState()` inside stores/adapters/engine code where React is not available.
+ */
+interface GraphState {
+    /** Normalized server-confirmed records. Mutate only via upsert/replace/remove — not from components. */
+    entities: Record<EntityType, Record<EntityId, Record<string, unknown>>>;
+    /** Local-only fields merged at read time (`readEntity` / hooks). Never send patches to the server. */
+    patches: Record<EntityType, Record<EntityId, Record<string, unknown>>>;
+    /** Per-entity fetch lifecycle keyed as `${type}:${id}`. */
+    entityStates: Record<string, EntityState>;
+    /** Optional sync/provenance state layered beside the canonical entity payload. */
+    syncMetadata: Record<string, EntitySyncMetadata>;
+    /** List slots keyed by serialized query keys. Values hold id arrays and pagination — not entity clones. */
+    lists: Record<QueryKey, ListState>;
+    /**
+     * Shallow-merge `data` into the canonical entity. Use when the API returns partial updates or normalized fragments.
+     * @param type - Entity kind
+     * @param id - Entity id
+     * @param data - Fields to merge into existing canonical data
+     */
+    upsertEntity: (type: EntityType, id: EntityId, data: Record<string, unknown>) => void;
+    /**
+     * Batch upsert for list endpoints — avoids N separate writes when hydrating many rows at once.
+     * @param type - Entity kind
+     * @param entries - Pairs of id + partial/full payloads to merge
+     */
+    upsertEntities: (type: EntityType, entries: Array<{
+        id: EntityId;
+        data: Record<string, unknown>;
+    }>) => void;
+    /**
+     * Replace the canonical entity entirely (no merge). Use when the server returns a full snapshot and partial merge would leave stale keys behind.
+     */
+    replaceEntity: (type: EntityType, id: EntityId, data: Record<string, unknown>) => void;
+    /** Remove canonical entity, its patches, and its entityState. Does not remove the id from lists — use `removeIdFromAllLists` if needed. */
+    removeEntity: (type: EntityType, id: EntityId) => void;
+    /**
+     * Merge UI-only fields into `patches` so every subscriber sees selection, expansion, optimistic toggles, etc., without forking canonical data.
+     */
+    patchEntity: (type: EntityType, id: EntityId, patch: Record<string, unknown>) => void;
+    /** Remove specific patch keys; other patch keys remain. */
+    unpatchEntity: (type: EntityType, id: EntityId, keys: string[]) => void;
+    /** Drop all patches for an entity (e.g. after successful mutation when server data is authoritative). */
+    clearPatch: (type: EntityType, id: EntityId) => void;
+    /** Reflect in-flight GET for a single entity (deduped fetches in the engine still flip this once per logical request). */
+    setEntityFetching: (type: EntityType, id: EntityId, fetching: boolean) => void;
+    /** Persist terminal fetch failure message and clear fetching — hooks surface `error` while leaving prior data if any. */
+    setEntityError: (type: EntityType, id: EntityId, error: string | null) => void;
+    /** Mark entity successfully loaded; clears error, fetching, stale, and updates `lastFetched`. */
+    setEntityFetched: (type: EntityType, id: EntityId) => void;
+    /** Drive background revalidation: when true, hooks refetch while still showing cached `readEntity` data. */
+    setEntityStale: (type: EntityType, id: EntityId, stale: boolean) => void;
+    /** Merge sync metadata for one entity without polluting canonical server fields. */
+    setEntitySyncMetadata: (type: EntityType, id: EntityId, metadata: Partial<EntitySyncMetadata>) => void;
+    /** Clear sync metadata for one entity. */
+    clearEntitySyncMetadata: (type: EntityType, id: EntityId) => void;
+    /**
+     * Replace list ids and merge pagination meta after a primary list fetch (not load-more).
+     * Resets fetching flags and clears list error on success path (engine calls this after normalize).
+     */
+    setListResult: (key: QueryKey, ids: EntityId[], meta: Partial<Omit<ListState, "ids" | "isFetching" | "isFetchingMore" | "error" | "stale">>) => void;
+    /** Append unique ids (e.g. infinite scroll) while merging meta; dedupes id order. */
+    appendListResult: (key: QueryKey, ids: EntityId[], meta: Partial<Omit<ListState, "ids" | "isFetching" | "isFetchingMore" | "error" | "stale">>) => void;
+    /** Prepend ids (e.g. “new item at top”) with optional meta merge. */
+    prependListResult: (key: QueryKey, ids: EntityId[], meta?: Partial<ListState>) => void;
+    /** After deletes, keep every list consistent by removing an id everywhere it appears and decrementing `total` when tracked. */
+    removeIdFromAllLists: (type: EntityType, id: EntityId) => void;
+    /**
+     * Insert or move an id in one list. If the id already exists, it is removed first then re-inserted at `position`.
+     * @param position - `"start"`, `"end"`, or numeric index
+     */
+    insertIdInList: (key: QueryKey, id: EntityId, position: "start" | "end" | number) => void;
+    /** Initial or full list fetch in progress (not page-2+). */
+    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.
+     * 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;
+    /**
+     * Mark one or all entities of a type stale for subscriber-driven refetch. Does not delete data.
+     * @param id - Omit to stale every entity of `type`
+     */
+    invalidateEntity: (type: EntityType, id?: EntityId) => void;
+    /**
+     * Mark lists stale by key prefix or custom predicate so the next access triggers background refresh without dropping ids immediately.
+     */
+    invalidateLists: (matcher: string | ((key: QueryKey) => boolean)) => void;
+    /** Convenience: stale all entities of a type and lists whose keys start with `type`. */
+    invalidateType: (type: EntityType) => void;
+    /**
+     * Single read path: `{ ...entities[type][id], ...patches[type][id] }` or null if no canonical row exists.
+     * @returns Merged view suitable for rendering; not a deep clone
+     */
+    readEntity: <T = Record<string, unknown>>(type: EntityType, id: EntityId) => T | null;
+    /**
+     * Sync-aware read path: canonical entity + patches + virtual sync metadata (`$synced`, `$origin`, `$updatedAt`).
+     */
+    readEntitySnapshot: <T = Record<string, unknown>>(type: EntityType, id: EntityId) => EntitySnapshot<T & Record<string, unknown>> | null;
+}
+/**
+ * Global entity graph store (Zustand + Immer). **Components should not subscribe directly** — use hooks so layering stays `Component → hook → store`.
+ * `getState()` is intended for non-React code paths (engine, adapters, mutations) that must write or read the graph synchronously.
+ */
+declare const useGraphStore: zustand.UseBoundStore<Omit<Omit<zustand.StoreApi<GraphState>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: GraphState, previousSelectedState: GraphState) => void): () => void;
+        <U>(selector: (state: GraphState) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+}, "setState"> & {
+    setState(nextStateOrUpdater: GraphState | Partial<GraphState> | ((state: {
+        entities: {
+            [x: string]: {
+                [x: string]: {
+                    [x: string]: unknown;
+                };
+            };
+        };
+        patches: {
+            [x: string]: {
+                [x: string]: {
+                    [x: string]: unknown;
+                };
+            };
+        };
+        entityStates: {
+            [x: string]: {
+                isFetching: boolean;
+                lastFetched: number | null;
+                error: string | null;
+                stale: boolean;
+            };
+        };
+        syncMetadata: {
+            [x: string]: {
+                synced: boolean;
+                origin: SyncOrigin;
+                updatedAt: number | null;
+            };
+        };
+        lists: {
+            [x: string]: {
+                ids: string[];
+                total: number | null;
+                nextCursor: string | null;
+                prevCursor: string | null;
+                hasNextPage: boolean;
+                hasPrevPage: boolean;
+                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;
+                pageSize: number | null;
+            };
+        };
+        upsertEntity: (type: EntityType, id: EntityId, data: Record<string, unknown>) => void;
+        upsertEntities: (type: EntityType, entries: Array<{
+            id: EntityId;
+            data: Record<string, unknown>;
+        }>) => void;
+        replaceEntity: (type: EntityType, id: EntityId, data: Record<string, unknown>) => void;
+        removeEntity: (type: EntityType, id: EntityId) => void;
+        patchEntity: (type: EntityType, id: EntityId, patch: Record<string, unknown>) => void;
+        unpatchEntity: (type: EntityType, id: EntityId, keys: string[]) => void;
+        clearPatch: (type: EntityType, id: EntityId) => void;
+        setEntityFetching: (type: EntityType, id: EntityId, fetching: boolean) => void;
+        setEntityError: (type: EntityType, id: EntityId, error: string | null) => void;
+        setEntityFetched: (type: EntityType, id: EntityId) => void;
+        setEntityStale: (type: EntityType, id: EntityId, stale: boolean) => void;
+        setEntitySyncMetadata: (type: EntityType, id: EntityId, metadata: Partial<EntitySyncMetadata>) => void;
+        clearEntitySyncMetadata: (type: EntityType, id: EntityId) => void;
+        setListResult: (key: QueryKey, ids: EntityId[], meta: Partial<Omit<ListState, "ids" | "isFetching" | "isFetchingMore" | "error" | "stale">>) => void;
+        appendListResult: (key: QueryKey, ids: EntityId[], meta: Partial<Omit<ListState, "ids" | "isFetching" | "isFetchingMore" | "error" | "stale">>) => void;
+        prependListResult: (key: QueryKey, ids: EntityId[], meta?: Partial<ListState>) => void;
+        removeIdFromAllLists: (type: EntityType, id: EntityId) => void;
+        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, typed?: EntityError | null) => void;
+        setListStale: (key: QueryKey, stale: boolean) => void;
+        invalidateEntity: (type: EntityType, id?: EntityId) => void;
+        invalidateLists: (matcher: string | ((key: QueryKey) => boolean)) => void;
+        invalidateType: (type: EntityType) => void;
+        readEntity: <T = Record<string, unknown>>(type: EntityType, id: EntityId) => T | null;
+        readEntitySnapshot: <T = Record<string, unknown>>(type: EntityType, id: EntityId) => EntitySnapshot<T & Record<string, unknown>> | null;
+    }) => void), shouldReplace?: false): void;
+    setState(nextStateOrUpdater: GraphState | ((state: {
+        entities: {
+            [x: string]: {
+                [x: string]: {
+                    [x: string]: unknown;
+                };
+            };
+        };
+        patches: {
+            [x: string]: {
+                [x: string]: {
+                    [x: string]: unknown;
+                };
+            };
+        };
+        entityStates: {
+            [x: string]: {
+                isFetching: boolean;
+                lastFetched: number | null;
+                error: string | null;
+                stale: boolean;
+            };
+        };
+        syncMetadata: {
+            [x: string]: {
+                synced: boolean;
+                origin: SyncOrigin;
+                updatedAt: number | null;
+            };
+        };
+        lists: {
+            [x: string]: {
+                ids: string[];
+                total: number | null;
+                nextCursor: string | null;
+                prevCursor: string | null;
+                hasNextPage: boolean;
+                hasPrevPage: boolean;
+                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;
+                pageSize: number | null;
+            };
+        };
+        upsertEntity: (type: EntityType, id: EntityId, data: Record<string, unknown>) => void;
+        upsertEntities: (type: EntityType, entries: Array<{
+            id: EntityId;
+            data: Record<string, unknown>;
+        }>) => void;
+        replaceEntity: (type: EntityType, id: EntityId, data: Record<string, unknown>) => void;
+        removeEntity: (type: EntityType, id: EntityId) => void;
+        patchEntity: (type: EntityType, id: EntityId, patch: Record<string, unknown>) => void;
+        unpatchEntity: (type: EntityType, id: EntityId, keys: string[]) => void;
+        clearPatch: (type: EntityType, id: EntityId) => void;
+        setEntityFetching: (type: EntityType, id: EntityId, fetching: boolean) => void;
+        setEntityError: (type: EntityType, id: EntityId, error: string | null) => void;
+        setEntityFetched: (type: EntityType, id: EntityId) => void;
+        setEntityStale: (type: EntityType, id: EntityId, stale: boolean) => void;
+        setEntitySyncMetadata: (type: EntityType, id: EntityId, metadata: Partial<EntitySyncMetadata>) => void;
+        clearEntitySyncMetadata: (type: EntityType, id: EntityId) => void;
+        setListResult: (key: QueryKey, ids: EntityId[], meta: Partial<Omit<ListState, "ids" | "isFetching" | "isFetchingMore" | "error" | "stale">>) => void;
+        appendListResult: (key: QueryKey, ids: EntityId[], meta: Partial<Omit<ListState, "ids" | "isFetching" | "isFetchingMore" | "error" | "stale">>) => void;
+        prependListResult: (key: QueryKey, ids: EntityId[], meta?: Partial<ListState>) => void;
+        removeIdFromAllLists: (type: EntityType, id: EntityId) => void;
+        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, typed?: EntityError | null) => void;
+        setListStale: (key: QueryKey, stale: boolean) => void;
+        invalidateEntity: (type: EntityType, id?: EntityId) => void;
+        invalidateLists: (matcher: string | ((key: QueryKey) => boolean)) => void;
+        invalidateType: (type: EntityType) => void;
+        readEntity: <T = Record<string, unknown>>(type: EntityType, id: EntityId) => T | null;
+        readEntitySnapshot: <T = Record<string, unknown>>(type: EntityType, id: EntityId) => EntitySnapshot<T & Record<string, unknown>> | null;
+    }) => 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>;
+
+declare function getValueAtPath<T = unknown>(source: unknown, path: string): T | undefined;
+declare function setValueAtPath<T extends object>(source: T, path: string, value: unknown): T;
+declare function collectDirtyPaths(current: unknown, original: unknown, prefix?: string, acc?: Set<string>): Set<string>;
+
+/**
+ * merge/types.ts — Pluggable conflict-resolution seam for the entity graph.
+ *
+ * Why a port (not a hard-wired engine):
+ * - The graph receives concurrent writes from multiple sources — realtime
+ *   adapters (Flint, Supabase, Surreal), AG-UI agents, and optimistic local
+ *   mutations. The default resolution is last-write-wins (LWW), matching the
+ *   historical shallow-merge in `upsertEntity`.
+ * - Collaborative / agentic multi-writer scenarios need stronger guarantees
+ *   (CRDT). But the *engine* (Loro vs Automerge vs Yjs) is a downstream
+ *   decision — and the Flint fabric's own CRDT choice is still open. Encoding
+ *   the decision as a swappable `MergeStrategy` keeps that open decision from
+ *   blocking this layer.
+ *
+ * One strategy is registered per entity type (or a global default). The graph
+ * consults it at write time; absent a registration it falls back to LWW, so
+ * existing behavior is byte-for-byte preserved.
+ */
+
+/** Context handed to a {@link MergeStrategy} for one write. */
+interface MergeContext {
+    /** Entity kind being written. */
+    type: EntityType;
+    /** Entity id being written. */
+    id: EntityId;
+    /** Provenance of the incoming write (server / client / optimistic). */
+    origin: SyncOrigin;
+    /** Wall-clock ms of the incoming write, when the caller knows it. */
+    updatedAt: number | null;
+}
+/**
+ * Resolves the next canonical entity value from the previous value and an
+ * incoming partial/full write.
+ *
+ * Contract:
+ * - MUST be pure (no side effects, no graph access) — the graph applies the
+ *   returned value inside its Immer producer.
+ * - MUST return a NEW object; never mutate `prev` or `next` (immutability rule).
+ * - `prev` is `undefined` on first write for an id.
+ *
+ * @param prev - Current canonical value, or undefined if none exists yet.
+ * @param next - Incoming write (partial for upsert, full for replace).
+ * @param ctx  - Type/id/origin/timestamp metadata for this write.
+ * @returns The merged canonical value to store.
+ */
+type MergeStrategy = (prev: Record<string, unknown> | undefined, next: Record<string, unknown>, ctx: MergeContext) => Record<string, unknown>;
+
+/**
+ * merge/lww.ts — Last-write-wins default strategy.
+ *
+ * Semantics match the historical `upsertEntity` behavior exactly: shallow-merge
+ * the incoming write over the previous value. This is the fallback when no
+ * other strategy is registered, so registering nothing is a no-op change.
+ */
+
+/**
+ * Shallow-merge `next` over `prev` (incoming keys win). Returns a new object.
+ * On first write (`prev` undefined) returns a shallow copy of `next`.
+ */
+declare const lwwStrategy: MergeStrategy;
+
+/**
+ * merge/registry.ts — One MergeStrategy per entity type (+ optional global default).
+ *
+ * Lookup order at write time:
+ *   1. strategy registered for the exact `type`
+ *   2. global default strategy (if one was set)
+ *   3. built-in LWW (`lwwStrategy`)
+ *
+ * Step 3 guarantees that with zero registrations the graph behaves exactly as
+ * it did before this seam existed.
+ */
+
+/**
+ * Register a {@link MergeStrategy} for one entity type. Overwrites any prior
+ * registration for that type.
+ */
+declare function registerMergeStrategy(type: string, strategy: MergeStrategy): void;
+/**
+ * Set the fallback strategy used for any type without its own registration.
+ * Pass `null` to clear it (reverting the fallback to built-in LWW).
+ */
+declare function setDefaultMergeStrategy(strategy: MergeStrategy | null): void;
+/**
+ * Resolve the effective strategy for a type: per-type → global default → LWW.
+ * Always returns a usable strategy (never null).
+ */
+declare function getMergeStrategy(type: string): MergeStrategy;
+/** True if `type` (or a global default) has a non-LWW strategy registered. */
+declare function hasMergeStrategy(type: string): boolean;
+
+/**
+ * merge/loro.ts — Loro-backed CRDT MergeStrategy (reference implementation).
+ *
+ * Maps each entity (`type:id`) onto a Loro document whose root is an LWW-Map —
+ * a near-1:1 fit for the graph's `type:id:field` model. Concurrent field writes
+ * resolve via Loro's CRDT semantics rather than blind last-write-wins, so two
+ * writers updating *different* fields never clobber each other, and writers
+ * updating the *same* field resolve deterministically across replicas.
+ *
+ * `loro-crdt` is an OPTIONAL peer dependency. It is imported lazily so the core
+ * bundle stays `zustand + immer` only — nothing loads Loro unless an app
+ * actually registers `createLoroMergeStrategy()`.
+ *
+ * NOTE: `createLoroMergeStrategy` is async because it dynamically imports the
+ * engine. Await it once at boot, then register the resolved synchronous
+ * strategy. The returned strategy itself is pure+sync (the MergeStrategy
+ * contract), keeping per-write resolution off the async path.
+ */
+
+/**
+ * Build a Loro-backed {@link MergeStrategy}. Resolves `loro-crdt` lazily; throws
+ * a clear error if the optional peer is not installed.
+ *
+ * @example
+ * ```ts
+ * const loro = await createLoroMergeStrategy();
+ * registerMergeStrategy("Document", loro);
+ * ```
+ */
+declare function createLoroMergeStrategy(): Promise<MergeStrategy>;
+
+type GraphStore = ReturnType<typeof useGraphStore.getState>;
+type GraphIncludeMap = Record<string, GraphIncludeRelation>;
+type GraphIncludeRelation = {
+    type: EntityType;
+    via: {
+        kind: "field";
+        field: string;
+    };
+    include?: GraphIncludeMap;
+} | {
+    type: EntityType;
+    via: {
+        kind: "array";
+        field: string;
+    };
+    include?: GraphIncludeMap;
+} | {
+    type: EntityType;
+    via: {
+        kind: "list";
+        key: QueryKey | ((entity: Record<string, unknown>) => QueryKey | null | undefined);
+    };
+    include?: GraphIncludeMap;
+} | {
+    type: EntityType;
+    via: {
+        kind: "resolver";
+        resolve: (entity: Record<string, unknown>, store: GraphStore) => EntityId | EntityId[] | null | undefined;
+    };
+    include?: GraphIncludeMap;
+};
+interface GraphQueryOptions<TEntity extends object> {
+    type: EntityType;
+    id?: EntityId;
+    ids?: EntityId[];
+    listKey?: QueryKey;
+    where?: (entity: EntitySnapshot<TEntity>) => boolean;
+    sort?: (a: EntitySnapshot<TEntity>, b: EntitySnapshot<TEntity>) => number;
+    include?: GraphIncludeMap;
+    select?: ((entity: Record<string, unknown>) => unknown) | string[];
+}
+type ProjectedRow = Record<string, unknown>;
+declare function queryOnce<TEntity extends object>(opts: GraphQueryOptions<TEntity> & {
+    id: EntityId;
+}): ProjectedRow | null;
+declare function queryOnce<TEntity extends object>(opts: GraphQueryOptions<TEntity>): ProjectedRow[];
+declare const selectGraph: typeof queryOnce;
+
+interface GraphDataSnapshot {
+    entities: ReturnType<typeof useGraphStore.getState>["entities"];
+    patches: ReturnType<typeof useGraphStore.getState>["patches"];
+    entityStates: ReturnType<typeof useGraphStore.getState>["entityStates"];
+    syncMetadata: ReturnType<typeof useGraphStore.getState>["syncMetadata"];
+    lists: ReturnType<typeof useGraphStore.getState>["lists"];
+}
+interface GraphTransaction {
+    upsertEntity: (type: EntityType, id: EntityId, data: Record<string, unknown>) => GraphTransaction;
+    replaceEntity: (type: EntityType, id: EntityId, data: Record<string, unknown>) => GraphTransaction;
+    removeEntity: (type: EntityType, id: EntityId) => GraphTransaction;
+    patchEntity: (type: EntityType, id: EntityId, patch: Record<string, unknown>) => GraphTransaction;
+    clearPatch: (type: EntityType, id: EntityId) => GraphTransaction;
+    insertIdInList: (key: QueryKey, id: EntityId, position: "start" | "end" | number) => GraphTransaction;
+    removeIdFromAllLists: (type: EntityType, id: EntityId) => GraphTransaction;
+    setEntitySyncMetadata: (type: EntityType, id: EntityId, metadata: Partial<EntitySyncMetadata>) => GraphTransaction;
+    markEntityPending: (type: EntityType, id: EntityId, origin?: SyncOrigin) => GraphTransaction;
+    markEntitySynced: (type: EntityType, id: EntityId, origin?: SyncOrigin) => GraphTransaction;
+    commit: () => void;
+    rollback: () => void;
+    snapshot: () => GraphDataSnapshot;
+}
+interface GraphActionOptions<TInput, TResult> {
+    key?: string;
+    optimistic?: (tx: GraphTransaction, input: TInput) => void;
+    run: (tx: GraphTransaction, input: TInput) => Promise<TResult> | TResult;
+    onSuccess?: (result: TResult, input: TInput, tx: GraphTransaction) => void;
+    onError?: (error: Error, input: TInput) => void;
+}
+interface GraphActionRecord$1 {
+    id: string;
+    key: string;
+    input: unknown;
+    enqueuedAt: string;
+}
+type GraphActionEvent = {
+    type: "enqueued";
+    record: GraphActionRecord$1;
+} | {
+    type: "settled";
+    record: GraphActionRecord$1;
+};
+declare function createGraphTransaction(): GraphTransaction;
+declare function createGraphAction<TInput, TResult>(opts: GraphActionOptions<TInput, TResult>): (input: TInput) => Promise<TResult>;
+
+interface GraphEffectEvent<T> {
+    key: string;
+    value: T;
+    previousValue: T;
+}
+interface GraphEffectOptions<T> {
+    query: () => T[] | T | null;
+    getKey?: (value: T, index: number) => string;
+    skipInitial?: boolean;
+    isEqual?: (previousValue: T, nextValue: T) => boolean;
+    onEnter?: (event: {
+        key: string;
+        value: T;
+    }) => void;
+    onUpdate?: (event: GraphEffectEvent<T>) => void;
+    onExit?: (event: {
+        key: string;
+        previousValue: T;
+    }) => void;
+}
+interface GraphEffectHandle {
+    dispose: () => void;
+}
+declare function createGraphEffect<T>(opts: GraphEffectOptions<T>): GraphEffectHandle;
+
+/**
+ * schema.ts (core) — framework-agnostic JSON-schema registry + snapshot/markdown
+ * helpers. The React field renderers/editors (MarkdownFieldRenderer,
+ * MarkdownFieldEditor, useSchemaEntityFields, buildEntityFieldsFromSchema which
+ * depends on the UI FieldDescriptor type) live in the react binding's schema.tsx,
+ * built on these primitives.
+ */
+interface JsonSchemaObject {
+    $id?: string;
+    title?: string;
+    description?: string;
+    type?: string | string[];
+    format?: string;
+    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;
+    ["x-hidden"]?: boolean;
+}
+interface EntityJsonSchemaConfig {
+    entityType: string;
+    schemaId?: string;
+    field?: string;
+    version?: string;
+    source?: "static" | "runtime" | "ai";
+    schema: JsonSchemaObject;
+}
+interface GetEntityJsonSchemaOptions {
+    entityType: string;
+    schemaId?: string;
+    field?: string;
+}
+interface GraphSnapshotWithSchemasOptions {
+    scope: string;
+    data: unknown;
+    schemas: Array<EntityJsonSchemaConfig | null | undefined>;
+    pretty?: boolean;
+}
+declare function registerEntityJsonSchema(config: EntityJsonSchemaConfig): void;
+declare function registerRuntimeSchema(config: EntityJsonSchemaConfig): void;
+declare function getEntityJsonSchema(opts: GetEntityJsonSchemaOptions): EntityJsonSchemaConfig | null;
+declare function exportGraphSnapshotWithSchemas(opts: GraphSnapshotWithSchemasOptions): string;
+declare function escapeHtml(input: string): string;
+declare function renderMarkdownToHtml(value: string): string;
+/** Infer a coarse field-type string from a JSON-schema node (UI-agnostic). */
+declare function inferSchemaFieldType(schema: JsonSchemaObject): string;
+declare function registryKey(entityType: string, field?: string, schemaId?: string): string;
+declare function humanizeFieldName(value: string): string;
+
+interface GraphSnapshotExportOptions {
+    scope: string;
+    data: unknown;
+    pretty?: boolean;
+}
+interface GraphToolContext {
+    store: ReturnType<typeof useGraphStore.getState>;
+    queryOnce: typeof queryOnce;
+    exportGraphSnapshot: typeof exportGraphSnapshot;
+}
+interface SchemaGraphToolContext extends GraphToolContext {
+    getEntityJsonSchema: typeof getEntityJsonSchema;
+    exportGraphSnapshotWithSchemas: typeof exportGraphSnapshotWithSchemas;
+}
+declare function exportGraphSnapshot(opts: GraphSnapshotExportOptions): string;
+declare function createGraphTool<TInput, TResult>(handler: (input: TInput, ctx: GraphToolContext) => Promise<TResult> | TResult): (input: TInput) => TResult | Promise<TResult>;
+declare function createSchemaGraphTool<TInput, TResult>(handler: (input: TInput, ctx: SchemaGraphToolContext) => Promise<TResult> | TResult): (input: TInput) => TResult | Promise<TResult>;
+
+interface GraphPersistenceAdapter {
+    get: (key: string) => Promise<string | null> | string | null;
+    set: (key: string, value: string) => Promise<void> | void;
+    remove?: (key: string) => Promise<void> | void;
+}
+interface GraphActionRecord {
+    id: string;
+    key: string;
+    input: unknown;
+    enqueuedAt: string;
+}
+interface GraphSyncStatus {
+    phase: "idle" | "hydrating" | "syncing" | "ready" | "offline" | "error";
+    isOnline: boolean;
+    isSynced: boolean;
+    pendingActions: number;
+    lastHydratedAt: string | null;
+    lastPersistedAt: string | null;
+    storageKey: string | null;
+    error: string | null;
+}
+interface GraphSnapshotPayload {
+    version: 1;
+    snapshot: {
+        entities: ReturnType<typeof useGraphStore.getState>["entities"];
+        patches: ReturnType<typeof useGraphStore.getState>["patches"];
+        entityStates: ReturnType<typeof useGraphStore.getState>["entityStates"];
+        syncMetadata: ReturnType<typeof useGraphStore.getState>["syncMetadata"];
+        lists: ReturnType<typeof useGraphStore.getState>["lists"];
+    };
+    pendingActions: GraphActionRecord[];
+}
+interface PersistGraphToStorageOptions {
+    storage: GraphPersistenceAdapter;
+    key: string;
+    pendingActions?: GraphActionRecord[];
+}
+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;
+    replayPendingActions?: boolean;
+    onlineSource?: {
+        getIsOnline: () => boolean;
+        subscribe: (listener: (online: boolean) => void) => () => void;
+    };
+    persistDebounceMs?: number;
+    /** Retry-with-backoff policy for offline action replay. */
+    retryPolicy?: ReplayRetryPolicy;
+}
+interface LocalFirstGraphRuntime {
+    ready: Promise<void>;
+    dispose: () => void;
+    persistNow: () => Promise<void>;
+    hydrate: () => Promise<Awaited<ReturnType<typeof hydrateGraphFromStorage>>>;
+    getStatus: () => GraphSyncStatus;
+}
+declare function useGraphSyncStatus(): GraphSyncStatus;
+declare function persistGraphToStorage(opts: PersistGraphToStorageOptions): Promise<{
+    ok: true;
+    key: string;
+    bytes: number;
+    persistedAt: string;
+}>;
+declare function hydrateGraphFromStorage(opts: HydrateGraphFromStorageOptions): Promise<{
+    ok: false;
+    key: string;
+    hydratedAt: null;
+    entityCounts: {};
+    error: string;
+    pendingActions?: undefined;
+} | {
+    ok: true;
+    key: string;
+    hydratedAt: string;
+    entityCounts: {
+        [k: string]: number;
+    };
+    pendingActions: GraphActionRecord[];
+    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;
+}>;
+
+/**
+ * Process-wide defaults for stale times, retries, and background revalidation.
+ * Keeps hook signatures small: `useEntity` / `useEntityList` merge these with per-query overrides.
+ */
+interface EngineOptions {
+    defaultStaleTime?: number;
+    /** Max age (`Date.now() - lastFetched`) for evicting entities with zero subscribers during GC. */
+    defaultGcTime?: number;
+    /** Interval between GC passes when the collector is active (default 60s). */
+    gcInterval?: number;
+    maxRetries?: number;
+    retryBaseDelay?: number;
+    revalidateOnFocus?: boolean;
+    revalidateOnReconnect?: boolean;
+}
+/**
+ * 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 object> {
+    type: EntityType;
+    id: EntityId | null | undefined;
+    fetch: (id: EntityId) => Promise<TRaw>;
+    normalize: (raw: TRaw) => TEntity;
+    idField?: string;
+    sideEffects?: (raw: TRaw, store: typeof useGraphStore) => void;
+    staleTime?: number;
+    enabled?: boolean;
+    onSuccess?: (entity: TEntity) => void;
+    onError?: (error: Error) => void;
+}
+/** Cursor/page knobs passed through to list `fetch` implementations (REST, GraphQL, etc.). */
+interface ListFetchParams {
+    cursor?: string;
+    page?: number;
+    pageSize?: number;
+    params?: Record<string, unknown>;
+}
+/**
+ * Normalized list page shape from any backend. Items are mapped through `normalize` into `{ id, data }` upserts — the list stores ids only.
+ */
+interface ListResponse<T> {
+    items: T[];
+    total?: number | null;
+    nextCursor?: string | null;
+    prevCursor?: string;
+    hasNextPage?: boolean;
+    hasPrevPage?: boolean;
+    page?: number;
+    pageSize?: number;
+}
+/**
+ * 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 object> {
+    type: EntityType;
+    queryKey: unknown[];
+    /**
+     * Inline fetcher (deprecated 1.x REST form). Optional in 2.0: pure graph
+     * subscriptions for Tier-A PGlite/Electric entities pass no fetcher — the
+     * graph is hydrated out-of-band and the hook only joins ids → entities.
+     * When omitted, `fetchList` is a no-op and the hook is read-only.
+     */
+    fetch?: (params: ListFetchParams) => Promise<ListResponse<TRaw>>;
+    /** Row normalizer. Optional alongside `fetch` (graph-only callers omit both). */
+    normalize?: (raw: TRaw) => {
+        id: EntityId;
+        data: TEntity;
+    };
+    sideEffects?: (items: TRaw[], store: typeof useGraphStore) => void;
+    mode?: "replace" | "append";
+    staleTime?: number;
+    enabled?: boolean;
+    onSuccess?: (result: ListResponse<TRaw>) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Deterministic string key for list queries so object order in nested keys does not create duplicate cache entries.
+ * @param key - Hook-provided query key array (serializable values)
+ */
+declare function serializeKey(key: unknown[]): string;
+/**
+ * Collapse concurrent identical requests into one Promise (prevents stampedes when many components mount the same entity/list).
+ * @param key - Logical dedupe key (e.g. `type:id` or serialized list key)
+ * @param fn - Async work that performs the fetch + graph writes
+ */
+declare function dedupe<T>(key: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Ref-count graph interest for a subscriber key (`${type}:${id}`). Background revalidation skips keys with zero subscribers.
+ * @returns Opaque token required for `unregisterSubscriber`
+ */
+declare function registerSubscriber(key: string): symbol;
+/** Pair with `registerSubscriber` on unmount so idle entities stop refetching. */
+declare function unregisterSubscriber(key: string, token: symbol): void;
+/**
+ * Subscribe to ref-count changes for `registerSubscriber` / `unregisterSubscriber`.
+ * Used by `useGraphDevTools` so subscriber totals update without graph mutations.
+ */
+declare function subscribeSubscriberStats(onChange: () => void): () => boolean;
+/** Total active entity subscriber tokens across all keys (sum of ref-counts). */
+declare function getActiveSubscriberCount(): number;
+/**
+ * Discriminated union of devtools events.
+ *
+ * - `upsert`, `patch`, `clearPatch` are emitted from `graph-actions.ts` ops.
+ * - `unpatch` and `list` are forward-compatible kinds reserved for future
+ *   instrumentation (W5+ event bus / W6+ panel). Consumers MUST handle them
+ *   in exhaustive `switch`/`if` chains today, even though no op-site emits
+ *   them in this change.
+ */
+type DevtoolsEvent = {
+    kind: "upsert";
+    type: EntityType;
+    id: EntityId;
+    data: Record<string, unknown>;
+    at: string;
+} | {
+    kind: "patch";
+    type: EntityType;
+    id: EntityId;
+    patch: Record<string, unknown>;
+    at: string;
+} | {
+    kind: "unpatch";
+    type: EntityType;
+    id: EntityId;
+    keys: string[];
+    at: string;
+} | {
+    kind: "clearPatch";
+    type: EntityType;
+    id: EntityId;
+    at: string;
+} | {
+    kind: "list";
+    key: string;
+    idCount: number;
+    at: string;
+};
+type DevtoolsListener = (event: DevtoolsEvent) => void;
+/**
+ * Subscribe to the devtools event stream.
+ *
+ * - Returns an `UnsubscribeFn` that removes this listener.
+ * - Idempotent: subscribing the same function reference twice tracks it once
+ *   (Set semantics).
+ * - Throwing listeners do NOT block delivery to other listeners; the error is
+ *   logged via `console.warn` and dispatch continues.
+ * - Re-entrancy safe: listeners that subscribe/unsubscribe during dispatch
+ *   affect future events only, not the in-flight one.
+ */
+declare function subscribeDevtoolsEvent(cb: DevtoolsListener): () => void;
+/**
+ * Stops the periodic garbage-collection timer started by `startGarbageCollector` / `configureEngine`.
+ */
+declare function stopGarbageCollector(): void;
+/**
+ * Starts periodic garbage collection using current `getEngineOptions().gcInterval`.
+ * Stops any previous interval first. No-ops during SSR (`window` is undefined) or without `setInterval`.
+ * @returns Disposer that stops this collector (equivalent to `stopGarbageCollector`).
+ */
+declare function startGarbageCollector(): () => void;
+/** Override global engine behavior (typically once at app bootstrap). Restarts GC with merged options. */
+declare function configureEngine(opts: EngineOptions): void;
+/** Read merged engine options; hooks use this for default `staleTime` and retry behavior. */
+declare function getEngineOptions(): Required<EngineOptions>;
+/**
+ * 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 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 object>(opts: ListQueryOptions<TRaw, TEntity>, params: ListFetchParams, engineOpts: Required<EngineOptions>, isLoadMore?: boolean): Promise<void>;
+/**
+ * Opt-in window listeners that mark **subscribed** entities stale on focus/reconnect so hooks can SWR-refetch.
+ * Idempotent; safe for SSR (no-ops without `window`). Pair with `configureEngine` flags.
+ */
+declare function attachGlobalListeners(): void;
+
+/**
+ * devtools-event-bus — W5 (seim-em-explorer-event-bus-registry)
+ *
+ * Ring-buffered, fan-out event bus on top of the W3 `subscribeDevtoolsEvent` tap.
+ * Adds: replay-on-subscribe, microtask-level burst coalescing, multi-store registry.
+ */
+
+interface DevtoolsEventBusOptions {
+    /** Maximum events retained in the ring buffer. Default: 500. */
+    bufferSize?: number;
+    /**
+     * Events 1..N (N = threshold) are dispatched individually as they arrive.
+     * Events N+1.. accumulate until the end of the microtask, then are coalesced
+     * into one synthetic `kind:"list"` summary event.
+     * Default: 10. Set to 0 to disable coalescing entirely.
+     */
+    coalesceBurstThreshold?: number;
+}
+interface DevtoolsEventBus {
+    /** Subscribe to live events. Replays current buffer synchronously before returning. */
+    subscribe(cb: (event: DevtoolsEvent) => void): () => void;
+    /** Snapshot of buffered events in chronological order (oldest first). */
+    getBuffer(): readonly DevtoolsEvent[];
+    /** Force-dispatch any pending coalesced burst synchronously. */
+    flush(): void;
+    /** Release engine-tap, clear all subscribers, cascade inactive to registry. */
+    destroy(): void;
+    /**
+     * Inject a synthetic `DevtoolsEvent` directly into the bus, bypassing the
+     * engine tap. Used by the Chrome MV3 extension panel to feed events arriving
+     * over the port-messaging bridge into the local bus instance.
+     */
+    inject(event: DevtoolsEvent): void;
+}
+/** Matches the signature of `subscribeDevtoolsEvent` — used for external sources. */
+type DevtoolsSourceFn = (cb: (event: DevtoolsEvent) => void) => () => void;
+interface RegisteredStore {
+    name: string;
+    active: boolean;
+}
+/** @internal Test-only. NOT re-exported from index.ts. */
+declare function __resetStoreRegistry(): void;
+declare function createDevtoolsEventBus(opts?: DevtoolsEventBusOptions): DevtoolsEventBus;
+/**
+ * Wire an additional event source into an existing `DevtoolsEventBus`.
+ * Events from `source` flow through the bus's ring buffer, coalescing, and fan-out.
+ * Throws if `name` is already registered and active.
+ */
+declare function registerStore(bus: DevtoolsEventBus, source: DevtoolsSourceFn, name: string): () => void;
+/** Returns a snapshot of all registered stores (active + inactive) in registration order. */
+declare function getRegisteredStores(): ReadonlyArray<RegisteredStore>;
+
+/**
+ * devtools-time-travel.ts — G4 parity: true time-travel for the entity graph.
+ *
+ * The Timeline tab (C5) inspected a read-only history log. This adds the
+ * defining Redux-DevTools capability the gap analysis called out: **rewind the
+ * LIVE graph to a prior recorded state and replay forward.**
+ *
+ * Model:
+ * - `recordGraphSnapshot()` captures the canonical graph data (entities, patches,
+ *   entityStates, syncMetadata, lists) into a bounded ring (default 50).
+ * - `restoreGraphSnapshot(index)` writes a captured snapshot back into the live
+ *   Zustand store — the graph (and every subscriber/view) reverts to that state.
+ * - `getTimeTravelState()` exposes the ring + current cursor for the devtools UI.
+ *
+ * Snapshots are deep-cloned on capture and on restore so restoring never aliases
+ * ring contents into the live store (a later mutation must not corrupt history).
+ *
+ * This is debug-time machinery: it is intended to run behind the EntityExplorer,
+ * not in production data paths.
+ */
+
+type GraphSlice = Pick<ReturnType<typeof useGraphStore.getState>, "entities" | "patches" | "entityStates" | "syncMetadata" | "lists">;
+interface TimeTravelSnapshot {
+    /** Monotonic id (capture order). */
+    seq: number;
+    /** Capture timestamp (ms). */
+    at: number;
+    /** Optional label (e.g. the action that produced this state). */
+    label?: string;
+    data: GraphSlice;
+}
+interface TimeTravelState {
+    snapshots: ReadonlyArray<Omit<TimeTravelSnapshot, "data">>;
+    /** Index currently restored, or null if live (at head). */
+    cursor: number | null;
+    capacity: number;
+}
+/** Configure ring capacity (number of retained snapshots). */
+declare function configureTimeTravel(opts: {
+    capacity?: number;
+}): void;
+/** Capture the current live graph state into the ring. Returns the snapshot seq. */
+declare function recordGraphSnapshot(label?: string): number;
+/**
+ * Restore the live graph to the snapshot at ring `index` (0-based into the
+ * current ring). The Zustand store is overwritten with a deep clone of the
+ * captured slice, so all subscribers re-render at that historical state.
+ * Returns true if restored.
+ */
+declare function restoreGraphSnapshot(index: number): boolean;
+/** Restore by capture seq (stable across ring eviction within capacity). */
+declare function restoreGraphSnapshotBySeq(seq: number): boolean;
+/** Step the cursor by `delta` (negative = back in time) and restore. */
+declare function stepTimeTravel(delta: number): boolean;
+/** Snapshot metadata + cursor for the devtools UI (no heavy data payloads). */
+declare function getTimeTravelState(): TimeTravelState;
+/** Subscribe to ring/cursor changes (for useSyncExternalStore in the UI). */
+declare function subscribeTimeTravel(cb: () => void): () => void;
+
+/**
+ * Evaluate `FilterSpec` against one in-memory entity — mirrors remote semantics as closely as plain JS allows.
+ * Use for **local** and **hybrid** `useEntityView` paths so UI filtering matches what users expect from the declarative spec.
+ */
+declare function matchesFilter(entity: Record<string, unknown>, filter: FilterSpec): boolean;
+/**
+ * Case-insensitive substring match across configured string fields; empty query is a no-op pass.
+ * Keeps quick search consistent between client-only and debounced remote `q` params.
+ */
+declare function matchesSearch(entity: Record<string, unknown>, query: string, fields: string[]): boolean;
+/**
+ * Multi-key comparator implementing `SortSpec` (null ordering, optional custom comparators, locale-aware string fallback).
+ * Shared by local sorting and binary insertion for realtime updates.
+ */
+declare function compareEntities(a: Record<string, unknown>, b: Record<string, unknown>, sort: SortSpec): number;
+/**
+ * Binary-search insertion index so realtime inserts land in sorted order without resorting the full id list (O(log n) per insert).
+ * Skips missing `getEntity` rows by advancing low — callers should ensure entities exist or tolerate append-like behavior.
+ */
+declare function findInsertionIndex(entity: Record<string, unknown>, sortedIds: string[], getEntity: (id: string) => Record<string, unknown> | null, sort: SortSpec): number;
+/**
+ * Pure list projection: map ids → entities, drop missing, filter/sort/search, return **ids** in display order.
+ * Bridges stored id lists with on-the-fly view descriptors without duplicating entity payloads.
+ */
+declare function applyView(ids: string[], getEntity: (id: string) => Record<string, unknown> | null, filter?: FilterSpec | null, sort?: SortSpec | null, search?: {
+    query: string;
+    fields: string[];
+} | null): string[];
+/**
+ * Heuristic for whether the graph likely holds **all** rows for a list key (enables local-only filtering/sorting in `useEntityView`).
+ * `total` and `hasNextPage` come from list metadata written by fetchers.
+ */
+declare function checkCompleteness(loadedCount: number, total: number | null, hasNextPage: boolean): {
+    isComplete: boolean;
+    reason: string;
+};
+
+/**
+ * view/incremental.ts — G3 parity: incremental view maintenance.
+ *
+ * The baseline `applyView` re-filters + re-sorts the entire id list on every
+ * change — O(n) per update. For large lists this is the gap vs TanStack DB's
+ * differential-dataflow live queries.
+ *
+ * This maintains a derived, sorted result and updates it for a SINGLE entity
+ * change in O(log n): binary-search the entity's current position, decide
+ * membership via the filter, and insert / remove / reposition. No full
+ * re-derivation. Result is byte-identical to `applyView` for the same inputs
+ * (correctness parity is asserted in tests).
+ *
+ * Design choice: a hand-rolled dirty-tracking index rather than adopting d2ts
+ * (0.1.x, pre-production) — same acceptance bar (sub-linear single-row update),
+ * far lower dependency risk. The differential engine can replace the internals
+ * later behind this same class without an API change.
+ */
+
+interface IncrementalViewOptions {
+    filter?: FilterSpec | null;
+    sort?: SortSpec | null;
+    search?: {
+        query: string;
+        fields: string[];
+    } | null;
+    /** Resolve an entity by id from the graph (or null if absent). */
+    getEntity: (id: string) => Record<string, unknown> | null;
+}
+/**
+ * A live, sorted view over a set of entity ids that updates incrementally.
+ *
+ * - `seed(ids)` builds the initial result (one O(n log n) pass).
+ * - `applyChange(id)` updates the result for one changed/added/removed entity
+ *   in O(log n) comparisons (+ array splice).
+ * - `result()` returns the current ordered id list (stable reference until a
+ *   change mutates it).
+ */
+declare class IncrementalView {
+    private readonly opts;
+    private ids;
+    private readonly members;
+    constructor(opts: IncrementalViewOptions);
+    /** Whether an entity qualifies for this view (filter + search). */
+    private qualifies;
+    /** Comparator over ids using the configured sort (stable, id tiebreak). */
+    private cmp;
+    /** Binary-search the insertion index for `id` among current `ids`. */
+    private insertionIndex;
+    /** Build the initial sorted result from a full id set. */
+    seed(ids: string[]): void;
+    /**
+     * Update the view for ONE entity that changed/was added/removed.
+     * Returns true if the result order changed.
+     *
+     * O(log n) to locate; the array splice is O(n) memory-move but performs no
+     * filter/sort over the whole set — the differentiator from full re-derivation.
+     */
+    applyChange(id: string): boolean;
+    /** Current ordered id list. */
+    result(): string[];
+    /** Current member count. */
+    size(): number;
+}
+
+/**
+ * FK edge: this entity points at one parent row. Used to invalidate parent aggregates and optional list keys when the FK changes.
+ */
+interface BelongsToRelation {
+    cardinality: "belongsTo";
+    foreignKey: string;
+    targetType: EntityType;
+    invalidateTargetLists?: string[];
+}
+/**
+ * Inverse collection: children carry `foreignKey` pointing here; `listKeyPrefix` builds the child list query key for a given parent id.
+ */
+interface HasManyRelation {
+    cardinality: "hasMany";
+    targetType: EntityType;
+    foreignKey: string;
+    listKeyPrefix: (parentId: EntityId) => unknown[];
+}
+/**
+ * Join-style relation stored as an id array on this entity; invalidates partner lists derived via `listKeyPrefix` for each touched id.
+ */
+interface ManyToManyRelation {
+    cardinality: "manyToMany";
+    targetType: EntityType;
+    localArrayField?: string;
+    listKeyPrefix: (thisId: EntityId) => unknown[];
+}
+type RelationDescriptor = BelongsToRelation | HasManyRelation | ManyToManyRelation;
+/**
+ * Declarative relation metadata for one `EntityType`: optional named relations and list key prefixes to invalidate on any mutation.
+ */
+interface EntitySchema {
+    type: EntityType;
+    relations?: Record<string, RelationDescriptor>;
+    globalListKeys?: string[];
+}
+/**
+ * Snapshot diff passed to cascade rules after CRUD: compare `previous` vs `next` to find FK moves, array membership changes, etc.
+ */
+interface CascadeContext {
+    type: EntityType;
+    id: EntityId;
+    previous: Record<string, unknown> | null;
+    next: Record<string, unknown> | null;
+    op: "create" | "update" | "delete";
+}
+/** Register or replace schema for `schema.type` (typically at app init). */
+declare function registerSchema(schema: EntitySchema): void;
+/** Lookup schema for cascade/join reads; returns null if unregistered. */
+declare function getSchema(type: EntityType): EntitySchema | null;
+/**
+ * After a successful mutation, mark related entities/lists stale so hooks refetch without manually hunting query keys.
+ * Traverses registered schemas (including reverse `hasMany`) so denormalized UIs stay eventually consistent with the graph.
+ */
+declare function cascadeInvalidation(ctx: CascadeContext): void;
+/**
+ * Resolve relation **placeholders** for detail panels: joins graph reads for belongs-to targets, has-many id lists, or many-to-many id arrays.
+ * Returns plain objects suitable for rendering; does not mutate the graph.
+ */
+declare function readRelations(type: EntityType, entity: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * agent/json-patch.ts — Minimal RFC-6902 JSON Patch applier.
+ *
+ * AG-UI `STATE_DELTA` events carry RFC-6902 operations. Rather than take a hard
+ * dependency on `fast-json-patch` (last released 2022) or require consumers to
+ * have `@ag-ui/client`'s applier, this implements the standard's six operations
+ * directly. It is small, dependency-free, and fully unit-tested.
+ *
+ * Immutability: every op returns a NEW document; the input is never mutated.
+ *
+ * Supported ops: add, replace, remove, move, copy, test.
+ * Pointers follow RFC-6901 (`/a/b/0`), including the `-` array-append token and
+ * `~1`/`~0` escapes for `/` and `~`.
+ */
+interface JsonPatchOp {
+    op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+    path: string;
+    /** For add/replace/test. */
+    value?: unknown;
+    /** For move/copy. */
+    from?: string;
+}
+/**
+ * Apply a sequence of RFC-6902 operations to `doc`, returning a new document.
+ * A failing `test` op throws (per spec); structural ops are applied in order.
+ */
+declare function applyJsonPatch<T = unknown>(doc: T, ops: readonly JsonPatchOp[]): T;
+
+/**
+ * agent/ag-ui-bridge.ts — Ingest AG-UI agent state into the entity graph.
+ *
+ * The headline agentic capability (change C2): an agent emits AG-UI state, it
+ * lands in the entity graph, and every view reading those entities updates.
+ *
+ * AG-UI (https://docs.ag-ui.com) streams two state events:
+ *   - STATE_SNAPSHOT — the complete agent state object
+ *   - STATE_DELTA    — a partial update as an RFC-6902 JSON Patch
+ *
+ * Our `patchEntity`/`upsertEntity` already align with this model: STATE_DELTA's
+ * JSON Patch maps onto the graph, and writes route through the C1 MergeStrategy
+ * so agent edits resolve against concurrent realtime/local writes.
+ *
+ * Mapping: the agent's state tree is projected onto entities via an
+ * {@link AgUiStateMapping}. Each entry says "the object at this JSON-Pointer
+ * prefix is an entity of `type`, keyed by `id` (a field of that object or a
+ * constant)". This keeps the bridge transport-agnostic — it does not depend on
+ * `@ag-ui/client` and takes plain event objects, so `@ag-ui/*` stays an OPTIONAL
+ * peer (use it for typed events on the consumer side if desired).
+ */
+
+/** AG-UI STATE_SNAPSHOT event (minimal shape — no @ag-ui dependency). */
+interface AgUiStateSnapshotEvent {
+    type?: "STATE_SNAPSHOT" | string;
+    snapshot: Record<string, unknown>;
+}
+/** AG-UI STATE_DELTA event (minimal shape — RFC-6902 patch). */
+interface AgUiStateDeltaEvent {
+    type?: "STATE_DELTA" | string;
+    delta: JsonPatchOp[];
+}
+/** Maps one slice of agent state onto an entity type. */
+interface AgUiStateMapping {
+    /** Entity type the mapped object(s) belong to. */
+    entityType: string;
+    /**
+     * JSON-Pointer prefix into the agent state where this entity (or collection)
+     * lives. `"/order"` → a single entity; `"/orders"` → a collection keyed by id.
+     */
+    pointer: string;
+    /** Whether `pointer` addresses one object or a collection (array/record). */
+    kind: "single" | "collection";
+    /**
+     * Field on each object that holds its entity id. For `single` you may instead
+     * pass a constant id via `constantId`.
+     */
+    idField?: string;
+    /** Constant id for `single` mappings whose object has no id field. */
+    constantId?: string;
+    /**
+     * How to write: `upsert` (merge via MergeStrategy — default) or `replace`
+     * (full overwrite). Snapshots typically replace; deltas typically upsert.
+     */
+    write?: "upsert" | "replace";
+}
+interface ApplyAgUiOptions {
+    mappings: AgUiStateMapping[];
+}
+/**
+ * Apply an AG-UI STATE_SNAPSHOT to the graph. Each mapped slice is written as an
+ * entity. Snapshots default to `replace` semantics when the mapping does not
+ * specify otherwise is left to the mapping's `write` field (default upsert).
+ *
+ * @example
+ * ```ts
+ * applyAgUiSnapshot(event, { mappings: [
+ *   { entityType: "Order", pointer: "/order", kind: "single", write: "replace" },
+ *   { entityType: "LineItem", pointer: "/order/items", kind: "collection" },
+ * ]});
+ * ```
+ */
+declare function applyAgUiSnapshot(event: AgUiStateSnapshotEvent, options: ApplyAgUiOptions): void;
+/**
+ * Apply an AG-UI STATE_DELTA (RFC-6902 JSON Patch) to the graph.
+ *
+ * The delta is applied against a reconstructed agent-state view assembled from
+ * the current graph entities (per the mappings), then the resulting slices are
+ * re-projected back into the graph. This lets path-based deltas target nested
+ * entity fields without the caller tracking the full agent state themselves.
+ */
+declare function applyAgUiDelta(event: AgUiStateDeltaEvent, options: ApplyAgUiOptions, 
+/** Current agent-state view; if omitted, reconstructed from the graph mappings. */
+currentState?: Record<string, unknown>): void;
+
+/**
+ * adapters/types.ts
+ *
+ * Common contract every data-source adapter implements.
+ * The entity graph doesn't care whether data comes from REST, GraphQL,
+ * WebSocket, Supabase, Convex, PGlite shape sync — they all speak this
+ * interface and write into the same graph.
+ */
+
+type ChangeOperation = "insert" | "update" | "delete" | "upsert";
+interface EntityChange<T = Record<string, unknown>> {
+    op: ChangeOperation;
+    type: EntityType;
+    id: EntityId;
+    data?: T;
+    patch?: Partial<T>;
+}
+interface ChangeSet<T = Record<string, unknown>> {
+    changes: EntityChange<T>[];
+    affectedListKeys?: string[];
+    timestamp?: string;
+}
+type UnsubscribeFn = () => void;
+interface SubscriptionConfig {
+    label?: string;
+    replayOnConnect?: boolean;
+}
+interface RealtimeAdapter {
+    readonly name: string;
+    subscribe(config: SubscriptionConfig, handler: (changeset: ChangeSet) => void): UnsubscribeFn;
+    onStatusChange?: (cb: (status: AdapterStatus) => void) => UnsubscribeFn;
+}
+type AdapterStatus = "connecting" | "connected" | "disconnected" | "error";
+interface SyncQueryResult<T> {
+    rows: T[];
+    total?: number;
+}
+interface SyncAdapter extends RealtimeAdapter {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<SyncQueryResult<T>>;
+    execute(sql: string, params?: unknown[]): Promise<void>;
+    isSynced(): boolean;
+    onSyncComplete(cb: () => void): UnsubscribeFn;
+}
+interface ChannelConfig {
+    type: EntityType;
+    filter?: Record<string, unknown>;
+    id?: EntityId;
+    operations?: ChangeOperation[];
+}
+
+interface ManagerOptions {
+    flushInterval?: number;
+    onStatusChange?: (adapter: string, status: AdapterStatus) => void;
+    onChangeReceived?: (adapter: string, change: EntityChange) => void;
+}
+declare class RealtimeManager {
+    private adapters;
+    private pendingChanges;
+    private pendingListKeys;
+    private flushTimer;
+    private opts;
+    constructor(opts?: ManagerOptions);
+    register(adapter: RealtimeAdapter, channels: ChannelConfig[], normalize?: (raw: unknown) => EntityChange | null): UnsubscribeFn;
+    unregister(name: string): void;
+    unregisterAll(): void;
+    private handleChangeset;
+    private scheduleFlush;
+    flush(): void;
+    forceFlush(): void;
+}
+declare function getRealtimeManager(opts?: ManagerOptions): RealtimeManager;
+declare function resetRealtimeManager(): void;
+
+/**
+ * adapters/realtime-adapters.ts
+ *
+ * WebSocket, Supabase Realtime, Convex, and GraphQL subscription adapters.
+ * All implement RealtimeAdapter and route through RealtimeManager → entity graph.
+ */
+
+interface WebSocketAdapterOptions {
+    url: string | (() => string);
+    parseMessage?: (data: unknown) => EntityChange[] | null;
+    protocols?: string | string[];
+    reconnectBaseDelay?: number;
+    maxReconnectAttempts?: number;
+    pingInterval?: number;
+    pingMessage?: string;
+}
+declare function createWebSocketAdapter(opts: WebSocketAdapterOptions): RealtimeAdapter;
+interface SupabaseClient {
+    channel(name: string): SupabaseChannel;
+}
+interface SupabaseChannel {
+    on(event: "postgres_changes", config: {
+        event: "*" | "INSERT" | "UPDATE" | "DELETE";
+        schema: string;
+        table: string;
+        filter?: string;
+    }, handler: (payload: SupabasePayload) => void): SupabaseChannel;
+    subscribe(cb?: (status: string) => void): SupabaseChannel;
+    unsubscribe(): Promise<void>;
+}
+interface SupabasePayload {
+    eventType: "INSERT" | "UPDATE" | "DELETE";
+    new: Record<string, unknown>;
+    old: Record<string, unknown>;
+    table: string;
+}
+interface SupabaseAdapterOptions {
+    tableTypeMap?: Record<string, string>;
+    extractId?: (record: Record<string, unknown>) => string;
+    schema?: string;
+}
+declare function createSupabaseRealtimeAdapter(client: SupabaseClient, opts?: SupabaseAdapterOptions): RealtimeAdapter & {
+    subscribeChannel: (config: ChannelConfig & {
+        _handler?: (cs: ChangeSet) => void;
+    }) => UnsubscribeFn;
+};
+interface ConvexClient {
+    onUpdate<T>(query: unknown, args: Record<string, unknown>, handler: (result: T) => void): UnsubscribeFn;
+}
+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 object>(opts: {
+    client: ConvexClient;
+    channels: ConvexChannelConfig<T>[];
+}): RealtimeAdapter;
+interface GQLWsClient {
+    subscribe<T>(payload: {
+        query: string;
+        variables?: Record<string, unknown>;
+    }, sink: {
+        next: (value: {
+            data: T;
+        }) => void;
+        error: (err: unknown) => void;
+        complete: () => void;
+    }): UnsubscribeFn;
+}
+interface GQLSubscriptionConfig<T extends object> {
+    type: string;
+    document: string;
+    variables?: Record<string, unknown>;
+    getPayload: (data: T) => GQLPayload | GQLPayload[] | null;
+}
+interface GQLPayload {
+    type?: string;
+    node?: Record<string, unknown>;
+    id?: string;
+}
+declare function createGraphQLSubscriptionAdapter<T extends object>(opts: {
+    client: GQLWsClient;
+    subscriptions: GQLSubscriptionConfig<T>[];
+    extractId?: (node: Record<string, unknown>, type: string) => string;
+    normalize?: (node: Record<string, unknown>, type: string) => Record<string, unknown>;
+}): RealtimeAdapter;
+
+/**
+ * adapters/surreal-live.ts
+ *
+ * SurrealDB LIVE SELECT realtime adapter.
+ *
+ *   SurrealDB live stream → per-channel state machine → RealtimeAdapter contract
+ *   one ChannelConfig = one LIVE SELECT = one independent reconnect/replay state
+ *
+ * Implements the RealtimeAdapter contract (NOT SyncAdapter) per the corrected
+ * spec at openspec/specs/entity-surreal-live-adapter/spec.md. The consumer
+ * owns the SurrealDB client; the adapter only orchestrates live queries.
+ */
+
+interface SurrealLike {
+    query<T = unknown>(sql: string, vars?: Record<string, unknown>): Promise<T[]>;
+    live<T = unknown>(table: string, callback: (action: SurrealLiveAction<T>) => void, diff?: boolean): Promise<string>;
+    kill(uuid: string): Promise<void>;
+}
+interface SurrealLiveAction<T = unknown> {
+    action: "CREATE" | "UPDATE" | "DELETE" | "CLOSE" | string;
+    result: T;
+}
+interface SurrealCheckpointStore {
+    get(channelKey: string): Promise<string | undefined>;
+    set(channelKey: string, value: string): Promise<void>;
+}
+interface SurrealTableConfig {
+    type: EntityType;
+    /** SurrealDB table name; defaults to `type`. */
+    table?: string;
+    /** Field in the row that carries the entity id; defaults to "id". */
+    idField?: string;
+}
+interface SurrealLiveAdapterOptions {
+    name?: string;
+    surreal: SurrealLike;
+    tables: SurrealTableConfig[];
+    initialQueryStrategy?: "select-then-live" | "live-only";
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    connectedSettleMs?: number;
+    checkpointStore?: SurrealCheckpointStore;
+    checkpointField?: string;
+    listKeyResolver?: (change: EntityChange) => string[] | undefined;
+    permanentErrorPatterns?: RegExp[];
+}
+declare function createSurrealLiveAdapter(opts: SurrealLiveAdapterOptions): RealtimeAdapter;
+
+/**
+ * adapters/flint.ts — Flint Realtime Fabric adapter.
+ *
+ *   Flint frf-entity-management `watchEntities()` AsyncIterable
+ *     → our ChangeSet stream → RealtimeManager → entity graph
+ *
+ * GAP-1 is a BRIDGE, not a from-scratch build: the Flint repo already ships
+ * `@prometheusags/frf-entity-management` whose `RealtimeAdapter.watchEntities()`
+ * yields a plain `EntityEvent` (it JSON-decodes the spine envelope — no proto
+ * types leak). We consume that entity-shaped facade behind a minimal-surface
+ * type, so:
+ *   - The unfrozen `proto-v1` risk is contained BELOW this seam.
+ *   - `@prometheusags/frf-sdk` stays an OPTIONAL peer; this module imports
+ *     nothing from it. The consumer constructs the Flint client and passes it in.
+ *
+ * `EntityEvent.offset` (bigint) is forwarded to an optional checkpoint store so
+ * reconnects resume from the last seen offset (mirrors the surreal-live adapter).
+ */
+
+/** A decoded entity change event received from the Flint spine. */
+interface FlintEntityEvent {
+    entityType: string;
+    entityId: string;
+    tenantId: string;
+    channelId: string;
+    data: Record<string, unknown>;
+    offset: bigint;
+    correlationId?: string;
+}
+/** Filter criteria for a Flint entity subscription. */
+interface FlintEntityQuery {
+    channelId: string;
+    consumerId: string;
+    entityType?: string;
+    fromOffset?: bigint;
+}
+/** An entity mutation to publish on the Flint spine. */
+interface FlintEntityRecord {
+    entityType: string;
+    entityId: string;
+    tenantId: string;
+    channelId: string;
+    data: Record<string, unknown>;
+    correlationId?: string;
+}
+/** Minimal surface of the Flint `RealtimeAdapter` we consume. */
+interface FlintClientLike {
+    watchEntities(query: FlintEntityQuery): AsyncIterable<FlintEntityEvent>;
+    mutateEntity(record: FlintEntityRecord): Promise<void>;
+}
+/** Optional resume-offset persistence (per channel+consumer). */
+interface FlintCheckpointStore {
+    get(key: string): Promise<bigint | undefined> | bigint | undefined;
+    set(key: string, offset: bigint): Promise<void> | void;
+}
+interface CreateFlintAdapterOptions {
+    name?: string;
+    /** The Flint entity-management client (frf-entity-management RealtimeAdapter). */
+    client: FlintClientLike;
+    /** Channel to subscribe/publish on. */
+    channelId: string;
+    /** Consumer id for this subscription. */
+    consumerId: string;
+    /** Restrict to one entity type (optional). */
+    entityType?: string;
+    /** Resume-offset store; reconnects start `fromOffset = lastSeen + 1`. */
+    checkpoints?: FlintCheckpointStore;
+    /** Map a Flint event to a change operation. Defaults to "upsert". */
+    resolveOp?: (event: FlintEntityEvent) => ChangeOperation;
+}
+/**
+ * Build a {@link RealtimeAdapter} backed by the Flint Realtime Fabric.
+ *
+ * The consumer owns the Flint client (constructed from `@prometheusags/frf-sdk`
+ * / `frf-entity-management`); this adapter only orchestrates the stream.
+ *
+ * @example
+ * ```ts
+ * import { RealtimeAdapter as FrfAdapter } from "@prometheusags/frf-entity-management";
+ * import { getRealtimeManager, createFlintAdapter } from "@prometheus-ags/prometheus-entity-management";
+ *
+ * const flint = new FrfAdapter(spineClient);
+ * const adapter = createFlintAdapter({ client: flint, channelId: "tenant-1", consumerId: "web-1" });
+ * getRealtimeManager().register(adapter);
+ * ```
+ */
+declare function createFlintAdapter(options: CreateFlintAdapterOptions): RealtimeAdapter;
+/**
+ * Publish an entity mutation to the Flint spine via the client.
+ * Thin pass-through kept here so consumers import one Flint surface from us.
+ */
+declare function publishFlintMutation(client: FlintClientLike, record: FlintEntityRecord): Promise<void>;
+
+/**
+ * adapters/electricsql.ts (core)
+ *
+ * ElectricSQL + PGlite local-first adapter — the React-free base.
+ *
+ * Server Postgres → ElectricSQL shape sync (SSE) → PGlite (local WASM Postgres)
+ *                                                        ↓ NOTIFY
+ *                                                   Entity Graph (Zustand)
+ *
+ * React hooks (`useLocalFirst`, `usePGliteQuery`) live in the binding package
+ * (`@prometheus-ags/entity-graph-react`), built on this adapter.
+ */
+
+interface PGlite$1 {
+    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$1<T = Record<string, unknown>> {
+    headers: {
+        operation: "insert" | "update" | "delete";
+    };
+    offset: string;
+    value: T;
+    key: string;
+}
+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 object> {
+    type: EntityType;
+    table: string;
+    where?: string;
+    idColumn?: string;
+    normalize?: (row: T) => Record<string, unknown>;
+    shapeStream: ShapeStream$1<T>;
+}
+interface ElectricAdapterOptions {
+    pglite: PGlite$1;
+    tables: ElectricTableConfig<Record<string, unknown>>[];
+    onSynced?: () => void;
+}
+
+declare function createElectricAdapter(opts: ElectricAdapterOptions): SyncAdapter;
+
+/**
+ * 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>;
+
+/**
+ * adapters/tauri-sql-persistence.ts
+ *
+ * SQLite-backed implementation of {@link GraphPersistenceAdapter} for Tauri
+ * desktop, via the official `@tauri-apps/plugin-sql` `Database` handle.
+ *
+ * Why this exists:
+ *   - On Tauri desktop the natural on-device store is SQLite, not PGlite-wasm.
+ *   - This pairs with `createPGlitePersistenceAdapter` (browser/wasm) so the
+ *     same local-first runtime persists across web and desktop unchanged.
+ *
+ * The consumer owns the Tauri `Database` handle (from `Database.load(...)`).
+ * This module does NOT import `@tauri-apps/plugin-sql` — it takes a
+ * minimal-surface client, mirroring the PGlite/Electric adapter pattern, so it
+ * adds no hard dependency. `@tauri-apps/plugin-sql` is an optional peer.
+ *
+ * Contract (same as every GraphPersistenceAdapter):
+ *   - `get(key)`    -> stored string or null
+ *   - `set(key, v)` -> upsert (INSERT ... ON CONFLICT)
+ *   - `remove(key)` -> delete (no-op if absent)
+ *
+ * Tauri SQL uses SQLite `?`-positional bind params (not `$1`).
+ */
+
+/**
+ * Minimal surface of a `@tauri-apps/plugin-sql` `Database` handle.
+ * Avoids a hard dep; matches the loaded-Database shape (`execute` + `select`).
+ */
+interface TauriSqlClient {
+    execute(query: string, bindValues?: unknown[]): Promise<unknown>;
+    select<T = Record<string, unknown>>(query: string, bindValues?: unknown[]): Promise<T[]>;
+}
+interface CreateTauriSqlPersistenceAdapterOptions {
+    /** Name of the snapshot table. Defaults to `_graph_snapshot`. */
+    tableName?: string;
+}
+/**
+ * Returns a {@link GraphPersistenceAdapter} backed by a Tauri SQLite `Database`.
+ *
+ * @example
+ * ```ts
+ * import Database from "@tauri-apps/plugin-sql";
+ * import { startLocalFirstGraph, createTauriSqlPersistenceAdapter } from "@prometheus-ags/prometheus-entity-management";
+ *
+ * const db = await Database.load("sqlite:app.db");
+ * const storage = await createTauriSqlPersistenceAdapter(db);
+ * const runtime = startLocalFirstGraph({ storage, key: "app:graph" });
+ * ```
+ */
+declare function createTauriSqlPersistenceAdapter(db: TauriSqlClient, options?: CreateTauriSqlPersistenceAdapterOptions): 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/types.ts
+ *
+ * Pure table engine type definitions — zero external dependencies.
+ * Structurally compatible with TanStack Table v8 for easy migration,
+ * but fully self-contained within the prometheus-entity-management library.
+ */
+
+type ViewMode = "table" | "gallery" | "list";
+type Updater<T> = T | ((prev: T) => T);
+type AccessorFn<TData, TValue = unknown> = (row: TData, index: number) => TValue;
+type HeaderContext<TData> = {
+    table: TableInstance<TData>;
+    header: Header<TData>;
+    column: Column<TData>;
+};
+type CellContext<TData> = {
+    table: TableInstance<TData>;
+    row: Row<TData>;
+    cell: Cell<TData>;
+    column: Column<TData>;
+    getValue: <T = unknown>() => T;
+    renderValue: <T = unknown>() => T | null;
+};
+type HeaderRenderer<TData> = string | ((context: HeaderContext<TData>) => React.ReactNode);
+type CellRenderer<TData> = string | ((context: CellContext<TData>) => React.ReactNode);
+type FilterFn<TData> = (row: Row<TData>, columnId: string, filterValue: unknown) => boolean;
+type SortingFn<TData> = (rowA: Row<TData>, rowB: Row<TData>, columnId: string) => number;
+type AggregationFn<TData> = (columnId: string, leafRows: Row<TData>[], childRows: Row<TData>[]) => unknown;
+interface ColumnMeta<TData = unknown> {
+    entityMeta?: {
+        field: keyof TData;
+        filterType: "text" | "number" | "date" | "dateRange" | "boolean" | "enum" | "relation" | "none";
+        enumOptions?: Array<{
+            label: string;
+            value: string;
+            color?: string;
+        }>;
+        relationEntityType?: string;
+        editable?: boolean;
+        hideable?: boolean;
+    };
+    [key: string]: unknown;
+}
+interface ColumnDef<TData, TValue = unknown> {
+    id?: string;
+    accessorKey?: keyof TData & string;
+    accessorFn?: AccessorFn<TData, TValue>;
+    header?: HeaderRenderer<TData>;
+    cell?: CellRenderer<TData>;
+    footer?: HeaderRenderer<TData>;
+    size?: number;
+    minSize?: number;
+    maxSize?: number;
+    enableSorting?: boolean;
+    enableFiltering?: boolean;
+    enableHiding?: boolean;
+    enablePinning?: boolean;
+    enableGrouping?: boolean;
+    enableResizing?: boolean;
+    filterFn?: FilterFn<TData> | "auto";
+    sortingFn?: SortingFn<TData> | "auto";
+    aggregationFn?: AggregationFn<TData> | "auto" | "sum" | "min" | "max" | "count" | "mean" | "median" | "unique";
+    sortDescFirst?: boolean;
+    sortUndefined?: "first" | "last" | false;
+    invertSorting?: boolean;
+    meta?: ColumnMeta<TData>;
+    columns?: ColumnDef<TData, unknown>[];
+}
+interface SortingColumn {
+    id: string;
+    desc: boolean;
+}
+type SortingState = SortingColumn[];
+interface ColumnFilter {
+    id: string;
+    value: unknown;
+}
+type ColumnFiltersState = ColumnFilter[];
+type RowSelectionState = Record<string, boolean>;
+type ColumnVisibilityState = Record<string, boolean>;
+type ColumnOrderState = string[];
+interface ColumnPinningState {
+    left?: string[];
+    right?: string[];
+}
+type ColumnSizingState = Record<string, number>;
+type ColumnSizingInfoState = {
+    startOffset: number | null;
+    startSize: number | null;
+    deltaOffset: number | null;
+    deltaPercentage: number | null;
+    isResizingColumn: string | false;
+    columnSizingStart: [string, number][];
+};
+type ExpandedState = Record<string, boolean> | true;
+type GroupingState = string[];
+interface PaginationState {
+    pageIndex: number;
+    pageSize: number;
+}
+interface TableState {
+    sorting: SortingState;
+    columnFilters: ColumnFiltersState;
+    globalFilter: unknown;
+    rowSelection: RowSelectionState;
+    columnVisibility: ColumnVisibilityState;
+    columnOrder: ColumnOrderState;
+    columnPinning: ColumnPinningState;
+    columnSizing: ColumnSizingState;
+    columnSizingInfo: ColumnSizingInfoState;
+    expanded: ExpandedState;
+    grouping: GroupingState;
+    pagination: PaginationState;
+}
+interface Row<TData> {
+    id: string;
+    index: number;
+    original: TData;
+    depth: number;
+    parentId?: string;
+    subRows: Row<TData>[];
+    getValue: <T = unknown>(columnId: string) => T;
+    renderValue: <T = unknown>(columnId: string) => T | null;
+    getIsSelected: () => boolean;
+    getCanSelect: () => boolean;
+    getIsAllSubRowsSelected: () => boolean;
+    getIsSomeSelected: () => boolean;
+    toggleSelected: (value?: boolean) => void;
+    getToggleSelectedHandler: () => (e: unknown) => void;
+    getIsExpanded: () => boolean;
+    getCanExpand: () => boolean;
+    toggleExpanded: (value?: boolean) => void;
+    getToggleExpandedHandler: () => () => void;
+    getIsGrouped: () => boolean;
+    groupingColumnId?: string;
+    groupingValue?: unknown;
+    getVisibleCells: () => Cell<TData>[];
+    getAllCells: () => Cell<TData>[];
+    getIsPinned: () => "top" | "bottom" | false;
+    pin: (position: "top" | "bottom" | false) => void;
+}
+interface Cell<TData> {
+    id: string;
+    row: Row<TData>;
+    column: Column<TData>;
+    getValue: <T = unknown>() => T;
+    renderValue: <T = unknown>() => T | null;
+    getIsGrouped: () => boolean;
+    getIsPlaceholder: () => boolean;
+    getIsAggregated: () => boolean;
+    getContext: () => CellContext<TData>;
+}
+interface Header<TData> {
+    id: string;
+    index: number;
+    depth: number;
+    column: Column<TData>;
+    isPlaceholder: boolean;
+    placeholderId?: string;
+    subHeaders: Header<TData>[];
+    colSpan: number;
+    rowSpan: number;
+    getSize: () => number;
+    getStart: () => number;
+    getContext: () => HeaderContext<TData>;
+    getResizeHandler: () => (event: unknown) => void;
+    getLeafHeaders: () => Header<TData>[];
+}
+interface HeaderGroup<TData> {
+    id: string;
+    depth: number;
+    headers: Header<TData>[];
+}
+interface Column<TData> {
+    id: string;
+    depth: number;
+    columnDef: ColumnDef<TData>;
+    columns: Column<TData>[];
+    parent?: Column<TData>;
+    getFlatColumns: () => Column<TData>[];
+    getLeafColumns: () => Column<TData>[];
+    getIsSorted: () => false | "asc" | "desc";
+    getNextSortingOrder: () => "asc" | "desc" | false;
+    getCanSort: () => boolean;
+    toggleSorting: (desc?: boolean, isMulti?: boolean) => void;
+    clearSorting: () => void;
+    getSortIndex: () => number;
+    getAutoSortingFn: () => SortingFn<TData>;
+    getAutoSortDir: () => "asc" | "desc";
+    getIsFiltered: () => boolean;
+    getFilterValue: () => unknown;
+    setFilterValue: (value: unknown) => void;
+    getCanFilter: () => boolean;
+    getAutoFilterFn: () => FilterFn<TData> | undefined;
+    getIsVisible: () => boolean;
+    toggleVisibility: (value?: boolean) => void;
+    getCanHide: () => boolean;
+    getIsPinned: () => "left" | "right" | false;
+    pin: (position: "left" | "right" | false) => void;
+    getCanPin: () => boolean;
+    getIsGrouped: () => boolean;
+    toggleGrouping: () => void;
+    getCanGroup: () => boolean;
+    getGroupedIndex: () => number;
+    getSize: () => number;
+    getStart: (position?: "left" | "center" | "right") => number;
+    getCanResize: () => boolean;
+    resetSize: () => void;
+    getIndex: (position?: "left" | "center" | "right") => number;
+}
+interface RowModel<TData> {
+    rows: Row<TData>[];
+    flatRows: Row<TData>[];
+    rowsById: Record<string, Row<TData>>;
+}
+interface TableOptions<TData> {
+    data: TData[];
+    columns: ColumnDef<TData>[];
+    getRowId?: (row: TData, index: number, parent?: Row<TData>) => string;
+    defaultColumn?: Partial<ColumnDef<TData>>;
+    /** Seed the initial value for any internal state slice without making it controlled. */
+    initialState?: Partial<TableState>;
+    /** Fully controlled state — every key provided here locks that slice and must be updated externally. */
+    state?: Partial<TableState>;
+    onStateChange?: (updater: Updater<TableState>) => void;
+    manualSorting?: boolean;
+    enableSorting?: boolean;
+    enableMultiSort?: boolean;
+    enableSortingRemoval?: boolean;
+    enableMultiRemove?: boolean;
+    maxMultiSortColCount?: number;
+    sortDescFirst?: boolean;
+    onSortingChange?: (updater: Updater<SortingState>) => void;
+    manualFiltering?: boolean;
+    enableFiltering?: boolean;
+    enableColumnFilters?: boolean;
+    enableGlobalFilter?: boolean;
+    globalFilterFn?: FilterFn<TData>;
+    onColumnFiltersChange?: (updater: Updater<ColumnFiltersState>) => void;
+    onGlobalFilterChange?: (updater: Updater<unknown>) => void;
+    manualPagination?: boolean;
+    pageCount?: number;
+    autoResetPageIndex?: boolean;
+    onPaginationChange?: (updater: Updater<PaginationState>) => void;
+    enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
+    enableMultiRowSelection?: boolean | ((row: Row<TData>) => boolean);
+    enableSubRowSelection?: boolean | ((row: Row<TData>) => boolean);
+    onRowSelectionChange?: (updater: Updater<RowSelectionState>) => void;
+    enableHiding?: boolean;
+    onColumnVisibilityChange?: (updater: Updater<ColumnVisibilityState>) => void;
+    onColumnOrderChange?: (updater: Updater<ColumnOrderState>) => void;
+    enablePinning?: boolean;
+    onColumnPinningChange?: (updater: Updater<ColumnPinningState>) => void;
+    enableColumnResizing?: boolean;
+    columnResizeMode?: "onChange" | "onEnd";
+    columnResizeDirection?: "ltr" | "rtl";
+    onColumnSizingChange?: (updater: Updater<ColumnSizingState>) => void;
+    onColumnSizingInfoChange?: (updater: Updater<ColumnSizingInfoState>) => void;
+    manualGrouping?: boolean;
+    enableGrouping?: boolean;
+    onGroupingChange?: (updater: Updater<GroupingState>) => void;
+    manualExpanding?: boolean;
+    enableExpanding?: boolean;
+    getSubRows?: (row: TData, index: number) => TData[] | undefined;
+    getIsRowExpanded?: (row: Row<TData>) => boolean;
+    onExpandedChange?: (updater: Updater<ExpandedState>) => void;
+    paginateExpandedRows?: boolean;
+    enableRowPinning?: boolean | ((row: Row<TData>) => boolean);
+    keepPinnedRows?: boolean;
+    onRowPinningChange?: (updater: Updater<Record<string, "top" | "bottom">>) => void;
+}
+interface TableInstance<TData> {
+    options: TableOptions<TData>;
+    getState: () => TableState;
+    setState: (updater: Updater<TableState>) => void;
+    reset: () => void;
+    getAllColumns: () => Column<TData>[];
+    getAllFlatColumns: () => Column<TData>[];
+    getAllLeafColumns: () => Column<TData>[];
+    getColumn: (id: string) => Column<TData> | undefined;
+    getHeaderGroups: () => HeaderGroup<TData>[];
+    getLeftHeaderGroups: () => HeaderGroup<TData>[];
+    getCenterHeaderGroups: () => HeaderGroup<TData>[];
+    getRightHeaderGroups: () => HeaderGroup<TData>[];
+    getFooterGroups: () => HeaderGroup<TData>[];
+    getCoreRowModel: () => RowModel<TData>;
+    getRowModel: () => RowModel<TData>;
+    getPreFilteredRowModel: () => RowModel<TData>;
+    getFilteredRowModel: () => RowModel<TData>;
+    getPreSortedRowModel: () => RowModel<TData>;
+    getSortedRowModel: () => RowModel<TData>;
+    getGroupedRowModel: () => RowModel<TData>;
+    getExpandedRowModel: () => RowModel<TData>;
+    getPrePaginationRowModel: () => RowModel<TData>;
+    getPaginationRowModel: () => RowModel<TData>;
+    getSelectedRowModel: () => RowModel<TData>;
+    getRow: (id: string) => Row<TData>;
+    setSorting: (updater: Updater<SortingState>) => void;
+    resetSorting: (defaultState?: boolean) => void;
+    setColumnFilters: (updater: Updater<ColumnFiltersState>) => void;
+    resetColumnFilters: (defaultState?: boolean) => void;
+    setGlobalFilter: (value: unknown) => void;
+    resetGlobalFilter: (defaultState?: boolean) => void;
+    setPageIndex: (updater: Updater<number>) => void;
+    resetPageIndex: (defaultState?: boolean) => void;
+    setPageSize: (updater: Updater<number>) => void;
+    resetPageSize: (defaultState?: boolean) => void;
+    getPageCount: () => number;
+    getCanPreviousPage: () => boolean;
+    getCanNextPage: () => boolean;
+    previousPage: () => void;
+    nextPage: () => void;
+    firstPage: () => void;
+    lastPage: () => void;
+    setRowSelection: (updater: Updater<RowSelectionState>) => void;
+    resetRowSelection: (defaultState?: boolean) => void;
+    toggleAllRowsSelected: (value?: boolean) => void;
+    toggleAllPageRowsSelected: (value?: boolean) => void;
+    getIsAllRowsSelected: () => boolean;
+    getIsAllPageRowsSelected: () => boolean;
+    getIsSomeRowsSelected: () => boolean;
+    getIsSomePageRowsSelected: () => boolean;
+    getToggleAllRowsSelectedHandler: () => (e: unknown) => void;
+    getToggleAllPageRowsSelectedHandler: () => (e: unknown) => void;
+    setColumnVisibility: (updater: Updater<ColumnVisibilityState>) => void;
+    resetColumnVisibility: (defaultState?: boolean) => void;
+    toggleAllColumnsVisible: (value?: boolean) => void;
+    getIsAllColumnsVisible: () => boolean;
+    getIsSomeColumnsVisible: () => boolean;
+    getToggleAllColumnsVisibilityHandler: () => (e: unknown) => void;
+    getVisibleFlatColumns: () => Column<TData>[];
+    getVisibleLeafColumns: () => Column<TData>[];
+    setColumnOrder: (updater: Updater<ColumnOrderState>) => void;
+    resetColumnOrder: (defaultState?: boolean) => void;
+    setColumnPinning: (updater: Updater<ColumnPinningState>) => void;
+    resetColumnPinning: (defaultState?: boolean) => void;
+    getLeftFlatColumns: () => Column<TData>[];
+    getRightFlatColumns: () => Column<TData>[];
+    getCenterFlatColumns: () => Column<TData>[];
+    getLeftLeafColumns: () => Column<TData>[];
+    getRightLeafColumns: () => Column<TData>[];
+    getCenterLeafColumns: () => Column<TData>[];
+    setColumnSizing: (updater: Updater<ColumnSizingState>) => void;
+    setColumnSizingInfo: (updater: Updater<ColumnSizingInfoState>) => void;
+    resetColumnSizing: (defaultState?: boolean) => void;
+    setGrouping: (updater: Updater<GroupingState>) => void;
+    resetGrouping: (defaultState?: boolean) => void;
+    setExpanded: (updater: Updater<ExpandedState>) => void;
+    resetExpanded: (defaultState?: boolean) => void;
+    toggleAllRowsExpanded: (expanded?: boolean) => void;
+    getIsAllRowsExpanded: () => boolean;
+    getIsSomeRowsExpanded: () => boolean;
+    getCanSomeRowsExpand: () => boolean;
+    getExpandedDepth: () => number;
+}
+interface ActionDef<TData> {
+    id: string;
+    label: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    onClick: (item: TData) => void;
+    destructive?: boolean;
+    hidden?: (item: TData) => boolean;
+    disabled?: (item: TData) => boolean;
+    confirm?: string | ((item: TData) => string);
+    variant?: "primary" | "default" | "ghost" | "destructive";
+}
+interface ItemDescriptorBadge<TData> {
+    field: keyof TData & string;
+    options?: Array<{
+        value: string;
+        label: string;
+        className?: string;
+    }>;
+}
+interface ItemDescriptorMeta<TData> {
+    field: keyof TData & string;
+    label: string;
+    format?: (value: unknown) => string;
+}
+interface ItemDescriptor<TData> {
+    title: keyof TData & string;
+    subtitle?: keyof TData & string;
+    image?: keyof TData & string;
+    icon?: (keyof TData & string) | React.ComponentType<{
+        className?: string;
+    }>;
+    avatar?: keyof TData & string;
+    badges?: ItemDescriptorBadge<TData>[];
+    metadata?: ItemDescriptorMeta<TData>[];
+    description?: keyof TData & string;
+}
+interface ItemRenderContext<TData> {
+    isSelected: boolean;
+    isEditing: boolean;
+    isMultiSelectMode: boolean;
+    onToggleSelect: () => void;
+    onEdit: () => void;
+    onSave: (changes: Partial<TData>) => void;
+    onCancel: () => void;
+    actions: ActionDef<TData>[];
+    row: Row<TData>;
+}
+interface EmptyStateConfig {
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    title?: string;
+    description?: string;
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    filteredTitle?: string;
+    filteredDescription?: string;
+    filteredAction?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+interface BatchActionDef {
+    id: string;
+    label: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    destructive?: boolean;
+}
+interface GalleryColumns {
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+}
+
+/**
+ * table/row-models.ts
+ *
+ * Pure row model pipeline functions. Each stage transforms data
+ * into a RowModel — no side effects, no external dependencies.
+ */
+
+declare function createRow<TData>(original: TData, index: number, columns: Column<TData>[], table: TableInstance<TData>, depth?: number, parentId?: string, subRows?: Row<TData>[]): Row<TData>;
+declare function getCoreRowModel<TData>(data: TData[], columns: Column<TData>[], table: TableInstance<TData>): RowModel<TData>;
+declare function getFilteredRowModel<TData>(rowModel: RowModel<TData>, columnFilters: ColumnFiltersState, globalFilter: unknown, columns: Column<TData>[], globalFilterFn?: FilterFn<TData>): RowModel<TData>;
+declare function getSortedRowModel<TData>(rowModel: RowModel<TData>, sorting: SortingState, columns: Column<TData>[]): RowModel<TData>;
+declare function getGroupedRowModel<TData>(rowModel: RowModel<TData>, grouping: GroupingState, columns: Column<TData>[], table: TableInstance<TData>): RowModel<TData>;
+declare function getExpandedRowModel<TData>(rowModel: RowModel<TData>, expanded: ExpandedState): RowModel<TData>;
+declare function getPaginatedRowModel<TData>(rowModel: RowModel<TData>, pagination: PaginationState): RowModel<TData>;
+declare function getSelectedRowModel<TData>(rowModel: RowModel<TData>, selection: Record<string, boolean>): RowModel<TData>;
+
+/**
+ * table/faceting.ts
+ *
+ * Column faceting utilities — compute unique values, counts,
+ * and min/max for filter UI controls.
+ */
+
+/**
+ * Compute unique values and their counts for a given column.
+ * Useful for rendering filter dropdown options with hit counts.
+ */
+declare function getFacetedUniqueValues<TData>(rowModel: RowModel<TData>, columnId: string): Map<unknown, number>;
+/**
+ * Compute min and max numeric values for a given column.
+ * Returns [min, max] or undefined if no numeric values exist.
+ */
+declare function getFacetedMinMaxValues<TData>(rowModel: RowModel<TData>, columnId: string): [number, number] | undefined;
+/**
+ * Get a filtered row model scoped to a single column's facet.
+ * Returns a row model that excludes the given column's own filter,
+ * so the facet counts reflect what would be available if that
+ * specific filter were removed.
+ */
+declare function getFacetedRowModel<TData>(preFilteredRowModel: RowModel<TData>, columnId: string, allFilteredRowModel: RowModel<TData>): RowModel<TData>;
+
+export { type AccessorFn, type ActionDef, type AdapterStatus, type AgUiStateDeltaEvent, type AgUiStateMapping, type AgUiStateSnapshotEvent, type AggregationFn, type ApplyAgUiOptions, type BatchActionDef, type BelongsToRelation, type CascadeContext, type Cell, type CellContext, type CellRenderer, type ChangeEvent, type ChangeOp, type ChangeOperation, type ChangeSet, type ChannelConfig, type Column, type ColumnDef, type ColumnFiltersState, type ColumnMeta, type ColumnOrderState, type ColumnPinningState, type ColumnSizingInfoState, type ColumnSizingState, type ColumnVisibilityState, type CompletenessMode, type CreateFlintAdapterOptions, type CreatePGlitePersistenceAdapterOptions, type CreateTauriSqlPersistenceAdapterOptions, type DevtoolsEvent, type DevtoolsEventBus, type DevtoolsEventBusOptions, type DevtoolsSourceFn, EMPTY_ENTITY_STATE, EMPTY_IDS, EMPTY_LIST_STATE, EMPTY_SYNC_METADATA, type ElectricAdapterOptions, type ElectricTableConfig, type EmptyStateConfig, type EngineOptions, type EntityChange, type EntityError, type EntityErrorOptions, type EntityId, type EntityJsonSchemaConfig, type EntityQueryOptions, type EntitySchema, type EntitySnapshot, type EntityState, type EntitySyncMetadata, type EntityTransport, type EntityType, type ExpandedState, type FilterClause, type FilterFn, type FilterGroup, type FilterOperator, type FilterSpec, type FlintCheckpointStore, type FlintClientLike, type FlintEntityEvent, type FlintEntityQuery, type FlintEntityRecord, type GalleryColumns, type GetEntityJsonSchemaOptions, 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, IncrementalView, type IncrementalViewOptions, type ItemDescriptor, type ItemDescriptorBadge, type ItemDescriptorMeta, type ItemRenderContext, type JsonPatchOp, type JsonSchemaObject, type ListFetchParams, type ListQuery, type ListQueryOptions, type ListResponse, type ListResult, type ListState, type LocalFirstGraphRuntime, type MakeRestTransportOptions, type ManagerOptions, type ManyToManyRelation, type MergeContext, type MergeStrategy, type PGlitePersistenceClient, type PaginationState, type ColumnDef as PureColumnDef, type ColumnMeta as PureColumnMeta, type QueryKey, type RealtimeAdapter, RealtimeManager, type RegisterEntityFromSqlOptions, type RegisteredStore, type RelationDescriptor, type ReplayRetryPolicy, type Row, type RowModel, type RowSelectionState, type SchemaGraphToolContext, type SortClause, type SortDirection, type SortSpec, type SortingFn, type SortingState, type StartLocalFirstGraphOptions, type SubscriptionConfig, type SupabaseAdapterOptions, type SupabaseLike, type SupabaseQueryBuilderLike, type SurrealCheckpointStore, type SurrealLike, type SurrealLiveAction, type SurrealLiveAdapterOptions, type SurrealTableConfig, type SyncAdapter, type SyncOrigin, type TableInstance, type TableOptions, type TableState, type TauriSqlClient, type TenantClaim, type TenantScopedAdapterOptions, type TenantScopedTableConfig, TerminalError, type TimeTravelSnapshot, type TimeTravelState, TransientError, type UnsubscribeFn, type Updater, type ViewDescriptor, type ViewMode, type WebSocketAdapterOptions, __resetEntityTransports, __resetStoreRegistry, applyAgUiDelta, applyAgUiSnapshot, applyJsonPatch, applyView, attachGlobalListeners, buildTenantWhere, cascadeInvalidation, checkCompleteness, collectDirtyPaths, compareEntities, configureEngine, configureTimeTravel, createConvexAdapter, createDevtoolsEventBus, createElectricAdapter, createFlintAdapter, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphTool, createGraphTransaction, createLoroMergeStrategy, createPGlitePersistenceAdapter, createRow, createSchemaGraphTool, createSupabaseRealtimeAdapter, createSurrealLiveAdapter, createTauriSqlPersistenceAdapter, createTenantScopedElectricAdapter, createWebSocketAdapter, dedupe, escapeHtml, exportGraphSnapshot, exportGraphSnapshotWithSchemas, fetchEntity, fetchList, findInsertionIndex, flattenClauses, getActiveSubscriberCount, getCoreRowModel, getRealtimeManager as getElectricRealtimeManager, getEngineOptions, getEntityJsonSchema, getEntityTransport, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGroupedRowModel, getMergeStrategy, getPaginatedRowModel, getRealtimeManager, getRegisteredEntityTypes, getRegisteredStores, getSchema, getSelectedRowModel, getSortedRowModel, getTimeTravelState, getValueAtPath, hasCustomPredicates, hasMergeStrategy, humanizeFieldName, hydrateGraphFromStorage, inferSchemaFieldType, lwwStrategy, makeRestTransport, matchesFilter, matchesSearch, parseCreateTable, persistGraphToStorage, publishFlintMutation, queryOnce, readRelations, recordGraphSnapshot, registerEntityFromSql, registerEntityJsonSchema, registerEntityTransport, registerMergeStrategy, registerRuntimeSchema, registerSchema, registerStore, registerSubscriber, registryKey, renderMarkdownToHtml, replayActionWithRetry, resetRealtimeManager, restoreGraphSnapshot, restoreGraphSnapshotBySeq, selectGraph, serializeKey, setDefaultMergeStrategy, setValueAtPath, sqlTypeToJsonSchema, startGarbageCollector, startLocalFirstGraph, stepTimeTravel, stopGarbageCollector, subscribeDevtoolsEvent, subscribeSubscriberStats, subscribeTimeTravel, toEntityError, toGraphQLVariables, toPrismaOrderBy, toPrismaWhere, toRestParams, toSQLClauses, unregisterSubscriber, useGraphStore, useGraphSyncStatus };