@exellix/graph-composer 2.0.9 → 2.1.8

package/.env.example

@@ -11,6 +11,10 @@ OPENROUTER_API_KEY=
 # Optional — @x12i/logxer: package log level (verbose|debug|info|warn|error|off).
 # GRAPH_COMPOSER_LOGS_LEVEL=info
 #
+# Optional — bulk package levels (host registry; also applied when graph-composer loads):
+# LOGXER_PACKAGE_LEVELS=GRAPH_COMPOSER:debug
+# LOGXER_PACKAGE_LOGS_DEFAULT=warn
+#
 # Optional — Mongo log sink (see @x12i/logxer). Loaded via @x12i/env before Logxer is constructed.
 # MONGO_URI=
 # Mongo persistence defaults to warn; set info (or lower) to persist info-level package logs:

package/README.md

@@ -38,7 +38,9 @@ Requires **Node.js 20+** (Catalox embedder and this package align on `>=20`).
 | `OPENROUTER_API_KEY` | **Yes** (for API runs) | OpenRouter API key. |
 | `LLM_MODEL_STRONG` | No | Model slug when using `mode: "strong"` (default preset from @x12i/funcx). |
 | `LLM_MODEL_NORMAL` | No | Model slug for `normal` mode. |
-| `GRAPH_COMPOSER_LOGS_LEVEL` | No | Log level for [@x12i/logxer](https://www.npmjs.com/package/@x12i/logxer) (`debug`, `info`, `warn`, `off`, …). Overridable in code via `configureGraphComposerLogging` or per-call `logsLevel`. Uses diagnostic catalog `functions/graph-composer/metadata/log-diagnostics.json` (code `GRAPH_COMPOSER_WORKER_FAILED` on worker errors). |
+| `GRAPH_COMPOSER_LOGS_LEVEL` | No | Per-package log level for [@x12i/logxer](https://www.npmjs.com/package/@x12i/logxer) (`debug`, `info`, `warn`, `off`, …). Overridable via `configureGraphComposerLogging`, per-call `logsLevel`, or parent `logging` (`StackLoggingOptions`). |
+| `LOGXER_PACKAGE_LEVELS` | No | Bulk levels, e.g. `GRAPH_COMPOSER:debug,GRAPH_ENGINE:warn` (applied at module load). |
+| `LOGXER_PACKAGE_LOGS_DEFAULT` | No | Registry default when a prefix has no override (default `warn`). |
 
 Copy [`.env.example`](./.env.example) to `.env` for local development. **Do not commit secrets.**
 
@@ -283,13 +285,16 @@ graph-composer explain-basic
 | `loadCatalogCandidatesFromCatalox`, `createCatalox`, `unifiedCatalogItemToSkillDescriptor`, … | Build `catalogCandidates` from **Catalox** catalogs; see [`docs/catalog-metadb-end-state-contract.md`](./docs/catalog-metadb-end-state-contract.md). |
 | `reportTaskNodeProtocolGaps` | Offline list of **AI task** nodes violating **`taskConfiguration.aiTaskProfile`** (pre/post, **`webScoping.questions`** when enabled, **`inputSynthesis`** fields when synthesis is on). See `docs/task-node-execution-protocol.md`. |
 | `collectCanonicalGraphWarnings` | Warn-first **`@exellix/graph-engine`** canonical checks (top-level keys, metadata placement, memory paths, model profile aliases). |
+| `analyzeGraphModelLayers`, `stampGraphModelLayersOnGraph`, `graphModelLayerLegend` | **Model map** for AI nodes: which `@x12i/ai-profiles` names win (PRE/MAIN/POST), resolved provider ids, precedence layer + color stack — **model JSON only** unless you pass an explicit `runtime` overlay. Stamp with `stampGraphModelLayersOnGraph` before explain/UI. |
 | `assertCanonicalGraphDocument` | Re-exported from graph-engine — **`validateCreateModifyOutput` hard-fails** when the canonicalized graph does not pass. |
 | `GRAPH_ENGINE_MEMORY_PATH_ROOTS` | Re-exported memory path allowlist from graph-engine — use for validation parity, not a forked copy. |
 | `WoroxScopingMapCatalogCreatePayload`, `WoroxScopedDataDocumentShape` | Host-side CRUD handoff (align field names with your persisted catalog / scoping schema). |
 | `parseGraphConceptStory`, `isGraphConceptStoryDescription`, `GRAPH_CONCEPT_STORY_MARKER`, … | Parse **graph concept story** text for `create` / `modify` / reviews. |
 | `redactSecretsForLog` | Deep-redact sensitive key names for logging (used by `reviewConcept` tracing). |
 
-`RunGraphComposerOptions`: `client`, `mode`, `model`, `temperature`, `maxTokens`, `askTimeoutMs`, `connectTimeoutMs`, **`catalogMatchListsAssist`**, **`traceReviewConceptIo`** — see [integration handoff](./docs/integration-handoff.md).
+`RunGraphComposerOptions`: `client`, `mode`, `model`, `temperature`, `maxTokens`, `askTimeoutMs`, `connectTimeoutMs`, **`catalogMatchListsAssist`**, **`traceReviewConceptIo`**, **`logsLevel`**, **`logging`** — see [integration handoff](./docs/integration-handoff.md).
+
+**Deep stacks (@x12i/logxer ≥ 4.5):** Call `applyPackageLogLevelsFromEnv()` / `configurePackageLogLevels()` in the host before importing graph-composer, or pass `logging: { packageLevels: { GRAPH_COMPOSER: 'debug' } }` on `runGraphComposer`. Re-exported: `configurePackageLogLevels`, `applyPackageLogLevelsFromEnv`, `StackLoggingOptions`.
 
 ## Bundled content
 

package/dist/canonicalGraphDocument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canonicalGraphDocument.d.ts","sourceRoot":"","sources":["../src/canonicalGraphDocument.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkbH,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAc7E;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAiCtF;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAWpF"}
+{"version":3,"file":"canonicalGraphDocument.d.ts","sourceRoot":"","sources":["../src/canonicalGraphDocument.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmbH,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAc7E;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAiCtF;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAWpF"}

package/dist/canonicalGraphDocument.js

@@ -50,6 +50,7 @@ const GRAPH_SHELL_TO_METADATA = [
     "catalogRequests",
     "graphConcept",
     "graphReadability",
+    "graphModelLayersSummary",
     "catalogBinding",
     "catalogRequest",
 ];

package/dist/canonicalGraphWarnings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canonicalGraphWarnings.d.ts","sourceRoot":"","sources":["../src/canonicalGraphWarnings.ts"],"names":[],"mappings":"AAuIA;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAuHrE"}
+{"version":3,"file":"canonicalGraphWarnings.d.ts","sourceRoot":"","sources":["../src/canonicalGraphWarnings.ts"],"names":[],"mappings":"AAwIA;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAuHrE"}

package/dist/canonicalGraphWarnings.js

@@ -61,6 +61,7 @@ const FORBIDDEN_NARRIX_WEB_KEYS = [
 ];
 const PURE_TASK_METADATA_KEYS = new Set([
     "graphReadability",
+    "graphModelLayers",
     "catalogBinding",
     "catalogRequest",
     "name",

package/dist/graphComposerLogging.d.ts

@@ -1,7 +1,7 @@
-import { type LogLevel, type Logxer } from "@x12i/logxer";
+import { type LogLevel, type Logxer, type PackageLogLevelsConfig, type StackLoggingOptions } from "@x12i/logxer";
 /** Canonical env prefix for graph-composer logs (`GRAPH_COMPOSER_LOGS_LEVEL`, …). */
 export declare const GRAPH_COMPOSER_LOG_ENV_PREFIX = "GRAPH_COMPOSER";
-export type { LogLevel };
+export type { LogLevel, PackageLogLevelsConfig, StackLoggingOptions };
 /** Accepted inputs for `configureGraphComposerLogging` and `RunGraphComposerOptions.logsLevel`. */
 export type GraphComposerLogsLevelInput = LogLevel | "off" | "none" | "silent" | (string & {});
 export type GraphComposerLoggingConfig = {
@@ -16,6 +16,21 @@ export type GraphComposerLoggingConfig = {
         legacy: string;
     };
 };
+export type ConfigureGraphComposerLoggingOptions = {
+    /** Process-wide threshold (wins over stack / env / registry for this package). */
+    logsLevel?: GraphComposerLogsLevelInput;
+    /** Parent stack levels (`packageLevels`, default `logLevel`). See logxer `package-log-levels-stack.md`. */
+    logging?: StackLoggingOptions;
+    /** Merge into the process-wide logxer registry (`configurePackageLogLevels`). */
+    packageLogLevels?: PackageLogLevelsConfig;
+};
+/**
+ * Factory for a graph-composer Logxer (for hosts that need a dedicated instance).
+ * Default export is `getGraphComposerLogger()`.
+ */
+export declare function createGraphComposerLogger(options?: {
+    logging?: StackLoggingOptions;
+}): Logxer;
 /**
  * Parse a log-level string (case-insensitive). Unknown values disable logging (`off`).
  * Accepts logxer synonyms: `off`, `none`, `silent`.
@@ -28,18 +43,18 @@ export declare function parseGraphComposerLogsLevel(raw: string | undefined): {
  * Process-wide logging for graph-composer (downstream hosts, servers, CLIs).
  *
  * Precedence for each `runGraphComposer` / `runGraphComposerAgent` call:
- * `options.logsLevel` → `configureGraphComposerLogging` → `GRAPH_COMPOSER_LOGS_LEVEL` env → default `warn`.
+ * `options.logsLevel` → `configureGraphComposerLogging.logsLevel` → parent `options.logging` /
+ * `configureGraphComposerLogging.logging` → `GRAPH_COMPOSER_LOGS_LEVEL` env →
+ * `LOGXER_PACKAGE_LEVELS` / `configurePackageLogLevels` registry → default `warn`.
  */
-export declare function configureGraphComposerLogging(options: {
-    logsLevel?: GraphComposerLogsLevelInput;
-}): void;
+export declare function configureGraphComposerLogging(options?: ConfigureGraphComposerLoggingOptions): void;
 /** Current effective logging configuration (after env + programmatic overrides). */
-export declare function getGraphComposerLoggingConfig(perCall?: GraphComposerLogsLevelInput): GraphComposerLoggingConfig;
+export declare function getGraphComposerLoggingConfig(perCall?: GraphComposerLogsLevelInput, perCallStack?: StackLoggingOptions): GraphComposerLoggingConfig;
 /** Shared @x12i/logxer instance for graph-composer (diagnostics catalog attached). */
 export declare function getGraphComposerLogger(): Logxer;
 /**
  * Run `fn` with a temporary log threshold (`options.logsLevel` on workers).
  * Restores the previous threshold when `fn` completes.
  */
-export declare function withGraphComposerLogsLevel<T>(logsLevel: GraphComposerLogsLevelInput | undefined, fn: () => T | Promise<T>): Promise<T>;
+export declare function withGraphComposerLogsLevel<T>(logsLevel: GraphComposerLogsLevelInput | undefined, fn: () => T | Promise<T>, logging?: StackLoggingOptions): Promise<T>;
 //# sourceMappingURL=graphComposerLogging.d.ts.map

package/dist/graphComposerLogging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphComposerLogging.d.ts","sourceRoot":"","sources":["../src/graphComposerLogging.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AAGtB,qFAAqF;AACrF,eAAO,MAAM,6BAA6B,mBAAmB,CAAC;AAE9D,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB,mGAAmG;AACnG,MAAM,MAAM,2BAA2B,GACnC,QAAQ,GACR,KAAK,GACL,MAAM,GACN,QAAQ,GACR,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,MAAM,0BAA0B,GAAG;IACvC,4EAA4E;IAC5E,SAAS,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC5B,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAC;IACtB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AA+DF;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB;IAAE,SAAS,EAAE,QAAQ,GAAG,KAAK,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAMxD;AAoCD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE;IACrD,SAAS,CAAC,EAAE,2BAA2B,CAAC;CACzC,GAAG,IAAI,CAMP;AAED,oFAAoF;AACpF,wBAAgB,6BAA6B,CAC3C,OAAO,CAAC,EAAE,2BAA2B,GACpC,0BAA0B,CAY5B;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAAC,CAAC,EAChD,SAAS,EAAE,2BAA2B,GAAG,SAAS,EAClD,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAYZ"}
+{"version":3,"file":"graphComposerLogging.d.ts","sourceRoot":"","sources":["../src/graphComposerLogging.ts"],"names":[],"mappings":"AAEA,OAAO,EASL,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAGtB,qFAAqF;AACrF,eAAO,MAAM,6BAA6B,mBAAmB,CAAC;AAE9D,YAAY,EAAE,QAAQ,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,CAAC;AAEtE,mGAAmG;AACnG,MAAM,MAAM,2BAA2B,GACnC,QAAQ,GACR,KAAK,GACL,MAAM,GACN,QAAQ,GACR,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,MAAM,0BAA0B,GAAG;IACvC,4EAA4E;IAC5E,SAAS,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC5B,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAC;IACtB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAOF,MAAM,MAAM,oCAAoC,GAAG;IACjD,kFAAkF;IAClF,SAAS,CAAC,EAAE,2BAA2B,CAAC;IACxC,2GAA2G;IAC3G,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC;AAiEF;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAClD,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B,GAAG,MAAM,CAiBT;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB;IAAE,SAAS,EAAE,QAAQ,GAAG,KAAK,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAMxD;AAyDD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,oCAAyC,GACjD,IAAI,CAWN;AAED,oFAAoF;AACpF,wBAAgB,6BAA6B,CAC3C,OAAO,CAAC,EAAE,2BAA2B,EACrC,YAAY,CAAC,EAAE,mBAAmB,GACjC,0BAA0B,CAe5B;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAAC,CAAC,EAChD,SAAS,EAAE,2BAA2B,GAAG,SAAS,EAClD,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,CAAC,CAAC,CAcZ"}

package/dist/graphComposerLogging.js

@@ -1,20 +1,15 @@
 import path from "node:path";
 import { initConfig } from "@x12i/env";
-import { createLogxer, legacyPackageLogLevelEnvKey, packageLogsLevelEnvKey, parsePackageLogsLevelString, resolvePackageLogsLevel, } from "@x12i/logxer";
+import { applyPackageLogLevelsFromEnv, createLogxer, legacyPackageLogLevelEnvKey, mergePackageLogLevelsConfig, packageLogsLevelEnvKey, parsePackageLogsLevelString, resolvePackageLogsLevel, resolveStackLogLevelForPrefix, } from "@x12i/logxer";
 import { graphComposerPackRoot } from "./packDir.js";
 /** Canonical env prefix for graph-composer logs (`GRAPH_COMPOSER_LOGS_LEVEL`, …). */
 export const GRAPH_COMPOSER_LOG_ENV_PREFIX = "GRAPH_COMPOSER";
 // Load .env before Logxer reads MONGO_URI (and related vars) at construction.
 initConfig({}, { dotenvPath: ".env", throwOnMissing: false });
-const logger = createLogxer({
-    packageName: "graph-composer",
-    envPrefix: GRAPH_COMPOSER_LOG_ENV_PREFIX,
-}, {
-    diagnostics: {
-        catalogPath: path.join(graphComposerPackRoot(), "metadata", "log-diagnostics.json"),
-    },
-});
+applyPackageLogLevelsFromEnv();
 let processWideLogsLevel;
+let processWideStack;
+const logger = createGraphComposerLogger();
 function logxerMutableConfig(logxer) {
     return logxer.config;
 }
@@ -41,6 +36,35 @@ const LOG_LEVELS = new Set([
 function isLogLevel(value) {
     return LOG_LEVELS.has(value);
 }
+function mergeStackLogging(base, overlay) {
+    if (base === undefined && overlay === undefined) {
+        return undefined;
+    }
+    return {
+        ...(base?.logLevel !== undefined || overlay?.logLevel !== undefined
+            ? { logLevel: overlay?.logLevel ?? base?.logLevel }
+            : {}),
+        packageLevels: {
+            ...base?.packageLevels,
+            ...overlay?.packageLevels,
+        },
+    };
+}
+/**
+ * Factory for a graph-composer Logxer (for hosts that need a dedicated instance).
+ * Default export is `getGraphComposerLogger()`.
+ */
+export function createGraphComposerLogger(options) {
+    return createLogxer({
+        packageName: "graph-composer",
+        envPrefix: GRAPH_COMPOSER_LOG_ENV_PREFIX,
+    }, {
+        diagnostics: {
+            catalogPath: path.join(graphComposerPackRoot(), "metadata", "log-diagnostics.json"),
+        },
+        stack: options?.logging,
+    });
+}
 /**
  * Parse a log-level string (case-insensitive). Unknown values disable logging (`off`).
  * Accepts logxer synonyms: `off`, `none`, `silent`.
@@ -65,36 +89,55 @@ function resolveFromInput(input) {
     }
     return { packageLogsDisabled: false, logLevel: parsed.logLevel };
 }
-function resolveGraphComposerLogsLevel(perCall) {
-    if (perCall !== undefined) {
-        return resolveFromInput(perCall);
+function resolveGraphComposerLogsLevel(options) {
+    if (options?.perCallLevel !== undefined) {
+        return resolveFromInput(options.perCallLevel);
     }
     if (processWideLogsLevel !== undefined) {
-        return resolveFromInput(processWideLogsLevel);
+        const fromConfigure = resolveFromInput(processWideLogsLevel);
+        if (fromConfigure.packageLogsDisabled) {
+            return fromConfigure;
+        }
+        return resolvePackageLogsLevel({
+            envPrefix: GRAPH_COMPOSER_LOG_ENV_PREFIX,
+            userLogLevel: fromConfigure.logLevel,
+            stackLogLevel: resolveStackLogLevelForPrefix(GRAPH_COMPOSER_LOG_ENV_PREFIX, mergeStackLogging(processWideStack, options?.perCallStack)),
+        });
     }
     return resolvePackageLogsLevel({
         envPrefix: GRAPH_COMPOSER_LOG_ENV_PREFIX,
+        stackLogLevel: resolveStackLogLevelForPrefix(GRAPH_COMPOSER_LOG_ENV_PREFIX, mergeStackLogging(processWideStack, options?.perCallStack)),
     });
 }
-function syncLoggerToEffectiveLevel(perCall) {
-    applyResolvedToLogger(resolveGraphComposerLogsLevel(perCall));
+function syncLoggerToEffectiveLevel(options) {
+    applyResolvedToLogger(resolveGraphComposerLogsLevel(options));
 }
 /**
  * Process-wide logging for graph-composer (downstream hosts, servers, CLIs).
  *
  * Precedence for each `runGraphComposer` / `runGraphComposerAgent` call:
- * `options.logsLevel` → `configureGraphComposerLogging` → `GRAPH_COMPOSER_LOGS_LEVEL` env → default `warn`.
+ * `options.logsLevel` → `configureGraphComposerLogging.logsLevel` → parent `options.logging` /
+ * `configureGraphComposerLogging.logging` → `GRAPH_COMPOSER_LOGS_LEVEL` env →
+ * `LOGXER_PACKAGE_LEVELS` / `configurePackageLogLevels` registry → default `warn`.
  */
-export function configureGraphComposerLogging(options) {
-    if (options.logsLevel === undefined) {
-        return;
+export function configureGraphComposerLogging(options = {}) {
+    if (options.packageLogLevels !== undefined) {
+        mergePackageLogLevelsConfig(options.packageLogLevels);
+    }
+    if ("logging" in options) {
+        processWideStack = options.logging;
+    }
+    if ("logsLevel" in options) {
+        processWideLogsLevel = options.logsLevel;
     }
-    processWideLogsLevel = options.logsLevel;
     syncLoggerToEffectiveLevel();
 }
 /** Current effective logging configuration (after env + programmatic overrides). */
-export function getGraphComposerLoggingConfig(perCall) {
-    const resolved = resolveGraphComposerLogsLevel(perCall);
+export function getGraphComposerLoggingConfig(perCall, perCallStack) {
+    const resolved = resolveGraphComposerLogsLevel({
+        perCallLevel: perCall,
+        perCallStack,
+    });
     const logsDisabled = resolved.packageLogsDisabled;
     return {
         logsLevel: logsDisabled ? "off" : resolved.logLevel,
@@ -114,12 +157,12 @@ export function getGraphComposerLogger() {
  * Run `fn` with a temporary log threshold (`options.logsLevel` on workers).
  * Restores the previous threshold when `fn` completes.
  */
-export async function withGraphComposerLogsLevel(logsLevel, fn) {
-    if (logsLevel === undefined) {
+export async function withGraphComposerLogsLevel(logsLevel, fn, logging) {
+    if (logsLevel === undefined && logging === undefined) {
         syncLoggerToEffectiveLevel();
         return fn();
     }
-    const restore = applyResolvedToLogger(resolveGraphComposerLogsLevel(logsLevel));
+    const restore = applyResolvedToLogger(resolveGraphComposerLogsLevel({ perCallLevel: logsLevel, perCallStack: logging }));
     try {
         return await fn();
     }
@@ -128,5 +171,5 @@ export async function withGraphComposerLogsLevel(logsLevel, fn) {
         syncLoggerToEffectiveLevel();
     }
 }
-// Apply env / default level at module load (before first log line).
+// Apply env / registry / default level at module load (before first log line).
 syncLoggerToEffectiveLevel();

package/dist/graphEngineBridge.d.ts

@@ -2,6 +2,6 @@
  * Re-exports from `@exellix/graph-engine` so hosts validate graphs with the same
  * rules as runtime — do not fork gap codes or memory path allowlists here.
  */
-export { assertCanonicalGraphDocument, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, GRAPH_ENGINE_MEMORY_PATH_ROOTS, isAllowedGraphEngineMemoryPath, collectAiTasksNodeExtensionIssues, assertAiTasksNodeExtensionsValid, resolveGraphEngineMemoryPathValue, buildGraphEngineMemoryResolutionRootFromWorkingMemory, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, looksLikeConcreteModelId, isGraphAiProfileName, } from "@exellix/graph-engine";
+export { assertCanonicalGraphDocument, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, GRAPH_ENGINE_MEMORY_PATH_ROOTS, isAllowedGraphEngineMemoryPath, collectAiTasksNodeExtensionIssues, assertAiTasksNodeExtensionsValid, resolveGraphEngineMemoryPathValue, buildGraphEngineMemoryResolutionRootFromWorkingMemory, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, looksLikeConcreteModelId, isGraphAiProfileName, isGraphAiModelConfig, isModelConfigSelection, resolveGraphAiModelConfig, } from "@exellix/graph-engine";
 export type { GraphEngineMemoryResolutionRoot } from "@exellix/graph-engine";
 //# sourceMappingURL=graphEngineBridge.d.ts.map

package/dist/graphEngineBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphEngineBridge.d.ts","sourceRoot":"","sources":["../src/graphEngineBridge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,4BAA4B,EAC5B,mCAAmC,EACnC,8BAA8B,EAC9B,8BAA8B,EAC9B,8BAA8B,EAC9B,iCAAiC,EACjC,gCAAgC,EAChC,iCAAiC,EACjC,qDAAqD,EACrD,qCAAqC,EACrC,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"graphEngineBridge.d.ts","sourceRoot":"","sources":["../src/graphEngineBridge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,4BAA4B,EAC5B,mCAAmC,EACnC,8BAA8B,EAC9B,8BAA8B,EAC9B,8BAA8B,EAC9B,iCAAiC,EACjC,gCAAgC,EAChC,iCAAiC,EACjC,qDAAqD,EACrD,qCAAqC,EACrC,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/graphEngineBridge.js

@@ -2,4 +2,4 @@
  * Re-exports from `@exellix/graph-engine` so hosts validate graphs with the same
  * rules as runtime — do not fork gap codes or memory path allowlists here.
  */
-export { assertCanonicalGraphDocument, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, GRAPH_ENGINE_MEMORY_PATH_ROOTS, isAllowedGraphEngineMemoryPath, collectAiTasksNodeExtensionIssues, assertAiTasksNodeExtensionsValid, resolveGraphEngineMemoryPathValue, buildGraphEngineMemoryResolutionRootFromWorkingMemory, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, looksLikeConcreteModelId, isGraphAiProfileName, } from "@exellix/graph-engine";
+export { assertCanonicalGraphDocument, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, GRAPH_ENGINE_MEMORY_PATH_ROOTS, isAllowedGraphEngineMemoryPath, collectAiTasksNodeExtensionIssues, assertAiTasksNodeExtensionsValid, resolveGraphEngineMemoryPathValue, buildGraphEngineMemoryResolutionRootFromWorkingMemory, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, looksLikeConcreteModelId, isGraphAiProfileName, isGraphAiModelConfig, isModelConfigSelection, resolveGraphAiModelConfig, } from "@exellix/graph-engine";

package/dist/graphModelLayers.d.ts

@@ -0,0 +1,91 @@
+/** Precedence layer ids (lowest number = wins when present). Matches @exellix/graph-engine 7.2. */
+export type GraphModelLayerSource = "runtime.nodes.modelConfig" | "node.taskConfiguration.modelConfig" | "runtime.modelConfig" | "graph.modelConfig" | "graph-engine.default";
+export type GraphModelLayerPhase = "preActionModel" | "skillModel" | "postActionModel";
+/** Same three slots as `GraphAiModelConfig` in @exellix/graph-engine (profile names or concrete ids). */
+export type GraphModelProfilesTriple = {
+    preActionModel: string;
+    skillModel: string;
+    postActionModel: string;
+};
+export type GraphModelLayerStackEntry = {
+    /** Stable layer id for UI / explain output. */
+    source: GraphModelLayerSource;
+    /** Dot-path style location, e.g. `graph.modelConfig.cases[0]`. */
+    sourcePath: string;
+    /** Hex color for diagram overlays (stack order uses `layerOrder`). */
+    layerColor: string;
+    /** 1 = highest precedence (runtime node); 5 = engine default. */
+    layerOrder: number;
+    /** True when this layer is the effective winner for the node (model-only or with runtime). */
+    active: boolean;
+    profiles: GraphModelProfilesTriple;
+    /** Set when `profiles` were resolved through bundled @x12i/ai-profiles. */
+    providerIds?: GraphModelProfilesTriple;
+    /** Present when the tier uses conditional cases and no execution context was supplied. */
+    conditionalNote?: string;
+};
+export type NodeGraphModelLayers = {
+    nodeId: string;
+    skillKey: string;
+    winning: Pick<GraphModelLayerStackEntry, "source" | "sourcePath" | "layerColor" | "layerOrder" | "profiles" | "providerIds">;
+    /** All declared tiers on this graph/run (map layers), highest precedence first. */
+    stack: GraphModelLayerStackEntry[];
+};
+export type GraphModelLayersAnalysis = {
+    analyzedAt: string;
+    /** False when `runtime` was omitted — analysis reflects model JSON + engine default only. */
+    runtimeIncluded: boolean;
+    graphDefaultProfiles: GraphModelProfilesTriple;
+    graphDefaultProviderIds?: GraphModelProfilesTriple;
+    nodes: NodeGraphModelLayers[];
+};
+export type GraphModelLayersRuntimeOverlay = {
+    modelConfig?: unknown;
+    nodes?: Record<string, {
+        modelConfig?: unknown;
+    } | undefined>;
+};
+export type AnalyzeGraphModelLayersOptions = {
+    /**
+     * Optional runtime overlay. Omit to analyze **model-authored** config only (recommended).
+     * Do not inject `runtime.modelConfig` at execute time unless you intend to override the graph.
+     */
+    runtime?: GraphModelLayersRuntimeOverlay;
+    utilitySkills?: Iterable<{
+        skillKey?: string;
+    }>;
+    extraLocalSkillKeys?: Iterable<string>;
+};
+/**
+ * Where runtime logs the resolved model (for operators debugging failed tasks):
+ * - `RunTaskRequest.modelConfig` (wire: `xynthesisModel` / `skillModel` per phase)
+ * - skill-executions / ai-actions / runTask diagnostics when level is not `basic`
+ * - `resolveCanonicalModelUsed(runTaskResponse)` after the call (authoritative provider id)
+ *
+ * This function answers the **authoring / planning** view from graph JSON (+ optional runtime overlay).
+ */
+export declare function analyzeGraphModelLayers(graph: object, options?: AnalyzeGraphModelLayersOptions): Promise<GraphModelLayersAnalysis>;
+/** Profile accent color for UI badges (MAIN slot). */
+export declare function graphModelProfileAccent(profileName: string): string;
+/**
+ * Human-readable legend for diagram tools (source → color → meaning).
+ */
+export declare function graphModelLayerLegend(): Array<{
+    source: GraphModelLayerSource;
+    layerColor: string;
+    label: string;
+    layerOrder: number;
+}>;
+/**
+ * Stamp `metadata.graphModelLayers` on each AI task node (planning-only; not read by graph-engine).
+ * Does not mutate `runtime` and does not add runtime model overrides.
+ */
+export declare function stampGraphModelLayersOnGraph<T extends object>(graph: T, options?: AnalyzeGraphModelLayersOptions): Promise<T>;
+/** Resolve a single profile name to provider/model id (for docs and explain text). */
+export declare function resolveGraphModelProfileName(profileName: string): Promise<{
+    profile: string;
+    provider: string;
+    modelId: string;
+    formatted: string;
+}>;
+//# sourceMappingURL=graphModelLayers.d.ts.map

package/dist/graphModelLayers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphModelLayers.d.ts","sourceRoot":"","sources":["../src/graphModelLayers.ts"],"names":[],"mappings":"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"}

package/dist/graphModelLayers.js

@@ -0,0 +1,322 @@
+/**
+ * Model resolution map for worox graphs: which @x12i/ai-profiles names apply per AI node,
+ * which precedence layer wins, and resolved provider ids — without forcing runtime overrides.
+ */
+import { resolveAIProfile } from "@x12i/ai-profiles";
+import { DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, isGraphAiModelConfig, isModelConfigSelection, resolveGraphAiModelConfig, } from "./graphEngineBridge.js";
+import { DEFAULT_LOCAL_SKILL_KEYS } from "./aiTaskProfile.js";
+const LAYER_META = {
+    "runtime.nodes.modelConfig": {
+        layerOrder: 1,
+        layerColor: "#dc2626",
+        label: "runtime node override",
+    },
+    "node.taskConfiguration.modelConfig": {
+        layerOrder: 2,
+        layerColor: "#ea580c",
+        label: "per-node model (graph)",
+    },
+    "runtime.modelConfig": {
+        layerOrder: 3,
+        layerColor: "#ca8a04",
+        label: "runtime graph override",
+    },
+    "graph.modelConfig": {
+        layerOrder: 4,
+        layerColor: "#2563eb",
+        label: "graph default model",
+    },
+    "graph-engine.default": {
+        layerOrder: 5,
+        layerColor: "#6b7280",
+        label: "engine default (@exellix/graph-engine)",
+    },
+};
+/** Distinct accent per profile name for MAIN slot badges in UIs. */
+const PROFILE_ACCENT = {
+    cheap: "#16a34a",
+    balanced: "#2563eb",
+    deep: "#7c3aed",
+    strong: "#9333ea",
+    weak: "#84cc16",
+};
+function readRecord(v) {
+    if (v === null || v === undefined || typeof v !== "object" || Array.isArray(v)) {
+        return undefined;
+    }
+    return v;
+}
+function localSkillKeys(options) {
+    const s = new Set(DEFAULT_LOCAL_SKILL_KEYS);
+    for (const u of options?.utilitySkills ?? []) {
+        if (typeof u.skillKey === "string" && u.skillKey.trim() !== "") {
+            s.add(u.skillKey.trim());
+        }
+    }
+    for (const k of options?.extraLocalSkillKeys ?? []) {
+        if (typeof k === "string" && k.trim() !== "")
+            s.add(k.trim());
+    }
+    return s;
+}
+function describeModelConfigTier(value, basePath) {
+    if (isGraphAiModelConfig(value)) {
+        return { profiles: value, sourcePath: basePath };
+    }
+    if (!isModelConfigSelection(value)) {
+        return { sourcePath: basePath };
+    }
+    const cases = value.cases;
+    if (!Array.isArray(cases) || cases.length === 0) {
+        return { sourcePath: basePath, conditionalNote: "empty cases[]" };
+    }
+    const unconditional = cases.find((c) => c.when === undefined || c.when === null);
+    if (unconditional?.modelConfig && isGraphAiModelConfig(unconditional.modelConfig)) {
+        const idx = cases.indexOf(unconditional);
+        return {
+            profiles: unconditional.modelConfig,
+            sourcePath: `${basePath}.cases[${idx}]`,
+            conditionalNote: cases.length > 1
+                ? "static analysis uses default case (no when); other cases need runtime gates"
+                : undefined,
+        };
+    }
+    const first = cases[0];
+    if (first?.modelConfig && isGraphAiModelConfig(first.modelConfig)) {
+        return {
+            profiles: first.modelConfig,
+            sourcePath: `${basePath}.cases[0]`,
+            conditionalNote: "no unconditional case — showing cases[0] only; runtime may pick another",
+        };
+    }
+    return { sourcePath: basePath, conditionalNote: "could not read modelConfig from cases" };
+}
+async function resolveProviderTriple(profiles, context) {
+    return resolveGraphAiModelConfig(profiles, context);
+}
+function buildStackEntry(source, sourcePath, profiles, active, conditionalNote, providerIds) {
+    if (profiles === undefined)
+        return undefined;
+    const meta = LAYER_META[source];
+    return {
+        source,
+        sourcePath,
+        layerColor: meta.layerColor,
+        layerOrder: meta.layerOrder,
+        active,
+        profiles,
+        ...(providerIds !== undefined ? { providerIds } : {}),
+        ...(conditionalNote !== undefined ? { conditionalNote } : {}),
+    };
+}
+async function resolveWinningTier(tiers) {
+    for (const tier of tiers) {
+        const described = describeModelConfigTier(tier.value, tier.basePath);
+        if (described.profiles !== undefined) {
+            return {
+                source: tier.source,
+                sourcePath: described.sourcePath,
+                profiles: described.profiles,
+            };
+        }
+    }
+    return {
+        source: "graph-engine.default",
+        sourcePath: "@exellix/graph-engine DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG",
+        profiles: { ...DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG },
+    };
+}
+/**
+ * Where runtime logs the resolved model (for operators debugging failed tasks):
+ * - `RunTaskRequest.modelConfig` (wire: `xynthesisModel` / `skillModel` per phase)
+ * - skill-executions / ai-actions / runTask diagnostics when level is not `basic`
+ * - `resolveCanonicalModelUsed(runTaskResponse)` after the call (authoritative provider id)
+ *
+ * This function answers the **authoring / planning** view from graph JSON (+ optional runtime overlay).
+ */
+export async function analyzeGraphModelLayers(graph, options) {
+    const g = graph;
+    const graphId = typeof g.id === "string" ? g.id : undefined;
+    const runtime = options?.runtime;
+    const runtimeIncluded = runtime !== undefined;
+    const locals = localSkillKeys(options);
+    const graphTier = describeModelConfigTier(g.modelConfig, "graph.modelConfig");
+    const graphDefaultProfiles = graphTier.profiles ?? { ...DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG };
+    const graphDefaultProviderIds = await resolveProviderTriple(graphDefaultProfiles, {
+        graphId,
+    });
+    const nodes = [];
+    const nodeList = g.nodes;
+    if (!Array.isArray(nodeList)) {
+        return {
+            analyzedAt: new Date().toISOString(),
+            runtimeIncluded,
+            graphDefaultProfiles,
+            graphDefaultProviderIds,
+            nodes,
+        };
+    }
+    for (const n of nodeList) {
+        const node = readRecord(n);
+        if (node === undefined)
+            continue;
+        if (node.type !== undefined && node.type !== "task")
+            continue;
+        const nodeId = typeof node.id === "string" ? node.id : "";
+        const skillKey = typeof node.skillKey === "string" ? node.skillKey.trim() : "";
+        if (nodeId === "" || skillKey === "" || locals.has(skillKey))
+            continue;
+        const tc = readRecord(node.taskConfiguration);
+        const runtimeNode = runtime?.nodes?.[nodeId];
+        const runtimeNodeMc = readRecord(runtimeNode)?.modelConfig;
+        const tiers = [];
+        if (runtimeIncluded && runtimeNodeMc !== undefined) {
+            tiers.push({
+                source: "runtime.nodes.modelConfig",
+                basePath: `runtime.nodes["${nodeId}"].modelConfig`,
+                value: runtimeNodeMc,
+            });
+        }
+        if (tc?.modelConfig !== undefined) {
+            tiers.push({
+                source: "node.taskConfiguration.modelConfig",
+                basePath: `nodes["${nodeId}"].taskConfiguration.modelConfig`,
+                value: tc.modelConfig,
+            });
+        }
+        if (runtimeIncluded && runtime?.modelConfig !== undefined) {
+            tiers.push({
+                source: "runtime.modelConfig",
+                basePath: "runtime.modelConfig",
+                value: runtime.modelConfig,
+            });
+        }
+        if (g.modelConfig !== undefined) {
+            tiers.push({
+                source: "graph.modelConfig",
+                basePath: "graph.modelConfig",
+                value: g.modelConfig,
+            });
+        }
+        const winning = await resolveWinningTier(tiers);
+        const winningProviderIds = await resolveProviderTriple(winning.profiles, {
+            graphId,
+            nodeId,
+        });
+        const stack = [];
+        const pushTier = async (tier) => {
+            const described = describeModelConfigTier(tier.value, tier.basePath);
+            if (described.profiles === undefined)
+                return;
+            const providerIds = await resolveProviderTriple(described.profiles, {
+                graphId,
+                nodeId,
+            });
+            const entry = buildStackEntry(tier.source, described.sourcePath, described.profiles, tier.source === winning.source && described.sourcePath === winning.sourcePath, described.conditionalNote, providerIds);
+            if (entry !== undefined)
+                stack.push(entry);
+        };
+        for (const tier of tiers) {
+            await pushTier(tier);
+        }
+        const defaultEntry = buildStackEntry("graph-engine.default", "@exellix/graph-engine DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG", { ...DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG }, winning.source === "graph-engine.default", tiers.length === 0
+            ? "no modelConfig on graph or node — engine default applies"
+            : undefined, await resolveProviderTriple(DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, { graphId, nodeId }));
+        if (defaultEntry !== undefined) {
+            stack.push(defaultEntry);
+        }
+        stack.sort((a, b) => a.layerOrder - b.layerOrder);
+        nodes.push({
+            nodeId,
+            skillKey,
+            winning: {
+                source: winning.source,
+                sourcePath: winning.sourcePath,
+                layerColor: LAYER_META[winning.source].layerColor,
+                layerOrder: LAYER_META[winning.source].layerOrder,
+                profiles: winning.profiles,
+                providerIds: winningProviderIds,
+            },
+            stack,
+        });
+    }
+    return {
+        analyzedAt: new Date().toISOString(),
+        runtimeIncluded,
+        graphDefaultProfiles,
+        graphDefaultProviderIds,
+        nodes,
+    };
+}
+/** Profile accent color for UI badges (MAIN slot). */
+export function graphModelProfileAccent(profileName) {
+    const key = profileName.trim().toLowerCase();
+    return PROFILE_ACCENT[key] ?? "#64748b";
+}
+/**
+ * Human-readable legend for diagram tools (source → color → meaning).
+ */
+export function graphModelLayerLegend() {
+    return Object.keys(LAYER_META).map((source) => ({
+        source,
+        ...LAYER_META[source],
+    }));
+}
+/**
+ * Stamp `metadata.graphModelLayers` on each AI task node (planning-only; not read by graph-engine).
+ * Does not mutate `runtime` and does not add runtime model overrides.
+ */
+export async function stampGraphModelLayersOnGraph(graph, options) {
+    const analysis = await analyzeGraphModelLayers(graph, options);
+    const g = graph;
+    const byId = new Map(analysis.nodes.map((n) => [n.nodeId, n]));
+    const nodes = g.nodes;
+    if (!Array.isArray(nodes))
+        return graph;
+    for (const n of nodes) {
+        const node = readRecord(n);
+        if (node === undefined)
+            continue;
+        const nodeId = typeof node.id === "string" ? node.id : "";
+        const layer = byId.get(nodeId);
+        if (layer === undefined)
+            continue;
+        const meta = { ...readRecord(node.metadata) };
+        meta.graphModelLayers = {
+            ...layer,
+            profileAccents: {
+                preActionModel: graphModelProfileAccent(layer.winning.profiles.preActionModel),
+                skillModel: graphModelProfileAccent(layer.winning.profiles.skillModel),
+                postActionModel: graphModelProfileAccent(layer.winning.profiles.postActionModel),
+            },
+            legend: graphModelLayerLegend(),
+        };
+        node.metadata = meta;
+    }
+    const rootMeta = { ...readRecord(g.metadata) };
+    rootMeta.graphModelLayersSummary = {
+        analyzedAt: analysis.analyzedAt,
+        runtimeIncluded: analysis.runtimeIncluded,
+        legend: graphModelLayerLegend(),
+        graphDefault: {
+            profiles: analysis.graphDefaultProfiles,
+            providerIds: analysis.graphDefaultProviderIds,
+        },
+        note: "Planning overlay only. At execute time @exellix/graph-engine resolves modelConfig (runtime.nodes → node → runtime → graph → default), then @x12i/ai-profiles maps profile names to provider ids. Omit runtime.modelConfig unless you intend to override the graph.",
+    };
+    g.metadata = rootMeta;
+    return graph;
+}
+/** Resolve a single profile name to provider/model id (for docs and explain text). */
+export async function resolveGraphModelProfileName(profileName) {
+    const resolved = await resolveAIProfile(profileName.trim(), { source: "bundled" });
+    const formatted = resolved.modelId.includes("/")
+        ? resolved.modelId
+        : `${resolved.provider}/${resolved.modelId}`;
+    return {
+        profile: resolved.profile,
+        provider: resolved.provider,
+        modelId: resolved.modelId,
+        formatted,
+    };
+}

package/dist/index.d.ts

@@ -3,8 +3,9 @@ export { GRAPH_COMPOSER_ACTION_REGISTRY, getActionDefinition, getActionDefinitio
 export { graphComposerPackRoot, readGraphComposerPromptFile, } from "./packDir.js";
 export { DEFAULT_UTILITY_SKILLS } from "./defaultUtilitySkills.js";
 export { runGraphComposer, runGraphWorker, resolveGraphComposerClient, getGraphComposerLlmClient, getPackDir, normalizeGraphComposerExplainOutput, normalizeReviewConceptComposerOutput, redactSecretsForLog, type RunGraphComposerOptions, } from "./runGraphComposer.js";
-export type { LogRuntimeContext, LogLevel } from "@x12i/logxer";
-export { GRAPH_COMPOSER_LOG_ENV_PREFIX, configureGraphComposerLogging, getGraphComposerLogger, getGraphComposerLoggingConfig, parseGraphComposerLogsLevel, withGraphComposerLogsLevel, type GraphComposerLoggingConfig, type GraphComposerLogsLevelInput, } from "./graphComposerLogging.js";
+export type { LogRuntimeContext, LogLevel, PackageLogLevelsConfig, StackLoggingOptions, } from "@x12i/logxer";
+export { applyPackageLogLevelsFromEnv, configurePackageLogLevels, } from "@x12i/logxer";
+export { GRAPH_COMPOSER_LOG_ENV_PREFIX, configureGraphComposerLogging, createGraphComposerLogger, getGraphComposerLogger, getGraphComposerLoggingConfig, parseGraphComposerLogsLevel, withGraphComposerLogsLevel, type ConfigureGraphComposerLoggingOptions, type GraphComposerLoggingConfig, type GraphComposerLogsLevelInput, } from "./graphComposerLogging.js";
 export { applyGraphConceptPatchOnlyIfEmpty } from "./graphConceptPatchMerge.js";
 export { runGraphComposerAgent, type GraphComposerAgentResult, type GraphComposerAgentOrchestrationStep, type RunGraphComposerAgentOptions, } from "./graphComposerAgent.js";
 export type { GraphComposerInput, GraphComposerAgentInput, GraphComposerIntent, GraphComposerConstraints, SkillDescriptor, PrimaryIntentType, GraphConceptStatus, GraphConceptEntityBindings, GraphConceptPatch, GraphConceptPatchKey, GraphConceptRequirementsPatch, GraphConceptCoreTaskPatchItem, RequirementOptionCandidate, RequirementOptionEntry, CatalogCandidates, ScopingMapCandidate, NarrixTemplateCandidate, } from "./types.js";
@@ -19,6 +20,7 @@ export type { ParsedGraphConcept } from "./parseGraphConceptStory.js";
 export { reportTaskNodeProtocolGaps, DEFAULT_LOCAL_SKILL_KEYS, type AiTaskProfileMetadata, type TaskNodeProtocolGap, type TaskNodeProtocolIssueCode, type WebScopingNodeConfig, type InputSynthesisNodeConfig, type InputSynthesisDestination, } from "./aiTaskProfile.js";
 export { assertCanonicalGraphDocument, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, GRAPH_ENGINE_MEMORY_PATH_ROOTS, isAllowedGraphEngineMemoryPath, collectAiTasksNodeExtensionIssues, assertAiTasksNodeExtensionsValid, resolveGraphEngineMemoryPathValue, buildGraphEngineMemoryResolutionRootFromWorkingMemory, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, looksLikeConcreteModelId, isGraphAiProfileName, type GraphEngineMemoryResolutionRoot, } from "./graphEngineBridge.js";
 export { collectCanonicalGraphWarnings } from "./canonicalGraphWarnings.js";
+export { analyzeGraphModelLayers, stampGraphModelLayersOnGraph, graphModelLayerLegend, graphModelProfileAccent, resolveGraphModelProfileName, type AnalyzeGraphModelLayersOptions, type GraphModelLayerPhase, type GraphModelLayerSource, type GraphModelLayerStackEntry, type GraphModelLayersAnalysis, type GraphModelLayersRuntimeOverlay, type GraphModelProfilesTriple, type NodeGraphModelLayers, } from "./graphModelLayers.js";
 export { resolveTaskNodeInputs, resolveTaskNodeInputsConfig, resolveTaskNodeTaskVariable, canonicalizeGraphTaskNodeTaskVariable, canonicalizeGraphModel, reportTaskNodeInputsLayoutIssues, taskNodeInputsLayoutWarningMessage, isTaskVariablePathRef, isTaskNode, isFinalizerNode, type TaskNodeInputsLayoutIssue, type TaskNodeInputsLayoutIssueCode, } from "./taskNodeTaskVariable.js";
 export { createCatalox, bindCataloxContext, Catalox, CataloxBound, } from "@x12i/catalox/embedder";
 export type { CataloxContext, CataloxRuntimeConfig, } from "@x12i/catalox/embedder";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -3,7 +3,8 @@ export { GRAPH_COMPOSER_ACTION_REGISTRY, getActionDefinition, getActionDefinitio
 export { graphComposerPackRoot, readGraphComposerPromptFile, } from "./packDir.js";
 export { DEFAULT_UTILITY_SKILLS } from "./defaultUtilitySkills.js";
 export { runGraphComposer, runGraphWorker, resolveGraphComposerClient, getGraphComposerLlmClient, getPackDir, normalizeGraphComposerExplainOutput, normalizeReviewConceptComposerOutput, redactSecretsForLog, } from "./runGraphComposer.js";
-export { GRAPH_COMPOSER_LOG_ENV_PREFIX, configureGraphComposerLogging, getGraphComposerLogger, getGraphComposerLoggingConfig, parseGraphComposerLogsLevel, withGraphComposerLogsLevel, } from "./graphComposerLogging.js";
+export { applyPackageLogLevelsFromEnv, configurePackageLogLevels, } from "@x12i/logxer";
+export { GRAPH_COMPOSER_LOG_ENV_PREFIX, configureGraphComposerLogging, createGraphComposerLogger, getGraphComposerLogger, getGraphComposerLoggingConfig, parseGraphComposerLogsLevel, withGraphComposerLogsLevel, } from "./graphComposerLogging.js";
 export { applyGraphConceptPatchOnlyIfEmpty } from "./graphConceptPatchMerge.js";
 export { runGraphComposerAgent, } from "./graphComposerAgent.js";
 export { buildCatalogMatchHints, } from "./catalogMatchAssist.js";
@@ -15,6 +16,7 @@ export { parseGraphConceptStory, parseGraphConceptStoryBody, isGraphConceptStory
 export { reportTaskNodeProtocolGaps, DEFAULT_LOCAL_SKILL_KEYS, } from "./aiTaskProfile.js";
 export { assertCanonicalGraphDocument, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, GRAPH_ENGINE_MEMORY_PATH_ROOTS, isAllowedGraphEngineMemoryPath, collectAiTasksNodeExtensionIssues, assertAiTasksNodeExtensionsValid, resolveGraphEngineMemoryPathValue, buildGraphEngineMemoryResolutionRootFromWorkingMemory, DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG, looksLikeConcreteModelId, isGraphAiProfileName, } from "./graphEngineBridge.js";
 export { collectCanonicalGraphWarnings } from "./canonicalGraphWarnings.js";
+export { analyzeGraphModelLayers, stampGraphModelLayersOnGraph, graphModelLayerLegend, graphModelProfileAccent, resolveGraphModelProfileName, } from "./graphModelLayers.js";
 export { resolveTaskNodeInputs, resolveTaskNodeInputsConfig, resolveTaskNodeTaskVariable, canonicalizeGraphTaskNodeTaskVariable, canonicalizeGraphModel, reportTaskNodeInputsLayoutIssues, taskNodeInputsLayoutWarningMessage, isTaskVariablePathRef, isTaskNode, isFinalizerNode, } from "./taskNodeTaskVariable.js";
 export { createCatalox, bindCataloxContext, Catalox, CataloxBound, } from "@x12i/catalox/embedder";
 export { loadCatalogCandidatesFromCatalox, unifiedCatalogItemToSkillDescriptor, unifiedCatalogItemToScopingMapCandidate, unifiedCatalogItemToNarrixTemplateCandidate, } from "./cataloxCatalogBridge.js";

package/dist/runGraphComposer.d.ts

@@ -1,5 +1,5 @@
 import { type LogRuntimeContext } from "@x12i/logxer";
-import { type GraphComposerLogsLevelInput } from "./graphComposerLogging.js";
+import { type GraphComposerLogsLevelInput, type StackLoggingOptions } from "./graphComposerLogging.js";
 import type { Client } from "@x12i/funcx";
 import { type LlmMode } from "@x12i/funcx/functions";
 import type { GraphComposerInput } from "./types.js";
@@ -44,6 +44,11 @@ export type RunGraphComposerOptions = {
      * Use `off` / `none` / `silent` to silence graph-composer logs for one invocation.
      */
     logsLevel?: GraphComposerLogsLevelInput;
+    /**
+     * Parent stack logging for this invocation (`StackLoggingOptions` from @x12i/logxer).
+     * Forward from the host when graph-composer is embedded in a larger app.
+     */
+    logging?: StackLoggingOptions;
     /**
      * Optional correlation ids merged into every log via @x12i/logxer `runWithLogContext`
      * (jobId, runId, graphId, nodeId, taskId, sessionId, correlationId).

package/dist/runGraphComposer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runGraphComposer.d.ts","sourceRoot":"","sources":["../src/runGraphComposer.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,uBAAuB,CAAC;AAc/B,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAC;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAC/B,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAgHhF;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,IAAI,CASN;AAuDD;;GAEG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,OAAO,GACd,OAAO,CAKT;AA0ED,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,2BAA2B,CAAC;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAmDF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,GAAG,SAAS,CA4BpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAYR;AAqLD,wBAAsB,cAAc,CAClC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAQlB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC"}
+{"version":3,"file":"runGraphComposer.d.ts","sourceRoot":"","sources":["../src/runGraphComposer.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,uBAAuB,CAAC;AAc/B,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAC;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAC/B,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAgHhF;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,IAAI,CASN;AAuDD;;GAEG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,OAAO,GACd,OAAO,CAKT;AA0ED,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,2BAA2B,CAAC;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAmDF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,GAAG,SAAS,CA4BpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAYR;AAqLD,wBAAsB,cAAc,CAClC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC"}

package/dist/runGraphComposer.js

@@ -459,7 +459,7 @@ export async function runGraphWorker(input, options = {}) {
             return runWithLogContext(ctx, () => runGraphWorkerInner(input, options));
         }
         return runGraphWorkerInner(input, options);
-    });
+    }, options.logging);
 }
 export async function runGraphComposer(input, options = {}) {
     return runGraphWorker(input, options);

package/functions/graph-composer/metadata/log-diagnostics.json

@@ -1,20 +1,20 @@
-{
-  "GRAPH_COMPOSER_WORKER_FAILED": {
-    "defaultLevel": "error",
-    "title": "Graph composer worker failed",
-    "impact": "The requested graph-composer action did not complete; callers receive no result.",
-    "possibleCauses": [
-      "OpenRouter or @x12i/funcx returned an error or timed out.",
-      "Model output failed action-specific validation.",
-      "Missing or invalid input (existingGraph, catalogCandidates, etc.)."
-    ],
-    "remediation": [
-      "Set GRAPH_COMPOSER_LOGS_LEVEL=debug (or traceReviewConceptIo for reviewConcept).",
-      "Inspect the exception message and validation errors in logs.",
-      "Verify OPENROUTER_API_KEY and LLM model slugs."
-    ],
-    "retryable": true,
-    "userActionRequired": false,
-    "confidence": "medium"
-  }
-}
+{
+  "GRAPH_COMPOSER_WORKER_FAILED": {
+    "defaultLevel": "error",
+    "title": "Graph composer worker failed",
+    "impact": "The requested graph-composer action did not complete; callers receive no result.",
+    "possibleCauses": [
+      "OpenRouter or @x12i/funcx returned an error or timed out.",
+      "Model output failed action-specific validation.",
+      "Missing or invalid input (existingGraph, catalogCandidates, etc.)."
+    ],
+    "remediation": [
+      "Set GRAPH_COMPOSER_LOGS_LEVEL=debug (or traceReviewConceptIo for reviewConcept).",
+      "Inspect the exception message and validation errors in logs.",
+      "Verify OPENROUTER_API_KEY and LLM model slugs."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  }
+}

package/functions/graph-composer/prompts/action-explain.md

@@ -8,6 +8,7 @@ You are a graph architect for the **worox-graph** DAG execution format. Your out
    - **`summary`**: 2–6 sentences: what the graph achieves end-to-end, main phases (ingest → transform → branch → infer → finalize), and where the canonical result appears.
    - **`executionOrder`**: A topologically sensible sequence of **node ids**. For branches, you may use short inline notes in string elements (e.g. `"nodeB (when tier=high)"`) or group logically—clarity beats perfect formatting.
    - **`nodeDescriptions`**: Array of objects with at least `nodeId`, `role` (one line), `reads` (memory paths, `inputs`, and `taskVariable` used), `writes` (output path or effect). Cover every task node; include the finalizer. If `focusNodeIds` is set, expand those nodes and keep others shorter.
+   - **`modelLayers`** (required when `metadata.graphModelLayers` / `graphModelLayersSummary` exist on the graph): For each **AI** task node, state the **winning** PRE/MAIN/POST profile names, resolved provider ids if stamped, **`sourcePath`** (where that triple was set — e.g. `graph-engine.default`, `graph.modelConfig`, `nodes["iq-…"].taskConfiguration.modelConfig`), and note that **runtime** overrides (`runtime.nodes[id].modelConfig`, `runtime.modelConfig`) are **not** in the graph JSON unless the host injected them at execute time. Use the stamped `stack` colors/legend when present. If no `graphModelLayers` metadata, say explicitly that the graph has **no** authored `modelConfig` and runs on **engine default** (`cheap` / `balanced` / `cheap` → bundled `@x12i/ai-profiles` provider ids).
    - **`dataFlow`**: Prose: how data enters (`input.*`), which nodes write which execution-memory paths, and how the finalizer builds the output.
    - **`conditionalPaths`**: List conditional edges: `fromNodeId`, branches with `toNodeId` and human-readable `condition`. Use `[]` if none.
 3. Use **node ids** and **paths** here as needed—they belong in technical explanation, not in product-facing `suggestConceptObjective` fields.
@@ -19,7 +20,7 @@ Respond with a **single JSON object**. **No markdown fences, no preamble, no tra
 
 The object **MUST** include top-level `"action": "explain"` (must match the request).
 
-**Required:** `action`, `explanation` (object with `summary`, `executionOrder`, `nodeDescriptions`, `dataFlow`, `conditionalPaths`); `warnings` optional.
+**Required:** `action`, `explanation` (object with `summary`, `executionOrder`, `nodeDescriptions`, `dataFlow`, `conditionalPaths`; include **`modelLayers`** when graph model metadata exists or when inferring defaults); `warnings` optional.
 
 Do **not** place `summary`, `executionOrder`, etc. at the top level—they must live under `explanation`.
 

package/functions/graph-composer/prompts/shared/graph-format.md

@@ -1,6 +1,6 @@
-## Format reference (GraphModelObject)
+## Format reference (worox-graph / GraphModelObject)
 
-Normative contracts: `docs/formats-documentations/graph-model-object-format.md` and `task-node-model-object-format.md`. Graph-composer emits **static model** JSON consumed by `@exellix/graph-engine`.
+Normative contracts for the **worox-graph** DAG JSON model: `docs/formats-documentations/graph-model-object-format.md` and `task-node-model-object-format.md`. Graph-composer emits **static model** JSON consumed by `@exellix/graph-engine`.
 
 A graph is a single JSON object. Top-level fields (canonical root keys only):
 
@@ -68,7 +68,7 @@ A graph is a single JSON object. Top-level fields (canonical root keys only):
 | Planning / UX | `metadata.*` | `graphReadability`, `catalogBinding`, `name`, `description` — **not** `aiTaskProfile` or `narrix`. |
 | Result wiring | `executionMapping` | Writes into execution memory after the task succeeds. |
 
-- **AI task nodes** must include **`taskConfiguration.aiTaskProfile`** with non-empty **`preStrategyKey`** and **`postStrategyKey`** (deployment catalog row ids). Add **`taskConfiguration.narrix`** when discovery applies. Add **`webScoping`** / **`inputSynthesis`** under **`aiTaskProfile`** when needed.
+- **AI task nodes** must include **`taskConfiguration.aiTaskProfile`** with non-empty **`preStrategyKey`** and **`postStrategyKey`** (deployment catalog row ids). Add **`taskConfiguration.narrix`** when discovery applies. Add **`webScoping`** / **`inputSynthesis`** under **`aiTaskProfile`** when needed. Legacy **`metadata.aiTaskProfile`** is dual-read and canonicalized to **`taskConfiguration`** on output — do not author new graphs under `metadata`.
 - `skillKey` must come from the provided skill catalog unless extensible mode is active.
 - Do **not** put `question`, literals, or `$path` variable refs under `inputsConfig`. Do **not** use deprecated task-node `inputs` or `outputMapping` (graph-composer renames them on output).
 - `taskVariable.question` should be clear and self-contained.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-composer",
-  "version": "2.0.9",
+  "version": "2.1.8",
   "publishConfig": {
     "access": "public"
   },
@@ -36,7 +36,7 @@
     "verify:local": "tsx src/verify-local.ts",
     "verify:catalog-live": "x12i-env run --env-file .env -- tsx scripts/verify-catalog-live.ts",
     "test": "npm run test:unit && npm run test:live",
-    "test:unit": "node --import tsx/esm --test --test-force-exit test/unit/explain-shape.test.ts test/unit/graph-concept-patch.test.ts test/unit/graph-concept-story-parse.test.ts test/unit/review-concept-output-validation.test.ts test/unit/review-concept-catalog-alias.test.ts test/unit/redact-for-log.test.ts test/unit/graph-composer-logging.test.ts test/unit/worker-instructions.test.ts test/unit/catalog-output-validation.test.ts test/unit/catalox-catalog-bridge.test.ts test/unit/ai-task-profile.test.ts test/unit/create-modify-output-validation.test.ts test/unit/task-node-task-variable.test.ts test/unit/canonical-graph-document.test.ts test/unit/graph-engine-bridge.test.ts test/unit/example-generation.test.ts",
+    "test:unit": "node --import tsx/esm --test --test-force-exit test/unit/explain-shape.test.ts test/unit/graph-concept-patch.test.ts test/unit/graph-concept-story-parse.test.ts test/unit/review-concept-output-validation.test.ts test/unit/review-concept-catalog-alias.test.ts test/unit/redact-for-log.test.ts test/unit/graph-composer-logging.test.ts test/unit/worker-instructions.test.ts test/unit/catalog-output-validation.test.ts test/unit/catalox-catalog-bridge.test.ts test/unit/ai-task-profile.test.ts test/unit/create-modify-output-validation.test.ts test/unit/task-node-task-variable.test.ts test/unit/canonical-graph-document.test.ts test/unit/graph-engine-bridge.test.ts test/unit/graph-model-layers.test.ts test/unit/example-generation.test.ts",
     "test:live": "x12i-env run --env-file .env -- node --import tsx/esm --test test/live/all.ts",
     "pack:check": "npm pack --dry-run",
     "suggest-smoke": "x12i-env run --env-file .env -- tsx scripts/run-suggest-concept-smoke.ts"
@@ -71,14 +71,14 @@
     }
   },
   "dependencies": {
-    "@x12i/ai-profiles": "^1.2.9",
-    "@x12i/catalox": "^5.1.1",
+    "@x12i/ai-profiles": "^1.7.2",
+    "@x12i/catalox": "^5.1.3",
     "@x12i/env": "^4.0.1",
-    "@x12i/funcx": "^4.2.3",
-    "@x12i/logxer": "^4.4.2"
+    "@x12i/funcx": "^4.2.7",
+    "@x12i/logxer": "^4.6.0"
   },
   "devDependencies": {
-    "@exellix/graph-engine": "^7.2.0",
+    "@exellix/graph-engine": "^7.3.8",
     "@types/node": "^22.10.2",
     "nx-config2": "^3.6.5",
     "tsx": "^4.19.2",