@exellix/graph-engine 6.0.0

package/dist/src/runtime/localSkills/scopedAnswerWriter.js

@@ -0,0 +1,156 @@
+/**
+ * scoped-answer-writer — local skill.
+ *
+ * Persists execution-memory payloads into Memorix **entity** collections, one
+ * **content type** per write (`inferences`, `decisions`, …) via `writeMemorixRecord`.
+ *
+ * Node config:
+ *   entityIdPath — required
+ *   payloadPath  — dot-path to `{ inferences?, decisions? }` or flat decisions map
+ *   memorixWriteDescriptors — optional map of contentType → Catalox write descriptor id
+ *     (default: descriptor id equals content type name)
+ */
+import { writeMemorixRecord } from '@x12i/memorix-writer';
+import { getMemorixWriterClient } from './memorixRuntime.js';
+import { DEFAULT_SCOPED_CONTENT_TYPES, resolveMemorixWriteDescriptorId, } from './memorixScopedConfig.js';
+import { resolveDotPath } from './utils.js';
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function bucketPlainValues(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value === undefined)
+            continue;
+        if (isPlainObject(value) && 'value' in value) {
+            out[key] = value.value;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function extractContentTypeBuckets(payload, contentTypes) {
+    const buckets = {};
+    const writtenKeys = [];
+    const hasNamedBuckets = contentTypes.some((ct) => isPlainObject(payload[ct]));
+    if (hasNamedBuckets) {
+        for (const ct of contentTypes) {
+            const raw = payload[ct];
+            if (!isPlainObject(raw))
+                continue;
+            const plain = bucketPlainValues(raw);
+            if (Object.keys(plain).length === 0)
+                continue;
+            buckets[ct] = plain;
+            writtenKeys.push(...Object.keys(plain).map((k) => `${ct}.${k}`));
+        }
+        return { buckets, writtenKeys };
+    }
+    const plain = bucketPlainValues(payload);
+    if (Object.keys(plain).length > 0) {
+        buckets.decisions = plain;
+        writtenKeys.push(...Object.keys(plain).map((k) => `decisions.${k}`));
+    }
+    return { buckets, writtenKeys };
+}
+const SKILL = 'scoped-answer-writer';
+export async function runScopedAnswerWriter(cfg, executionMemory, pathOpts) {
+    const { entityIdPath } = cfg;
+    const payloadPath = cfg.payloadPath;
+    const contentTypes = cfg.memorixContentTypes?.length
+        ? cfg.memorixContentTypes
+        : [...DEFAULT_SCOPED_CONTENT_TYPES];
+    if (!entityIdPath || !payloadPath) {
+        return {
+            write_status: 'error',
+            entity_id: '',
+            content_types_written: [],
+            written_keys: [],
+            error: `${SKILL}: taskConfiguration.entityIdPath and payloadPath are required`,
+        };
+    }
+    const entityId = resolveDotPath(executionMemory, entityIdPath, pathOpts);
+    if (entityId == null || typeof entityId !== 'string' || entityId === '') {
+        return {
+            write_status: 'error',
+            entity_id: String(entityId ?? ''),
+            content_types_written: [],
+            written_keys: [],
+            error: `${SKILL}: entityIdPath "${entityIdPath}" resolved to empty/non-string value`,
+        };
+    }
+    const rawPayload = resolveDotPath(executionMemory, payloadPath, pathOpts);
+    if (rawPayload == null || typeof rawPayload !== 'object' || Array.isArray(rawPayload)) {
+        return {
+            write_status: 'error',
+            entity_id: entityId,
+            content_types_written: [],
+            written_keys: [],
+            error: `${SKILL}: payloadPath "${payloadPath}" did not resolve to a plain object`,
+        };
+    }
+    const { buckets, writtenKeys } = extractContentTypeBuckets(rawPayload, contentTypes);
+    if (writtenKeys.length === 0) {
+        return {
+            write_status: 'error',
+            entity_id: entityId,
+            content_types_written: [],
+            written_keys: [],
+            error: `${SKILL}: payload at "${payloadPath}" produced no fields to write`,
+        };
+    }
+    const entityType = (cfg.entityTypePath ? String(resolveDotPath(executionMemory, cfg.entityTypePath, pathOpts) ?? '') : '') ||
+        cfg.staticEntityType ||
+        undefined;
+    const now = new Date().toISOString();
+    const contentTypesWritten = [];
+    try {
+        const client = await getMemorixWriterClient();
+        for (const [contentType, bucket] of Object.entries(buckets)) {
+            const writeDescriptorId = resolveMemorixWriteDescriptorId(cfg, contentType);
+            const result = await writeMemorixRecord(client, {
+                writeDescriptorId,
+                entityId,
+                operation: 'upsert',
+                input: {
+                    ...bucket,
+                    entityType,
+                    question: cfg.questionTitle,
+                    updatedAt: now,
+                    modifiedAt: now,
+                },
+            });
+            if (!result.ok) {
+                const msg = result.issues
+                    ?.filter((i) => i.severity === 'error')
+                    .map((i) => i.message)
+                    .join('; ') || `Memorix write failed for content type "${contentType}"`;
+                return {
+                    write_status: 'error',
+                    entity_id: entityId,
+                    content_types_written: contentTypesWritten,
+                    written_keys: [],
+                    error: `${SKILL}: ${msg}`,
+                };
+            }
+            contentTypesWritten.push(contentType);
+        }
+        return {
+            write_status: 'ok',
+            entity_id: entityId,
+            content_types_written: contentTypesWritten,
+            written_keys: writtenKeys,
+        };
+    }
+    catch (err) {
+        return {
+            write_status: 'error',
+            entity_id: entityId,
+            content_types_written: contentTypesWritten,
+            written_keys: [],
+            error: `${SKILL}: ${err?.message ?? String(err)}`,
+        };
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * scoped-data-reader — local deterministic skill.
+ *
+ * Reads entity state via Memorix `fetchMemorixItem`. Item descriptors define which
+ * content types and properties appear in sections; this skill flattens them to `fields.*`.
+ *
+ * Node config:
+ *   memorixItemDescriptorId | itemDescriptorId — required
+ *   entityIdPath — dot-path to resolve Memorix entity id
+ *   pack — parallel reads: `{ slot, memorixItemDescriptorId, entityIdPath }[]`
+ */
+import { type MemorixScopedSkillConfig } from './memorixScopedConfig.js';
+import { type ResolveDotPathOpts } from './utils.js';
+export { scopedAnswerDocToFlatFields } from './scopedAnswerFields.js';
+export type ScopedDataReaderPackSlot = {
+    slot: string;
+    entityIdPath: string;
+    memorixItemDescriptorId?: string;
+    itemDescriptorId?: string;
+};
+export type ScopedDataReaderConfig = MemorixScopedSkillConfig & {
+    entityIdPath: string;
+    pack?: ScopedDataReaderPackSlot[];
+};
+export type ScopedDataReaderOutput = {
+    answer_status: 'answered' | 'not_found' | 'empty' | 'error';
+    fields: Record<string, {
+        value: unknown;
+        fieldPath: string;
+        description?: string;
+        reasoning?: string;
+        linked?: boolean;
+    }>;
+    freshness: {
+        scopedAt: string;
+    } | null;
+    unknowns: string[];
+    entity_id: string;
+    error?: string;
+};
+export type ScopedDataReaderPackOutput = {
+    pack_status: 'ok' | 'error';
+    slots: Record<string, ScopedDataReaderOutput>;
+    error?: string;
+};
+export declare function runScopedDataReaderPack(pack: ScopedDataReaderPackSlot[], executionMemory: unknown, pathOpts?: ResolveDotPathOpts): Promise<ScopedDataReaderPackOutput>;
+export declare function runScopedDataReader(cfg: ScopedDataReaderConfig, executionMemory: unknown, pathOpts?: ResolveDotPathOpts): Promise<ScopedDataReaderOutput | ScopedDataReaderPackOutput>;

package/dist/src/runtime/localSkills/scopedDataReader.js

@@ -0,0 +1,89 @@
+/**
+ * scoped-data-reader — local deterministic skill.
+ *
+ * Reads entity state via Memorix `fetchMemorixItem`. Item descriptors define which
+ * content types and properties appear in sections; this skill flattens them to `fields.*`.
+ *
+ * Node config:
+ *   memorixItemDescriptorId | itemDescriptorId — required
+ *   entityIdPath — dot-path to resolve Memorix entity id
+ *   pack — parallel reads: `{ slot, memorixItemDescriptorId, entityIdPath }[]`
+ */
+import { fetchMemorixItem } from '@x12i/memorix-retrieval';
+import { memorixItemToScopedOutput } from './memorixItemToScopedOutput.js';
+import { getMemorixRetrievalClient } from './memorixRuntime.js';
+import { resolveMemorixItemDescriptorId } from './memorixScopedConfig.js';
+import { resolveDotPath } from './utils.js';
+export { scopedAnswerDocToFlatFields } from './scopedAnswerFields.js';
+async function runScopedDataReaderCore(cfg, executionMemory, pathOpts) {
+    const { entityIdPath } = cfg;
+    const itemDescriptorId = resolveMemorixItemDescriptorId(cfg);
+    const entityId = resolveDotPath(executionMemory, entityIdPath, pathOpts);
+    if (entityId == null || typeof entityId !== 'string' || entityId === '') {
+        return {
+            answer_status: 'error',
+            fields: {},
+            freshness: null,
+            unknowns: [],
+            entity_id: String(entityId ?? ''),
+            error: `scoped-data-reader: entityIdPath "${entityIdPath}" resolved to empty/non-string value`,
+        };
+    }
+    if (!itemDescriptorId) {
+        return {
+            answer_status: 'error',
+            fields: {},
+            freshness: null,
+            unknowns: [],
+            entity_id: entityId,
+            error: 'scoped-data-reader: memorixItemDescriptorId or itemDescriptorId is required',
+        };
+    }
+    try {
+        const client = await getMemorixRetrievalClient();
+        const item = await fetchMemorixItem(client, {
+            itemDescriptorId,
+            entityId,
+        });
+        return memorixItemToScopedOutput(item, entityId);
+    }
+    catch (err) {
+        return {
+            answer_status: 'error',
+            fields: {},
+            freshness: null,
+            unknowns: [],
+            entity_id: entityId,
+            error: `scoped-data-reader: ${err?.message ?? String(err)}`,
+        };
+    }
+}
+export async function runScopedDataReaderPack(pack, executionMemory, pathOpts) {
+    try {
+        const entries = await Promise.all(pack.map(async (p) => {
+            const out = await runScopedDataReaderCore({
+                entityIdPath: p.entityIdPath,
+                memorixItemDescriptorId: p.memorixItemDescriptorId,
+                itemDescriptorId: p.itemDescriptorId,
+            }, executionMemory, pathOpts);
+            return [p.slot, out];
+        }));
+        return {
+            pack_status: 'ok',
+            slots: Object.fromEntries(entries),
+        };
+    }
+    catch (err) {
+        return {
+            pack_status: 'error',
+            slots: {},
+            error: err?.message ?? String(err),
+        };
+    }
+}
+export async function runScopedDataReader(cfg, executionMemory, pathOpts) {
+    if (Array.isArray(cfg.pack) && cfg.pack.length > 0) {
+        return runScopedDataReaderPack(cfg.pack, executionMemory, pathOpts);
+    }
+    return runScopedDataReaderCore(cfg, executionMemory, pathOpts);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Shared utilities for local skills — no external dependencies.
+ */
+export type ResolveDotPathOpts = {
+    /** Resolves `xynthesized.task.*` against `execution.xynthesized.taskByNode[nodeId]`. */
+    graphTaskNodeId?: string;
+};
+/**
+ * Resolve a dot-path into an object. Returns undefined when any segment is missing.
+ * Supports `xynthesized.job.*`, `xynthesized.task.*` (node-scoped), and `xynthesized.execution.*`.
+ */
+export declare function resolveDotPath(obj: unknown, path: string, opts?: ResolveDotPathOpts): unknown;

package/dist/src/runtime/localSkills/utils.js

@@ -0,0 +1,39 @@
+/**
+ * Shared utilities for local skills — no external dependencies.
+ */
+/**
+ * Resolve a dot-path into an object. Returns undefined when any segment is missing.
+ * Supports `xynthesized.job.*`, `xynthesized.task.*` (node-scoped), and `xynthesized.execution.*`.
+ */
+export function resolveDotPath(obj, path, opts) {
+    const p = typeof path === 'string' ? path.trim() : '';
+    if (!p)
+        return obj;
+    if (p.startsWith('xynthesized.execution.')) {
+        const tail = p.slice('xynthesized.execution.'.length);
+        const ex = obj;
+        const xy = ex?.xynthesized;
+        return resolveDotPath(xy?.execution, tail, opts);
+    }
+    if (p.startsWith('xynthesized.job.')) {
+        const tail = p.slice('xynthesized.job.'.length);
+        const ex = obj;
+        const xy = ex?.xynthesized;
+        return resolveDotPath(xy?.job, tail, opts);
+    }
+    if (opts?.graphTaskNodeId && p.startsWith('xynthesized.task.')) {
+        const tail = p.slice('xynthesized.task.'.length);
+        const ex = obj;
+        const xy = ex?.xynthesized;
+        const bucket = xy?.taskByNode?.[opts.graphTaskNodeId];
+        return resolveDotPath(bucket, tail, opts);
+    }
+    const parts = p.split('.');
+    let cur = obj;
+    for (const seg of parts) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Ensures `executionMemory.input.raw` holds the active MAIN payload for PRE synthesis paths
+ * (e.g. `inputsConfig` bindings with `path: "input.raw"`).
+ */
+export declare function mirrorRuntimeInputRawOnExecutionMemory(executionMemory: Record<string, unknown>): void;
+/**
+ * Mirrors MAIN task input onto `executionMemory.input` for the current graph run.
+ */
+export declare function mirrorStructuredInputOntoExecutionMemory(executionMemory: Record<string, unknown>, structuredInput: Record<string, unknown>): void;

package/dist/src/runtime/materializeStructuredRunTaskInput.js

@@ -0,0 +1,34 @@
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Ensures `executionMemory.input.raw` holds the active MAIN payload for PRE synthesis paths
+ * (e.g. `inputsConfig` bindings with `path: "input.raw"`).
+ */
+export function mirrorRuntimeInputRawOnExecutionMemory(executionMemory) {
+    const main = executionMemory.input;
+    if (main === undefined)
+        return;
+    const raw = isPlainObject(main)
+        ? (() => {
+            const copy = { ...main };
+            delete copy.raw;
+            return copy;
+        })()
+        : main;
+    const prev = isPlainObject(executionMemory.input) ? executionMemory.input : {};
+    executionMemory.input = { ...prev, raw };
+}
+/**
+ * Mirrors MAIN task input onto `executionMemory.input` for the current graph run.
+ */
+export function mirrorStructuredInputOntoExecutionMemory(executionMemory, structuredInput) {
+    const prev = structuredInput != null && typeof structuredInput === 'object' && !Array.isArray(structuredInput)
+        ? (executionMemory.input != null &&
+            typeof executionMemory.input === 'object' &&
+            !Array.isArray(executionMemory.input)
+            ? executionMemory.input
+            : {})
+        : {};
+    executionMemory.input = { ...prev, ...structuredInput };
+}

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

@@ -0,0 +1,51 @@
+import { GraphNode } from '../types/refs.js';
+import { NodeExecutionResult } from '../types/results.js';
+/**
+ * Creates a mapped object from a map configuration.
+ * Uses pathExpr (selectByPath) for paths containing [*], {*}, or starting with executionMemory./jobMemory.;
+ * otherwise uses Graphenix resolveMappingPath for node.X, output.X, variables.X.
+ */
+export declare function createMappedObject(map: Record<string, string>, context: {
+    node?: GraphNode;
+    output?: any;
+    jobMemory?: any;
+    executionMemory?: any;
+    variables?: Record<string, any>;
+}): any;
+/**
+ * Merges memory from job and node sources.
+ */
+export declare function mergeMemory(options: {
+    jobMemory?: any;
+    taskMemory?: any;
+    node?: GraphNode;
+}): {
+    jobMemory?: any;
+    taskMemory?: any;
+};
+/**
+ * Merges output into execution object based on mapping configuration.
+ * Uses writeByPath for target path (supports nested paths, creates missing objects).
+ * Resolves map sources via selectByPath on { output, node, variables } with fallback to Graphenix.
+ */
+export declare function mergeExecutionObject(execution: any, path: string, output: any, mode?: 'replace' | 'append' | 'merge', mappingConfig?: {
+    map?: Record<string, string>;
+    fields?: string[];
+}, context?: {
+    node?: GraphNode;
+    variables?: Record<string, any>;
+}): any;
+/**
+ * Merges execution object into jobMemory so it appears in workingMemory.
+ */
+export declare function mergeExecutionIntoMemory(jobMemory: any, execution: any): any;
+/**
+ * Builds a semantic memory key for a node result.
+ */
+export declare function buildMemoryKey(node: GraphNode): string;
+/**
+ * Accumulates a node execution result into jobMemory.
+ */
+export declare function accumulateNodeResult(currentMemory: any, node: GraphNode, result: NodeExecutionResult): any;
+/** Copy selected execution fields when target omits them (e.g. webContext from response.executionMemory). */
+export declare function copyExecutionContextFields(targetExecution: unknown, sourceExecution: unknown, fields: string[]): void;