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

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# @prometheus-ags/entity-graph-core
+
+## 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Travis James / Prometheus AGS / KnowMe LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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