@exellix/graph-engine 6.0.0

package/dist/src/runtime/graphEngineMemoryPaths.js

@@ -0,0 +1,55 @@
+/**
+ * Allowed memory-path roots for smartInput.paths and taskConfiguration.aiTaskProfile.inputSynthesis.sources.
+ * `input` and `inputs` are distinct roots (see `.docs/CR-input-and-inputs-dual-root.md`).
+ */
+export const GRAPH_ENGINE_MEMORY_PATH_ROOTS = [
+    'input',
+    'inputs',
+    'variables',
+    'jobVariables',
+    'taskVariables',
+    'jobMemory',
+    'taskMemory',
+    'executionMemory',
+    'xynthesized.job',
+    'xynthesized.task',
+    'xynthesized.execution',
+];
+const ALLOWED_ROOTS = GRAPH_ENGINE_MEMORY_PATH_ROOTS;
+const MEMORY_ROOTS_LONGEST_FIRST = [...ALLOWED_ROOTS].sort((a, b) => b.length - a.length);
+/** Splits a path into allowlisted root + dot tail (longest root wins, e.g. `inputs` before `input`). */
+export function splitGraphEngineMemoryPath(path) {
+    const p = typeof path === 'string' ? path.trim() : '';
+    if (!p)
+        return { root: '', tail: '' };
+    for (const root of MEMORY_ROOTS_LONGEST_FIRST) {
+        if (p === root)
+            return { root, tail: '' };
+        if (p.startsWith(`${root}.`))
+            return { root, tail: p.slice(root.length + 1) };
+    }
+    return { root: p, tail: '' };
+}
+function isAllowedGraphEngineMemoryPathForRoot(path) {
+    const p = path.trim();
+    if (!p)
+        return false;
+    for (const root of ALLOWED_ROOTS) {
+        if (p === root || p.startsWith(`${root}.`))
+            return true;
+    }
+    return false;
+}
+export function isAllowedGraphEngineMemoryPath(path) {
+    return isAllowedGraphEngineMemoryPathForRoot(path);
+}
+export function graphEngineMemoryPathValidationMessage(path) {
+    const raw = typeof path === 'string' ? path.trim() : String(path);
+    if (!raw)
+        return 'disallowed or empty path ""';
+    const { root } = splitGraphEngineMemoryPath(raw);
+    if (root && !ALLOWED_ROOTS.includes(root)) {
+        return `disallowed path "${raw}" — root must be one of: ${ALLOWED_ROOTS.join(', ')}`;
+    }
+    return `disallowed or empty path "${raw}"`;
+}

package/dist/src/runtime/graphResponseMapping.d.ts

@@ -0,0 +1,23 @@
+import type { Graph, GraphResponseDefinition } from '../types/refs.js';
+declare const GRAPH_RESPONSE_MAPPING_ERROR_CODE = "GRAPH_RESPONSE_MAPPING_INVALID";
+export type GraphResponseMappingContext = {
+    graph: Graph;
+    executionMemory: unknown;
+    outputsMemory?: unknown;
+    selectedFinalOutput?: unknown;
+    outputsByNodeId?: Record<string, unknown>;
+    stepsResponses?: unknown[];
+};
+export type GraphResponseMappingError = Error & {
+    code: typeof GRAPH_RESPONSE_MAPPING_ERROR_CODE;
+    path?: string;
+    details?: Record<string, unknown>;
+};
+export declare function assertGraphResponseDefinition(response: unknown): asserts response is GraphResponseDefinition;
+export declare function applyGraphResponseDefinition(args: {
+    response: GraphResponseDefinition;
+    context: GraphResponseMappingContext;
+}): unknown;
+/** @deprecated Use applyGraphResponseDefinition with root-level graph.response. */
+export declare const applyGraphResponseMapping: typeof applyGraphResponseDefinition;
+export {};

package/dist/src/runtime/graphResponseMapping.js

@@ -0,0 +1,156 @@
+import { selectByPath } from './pathExpr.js';
+import { isNodeInputsConfigSelectorType, readTaskNodeModelInputSurface, } from './readTaskNodeInputsConfig.js';
+const GRAPH_RESPONSE_MAPPING_ERROR_CODE = 'GRAPH_RESPONSE_MAPPING_INVALID';
+const OMIT = Symbol('graphResponseMapping.omit');
+const FORBIDDEN_GRAPH_RESPONSE_KEYS = [
+    'version',
+    'target',
+    'primaryResponsePaths',
+    'debugResponsePaths',
+    'notableExecutionPaths',
+    'mappingPreset',
+];
+function createGraphResponseMappingError(message, path, details) {
+    const err = new Error(message);
+    err.code = GRAPH_RESPONSE_MAPPING_ERROR_CODE;
+    if (path)
+        err.path = path;
+    if (details)
+        err.details = details;
+    return err;
+}
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function isSupportedSelector(v) {
+    if (!isPlainObject(v) || typeof v.type !== 'string')
+        return false;
+    return (v.type === 'outputsMemoryPath' ||
+        v.type === 'executionMemoryPath' ||
+        v.type === 'executionPath' ||
+        v.type === 'nodeMetadata' ||
+        v.type === 'nodeInputsConfig' ||
+        v.type === 'nodeInputs' ||
+        v.type === 'literal' ||
+        v.type === 'firstPresent');
+}
+function getGraphNodes(graph) {
+    return Array.isArray(graph.nodes)
+        ? graph.nodes
+        : Object.values(graph.nodes ?? {});
+}
+function getNodeById(graph, nodeId) {
+    return getGraphNodes(graph).find((node) => String(node?.id) === nodeId);
+}
+function assertNonEmptyString(value, path, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw createGraphResponseMappingError(`${label} must be a non-empty string.`, path, { actual: value });
+    }
+    return value;
+}
+export function assertGraphResponseDefinition(response) {
+    if (!isPlainObject(response)) {
+        throw createGraphResponseMappingError('graph.response must be a plain object.', 'graph.response');
+    }
+    for (const key of FORBIDDEN_GRAPH_RESPONSE_KEYS) {
+        if (key in response) {
+            throw createGraphResponseMappingError(`graph.response.${key} is not part of the root response contract.`, `graph.response.${key}`, { key });
+        }
+    }
+    if (response.missing !== undefined && response.missing !== 'omit' && response.missing !== 'null') {
+        throw createGraphResponseMappingError('graph.response.missing must be "omit" or "null" when provided.', 'graph.response.missing', { actual: response.missing });
+    }
+    if (!('shape' in response)) {
+        throw createGraphResponseMappingError('graph.response.shape is required.', 'graph.response.shape');
+    }
+}
+function materializeMissing(missing) {
+    return missing === 'null' ? null : OMIT;
+}
+function presentOrMissing(value, missing) {
+    return value === undefined || value === null ? materializeMissing(missing) : value;
+}
+function resolveSelector(selector, context, path, missing) {
+    if (selector.type === 'literal') {
+        if (!Object.prototype.hasOwnProperty.call(selector, 'value')) {
+            throw createGraphResponseMappingError('literal selector requires a value field.', `${path}.value`);
+        }
+        return selector.value;
+    }
+    if (selector.type === 'outputsMemoryPath') {
+        const sourcePath = assertNonEmptyString(selector.path, `${path}.path`, `${selector.type}.path`);
+        return presentOrMissing(selectByPath(context.outputsMemory, sourcePath), missing);
+    }
+    if (selector.type === 'executionMemoryPath' || selector.type === 'executionPath') {
+        const sourcePath = assertNonEmptyString(selector.path, `${path}.path`, `${selector.type}.path`);
+        return presentOrMissing(selectByPath(context.executionMemory, sourcePath), missing);
+    }
+    if (selector.type === 'nodeMetadata') {
+        const nodeId = assertNonEmptyString(selector.nodeId, `${path}.nodeId`, `${selector.type}.nodeId`);
+        const sourcePath = assertNonEmptyString(selector.path, `${path}.path`, `${selector.type}.path`);
+        const node = getNodeById(context.graph, nodeId);
+        if (!node) {
+            throw createGraphResponseMappingError(`${selector.type} selector references missing nodeId "${nodeId}".`, `${path}.nodeId`, { nodeId });
+        }
+        return presentOrMissing(selectByPath(node.metadata, sourcePath), missing);
+    }
+    if (isNodeInputsConfigSelectorType(selector.type)) {
+        const inputSelector = selector;
+        const nodeId = assertNonEmptyString(inputSelector.nodeId, `${path}.nodeId`, `${selector.type}.nodeId`);
+        const sourcePath = assertNonEmptyString(inputSelector.path, `${path}.path`, `${selector.type}.path`);
+        const node = getNodeById(context.graph, nodeId);
+        if (!node) {
+            throw createGraphResponseMappingError(`${selector.type} selector references missing nodeId "${nodeId}".`, `${path}.nodeId`, { nodeId });
+        }
+        const root = readTaskNodeModelInputSurface(node);
+        return presentOrMissing(selectByPath(root, sourcePath), missing);
+    }
+    if (selector.type === 'firstPresent') {
+        if (!Array.isArray(selector.sources) || selector.sources.length === 0) {
+            throw createGraphResponseMappingError('firstPresent selector requires a non-empty sources array.', `${path}.sources`);
+        }
+        for (let i = 0; i < selector.sources.length; i++) {
+            const source = selector.sources[i];
+            if (!isSupportedSelector(source)) {
+                throw createGraphResponseMappingError('firstPresent.sources entries must be graph response mapping selectors.', `${path}.sources.${i}`);
+            }
+            const value = resolveSelector(source, context, `${path}.sources.${i}`, 'omit');
+            if (value !== OMIT && value !== null)
+                return value;
+        }
+        return materializeMissing(missing);
+    }
+    throw createGraphResponseMappingError(`Unsupported graph response mapping selector type "${String(selector.type)}".`, `${path}.type`);
+}
+function resolveShape(shape, context, path, missing) {
+    if (isSupportedSelector(shape)) {
+        return resolveSelector(shape, context, path, missing);
+    }
+    if (Array.isArray(shape)) {
+        const out = [];
+        for (let i = 0; i < shape.length; i++) {
+            const value = resolveShape(shape[i], context, `${path}.${i}`, missing);
+            if (value !== OMIT)
+                out.push(value);
+        }
+        return out;
+    }
+    if (isPlainObject(shape)) {
+        const out = {};
+        for (const [key, valueShape] of Object.entries(shape)) {
+            const value = resolveShape(valueShape, context, `${path}.${key}`, missing);
+            if (value !== OMIT)
+                out[key] = value;
+        }
+        return out;
+    }
+    return shape;
+}
+export function applyGraphResponseDefinition(args) {
+    assertGraphResponseDefinition(args.response);
+    const missing = args.response.missing ?? 'omit';
+    const mapped = resolveShape(args.response.shape, args.context, 'graph.response.shape', missing);
+    return mapped === OMIT ? undefined : mapped;
+}
+/** @deprecated Use applyGraphResponseDefinition with root-level graph.response. */
+export const applyGraphResponseMapping = applyGraphResponseDefinition;

package/dist/src/runtime/graphResponseMigration.d.ts

@@ -0,0 +1,7 @@
+import type { GraphModelObject } from '../types/refs.js';
+export type MigrateGraphResponseResult<T> = {
+    graph: T;
+    migrated: boolean;
+};
+export declare function migrateLegacyGraphResponseDefinition<T extends object>(graph: T): MigrateGraphResponseResult<T>;
+export declare function migrateLegacyGraphResponse<T extends GraphModelObject | object>(graph: T): MigrateGraphResponseResult<T>;

package/dist/src/runtime/graphResponseMigration.js

@@ -0,0 +1,44 @@
+const LEGACY_RESPONSE_DROP_KEYS = new Set([
+    'version',
+    'target',
+    'primaryResponsePaths',
+    'debugResponsePaths',
+    'notableExecutionPaths',
+    'mappingPreset',
+]);
+function isPlainObject(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function cloneGraph(graph) {
+    return structuredClone(graph);
+}
+export function migrateLegacyGraphResponseDefinition(graph) {
+    const graphRecord = graph;
+    const metadata = isPlainObject(graphRecord.metadata) ? graphRecord.metadata : undefined;
+    const graphResponse = metadata && isPlainObject(metadata.graphResponse) ? metadata.graphResponse : undefined;
+    const legacyMapping = graphResponse && isPlainObject(graphResponse.responseMapping)
+        ? graphResponse.responseMapping
+        : undefined;
+    if (graphRecord.response !== undefined || !legacyMapping) {
+        return { graph, migrated: false };
+    }
+    const next = cloneGraph(graph);
+    const nextRecord = next;
+    const response = {};
+    for (const [key, value] of Object.entries(legacyMapping)) {
+        if (LEGACY_RESPONSE_DROP_KEYS.has(key))
+            continue;
+        response[key] = value;
+    }
+    if (!Object.prototype.hasOwnProperty.call(response, 'missing')) {
+        response.missing = 'omit';
+    }
+    nextRecord.response = response;
+    if (isPlainObject(nextRecord.metadata)) {
+        delete nextRecord.metadata.graphResponse;
+    }
+    return { graph: next, migrated: true };
+}
+export function migrateLegacyGraphResponse(graph) {
+    return migrateLegacyGraphResponseDefinition(graph);
+}

package/dist/src/runtime/graphRunExecutionSeed.d.ts

@@ -0,0 +1,29 @@
+import type { Job } from '../types/refs.js';
+export type GraphEngineXynthesizedState = {
+    job: Record<string, unknown>;
+    taskByNode: Record<string, Record<string, unknown>>;
+    execution: Record<string, unknown>;
+};
+/**
+ * Ensures internal execution shape for xynthesized graph memory and caller `inputs` bag seeding.
+ */
+export declare function seedGraphRunExecutionState(args: {
+    execution: Record<string, unknown>;
+    jobMemory: Record<string, unknown>;
+    job?: Job;
+}): void;
+/** Outbound {@link XynthesizedMemory} for ai-tasks `xynthesized` field. */
+export declare function xynthesizedOutboundForNode(execution: Record<string, unknown>, nodeId: string): {
+    job: Record<string, unknown>;
+    task: Record<string, unknown>;
+    execution: Record<string, unknown>;
+};
+export declare function mergeXynthesizedPatchIntoExecution(args: {
+    execution: Record<string, unknown>;
+    nodeId: string;
+    patch: {
+        job?: Record<string, unknown>;
+        task?: Record<string, unknown>;
+        execution?: Record<string, unknown>;
+    } | undefined | null;
+}): void;

package/dist/src/runtime/graphRunExecutionSeed.js

@@ -0,0 +1,61 @@
+import { extractCallerInputsBag } from './resolveGraphEngineMemoryPaths.js';
+import { deepMerge } from './deepMerge.js';
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Ensures internal execution shape for xynthesized graph memory and caller `inputs` bag seeding.
+ */
+export function seedGraphRunExecutionState(args) {
+    const { execution, jobMemory } = args;
+    ensureXynthesizedOnExecution(execution);
+    const callerInputs = extractCallerInputsBag({ execution, jobMemory });
+    if (callerInputs != null && !isPlainObject(execution.inputs)) {
+        execution.inputs = { ...callerInputs };
+    }
+}
+/** Outbound {@link XynthesizedMemory} for ai-tasks `xynthesized` field. */
+export function xynthesizedOutboundForNode(execution, nodeId) {
+    const xy = execution.xynthesized;
+    const job = (xy?.job != null && typeof xy.job === 'object' && !Array.isArray(xy.job) ? xy.job : {});
+    const task = xy?.taskByNode != null && typeof xy.taskByNode === 'object' && !Array.isArray(xy.taskByNode)
+        ? xy.taskByNode[nodeId] ?? {}
+        : {};
+    const executionBucket = xy?.execution != null && typeof xy.execution === 'object' && !Array.isArray(xy.execution) ? xy.execution : {};
+    return {
+        job,
+        task: task != null && typeof task === 'object' && !Array.isArray(task) ? task : {},
+        execution: executionBucket,
+    };
+}
+function ensureXynthesizedOnExecution(execution) {
+    let xy = execution.xynthesized;
+    if (!isPlainObject(xy)) {
+        xy = {};
+        execution.xynthesized = xy;
+    }
+    const xyo = xy;
+    if (!isPlainObject(xyo.job))
+        xyo.job = {};
+    if (!isPlainObject(xyo.taskByNode))
+        xyo.taskByNode = {};
+    if (!isPlainObject(xyo.execution))
+        xyo.execution = {};
+    return xyo;
+}
+export function mergeXynthesizedPatchIntoExecution(args) {
+    const { execution, nodeId, patch } = args;
+    if (patch == null || typeof patch !== 'object')
+        return;
+    const xy = ensureXynthesizedOnExecution(execution);
+    if (patch.job != null && typeof patch.job === 'object' && !Array.isArray(patch.job)) {
+        xy.job = deepMerge(xy.job ?? {}, patch.job);
+    }
+    if (patch.task != null && typeof patch.task === 'object' && !Array.isArray(patch.task)) {
+        const prev = xy.taskByNode[nodeId] ?? {};
+        xy.taskByNode[nodeId] = deepMerge(prev, patch.task);
+    }
+    if (patch.execution != null && typeof patch.execution === 'object' && !Array.isArray(patch.execution)) {
+        xy.execution = deepMerge(xy.execution ?? {}, patch.execution);
+    }
+}

package/dist/src/runtime/graphRunIdentity.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Host-supplied correlation id for a single graph run (queue/matrix/job id from outside this package).
+ * Must be non-empty after trim.
+ */
+export declare function assertHostJobId(jobId: unknown): string;
+/** One UUID per `executeGraph` invocation — forwarded on every `runTask` as `taskId` and on graph/node events. */
+export declare function newGraphRunTaskId(): string;

package/dist/src/runtime/graphRunIdentity.js

@@ -0,0 +1,18 @@
+import { randomUUID } from "node:crypto";
+import { ExellixGraphError } from "../errors/ExellixGraphError.js";
+import { ExellixGraphErrorCode } from "../errors/exellixGraphErrorCodes.js";
+/**
+ * Host-supplied correlation id for a single graph run (queue/matrix/job id from outside this package).
+ * Must be non-empty after trim.
+ */
+export function assertHostJobId(jobId) {
+    const s = jobId == null ? "" : String(jobId).trim();
+    if (!s) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.JOB_ID_REQUIRED, "executeGraph requires a non-empty host `jobId` string.", {});
+    }
+    return s;
+}
+/** One UUID per `executeGraph` invocation — forwarded on every `runTask` as `taskId` and on graph/node events. */
+export function newGraphRunTaskId() {
+    return randomUUID();
+}

package/dist/src/runtime/localSkills/deterministicRule.d.ts

@@ -0,0 +1,137 @@
+/**
+ * deterministic-rule — local deterministic skill.
+ *
+ * Evaluates a rule table against executionMemory (or a custom root path) and returns
+ * the first matching rule's output, a full evaluation trace, and optional sensitivity
+ * analysis for UNKNOWN-tagged inputs (DQ-1 swing calculation).
+ *
+ * Node config (in node.taskConfiguration):
+ *   rules            : Rule[]    — ordered list of rules
+ *   firstMatchWins   : boolean   — default true; when false all matching rules fire
+ *   defaultOutput    : object?   — emitted when no rule matches
+ *   sensitivityAnalysis : SensitivityAnalysisConfig? — only used by DQ-1
+ *
+ * Each rule:
+ *   id        : string
+ *   label?    : string         — human-readable description
+ *   condition : Condition      — nested logical condition
+ *   output    : Record<string,unknown>  — merged into result when this rule fires
+ *   stopOnMatch? : boolean     — default true (respected when firstMatchWins=true)
+ *
+ * Condition operators (leaf):
+ *   { path, eq }       — strict equality
+ *   { path, in }       — value in array
+ *   { path, gte }      — >= number
+ *   { path, gt }       — > number
+ *   { path, lte }      — <= number
+ *   { path, lt }       — < number
+ *   { path, exists }   — boolean (truthy check when true, falsy check when false)
+ *   { path, contains } — string or array contains value
+ *   { path, regex }    — string matches pattern
+ * Compound:
+ *   { all: Condition[] }
+ *   { any: Condition[] }
+ *   { not: Condition }
+ *
+ * Output:
+ * {
+ *   matched        : boolean
+ *   rule_id        : string | null
+ *   rule_label     : string | null
+ *   output         : Record<string,unknown>
+ *   evaluation_trace : { ruleId, matched, shortCircuited }[]
+ *   sensitivity?   : SensitivityResult      — only when sensitivityAnalysis is configured
+ * }
+ */
+import { type ResolveDotPathOpts } from './utils.js';
+export type LeafCondition = {
+    path: string;
+    eq: unknown;
+} | {
+    path: string;
+    in: unknown[];
+} | {
+    path: string;
+    gte: number;
+} | {
+    path: string;
+    gt: number;
+} | {
+    path: string;
+    lte: number;
+} | {
+    path: string;
+    lt: number;
+} | {
+    path: string;
+    exists: boolean;
+} | {
+    path: string;
+    contains: unknown;
+} | {
+    path: string;
+    regex: string;
+};
+export type Condition = LeafCondition | {
+    all: Condition[];
+} | {
+    any: Condition[];
+} | {
+    not: Condition;
+};
+export type Rule = {
+    id: string;
+    label?: string;
+    condition: Condition;
+    output: Record<string, unknown>;
+};
+export type SensitivityAnalysisConfig = {
+    /**
+     * Dot-path into executionMemory where the unknowns array lives.
+     * Each unknown must have: { id, tag, up_substitute, down_substitute }
+     * and a path where the substitute should be injected for the re-run.
+     */
+    unknownsPath: string;
+    /**
+     * The field in the rule output that holds the priority value for swing calculation.
+     * e.g. "priority"
+     */
+    priorityField: string;
+    /**
+     * Ordered array of priority values from highest to lowest.
+     * e.g. ["P1","P2","P3","P4","CLOSE"]
+     * Swing = |rank(up_result) - rank(down_result)|
+     */
+    priorityRank: string[];
+};
+export type SensitivityEntry = {
+    unknown_id: string;
+    up_substitute: unknown;
+    down_substitute: unknown;
+    up_priority: string | null;
+    down_priority: string | null;
+    swing: number;
+};
+export type SensitivityResult = {
+    any_high_swing: boolean;
+    entries: SensitivityEntry[];
+};
+export type DeterministicRuleOutput = {
+    matched: boolean;
+    rule_id: string | null;
+    rule_label: string | null;
+    output: Record<string, unknown>;
+    evaluation_trace: Array<{
+        ruleId: string;
+        matched: boolean;
+        shortCircuited?: boolean;
+    }>;
+    sensitivity?: SensitivityResult;
+};
+export type DeterministicRuleConfig = {
+    rules: Rule[];
+    firstMatchWins?: boolean;
+    defaultOutput?: Record<string, unknown>;
+    sensitivityAnalysis?: SensitivityAnalysisConfig;
+};
+export declare function runDeterministicRule(cfg: DeterministicRuleConfig, executionMemory: unknown, pathOpts?: ResolveDotPathOpts): DeterministicRuleOutput;