@prometheus-ags/entity-graph-core 3.0.5 → 3.2.0

package/fixtures/devtools/README.md

@@ -0,0 +1,37 @@
+# DevTools inspection fixtures
+
+`entity-inspection-v1.json` is the normative, versioned conformance fixture for
+the transport-independent entity-inspection projection. The byte-identical copy
+under `packages/entity_graph_flutter/fixtures/devtools/` is consumed by the
+Dart/Flutter implementation. The assembled integration gate must reject drift
+between the two copies.
+
+The fixture freezes these cross-runtime semantics:
+
+- `canonical` is the server-confirmed original, `patch` is the local overlay,
+  and `merged` is the live value rendered by graph consumers.
+- `dirtyReasons` explains field-level local changes and entity-level sync state;
+  `dirty` is true when that array is non-empty.
+- All wire timestamps are UTC ISO-8601 strings. Missing values are explicit
+  `null`; omitted fields are not interchangeable with `null`.
+- View identities are stable host-provided strings. Membership is represented
+  in both view-to-entity and entity-to-view directions and must agree.
+- `subscriberCount` is the number of active rendered registrations for a view;
+  it is independent of the cumulative `renderCount`.
+- Relationships come only from the existing entity schema registry and expose
+  unresolved foreign keys as `missing-target` rather than inventing entities.
+- A preview receipt owns the exact prior patch and the entity revision produced
+  by preview application. Restore succeeds only at that revision; any later
+  canonical or patch mutation returns the typed conflict receipt unchanged.
+
+The JSON document is data, not a second graph state or a persistence format.
+Production projections are derived on demand from the owning graph store.
+
+`time-travel-v1.json` is the normative cross-runtime contract for controller-
+owned snapshot history. Its byte-identical Flutter copy freezes the complete
+five-field graph data shape, stable cursor and expiry semantics, rewind/live
+receipts, mutation-while-rewound ordering, and inert/confirmed import flow.
+The conformance harness attaches the fixture to the declared `time-a` store;
+consumers must attach that store ID or replace it consistently before import.
+Snapshot values remain local controller data; the fixture is conformance input,
+not a persistence or unbounded history format.

package/fixtures/devtools/entity-inspection-v1.json

@@ -0,0 +1,304 @@
+{
+  "fixture": "prometheus.entity-graph.devtools.entity-inspection",
+  "fixtureVersion": 1,
+  "protocol": "prometheus.entity-graph.devtools",
+  "protocolVersion": 1,
+  "storeId": "fixture-store",
+  "capturedAt": "2026-08-29T15:04:05.000Z",
+  "entityRecords": [
+    {
+      "key": "Project:p1",
+      "type": "Project",
+      "id": "p1",
+      "presence": "present",
+      "canonical": {
+        "id": "p1",
+        "name": "Apollo",
+        "ownerId": "u1",
+        "status": "active"
+      },
+      "patch": {
+        "name": "Apollo RC",
+        "status": "review"
+      },
+      "merged": {
+        "id": "p1",
+        "name": "Apollo RC",
+        "ownerId": "u1",
+        "status": "review"
+      },
+      "dirty": true,
+      "dirtyReasons": [
+        {
+          "kind": "local-patch",
+          "field": "name",
+          "change": "changed"
+        },
+        {
+          "kind": "local-patch",
+          "field": "status",
+          "change": "changed"
+        },
+        {
+          "kind": "sync-state",
+          "field": null,
+          "change": "unsynced"
+        }
+      ],
+      "entityState": {
+        "isFetching": false,
+        "lastFetchedAt": "2026-08-29T15:03:00.000Z",
+        "stale": false,
+        "error": null
+      },
+      "sync": {
+        "synced": false,
+        "origin": "optimistic",
+        "updatedAt": "2026-08-29T15:04:00.000Z"
+      },
+      "revision": 15,
+      "viewIds": [
+        "project-detail:p1",
+        "project-list:active"
+      ]
+    },
+    {
+      "key": "Project:p2",
+      "type": "Project",
+      "id": "p2",
+      "presence": "present",
+      "canonical": {
+        "id": "p2",
+        "name": "Hermes",
+        "ownerId": "u-missing",
+        "status": "active"
+      },
+      "patch": null,
+      "merged": {
+        "id": "p2",
+        "name": "Hermes",
+        "ownerId": "u-missing",
+        "status": "active"
+      },
+      "dirty": false,
+      "dirtyReasons": [],
+      "entityState": {
+        "isFetching": false,
+        "lastFetchedAt": "2026-08-29T15:02:00.000Z",
+        "stale": true,
+        "error": {
+          "kind": "entity-fetch",
+          "message": "Background refresh failed",
+          "retryable": true
+        }
+      },
+      "sync": {
+        "synced": true,
+        "origin": "server",
+        "updatedAt": "2026-08-29T15:02:00.000Z"
+      },
+      "revision": 8,
+      "viewIds": [
+        "project-list:active"
+      ]
+    },
+    {
+      "key": "User:u1",
+      "type": "User",
+      "id": "u1",
+      "presence": "present",
+      "canonical": {
+        "id": "u1",
+        "displayName": "Ada"
+      },
+      "patch": null,
+      "merged": {
+        "id": "u1",
+        "displayName": "Ada"
+      },
+      "dirty": false,
+      "dirtyReasons": [],
+      "entityState": {
+        "isFetching": false,
+        "lastFetchedAt": null,
+        "stale": false,
+        "error": null
+      },
+      "sync": {
+        "synced": true,
+        "origin": "server",
+        "updatedAt": "2026-08-29T14:59:00.000Z"
+      },
+      "revision": 3,
+      "viewIds": []
+    }
+  ],
+  "views": [
+    {
+      "viewId": "project-detail:p1",
+      "label": "Project detail",
+      "kind": "entity",
+      "entityType": "Project",
+      "queryKey": null,
+      "registeredAt": "2026-08-29T15:00:00.000Z",
+      "lastRenderedAt": "2026-08-29T15:04:04.000Z",
+      "renderCount": 12,
+      "subscriberCount": 1,
+      "membership": [
+        {
+          "type": "Project",
+          "id": "p1"
+        }
+      ],
+      "list": null
+    },
+    {
+      "viewId": "project-list:active",
+      "label": "Active projects",
+      "kind": "list",
+      "entityType": "Project",
+      "queryKey": "[\"projects\",{\"status\":\"active\"}]",
+      "registeredAt": "2026-08-29T14:58:00.000Z",
+      "lastRenderedAt": "2026-08-29T15:04:03.000Z",
+      "renderCount": 31,
+      "subscriberCount": 1,
+      "membership": [
+        {
+          "type": "Project",
+          "id": "p1"
+        },
+        {
+          "type": "Project",
+          "id": "p2"
+        }
+      ],
+      "list": {
+        "visibleCount": 2,
+        "graphCount": 2,
+        "total": 2,
+        "isFetching": false,
+        "isFetchingMore": false,
+        "stale": false,
+        "hasNextPage": false,
+        "hasPreviousPage": false
+      }
+    }
+  ],
+  "entityViewMembership": [
+    {
+      "type": "Project",
+      "id": "p1",
+      "viewIds": [
+        "project-detail:p1",
+        "project-list:active"
+      ]
+    },
+    {
+      "type": "Project",
+      "id": "p2",
+      "viewIds": [
+        "project-list:active"
+      ]
+    },
+    {
+      "type": "User",
+      "id": "u1",
+      "viewIds": []
+    }
+  ],
+  "relationships": [
+    {
+      "relation": "owner",
+      "cardinality": "belongsTo",
+      "direction": "outgoing",
+      "source": {
+        "type": "Project",
+        "id": "p1",
+        "field": "ownerId"
+      },
+      "target": {
+        "type": "User",
+        "id": "u1"
+      },
+      "status": "resolved"
+    },
+    {
+      "relation": "projects",
+      "cardinality": "hasMany",
+      "direction": "reverse",
+      "source": {
+        "type": "User",
+        "id": "u1",
+        "field": null
+      },
+      "target": {
+        "type": "Project",
+        "id": "p1"
+      },
+      "status": "resolved"
+    },
+    {
+      "relation": "owner",
+      "cardinality": "belongsTo",
+      "direction": "outgoing",
+      "source": {
+        "type": "Project",
+        "id": "p2",
+        "field": "ownerId"
+      },
+      "target": {
+        "type": "User",
+        "id": "u-missing"
+      },
+      "status": "missing-target"
+    }
+  ],
+  "previewReceipts": {
+    "applied": {
+      "previewId": "preview-p1-1",
+      "entity": {
+        "type": "Project",
+        "id": "p1"
+      },
+      "priorPatch": {
+        "name": "Apollo RC",
+        "status": "review"
+      },
+      "previewPatch": {
+        "status": "paused"
+      },
+      "appliedPatch": {
+        "name": "Apollo RC",
+        "status": "paused"
+      },
+      "baselineRevision": 14,
+      "previewRevision": 15,
+      "appliedAt": "2026-08-29T15:04:00.000Z"
+    },
+    "restored": {
+      "previewId": "preview-p1-1",
+      "status": "restored",
+      "restoredPatch": {
+        "name": "Apollo RC",
+        "status": "review"
+      },
+      "observedRevision": 15,
+      "restoredAt": "2026-08-29T15:04:06.000Z"
+    },
+    "conflict": {
+      "previewId": "preview-p1-2",
+      "status": "conflict",
+      "reason": "entity-changed-since-preview",
+      "expectedRevision": 19,
+      "observedRevision": 20,
+      "currentPatch": {
+        "name": "Apollo Final",
+        "status": "review"
+      },
+      "priorPatch": {
+        "name": "Apollo RC",
+        "status": "review"
+      }
+    }
+  }
+}

package/fixtures/devtools/time-travel-v1.json

@@ -0,0 +1,110 @@
+{
+  "fixture": "prometheus.entity-graph.devtools.time-travel",
+  "fixtureVersion": 1,
+  "protocol": "prometheus.entity-graph.devtools",
+  "protocolVersion": 1,
+  "storeId": "time-a",
+  "retention": {
+    "countLimit": 2,
+    "byteLimit": 1048576,
+    "baselineCursor": 40,
+    "retainedCursors": [41, 42],
+    "expiredBaseline": {
+      "status": "expired-history",
+      "cursor": 40,
+      "reason": "evicted",
+      "oldestCursor": 41,
+      "newestCursor": 42,
+      "latestCursor": 42
+    }
+  },
+  "snapshots": [
+    {
+      "cursor": 41,
+      "capturedAt": "2026-08-29T19:58:00.000Z",
+      "eventSequence": 7,
+      "data": {
+        "entities": {
+          "Task": {
+            "one": { "id": "one", "value": 1, "title": "First" }
+          }
+        },
+        "patches": {},
+        "entityStates": {},
+        "syncMetadata": {},
+        "lists": {}
+      }
+    },
+    {
+      "cursor": 42,
+      "capturedAt": "2026-08-29T19:59:00.000Z",
+      "eventSequence": 8,
+      "data": {
+        "entities": {
+          "Task": {
+            "one": { "id": "one", "value": 2, "title": "Second" }
+          }
+        },
+        "patches": {
+          "Task": {
+            "one": { "title": "Second draft" }
+          }
+        },
+        "entityStates": {},
+        "syncMetadata": {},
+        "lists": {}
+      }
+    }
+  ],
+  "rewind": {
+    "status": "rewound",
+    "cursor": 41,
+    "source": "retained",
+    "previousCursor": null,
+    "previousSource": null
+  },
+  "returnToLive": {
+    "status": "live",
+    "cursor": null,
+    "previousCursor": 41,
+    "previousSource": "retained",
+    "reason": "command"
+  },
+  "mutationWhileRewound": {
+    "eventOrder": ["time-travel:live:mutation", "mutation"],
+    "newLiveValue": 20,
+    "returnAfterMutation": null
+  },
+  "validImport": {
+    "protocol": "prometheus.entity-graph.devtools",
+    "version": 1,
+    "storeId": "time-a",
+    "exportedAt": "2026-08-29T20:00:00.000Z",
+    "snapshots": [
+      {
+        "cursor": 9001,
+        "capturedAt": "2026-08-29T19:59:30.000Z",
+        "eventSequence": null,
+        "data": {
+          "entities": {
+            "Task": {
+              "one": { "id": "one", "value": 9001, "title": "Imported" }
+            }
+          },
+          "patches": {},
+          "entityStates": {},
+          "syncMetadata": {},
+          "lists": {}
+        }
+      }
+    ]
+  },
+  "importExpectations": {
+    "inspectionStatus": "awaiting-confirmation",
+    "inspectionMutatesGraph": false,
+    "confirmationRequired": true,
+    "restoreStatus": "rewound",
+    "restoreSource": "import",
+    "candidateIsOneShot": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prometheus-ags/entity-graph-core",
-  "version": "3.0.5",
+  "version": "3.2.0",
   "description": "Framework-agnostic normalized entity graph store (zero React) — the core of the Prometheus entity-graph ecosystem.",
   "author": "Travis James <travis@prometheus.dev>",
   "license": "MIT",
@@ -8,6 +8,13 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "devtools": [
+        "dist/devtools.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "import": {
@@ -18,11 +25,28 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./devtools": {
+      "import": {
+        "types": "./dist/devtools.d.ts",
+        "default": "./dist/devtools.mjs"
+      },
+      "require": {
+        "types": "./dist/devtools.d.cts",
+        "default": "./dist/devtools.cjs"
+      }
+    },
+    "./devtools/fixtures/entity-inspection-v1.json": {
+      "default": "./fixtures/devtools/entity-inspection-v1.json"
+    },
+    "./devtools/fixtures/time-travel-v1.json": {
+      "default": "./fixtures/devtools/time-travel-v1.json"
     }
   },
   "sideEffects": false,
   "files": [
     "dist",
+    "fixtures",
     "README.md",
     "CHANGELOG.md"
   ],