@exellix/catalox-graphs 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.2.2 — 2026-06-23
+
+### Added
+
+- **`createCataloxGraphDocumentLoader`** — Catalox-first `loadGraph` for execute/compile paths (same catalog Graph Studio saves to).
+- **`createExecuteGraphLoader`** — alias for factory and matrix workers.
+- Tests for loader precedence (Catalox wins over Mongo fallback).
+
+### Changed
+
+- README and `docs/STUDIO_INTEGRATION.md`: Catalox `graphs` catalog is the single authoritative store for executable documents; Mongo `exellix.graphs` is matrix id-registry only.

package/README.md

@@ -1,15 +1,17 @@
-# @x12i/catalox-graphs
+# @exellix/catalox-graphs
 
-Shared Catalox data tier for **graphs-studio** and **jobs-ui**: graph catalog CRUD, version checkpoints, templates, legacy concepts, HTTP proxy routes, browser client, and `CataloxGraphPicker`.
+Shared Catalox data tier for **graphs-studio**, **jobs-api**, and **jobs-ui**: graph catalog CRUD, version checkpoints, templates, execute-time loading, HTTP proxy routes, browser client, and `CataloxGraphPicker`.
+
+**Authoritative store:** Catalox catalog `graphs` (full `AuthoringGraphDocument`). Mongo `exellix.graphs` is matrix id-registry only.
 
 ## Exports
 
 | Import | Use |
 |--------|-----|
-| `@x12i/catalox-graphs` | Server stores, readiness probe, types |
-| `@x12i/catalox-graphs/http` | Fastify route registrar (`/api/catalox/*`) |
-| `@x12i/catalox-graphs/browser` | Browser fetch client |
-| `@x12i/catalox-graphs/react` | `CataloxGraphPicker`, `useCataloxGraphs` |
+| `@exellix/catalox-graphs` | Server stores, `createCataloxGraphDocumentLoader` / `createExecuteGraphLoader`, readiness |
+| `@exellix/catalox-graphs/http` | Fastify route registrar (`/api/catalox/*`) |
+| `@exellix/catalox-graphs/browser` | Browser fetch client |
+| `@exellix/catalox-graphs/react` | `CataloxGraphPicker`, `useCataloxGraphs` |
 
 ## Env
 

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { getCataloxBound, resetCataloxRuntimeCache } from './client/catalox-runt
 export { listCatalogItems, getCatalogItem, upsertCatalogItem, deleteCatalogItem, type CatalogListResponse, type CatalogGetResponse, type CatalogWriteResponse, } from './client/catalox-api.js';
 export { probeCataloxReady, invalidateCataloxReadyCache, type CataloxReadyStatus } from './readiness.js';
 export { listGraphsFromCatalox, loadGraphFromCatalox, saveGraphToCatalox, deleteGraphFromCatalox, listCompatibleGraphsFromCatalox, graphProjectSummaryFromItem, buildGraphProjectDocument, graphToCatalogPayload, type CompatibleGraphFromCatalox, } from './stores/graph-store.js';
+export { createCataloxGraphDocumentLoader, createExecuteGraphLoader, type CreateCataloxGraphDocumentLoaderOptions, type GraphDocumentLoaderLike, } from './stores/graph-document-loader.js';
 export { saveGraphVersionToCatalox, loadGraphVersionFromCatalox, listGraphVersionsFromCatalox, deleteGraphVersionFromCatalox, pruneGraphVersionsBeyondLimit, graphVersionItemId, parseGraphVersionItemId, } from './stores/graph-version-store.js';
 export { listGraphTemplatesFromCatalox, getGraphTemplateFromCatalox, saveGraphTemplateToCatalox, deleteGraphTemplateFromCatalox, type GraphTemplateSummary, } from './stores/graph-template-store.js';
 export { loadConceptFromCatalox, saveConceptToCatalox, deleteConceptFromCatalox, } from './stores/concept-store.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACrG,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,qBAAqB,GAC3B,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzG,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,+BAA+B,EAC/B,2BAA2B,EAC3B,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,EAC7B,6BAA6B,EAC7B,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B,EAC9B,KAAK,oBAAoB,GAC1B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,0BAA0B,EAAE,KAAK,iCAAiC,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACrG,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,qBAAqB,GAC3B,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzG,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,+BAA+B,EAC/B,2BAA2B,EAC3B,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gCAAgC,EAChC,wBAAwB,EACxB,KAAK,uCAAuC,EAC5C,KAAK,uBAAuB,GAC7B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,EAC7B,6BAA6B,EAC7B,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B,EAC9B,KAAK,oBAAoB,GAC1B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,0BAA0B,EAAE,KAAK,iCAAiC,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -4,6 +4,7 @@ export { getCataloxBound, resetCataloxRuntimeCache } from './client/catalox-runt
 export { listCatalogItems, getCatalogItem, upsertCatalogItem, deleteCatalogItem, } from './client/catalox-api.js';
 export { probeCataloxReady, invalidateCataloxReadyCache } from './readiness.js';
 export { listGraphsFromCatalox, loadGraphFromCatalox, saveGraphToCatalox, deleteGraphFromCatalox, listCompatibleGraphsFromCatalox, graphProjectSummaryFromItem, buildGraphProjectDocument, graphToCatalogPayload, } from './stores/graph-store.js';
+export { createCataloxGraphDocumentLoader, createExecuteGraphLoader, } from './stores/graph-document-loader.js';
 export { saveGraphVersionToCatalox, loadGraphVersionFromCatalox, listGraphVersionsFromCatalox, deleteGraphVersionFromCatalox, pruneGraphVersionsBeyondLimit, graphVersionItemId, parseGraphVersionItemId, } from './stores/graph-version-store.js';
 export { listGraphTemplatesFromCatalox, getGraphTemplateFromCatalox, saveGraphTemplateToCatalox, deleteGraphTemplateFromCatalox, } from './stores/graph-template-store.js';
 export { loadConceptFromCatalox, saveConceptToCatalox, deleteConceptFromCatalox, } from './stores/concept-store.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACrG,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,GAEnB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAIlB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAA2B,MAAM,gBAAgB,CAAC;AAEzG,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,+BAA+B,EAC/B,2BAA2B,EAC3B,yBAAyB,EACzB,qBAAqB,GAEtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,EAC7B,6BAA6B,EAC7B,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B,GAE/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAWnC,OAAO,EAAE,0BAA0B,EAA0C,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACrG,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,GAEnB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAIlB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAA2B,MAAM,gBAAgB,CAAC;AAEzG,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,+BAA+B,EAC/B,2BAA2B,EAC3B,yBAAyB,EACzB,qBAAqB,GAEtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,gCAAgC,EAChC,wBAAwB,GAGzB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,EAC7B,6BAA6B,EAC7B,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B,GAE/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAWnC,OAAO,EAAE,0BAA0B,EAA0C,MAAM,2BAA2B,CAAC"}

package/dist/stores/graph-document-loader.d.ts

@@ -0,0 +1,23 @@
+import type { CataloxBound } from '@x12i/catalox/embedder';
+/** Minimal loader surface shared with jobs-db {@link GraphDocumentLoader}. */
+export type GraphDocumentLoaderLike = {
+    loadGraph(graphId: string): Promise<unknown>;
+};
+export type CreateCataloxGraphDocumentLoaderOptions = {
+    bound?: CataloxBound;
+    /**
+     * Optional fallback when the graph id is absent from Catalox.
+     * Not used when Catalox returns a graph — authoritative source is always Catalox when present.
+     */
+    fallback?: GraphDocumentLoaderLike;
+};
+/**
+ * Loads executable graph documents from the Catalox `graphs` catalog — same source Graph Studio saves to.
+ *
+ * Mongo `exellix.graphs` config rows (matrix metadata) are not AuthoringGraphDocuments and must not
+ * be used as the primary execution source.
+ */
+export declare function createCataloxGraphDocumentLoader(options?: CreateCataloxGraphDocumentLoaderOptions): GraphDocumentLoaderLike;
+/** Alias for factory/matrix execute paths — same Catalox-first loader. */
+export declare const createExecuteGraphLoader: typeof createCataloxGraphDocumentLoader;
+//# sourceMappingURL=graph-document-loader.d.ts.map

package/dist/stores/graph-document-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-document-loader.d.ts","sourceRoot":"","sources":["../../src/stores/graph-document-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,8EAA8E;AAC9E,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,uCAAuC,GAAG;IACpD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,uCAA4C,GACpD,uBAAuB,CAkBzB;AAED,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,yCAAmC,CAAC"}

package/dist/stores/graph-document-loader.js

@@ -0,0 +1,29 @@
+import { getCataloxBound } from '../client/catalox-runtime.js';
+import { loadGraphFromCatalox } from './graph-store.js';
+/**
+ * Loads executable graph documents from the Catalox `graphs` catalog — same source Graph Studio saves to.
+ *
+ * Mongo `exellix.graphs` config rows (matrix metadata) are not AuthoringGraphDocuments and must not
+ * be used as the primary execution source.
+ */
+export function createCataloxGraphDocumentLoader(options = {}) {
+    return {
+        async loadGraph(graphId) {
+            const bound = options.bound ?? (await getCataloxBound());
+            const fromCatalox = await loadGraphFromCatalox(graphId, { bound });
+            if (fromCatalox.ok && fromCatalox.graph != null) {
+                return fromCatalox.graph;
+            }
+            if (options.fallback) {
+                return options.fallback.loadGraph(graphId);
+            }
+            const message = !fromCatalox.ok && 'error' in fromCatalox && fromCatalox.error
+                ? fromCatalox.error
+                : `Graph "${graphId}" not found in Catalox graphs catalog`;
+            throw new Error(message);
+        },
+    };
+}
+/** Alias for factory/matrix execute paths — same Catalox-first loader. */
+export const createExecuteGraphLoader = createCataloxGraphDocumentLoader;
+//# sourceMappingURL=graph-document-loader.js.map

package/dist/stores/graph-document-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-document-loader.js","sourceRoot":"","sources":["../../src/stores/graph-document-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAgBxD;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAC9C,UAAmD,EAAE;IAErD,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,OAAe;YAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,MAAM,eAAe,EAAE,CAAC,CAAC;YACzD,MAAM,WAAW,GAAG,MAAM,oBAAoB,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YACnE,IAAI,WAAW,CAAC,EAAE,IAAI,WAAW,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;gBAChD,OAAO,WAAW,CAAC,KAAK,CAAC;YAC3B,CAAC;YACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACrB,OAAO,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAC7C,CAAC;YACD,MAAM,OAAO,GACX,CAAC,WAAW,CAAC,EAAE,IAAI,OAAO,IAAI,WAAW,IAAI,WAAW,CAAC,KAAK;gBAC5D,CAAC,CAAC,WAAW,CAAC,KAAK;gBACnB,CAAC,CAAC,UAAU,OAAO,uCAAuC,CAAC;YAC/D,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAG,gCAAgC,CAAC"}

package/docs/STUDIO_INTEGRATION.md

@@ -0,0 +1,61 @@
+# graphs-studio — Catalox data tier integration
+
+**Single source of truth:** executable graph documents live in the Catalox `graphs` catalog only.  
+Do not duplicate save/load logic or persist full graphs to Mongo `exellix.graphs` (matrix id-registry only).
+
+## Package
+
+`@exellix/catalox-graphs` — use this for **all** graph catalog CRUD, listing, and execute-time loading.
+
+## Required studio integration
+
+| Concern | Use from `@exellix/catalox-graphs` | Do not |
+|---------|-----------------------------------|--------|
+| Save / load graph | `saveGraphToCatalox`, `loadGraphFromCatalox` | Inline Catalox SDK calls, duplicate HTTP |
+| List / picker | `listGraphsFromCatalox`, `CataloxGraphPicker`, `useCataloxGraphs` | Separate graph list API |
+| Execute / compile load | `createCataloxGraphDocumentLoader` or `createExecuteGraphLoader` | Mongo `exellix.graphs` documents |
+| Versions / templates | `saveGraphVersionToCatalox`, `listGraphTemplatesFromCatalox`, HTTP routes | Ad-hoc catalog writes |
+| HTTP BFF | `registerCataloxGraphRoutes(app, { prefix: '/api/catalox' })` | Re-implement `/api/catalox/*` |
+
+### Server (BFF)
+
+```ts
+import { registerCataloxGraphRoutes } from '@exellix/catalox-graphs/http';
+
+await registerCataloxGraphRoutes(app, { prefix: '/api/catalox' });
+```
+
+### Browser / React
+
+```ts
+import { cataloxApi } from '@exellix/catalox-graphs/browser';
+import { CataloxGraphPicker, useCataloxGraphs } from '@exellix/catalox-graphs/react';
+```
+
+### Save path
+
+```ts
+import { saveGraphToCatalox } from '@exellix/catalox-graphs';
+
+await saveGraphToCatalox(authoringDocument, { title, concept });
+```
+
+Studio-only metadata (examples, `graphsStudio` UI blobs) stays in the **graphs-studio DB** per `GraphStudioDocument` — not in Mongo config, not duplicated in Catalox unless explicitly modeled as `concept`.
+
+## Job memory context (with Memorix)
+
+| Concern | Package |
+|---------|---------|
+| Graph catalog, versions, templates | `@exellix/catalox-graphs` |
+| Context query types, resolution, source reads | `@x12i/memorix-mongo` |
+
+See [`@x12i/memorix-mongo` STUDIO_INTEGRATION.md](../../memorix-mongo/docs/STUDIO_INTEGRATION.md).
+
+## Same package used by jobs
+
+`@exellix/jobs-api` and `@exellix/jobs` load executable graphs via `createExecuteGraphLoader` → Catalox first.  
+Studio and factory runs therefore share one catalog document.
+
+## Env
+
+Same Firebase / Catalox vars as jobs-api — see [README.md](../README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/catalox-graphs",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Catalox graph catalog data tier: CRUD for graphs, versions, templates, and shared React picker.",
   "type": "module",
   "engines": {
@@ -32,7 +32,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "docs"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.react.json",