@prometheus-ags/entity-graph-core 3.0.0-alpha.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# @prometheus-ags/entity-graph-core
+
+## 3.0.0
+
+### Patch Changes
+
+- 30fc348: Certify the React 19 and Vite 8 release showcase with normalized cross-view
+  updates, local/remote/hybrid queries, optimistic confirmation and rollback,
+  relationship invalidation, realtime coalescing, PGlite persistence, Loro
+  convergence, Suspense and error-boundary lifecycle behavior, DevTools, and
+  browser accessibility evidence.
+- 7b64d76: Scope engine dedupe, subscribers, fetches, React hooks, mutations, and realtime
+  writes to an application-owned graph so concurrent Next.js requests can
+  dehydrate and hydrate without sharing process-global entity state.
+
+## 3.0.0-rc.1
+
+### Patch Changes
+
+- Preserve coalesced realtime update operations while merging repeated patches, so a burst does not degrade into a data-less upsert that the graph discards.
+- Accept a public `LoroModuleLoader` callback in `createLoroMergeStrategy` so browser bundlers can include the optional `loro-crdt` peer without making it a core dependency.
+
+## 3.0.0
+
+### Major Changes
+
+- v3.0.0 — Universal Platform Evolution
+
+  Evolves the React-only entity graph into a cross-platform, multi-framework,
+  AI-native, local-first ecosystem.
+  - **Monorepo split (breaking, but consumer-safe):** the framework-agnostic core
+    is extracted into `@prometheus-ags/entity-graph-core` (zero React). The
+    published `@prometheus-ags/prometheus-entity-management` package is the React
+    binding over the vanilla core. Existing React hook names remain available,
+    while core-only imperative consumers migrate from `useGraphStore.getState()`
+    to `graphStore.getState()`; the deprecated core alias remains through the
+    next-major removal window.
+  - **New framework bindings:** `entity-graph-svelte` (Svelte 5 runes),
+    `entity-graph-solid`, `entity-graph-web-components` (Lit 3), `entity-graph-alpine`,
+    `entity-graph-htmx` (Node SSE fragment server).
+  - **Peer sync:** `entity-graph-sync` with a pluggable SyncProvider — Yjs (default)
+    and Loro (reusing the 2.2.0 merge seam).
+  - **AI-native:** `entity-graph-a2a` plus `a2ui-react` with official A2UI
+    v0.9.1 rendering and default-deny graph actions; legacy
+    EntityChat/Copilot/Stream/Diff/Approval APIs live under `./ag-ui`.
+  - **Codegen contract:** `entity-graph-sdl` (schema → validated IR).
+  - **Native (published outside npm):** `entity-graph-cli` + `entity-graph-mcp`
+    (Rust, via crates.io), `entity-graph-tauri` (Tauri v2 plugin), and
+    `entity_graph_flutter` (Riverpod 3, via pub.dev).
+
+  All integrations ship as optional peer dependencies; the core bundle stays
+  `zustand + immer`.

package/README.md

@@ -0,0 +1,124 @@
+# `@prometheus-ags/entity-graph-core`
+
+Framework-neutral normalized entity graph for the Prometheus entity-management ecosystem. The package contains no React code. React, Svelte, Solid, Alpine, Lit, Tauri, and other bindings share this graph so an entity is stored once and every subscribed view observes the same value.
+
+## Install
+
+```bash
+pnpm add @prometheus-ags/entity-graph-core
+```
+
+The core runtime depends on Zustand and Immer. Optional integrations such as AG-UI, Loro, and Tauri SQL are loaded only when their adapters are used.
+
+## The data model
+
+The graph keeps three distinct structures:
+
+- `entities[type][id]` is canonical server-confirmed data.
+- `patches[type][id]` contains local UI-only augmentation merged at read time.
+- `lists[queryKey].ids` contains ordered identifiers, never copied entity records.
+
+This ID-only list rule is what makes cross-view updates reliable: changing one canonical entity updates every list, detail view, and relation that reads that identifier.
+
+## Register a transport
+
+Register I/O once at application boot. Framework hooks call store and engine methods; transports and adapters own external communication.
+
+```ts
+import {
+  registerEntityTransport,
+} from "@prometheus-ags/entity-graph-core";
+
+registerEntityTransport("users", {
+  identify: (user) => user.id,
+  authoritative: false,
+  async list(query) {
+    const response = await fetch(`/api/users?limit=${query.limit ?? 50}`, {
+      signal: query.signal,
+    });
+    const rows = await response.json();
+    return { rows, total: rows.length, nextCursor: null };
+  },
+});
+```
+
+Custom transports implement `EntityTransport<T>` with `identify`, `authoritative`, and `list`; `get` and `subscribe` are optional.
+
+## Create, read, and update graphs outside a UI framework
+
+```ts
+import {
+  createGraphStore,
+  graphStore,
+} from "@prometheus-ags/entity-graph-core";
+
+const graph = graphStore.getState();
+
+graph.upsertEntity("users", "user-1", {
+  id: "user-1",
+  name: "Ada Lovelace",
+});
+
+graph.setListResult("users:active", ["user-1"], {
+  total: 1,
+  hasNextPage: false,
+});
+
+const user = graphStore.getState().readEntity("users", "user-1");
+
+// Isolated stores are useful for SSR requests, tests, and workers.
+const requestGraph = createGraphStore();
+requestGraph.getState().upsertEntity("users", "request-user", {
+  id: "request-user",
+  name: "Grace Hopper",
+});
+```
+
+UI components should consume the hooks provided by their framework binding instead of reading the store directly.
+
+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.
+
+## Optional Loro merge strategy
+
+`loro-crdt` remains an optional peer. Node consumers can let core load it at
+runtime; browser bundlers should provide a statically visible loader:
+
+```ts
+import {
+  createLoroMergeStrategy,
+  registerMergeStrategy,
+} from "@prometheus-ags/entity-graph-core";
+
+const strategy = await createLoroMergeStrategy(
+  () => import("loro-crdt"),
+);
+registerMergeStrategy("Document", strategy);
+```
+
+The public `LoroModuleLoader` type describes this callback. Supplying it does
+not make Loro part of the mandatory core bundle.
+
+## Major capabilities
+
+- request deduplication, stale-while-revalidate, subscriber tracking, and garbage collection
+- transport-neutral filtering, sorting, search, pagination, and incremental views
+- realtime adapters with coalesced graph writes
+- graph actions, transactions, effects, snapshots, and time travel
+- local-first persistence and retryable action replay
+- schema and relation registries with cascade invalidation
+- AG-UI snapshot/delta ingestion and JSON Patch
+- REST, WebSocket, Supabase, GraphQL, ElectricSQL, PGlite, Tauri SQL, SurrealDB, and Flint adapter seams
+- framework-neutral table row models and faceting
+
+## Module support
+
+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`.
+
+Both paths are selected through conditional package exports.
+
+## License
+
+MIT