@exellix/catalox-graphs

Node data tier for Catalox graph catalogs: CRUD stores, version checkpoints, templates, execute-time loaders, and readiness probes.

Authoritative store: Catalox catalog graphs (full AuthoringGraphDocument). Mongo exellix.graphs is matrix id-registry only.

Related packages (split by layer):

| Package | Layer | |---------|-------| | @exellix/catalox-graphs | Data tier — stores, loaders, Catalox runtime (this package) | | @exellix/catalox-graphs-http | HTTP BFF — Fastify /api/catalox/* routes | | @exellix/catalox-graphs-ui | Browser + React — fetch client, CataloxGraphPicker, CataloxGraphLibrary |

Exports

| Import | Use | |--------|-----| | @exellix/catalox-graphs | saveGraphToCatalox, loadGraphFromCatalox, createExecuteGraphLoader, stores, types |

Catalox runtime client

Hosts that need direct access to the bound Catalox SDK (outside the graph-store helpers) use:

| Export | Role | |--------|------| | getCataloxBound() | Lazily initialized Catalox client bound to CATALOX_APP_ID / credentials from env | | getRawCatalox() | Same client without app binding — used when resolving skills across Catalox apps | | resetCataloxRuntimeCache() | Clear cached client (tests / hot reload) | | seedCataloxBound(client) | Inject a test double |

For HTTP routes use @exellix/catalox-graphs-http. For browser/React use @exellix/catalox-graphs-ui.

Env

Catalox 6 Mongo (same as host apps):

• MONGO_URI (required)
• MONGO_DB_NAME (optional; default catalox)
• CATALOX_APP_ID (e.g. graphs-studio)
• CATALOX_STORE_ID (optional Catalox context store pin)
• CATALOX_GOD_MODE (optional service superAdmin)

HTTP routes

Mount BFF from the sibling package:

import { registerCataloxGraphRoutes } from '@exellix/catalox-graphs-http';

await registerCataloxGraphRoutes(app, { prefix: '/api/catalox' });

Key endpoints:

• GET /api/catalox/status
• GET /api/catalox/graphs?compatible=1&entityName=&contentType=
• GET|PUT|DELETE /api/catalox/graphs/:itemId
• GET|PUT|DELETE /api/catalox/graph-versions/:graphId/:versionId
• GET|PUT|DELETE /api/catalox/graph-templates/:templateKey
• Generic catalog CRUD under /api/catalox/catalogs/:catalogId/items/:itemId

React picker

import { CataloxGraphPicker } from '@exellix/catalox-graphs-ui/react';

<CataloxGraphPicker
  value={graphId}
  onChange={(id) => setGraphId(id)}
  entityName="subnets"
  contentType="snapshots"
  filterCompatible
/>

graphs-studio integration

See docs/STUDIO_INTEGRATION.md. Pair with @x12i/memorix-mongo for job memory context.

Catalogs owned

• graphs — working graph projects
• graph-versions — version checkpoints
• graph-templates — saved/system templates
• graph-concepts — legacy concept rows (dual-write optional in studio)

Migration from 1.2.x

Subpath exports moved to dedicated packages:

| Before | After | |--------|-------| | @exellix/catalox-graphs/http | @exellix/catalox-graphs-http | | @exellix/catalox-graphs/browser | @exellix/catalox-graphs-ui | | @exellix/catalox-graphs/react | @exellix/catalox-graphs-ui/react |

Ops — graphKind taxonomy

npm run build
npm run provision:graph-kind              # upsert descriptor 1.1.0 + verify list filters
npm run provision:graph-kind -- --backfill  # + backfill existing graph rows
npm run backfill:graph-kind -- --dry-run

From jobs-api: npm run provision:catalox-graphs / provision:catalox-graphs:full

Publish

Requires root .npmrc with your npm token (copy from .npmrc.example at repo root).

# This package only
cd catalox-graphs && npm run release

# Plan without publishing
npm run release:dry

# All three catalox packages in order (graphs → http → ui)
node ../scripts/publish-all.mjs --packages catalox-graphs,catalox-graphs-http,catalox-graphs-ui --no-bump

From repo root: npm run publish:all publishes the full core chain in dependency order.