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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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.js';
-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.js';
+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-QfI6o5eV.js';
+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-QfI6o5eV.js';
 import * as zustand_vanilla from 'zustand/vanilla';
 
 /**
@@ -663,17 +663,14 @@ declare function exportGraphSnapshot(opts: GraphSnapshotExportOptions): string;
 declare function createGraphTool<TInput, TResult>(handler: (input: TInput, ctx: GraphToolContext) => Promise<TResult> | TResult): (input: TInput) => TResult | Promise<TResult>;
 declare function createSchemaGraphTool<TInput, TResult>(handler: (input: TInput, ctx: SchemaGraphToolContext) => Promise<TResult> | TResult): (input: TInput) => TResult | Promise<TResult>;
 
-interface GraphPersistenceAdapter {
-    get: (key: string) => Promise<string | null> | string | null;
-    set: (key: string, value: string) => Promise<void> | void;
-    remove?: (key: string) => Promise<void> | void;
-}
-interface GraphActionRecord {
-    id: string;
-    key: string;
-    input: unknown;
-    enqueuedAt: string;
-}
+/**
+ * Types shared by the local-first runtime and its runtime scope.
+ *
+ * These live here, not in local-first-runtime.ts, because runtime-scope.ts
+ * needs them too. Importing them from the runtime would make the two modules
+ * import each other, and TypeScript resolves that cycle by widening the types
+ * to `unknown` — which type-checks at the definition and fails at every use.
+ */
 interface GraphSyncStatus {
     phase: "idle" | "hydrating" | "syncing" | "ready" | "offline" | "error";
     isOnline: boolean;
@@ -684,6 +681,65 @@ interface GraphSyncStatus {
     storageKey: string | null;
     error: string | null;
 }
+interface GraphActionRecord {
+    id: string;
+    key: string;
+    input: unknown;
+    enqueuedAt: string;
+}
+interface ReplayRetryPolicy {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffFactor?: number;
+    jitter?: "full" | "equal" | "none";
+    poisonHandler?: (action: GraphActionRecord, error: unknown) => void | Promise<void>;
+}
+
+/** Create an independent sync-status store. Each runtime owns one. */
+declare function createGraphSyncStatusStore(): zustand_vanilla.StoreApi<{
+    status: GraphSyncStatus;
+    setStatus: (status: Partial<GraphSyncStatus>) => void;
+}>;
+type GraphSyncStatusStore = ReturnType<typeof createGraphSyncStatusStore>;
+/**
+ * Per-runtime state container.
+ *
+ * Both fields 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;
+}
+/** Create an isolated runtime scope. */
+declare function createRuntimeScope(): RuntimeScope;
+
+/**
+ * Replay retry policy: defaults, exponential backoff, and jitter.
+ *
+ * Separated from the runtime because it is pure scheduling arithmetic — it
+ * touches no store, no adapter, and no persisted state, and is the part most
+ * likely to be reasoned about (or tuned) on its own.
+ */
+interface ResolvedRetryPolicy {
+    maxAttempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffFactor: number;
+    jitter: "full" | "equal" | "none";
+    poisonHandler?: (action: GraphActionRecord, error: unknown) => void | Promise<void>;
+}
+
+interface GraphPersistenceAdapter {
+    get: (key: string) => Promise<string | null> | string | null;
+    set: (key: string, value: string) => Promise<void> | void;
+    remove?: (key: string) => Promise<void> | void;
+}
 interface GraphSnapshotPayload {
     version: 1;
     snapshot: {
@@ -731,14 +787,6 @@ interface HydrateGraphFromStorageOptions {
  * Defaults: 5 attempts, starting at 500ms, doubling up to 30s, with
  * "equal" jitter (random in `[delay/2, delay]`).
  */
-interface ReplayRetryPolicy {
-    maxAttempts?: number;
-    initialDelayMs?: number;
-    maxDelayMs?: number;
-    backoffFactor?: number;
-    jitter?: "full" | "equal" | "none";
-    poisonHandler?: (action: GraphActionRecord, error: unknown) => void | Promise<void>;
-}
 interface StartLocalFirstGraphOptions {
     storage: GraphPersistenceAdapter;
     store?: GraphStore$1;
@@ -777,32 +825,11 @@ interface LocalFirstGraphRuntime {
      */
     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;
@@ -828,14 +855,6 @@ declare function hydrateGraphFromStorage(opts: HydrateGraphFromStorageOptions):
     error?: undefined;
 }>;
 declare function startLocalFirstGraph(opts: StartLocalFirstGraphOptions): LocalFirstGraphRuntime;
-interface ResolvedRetryPolicy {
-    maxAttempts: number;
-    initialDelayMs: number;
-    maxDelayMs: number;
-    backoffFactor: number;
-    jitter: "full" | "equal" | "none";
-    poisonHandler?: (action: GraphActionRecord, error: unknown) => void | Promise<void>;
-}
 /**
  * Attempt to replay an action up to `maxAttempts` times. On exhaustion the
  * action goes to "poison" — the optional handler is invoked and the function

package/dist/index.mjs

@@ -1,5 +1,5 @@
-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 { graphStore, useGraphStore, subscribeDevtoolsEvent, getGraphDevtoolsCompatibilityDelegate, subscribeGraphDevtoolsCompatibility, matchesFilter, matchesSearch, compareEntities, emitLegacyDevtoolsEvent, __require } from './chunk-64YZRB56.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-64YZRB56.mjs';
 import { createStore } from 'zustand/vanilla';
 
 // src/errors.ts
@@ -949,6 +949,57 @@ function createSchemaGraphTool(handler) {
     exportGraphSnapshotWithSchemas
   });
 }
+var initialStatus = {
+  phase: "idle",
+  isOnline: true,
+  isSynced: true,
+  pendingActions: 0,
+  lastHydratedAt: null,
+  lastPersistedAt: null,
+  storageKey: null,
+  error: null
+};
+function createGraphSyncStatusStore() {
+  return createStore()((set) => ({
+    status: { ...initialStatus },
+    setStatus: (status) => set((state) => ({ status: { ...state.status, ...status } }))
+  }));
+}
+function createRuntimeScope() {
+  return {
+    pendingActions: /* @__PURE__ */ new Map(),
+    statusStore: createGraphSyncStatusStore()
+  };
+}
+
+// src/replay-retry.ts
+function resolveRetryPolicy(policy) {
+  return {
+    maxAttempts: policy?.maxAttempts ?? 5,
+    initialDelayMs: policy?.initialDelayMs ?? 500,
+    maxDelayMs: policy?.maxDelayMs ?? 3e4,
+    backoffFactor: policy?.backoffFactor ?? 2,
+    jitter: policy?.jitter ?? "equal",
+    poisonHandler: policy?.poisonHandler
+  };
+}
+function computeDelay(policy, attempt) {
+  const base = Math.min(
+    policy.initialDelayMs * Math.pow(policy.backoffFactor, Math.max(0, attempt - 1)),
+    policy.maxDelayMs
+  );
+  switch (policy.jitter) {
+    case "none":
+      return base;
+    case "full":
+      return Math.random() * base;
+    case "equal":
+    default:
+      return base / 2 + Math.random() * (base / 2);
+  }
+}
+
+// src/local-first-runtime.ts
 var DEFAULT_STORAGE_KEY = "prometheus:graph";
 var graphSyncStatusStore = createStore()((set) => ({
   status: {
@@ -968,27 +1019,6 @@ var graphSyncStatusStore = createStore()((set) => ({
     }
   }))
 }));
-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
@@ -1198,31 +1228,6 @@ function cloneGraphSnapshot(storeApi) {
     lists: structuredClone(state.lists)
   };
 }
-function resolveRetryPolicy(policy) {
-  return {
-    maxAttempts: policy?.maxAttempts ?? 5,
-    initialDelayMs: policy?.initialDelayMs ?? 500,
-    maxDelayMs: policy?.maxDelayMs ?? 3e4,
-    backoffFactor: policy?.backoffFactor ?? 2,
-    jitter: policy?.jitter ?? "equal",
-    poisonHandler: policy?.poisonHandler
-  };
-}
-function computeDelay(policy, attempt) {
-  const base = Math.min(
-    policy.initialDelayMs * Math.pow(policy.backoffFactor, Math.max(0, attempt - 1)),
-    policy.maxDelayMs
-  );
-  switch (policy.jitter) {
-    case "none":
-      return base;
-    case "full":
-      return Math.random() * base;
-    case "equal":
-    default:
-      return base / 2 + Math.random() * (base / 2);
-  }
-}
 function sleep(ms) {
   if (ms <= 0) return Promise.resolve();
   return new Promise((r) => setTimeout(r, ms));