@exellix/graph-composer 2.0.9 → 2.1.0

package/README.md

@@ -283,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/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

@@ -19,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":"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"}

package/dist/index.js

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

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-composer",
-  "version": "2.0.9",
+  "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/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,11 +71,11 @@
     }
   },
   "dependencies": {
-    "@x12i/ai-profiles": "^1.2.9",
-    "@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.3",
-    "@x12i/logxer": "^4.4.2"
+    "@x12i/funcx": "^4.2.4",
+    "@x12i/logxer": "^4.6.0"
   },
   "devDependencies": {
     "@exellix/graph-engine": "^7.2.0",