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

package/dist/index.d.ts

@@ -700,11 +700,24 @@ interface PersistGraphToStorageOptions {
     key: string;
     store?: GraphStore$1;
     pendingActions?: GraphActionRecord[];
+    /**
+     * The runtime whose status this write reports to. Omit for standalone calls,
+     * which fall back to the process-wide status store.
+     */
+    scope?: RuntimeScope;
 }
 interface HydrateGraphFromStorageOptions {
     storage: GraphPersistenceAdapter;
     key: string;
     store?: GraphStore$1;
+    /**
+     * The runtime that owns the pending-action set this hydrate populates.
+     *
+     * Without a scope, hydrate writes into the process-wide fallback set — which
+     * is what made a second runtime's hydrate erase the first runtime's
+     * un-settled actions. A runtime always passes its own scope.
+     */
+    scope?: RuntimeScope;
 }
 /**
  * Retry-with-backoff policy for replaying pending offline actions.
@@ -738,18 +751,58 @@ interface StartLocalFirstGraphOptions {
     persistDebounceMs?: number;
     /** Retry-with-backoff policy for offline action replay. */
     retryPolicy?: ReplayRetryPolicy;
+    /**
+     * Pre-built scope for this runtime. Omit and one is created — the normal
+     * case. Supply one only to share state deliberately (e.g. in a test).
+     */
+    scope?: RuntimeScope;
 }
 interface LocalFirstGraphRuntime {
     ready: Promise<void>;
-    dispose: () => void;
+    /**
+     * Tear down and drain. The returned promise resolves only once every
+     * in-flight persist has settled, so `await dispose()` guarantees no further
+     * write from this runtime lands (ADR-009 G2).
+     *
+     * Callers that do not await it get the old fire-and-forget behaviour, which
+     * is why the ASO session manager awaits it before opening a replacement.
+     */
+    dispose: () => Promise<void>;
     persistNow: () => Promise<void>;
     hydrate: () => Promise<Awaited<ReturnType<typeof hydrateGraphFromStorage>>>;
     getStatus: () => GraphSyncStatus;
+    /**
+     * This runtime's own state. Read `scope.statusStore` for status isolated from
+     * every other runtime in the process.
+     */
+    scope: RuntimeScope;
 }
 declare const graphSyncStatusStore: zustand_vanilla.StoreApi<{
     status: GraphSyncStatus;
     setStatus: (status: Partial<GraphSyncStatus>) => void;
 }>;
+/**
+ * Per-runtime state: the pending-action set and the status store that runtime
+ * publishes to.
+ *
+ * Both were previously module-level singletons shared by every runtime in the
+ * process. That was not merely shared state — `hydrateGraphFromStorage` clears
+ * the pending set before repopulating it, so a second runtime hydrating erased
+ * the first runtime's un-settled actions. On an account or practice switch that
+ * is silent write loss, which is why this is scoped per runtime (ADR-009 G1).
+ */
+interface RuntimeScope {
+    pendingActions: Map<string, GraphActionRecord>;
+    statusStore: GraphSyncStatusStore;
+}
+type GraphSyncStatusStore = ReturnType<typeof createGraphSyncStatusStore>;
+/** Create an independent sync-status store. Each runtime owns one. */
+declare function createGraphSyncStatusStore(): zustand_vanilla.StoreApi<{
+    status: GraphSyncStatus;
+    setStatus: (status: Partial<GraphSyncStatus>) => void;
+}>;
+/** Create an isolated runtime scope. */
+declare function createRuntimeScope(): RuntimeScope;
 declare function getGraphSyncStatus(): GraphSyncStatus;
 declare function persistGraphToStorage(opts: PersistGraphToStorageOptions): Promise<{
     ok: true;
@@ -1374,6 +1427,22 @@ interface ChangeSet<T = Record<string, unknown>> {
     changes: EntityChange<T>[];
     affectedListKeys?: string[];
     timestamp?: string;
+    /**
+     * The transport's resume position for this batch, when it has one.
+     *
+     * For ElectricSQL this is the shape handle plus the offset of the last
+     * message in the batch — the pair a consumer echoes back to resume. It is
+     * **batch-level, not per-change**: a resume position describes a boundary
+     * between batches, not a point inside one.
+     *
+     * Absent for transports with no resume semantics (a Postgres LISTEN/NOTIFY
+     * frame, for instance, carries no Electric offset). Absent is meaningful —
+     * it means "this batch cannot be checkpointed", not "offset zero".
+     */
+    cursor?: {
+        handle: string;
+        offset: string;
+    };
 }
 type UnsubscribeFn = () => void;
 interface SubscriptionConfig {
@@ -1691,6 +1760,13 @@ interface ShapeStream$1<T = Record<string, unknown>> {
     subscribe(onMsg: (msgs: ShapeMessage$1<T>[]) => void, onErr?: (e: Error) => void): () => void;
     isUpToDate: boolean;
     lastOffset: string;
+    /**
+     * Electric's handle for this shape. Optional because this is a structural
+     * type over the real client and older streams may not expose it — a batch
+     * without a handle yields no cursor rather than a half-formed one, since a
+     * resume needs BOTH handle and offset.
+     */
+    shapeHandle?: string;
 }
 interface ElectricTableConfig<T extends object> {
     type: EntityType;
@@ -1839,6 +1915,63 @@ declare function createTenantScopedElectricAdapter(opts: TenantScopedAdapterOpti
  * not import `@electric-sql/pglite` — consumers pass a PGlite-shaped handle.
  */
 
+/**
+ * Where a replica resumes from, and which generation it belongs to.
+ *
+ * `handle` and `offset` are ElectricSQL's own values, echoed back verbatim on
+ * resume — they are opaque here. `generation` increments when a snapshot is
+ * rebuilt (Electric's must-refetch), so a checkpoint from a previous generation
+ * is recognisably stale rather than silently resumed against new rows.
+ */
+interface ReplicaCheckpoint {
+    handle: string;
+    offset: string;
+    generation: number;
+}
+/** Checkpoint plus the rows it describes, committed together or not at all. */
+interface CheckpointedWrite {
+    key: string;
+    value: string;
+    checkpoint: ReplicaCheckpoint;
+}
+/** What a caller should do with what it found on disk. */
+type ResumeDecision = {
+    action: "resume";
+    checkpoint: ReplicaCheckpoint;
+} | {
+    action: "rebuild";
+    reason: ResumeRejection;
+};
+/**
+ * Why a stored replica cannot be resumed.
+ *
+ * Each is a *rebuild*, never a silent continue: resuming against a boundary
+ * that does not describe the rows on disk is how a replica ends up with a
+ * plausible-looking mixture of two generations.
+ */
+type ResumeRejection = 
+/** Nothing stored — a cold start, not a fault. */
+"no-value"
+/** Rows exist but were written by plain `set`, so their position is unknown. */
+ | "no-checkpoint"
+/** The checkpoint predates a rebuild; its offsets refer to a dead generation. */
+ | "stale-generation"
+/** The server issued a new shape handle, so old offsets are meaningless. */
+ | "handle-changed";
+/**
+ * Decide whether a stored replica may be resumed.
+ *
+ * Pure so the decision is testable without a database. `expected` is what the
+ * caller intends to resume as — its current replica generation, and the shape
+ * handle the server most recently gave it.
+ */
+declare function evaluateResume(stored: {
+    value: string | null;
+    checkpoint: ReplicaCheckpoint | null;
+}, expected: {
+    generation: number;
+    handle?: string;
+}): ResumeDecision;
 interface PGlitePersistenceClient {
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
         rows: T[];
@@ -1849,6 +1982,20 @@ interface CreatePGlitePersistenceAdapterOptions {
     /** Name of the snapshot table. Defaults to `_graph_snapshot`. */
     tableName?: string;
 }
+/**
+ * A persistence adapter that can also commit a resume checkpoint atomically.
+ *
+ * The plain {@link GraphPersistenceAdapter} contract cannot express this: its
+ * `set` writes a value and returns, so a checkpoint written after it is a
+ * second transaction, and a crash between the two leaves rows whose resume
+ * position is unknown. `setWithCheckpoint` closes that window (ADR-009 G3).
+ */
+interface CheckpointingPersistenceAdapter extends GraphPersistenceAdapter {
+    /** Commit rows and their resume checkpoint in ONE transaction. */
+    setWithCheckpoint: (write: CheckpointedWrite) => Promise<void>;
+    /** The checkpoint stored for `key`, or null if none. */
+    getCheckpoint: (key: string) => Promise<ReplicaCheckpoint | null>;
+}
 /**
  * Returns a {@link GraphPersistenceAdapter} that reads/writes the graph
  * snapshot through a PGlite-shaped client.
@@ -1863,7 +2010,7 @@ interface CreatePGlitePersistenceAdapterOptions {
  * const runtime = startLocalFirstGraph({ storage, key: "hotseaters:graph" });
  * ```
  */
-declare function createPGlitePersistenceAdapter(pglite: PGlitePersistenceClient, options?: CreatePGlitePersistenceAdapterOptions): Promise<GraphPersistenceAdapter>;
+declare function createPGlitePersistenceAdapter(pglite: PGlitePersistenceClient, options?: CreatePGlitePersistenceAdapterOptions): Promise<CheckpointingPersistenceAdapter>;
 
 /**
  * adapters/tauri-sql-persistence.ts
@@ -2380,4 +2527,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 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 };
+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 CheckpointedWrite, type CheckpointingPersistenceAdapter, 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 GraphSyncStatusStore, 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 ReplicaCheckpoint, type ResumeDecision, type ResumeRejection, type Row, type RowModel, type RowSelectionState, type RuntimeScope, 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, createGraphSyncStatusStore, createGraphTool, createGraphTransaction, createLoroMergeStrategy, createPGlitePersistenceAdapter, createRow, createRuntimeScope, createSchemaGraphTool, createSupabaseRealtimeAdapter, createSurrealLiveAdapter, createTauriSqlPersistenceAdapter, createTenantScopedElectricAdapter, createWebSocketAdapter, dedupe, escapeHtml, evaluateResume, 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 };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { graphStore, useGraphStore, subscribeDevtoolsEvent, getGraphDevtoolsCompatibilityDelegate, subscribeGraphDevtoolsCompatibility, matchesFilter, matchesSearch, compareEntities, emitLegacyDevtoolsEvent, __require } from './chunk-BE3BMRKF.mjs';
-export { EMPTY_ENTITY_STATE, EMPTY_IDS, EMPTY_LIST_STATE, EMPTY_SYNC_METADATA, applyView, attachGlobalListeners, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createGraphStore, dedupe, fetchEntity, fetchList, findInsertionIndex, getActiveSubscriberCount, getEngineOptions, getMergeStrategy, getSchema, graphStore, hasMergeStrategy, lwwStrategy, matchesFilter, matchesSearch, readRelations, registerMergeStrategy, registerSchema, registerSubscriber, serializeKey, setDefaultMergeStrategy, startGarbageCollector, stopGarbageCollector, subscribeDevtoolsEvent, subscribeSubscriberStats, unregisterSubscriber, useGraphStore } from './chunk-BE3BMRKF.mjs';
+import { graphStore, useGraphStore, subscribeDevtoolsEvent, getGraphDevtoolsCompatibilityDelegate, subscribeGraphDevtoolsCompatibility, matchesFilter, matchesSearch, compareEntities, emitLegacyDevtoolsEvent, __require } from './chunk-H7NBREZV.mjs';
+export { EMPTY_ENTITY_STATE, EMPTY_IDS, EMPTY_LIST_STATE, EMPTY_SYNC_METADATA, applyView, attachGlobalListeners, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createGraphStore, dedupe, fetchEntity, fetchList, findInsertionIndex, getActiveSubscriberCount, getEngineOptions, getMergeStrategy, getSchema, graphStore, hasMergeStrategy, lwwStrategy, matchesFilter, matchesSearch, readRelations, registerMergeStrategy, registerSchema, registerSubscriber, serializeKey, setDefaultMergeStrategy, startGarbageCollector, stopGarbageCollector, subscribeDevtoolsEvent, subscribeSubscriberStats, unregisterSubscriber, useGraphStore } from './chunk-H7NBREZV.mjs';
 import { createStore } from 'zustand/vanilla';
 
 // src/errors.ts
@@ -968,21 +968,49 @@ var graphSyncStatusStore = createStore()((set) => ({
     }
   }))
 }));
-var pendingActions = /* @__PURE__ */ new Map();
+function createGraphSyncStatusStore() {
+  return createStore()((set) => ({
+    status: {
+      phase: "idle",
+      isOnline: true,
+      isSynced: true,
+      pendingActions: 0,
+      lastHydratedAt: null,
+      lastPersistedAt: null,
+      storageKey: null,
+      error: null
+    },
+    setStatus: (status) => set((state) => ({ status: { ...state.status, ...status } }))
+  }));
+}
+function createRuntimeScope() {
+  return {
+    pendingActions: /* @__PURE__ */ new Map(),
+    statusStore: createGraphSyncStatusStore()
+  };
+}
+var fallbackScope = {
+  pendingActions: /* @__PURE__ */ new Map(),
+  statusStore: graphSyncStatusStore
+};
+function resolveScope(scope) {
+  return scope ?? fallbackScope;
+}
 function getGraphSyncStatus() {
   return graphSyncStatusStore.getState().status;
 }
 async function persistGraphToStorage(opts) {
   const storeApi = opts.store ?? graphStore;
+  const scope = resolveScope(opts.scope);
   const payload = {
     version: 1,
     snapshot: cloneGraphSnapshot(storeApi),
-    pendingActions: opts.pendingActions ?? Array.from(pendingActions.values())
+    pendingActions: opts.pendingActions ?? Array.from(scope.pendingActions.values())
   };
   const json = JSON.stringify(payload);
   await opts.storage.set(opts.key, json);
   const persistedAt = (/* @__PURE__ */ new Date()).toISOString();
-  graphSyncStatusStore.getState().setStatus({
+  scope.statusStore.getState().setStatus({
     lastPersistedAt: persistedAt,
     storageKey: opts.key,
     pendingActions: payload.pendingActions.length
@@ -996,6 +1024,7 @@ async function persistGraphToStorage(opts) {
 }
 async function hydrateGraphFromStorage(opts) {
   const storeApi = opts.store ?? graphStore;
+  const scope = resolveScope(opts.scope);
   const raw = await opts.storage.get(opts.key);
   if (!raw) {
     return {
@@ -1009,13 +1038,13 @@ async function hydrateGraphFromStorage(opts) {
   try {
     const parsed = JSON.parse(raw);
     storeApi.setState(parsed.snapshot);
-    pendingActions.clear();
-    for (const action of parsed.pendingActions ?? []) pendingActions.set(action.id, action);
+    scope.pendingActions.clear();
+    for (const action of parsed.pendingActions ?? []) scope.pendingActions.set(action.id, action);
     const hydratedAt = (/* @__PURE__ */ new Date()).toISOString();
-    graphSyncStatusStore.getState().setStatus({
+    scope.statusStore.getState().setStatus({
       lastHydratedAt: hydratedAt,
       storageKey: opts.key,
-      pendingActions: pendingActions.size,
+      pendingActions: scope.pendingActions.size,
       error: null
     });
     return {
@@ -1025,11 +1054,11 @@ async function hydrateGraphFromStorage(opts) {
       entityCounts: Object.fromEntries(
         Object.entries(parsed.snapshot.entities).map(([type, entities]) => [type, Object.keys(entities).length])
       ),
-      pendingActions: Array.from(pendingActions.values())
+      pendingActions: Array.from(scope.pendingActions.values())
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    graphSyncStatusStore.getState().setStatus({
+    scope.statusStore.getState().setStatus({
       phase: "error",
       error: message,
       storageKey: opts.key
@@ -1047,8 +1076,15 @@ function startLocalFirstGraph(opts) {
   const storeApi = opts.store ?? graphStore;
   const key = opts.key ?? DEFAULT_STORAGE_KEY;
   const persistDebounceMs = opts.persistDebounceMs ?? 50;
-  const statusStore = graphSyncStatusStore.getState();
-  statusStore.setStatus({
+  const scope = opts.scope ?? createRuntimeScope();
+  const { pendingActions } = scope;
+  const setStatus = (status) => {
+    scope.statusStore.getState().setStatus(status);
+    if (scope.statusStore !== graphSyncStatusStore) {
+      graphSyncStatusStore.getState().setStatus(status);
+    }
+  };
+  setStatus({
     phase: "hydrating",
     storageKey: key,
     isOnline: opts.onlineSource?.getIsOnline() ?? getDefaultOnlineSource().getIsOnline(),
@@ -1056,10 +1092,22 @@ function startLocalFirstGraph(opts) {
     error: null
   });
   let persistTimer = null;
+  const inFlight = /* @__PURE__ */ new Set();
+  let disposePromise = null;
+  let disposed = false;
+  const runPersist = () => {
+    const write = persistGraphToStorage({ storage: opts.storage, key, store: storeApi, scope }).catch(() => void 0).finally(() => {
+      inFlight.delete(write);
+    });
+    inFlight.add(write);
+    return write;
+  };
   const schedulePersist = () => {
+    if (disposed) return;
     if (persistTimer) clearTimeout(persistTimer);
     persistTimer = setTimeout(() => {
-      void persistGraphToStorage({ storage: opts.storage, key, store: storeApi });
+      persistTimer = null;
+      void runPersist();
     }, persistDebounceMs);
   };
   const graphUnsub = storeApi.subscribe(() => {
@@ -1068,7 +1116,7 @@ function startLocalFirstGraph(opts) {
   const actionUnsub = subscribeGraphActionEvents((event) => {
     if (event.type === "enqueued") pendingActions.set(event.record.id, event.record);
     if (event.type === "settled") pendingActions.delete(event.record.id);
-    graphSyncStatusStore.getState().setStatus({
+    setStatus({
       pendingActions: pendingActions.size,
       isSynced: pendingActions.size === 0
     });
@@ -1076,15 +1124,15 @@ function startLocalFirstGraph(opts) {
   });
   const onlineSource = opts.onlineSource ?? getDefaultOnlineSource();
   const onlineUnsub = onlineSource.subscribe((online) => {
-    graphSyncStatusStore.getState().setStatus({
+    setStatus({
       isOnline: online,
       phase: online ? "ready" : "offline"
     });
   });
   const ready = (async () => {
-    const hydrated = await hydrateGraphFromStorage({ storage: opts.storage, key, store: storeApi });
+    const hydrated = await hydrateGraphFromStorage({ storage: opts.storage, key, store: storeApi, scope });
     if (opts.replayPendingActions && hydrated.ok && pendingActions.size > 0) {
-      graphSyncStatusStore.getState().setStatus({
+      setStatus({
         phase: "syncing",
         isSynced: false
       });
@@ -1093,10 +1141,10 @@ function startLocalFirstGraph(opts) {
         await replayActionWithRetry(action, policy, storeApi);
         pendingActions.delete(action.id);
       }
-      await persistGraphToStorage({ storage: opts.storage, key, store: storeApi });
+      await persistGraphToStorage({ storage: opts.storage, key, store: storeApi, scope });
     }
     const online = onlineSource.getIsOnline();
-    graphSyncStatusStore.getState().setStatus({
+    setStatus({
       phase: online ? "ready" : "offline",
       isOnline: online,
       isSynced: pendingActions.size === 0,
@@ -1105,21 +1153,39 @@ function startLocalFirstGraph(opts) {
   })();
   return {
     ready,
+    /**
+     * Tear down, and do not resolve until this runtime is quiescent.
+     *
+     * Unsubscribes first so no further work is queued, cancels a scheduled
+     * write, then awaits every write already in flight. Callers that await
+     * this are guaranteed no persist from this runtime lands afterwards.
+     *
+     * Idempotent: a second call returns the same promise rather than starting
+     * a second teardown, which is what makes a StrictMode double-unmount safe.
+     */
     dispose() {
+      if (disposePromise) return disposePromise;
+      disposed = true;
       graphUnsub();
       actionUnsub();
       onlineUnsub();
-      if (persistTimer) clearTimeout(persistTimer);
+      if (persistTimer) {
+        clearTimeout(persistTimer);
+        persistTimer = null;
+      }
+      disposePromise = Promise.all([...inFlight]).then(() => void 0);
+      return disposePromise;
     },
     async persistNow() {
-      await persistGraphToStorage({ storage: opts.storage, key, store: storeApi });
+      await runPersist();
     },
     hydrate() {
-      return hydrateGraphFromStorage({ storage: opts.storage, key, store: storeApi });
+      return hydrateGraphFromStorage({ storage: opts.storage, key, store: storeApi, scope });
     },
     getStatus() {
-      return graphSyncStatusStore.getState().status;
-    }
+      return scope.statusStore.getState().status;
+    },
+    scope
   };
 }
 function cloneGraphSnapshot(storeApi) {
@@ -2500,7 +2566,10 @@ function createElectricAdapter(opts) {
     shapeUnsubs.push(tc.shapeStream.subscribe((msgs) => {
       if (!globalHandler) return;
       const changes = msgs.map((m) => toChange(tc, m)).filter((c) => c !== null);
-      if (changes.length > 0) globalHandler({ changes, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      const last = msgs.at(-1);
+      const handle = tc.shapeStream.shapeHandle;
+      const cursor = handle && last?.offset ? { handle, offset: last.offset } : void 0;
+      if (changes.length > 0) globalHandler({ changes, timestamp: (/* @__PURE__ */ new Date()).toISOString(), cursor });
       if (tc.shapeStream.isUpToDate) {
         syncedTables.add(tc.table);
         checkAllSynced();
@@ -2605,6 +2674,17 @@ function createTenantScopedElectricAdapter(opts) {
 }
 
 // src/adapters/pglite-persistence.ts
+function evaluateResume(stored, expected) {
+  if (stored.value === null) return { action: "rebuild", reason: "no-value" };
+  if (!stored.checkpoint) return { action: "rebuild", reason: "no-checkpoint" };
+  if (stored.checkpoint.generation !== expected.generation) {
+    return { action: "rebuild", reason: "stale-generation" };
+  }
+  if (expected.handle && stored.checkpoint.handle !== expected.handle) {
+    return { action: "rebuild", reason: "handle-changed" };
+  }
+  return { action: "resume", checkpoint: stored.checkpoint };
+}
 var DEFAULT_TABLE = "_graph_snapshot";
 async function createPGlitePersistenceAdapter(pglite, options = {}) {
   const tableName = options.tableName ?? DEFAULT_TABLE;
@@ -2618,6 +2698,12 @@ async function createPGlitePersistenceAdapter(pglite, options = {}) {
        updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
      )`
   );
+  await pglite.exec(
+    `ALTER TABLE ${tableName}
+       ADD COLUMN IF NOT EXISTS checkpoint_handle     TEXT,
+       ADD COLUMN IF NOT EXISTS checkpoint_offset     TEXT,
+       ADD COLUMN IF NOT EXISTS checkpoint_generation INTEGER`
+  );
   return {
     async get(key) {
       const result = await pglite.query(
@@ -2639,6 +2725,42 @@ async function createPGlitePersistenceAdapter(pglite, options = {}) {
     },
     async remove(key) {
       await pglite.query(`DELETE FROM ${tableName} WHERE key = $1`, [key]);
+    },
+    /**
+     * Commit rows and their resume checkpoint together.
+     *
+     * One statement, so the two cannot be separated by a crash: either the row
+     * carries the new value AND the new checkpoint, or it carries neither. On
+     * resume, `getCheckpoint` therefore describes exactly the value returned by
+     * `get` — the property ADR-009 G3 requires.
+     */
+    async setWithCheckpoint({ key, value, checkpoint }) {
+      await pglite.query(
+        `INSERT INTO ${tableName}
+           (key, value, updated_at, checkpoint_handle, checkpoint_offset, checkpoint_generation)
+         VALUES ($1, $2, now(), $3, $4, $5)
+         ON CONFLICT (key) DO UPDATE
+           SET value                 = EXCLUDED.value,
+               updated_at            = now(),
+               checkpoint_handle     = EXCLUDED.checkpoint_handle,
+               checkpoint_offset     = EXCLUDED.checkpoint_offset,
+               checkpoint_generation = EXCLUDED.checkpoint_generation`,
+        [key, value, checkpoint.handle, checkpoint.offset, checkpoint.generation]
+      );
+    },
+    async getCheckpoint(key) {
+      const result = await pglite.query(
+        `SELECT checkpoint_handle, checkpoint_offset, checkpoint_generation
+           FROM ${tableName} WHERE key = $1`,
+        [key]
+      );
+      const row = result.rows[0];
+      if (!row?.checkpoint_handle || row.checkpoint_offset === null) return null;
+      return {
+        handle: row.checkpoint_handle,
+        offset: row.checkpoint_offset,
+        generation: row.checkpoint_generation ?? 0
+      };
     }
   };
 }
@@ -3163,6 +3285,6 @@ function getFacetedRowModel(preFilteredRowModel, columnId, allFilteredRowModel)
   return preFilteredRowModel;
 }
 
-export { IncrementalView, RealtimeManager, TerminalError, TransientError, __resetActiveGraphStore, __resetEntityTransports, __resetStoreRegistry, applyAgUiDelta, applyAgUiSnapshot, applyJsonPatch, buildTenantWhere, collectDirtyPaths, configureTimeTravel, createConvexAdapter, createDevtoolsEventBus, createElectricAdapter, createFlintAdapter, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphTool, createGraphTransaction, createLoroMergeStrategy, createPGlitePersistenceAdapter, createRow, createSchemaGraphTool, createSupabaseRealtimeAdapter, createSurrealLiveAdapter, createTauriSqlPersistenceAdapter, createTenantScopedElectricAdapter, createWebSocketAdapter, escapeHtml, exportGraphSnapshot, exportGraphSnapshotWithSchemas, flattenClauses, getCoreRowModel, getRealtimeManager as getElectricRealtimeManager, getEntityJsonSchema, getEntityTransport, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGraphSyncStatus, getGroupedRowModel, getPaginatedRowModel, getRealtimeManager, getRegisteredEntityTypes, getRegisteredStores, getSelectedRowModel, getSortedRowModel, getTimeTravelState, getValueAtPath, graphSyncStatusStore, hasCustomPredicates, humanizeFieldName, hydrateGraphFromStorage, inferSchemaFieldType, makeRestTransport, parseCreateTable, persistGraphToStorage, prepareGraphStoreScope, publishFlintMutation, queryOnce, recordGraphSnapshot, registerEntityFromSql, registerEntityJsonSchema, registerEntityTransport, registerRuntimeSchema, registerStore, registryKey, renderMarkdownToHtml, replayActionWithRetry, resetRealtimeManager, resolveActiveGraphStore, restoreGraphSnapshot, restoreGraphSnapshotBySeq, runWithGraphStore, selectGraph, setActiveGraphStore, setValueAtPath, sqlTypeToJsonSchema, startLocalFirstGraph, stepTimeTravel, subscribeTimeTravel, toEntityError, toGraphQLVariables, toPrismaOrderBy, toPrismaWhere, toRestParams, toSQLClauses };
+export { IncrementalView, RealtimeManager, TerminalError, TransientError, __resetActiveGraphStore, __resetEntityTransports, __resetStoreRegistry, applyAgUiDelta, applyAgUiSnapshot, applyJsonPatch, buildTenantWhere, collectDirtyPaths, configureTimeTravel, createConvexAdapter, createDevtoolsEventBus, createElectricAdapter, createFlintAdapter, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphSyncStatusStore, createGraphTool, createGraphTransaction, createLoroMergeStrategy, createPGlitePersistenceAdapter, createRow, createRuntimeScope, createSchemaGraphTool, createSupabaseRealtimeAdapter, createSurrealLiveAdapter, createTauriSqlPersistenceAdapter, createTenantScopedElectricAdapter, createWebSocketAdapter, escapeHtml, evaluateResume, exportGraphSnapshot, exportGraphSnapshotWithSchemas, flattenClauses, getCoreRowModel, getRealtimeManager as getElectricRealtimeManager, getEntityJsonSchema, getEntityTransport, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGraphSyncStatus, getGroupedRowModel, getPaginatedRowModel, getRealtimeManager, getRegisteredEntityTypes, getRegisteredStores, getSelectedRowModel, getSortedRowModel, getTimeTravelState, getValueAtPath, graphSyncStatusStore, hasCustomPredicates, humanizeFieldName, hydrateGraphFromStorage, inferSchemaFieldType, makeRestTransport, parseCreateTable, persistGraphToStorage, prepareGraphStoreScope, publishFlintMutation, queryOnce, recordGraphSnapshot, registerEntityFromSql, registerEntityJsonSchema, registerEntityTransport, registerRuntimeSchema, registerStore, registryKey, renderMarkdownToHtml, replayActionWithRetry, resetRealtimeManager, resolveActiveGraphStore, restoreGraphSnapshot, restoreGraphSnapshotBySeq, runWithGraphStore, selectGraph, setActiveGraphStore, setValueAtPath, sqlTypeToJsonSchema, startLocalFirstGraph, stepTimeTravel, subscribeTimeTravel, toEntityError, toGraphQLVariables, toPrismaOrderBy, toPrismaWhere, toRestParams, toSQLClauses };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map