@prometheus-ags/entity-graph-core 3.0.4 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @prometheus-ags/entity-graph-core
 
+## 3.1.0
+
+## 3.0.5
+
+### Patch Changes
+
+- Resolve imperative graph access against the active graph instead of the package
+  singleton, so `GraphStoreProvider` scopes `useGraphStore.getState()`,
+  `.setState()`, `.subscribe()` and `.getInitialState()` (issue #42).
+
+  3.0.4 replaced the copied StoreApi with delegates that warned but still targeted
+  the singleton, which left consumers using the documented imperative API with no
+  isolation. The React binding now proxies those methods, resolving per call.
+
+  New in `entity-graph-core`:
+  - `runWithGraphStore(store, fn)` — an `AsyncLocalStorage` request scope, so
+    concurrent server renders never share entity state.
+  - `prepareGraphStoreScope()` — awaited once during startup on **pure-ESM**
+    servers, where there is no synchronous `require` to load `node:async_hooks`.
+    Without it request scoping degrades to a module-level store and warns.
+  - `setActiveGraphStore(store)` — the module-level active store, set by
+    `GraphStoreProvider` on mount and restored on unmount.
+  - `resolveActiveGraphStore(fallback)` — request scope → module-level store →
+    fallback.
+
+  `node:async_hooks` is loaded lazily and never statically imported, so browser
+  bundles are unaffected. With no provider and no request scope, behaviour is
+  unchanged from 3.0.4, and the deprecation warning is gone because the methods
+  now do what callers expected.
+
 ## 3.0.4
 
 ## 3.0.3

package/README.md

@@ -98,6 +98,252 @@ registerMergeStrategy("Document", strategy);
 The public `LoroModuleLoader` type describes this callback. Supplying it does
 not make Loro part of the mandatory core bundle.
 
+## Optional DevTools controller
+
+The versioned DevTools runtime is isolated behind the
+`@prometheus-ags/entity-graph-core/devtools` export. Normal application imports
+do not expose the controller API.
+
+```ts
+import { createGraphStore } from "@prometheus-ags/entity-graph-core";
+import {
+  attachGraphDevtools,
+  createGraphDevtoolsClient,
+} from "@prometheus-ags/entity-graph-core/devtools";
+
+const store = createGraphStore();
+const attachment = attachGraphDevtools(store, {
+  storeId: "admin-graph",
+  historyLimit: 500,
+});
+
+if (attachment.controller) {
+  const client = createGraphDevtoolsClient(
+    attachment.controller.storeId,
+    attachment.controller.connect("local-inspector"),
+  );
+
+  const snapshot = await client.request("get-snapshot");
+  client.disconnect();
+}
+
+attachment.detach();
+```
+
+### Inspect entities, rendered views, and relationships
+
+The controller projects inspection state on demand from the owning graph. It
+does not copy entity values into a second store:
+
+```ts
+const attachment = attachGraphDevtools(store, {
+  storeId: "admin-graph",
+  values: { mode: "include" },
+});
+
+const controller = attachment.controller;
+if (controller) {
+  const view = controller.registerView({
+    viewId: "users:active-table",
+    label: "Active users",
+    kind: "list",
+    entityType: "users",
+    queryKey: "users:active",
+  });
+
+  // Call this whenever the rendered membership changes.
+  view.updateMembership(["user-1", "user-2"]);
+
+  const entities = controller.getEntityRecords();
+  const views = controller.getViews();
+  const relationships = controller.getRelationships();
+
+  view.unregister();
+}
+```
+
+Entity records keep the canonical server-confirmed original, local graph patch,
+and merged live value distinct. `dirtyReasons` names patched fields and
+unsynchronized state; fetch/sync timestamps, typed fetch errors, store-local
+revisions, and the stable IDs of views displaying the entity are projected
+beside them. Missing canonical rows retained only by patch or metadata state are
+reported as `presence: "missing-canonical"`.
+
+View registrations are token-scoped. Duplicate registrations for one stable
+`viewId` share the projected view but retain independent lifetimes, so one
+consumer cannot unregister another. List views include current graph/list
+statistics, and membership is available in both directions.
+
+Relationships are derived from the existing CRUD schema registry and current
+merged graph values. `belongsTo`, reverse `hasMany`, and `manyToMany` edges are
+reported as `resolved` or `missing-target`; DevTools does not create a parallel
+relationship registry.
+
+### Preview and restore a local patch
+
+Preview commands write through the graph's existing patch layer, so every live
+consumer observes the proposed value:
+
+```ts
+const preview = await client.request("preview-entity-patch", {
+  type: "users",
+  id: "user-1",
+  patch: { displayName: "Proposed name" },
+});
+
+if (preview.ok && "previewId" in preview.result) {
+  const restore = await client.request("restore-entity-preview", {
+    previewId: preview.result.previewId,
+  });
+}
+```
+
+The receipt captures the exact prior patch. Restore replaces that patch
+atomically only when no intervening canonical or patch publication touched the
+entity. Otherwise it returns a typed `conflict` receipt and leaves current graph
+state unchanged. Fetch/sync metadata-only publications do not cause false
+conflicts. Only one active preview is retained per entity, and receipts are
+discarded with their controller.
+
+The same value policy governs events, entity records, and preview receipts.
+Under the default metadata-only policy, value positions contain an explicit
+`{ $type: "hidden-by-policy" }` marker. Hosts must opt into `mode: "include"`
+before canonical values, patches, merged values, or receipt values can cross the
+inspection boundary.
+
+The versioned conformance fixture is published at
+`@prometheus-ags/entity-graph-core/devtools/fixtures/entity-inspection-v1.json`.
+Its byte-identical source copy under `packages/entity_graph_flutter` freezes the
+TypeScript/Flutter wire semantics; changing those semantics requires a new
+fixture version.
+
+Node ESM consumers import the JSON fixture with an import attribute:
+
+```ts
+import fixture from "@prometheus-ags/entity-graph-core/devtools/fixtures/entity-inspection-v1.json"
+  with { type: "json" };
+```
+
+### Rewind controller-owned snapshot history
+
+Each active controller captures one initial attach baseline and the complete
+mutable graph data slice after every semantic graph publication. Snapshot
+payloads, stable cursors, imported candidates, rewind state, and the protected
+live head stay inside that controller; UI code renders status and submits
+intent rather than owning a second history ring.
+
+```ts
+const attachment = attachGraphDevtools(store, {
+  storeId: "admin-graph",
+  snapshotLimit: 50,
+  snapshotBytesLimit: 10 * 1024 * 1024,
+});
+
+const controller = attachment.controller;
+if (controller) {
+  const status = controller.getSnapshotHistoryStatus();
+  const cursor = status.newestCursor;
+
+  if (cursor !== null) {
+    const rewind = controller.rewind(cursor);
+    if (rewind?.status === "rewound") {
+      // Every graph subscriber now reads the selected historical state.
+      controller.returnToLive();
+    }
+  }
+}
+```
+
+Count and byte ceilings both apply; eviction always removes whole oldest
+snapshots. A cursor is never reused. Rewinding an evicted, cleared, or
+unavailable capture returns a typed `expired-history` receipt with the current
+retained range and never mutates the graph. Oversize captures remain visible as
+`unavailable` metadata rather than retaining a partial graph.
+
+The first rewind protects an exact deep clone of the live head. Explicit
+return-to-live restores that clone through the Zustand publication boundary.
+If an application mutation occurs while rewound, DevTools first emits a live
+transition with `reason: "mutation"`, then emits and snapshots the completed
+mutation as the new branch; the former protected future is released.
+
+History imports are inert until confirmation. `inspectHistoryImport()` accepts
+only the current protocol version, the same controller store ID, ordered stable
+cursors, JSON-safe complete graph data, and the controller's count/byte budget.
+`confirmHistoryImport(candidateId, cursor)` is one-shot and restores only the
+exact inspected candidate. Inspection receipts and time-travel events expose
+metadata, not snapshot values.
+
+The deprecated root functions (`recordGraphSnapshot`,
+`restoreGraphSnapshot*`, `stepTimeTravel`, and `getTimeTravelState`) are a thin
+compatibility facade over the selected store's controller. They own no graph
+payloads or cursors and return unavailable results until the explicit
+`@prometheus-ags/entity-graph-core/devtools` module has been loaded. New tools
+should use the controller's stable cursors and explicit return-to-live API.
+
+The versioned time-travel fixture is published at
+`@prometheus-ags/entity-graph-core/devtools/fixtures/time-travel-v1.json`. Its
+byte-identical Flutter source copy freezes retention, rewind/live, branching,
+expired-cursor, and confirmed-import semantics for the later Dart controller.
+
+Each store owns one reference-counted controller. Attachments to the same store
+share its event sequence and bounded history; separate stores never share
+events, commands, clients, or teardown. The first active attachment determines
+that controller's identifier, limits, and value policy until its final
+attachment detaches.
+
+Set `enabled: false` when a host should skip creating a particular attachment.
+This is an attachment-level no-op, not a global kill switch: it never tears
+down a controller still referenced by another attachment. Detach every active
+attachment to stop observation for that store.
+
+The controller observes the Zustand publication boundary, so transactions,
+adapter writes, hydration, rollback, and direct `store.setState` changes use the
+same semantic event stream. Events carry protocol version, store and event IDs,
+sequence/correlation data, before/after graph counts, and categorized changes.
+
+The deprecated root `subscribeDevtoolsEvent` API remains the original
+history-free graph-transaction op-site stream. It does not attach this
+controller and does not observe arbitrary direct `store.setState` writes. New
+inspection tools should use this versioned subpath; the separate root shim
+exists only for compatibility and keeps its incremental patch payloads.
+
+### DevTools data boundary
+
+Entity and patch values are omitted by default. Events contain metadata and
+counts unless the host explicitly opts into values and supplies any required
+redaction policy:
+
+```ts
+const attachment = attachGraphDevtools(store, {
+  values: {
+    mode: "include",
+    redact(value, context) {
+      if (context.category !== "entity" || !value || typeof value !== "object") {
+        return value;
+      }
+      const { accessToken: _secret, ...safe } = value as Record<string, unknown>;
+      return safe;
+    },
+  },
+});
+```
+
+The current v1 redactor receives each whole changed value, represented by an
+empty `context.fieldPath`. `context.destination` distinguishes retained event
+history from on-demand inspection. Nested field paths are reserved for later
+field-level inspection. A throwing redactor marks that change with
+`valueState: "redaction-error"` and exposes neither the exception nor the
+original value.
+
+History is bounded by both event count and encoded bytes. Oversized included
+values are removed before an event is retained or delivered; if metadata alone
+still exceeds the per-event limit, `changesOmitted` records the explicit loss.
+Redactor and
+observer failures are isolated from graph writes, disconnected clients cannot
+continue issuing commands, and the controller stops observing the store after
+the final detach. A transport adapter is responsible for preserving the same
+store/client boundary when messages leave the process.
+
 ## Major capabilities
 
 - request deduplication, stale-while-revalidate, subscriber tracking, and garbage collection
@@ -116,6 +362,8 @@ The package publishes loader-specific artifacts and declarations:
 
 - Node ESM and modern bundlers use `dist/index.mjs` with `dist/index.d.ts`.
 - Node CommonJS uses `dist/index.cjs` with `dist/index.d.cts`.
+- DevTools ESM uses `dist/devtools.mjs` with `dist/devtools.d.ts`.
+- DevTools CommonJS uses `dist/devtools.cjs` with `dist/devtools.d.cts`.
 
 Both paths are selected through conditional package exports.