@prometheus-ags/entity-graph-core 3.2.0 → 4.0.0

package/dist/graph-ClW3HD8B.d.cts

@@ -1,990 +0,0 @@
-import * as zustand_vanilla from 'zustand/vanilla';
-
-/**
- * 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;
-
-/**
- * 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;
-
-/** 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;
-}
-/** Pagination and lifecycle metadata accepted by successful list writes. */
-type ListResultMeta = Partial<Omit<ListState, "ids" | "isFetching" | "isFetchingMore" | "error" | "stale">>;
-/** One list projection updated as part of an atomic fetched-list ingestion. */
-interface FetchedListTarget {
-    key: QueryKey;
-    mode?: "replace" | "append";
-    meta?: ListResultMeta;
-    /** Override list membership when the transport derives ids separately. */
-    ids?: EntityId[];
-}
-/** Additional normalized entity rows committed with the primary fetched list. */
-interface FetchedEntityBatch {
-    type: EntityType;
-    entries: Array<{
-        id: EntityId;
-        data: Record<string, unknown>;
-    }>;
-}
-/** Incrementally project fetched rows into an existing view-backed list. */
-interface FetchedListProjection {
-    key: QueryKey;
-    view: ViewDescriptor;
-    /** Complete the projection's fetch lifecycle without replacing its ids. */
-    completeFetch?: boolean;
-}
-/** Additional graph projections completed by one fetched-list response. */
-interface IngestFetchedListOptions {
-    lists?: FetchedListTarget[];
-    /** Side-descriptor rows that must commit or fail with the primary batch. */
-    sideBatches?: FetchedEntityBatch[];
-    /** View-backed lists that receive matching fetched ids in the same publication. */
-    projections?: FetchedListProjection[];
-    /** List fetch flags to clear without replacing their existing ids or metadata. */
-    finishListFetches?: QueryKey[];
-}
-/**
- * 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).
- * Framework bindings subscribe to the vanilla store; stores, adapters, and
- * engines can read it synchronously through `graphStore.getState()`.
- */
-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;
-    /**
-     * Merge one fetched page, mark every row fetched, and update its list
-     * projections in one Zustand publication.
-     */
-    ingestFetchedList: (type: EntityType, entries: Array<{
-        id: EntityId;
-        data: Record<string, unknown>;
-    }>, options?: IngestFetchedListOptions) => 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;
-}
-/** Creates an isolated, framework-neutral entity graph store. */
-declare function createGraphStore(): Omit<Omit<zustand_vanilla.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;
-        ingestFetchedList: (type: EntityType, entries: Array<{
-            id: EntityId;
-            data: Record<string, unknown>;
-        }>, options?: IngestFetchedListOptions) => 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;
-        ingestFetchedList: (type: EntityType, entries: Array<{
-            id: EntityId;
-            data: Record<string, unknown>;
-        }>, options?: IngestFetchedListOptions) => 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;
-};
-/**
- * Default process-wide entity graph store. Framework bindings subscribe to
- * this vanilla store; non-React consumers use its `getState`, `setState`, and
- * `subscribe` methods directly.
- */
-declare const graphStore: Omit<Omit<zustand_vanilla.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;
-        ingestFetchedList: (type: EntityType, entries: Array<{
-            id: EntityId;
-            data: Record<string, unknown>;
-        }>, options?: IngestFetchedListOptions) => 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;
-        ingestFetchedList: (type: EntityType, entries: Array<{
-            id: EntityId;
-            data: Record<string, unknown>;
-        }>, options?: IngestFetchedListOptions) => 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;
-};
-type GraphStore = ReturnType<typeof createGraphStore>;
-/**
- * @deprecated Import `graphStore` from core, or `useGraphStore` from the React
- * binding. This StoreApi-shaped alias remains for non-React 2.x migrations.
- */
-declare const useGraphStore: Omit<Omit<zustand_vanilla.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;
-        ingestFetchedList: (type: EntityType, entries: Array<{
-            id: EntityId;
-            data: Record<string, unknown>;
-        }>, options?: IngestFetchedListOptions) => 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;
-        ingestFetchedList: (type: EntityType, entries: Array<{
-            id: EntityId;
-            data: Record<string, unknown>;
-        }>, options?: IngestFetchedListOptions) => 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;
-};
-
-export { hasCustomPredicates as A, toEntityError as B, type CompletenessMode as C, toGraphQLVariables as D, type EntityType as E, type FilterSpec as F, type GraphStore as G, toRestParams as H, type IngestFetchedListOptions as I, toSQLClauses as J, type ListResultMeta as L, type QueryKey as Q, type SortSpec as S, TerminalError as T, type ViewDescriptor as V, type EntityId as a, type SyncOrigin as b, type EntitySnapshot as c, type EntitySyncMetadata as d, EMPTY_ENTITY_STATE as e, EMPTY_IDS as f, graphStore as g, EMPTY_LIST_STATE as h, EMPTY_SYNC_METADATA as i, type EntityError as j, type EntityErrorOptions as k, type EntityState as l, type FetchedEntityBatch as m, type FetchedListProjection as n, type FetchedListTarget as o, type FilterClause as p, type FilterGroup as q, type FilterOperator as r, type GraphState as s, type ListState as t, useGraphStore as u, type SortClause as v, type SortDirection as w, TransientError as x, createGraphStore as y, flattenClauses as z };