@exellix/graph-composer 2.0.7 → 2.1.0

package/README.md

@@ -38,7 +38,7 @@ 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) (`info`, `warn`, …). |
+| `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). |
 
 Copy [`.env.example`](./.env.example) to `.env` for local development. **Do not commit secrets.**
 
@@ -158,7 +158,30 @@ const result = await runGraphComposer(inputSuggestConceptObjectiveNetworkVulnSub
 
 **Requires** `existingGraph`. Returns **`verdict`** (`coherent`, `summary`) and **`findings`** (category, severity, summary, optional **`taskIndex`**, **`proposal`**, `nodeIds`, `suggestedChange`). When **`metadata.graphConcept.coreTasks`** is non-empty, the model should return **`graphConceptPatch`** or **`suggestedConceptPatch`** (same partial shape; prefer one) with **`coreTasks`** index-aligned to that array and partial **`requirements`** (`skill`, `catalogBinding`, `narrix`, `memoryIO`, optional **`webScoping`**, etc.) inferred from the graph and catalogs. When a single value cannot be chosen, the model may return **`requirementOptions`** (ranked **`candidates`** per `taskIndex` + dot-path **`field`**, plus **`needsNewArtifact`**). Optional extended string fields on the patch (e.g. `expectedInput`, `outputDescription`) and optional **`catalogProposals`** for catalog gaps. No `graph`, `changelog`, or `explanation`. Use for design review before heavy edits.
 
-**Tracing:** For `reviewConcept` only, `runGraphWorker` logs a **redacted** JSON snapshot of the serialized worker request and the **raw LLM worker response** (@x12i/funcx function-pack invocation): at **`debug`** by default (set `GRAPH_COMPOSER_LOGS_LEVEL=debug`), or at **`info`** when **`traceReviewConceptIo: true`** is passed in `RunGraphComposerOptions`. Payloads are capped (~500k chars) and keys matching secrets (`apiKey`, `password`, `token`, etc.) are replaced with `[redacted]`.
+**Tracing:** For `reviewConcept` only, `runGraphWorker` logs a **redacted** JSON snapshot of the serialized worker request and the **raw LLM worker response** (@x12i/funcx function-pack invocation): at **`debug`** by default (`logsLevel: "debug"` or `GRAPH_COMPOSER_LOGS_LEVEL=debug`), or at **`info`** when **`traceReviewConceptIo: true`** is passed in `RunGraphComposerOptions`. Payloads are capped (~500k chars) and keys matching secrets (`apiKey`, `password`, `token`, etc.) are replaced with `[redacted]`. Pass **`logContext`** (`jobId`, `runId`, `graphId`, …) in `RunGraphComposerOptions` so all logs correlate in Mongo/query APIs via logxer `runWithLogContext`.
+
+### Logging from downstream hosts
+
+Set the threshold once at process startup, per request, or via env:
+
+```ts
+import {
+  configureGraphComposerLogging,
+  getGraphComposerLoggingConfig,
+  runGraphComposer,
+} from "@x12i/graph-composer";
+
+// Process-wide (e.g. after reading your service config)
+configureGraphComposerLogging({ logsLevel: "info" });
+
+// Per invocation — wins over configure + env for that call only
+await runGraphComposer(input, { logsLevel: "debug", logContext: { jobId: "j-1" } });
+
+// Inspect effective level (after overrides)
+const { logsLevel, debugEnabled, envKeys } = getGraphComposerLoggingConfig();
+```
+
+Precedence per worker run: **`options.logsLevel`** → **`configureGraphComposerLogging`** → **`GRAPH_COMPOSER_LOGS_LEVEL`** (or legacy `GRAPH_COMPOSER_LOG_LEVEL`) → default **`warn`**. Use **`off`** / **`none`** / **`silent`** to silence graph-composer logs. **`getGraphComposerLogger()`** returns the shared logxer instance if you need `getJobLogs` / `scopeLogs` from the same sink.
 
 ### Generate example input
 
@@ -195,6 +218,8 @@ Both **require** `existingGraph`. Pass **`catalogCandidates`** (from **Catalox**
 In addition to `client`, `mode`, `model`, `temperature`, `maxTokens`, `askTimeoutMs`, `connectTimeoutMs`:
 
 - **`catalogMatchListsAssist`** — When not `false`, enables **`matchLists`** pre-passes for `suggestCatalogResolution`, `suggestCatalogCreations`, and **`suggestScopingNeedMatch`** when a client is resolved (skips if no client).
+- **`logsLevel`** — Per-call log threshold (`debug`, `info`, `off`, …). Overrides `configureGraphComposerLogging` and env for that run.
+- **`logContext`** — Correlation ids (`jobId`, `runId`, `graphId`, …) on every log line via logxer `runWithLogContext`.
 - **`traceReviewConceptIo`** — When `true`, emit **`reviewConcept`** request/response trace logs at **`info`** (still redacted). When `false` (default), the same traces use **`debug`** only.
 
 ### Worker actions cheat sheet
@@ -258,6 +283,7 @@ 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). |

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

@@ -0,0 +1,45 @@
+import { type LogLevel, type Logxer } 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 };
+/** Accepted inputs for `configureGraphComposerLogging` and `RunGraphComposerOptions.logsLevel`. */
+export type GraphComposerLogsLevelInput = LogLevel | "off" | "none" | "silent" | (string & {});
+export type GraphComposerLoggingConfig = {
+    /** Effective threshold after overrides (`off` when logging is disabled). */
+    logsLevel: LogLevel | "off";
+    /** True when package logging is silenced (`off` / `none` / `silent`). */
+    logsDisabled: boolean;
+    /** Whether `debug` (and `verbose`) lines are emitted. */
+    debugEnabled: boolean;
+    envKeys: {
+        canonical: string;
+        legacy: string;
+    };
+};
+/**
+ * Parse a log-level string (case-insensitive). Unknown values disable logging (`off`).
+ * Accepts logxer synonyms: `off`, `none`, `silent`.
+ */
+export declare function parseGraphComposerLogsLevel(raw: string | undefined): {
+    logsLevel: LogLevel | "off";
+    logsDisabled: boolean;
+};
+/**
+ * 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`.
+ */
+export declare function configureGraphComposerLogging(options: {
+    logsLevel?: GraphComposerLogsLevelInput;
+}): void;
+/** Current effective logging configuration (after env + programmatic overrides). */
+export declare function getGraphComposerLoggingConfig(perCall?: GraphComposerLogsLevelInput): 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>;
+//# sourceMappingURL=graphComposerLogging.d.ts.map

package/dist/graphComposerLogging.d.ts.map

@@ -0,0 +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"}

package/dist/graphComposerLogging.js

@@ -0,0 +1,132 @@
+import path from "node:path";
+import { initConfig } from "@x12i/env";
+import { createLogxer, legacyPackageLogLevelEnvKey, packageLogsLevelEnvKey, parsePackageLogsLevelString, resolvePackageLogsLevel, } 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"),
+    },
+});
+let processWideLogsLevel;
+function logxerMutableConfig(logxer) {
+    return logxer.config;
+}
+function applyResolvedToLogger(resolved) {
+    const internal = logxerMutableConfig(logger);
+    const prev = {
+        logLevel: internal.logLevel,
+        packageLogsDisabled: internal.packageLogsDisabled,
+    };
+    internal.logLevel = resolved.logLevel;
+    internal.packageLogsDisabled = resolved.packageLogsDisabled;
+    return () => {
+        internal.logLevel = prev.logLevel;
+        internal.packageLogsDisabled = prev.packageLogsDisabled;
+    };
+}
+const LOG_LEVELS = new Set([
+    "verbose",
+    "debug",
+    "info",
+    "warn",
+    "error",
+]);
+function isLogLevel(value) {
+    return LOG_LEVELS.has(value);
+}
+/**
+ * Parse a log-level string (case-insensitive). Unknown values disable logging (`off`).
+ * Accepts logxer synonyms: `off`, `none`, `silent`.
+ */
+export function parseGraphComposerLogsLevel(raw) {
+    const parsed = parsePackageLogsLevelString(raw);
+    if (parsed.packageLogsDisabled || parsed.logLevel === undefined) {
+        return { logsLevel: "off", logsDisabled: true };
+    }
+    return { logsLevel: parsed.logLevel, logsDisabled: false };
+}
+function resolveFromInput(input) {
+    if (input === "off" || input === "none" || input === "silent") {
+        return { packageLogsDisabled: true, logLevel: "error" };
+    }
+    if (typeof input === "string" && isLogLevel(input)) {
+        return { packageLogsDisabled: false, logLevel: input };
+    }
+    const parsed = parsePackageLogsLevelString(String(input));
+    if (parsed.packageLogsDisabled || parsed.logLevel === undefined) {
+        return { packageLogsDisabled: true, logLevel: "error" };
+    }
+    return { packageLogsDisabled: false, logLevel: parsed.logLevel };
+}
+function resolveGraphComposerLogsLevel(perCall) {
+    if (perCall !== undefined) {
+        return resolveFromInput(perCall);
+    }
+    if (processWideLogsLevel !== undefined) {
+        return resolveFromInput(processWideLogsLevel);
+    }
+    return resolvePackageLogsLevel({
+        envPrefix: GRAPH_COMPOSER_LOG_ENV_PREFIX,
+    });
+}
+function syncLoggerToEffectiveLevel(perCall) {
+    applyResolvedToLogger(resolveGraphComposerLogsLevel(perCall));
+}
+/**
+ * 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`.
+ */
+export function configureGraphComposerLogging(options) {
+    if (options.logsLevel === undefined) {
+        return;
+    }
+    processWideLogsLevel = options.logsLevel;
+    syncLoggerToEffectiveLevel();
+}
+/** Current effective logging configuration (after env + programmatic overrides). */
+export function getGraphComposerLoggingConfig(perCall) {
+    const resolved = resolveGraphComposerLogsLevel(perCall);
+    const logsDisabled = resolved.packageLogsDisabled;
+    return {
+        logsLevel: logsDisabled ? "off" : resolved.logLevel,
+        logsDisabled,
+        debugEnabled: !logsDisabled && logger.isLevelEnabled("debug"),
+        envKeys: {
+            canonical: packageLogsLevelEnvKey(GRAPH_COMPOSER_LOG_ENV_PREFIX),
+            legacy: legacyPackageLogLevelEnvKey(GRAPH_COMPOSER_LOG_ENV_PREFIX),
+        },
+    };
+}
+/** Shared @x12i/logxer instance for graph-composer (diagnostics catalog attached). */
+export function getGraphComposerLogger() {
+    return logger;
+}
+/**
+ * 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) {
+        syncLoggerToEffectiveLevel();
+        return fn();
+    }
+    const restore = applyResolvedToLogger(resolveGraphComposerLogsLevel(logsLevel));
+    try {
+        return await fn();
+    }
+    finally {
+        restore();
+        syncLoggerToEffectiveLevel();
+    }
+}
+// Apply env / 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,6 +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, 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 { 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";
@@ -17,6 +19,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":"AAAA,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,8BAA8B,EAC9B,mBAAmB,EACnB,6BAA6B,EAC7B,+BAA+B,EAC/B,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,GACnC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,yBAAyB,EACzB,UAAU,EACV,mCAAmC,EACnC,oCAAoC,EACpC,mBAAmB,EACnB,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,EAC7B,sBAAsB,EACtB,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,GACjC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EACL,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,mCAAmC,EACxC,KAAK,4BAA4B,GAClC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,6BAA6B,EAC7B,6BAA6B,EAC7B,0BAA0B,EAC1B,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,KAAK,yBAAyB,GAC/B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,0BAA0B,EAC1B,KAAK,6BAA6B,GACnC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACtC,qCAAqC,EACrC,qCAAqC,EACrC,uCAAuC,EACvC,2BAA2B,EAC3B,uCAAuC,EACvC,KAAK,uBAAuB,GAC7B,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EACV,mCAAmC,EACnC,4BAA4B,GAC7B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,gBAAgB,EAChB,6BAA6B,EAC7B,6CAA6C,EAC7C,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,mCAAmC,EACxC,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,8BAA8B,EAC9B,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,oBAAoB,CAAC;AAC5B,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,KAAK,+BAA+B,GACrC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,qBAAqB,EACrB,uBAAuB,EACvB,4BAA4B,EAC5B,KAAK,8BAA8B,EACnC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACnC,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,2BAA2B,EAC3B,qCAAqC,EACrC,sBAAsB,EACtB,gCAAgC,EAChC,kCAAkC,EAClC,qBAAqB,EACrB,UAAU,EACV,eAAe,EACf,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,GACnC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,OAAO,EACP,YAAY,GACb,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gCAAgC,EAChC,mCAAmC,EACnC,uCAAuC,EACvC,2CAA2C,EAC3C,KAAK,8BAA8B,EACnC,KAAK,gCAAgC,EACrC,KAAK,+BAA+B,EACpC,KAAK,+BAA+B,EACpC,KAAK,2BAA2B,GACjC,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -3,6 +3,7 @@ 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 { applyGraphConceptPatchOnlyIfEmpty } from "./graphConceptPatchMerge.js";
 export { runGraphComposerAgent, } from "./graphComposerAgent.js";
 export { buildCatalogMatchHints, } from "./catalogMatchAssist.js";
@@ -14,6 +15,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,3 +1,5 @@
+import { type LogRuntimeContext } from "@x12i/logxer";
+import { type GraphComposerLogsLevelInput } from "./graphComposerLogging.js";
 import type { Client } from "@x12i/funcx";
 import { type LlmMode } from "@x12i/funcx/functions";
 import type { GraphComposerInput } from "./types.js";
@@ -34,9 +36,19 @@ export type RunGraphComposerOptions = {
     maxTokens?: number;
     /**
      * When true, `reviewConcept` logs redacted serialized request and raw LLM result at `info`.
-     * When false (default), the same traces use `debug` (enable via `GRAPH_COMPOSER_LOGS_LEVEL=debug`).
+     * When false (default), the same traces use `debug` (enable via `logsLevel: "debug"` or env).
      */
     traceReviewConceptIo?: boolean;
+    /**
+     * Per-call log threshold. Wins over `configureGraphComposerLogging` and env for this run only.
+     * Use `off` / `none` / `silent` to silence graph-composer logs for one invocation.
+     */
+    logsLevel?: GraphComposerLogsLevelInput;
+    /**
+     * Optional correlation ids merged into every log via @x12i/logxer `runWithLogContext`
+     * (jobId, runId, graphId, nodeId, taskId, sessionId, correlationId).
+     */
+    logContext?: LogRuntimeContext;
 };
 export declare function resolveGraphComposerClient(options: RunGraphComposerOptions): Client | undefined;
 /**
@@ -44,10 +56,6 @@ export declare function resolveGraphComposerClient(options: RunGraphComposerOpti
  * Unlike `resolveGraphComposerClient`, this always returns a `Client` when OpenRouter is configured.
  */
 export declare function getGraphComposerLlmClient(options?: RunGraphComposerOptions): Client;
-/**
- * Run a single graph-composer worker (`intent.action`) with the per-action system prompt.
- * Shared by `runGraphComposer` and `runGraphComposerAgent`.
- */
 export declare function runGraphWorker(input: GraphComposerInput, options?: RunGraphComposerOptions): Promise<unknown>;
 export declare function runGraphComposer(input: GraphComposerInput, options?: RunGraphComposerOptions): Promise<unknown>;
 export declare function getPackDir(): string;

package/dist/runGraphComposer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runGraphComposer.d.ts","sourceRoot":"","sources":["../src/runGraphComposer.ts"],"names":[],"mappings":"AAKA,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;AAsHhF;;;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;CAChC,CAAC;AAgDF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,GAAG,SAAS,CA4BpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAYR;AAMD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAkJlB;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,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"}

package/dist/runGraphComposer.js

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import path from "node:path";
-import { initConfig } from "@x12i/env";
-import { createLogxer } from "@x12i/logxer";
+import { DebugLogAbstract, exceptionEvidence, fieldEvidence, runWithLogContext, } from "@x12i/logxer";
+import { getGraphComposerLogger, withGraphComposerLogsLevel, } from "./graphComposerLogging.js";
 import { createClient } from "@x12i/funcx";
 import { buildRequestPrompt, executeFuncx as invokeFuncxPack, } from "@x12i/funcx/functions";
 import { composeWorkerInstructions } from "./composeInstructions.js";
@@ -33,12 +33,7 @@ function processSuggestConceptObjectiveOutput(shaped, intent, existingGraph) {
             typeof r === "string" && r.trim().length > 0 ? `${prefix} ${r}` : prefix;
     }
 }
-// Load .env into process.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",
-});
+const logger = getGraphComposerLogger();
 let cachedRules = null;
 function loadRules() {
     if (cachedRules !== null)
@@ -253,6 +248,9 @@ function logReviewConceptIo(phase, data, traceReviewConceptIo) {
     const payload = safeJsonStringifyForLog(redacted);
     const msg = `graph-composer reviewConcept ${phase}`;
     const meta = {
+        phase,
+        debugKind: DebugLogAbstract.STATE,
+        evidence: [fieldEvidence("payloadCharLength", payload.length)],
         payloadCharLength: payload.length,
         payload,
     };
@@ -324,7 +322,7 @@ function buildGraphComposerPrompt(request) {
  * Run a single graph-composer worker (`intent.action`) with the per-action system prompt.
  * Shared by `runGraphComposer` and `runGraphComposerAgent`.
  */
-export async function runGraphWorker(input, options = {}) {
+async function runGraphWorkerInner(input, options) {
     assertInputShape(input);
     const normalized = normalizeInput(input);
     const action = normalized.intent.action;
@@ -391,6 +389,7 @@ export async function runGraphWorker(input, options = {}) {
         aiSkillCount: normalized.aiSkills.length,
         utilitySkillCount: normalized.utilitySkills.length,
         composedInstructionChars: system.length,
+        debugKind: DebugLogAbstract.EVENT,
     });
     const mode = options.mode ?? "strong";
     try {
@@ -425,17 +424,43 @@ export async function runGraphWorker(input, options = {}) {
                 });
             }
         }
-        logger.info("graph-composer worker complete", { action });
+        logger.info("graph-composer worker complete", {
+            action,
+            debugKind: DebugLogAbstract.EVENT,
+        });
         return shaped;
     }
     catch (e) {
-        logger.error("graph-composer worker failed", {
+        const message = e instanceof Error ? e.message : String(e);
+        logger.errorCode("GRAPH_COMPOSER_WORKER_FAILED", {
             action,
-            message: e instanceof Error ? e.message : String(e),
+            error: e,
+            debugKind: DebugLogAbstract.ANOMALY,
+            evidence: [
+                exceptionEvidence(e),
+                fieldEvidence("intent.action", action),
+            ],
+            diagnostics: {
+                expected: "The graph-composer worker should complete and return validated output.",
+                actual: message,
+                impact: "The requested graph-composer action did not complete; callers receive no result.",
+                retryable: true,
+                userActionRequired: false,
+                confidence: "medium",
+            },
         });
         throw e;
     }
 }
+export async function runGraphWorker(input, options = {}) {
+    return withGraphComposerLogsLevel(options.logsLevel, async () => {
+        const ctx = options.logContext;
+        if (ctx !== undefined && Object.keys(ctx).length > 0) {
+            return runWithLogContext(ctx, () => runGraphWorkerInner(input, options));
+        }
+        return runGraphWorkerInner(input, options);
+    });
+}
 export async function runGraphComposer(input, options = {}) {
     return runGraphWorker(input, options);
 }

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

@@ -0,0 +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"
+  }
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-composer",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "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/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,11 +71,11 @@
     }
   },
   "dependencies": {
-    "@x12i/ai-profiles": "^1.2.7",
-    "@x12i/catalox": "^5.1.1",
+    "@x12i/ai-profiles": "^1.7.0",
+    "@x12i/catalox": "^5.1.3",
     "@x12i/env": "^4.0.1",
-    "@x12i/funcx": "^4.2.0",
-    "@x12i/logxer": "^4.3.5"
+    "@x12i/funcx": "^4.2.4",
+    "@x12i/logxer": "^4.6.0"
   },
   "devDependencies": {
     "@exellix/graph-engine": "^7.2.0",