@exellix/graph-composer 2.0.0

package/dist/runGraphComposer.js

@@ -0,0 +1,444 @@
+import { readFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { initConfig } from "@x12i/env";
+import { createLogxer } from "@x12i/logxer";
+import { createClient } from "@x12i/funcx";
+import { buildRequestPrompt, executeFuncx as invokeFuncxPack, } from "@x12i/funcx/functions";
+import { composeWorkerInstructions } from "./composeInstructions.js";
+import { buildCatalogMatchHints } from "./catalogMatchAssist.js";
+import { buildScopingNeedMatchHints } from "./scopingNeedMatchAssist.js";
+import { DEFAULT_UTILITY_SKILLS } from "./defaultUtilitySkills.js";
+import { getActionDefinition } from "./graphComposerActions.js";
+import { extractFirstFencedJsonBlock, graphComposerPackRoot, } from "./packDir.js";
+import { isGraphConceptStoryDescription, parseGraphConceptStory, } from "./parseGraphConceptStory.js";
+import { applyGraphConceptPatchOnlyIfEmpty } from "./graphConceptPatchMerge.js";
+import { redactSecretsForLog } from "./redactForLog.js";
+import { validateReviewConceptOutputAgainstInput } from "./graphComposerOutputValidation.js";
+export { redactSecretsForLog };
+export { applyGraphConceptPatchOnlyIfEmpty } from "./graphConceptPatchMerge.js";
+function processSuggestConceptObjectiveOutput(shaped, intent, existingGraph) {
+    const patchRaw = shaped.graphConceptPatch;
+    if (patchRaw === null ||
+        typeof patchRaw !== "object" ||
+        Array.isArray(patchRaw)) {
+        return;
+    }
+    const patch = patchRaw;
+    const { patch: next, skipped } = applyGraphConceptPatchOnlyIfEmpty(patch, intent.onlyIfEmpty, existingGraph);
+    shaped.graphConceptPatch = next;
+    if (skipped.length > 0) {
+        const prefix = `Skipped fields already set in metadata.graphConcept: ${skipped.join(", ")}.`;
+        const r = shaped.rationale;
+        shaped.rationale =
+            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",
+});
+let cachedRules = null;
+function loadRules() {
+    if (cachedRules !== null)
+        return cachedRules;
+    const root = graphComposerPackRoot();
+    const judgeMd = path.join(root, "prompts", "judge-rules.md");
+    const legacyJson = path.join(root, "rules.json");
+    const legacyRules = path.join(root, "rules");
+    let raw;
+    if (existsSync(judgeMd)) {
+        raw = extractFirstFencedJsonBlock(readFileSync(judgeMd, "utf-8"));
+    }
+    else if (existsSync(legacyRules)) {
+        raw = readFileSync(legacyRules, "utf-8");
+    }
+    else if (existsSync(legacyJson)) {
+        raw = readFileSync(legacyJson, "utf-8");
+    }
+    else {
+        throw new Error(`Missing judge rules: expected ${judgeMd} or legacy rules.json`);
+    }
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+        cachedRules = [];
+        return cachedRules;
+    }
+    cachedRules = parsed.filter((r) => r !== null &&
+        typeof r === "object" &&
+        "rule" in r &&
+        typeof r.rule === "string" &&
+        "weight" in r &&
+        typeof r.weight === "number");
+    return cachedRules;
+}
+function normalizeInput(input) {
+    const skillMode = input.skillMode ?? "locked";
+    const aiSkills = input.aiSkills ?? [];
+    const utilitySkills = input.utilitySkills === undefined
+        ? [...DEFAULT_UTILITY_SKILLS]
+        : input.utilitySkills;
+    return {
+        ...input,
+        skillMode,
+        aiSkills,
+        utilitySkills,
+        catalogCandidates: input.catalogCandidates,
+    };
+}
+function assertInputShape(input) {
+    const def = getActionDefinition(input.intent.action);
+    if (def.requiresExistingGraph) {
+        if (input.existingGraph === undefined ||
+            input.existingGraph === null ||
+            typeof input.existingGraph !== "object") {
+            throw new Error(`existingGraph is required when intent.action is "${def.action}"`);
+        }
+    }
+    if (input.intent.action === "suggestScopingNeedMatch") {
+        const maps = input.catalogCandidates?.scopingMaps;
+        if (!Array.isArray(maps) || maps.length === 0) {
+            throw new Error('catalogCandidates.scopingMaps must be a non-empty array when intent.action is "suggestScopingNeedMatch"');
+        }
+    }
+}
+/**
+ * Maps `suggestedCatalogArtifacts` to `catalogProposals` when the latter is empty
+ * or missing (consumer contract alias). No-op for other actions.
+ */
+export function normalizeReviewConceptComposerOutput(out) {
+    const cur = out.catalogProposals;
+    const hasProposals = Array.isArray(cur) && cur.length > 0;
+    if (hasProposals)
+        return;
+    const alt = out.suggestedCatalogArtifacts;
+    if (Array.isArray(alt) && alt.length > 0) {
+        out.catalogProposals = alt;
+    }
+}
+/** Models sometimes omit `action` or nest the payload; normalize before validation. */
+function unwrapComposerPayload(result) {
+    if (result === null || typeof result !== "object")
+        return result;
+    const o = result;
+    if (typeof o.action === "string")
+        return result;
+    for (const k of ["result", "output", "data", "response"]) {
+        const inner = o[k];
+        if (inner !== null && typeof inner === "object") {
+            const io = inner;
+            if (typeof io.action === "string" ||
+                io.graph !== undefined ||
+                io.explanation !== undefined ||
+                io.changelog !== undefined ||
+                io.graphConceptPatch !== undefined ||
+                io.suggestedConceptPatch !== undefined ||
+                io.skillResolution !== undefined ||
+                io.catalogRequestProposals !== undefined ||
+                io.hasSuitableMatch !== undefined ||
+                io.scopingMapProposal !== undefined ||
+                io.verdict !== undefined ||
+                io.findings !== undefined ||
+                io.catalogProposals !== undefined ||
+                io.suggestedCatalogArtifacts !== undefined ||
+                io.requirementOptions !== undefined) {
+                return inner;
+            }
+        }
+    }
+    return result;
+}
+const EXPLAIN_TOP_LEVEL_KEYS = [
+    "summary",
+    "executionOrder",
+    "nodeDescriptions",
+    "dataFlow",
+    "conditionalPaths",
+];
+const EXPLAIN_NODE_DESC_ALIASES = ["perNodeDescriptions", "perNode"];
+function explainTopLevelCandidatePresent(o) {
+    for (const k of EXPLAIN_TOP_LEVEL_KEYS) {
+        if (k in o && o[k] !== undefined)
+            return true;
+    }
+    for (const k of EXPLAIN_NODE_DESC_ALIASES) {
+        if (k in o && o[k] !== undefined)
+            return true;
+    }
+    return false;
+}
+/**
+ * If `action` is `explain` and known fields are flattened at the top level, moves them under `explanation` (see `functions/graph-composer/meta.json`). Maps `perNode` / `perNodeDescriptions` to `nodeDescriptions`. No-op for other actions or when `explanation` is already an object.
+ */
+export function normalizeGraphComposerExplainOutput(result) {
+    if (result === null || typeof result !== "object")
+        return result;
+    const o = result;
+    if (o.action !== "explain")
+        return result;
+    return normalizeExplainFlattenedShallow(o);
+}
+function normalizeExplainFlattenedShallow(o) {
+    const expl = o.explanation;
+    if (expl !== null &&
+        expl !== undefined &&
+        typeof expl === "object" &&
+        !Array.isArray(expl)) {
+        return { ...o };
+    }
+    if (!explainTopLevelCandidatePresent(o)) {
+        return { ...o };
+    }
+    const explanation = {};
+    for (const k of EXPLAIN_TOP_LEVEL_KEYS) {
+        if (k in o && o[k] !== undefined) {
+            explanation[k] = o[k];
+        }
+    }
+    if (explanation.nodeDescriptions === undefined) {
+        if ("perNodeDescriptions" in o &&
+            o.perNodeDescriptions !== undefined) {
+            explanation.nodeDescriptions = o.perNodeDescriptions;
+        }
+        else if ("perNode" in o && o.perNode !== undefined) {
+            explanation.nodeDescriptions = o.perNode;
+        }
+    }
+    const omit = new Set([
+        ...EXPLAIN_TOP_LEVEL_KEYS,
+        ...EXPLAIN_NODE_DESC_ALIASES,
+    ]);
+    const rest = {};
+    for (const [k, v] of Object.entries(o)) {
+        if (!omit.has(k))
+            rest[k] = v;
+    }
+    return { ...rest, explanation };
+}
+function ensureComposerOutputShape(intentAction, result) {
+    const unwrapped = unwrapComposerPayload(result);
+    if (unwrapped === null || typeof unwrapped !== "object")
+        return unwrapped;
+    const raw = unwrapped;
+    const o = typeof raw.action === "string"
+        ? { ...raw }
+        : { ...raw, action: intentAction };
+    if (o.action === "explain") {
+        return normalizeExplainFlattenedShallow(o);
+    }
+    return o;
+}
+function validateGraphComposerOutput(intentAction, out, input) {
+    if (out.action !== intentAction) {
+        throw new Error(`Output action "${String(out.action)}" does not match intent.action "${intentAction}"`);
+    }
+    getActionDefinition(intentAction).validateOutput(out, { input });
+}
+const REVIEW_TRACE_MAX_JSON_CHARS = 500_000;
+function safeJsonStringifyForLog(value) {
+    try {
+        const s = JSON.stringify(value);
+        if (s.length > REVIEW_TRACE_MAX_JSON_CHARS) {
+            return `${s.slice(0, REVIEW_TRACE_MAX_JSON_CHARS)}\n...[truncated]`;
+        }
+        return s;
+    }
+    catch {
+        return "[non-serializable]";
+    }
+}
+function logReviewConceptIo(phase, data, traceReviewConceptIo) {
+    const redacted = redactSecretsForLog(data);
+    const payload = safeJsonStringifyForLog(redacted);
+    const msg = `graph-composer reviewConcept ${phase}`;
+    const meta = {
+        payloadCharLength: payload.length,
+        payload,
+    };
+    if (traceReviewConceptIo) {
+        logger.info(msg, meta);
+    }
+    else {
+        logger.debug(msg, meta);
+    }
+}
+function withAskTimeout(client, timeoutMs) {
+    const ask = client.ask.bind(client);
+    return {
+        ...client,
+        ask(instruction, opts) {
+            return ask(instruction, {
+                ...opts,
+                timeoutMs: opts?.timeoutMs ?? timeoutMs,
+            });
+        },
+    };
+}
+export function resolveGraphComposerClient(options) {
+    const needsBuiltClient = options.client === undefined &&
+        (options.connectTimeoutMs !== undefined ||
+            options.askTimeoutMs !== undefined);
+    if (!needsBuiltClient && options.askTimeoutMs === undefined) {
+        return options.client;
+    }
+    if (options.client !== undefined) {
+        if (options.askTimeoutMs === undefined) {
+            return options.client;
+        }
+        return withAskTimeout(options.client, options.askTimeoutMs);
+    }
+    const base = createClient({
+        backend: "openrouter",
+        ...(options.connectTimeoutMs !== undefined
+            ? { openrouter: { connectTimeoutMs: options.connectTimeoutMs } }
+            : {}),
+    });
+    if (options.askTimeoutMs === undefined) {
+        return base;
+    }
+    return withAskTimeout(base, options.askTimeoutMs);
+}
+/**
+ * Returns a concrete OpenRouter client for flows that require `client.ask` (e.g. orchestrator).
+ * Unlike `resolveGraphComposerClient`, this always returns a `Client` when OpenRouter is configured.
+ */
+export function getGraphComposerLlmClient(options = {}) {
+    const resolved = resolveGraphComposerClient(options);
+    if (resolved !== undefined)
+        return resolved;
+    const base = createClient({
+        backend: "openrouter",
+        ...(options.connectTimeoutMs !== undefined
+            ? { openrouter: { connectTimeoutMs: options.connectTimeoutMs } }
+            : {}),
+    });
+    return options.askTimeoutMs !== undefined
+        ? withAskTimeout(base, options.askTimeoutMs)
+        : base;
+}
+function buildGraphComposerPrompt(request) {
+    return `# graph-composer\n\n${buildRequestPrompt(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 = {}) {
+    assertInputShape(input);
+    const normalized = normalizeInput(input);
+    const action = normalized.intent.action;
+    getActionDefinition(action);
+    const rules = loadRules();
+    const system = composeWorkerInstructions(action, normalized.aiSkills, normalized.utilitySkills, normalized.skillMode);
+    /** Per-mode system text for aifunctions-js (same pack for all tiers unless you add ultra-specific prompts). */
+    const instructions = {
+        weak: system,
+        normal: system,
+        strong: system,
+        ultra: system,
+    };
+    const client = resolveGraphComposerClient(options);
+    let requestForPrompt = normalized;
+    const assist = options.catalogMatchListsAssist !== false &&
+        (action === "suggestCatalogResolution" ||
+            action === "suggestCatalogCreations") &&
+        client !== undefined &&
+        normalized.catalogCandidates !== undefined;
+    if (assist) {
+        const hints = await buildCatalogMatchHints(normalized, {
+            client,
+            mode: options.mode,
+            model: options.model,
+        });
+        if (hints !== undefined) {
+            requestForPrompt = { ...normalized, catalogMatchHints: hints };
+        }
+    }
+    const scopingAssist = options.catalogMatchListsAssist !== false &&
+        action === "suggestScopingNeedMatch" &&
+        client !== undefined;
+    if (scopingAssist) {
+        const sh = await buildScopingNeedMatchHints(normalized, {
+            client,
+            mode: options.mode,
+            model: options.model,
+        });
+        if (sh !== undefined) {
+            requestForPrompt = { ...requestForPrompt, scopingNeedMatchHints: sh };
+        }
+    }
+    const focusEmpty = normalized.intent.focusNodeIds === undefined ||
+        normalized.intent.focusNodeIds.length === 0;
+    if ((action === "create" ||
+        action === "modify" ||
+        action === "reviewConcept") &&
+        focusEmpty &&
+        isGraphConceptStoryDescription(normalized.intent.description)) {
+        requestForPrompt = {
+            ...requestForPrompt,
+            graphConceptFromStory: {
+                parsed: parseGraphConceptStory(normalized.intent.description),
+            },
+        };
+    }
+    if (action === "reviewConcept") {
+        logReviewConceptIo("request", requestForPrompt, options.traceReviewConceptIo);
+    }
+    logger.info("graph-composer worker start", {
+        action,
+        skillMode: normalized.skillMode,
+        aiSkillCount: normalized.aiSkills.length,
+        utilitySkillCount: normalized.utilitySkills.length,
+        composedInstructionChars: system.length,
+    });
+    const mode = options.mode ?? "strong";
+    try {
+        // One @x12i/funcx function-pack LLM call for this intent.action (not a DAG node skill).
+        const result = await invokeFuncxPack({
+            request: requestForPrompt,
+            buildPrompt: buildGraphComposerPrompt,
+            instructions,
+            rules,
+            client,
+            mode,
+            model: options.model,
+            temperature: options.temperature,
+            maxTokens: options.maxTokens,
+        });
+        if (action === "reviewConcept") {
+            logReviewConceptIo("rawResult", result, options.traceReviewConceptIo);
+        }
+        const shaped = ensureComposerOutputShape(action, result);
+        if (shaped !== null && typeof shaped === "object") {
+            const o = shaped;
+            if (action === "reviewConcept") {
+                normalizeReviewConceptComposerOutput(o);
+            }
+            if (action === "suggestConceptObjective") {
+                processSuggestConceptObjectiveOutput(o, normalized.intent, normalized.existingGraph);
+            }
+            validateGraphComposerOutput(action, shaped, normalized);
+            if (action === "reviewConcept") {
+                validateReviewConceptOutputAgainstInput(shaped, {
+                    existingGraph: normalized.existingGraph,
+                });
+            }
+        }
+        logger.info("graph-composer worker complete", { action });
+        return shaped;
+    }
+    catch (e) {
+        logger.error("graph-composer worker failed", {
+            action,
+            message: e instanceof Error ? e.message : String(e),
+        });
+        throw e;
+    }
+}
+export async function runGraphComposer(input, options = {}) {
+    return runGraphWorker(input, options);
+}
+export function getPackDir() {
+    return graphComposerPackRoot();
+}

package/dist/scopingCatalogHostTypes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Host-side handoff types for creating scoping catalog rows (e.g. Catalox native
+ * catalog + governance, or your persistence layer). **Verify** field names against
+ * your catalog schema; graph-composer does not perform CRUD.
+ */
+/** Payload your service might send to register a new scoping map document shape. */
+export type WoroxScopingMapCatalogCreatePayload = {
+    /** Canonical id, e.g. xmemory:scopemap:v1:... */
+    scopingMapId: string;
+    title: string;
+    purpose: string;
+    /** Optional: default question framing for scoped Q&A docs */
+    questionTitle?: string;
+    /** Tags for list APIs / UI */
+    tags?: string[];
+};
+/** Example Mongo-oriented create body for xmemory scoped data layout (illustrative). */
+export type WoroxScopedDataDocumentShape = {
+    _meta: {
+        scopingMapId: string;
+        entityId: string;
+        entityType?: string;
+        questionTitle?: string;
+        scopedAt?: string;
+    };
+    answer: Record<string, unknown>;
+};
+//# sourceMappingURL=scopingCatalogHostTypes.d.ts.map

package/dist/scopingCatalogHostTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopingCatalogHostTypes.d.ts","sourceRoot":"","sources":["../src/scopingCatalogHostTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oFAAoF;AACpF,MAAM,MAAM,mCAAmC,GAAG;IAChD,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,wFAAwF;AACxF,MAAM,MAAM,4BAA4B,GAAG;IACzC,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC"}

package/dist/scopingCatalogHostTypes.js

@@ -0,0 +1,6 @@
+/**
+ * Host-side handoff types for creating scoping catalog rows (e.g. Catalox native
+ * catalog + governance, or your persistence layer). **Verify** field names against
+ * your catalog schema; graph-composer does not perform CRUD.
+ */
+export {};

package/dist/scopingNeedMatchAssist.d.ts

@@ -0,0 +1,14 @@
+import type { Client } from "@x12i/funcx";
+import type { LlmMode } from "@x12i/funcx/functions";
+import type { GraphComposerInput } from "./types.js";
+export type ScopingNeedMatchAssistOptions = {
+    client: Client;
+    mode?: LlmMode;
+    model?: string;
+};
+/**
+ * `matchLists` pre-pass: map the stated need (and optional graph hint) to `scopingMaps` candidates.
+ * Injected as `scopingNeedMatchHints` on the worker request payload.
+ */
+export declare function buildScopingNeedMatchHints(input: GraphComposerInput, opts: ScopingNeedMatchAssistOptions): Promise<Record<string, unknown> | undefined>;
+//# sourceMappingURL=scopingNeedMatchAssist.d.ts.map

package/dist/scopingNeedMatchAssist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopingNeedMatchAssist.d.ts","sourceRoot":"","sources":["../src/scopingNeedMatchAssist.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AA0BpB,MAAM,MAAM,6BAA6B,GAAG;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,kBAAkB,EACzB,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAqC9C"}

package/dist/scopingNeedMatchAssist.js

@@ -0,0 +1,58 @@
+import { matchLists } from "@x12i/funcx/functions";
+function scopingCatalogItems(maps) {
+    return maps.map((m) => ({
+        scopingMapId: m.scopingMapId,
+        questionId: m.questionId,
+        title: m.title,
+        description: m.description,
+        tags: m.tags ?? [],
+    }));
+}
+function graphOneLiner(graph) {
+    if (graph === undefined || graph === null || typeof graph !== "object") {
+        return undefined;
+    }
+    const g = graph;
+    const id = typeof g.id === "string" ? g.id : "";
+    const nodes = g.nodes;
+    const n = Array.isArray(nodes) ? nodes.length : 0;
+    if (!id && n === 0)
+        return undefined;
+    return [id ? `graphId=${id}` : null, `taskNodeCount~${n}`]
+        .filter(Boolean)
+        .join(" ");
+}
+/**
+ * `matchLists` pre-pass: map the stated need (and optional graph hint) to `scopingMaps` candidates.
+ * Injected as `scopingNeedMatchHints` on the worker request payload.
+ */
+export async function buildScopingNeedMatchHints(input, opts) {
+    if (input.intent.action !== "suggestScopingNeedMatch") {
+        return undefined;
+    }
+    const maps = input.catalogCandidates?.scopingMaps;
+    if (!Array.isArray(maps) || maps.length === 0) {
+        return undefined;
+    }
+    const need = input.intent.description?.trim() ?? "";
+    if (need === "") {
+        return undefined;
+    }
+    const hint = graphOneLiner(input.existingGraph);
+    const list1 = [
+        {
+            need,
+            ...(hint !== undefined ? { graphHint: hint } : {}),
+        },
+    ];
+    const { client, mode, model } = opts;
+    const r = await matchLists({
+        list1,
+        list2: scopingCatalogItems(maps),
+        guidance: "Match the data need to the single best scoping map or questionId candidate. Prefer precise title/description fit over generic maps. Use reason briefly.",
+        mode,
+        client,
+        model,
+    }, { rules: [] });
+    return { matches: r.matches, unmatched: r.unmatched };
+}

package/dist/taskNodeTaskVariable.d.ts

@@ -0,0 +1,44 @@
+/**
+
+ * Task nodes (GraphModelObject / TaskNode): runtime payload bindings in
+
+ * `inputsConfig`; dynamic task config in `taskVariable`; results in
+
+ * `executionMapping`. See `docs/formats-documentations/`.
+
+ */
+export type TaskNodeInputsLayoutIssueCode = "variables_in_inputs" | "question_in_inputs" | "deprecated_inputs_field" | "deprecated_inputs_and_inputsConfig" | "deprecated_output_mapping" | "metadata_ai_task_profile" | "metadata_narrix" | "metadata_execution_key";
+export type TaskNodeInputsLayoutIssue = {
+    nodeId: string;
+    code: TaskNodeInputsLayoutIssueCode;
+    keys?: string[];
+    metadataKey?: string;
+};
+export declare function isFinalizerNode(node: Record<string, unknown>): boolean;
+export declare function isTaskNode(node: Record<string, unknown>): boolean;
+/** True when the value is a `$path` ref to a template variable bucket. */
+export declare function isTaskVariablePathRef(v: unknown): boolean;
+/** Dual-read: canonical `inputsConfig`, then legacy `inputs`. */
+export declare function resolveTaskNodeInputsConfig(node: Record<string, unknown>): Record<string, unknown> | undefined;
+/** @deprecated Use `resolveTaskNodeInputsConfig`. */
+export declare function resolveTaskNodeInputs(node: Record<string, unknown>): Record<string, unknown> | undefined;
+export declare function resolveTaskNodeTaskVariable(node: Record<string, unknown>): Record<string, unknown> | undefined;
+export declare function reportTaskNodeInputsLayoutIssues(graph: object): TaskNodeInputsLayoutIssue[];
+/**
+
+ * Canonicalizes task nodes toward `docs/formats-documentations`:
+
+ * - splits dynamic config into `taskVariable`
+
+ * - renames `inputs` → `inputsConfig`, `outputMapping` → `executionMapping`
+
+ * - moves execution keys from `metadata` → `taskConfiguration`
+
+ * - preserves `variables.*` / `jobVariables.*` / `taskVariables.*` path refs as authored
+
+ */
+export declare function canonicalizeGraphTaskNodeTaskVariable(graph: object): object;
+/** Full graph model canonicalization for create/modify output. */
+export declare function canonicalizeGraphModel(graph: object): object;
+export declare function taskNodeInputsLayoutWarningMessage(issues: TaskNodeInputsLayoutIssue[]): string;
+//# sourceMappingURL=taskNodeTaskVariable.d.ts.map

package/dist/taskNodeTaskVariable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taskNodeTaskVariable.d.ts","sourceRoot":"","sources":["../src/taskNodeTaskVariable.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,MAAM,MAAM,6BAA6B,GAErC,qBAAqB,GAErB,oBAAoB,GAEpB,yBAAyB,GAEzB,oCAAoC,GAEpC,2BAA2B,GAE3B,0BAA0B,GAE1B,iBAAiB,GAEjB,wBAAwB,CAAC;AAI7B,MAAM,MAAM,yBAAyB,GAAG;IAEtC,MAAM,EAAE,MAAM,CAAC;IAEf,IAAI,EAAE,6BAA6B,CAAC;IAEpC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,WAAW,CAAC,EAAE,MAAM,CAAC;CAEtB,CAAC;AAsDF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAItE;AAID,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAQjE;AAkBD,0EAA0E;AAE1E,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAgBzD;AAID,iEAAiE;AAEjE,wBAAgB,2BAA2B,CAEzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAE5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAMrC;AAID,qDAAqD;AAErD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAErC;AAID,wBAAgB,2BAA2B,CAEzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAE5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAMrC;AAgCD,wBAAgB,gCAAgC,CAE9C,KAAK,EAAE,MAAM,GAEZ,yBAAyB,EAAE,CAwH7B;AAoOD;;;;;;;;;;;;GAYG;AAEH,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI3E;AAID,kEAAkE;AAElE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAoD5D;AAID,wBAAgB,kCAAkC,CAEhD,MAAM,EAAE,yBAAyB,EAAE,GAElC,MAAM,CA8HR"}