@prometheus-ags/entity-graph-core 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @prometheus-ags/entity-graph-core
 
+## 4.4.0
+
+### Minor Changes
+
+- **Behavior change: the AG-UI bridge now deletes entities the agent removes
+  from its state.** In 4.3.0 such entities stayed in the graph. Only ids the
+  previous stored (or caller-supplied) state held at a mapped pointer are
+  removed; an id still held by another mapping of the same type is kept; a base
+  reconstructed from a pre-4.4.0 graph never removes anything.
+
+- Streaming-store hardening for agentic UIs.
+
+  **Atomic batched writes without a graph copy.** New `batchGraphWrites(fn)`
+  applies any number of writes across entity types on one immer draft and
+  publishes once; a throw writes nothing. `applyGraphChanges(changes)` is its
+  serialisable, idempotent form. `createGraphTransaction` no longer
+  `structuredClone`s the whole graph when it opens: its rollback baseline is the
+  set of references to the current immutable state, so opening is O(1).
+
+  **Render-only live layer.** `createLiveLayer()` holds ephemeral field values
+  (streaming text) beside the graph: per-entity subscriptions, a merged
+  `read()`, and explicit `commit()` / `commitAll()` / `discard()`. Live values are
+  not graph writes, are not persisted and do not reach devtools.
+
+  **Lossless, ordered AG-UI bridge.** `applyAgUiSnapshot` / `applyAgUiDelta` now
+  store the whole agent state document (`readAgUiState`, so plain fields and
+  root pointers survive), keep collection order in a list (`agUiListKey`), apply
+  RFC 6902 `remove` / `replace` / `move` as entity removals and reorders, publish
+  once per event, never freeze the caller's event objects, and skip an `eventId`
+  that was already applied. Both functions now return `{ applied, state }`
+  instead of `void`.
+
+  **No devtools events in production browsers.** The transaction op-site stream
+  emitted in every browser bundle (`typeof process === "undefined" || ...`). It is
+  now off where `process` is absent unless Vite's `import.meta.env.DEV` is set or
+  `setGraphDevtoolsEmission(true)` is called; Node/SSR keep the
+  `NODE_ENV !== "production"` rule. Defining `__PROMETHEUS_ENTITY_GRAPH_DEVTOOLS__`
+  as `false` removes the emission code from bundles.
+
 ## 4.1.1
 
 ### Patch Changes

package/README.md

@@ -78,6 +78,70 @@ UI components should consume the hooks provided by their framework binding inste
 
 The deprecated core `useGraphStore` name is a StoreApi-shaped alias for `graphStore`, not a React hook. React consumers import the callable `useGraphStore(selector)` hook from `@prometheus-ags/prometheus-entity-management`. See the repository's `release/framework-neutral-core.md` migration contract for the complete boundary.
 
+## Streaming agent state
+
+Four primitives keep a store usable at token rate (all since 4.4.0):
+
+```ts
+import {
+  applyAgUiDelta,
+  applyAgUiSnapshot,
+  applyGraphChanges,
+  batchGraphWrites,
+  createLiveLayer,
+  readAgUiState,
+} from "@prometheus-ags/entity-graph-core";
+
+// 1. Many writes, one notification, no graph copy. A throw writes nothing.
+batchGraphWrites((batch) => {
+  batch.upsertEntity("Message", "m1", { id: "m1", status: "done" });
+  batch.upsertEntity("ToolCall", "t1", { id: "t1", status: "running" });
+  batch.insertIdInList("thread:messages", "m1", "end");
+});
+// The same thing as data (journal, replay); idempotent with the default merge.
+applyGraphChanges([{ op: "remove", type: "Message", id: "draft" }]);
+
+// 2. Render-only live values: not graph writes, not persisted, not in devtools.
+const live = createLiveLayer();
+live.append("Message", "m1", "text", token);        // per token
+live.subscribe("Message", "m1", render);            // live + durable changes
+live.read("Message", "m1");                         // durable entity + live fields
+live.commit("Message", "m1");                       // one durable write
+
+// 3. Lossless AG-UI state: plain fields, order and removals are kept.
+applyAgUiSnapshot({ snapshot }, { mappings, eventId: "41" });
+applyAgUiDelta({ delta }, { mappings, eventId: "42" }); // a replayed id is skipped
+readAgUiState(); // the whole agent state document
+```
+
+`createGraphTransaction` no longer copies the graph when it opens (rollback
+restores references to the immutable previous state). Collection mappings keep
+their order in the list `agUiListKey(mapping)`; items that leave a mapped slice
+are removed. Only ids that the previous agent state held at that pointer are
+removed. Written values are adopted and deep-frozen by the store, so if your
+code keeps mutating an object, write a `structuredClone` of it. The AG-UI bridge
+copies its input for you.
+
+Persisting with `persistGraphToStorage` and hydrating with
+`hydrateGraphFromStorage` round-trips the AG-UI document, its order lists and
+its applied event ids, so a transport that replays after a reload does not
+apply the same delta twice. Live values are not persisted. Commit them before a
+checkpoint if they must survive.
+
+### DevTools events in production
+
+The deprecated `subscribeDevtoolsEvent` stream fed by graph transactions emits
+only where `process` exists and `NODE_ENV !== "production"`, or in a browser
+under Vite's `import.meta.env.DEV`. Plain browser production bundles emit
+nothing. To enable or disable it at runtime, call
+`setGraphDevtoolsEmission(true | false)`. To remove the code from a bundle,
+define `__PROMETHEUS_ENTITY_GRAPH_DEVTOOLS__` as `false`:
+
+```ts
+// vite.config.ts
+export default { define: { __PROMETHEUS_ENTITY_GRAPH_DEVTOOLS__: "false" } };
+```
+
 ## Optional Loro merge strategy
 
 `loro-crdt` remains an optional peer. Node consumers can let core load it at

package/dist/{chunk-64YZRB56.mjs → chunk-T5WSFBXH.mjs}

@@ -158,6 +158,105 @@ function getNestedValue(obj, path) {
   }
   return current;
 }
+
+// src/graph-mutators.ts
+function entityKey(type, id) {
+  return `${type}:${id}`;
+}
+function defaultSyncMetadata() {
+  return { synced: true, origin: "server", updatedAt: null };
+}
+function defaultListState() {
+  return {
+    ids: [],
+    total: null,
+    nextCursor: null,
+    prevCursor: null,
+    hasNextPage: false,
+    hasPrevPage: false,
+    isFetching: false,
+    isFetchingMore: false,
+    error: null,
+    lastError: null,
+    lastFetched: null,
+    stale: false,
+    currentPage: null,
+    pageSize: null
+  };
+}
+function upsertEntityDraft(s, type, id, data) {
+  if (!s.entities[type]) s.entities[type] = {};
+  const key = entityKey(type, id);
+  const strategy = getMergeStrategy(type);
+  const ctx = { type, id, origin: s.syncMetadata[key]?.origin ?? "server", updatedAt: Date.now() };
+  s.entities[type][id] = strategy(s.entities[type][id], data, ctx);
+  if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
+}
+function upsertEntitiesDraft(s, type, entries) {
+  if (!s.entities[type]) s.entities[type] = {};
+  const strategy = getMergeStrategy(type);
+  for (const { id, data } of entries) {
+    const key = entityKey(type, id);
+    const ctx = { type, id, origin: s.syncMetadata[key]?.origin ?? "server", updatedAt: Date.now() };
+    s.entities[type][id] = strategy(s.entities[type][id], data, ctx);
+    if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
+  }
+}
+function replaceEntityDraft(s, type, id, data) {
+  if (!s.entities[type]) s.entities[type] = {};
+  s.entities[type][id] = data;
+  const key = entityKey(type, id);
+  if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
+}
+function removeEntityDraft(s, type, id) {
+  delete s.entities[type]?.[id];
+  delete s.patches[type]?.[id];
+  delete s.entityStates[entityKey(type, id)];
+  delete s.syncMetadata[entityKey(type, id)];
+}
+function patchEntityDraft(s, type, id, patch) {
+  if (!s.patches[type]) s.patches[type] = {};
+  s.patches[type][id] = { ...s.patches[type][id] ?? {}, ...patch };
+}
+function unpatchEntityDraft(s, type, id, keys) {
+  const p = s.patches[type]?.[id];
+  if (!p) return;
+  for (const k of keys) delete p[k];
+}
+function clearPatchDraft(s, type, id) {
+  delete s.patches[type]?.[id];
+}
+function setEntitySyncMetadataDraft(s, type, id, metadata) {
+  const k = entityKey(type, id);
+  s.syncMetadata[k] = { ...s.syncMetadata[k] ?? defaultSyncMetadata(), ...metadata };
+}
+function removeIdFromAllListsDraft(s, type, id) {
+  for (const key of Object.keys(s.lists)) {
+    const list = s.lists[key];
+    if (list.entityType && list.entityType !== type) continue;
+    const idx = list.ids.indexOf(id);
+    if (idx !== -1) {
+      list.ids.splice(idx, 1);
+      if (list.total !== null) list.total -= 1;
+    }
+  }
+}
+function insertIdInListDraft(s, key, id, position) {
+  if (!s.lists[key]) s.lists[key] = defaultListState();
+  const ids = s.lists[key].ids;
+  const ex = ids.indexOf(id);
+  if (ex !== -1) ids.splice(ex, 1);
+  if (position === "start") ids.unshift(id);
+  else if (position === "end") ids.push(id);
+  else ids.splice(position, 0, id);
+}
+function setListIdsDraft(s, key, ids, entityType) {
+  if (!s.lists[key]) s.lists[key] = defaultListState();
+  s.lists[key].ids = Array.from(new Set(ids));
+  if (entityType !== void 0) s.lists[key].entityType = entityType;
+}
+
+// src/graph.ts
 var EMPTY_IDS = [];
 var EMPTY_ENTITY_STATE = {
   isFetching: false,
@@ -189,19 +288,10 @@ var EMPTY_LIST_STATE = {
 function defaultEntityState() {
   return { ...EMPTY_ENTITY_STATE };
 }
-function defaultSyncMetadata() {
-  return { ...EMPTY_SYNC_METADATA };
-}
-function defaultListState() {
-  return { ...EMPTY_LIST_STATE, ids: [] };
-}
-function ek(type, id) {
-  return `${type}:${id}`;
-}
 var snapshotCache = /* @__PURE__ */ new Map();
 var mergedReadCache = /* @__PURE__ */ new Map();
 function readCachedEntitySnapshot(type, id, base, patch, metadata) {
-  const key = ek(type, id);
+  const key = entityKey(type, id);
   const cached = snapshotCache.get(key);
   if (cached && cached.base === base && cached.patch === patch && cached.metadata === metadata) {
     return cached.snapshot;
@@ -224,24 +314,8 @@ function createGraphStore() {
         entityStates: {},
         syncMetadata: {},
         lists: {},
-        upsertEntity: (type, id, data) => set((s) => {
-          if (!s.entities[type]) s.entities[type] = {};
-          const key = ek(type, id);
-          const strategy = getMergeStrategy(type);
-          const ctx = { type, id, origin: s.syncMetadata[key]?.origin ?? "server", updatedAt: Date.now() };
-          s.entities[type][id] = strategy(s.entities[type][id], data, ctx);
-          if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
-        }),
-        upsertEntities: (type, entries) => set((s) => {
-          if (!s.entities[type]) s.entities[type] = {};
-          const strategy = getMergeStrategy(type);
-          for (const { id, data } of entries) {
-            const key = ek(type, id);
-            const ctx = { type, id, origin: s.syncMetadata[key]?.origin ?? "server", updatedAt: Date.now() };
-            s.entities[type][id] = strategy(s.entities[type][id], data, ctx);
-            if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
-          }
-        }),
+        upsertEntity: (type, id, data) => set((s) => upsertEntityDraft(s, type, id, data)),
+        upsertEntities: (type, entries) => set((s) => upsertEntitiesDraft(s, type, entries)),
         ingestFetchedList: (type, entries, options = {}) => set((s) => {
           const fetchedAt = Date.now();
           const ids = entries.map(({ id }) => id);
@@ -253,7 +327,7 @@ function createGraphStore() {
           for (const batch of batches) {
             if (!s.entities[batch.type]) s.entities[batch.type] = {};
             for (const { id } of batch.entries) {
-              const key = ek(batch.type, id);
+              const key = entityKey(batch.type, id);
               if (!origins.has(key)) {
                 origins.set(key, s.syncMetadata[key]?.origin ?? "server");
               }
@@ -262,7 +336,7 @@ function createGraphStore() {
           for (const batch of batches) {
             const strategy = getMergeStrategy(batch.type);
             for (const { id, data } of batch.entries) {
-              const key = ek(batch.type, id);
+              const key = entityKey(batch.type, id);
               const ctx = {
                 type: batch.type,
                 id,
@@ -275,7 +349,7 @@ function createGraphStore() {
           const completed = /* @__PURE__ */ new Set();
           for (const batch of batches) {
             for (const { id } of batch.entries) {
-              const key = ek(batch.type, id);
+              const key = entityKey(batch.type, id);
               if (completed.has(key)) continue;
               completed.add(key);
               if (!s.entityStates[key]) s.entityStates[key] = defaultEntityState();
@@ -295,7 +369,7 @@ function createGraphStore() {
             const base = s.entities[type]?.[id];
             if (!base) return null;
             const patch = s.patches[type]?.[id];
-            const metadata = s.syncMetadata[ek(type, id)] ?? defaultSyncMetadata();
+            const metadata = s.syncMetadata[entityKey(type, id)] ?? defaultSyncMetadata();
             return {
               ...base,
               ...patch ?? {},
@@ -355,43 +429,24 @@ function createGraphStore() {
             s.lists[key].isFetching = false;
           }
         }),
-        replaceEntity: (type, id, data) => set((s) => {
-          if (!s.entities[type]) s.entities[type] = {};
-          s.entities[type][id] = data;
-          const key = ek(type, id);
-          if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
-        }),
-        removeEntity: (type, id) => set((s) => {
-          delete s.entities[type]?.[id];
-          delete s.patches[type]?.[id];
-          delete s.entityStates[ek(type, id)];
-          delete s.syncMetadata[ek(type, id)];
-        }),
-        patchEntity: (type, id, patch) => set((s) => {
-          if (!s.patches[type]) s.patches[type] = {};
-          s.patches[type][id] = { ...s.patches[type][id] ?? {}, ...patch };
-        }),
-        unpatchEntity: (type, id, keys) => set((s) => {
-          const p = s.patches[type]?.[id];
-          if (!p) return;
-          for (const k of keys) delete p[k];
-        }),
-        clearPatch: (type, id) => set((s) => {
-          delete s.patches[type]?.[id];
-        }),
+        replaceEntity: (type, id, data) => set((s) => replaceEntityDraft(s, type, id, data)),
+        removeEntity: (type, id) => set((s) => removeEntityDraft(s, type, id)),
+        patchEntity: (type, id, patch) => set((s) => patchEntityDraft(s, type, id, patch)),
+        unpatchEntity: (type, id, keys) => set((s) => unpatchEntityDraft(s, type, id, keys)),
+        clearPatch: (type, id) => set((s) => clearPatchDraft(s, type, id)),
         setEntityFetching: (type, id, fetching) => set((s) => {
-          const k = ek(type, id);
+          const k = entityKey(type, id);
           if (!s.entityStates[k]) s.entityStates[k] = defaultEntityState();
           s.entityStates[k].isFetching = fetching;
         }),
         setEntityError: (type, id, error) => set((s) => {
-          const k = ek(type, id);
+          const k = entityKey(type, id);
           if (!s.entityStates[k]) s.entityStates[k] = defaultEntityState();
           s.entityStates[k].error = error;
           s.entityStates[k].isFetching = false;
         }),
         setEntityFetched: (type, id) => set((s) => {
-          const k = ek(type, id);
+          const k = entityKey(type, id);
           if (!s.entityStates[k]) s.entityStates[k] = defaultEntityState();
           s.entityStates[k].lastFetched = Date.now();
           s.entityStates[k].isFetching = false;
@@ -400,16 +455,13 @@ function createGraphStore() {
           s.syncMetadata[k] = { ...s.syncMetadata[k] ?? defaultSyncMetadata(), synced: true, origin: "server", updatedAt: Date.now() };
         }),
         setEntityStale: (type, id, stale) => set((s) => {
-          const k = ek(type, id);
+          const k = entityKey(type, id);
           if (!s.entityStates[k]) s.entityStates[k] = defaultEntityState();
           s.entityStates[k].stale = stale;
         }),
-        setEntitySyncMetadata: (type, id, metadata) => set((s) => {
-          const k = ek(type, id);
-          s.syncMetadata[k] = { ...s.syncMetadata[k] ?? defaultSyncMetadata(), ...metadata };
-        }),
+        setEntitySyncMetadata: (type, id, metadata) => set((s) => setEntitySyncMetadataDraft(s, type, id, metadata)),
         clearEntitySyncMetadata: (type, id) => set((s) => {
-          delete s.syncMetadata[ek(type, id)];
+          delete s.syncMetadata[entityKey(type, id)];
         }),
         setListResult: (key, ids, meta) => set((s) => {
           const ex = s.lists[key] ?? defaultListState();
@@ -423,26 +475,8 @@ function createGraphStore() {
           const ex = s.lists[key] ?? defaultListState();
           s.lists[key] = { ...ex, ...meta ?? {}, ids: Array.from(/* @__PURE__ */ new Set([...ids, ...ex.ids])), isFetching: false, isFetchingMore: false, error: null, lastError: null, stale: false, lastFetched: Date.now() };
         }),
-        removeIdFromAllLists: (type, id) => set((s) => {
-          for (const key of Object.keys(s.lists)) {
-            const list = s.lists[key];
-            if (list.entityType && list.entityType !== type) continue;
-            const idx = list.ids.indexOf(id);
-            if (idx !== -1) {
-              list.ids.splice(idx, 1);
-              if (list.total !== null) list.total -= 1;
-            }
-          }
-        }),
-        insertIdInList: (key, id, position) => set((s) => {
-          if (!s.lists[key]) s.lists[key] = defaultListState();
-          const ids = s.lists[key].ids;
-          const ex = ids.indexOf(id);
-          if (ex !== -1) ids.splice(ex, 1);
-          if (position === "start") ids.unshift(id);
-          else if (position === "end") ids.push(id);
-          else ids.splice(position, 0, id);
-        }),
+        removeIdFromAllLists: (type, id) => set((s) => removeIdFromAllListsDraft(s, type, id)),
+        insertIdInList: (key, id, position) => set((s) => insertIdInListDraft(s, key, id, position)),
         setListFetching: (key, fetching) => set((s) => {
           if (!s.lists[key]) s.lists[key] = defaultListState();
           s.lists[key].isFetching = fetching;
@@ -466,7 +500,7 @@ function createGraphStore() {
         }),
         invalidateEntity: (type, id) => set((s) => {
           if (id) {
-            const k = ek(type, id);
+            const k = entityKey(type, id);
             if (s.entityStates[k]) s.entityStates[k].stale = true;
           } else {
             for (const k of Object.keys(s.entityStates)) if (k.startsWith(`${type}:`)) s.entityStates[k].stale = true;
@@ -484,12 +518,12 @@ function createGraphStore() {
           const s = get();
           const base = s.entities[type]?.[id];
           if (!base) {
-            mergedReadCache.delete(ek(type, id));
+            mergedReadCache.delete(entityKey(type, id));
             return null;
           }
           const patch = s.patches[type]?.[id];
           if (!patch) return base;
-          const key = ek(type, id);
+          const key = entityKey(type, id);
           const cached = mergedReadCache.get(key);
           if (cached && cached.base === base && cached.patch === patch) {
             return cached.merged;
@@ -502,11 +536,11 @@ function createGraphStore() {
           const s = get();
           const base = s.entities[type]?.[id];
           if (!base) {
-            snapshotCache.delete(ek(type, id));
+            snapshotCache.delete(entityKey(type, id));
             return null;
           }
           const patch = s.patches[type]?.[id];
-          const metadata = s.syncMetadata[ek(type, id)] ?? EMPTY_SYNC_METADATA;
+          const metadata = s.syncMetadata[entityKey(type, id)] ?? EMPTY_SYNC_METADATA;
           return readCachedEntitySnapshot(
             type,
             id,
@@ -959,6 +993,6 @@ function subscribeGraphDevtoolsCompatibility(store, listener) {
   };
 }
 
-export { EMPTY_ENTITY_STATE, EMPTY_IDS, EMPTY_LIST_STATE, EMPTY_SYNC_METADATA, __require, applyView, attachGlobalListeners, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createGraphStore, dedupe, emitLegacyDevtoolsEvent, fetchEntity, fetchList, findInsertionIndex, getActiveSubscriberCount, getEngineOptions, getGraphDevtoolsCompatibilityDelegate, getMergeStrategy, getRegisteredSchemas, getSchema, graphStore, hasMergeStrategy, lwwStrategy, matchesFilter, matchesSearch, readRelations, registerGraphDevtoolsCompatibilityDelegate, registerGraphDevtoolsCompatibilityFactory, registerMergeStrategy, registerSchema, registerSubscriber, serializeKey, setDefaultMergeStrategy, startGarbageCollector, stopGarbageCollector, subscribeDevtoolsEvent, subscribeGraphDevtoolsCompatibility, subscribeSubscriberStats, unregisterSubscriber, useGraphStore };
-//# sourceMappingURL=chunk-64YZRB56.mjs.map
-//# sourceMappingURL=chunk-64YZRB56.mjs.map
+export { EMPTY_ENTITY_STATE, EMPTY_IDS, EMPTY_LIST_STATE, EMPTY_SYNC_METADATA, __require, applyView, attachGlobalListeners, cascadeInvalidation, checkCompleteness, clearPatchDraft, compareEntities, configureEngine, createGraphStore, dedupe, emitLegacyDevtoolsEvent, fetchEntity, fetchList, findInsertionIndex, getActiveSubscriberCount, getEngineOptions, getGraphDevtoolsCompatibilityDelegate, getMergeStrategy, getRegisteredSchemas, getSchema, graphStore, hasMergeStrategy, insertIdInListDraft, lwwStrategy, matchesFilter, matchesSearch, patchEntityDraft, readRelations, registerGraphDevtoolsCompatibilityDelegate, registerGraphDevtoolsCompatibilityFactory, registerMergeStrategy, registerSchema, registerSubscriber, removeEntityDraft, removeIdFromAllListsDraft, replaceEntityDraft, serializeKey, setDefaultMergeStrategy, setEntitySyncMetadataDraft, setListIdsDraft, startGarbageCollector, stopGarbageCollector, subscribeDevtoolsEvent, subscribeGraphDevtoolsCompatibility, subscribeSubscriberStats, unpatchEntityDraft, unregisterSubscriber, upsertEntitiesDraft, upsertEntityDraft, useGraphStore };
+//# sourceMappingURL=chunk-T5WSFBXH.mjs.map
+//# sourceMappingURL=chunk-T5WSFBXH.mjs.map