@exellix/catalox-graphs 1.2.5 → 1.2.7

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.2.7 — 2026-06-23
+
+### Added
+
+- **`assertAuthoringGraphDocument`** — authoring-only load/save gate after `normalizeCatalogGraphDocument`; rejects flat root `nodes[]`, unsupported format versions (`2.0.0`, `2.1.1`), and non-authoring payloads with structured `{ code, message, hint }`.
+- **`readAuthoringGraphFromProjectData`** — normalize → assert → `{ ok, graph, graphId }` for Catalox project envelopes.
+- Error codes: `CATALOX_GRAPH_LEGACY_FLAT`, `CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION`, `CATALOX_GRAPH_NOT_AUTHORING`.
+
+### Changed
+
+- **`loadGraphFromCatalox`**, **`createCataloxGraphDocumentLoader`**, and **`graphToCatalogPayload`** use the same assert path; contract failures do not fall back to Mongo.
+- **`normalizeCatalogGraphDocument`** restored for hybrid Graph Studio envelope reshape only (no legacy content migration).
+
+## 1.2.6 — 2026-06-23
+
+### Fixed
+
+- Republish without stale `normalize-catalog-graph-document` build artifacts.
+
 ## 1.2.5 — 2026-06-23
 
 ### Removed

package/dist/index.d.ts

@@ -3,11 +3,13 @@ export { cataloxContextFromEnv, hasFirebaseCredentials, readCataloxAppId, readCa
 export { getCataloxBound, resetCataloxRuntimeCache } from './client/catalox-runtime.js';
 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 { listGraphsFromCatalox, loadGraphFromCatalox, saveGraphToCatalox, deleteGraphFromCatalox, listCompatibleGraphsFromCatalox, graphProjectSummaryFromItem, buildGraphProjectDocument, graphToCatalogPayload, readGraphFromProjectData, readAuthoringGraphFromProjectData, type CompatibleGraphFromCatalox, type ReadAuthoringGraphResult, } from './stores/graph-store.js';
+export { normalizeCatalogGraphDocument } from './stores/normalize-catalog-graph-document.js';
+export { assertAuthoringGraphDocument, cataloxGraphContractError, isCataloxGraphContractError, CataloxGraphContractError, CATALOX_GRAPH_LEGACY_FLAT, CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION, CATALOX_GRAPH_NOT_AUTHORING, type AssertAuthoringGraphResult, type AssertAuthoringGraphFailure, type AssertAuthoringGraphSuccess, } from './stores/assert-authoring-graph-document.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';
-export type { GraphProjectSummary, GraphProjectDocument, LoadGraphResult, SaveGraphOptions, GraphVersionPayload, GraphTemplatePayload, } from './types/graph-project.js';
+export type { GraphProjectSummary, GraphProjectDocument, LoadGraphResult, SaveGraphOptions, GraphVersionPayload, GraphTemplatePayload, CataloxGraphErrorCode, } from './types/graph-project.js';
 export { registerCataloxGraphRoutes, type RegisterCataloxGraphRoutesOptions } from './http/register-routes.js';
 //# sourceMappingURL=index.d.ts.map

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,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"}
+{"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,wBAAwB,EACxB,iCAAiC,EACjC,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,6BAA6B,EAAE,MAAM,8CAA8C,CAAC;AAE7F,OAAO,EACL,4BAA4B,EAC5B,yBAAyB,EACzB,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,EACzB,wCAAwC,EACxC,2BAA2B,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,GACjC,MAAM,6CAA6C,CAAC;AAErD,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,EACpB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,0BAA0B,EAAE,KAAK,iCAAiC,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -3,7 +3,9 @@ export { cataloxContextFromEnv, hasFirebaseCredentials, readCataloxAppId, readCa
 export { getCataloxBound, resetCataloxRuntimeCache } from './client/catalox-runtime.js';
 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 { listGraphsFromCatalox, loadGraphFromCatalox, saveGraphToCatalox, deleteGraphFromCatalox, listCompatibleGraphsFromCatalox, graphProjectSummaryFromItem, buildGraphProjectDocument, graphToCatalogPayload, readGraphFromProjectData, readAuthoringGraphFromProjectData, } from './stores/graph-store.js';
+export { normalizeCatalogGraphDocument } from './stores/normalize-catalog-graph-document.js';
+export { assertAuthoringGraphDocument, cataloxGraphContractError, isCataloxGraphContractError, CataloxGraphContractError, CATALOX_GRAPH_LEGACY_FLAT, CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION, CATALOX_GRAPH_NOT_AUTHORING, } from './stores/assert-authoring-graph-document.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';

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,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"}
+{"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,EACrB,wBAAwB,EACxB,iCAAiC,GAGlC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,6BAA6B,EAAE,MAAM,8CAA8C,CAAC;AAE7F,OAAO,EACL,4BAA4B,EAC5B,yBAAyB,EACzB,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,EACzB,wCAAwC,EACxC,2BAA2B,GAI5B,MAAM,6CAA6C,CAAC;AAErD,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;AAYnC,OAAO,EAAE,0BAA0B,EAA0C,MAAM,2BAA2B,CAAC"}

package/dist/stores/assert-authoring-graph-document.d.ts

@@ -0,0 +1,32 @@
+export declare const CATALOX_GRAPH_LEGACY_FLAT: "CATALOX_GRAPH_LEGACY_FLAT";
+export declare const CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION: "CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION";
+export declare const CATALOX_GRAPH_NOT_AUTHORING: "CATALOX_GRAPH_NOT_AUTHORING";
+export type CataloxGraphErrorCode = typeof CATALOX_GRAPH_LEGACY_FLAT | typeof CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION | typeof CATALOX_GRAPH_NOT_AUTHORING;
+export type AssertAuthoringGraphSuccess = {
+    ok: true;
+    graph: Record<string, unknown>;
+};
+export type AssertAuthoringGraphFailure = {
+    ok: false;
+    code: CataloxGraphErrorCode;
+    message: string;
+    hint?: string;
+};
+export type AssertAuthoringGraphResult = AssertAuthoringGraphSuccess | AssertAuthoringGraphFailure;
+export declare class CataloxGraphContractError extends Error {
+    readonly code: CataloxGraphErrorCode;
+    readonly hint?: string;
+    constructor(failure: AssertAuthoringGraphFailure);
+}
+export declare function cataloxGraphContractError(failure: AssertAuthoringGraphFailure | {
+    code: CataloxGraphErrorCode;
+    message: string;
+    hint?: string;
+}): CataloxGraphContractError;
+export declare function isCataloxGraphContractError(err: unknown): err is CataloxGraphContractError;
+/**
+ * Authoring-only gate for Catalox graph documents.
+ * Applies {@link normalizeCatalogGraphDocument} then requires current Graphenix AuthoringGraphDocument shape.
+ */
+export declare function assertAuthoringGraphDocument(raw: unknown): AssertAuthoringGraphResult;
+//# sourceMappingURL=assert-authoring-graph-document.d.ts.map

package/dist/stores/assert-authoring-graph-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-authoring-graph-document.d.ts","sourceRoot":"","sources":["../../src/stores/assert-authoring-graph-document.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAC9E,eAAO,MAAM,wCAAwC,EACnD,0CAAmD,CAAC;AACtD,eAAO,MAAM,2BAA2B,EAAG,6BAAsC,CAAC;AAElF,MAAM,MAAM,qBAAqB,GAC7B,OAAO,yBAAyB,GAChC,OAAO,wCAAwC,GAC/C,OAAO,2BAA2B,CAAC;AAEvC,MAAM,MAAM,2BAA2B,GAAG;IACxC,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,2BAA2B,GAAG,2BAA2B,CAAC;AAanG,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,2BAA2B;CAMjD;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,2BAA2B,GAAG;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACrG,yBAAyB,CAE3B;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,yBAAyB,CAE1F;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,OAAO,GAAG,0BAA0B,CA4DrF"}

package/dist/stores/assert-authoring-graph-document.js

@@ -0,0 +1,89 @@
+import { GRAPHENIX_FORMAT_VERSION } from '@x12i/graphenix-core';
+import { normalizeCatalogGraphDocument } from './normalize-catalog-graph-document.js';
+export const CATALOX_GRAPH_LEGACY_FLAT = 'CATALOX_GRAPH_LEGACY_FLAT';
+export const CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION = 'CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION';
+export const CATALOX_GRAPH_NOT_AUTHORING = 'CATALOX_GRAPH_NOT_AUTHORING';
+const UNSUPPORTED_FORMAT_VERSIONS = new Set(['2.0.0', '2.1.1']);
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function isLegacyFlatGraph(doc) {
+    return Array.isArray(doc.nodes) && !asRecord(doc.graph);
+}
+export class CataloxGraphContractError extends Error {
+    code;
+    hint;
+    constructor(failure) {
+        super(failure.message);
+        this.name = 'CataloxGraphContractError';
+        this.code = failure.code;
+        this.hint = failure.hint;
+    }
+}
+export function cataloxGraphContractError(failure) {
+    return new CataloxGraphContractError({ ok: false, ...failure });
+}
+export function isCataloxGraphContractError(err) {
+    return err instanceof CataloxGraphContractError;
+}
+/**
+ * Authoring-only gate for Catalox graph documents.
+ * Applies {@link normalizeCatalogGraphDocument} then requires current Graphenix AuthoringGraphDocument shape.
+ */
+export function assertAuthoringGraphDocument(raw) {
+    const record = asRecord(raw);
+    if (!record) {
+        return {
+            ok: false,
+            code: CATALOX_GRAPH_NOT_AUTHORING,
+            message: 'Graph document must be a JSON object.',
+            hint: 'Save an AuthoringGraphDocument from Graph Studio to the Catalox graphs catalog.',
+        };
+    }
+    const doc = normalizeCatalogGraphDocument(record);
+    if (isLegacyFlatGraph(doc)) {
+        return {
+            ok: false,
+            code: CATALOX_GRAPH_LEGACY_FLAT,
+            message: 'Flat exellix graph documents (root nodes[]) are not supported for execution.',
+            hint: 'Republish from Graph Studio as a Graphenix AuthoringGraphDocument.',
+        };
+    }
+    const formatVersion = doc.formatVersion;
+    if (typeof formatVersion !== 'string' || formatVersion.trim().length === 0) {
+        return {
+            ok: false,
+            code: CATALOX_GRAPH_NOT_AUTHORING,
+            message: 'Graph document is missing formatVersion.',
+            hint: 'Executable graphs must be AuthoringGraphDocument payloads saved from Graph Studio.',
+        };
+    }
+    if (UNSUPPORTED_FORMAT_VERSIONS.has(formatVersion)) {
+        return {
+            ok: false,
+            code: CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION,
+            message: `Graph formatVersion "${formatVersion}" is not supported.`,
+            hint: `Re-save from Graph Studio using Graphenix ${GRAPHENIX_FORMAT_VERSION}.`,
+        };
+    }
+    if (formatVersion !== GRAPHENIX_FORMAT_VERSION) {
+        return {
+            ok: false,
+            code: CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION,
+            message: `Graph formatVersion "${formatVersion}" is not supported; expected ${GRAPHENIX_FORMAT_VERSION}.`,
+            hint: `Re-save from Graph Studio using Graphenix ${GRAPHENIX_FORMAT_VERSION}.`,
+        };
+    }
+    if (!asRecord(doc.graph)) {
+        return {
+            ok: false,
+            code: CATALOX_GRAPH_NOT_AUTHORING,
+            message: 'Graph document is missing nested graph payload.',
+            hint: 'Executable graphs must include graph.nodes on an AuthoringGraphDocument root.',
+        };
+    }
+    return { ok: true, graph: doc };
+}
+//# sourceMappingURL=assert-authoring-graph-document.js.map

package/dist/stores/assert-authoring-graph-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-authoring-graph-document.js","sourceRoot":"","sources":["../../src/stores/assert-authoring-graph-document.ts"],"names":[],"mappings":"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"}

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

@@ -1 +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,CAmBzB;AAED,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,yCAAmC,CAAC"}
+{"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;AAK3D,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,CA6BzB;AAED,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,yCAAmC,CAAC"}

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

@@ -1,4 +1,5 @@
 import { getCataloxBound } from '../client/catalox-runtime.js';
+import { cataloxGraphContractError, isCataloxGraphContractError } from './assert-authoring-graph-document.js';
 import { loadGraphFromCatalox } from './graph-store.js';
 /**
  * Loads executable graph documents from the Catalox `graphs` catalog — same source Graph Studio saves to.
@@ -15,8 +16,18 @@ export function createCataloxGraphDocumentLoader(options = {}) {
                 if (fromCatalox.ok && fromCatalox.graph != null) {
                     return fromCatalox.graph;
                 }
+                if (!fromCatalox.ok && fromCatalox.code) {
+                    throw cataloxGraphContractError({
+                        code: fromCatalox.code,
+                        message: fromCatalox.error,
+                        hint: fromCatalox.hint,
+                    });
+                }
             }
-            catch {
+            catch (err) {
+                if (isCataloxGraphContractError(err)) {
+                    throw err;
+                }
                 // Catalox unavailable — use fallback when configured
             }
             if (options.fallback) {

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

@@ -1 +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,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,MAAM,eAAe,EAAE,CAAC,CAAC;gBACzD,MAAM,WAAW,GAAG,MAAM,oBAAoB,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnE,IAAI,WAAW,CAAC,EAAE,IAAI,WAAW,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;oBAChD,OAAO,WAAW,CAAC,KAAK,CAAC;gBAC3B,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,qDAAqD;YACvD,CAAC;YACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACrB,OAAO,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAC7C,CAAC;YACD,MAAM,OAAO,GAAG,UAAU,OAAO,uCAAuC,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAG,gCAAgC,CAAC"}
+{"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,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AAC9G,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,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,MAAM,eAAe,EAAE,CAAC,CAAC;gBACzD,MAAM,WAAW,GAAG,MAAM,oBAAoB,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnE,IAAI,WAAW,CAAC,EAAE,IAAI,WAAW,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;oBAChD,OAAO,WAAW,CAAC,KAAK,CAAC;gBAC3B,CAAC;gBACD,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC;oBACxC,MAAM,yBAAyB,CAAC;wBAC9B,IAAI,EAAE,WAAW,CAAC,IAAI;wBACtB,OAAO,EAAE,WAAW,CAAC,KAAK;wBAC1B,IAAI,EAAE,WAAW,CAAC,IAAI;qBACvB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,2BAA2B,CAAC,GAAG,CAAC,EAAE,CAAC;oBACrC,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,qDAAqD;YACvD,CAAC;YACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACrB,OAAO,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAC7C,CAAC;YACD,MAAM,OAAO,GAAG,UAAU,OAAO,uCAAuC,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAG,gCAAgC,CAAC"}

package/dist/stores/graph-project-build.d.ts

@@ -1,5 +1,6 @@
 import type { UnifiedCatalogItem } from '@x12i/catalox/embedder';
 import type { GraphProjectDocument, GraphProjectSummary, SaveGraphOptions } from '../types/graph-project.js';
+import { type AssertAuthoringGraphFailure } from './assert-authoring-graph-document.js';
 export declare function graphProjectSummaryFromItem(item: UnifiedCatalogItem): GraphProjectSummary;
 export declare function buildGraphProjectDocument(graph: Record<string, unknown>, options: SaveGraphOptions & {
     graphId: string;
@@ -9,6 +10,12 @@ export declare function graphToCatalogPayload(graph: Record<string, unknown>, op
     data: GraphProjectDocument;
 };
 export declare function readGraphFromProjectData(itemData: Record<string, unknown>): Record<string, unknown> | null;
+export type ReadAuthoringGraphResult = {
+    ok: true;
+    graph: Record<string, unknown>;
+    graphId: string;
+} | AssertAuthoringGraphFailure;
+export declare function readAuthoringGraphFromProjectData(itemData: Record<string, unknown>, itemId?: string): ReadAuthoringGraphResult;
 export declare function readGraphIdFromProjectData(itemData: Record<string, unknown>, itemId: string): string;
 /** Graph document version (`version` or `metadata.version`). Same semantics as graph-engine `readGraphDocumentVersion`. */
 export declare function readGraphDocumentVersion(graphDoc: unknown): string | undefined;

package/dist/stores/graph-project-build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-project-build.d.ts","sourceRoot":"","sources":["../../src/stores/graph-project-build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAW7G,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,kBAAkB,GAAG,mBAAmB,CAezF;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,gBAAgB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9C,oBAAoB,CAoBtB;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,GAAE,gBAAqB,GAC7B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAShD;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIhC;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpG;AAED,2HAA2H;AAC3H,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAO9E"}
+{"version":3,"file":"graph-project-build.d.ts","sourceRoot":"","sources":["../../src/stores/graph-project-build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7G,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,sCAAsC,CAAC;AAW9C,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,kBAAkB,GAAG,mBAAmB,CAezF;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,gBAAgB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9C,oBAAoB,CAoBtB;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,GAAE,gBAAqB,GAC7B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAehD;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIhC;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7D,2BAA2B,CAAC;AAEhC,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,SAAK,GACV,wBAAwB,CAqB1B;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpG;AAED,2HAA2H;AAC3H,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAO9E"}

package/dist/stores/graph-project-build.js

@@ -1,3 +1,4 @@
+import { assertAuthoringGraphDocument, CataloxGraphContractError, } from './assert-authoring-graph-document.js';
 function pickStr(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 }
@@ -40,12 +41,17 @@ export function buildGraphProjectDocument(graph, options) {
     return project;
 }
 export function graphToCatalogPayload(graph, options = {}) {
-    const metadata = asRecord(graph.metadata);
-    const graphId = pickStr(graph.id) ??
+    const asserted = assertAuthoringGraphDocument(graph);
+    if (!asserted.ok) {
+        throw new CataloxGraphContractError(asserted);
+    }
+    const authoringGraph = asserted.graph;
+    const metadata = asRecord(authoringGraph.metadata);
+    const graphId = pickStr(authoringGraph.id) ??
         pickStr(metadata?.id) ??
         pickStr(options.conceptName) ??
         `graph-${Date.now()}`;
-    const project = buildGraphProjectDocument(graph, { ...options, graphId });
+    const project = buildGraphProjectDocument(authoringGraph, { ...options, graphId });
     return { itemId: graphId, data: project };
 }
 export function readGraphFromProjectData(itemData) {
@@ -54,6 +60,26 @@ export function readGraphFromProjectData(itemData) {
         return null;
     return graph;
 }
+export function readAuthoringGraphFromProjectData(itemData, itemId = '') {
+    const raw = readGraphFromProjectData(itemData);
+    if (!raw) {
+        return {
+            ok: false,
+            code: 'CATALOX_GRAPH_NOT_AUTHORING',
+            message: 'Catalox item has no graph payload.',
+            hint: 'Save an AuthoringGraphDocument from Graph Studio to the Catalox graphs catalog.',
+        };
+    }
+    const asserted = assertAuthoringGraphDocument(raw);
+    if (!asserted.ok) {
+        return asserted;
+    }
+    return {
+        ok: true,
+        graph: asserted.graph,
+        graphId: readGraphIdFromProjectData(itemData, itemId),
+    };
+}
 export function readGraphIdFromProjectData(itemData, itemId) {
     return pickStr(itemData.graphId) ?? itemId;
 }

package/dist/stores/graph-project-build.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-project-build.js","sourceRoot":"","sources":["../../src/stores/graph-project-build.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph-project-build.js","sourceRoot":"","sources":["../../src/stores/graph-project-build.ts"],"names":[],"mappings":"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"}

package/dist/stores/graph-store.d.ts

@@ -1,6 +1,6 @@
 import type { CataloxBound } from '@x12i/catalox/embedder';
 import type { LoadGraphResult, SaveGraphOptions } from '../types/graph-project.js';
-export { graphProjectSummaryFromItem, buildGraphProjectDocument, graphToCatalogPayload, } from './graph-project-build.js';
+export { graphProjectSummaryFromItem, buildGraphProjectDocument, graphToCatalogPayload, readGraphFromProjectData, readAuthoringGraphFromProjectData, type ReadAuthoringGraphResult, } from './graph-project-build.js';
 export type GraphProjectSummary = import('../types/graph-project.js').GraphProjectSummary;
 export declare function listGraphsFromCatalox(options?: {
     limit?: number;
@@ -17,6 +17,8 @@ export declare function saveGraphToCatalox(graph: Record<string, unknown>, optio
     ok: boolean;
     itemId?: string;
     error?: string;
+    code?: string;
+    hint?: string;
 }>;
 export declare function deleteGraphFromCatalox(itemId: string): Promise<{
     ok: boolean;

package/dist/stores/graph-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-store.d.ts","sourceRoot":"","sources":["../../src/stores/graph-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAU3D,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEnF,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAIlC,MAAM,MAAM,mBAAmB,GAAG,OAAO,2BAA2B,EAAE,mBAAmB,CAAC;AAE1F,wBAAsB,qBAAqB,CACzC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAA;CAAO,GACrD,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CASzE;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,YAAY,CAAA;CAAO,GACrC,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAS3D;AAED,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAE1C;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAsB,+BAA+B,CAAC,OAAO,EAAE;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,GAAG,OAAO,CAAC;IACV,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,0BAA0B,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAwCD"}
+{"version":3,"file":"graph-store.d.ts","sourceRoot":"","sources":["../../src/stores/graph-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAU3D,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEnF,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,qBAAqB,EACrB,wBAAwB,EACxB,iCAAiC,EACjC,KAAK,wBAAwB,GAC9B,MAAM,0BAA0B,CAAC;AAIlC,MAAM,MAAM,mBAAmB,GAAG,OAAO,2BAA2B,EAAE,mBAAmB,CAAC;AAE1F,wBAAsB,qBAAqB,CACzC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAA;CAAO,GACrD,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CASzE;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,YAAY,CAAA;CAAO,GACrC,OAAO,CAAC,eAAe,CAAC,CAgC1B;AAED,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBzF;AAED,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAE1C;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAsB,+BAA+B,CAAC,OAAO,EAAE;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,GAAG,OAAO,CAAC;IACV,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,0BAA0B,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAwCD"}

package/dist/stores/graph-store.js

@@ -1,7 +1,8 @@
 import { CATALOG_IDS, DEFAULT_LIST_LIMIT } from '../config/catalog-ids.js';
 import { getCatalogItem, getCatalogItemByField, listCatalogItems, upsertCatalogItem, deleteCatalogItem } from '../client/catalox-api.js';
-import { graphProjectSummaryFromItem, graphToCatalogPayload, readGraphDocumentVersion, readGraphFromProjectData, readGraphIdFromProjectData, } from './graph-project-build.js';
-export { graphProjectSummaryFromItem, buildGraphProjectDocument, graphToCatalogPayload, } from './graph-project-build.js';
+import { graphProjectSummaryFromItem, graphToCatalogPayload, readAuthoringGraphFromProjectData, readGraphDocumentVersion, } from './graph-project-build.js';
+import { isCataloxGraphContractError } from './assert-authoring-graph-document.js';
+export { graphProjectSummaryFromItem, buildGraphProjectDocument, graphToCatalogPayload, readGraphFromProjectData, readAuthoringGraphFromProjectData, } from './graph-project-build.js';
 const GRAPHS_CATALOG = CATALOG_IDS.graphs;
 export async function listGraphsFromCatalox(options = {}) {
     const out = await listCatalogItems(GRAPHS_CATALOG, { limit: options.limit ?? DEFAULT_LIST_LIMIT, bound: options.bound });
@@ -20,32 +21,44 @@ export async function loadGraphFromCatalox(itemId, options = {}) {
     if (!out.ok || !out.item)
         return { ok: false, error: out.error ?? 'not found' };
     const itemData = out.item.data ?? {};
-    const graph = readGraphFromProjectData(itemData);
-    if (!graph) {
-        return { ok: false, error: 'Catalox item has no graph payload.' };
+    const loaded = readAuthoringGraphFromProjectData(itemData, itemId);
+    if (!loaded.ok) {
+        return {
+            ok: false,
+            error: loaded.message,
+            code: loaded.code,
+            hint: loaded.hint,
+        };
     }
-    const graphId = readGraphIdFromProjectData(itemData, itemId);
     const concept = itemData.concept && typeof itemData.concept === 'object' && !Array.isArray(itemData.concept)
         ? itemData.concept
         : undefined;
     return {
         ok: true,
-        graph,
-        graphId,
+        graph: loaded.graph,
+        graphId: loaded.graphId,
         concept,
         item: out.item,
     };
 }
 export async function saveGraphToCatalox(graph, options = {}) {
-    const payload = graphToCatalogPayload(graph, options);
-    const out = await upsertCatalogItem(GRAPHS_CATALOG, {
-        itemId: payload.itemId,
-        data: payload.data,
-        title: payload.data.title,
-    });
-    if (!out.ok)
-        return { ok: false, error: out.error };
-    return { ok: true, itemId: payload.itemId };
+    try {
+        const payload = graphToCatalogPayload(graph, options);
+        const out = await upsertCatalogItem(GRAPHS_CATALOG, {
+            itemId: payload.itemId,
+            data: payload.data,
+            title: payload.data.title,
+        });
+        if (!out.ok)
+            return { ok: false, error: out.error };
+        return { ok: true, itemId: payload.itemId };
+    }
+    catch (err) {
+        if (isCataloxGraphContractError(err)) {
+            return { ok: false, error: err.message, code: err.code, hint: err.hint };
+        }
+        throw err;
+    }
 }
 export async function deleteGraphFromCatalox(itemId) {
     return deleteCatalogItem(GRAPHS_CATALOG, itemId);

package/dist/stores/graph-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-store.js","sourceRoot":"","sources":["../../src/stores/graph-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph-store.js","sourceRoot":"","sources":["../../src/stores/graph-store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACzI,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,iCAAiC,EACjC,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AAGnF,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,qBAAqB,EACrB,wBAAwB,EACxB,iCAAiC,GAElC,MAAM,0BAA0B,CAAC;AAElC,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,CAAC;AAI1C,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,UAAoD,EAAE;IAEtD,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,kBAAkB,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACzH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;IAChE,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAC/D,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CACrD;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAc,EACd,UAAoC,EAAE;IAEtC,IAAI,GAAG,GAAG,MAAM,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAEtE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,GAAG,GAAG,MAAM,qBAAqB,CAAC,cAAc,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3F,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,WAAW,EAAE,CAAC;IAEhF,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,iCAAiC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACnE,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,MAAM,CAAC,OAAO;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;SAClB,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GACX,QAAQ,CAAC,OAAO,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;QAC1F,CAAC,CAAE,QAAQ,CAAC,OAAmC;QAC/C,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO;QACP,IAAI,EAAE,GAAG,CAAC,IAA0C;KACrD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAA8B,EAC9B,UAA4B,EAAE;IAE9B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,cAAc,EAAE;YAClD,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;QACpD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,2BAA2B,CAAC,GAAG,CAAC,EAAE,CAAC;YACrC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3E,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAc;IAEd,OAAO,iBAAiB,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,+BAA+B,CAAC,OAKrD;IAOC,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC3F,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,EAAE;YACV,WAAW,EAAE,CAAC;YACd,QAAQ,EAAE,KAAK;YACf,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAiC,EAAE,CAAC;IAEhD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;YACpF,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,SAAS;YAEzB,MAAM,CAAC,IAAI,CAAC;gBACV,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,YAAY,EAAE,wBAAwB,CAAC,MAAM,CAAC,KAAK,CAAC;aACrD,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,IAAI,CAAC;gBACV,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM;QACN,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;QACjC,QAAQ,EAAE,KAAK;KAChB,CAAC;AACJ,CAAC"}

package/dist/stores/normalize-catalog-graph-document.d.ts

@@ -1,8 +1,7 @@
 /**
- * Graph Studio sometimes persists a hybrid envelope: Graphenix 2.x nested `graph`
- * plus duplicate flat keys at the root (`response`, `modelConfig`, …).
- * Execution requires a strict AuthoringGraphDocument root — reshape on load only.
- * No legacy feature migration; invalid graph content must be fixed at the source.
+ * Graph Studio sometimes persists a hybrid document: Graphenix 2.x nested `graph`
+ * plus duplicate flat keys at the root (`nodes`, `response`, `modelConfig`, …).
+ * Reshape to a strict AuthoringGraphDocument root on load — envelope fix only, no content migration.
  */
 export declare function normalizeCatalogGraphDocument(raw: Record<string, unknown>): Record<string, unknown>;
 //# sourceMappingURL=normalize-catalog-graph-document.d.ts.map

package/dist/stores/normalize-catalog-graph-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-catalog-graph-document.d.ts","sourceRoot":"","sources":["../../src/stores/normalize-catalog-graph-document.ts"],"names":[],"mappings":"AAsDA;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8CzB"}
+{"version":3,"file":"normalize-catalog-graph-document.d.ts","sourceRoot":"","sources":["../../src/stores/normalize-catalog-graph-document.ts"],"names":[],"mappings":"AAuDA;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8CzB"}

package/dist/stores/normalize-catalog-graph-document.js

@@ -32,8 +32,9 @@ function deepMerge(base, overlay) {
     for (const [key, value] of Object.entries(overlay)) {
         if (value === undefined)
             continue;
-        const existingRecord = asRecord(out[key]);
+        const existing = out[key];
         const valueRecord = asRecord(value);
+        const existingRecord = asRecord(existing);
         if (existingRecord && valueRecord) {
             out[key] = deepMerge(existingRecord, valueRecord);
         }
@@ -43,18 +44,17 @@ function deepMerge(base, overlay) {
     }
     return out;
 }
-function hasDuplicateRootKeys(raw) {
+function hasDuplicateRoot(raw) {
     return DUPLICATE_ROOT_KEYS.some((key) => hasOwn(raw, key));
 }
 /**
- * Graph Studio sometimes persists a hybrid envelope: Graphenix 2.x nested `graph`
- * plus duplicate flat keys at the root (`response`, `modelConfig`, …).
- * Execution requires a strict AuthoringGraphDocument root — reshape on load only.
- * No legacy feature migration; invalid graph content must be fixed at the source.
+ * Graph Studio sometimes persists a hybrid document: Graphenix 2.x nested `graph`
+ * plus duplicate flat keys at the root (`nodes`, `response`, `modelConfig`, …).
+ * Reshape to a strict AuthoringGraphDocument root on load — envelope fix only, no content migration.
  */
 export function normalizeCatalogGraphDocument(raw) {
     const inner = asRecord(raw.graph);
-    if (!inner || !hasDuplicateRootKeys(raw)) {
+    if (!inner || !hasDuplicateRoot(raw)) {
         return raw;
     }
     const graph = { ...inner };

package/dist/stores/normalize-catalog-graph-document.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-catalog-graph-document.js","sourceRoot":"","sources":["../../src/stores/normalize-catalog-graph-document.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"normalize-catalog-graph-document.js","sourceRoot":"","sources":["../../src/stores/normalize-catalog-graph-document.ts"],"names":[],"mappings":"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"}

package/dist/types/graph-project.d.ts

@@ -15,6 +15,7 @@ export type GraphProjectDocument = {
     status?: string;
     [key: string]: unknown;
 };
+export type CataloxGraphErrorCode = 'CATALOX_GRAPH_LEGACY_FLAT' | 'CATALOX_GRAPH_UNSUPPORTED_FORMAT_VERSION' | 'CATALOX_GRAPH_NOT_AUTHORING';
 export type LoadGraphResult = {
     ok: true;
     graph: Record<string, unknown>;
@@ -24,6 +25,8 @@ export type LoadGraphResult = {
 } | {
     ok: false;
     error: string;
+    code?: CataloxGraphErrorCode;
+    hint?: string;
 };
 export type SaveGraphOptions = {
     title?: string;

package/dist/types/graph-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-project.d.ts","sourceRoot":"","sources":["../../src/types/graph-project.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CACnC,CAAC"}
+{"version":3,"file":"graph-project.d.ts","sourceRoot":"","sources":["../../src/types/graph-project.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B,2BAA2B,GAC3B,0CAA0C,GAC1C,6BAA6B,CAAC;AAElC,MAAM,MAAM,eAAe,GACvB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,qBAAqB,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CACnC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/catalox-graphs",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Catalox graph catalog data tier: CRUD for graphs, versions, templates, and shared React picker.",
   "type": "module",
   "engines": {
@@ -45,7 +45,8 @@
     "patch:graphs-graphid-index": "node scripts/patch-graphs-catalog-graphid-index.mjs"
   },
   "dependencies": {
-    "@x12i/catalox": "^5.9.8"
+    "@x12i/catalox": "^5.9.8",
+    "@x12i/graphenix-core": "^2.8.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",