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

package/dist/index.d.cts

@@ -1,76 +1,7 @@
+import { S as SortSpec, F as FilterSpec, E as EntityType, G as GraphStore$1, a as EntityId, b as SyncOrigin, Q as QueryKey, u as useGraphStore, c as EntitySnapshot, d as EntitySyncMetadata, g as graphStore } from './graph-ClW3HD8B.cjs';
+export { C as CompletenessMode, e as EMPTY_ENTITY_STATE, f as EMPTY_IDS, h as EMPTY_LIST_STATE, i as EMPTY_SYNC_METADATA, j as EntityError, k as EntityErrorOptions, l as EntityState, m as FetchedEntityBatch, n as FetchedListProjection, o as FetchedListTarget, p as FilterClause, q as FilterGroup, r as FilterOperator, s as GraphState, I as IngestFetchedListOptions, L as ListResultMeta, t as ListState, v as SortClause, w as SortDirection, T as TerminalError, x as TransientError, V as ViewDescriptor, y as createGraphStore, z as flattenClauses, A as hasCustomPredicates, B as toEntityError, D as toGraphQLVariables, H as toRestParams, J as toSQLClauses } from './graph-ClW3HD8B.cjs';
 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;
-
 /**
  * Compiles a {@link FilterSpec} into a Prisma `where` object (plain JSON-serializable shape).
  *
@@ -87,922 +18,6 @@ declare function toPrismaWhere(filter: FilterSpec): Record<string, unknown>;
  */
 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;
-
-/** 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$1 = 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;
-};
-
 /**
  * 2.0 transport contract.
  *
@@ -1781,6 +796,37 @@ declare function replayActionWithRetry(action: GraphActionRecord, policy: Resolv
     error: unknown;
 }>;
 
+/** Deprecated in-process event shape retained by the package root. */
+type LegacyDevtoolsEvent = {
+    kind: "upsert";
+    type: string;
+    id: string;
+    data: Record<string, unknown>;
+    at: string;
+} | {
+    kind: "patch";
+    type: string;
+    id: string;
+    patch: Record<string, unknown>;
+    at: string;
+} | {
+    kind: "unpatch";
+    type: string;
+    id: string;
+    keys: string[];
+    at: string;
+} | {
+    kind: "clearPatch";
+    type: string;
+    id: string;
+    at: string;
+} | {
+    kind: "list";
+    key: string;
+    idCount: number;
+    at: string;
+};
+
 /**
  * Process-wide defaults for stale times, retries, and background revalidation.
  * Keeps hook signatures small: `useEntity` / `useEntityList` merge these with per-query overrides.
@@ -1880,47 +926,15 @@ declare function unregisterSubscriber(key: string, token: symbol, store?: GraphS
  * Subscribe to ref-count changes for `registerSubscriber` / `unregisterSubscriber`.
  * Used by `useGraphDevTools` so subscriber totals update without graph mutations.
  */
-declare function subscribeSubscriberStats(onChange: () => void): () => boolean;
+declare function subscribeSubscriberStats(onChange: () => void, store?: GraphStore$1): () => boolean;
 /** Total active entity subscriber tokens across all keys (sum of ref-counts). */
 declare function getActiveSubscriberCount(store?: GraphStore$1): 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.
+ * New inspection surfaces should use the versioned `./devtools` subpath.
  */
-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 DevtoolsEvent = LegacyDevtoolsEvent;
 type DevtoolsListener = (event: DevtoolsEvent) => void;
 /**
  * Subscribe to the devtools event stream.
@@ -2014,67 +1028,54 @@ declare function createDevtoolsEventBus(opts?: DevtoolsEventBusOptions): Devtool
  * 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>;
+/** Returns registered stores for one bus, or every bus for legacy callers. */
+declare function getRegisteredStores(bus?: DevtoolsEventBus): ReadonlyArray<RegisteredStore>;
 
 /**
- * devtools-time-travel.ts — G4 parity: true time-travel for the entity graph.
+ * Deprecated root time-travel compatibility facade.
  *
- * 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.
+ * Snapshot data, cursors, retention, rewind state, and listeners are owned by
+ * the optional per-store DevTools controller. This root module imports only a
+ * lightweight delegate bridge, so normal package imports do not pull the
+ * optional controller/protocol implementation into the root bundle.
  */
 
 type GraphSlice = Pick<ReturnType<typeof graphStore.getState>, "entities" | "patches" | "entityStates" | "syncMetadata" | "lists">;
 interface TimeTravelSnapshot {
-    /** Monotonic id (capture order). */
+    /** Monotonic controller cursor for the captured state. */
     seq: number;
     /** Capture timestamp (ms). */
     at: number;
-    /** Optional label (e.g. the action that produced this state). */
+    /** Optional compatibility label. */
     label?: string;
+    /** Snapshot payloads are controller-private and no longer exposed at root. */
     data: GraphSlice;
 }
 interface TimeTravelState {
     snapshots: ReadonlyArray<Omit<TimeTravelSnapshot, "data">>;
-    /** Index currently restored, or null if live (at head). */
+    /** Compatibility ring index currently restored, or null when live. */
     cursor: number | null;
     capacity: number;
 }
-/** Configure ring capacity (number of retained snapshots). */
+/** @deprecated Attach `@prometheus-ags/entity-graph-core/devtools` and configure its controller. */
 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, storeApi?: GraphStore$1): number;
+}, storeApi?: GraphStore$1): void;
 /**
- * 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.
+ * @deprecated Use the attached controller's automatic snapshot history.
+ * Returns `-1` when the optional controller is not attached to `storeApi`.
  */
+declare function recordGraphSnapshot(label?: string, storeApi?: GraphStore$1): number;
+/** @deprecated Use `controller.rewind(cursor)` from the explicit `./devtools` entry. */
 declare function restoreGraphSnapshot(index: number, storeApi?: GraphStore$1): boolean;
-/** Restore by capture seq (stable across ring eviction within capacity). */
+/** @deprecated Use `controller.rewind(cursor)` from the explicit `./devtools` entry. */
 declare function restoreGraphSnapshotBySeq(seq: number, storeApi?: GraphStore$1): boolean;
-/** Step the cursor by `delta` (negative = back in time) and restore. */
+/** @deprecated Resolve retained cursors through the explicit per-store controller. */
 declare function stepTimeTravel(delta: number, storeApi?: GraphStore$1): 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;
+/** @deprecated Use `controller.getSnapshotHistoryStatus()` and controller events. */
+declare function getTimeTravelState(storeApi?: GraphStore$1): TimeTravelState;
+/** @deprecated Subscribe to the explicit per-store controller. */
+declare function subscribeTimeTravel(cb: () => void, storeApi?: GraphStore$1): () => void;
 
 /**
  * Evaluate `FilterSpec` against one in-memory entity — mirrors remote semantics as closely as plain JS allows.
@@ -3379,4 +2380,4 @@ declare function getFacetedMinMaxValues<TData>(rowModel: RowModel<TData>, column
  */
 declare function getFacetedRowModel<TData>(preFilteredRowModel: RowModel<TData>, columnId: string, allFilteredRowModel: RowModel<TData>): RowModel<TData>;
 
-export { type AccessorFn, type AdapterStatus, type AgUiStateDeltaEvent, type AgUiStateMapping, type AgUiStateSnapshotEvent, type AggregationFn, type ApplyAgUiOptions, 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 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 FetchedEntityBatch, type FetchedListProjection, type FetchedListTarget, type FilterClause, type FilterFn, type FilterGroup, type FilterOperator, type FilterSpec, type FlintCheckpointStore, type FlintClientLike, type FlintEntityEvent, type FlintEntityQuery, type FlintEntityRecord, 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 GraphStore$1 as GraphStore, type GraphSyncStatus, type GraphToolContext, type GraphTransaction, type GroupingState, type HasManyRelation, type Header, type HeaderContext, type HeaderGroup, type HeaderRenderer, IncrementalView, type IncrementalViewOptions, type IngestFetchedListOptions, type JsonPatchOp, type JsonSchemaObject, type ListFetchParams, type ListQuery, type ListQueryOptions, type ListResponse, type ListResult, type ListResultMeta, type ListState, type LocalFirstGraphRuntime, type LoroModuleLoader, 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, __resetActiveGraphStore, __resetEntityTransports, __resetStoreRegistry, applyAgUiDelta, applyAgUiSnapshot, applyJsonPatch, applyView, attachGlobalListeners, buildTenantWhere, cascadeInvalidation, checkCompleteness, collectDirtyPaths, compareEntities, configureEngine, configureTimeTravel, createConvexAdapter, createDevtoolsEventBus, createElectricAdapter, createFlintAdapter, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphStore, 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, getGraphSyncStatus, getGroupedRowModel, getMergeStrategy, getPaginatedRowModel, getRealtimeManager, getRegisteredEntityTypes, getRegisteredStores, getSchema, getSelectedRowModel, getSortedRowModel, getTimeTravelState, getValueAtPath, graphStore, graphSyncStatusStore, hasCustomPredicates, hasMergeStrategy, humanizeFieldName, hydrateGraphFromStorage, inferSchemaFieldType, lwwStrategy, makeRestTransport, matchesFilter, matchesSearch, parseCreateTable, persistGraphToStorage, prepareGraphStoreScope, publishFlintMutation, queryOnce, readRelations, recordGraphSnapshot, registerEntityFromSql, registerEntityJsonSchema, registerEntityTransport, registerMergeStrategy, registerRuntimeSchema, registerSchema, registerStore, registerSubscriber, registryKey, renderMarkdownToHtml, replayActionWithRetry, resetRealtimeManager, resolveActiveGraphStore, restoreGraphSnapshot, restoreGraphSnapshotBySeq, runWithGraphStore, selectGraph, serializeKey, setActiveGraphStore, setDefaultMergeStrategy, setValueAtPath, sqlTypeToJsonSchema, startGarbageCollector, startLocalFirstGraph, stepTimeTravel, stopGarbageCollector, subscribeDevtoolsEvent, subscribeSubscriberStats, subscribeTimeTravel, toEntityError, toGraphQLVariables, toPrismaOrderBy, toPrismaWhere, toRestParams, toSQLClauses, unregisterSubscriber, useGraphStore };
+export { type AccessorFn, type AdapterStatus, type AgUiStateDeltaEvent, type AgUiStateMapping, type AgUiStateSnapshotEvent, type AggregationFn, type ApplyAgUiOptions, 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 CreateFlintAdapterOptions, type CreatePGlitePersistenceAdapterOptions, type CreateTauriSqlPersistenceAdapterOptions, type DevtoolsEvent, type DevtoolsEventBus, type DevtoolsEventBusOptions, type DevtoolsSourceFn, type ElectricAdapterOptions, type ElectricTableConfig, type EngineOptions, type EntityChange, EntityId, type EntityJsonSchemaConfig, type EntityQueryOptions, type EntitySchema, EntitySnapshot, EntitySyncMetadata, type EntityTransport, EntityType, type ExpandedState, type FilterFn, FilterSpec, type FlintCheckpointStore, type FlintClientLike, type FlintEntityEvent, type FlintEntityQuery, type FlintEntityRecord, 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, GraphStore$1 as GraphStore, type GraphSyncStatus, type GraphToolContext, type GraphTransaction, type GroupingState, type HasManyRelation, type Header, type HeaderContext, type HeaderGroup, type HeaderRenderer, IncrementalView, type IncrementalViewOptions, type JsonPatchOp, type JsonSchemaObject, type ListFetchParams, type ListQuery, type ListQueryOptions, type ListResponse, type ListResult, type LocalFirstGraphRuntime, type LoroModuleLoader, type MakeRestTransportOptions, type ManagerOptions, type ManyToManyRelation, type MergeContext, type MergeStrategy, type PGlitePersistenceClient, type PaginationState, type ColumnDef as PureColumnDef, type ColumnMeta as PureColumnMeta, QueryKey, type RealtimeAdapter, RealtimeManager, type RegisterEntityFromSqlOptions, type RegisteredStore, type RelationDescriptor, type ReplayRetryPolicy, type Row, type RowModel, type RowSelectionState, type SchemaGraphToolContext, 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, SyncOrigin, type TableInstance, type TableOptions, type TableState, type TauriSqlClient, type TenantClaim, type TenantScopedAdapterOptions, type TenantScopedTableConfig, type TimeTravelSnapshot, type TimeTravelState, type UnsubscribeFn, type Updater, type ViewMode, type WebSocketAdapterOptions, __resetActiveGraphStore, __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, getActiveSubscriberCount, getCoreRowModel, getRealtimeManager as getElectricRealtimeManager, getEngineOptions, getEntityJsonSchema, getEntityTransport, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGraphSyncStatus, getGroupedRowModel, getMergeStrategy, getPaginatedRowModel, getRealtimeManager, getRegisteredEntityTypes, getRegisteredStores, getSchema, getSelectedRowModel, getSortedRowModel, getTimeTravelState, getValueAtPath, graphStore, graphSyncStatusStore, hasMergeStrategy, humanizeFieldName, hydrateGraphFromStorage, inferSchemaFieldType, lwwStrategy, makeRestTransport, matchesFilter, matchesSearch, parseCreateTable, persistGraphToStorage, prepareGraphStoreScope, publishFlintMutation, queryOnce, readRelations, recordGraphSnapshot, registerEntityFromSql, registerEntityJsonSchema, registerEntityTransport, registerMergeStrategy, registerRuntimeSchema, registerSchema, registerStore, registerSubscriber, registryKey, renderMarkdownToHtml, replayActionWithRetry, resetRealtimeManager, resolveActiveGraphStore, restoreGraphSnapshot, restoreGraphSnapshotBySeq, runWithGraphStore, selectGraph, serializeKey, setActiveGraphStore, setDefaultMergeStrategy, setValueAtPath, sqlTypeToJsonSchema, startGarbageCollector, startLocalFirstGraph, stepTimeTravel, stopGarbageCollector, subscribeDevtoolsEvent, subscribeSubscriberStats, subscribeTimeTravel, toPrismaOrderBy, toPrismaWhere, unregisterSubscriber, useGraphStore };