@exellix/graph-engine 6.0.0

package/dist/src/runtime/dataFiltersEvaluation.js

@@ -0,0 +1,169 @@
+import { EXELLIX_STRUCTURED_DATA_FILTERS_V1, } from '../types/refs.js';
+function getByDotPath(root, path) {
+    if (!path)
+        return undefined;
+    const parts = path.split('.').filter(Boolean);
+    let cur = root;
+    for (const p of parts) {
+        if (cur == null || typeof cur !== 'object' || Array.isArray(cur))
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+function collectLeafPaths(predicate) {
+    if (predicate == null)
+        return [];
+    if (typeof predicate !== 'object')
+        return [];
+    if ('path' in predicate && typeof predicate.path === 'string') {
+        return [predicate.path];
+    }
+    if ('all' in predicate) {
+        const items = predicate.all;
+        if (!Array.isArray(items))
+            return [];
+        return items.flatMap((p) => collectLeafPaths(p));
+    }
+    if ('any' in predicate) {
+        const items = predicate.any;
+        if (!Array.isArray(items))
+            return [];
+        return items.flatMap((p) => collectLeafPaths(p));
+    }
+    if ('not' in predicate) {
+        return collectLeafPaths(predicate.not);
+    }
+    return [];
+}
+/**
+ * Returns paths that are not valid roots for structured data-filter predicates
+ * (`data` or `data.*`). Empty when every leaf path is valid.
+ */
+export function getStructuredDataFilterPathViolations(predicate) {
+    const paths = collectLeafPaths(predicate);
+    const bad = [];
+    for (const p of paths) {
+        if (p === 'data' || p.startsWith('data.'))
+            continue;
+        bad.push(p);
+    }
+    return bad;
+}
+function resolveDataPath(record, fullPath) {
+    if (!fullPath)
+        return undefined;
+    const [rootKey, ...rest] = fullPath.split('.');
+    const tail = rest.join('.');
+    if (rootKey !== 'data')
+        return undefined;
+    return tail ? getByDotPath(record, tail) : record;
+}
+/**
+ * Evaluate a {@link GraphPredicate} tree where every leaf `path` is rooted at `data` or `data.*`,
+ * resolving values from `record` (the object that backs those paths).
+ *
+ * Semantics match {@link evaluateGraphPredicate} leaf operators (`exists`, `eq`) and boolean
+ * combinators (`all`, `any`, `not`), but paths are restricted to the `data` root only.
+ */
+export function evaluateDataFilterPredicate(predicate, record) {
+    if (predicate == null)
+        return true;
+    if (typeof predicate !== 'object')
+        return false;
+    if ('all' in predicate) {
+        const items = predicate.all;
+        if (!Array.isArray(items))
+            return false;
+        return items.every((p) => evaluateDataFilterPredicate(p, record));
+    }
+    if ('any' in predicate) {
+        const items = predicate.any;
+        if (!Array.isArray(items))
+            return false;
+        return items.some((p) => evaluateDataFilterPredicate(p, record));
+    }
+    if ('not' in predicate) {
+        return !evaluateDataFilterPredicate(predicate.not, record);
+    }
+    if ('path' in predicate && typeof predicate.path === 'string') {
+        const path = predicate.path;
+        const v = resolveDataPath(record, path);
+        if (predicate.exists !== undefined) {
+            if (typeof predicate.exists !== 'boolean')
+                return false;
+            const exists = v !== undefined && v !== null;
+            return predicate.exists ? exists : !exists;
+        }
+        if (predicate.eq !== undefined) {
+            return v === predicate.eq;
+        }
+        return false;
+    }
+    return false;
+}
+export function isStructuredDataFiltersV1(value) {
+    return (value != null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        value.version === EXELLIX_STRUCTURED_DATA_FILTERS_V1 &&
+        typeof value.when === 'object' &&
+        value.when != null &&
+        !Array.isArray(value.when));
+}
+/**
+ * Public entry: interpret `conditions.dataFilters` (or the same field on `metadata.graphEntry`)
+ * against a plain JSON-serializable **record** object.
+ *
+ * - **Structured v1** (`{ version: "exellix.dataFilters.v1", when }`): evaluated here; leaf paths
+ *   must be `data` or `data.*` and read from `record`.
+ * - **Legacy `string[]`**: not evaluated; returned as {@link EvaluateStructuredDataFiltersResult} with
+ *   `status: "legacy_reference_ids"` so callers can apply catalog logic themselves.
+ * - **`undefined`**: `status: "no_gate"`, `ok: true`.
+ *
+ * This function performs **no I/O**. It does **not** evaluate `conditions.narratives` or
+ * `conditions.aiFilter` — those remain host / tooling concerns unless documented otherwise.
+ */
+export function evaluateStructuredDataFilters(dataFilters, record, options) {
+    const strictPaths = options?.strictPaths !== false;
+    if (dataFilters === undefined) {
+        return {
+            status: 'no_gate',
+            ok: true,
+            message: 'conditions.dataFilters was undefined or omitted',
+        };
+    }
+    if (Array.isArray(dataFilters)) {
+        return {
+            status: 'legacy_reference_ids',
+            ok: true,
+            ids: dataFilters,
+            message: 'conditions.dataFilters is a string[] of reference ids; graph-engine does not resolve ids. Evaluate in your host or pass a structured `{ version, when }` gate.',
+        };
+    }
+    if (!isStructuredDataFiltersV1(dataFilters)) {
+        return {
+            status: 'unsupported_shape',
+            ok: false,
+            message: 'conditions.dataFilters must be string[] (legacy ids), undefined, or { version: "exellix.dataFilters.v1", when: GraphPredicate }.',
+        };
+    }
+    const invalidPaths = getStructuredDataFilterPathViolations(dataFilters.when);
+    if (invalidPaths.length > 0 && strictPaths) {
+        return {
+            status: 'evaluated',
+            ok: false,
+            version: EXELLIX_STRUCTURED_DATA_FILTERS_V1,
+            invalidPaths,
+            predicateRejected: false,
+        };
+    }
+    const pass = evaluateDataFilterPredicate(dataFilters.when, record);
+    return {
+        status: 'evaluated',
+        ok: pass,
+        version: EXELLIX_STRUCTURED_DATA_FILTERS_V1,
+        ...(invalidPaths.length ? { invalidPaths } : {}),
+        predicateRejected: !pass && invalidPaths.length === 0,
+    };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Deep-merge plain objects for graph-run memory (xynthesized patches).
+ * Arrays and non-plain objects are replaced by the patch value.
+ */
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, patch: Record<string, unknown>): T;

package/dist/src/runtime/deepMerge.js

@@ -0,0 +1,22 @@
+/**
+ * Deep-merge plain objects for graph-run memory (xynthesized patches).
+ * Arrays and non-plain objects are replaced by the patch value.
+ */
+export function deepMerge(target, patch) {
+    const out = { ...target };
+    for (const [k, pv] of Object.entries(patch)) {
+        if (pv === undefined)
+            continue;
+        const tv = out[k];
+        if (isPlainObject(tv) && isPlainObject(pv)) {
+            out[k] = deepMerge(tv, pv);
+        }
+        else {
+            out[k] = pv;
+        }
+    }
+    return out;
+}
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}

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

@@ -0,0 +1,92 @@
+import { GraphExecutionEvent, NodeExecutionEvent } from '../types/events.js';
+import { GraphNode } from '../types/refs.js';
+/**
+ * Event emitter interface for graph execution
+ */
+export interface EventEmitter {
+    emit(event: GraphExecutionEvent | NodeExecutionEvent): void;
+    on?(eventType: string, handler: (event: GraphExecutionEvent | NodeExecutionEvent) => void): void;
+}
+/**
+ * Forward each emitted event to every emitter in order. Undefined entries are skipped.
+ */
+export declare function composeEventEmitters(...emitters: Array<EventEmitter | undefined>): EventEmitter | undefined;
+/**
+ * Creates a graph start event
+ */
+export declare function createGraphStartEvent(jobId: string, graphId: string, taskId: string, data?: {
+    agentId?: string;
+    graphDefinition?: any;
+    input?: {
+        variables?: Record<string, any>;
+        jobMemory?: any;
+        taskMemory?: any;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}): GraphExecutionEvent;
+/**
+ * Creates a graph complete event
+ */
+export declare function createGraphCompleteEvent(jobId: string, graphId: string, taskId: string, data?: {
+    output?: any;
+    nodesExecuted?: number;
+    finalMemory?: {
+        jobMemory?: any;
+        taskMemory?: any;
+        [key: string]: any;
+    };
+    nodeResults?: any[];
+    [key: string]: any;
+}): GraphExecutionEvent;
+/**
+ * Creates a graph fail event
+ */
+export declare function createGraphFailEvent(jobId: string, graphId: string, taskId: string, error: any, data?: {
+    finalMemory?: {
+        jobMemory?: any;
+        taskMemory?: any;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}): GraphExecutionEvent;
+/**
+ * Creates a node start event
+ */
+export declare function createNodeStartEvent(jobId: string, graphId: string, taskId: string, node: GraphNode, skillKey: string, input?: {
+    variables?: Record<string, any>;
+    jobMemory?: any;
+    taskMemory?: any;
+    [key: string]: any;
+}, correlation?: {
+    jobType?: string;
+}): NodeExecutionEvent;
+/**
+ * Creates a node complete event
+ */
+export declare function createNodeCompleteEvent(jobId: string, graphId: string, taskId: string, node: GraphNode, skillKey: string, result: {
+    output?: any;
+    memoryAfter?: {
+        jobMemory?: any;
+        taskMemory?: any;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}, correlation?: {
+    jobType?: string;
+}): NodeExecutionEvent;
+/**
+ * Creates a node fail event
+ */
+export declare function createNodeFailEvent(jobId: string, graphId: string, taskId: string, node: GraphNode, skillKey: string, data: {
+    error: any;
+    memoryAfter?: {
+        jobMemory?: any;
+        taskMemory?: any;
+        execution?: any;
+        [key: string]: any;
+    };
+    response?: any;
+}, correlation?: {
+    jobType?: string;
+}): NodeExecutionEvent;

package/dist/src/runtime/events.js

@@ -0,0 +1,122 @@
+/**
+ * Forward each emitted event to every emitter in order. Undefined entries are skipped.
+ */
+export function composeEventEmitters(...emitters) {
+    const valid = emitters.filter((e) => e != null);
+    if (valid.length === 0)
+        return undefined;
+    if (valid.length === 1)
+        return valid[0];
+    return {
+        emit(event) {
+            for (const em of valid) {
+                em.emit(event);
+            }
+        },
+    };
+}
+/**
+ * Creates a graph start event
+ */
+export function createGraphStartEvent(jobId, graphId, taskId, data) {
+    return {
+        type: 'graph:start',
+        timestamp: Date.now(),
+        jobId,
+        taskId,
+        graphId,
+        data,
+    };
+}
+/**
+ * Creates a graph complete event
+ */
+export function createGraphCompleteEvent(jobId, graphId, taskId, data) {
+    return {
+        type: 'graph:complete',
+        timestamp: Date.now(),
+        jobId,
+        taskId,
+        graphId,
+        data,
+    };
+}
+/**
+ * Creates a graph fail event
+ */
+export function createGraphFailEvent(jobId, graphId, taskId, error, data) {
+    return {
+        type: 'graph:fail',
+        timestamp: Date.now(),
+        jobId,
+        taskId,
+        graphId,
+        data: {
+            error,
+            ...data,
+        },
+    };
+}
+/**
+ * Creates a node start event
+ */
+export function createNodeStartEvent(jobId, graphId, taskId, node, skillKey, input, correlation) {
+    return {
+        type: 'node:start',
+        timestamp: Date.now(),
+        jobId,
+        taskId,
+        graphId,
+        nodeId: node.id,
+        node,
+        skillKey,
+        data: {
+            input,
+            nodeDefinition: node,
+            ...(correlation?.jobType != null ? { jobType: correlation.jobType } : {}),
+        },
+    };
+}
+/**
+ * Creates a node complete event
+ */
+export function createNodeCompleteEvent(jobId, graphId, taskId, node, skillKey, result, correlation) {
+    return {
+        type: 'node:complete',
+        timestamp: Date.now(),
+        jobId,
+        taskId,
+        graphId,
+        nodeId: node.id,
+        node,
+        skillKey,
+        result: result.output,
+        data: {
+            output: result.output,
+            memoryAfter: result.memoryAfter,
+            ...(correlation?.jobType != null ? { jobType: correlation.jobType } : {}),
+        },
+    };
+}
+/**
+ * Creates a node fail event
+ */
+export function createNodeFailEvent(jobId, graphId, taskId, node, skillKey, data, correlation) {
+    return {
+        type: 'node:fail',
+        timestamp: Date.now(),
+        jobId,
+        taskId,
+        graphId,
+        nodeId: node.id,
+        node,
+        skillKey,
+        error: data.error,
+        data: {
+            error: data.error,
+            memoryAfter: data.memoryAfter,
+            ...(data.response !== undefined ? { response: data.response } : {}),
+            ...(correlation?.jobType != null ? { jobType: correlation.jobType } : {}),
+        },
+    };
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Host helpers for execution-matrix style orchestrators (e.g. `@exellix/exellix-runtime`).
+ *
+ * Graph-engine does not call matrix claim APIs; the host injects `executeGraph` and supplies
+ * a `{ model, runtime }` request with per-graph `GraphEntryContract` + seeded
+ * `runtime.executionMemory` objects built here.
+ */
+import type { Graph, GraphEntryContract, GraphEntryExecutionInputSpec, Job } from '../types/refs.js';
+import type { ExellixGraphRuntimeOptions, ExecuteGraphInput, ExecuteGraphResult, GraphRuntimeObject } from './ExellixGraphRuntime.js';
+import type { GraphLoader } from './ExellixGraphRuntime.js';
+/**
+ * Reads Layer 01 contract from the canonical graph document (`metadata.graphEntry`).
+ * Does not fetch Catalox or bundle stores — those are host concerns before load.
+ */
+export declare function resolveGraphEntryFromGraph(graph: Graph): GraphEntryContract | undefined;
+/**
+ * Returns an async resolver suitable for `graphId -> GraphEntryContract` when graphs
+ * are loaded through the same `GraphLoader` used for execution.
+ */
+export declare function createResolveGraphEntryFromLoader(loader: GraphLoader): (graphId: string) => Promise<GraphEntryContract | undefined>;
+export type BuildExecutionSeedSources = {
+    /**
+     * Highest precedence: explicit dot-path → value (paths match `GraphEntryValueInputSpec.path`).
+     */
+    valuesByPath?: Record<string, unknown>;
+    /**
+     * Lower precedence: plain objects (matrix defaults, row payload, per-graph map).
+     * For each spec path, `selectByPath(layer, path)` is evaluated; later layers override earlier ones.
+     */
+    layers?: unknown[];
+};
+export type BuildExecutionSeedResult = {
+    /** Shallow clone base + writes; safe to pass as `GraphRuntimeObject.executionMemory`. */
+    executionMemory: Record<string, unknown>;
+    /** Backwards-readable alias for callers still naming the seed object `execution`. */
+    execution: Record<string, unknown>;
+    /** Paths written for value-kind specs. */
+    appliedPaths: string[];
+    /** `kind: "execution"` specs are never auto-filled — host must materialize prior runs. */
+    skippedExecutionSpecs: GraphEntryExecutionInputSpec[];
+};
+/**
+ * Builds an initial `execution` object from `metadata.graphEntry.inputs` for **value** kinds only.
+ * `kind: "execution"` entries are skipped (see return value); the host must merge source executions
+ * using `graphId` / `metadataFilter` before calling `executeGraph`.
+ */
+export declare function buildExecutionSeedFromGraphEntry(graphEntry: GraphEntryContract | undefined, sources?: BuildExecutionSeedSources): BuildExecutionSeedResult;
+/** Builds the canonical graph-engine execution request for matrix-style hosts. */
+export declare function buildGraphExecutionRequest(input: {
+    model: Graph;
+    runtime: GraphRuntimeObject;
+}): ExecuteGraphInput;
+/**
+ * Validates that dot-paths declared in `requiredExecutionPaths` are present on `execution`
+ * (after seeding). Graph-engine does not enforce `graphEntry` at runtime; hosts may call this before execute.
+ */
+export declare function validateExecutionSeedPaths(execution: Record<string, unknown>, graphEntry: GraphEntryContract | undefined): {
+    ok: boolean;
+    missingPaths: string[];
+};
+/**
+ * Deterministic job id for matrix rows so retries can reuse the same id for idempotent downstream dedupe.
+ * Use the same `attempt` for automatic retries of the same logical run; bump `attempt` only when
+ * intentionally starting a new run (new side effects).
+ */
+export declare function buildStableMatrixJobId(input: {
+    matrixId: string;
+    rowId: string;
+    graphId: string;
+    /** Default 0 — keep constant for same-run retries. */
+    attempt?: number;
+}): string;
+/**
+ * Builds a `Job` compatible with both classic `executeGraph` (`job.id`) and
+ * `createExellixGraphRuntime().executeGraph` (`job.jobId` is also set).
+ */
+export declare function buildMatrixJobForGraphRun(input: {
+    matrixId: string;
+    rowId: string;
+    graphId: string;
+    attempt?: number;
+    agentId?: string;
+    jobType?: string;
+    jobVariables?: Record<string, unknown>;
+    /** Forwarded as `job.input` for runTask `jobInput` merge in injected runtime. */
+    jobInput?: unknown;
+}): Job & {
+    jobId: string;
+};
+/** True when injected-runtime result is terminal failure (host decides retry / reset). */
+export declare function isExecuteGraphResultFailed(result: ExecuteGraphResult): boolean;
+/**
+ * Creates a long-lived graph runtime and exposes `executeGraph` for injection into matrix claim
+ * processors (`ProcessMatrixClaimDeps.executeGraph` in `@exellix/exellix-runtime`, etc.).
+ */
+export declare function createMatrixHostGraphExecutor(options: ExellixGraphRuntimeOptions): {
+    executeGraph: (input: ExecuteGraphInput) => Promise<ExecuteGraphResult>;
+};

package/dist/src/runtime/executionMatrixHost.js

@@ -0,0 +1,134 @@
+/**
+ * Host helpers for execution-matrix style orchestrators (e.g. `@exellix/exellix-runtime`).
+ *
+ * Graph-engine does not call matrix claim APIs; the host injects `executeGraph` and supplies
+ * a `{ model, runtime }` request with per-graph `GraphEntryContract` + seeded
+ * `runtime.executionMemory` objects built here.
+ */
+import { mergeGraphDocumentModel } from '../types/refs.js';
+import { createExellixGraphRuntime } from './ExellixGraphRuntime.js';
+import { selectByPath, writeByPath } from './pathExpr.js';
+function isExecutionInputSpec(spec) {
+    return spec.kind === 'execution';
+}
+function isValueInputSpec(spec) {
+    return spec.kind !== 'execution' && typeof spec.path === 'string';
+}
+/**
+ * Reads Layer 01 contract from the canonical graph document (`metadata.graphEntry`).
+ * Does not fetch Catalox or bundle stores — those are host concerns before load.
+ */
+export function resolveGraphEntryFromGraph(graph) {
+    const meta = mergeGraphDocumentModel(graph);
+    return meta.graphEntry;
+}
+/**
+ * Returns an async resolver suitable for `graphId -> GraphEntryContract` when graphs
+ * are loaded through the same `GraphLoader` used for execution.
+ */
+export function createResolveGraphEntryFromLoader(loader) {
+    return async function resolveGraphEntry(graphId) {
+        const graph = await loader.loadGraph(graphId);
+        return resolveGraphEntryFromGraph(graph);
+    };
+}
+/**
+ * Builds an initial `execution` object from `metadata.graphEntry.inputs` for **value** kinds only.
+ * `kind: "execution"` entries are skipped (see return value); the host must merge source executions
+ * using `graphId` / `metadataFilter` before calling `executeGraph`.
+ */
+export function buildExecutionSeedFromGraphEntry(graphEntry, sources = {}) {
+    const execution = {};
+    const appliedPaths = [];
+    const skippedExecutionSpecs = [];
+    const valuesByPath = sources.valuesByPath ?? {};
+    const layers = sources.layers ?? [];
+    for (const spec of graphEntry?.inputs ?? []) {
+        if (isExecutionInputSpec(spec)) {
+            skippedExecutionSpecs.push(spec);
+            continue;
+        }
+        if (!isValueInputSpec(spec))
+            continue;
+        const path = spec.path.trim();
+        if (!path)
+            continue;
+        let value = undefined;
+        if (Object.prototype.hasOwnProperty.call(valuesByPath, path)) {
+            value = valuesByPath[path];
+        }
+        else {
+            for (const layer of layers) {
+                if (layer == null || typeof layer !== 'object' || Array.isArray(layer))
+                    continue;
+                const picked = selectByPath(layer, path);
+                if (picked !== undefined)
+                    value = picked;
+            }
+        }
+        if (value !== undefined) {
+            writeByPath(execution, path, value, 'replace');
+            appliedPaths.push(path);
+        }
+    }
+    return { executionMemory: execution, execution, appliedPaths, skippedExecutionSpecs };
+}
+/** Builds the canonical graph-engine execution request for matrix-style hosts. */
+export function buildGraphExecutionRequest(input) {
+    return {
+        model: input.model,
+        runtime: input.runtime,
+    };
+}
+/**
+ * Validates that dot-paths declared in `requiredExecutionPaths` are present on `execution`
+ * (after seeding). Graph-engine does not enforce `graphEntry` at runtime; hosts may call this before execute.
+ */
+export function validateExecutionSeedPaths(execution, graphEntry) {
+    const missingPaths = [];
+    for (const p of graphEntry?.requiredExecutionPaths ?? []) {
+        if (typeof p !== 'string' || !p.trim())
+            continue;
+        const v = selectByPath(execution, p.trim());
+        if (v === undefined)
+            missingPaths.push(p.trim());
+    }
+    return { ok: missingPaths.length === 0, missingPaths };
+}
+/**
+ * Deterministic job id for matrix rows so retries can reuse the same id for idempotent downstream dedupe.
+ * Use the same `attempt` for automatic retries of the same logical run; bump `attempt` only when
+ * intentionally starting a new run (new side effects).
+ */
+export function buildStableMatrixJobId(input) {
+    const attempt = input.attempt ?? 0;
+    return `matrix:${input.matrixId}:row:${input.rowId}:graph:${input.graphId}:attempt:${attempt}`;
+}
+/**
+ * Builds a `Job` compatible with both classic `executeGraph` (`job.id`) and
+ * `createExellixGraphRuntime().executeGraph` (`job.jobId` is also set).
+ */
+export function buildMatrixJobForGraphRun(input) {
+    const jobId = buildStableMatrixJobId(input);
+    const job = {
+        id: jobId,
+        jobId,
+        ...(input.agentId != null ? { agentId: input.agentId } : {}),
+        ...(input.jobType != null ? { jobType: input.jobType } : {}),
+        ...(input.jobVariables != null ? { jobVariables: input.jobVariables } : {}),
+        ...(input.jobInput !== undefined ? { input: input.jobInput } : {}),
+    };
+    return job;
+}
+/** True when injected-runtime result is terminal failure (host decides retry / reset). */
+export function isExecuteGraphResultFailed(result) {
+    return result.status === 'failed';
+}
+/**
+ * Creates a long-lived graph runtime and exposes `executeGraph` for injection into matrix claim
+ * processors (`ProcessMatrixClaimDeps.executeGraph` in `@exellix/exellix-runtime`, etc.).
+ */
+export function createMatrixHostGraphExecutor(options) {
+    const { executeGraph } = createExellixGraphRuntime(options);
+    return { executeGraph };
+}