@exellix/graph-engine 7.2.10 → 7.2.13

package/dist/src/runtime/buildRunLog.js

@@ -1,3 +1,4 @@
+import { normalizeLogRecord } from '@x12i/logxer';
 import { AI_TASKS_LOGXER_RUN_ID_METADATA_KEY, AI_TASKS_RUN_LOG_METADATA_KEY, DEFAULT_MAX_RUN_LOG_DATA_JSON_CHARS, DEFAULT_MAX_RUN_LOG_ENTRIES, } from '../types/runLog.js';
 function safeJsonLen(value) {
     try {
@@ -68,6 +69,13 @@ export function normalizeExternalRunLogEntries(raw) {
             ? r.correlationIds
             : undefined;
         const data = 'data' in r ? r.data : undefined;
+        const normalized = normalizeLogRecord(r);
+        const code = typeof normalized.code === 'string' && normalized.code.length > 0 ? normalized.code : undefined;
+        const diagnostics = normalized.diagnostics;
+        const debugKind = typeof r.debugKind === 'string' && r.debugKind.length > 0
+            ? r.debugKind
+            : undefined;
+        const evidence = Array.isArray(r.evidence) ? r.evidence : undefined;
         out.push({
             ts,
             level,
@@ -78,6 +86,10 @@ export function normalizeExternalRunLogEntries(raw) {
             ...(correlationIds ? { correlationIds } : {}),
             message,
             ...(data !== undefined ? { data } : {}),
+            ...(code ? { code } : {}),
+            ...(diagnostics ? { diagnostics } : {}),
+            ...(debugKind ? { debugKind } : {}),
+            ...(evidence?.length ? { evidence } : {}),
         });
     }
     return out;

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

@@ -0,0 +1,42 @@
+/**
+ * Graph-engine Logxer integration (@x12i/logxer 4.5.x).
+ * Structured runtime logs, correlation context, stack log-level pass-through, and queryable in-process logs.
+ */
+import { DebugLogAbstract, exceptionEvidence, fieldEvidence, runWithLogContext, patchLogContext } from '@x12i/logxer';
+import type { GetJobLogsInput, GetJobLogsResult, Logxer, LogRuntimeContext, StackLoggingOptions } from '@x12i/logxer';
+import type { LogxerQueryableClient, RuntimeObjects } from './runtimeObjects.js';
+/** Env prefix for package-level log level: `GRAPH_ENGINE_LOGS_LEVEL` (canonical). */
+export declare const GRAPH_ENGINE_LOGXER_ENV_PREFIX: "GRAPH_ENGINE";
+/**
+ * Factory for a graph-engine Logxer instance.
+ * Pass `logging` from host {@link StackLoggingOptions} (logxer 4.5+ stack pass-through).
+ */
+export declare function createGraphEngineLogxer(options?: {
+    logging?: StackLoggingOptions;
+}): Logxer;
+/** Default process logger (env / host registry). Lazily created without stack overrides. */
+export declare function getGraphEngineLogxer(): Logxer;
+/** Bind the logger used for the current graph run (cleared in {@link clearGraphEngineRunLogxer}). */
+export declare function bindGraphEngineRunLogxer(logxer: Logxer): void;
+export declare function clearGraphEngineRunLogxer(): void;
+/** Queryable client surface for {@link RuntimeObjects.logxerClient}. */
+export declare function createGraphEngineLogxerClient(logxer?: Logxer): LogxerQueryableClient;
+/** Attach graph-level Logxer query client when hosts omit one on runtimeObjects. */
+export declare function ensureGraphEngineLogxerOnRuntimeObjects(runtimeObjects: RuntimeObjects | undefined, logxer?: Logxer): void;
+/** Run graph work with Logxer correlation ids (jobId, taskId, graphId, runId). */
+export declare function runGraphWithLogContext<T>(ctx: LogRuntimeContext, fn: () => T | Promise<T>): Promise<T>;
+/** Narrow node-scoped correlation inside an active graph run context. */
+export declare function patchGraphNodeLogContext(nodeId: string): void;
+/** Gated verbose/state traces (replaces DEBUG_EXECUTION_MEMORY / DEBUG_OUTPUT_MAPPING console.log). */
+export declare function traceExecutionMemory(scope: 'executeNode' | 'executeGraph', message: string, data?: Record<string, unknown>): void;
+/** Emit a catalog-backed graph error log when a node/graph failure occurs. */
+export declare function logGraphEngineErrorCode(code: string, _message: string, ctx: {
+    graphId?: string;
+    nodeId?: string;
+    jobId?: string;
+    taskId?: string;
+    error?: unknown;
+    evidence?: Record<string, unknown>;
+}): void;
+export { DebugLogAbstract, fieldEvidence, exceptionEvidence, runWithLogContext, patchLogContext };
+export type { GetJobLogsInput, GetJobLogsResult, LogRuntimeContext, StackLoggingOptions };

package/dist/src/runtime/graphEngineLogxer.js

@@ -0,0 +1,165 @@
+/**
+ * Graph-engine Logxer integration (@x12i/logxer 4.5.x).
+ * Structured runtime logs, correlation context, stack log-level pass-through, and queryable in-process logs.
+ */
+import { createLogxer, DebugLogAbstract, exceptionEvidence, fieldEvidence, runWithLogContext, patchLogContext, } from '@x12i/logxer';
+import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
+import { EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME } from './runtimeObjects.js';
+/** Env prefix for package-level log level: `GRAPH_ENGINE_LOGS_LEVEL` (canonical). */
+export const GRAPH_ENGINE_LOGXER_ENV_PREFIX = 'GRAPH_ENGINE';
+const GRAPH_ENGINE_DIAGNOSTIC_CATALOG = {
+    [ExellixGraphErrorCode.GRAPH_ENTRY_DATA_FILTERS_REJECTED]: {
+        defaultLevel: 'error',
+        title: 'Graph entry data filters rejected',
+        impact: 'The graph run cannot start because structured entry filters did not accept runtime input.',
+        possibleCauses: [
+            'metadata.graphEntry.dataFilters shape is unsupported or evaluated false.',
+            'runtime.executionMemory.input is missing expected fields for the filter contract.',
+        ],
+        remediation: [
+            'Inspect metadata.graphEntry.dataFilters against exellix.dataFilters.v1.',
+            'Verify runtime.executionMemory.input before executeGraph.',
+        ],
+        retryable: false,
+        userActionRequired: true,
+        confidence: 'high',
+    },
+    [ExellixGraphErrorCode.MAIN_READINESS_FAILED]: {
+        defaultLevel: 'error',
+        title: 'MAIN task readiness failed',
+        impact: 'The node MAIN runTask call was blocked before ai-tasks could execute.',
+        possibleCauses: [
+            'Execution input or synthesized context did not satisfy MAIN readiness policy.',
+            'Required smartInput paths or memory buckets are empty.',
+        ],
+        remediation: [
+            'Inspect taskNodeMainReadiness evaluation for the node.',
+            'Verify executionMemory input and xynthesized seeding.',
+        ],
+        retryable: false,
+        userActionRequired: true,
+        confidence: 'high',
+    },
+    [ExellixGraphErrorCode.NODE_EXECUTION_FAILED]: {
+        defaultLevel: 'error',
+        title: 'Graph node execution failed',
+        impact: 'The node did not complete successfully; downstream nodes may be skipped.',
+        possibleCauses: [
+            'runTask returned an error or threw.',
+            'Local skill execution failed.',
+            'Engine PRE/POST strategy utility failed.',
+        ],
+        remediation: [
+            'Inspect node runLog lines and aiTasksObservability.',
+            'Check runTask response error and metadata.runLog.',
+        ],
+        retryable: true,
+        userActionRequired: false,
+        confidence: 'medium',
+    },
+    [ExellixGraphErrorCode.GRAPH_EXECUTION_FAILED]: {
+        defaultLevel: 'error',
+        title: 'Graph execution failed',
+        impact: 'The graph run ended in a failed state.',
+        possibleCauses: [
+            'One or more nodes failed under failFast or finalizer failure.',
+            'Graph entry gate or finalizer validation failed.',
+        ],
+        remediation: [
+            'Inspect ExecuteGraphResult.errors and runLog.',
+            'Use runtimeObjects.logxerClient.getJobLogs for in-process diagnostics.',
+        ],
+        retryable: true,
+        userActionRequired: false,
+        confidence: 'medium',
+    },
+};
+let defaultLogxer;
+/** Active logger for the current `executeGraph` run (falls back to {@link defaultLogxer}). */
+let activeRunLogxer;
+function buildGraphEngineLogxerConfig(logging) {
+    return {
+        runtimeIdentity: { service: 'graph-engine' },
+        diagnostics: {
+            catalog: GRAPH_ENGINE_DIAGNOSTIC_CATALOG,
+        },
+        ...(logging ? { stack: logging } : {}),
+    };
+}
+/**
+ * Factory for a graph-engine Logxer instance.
+ * Pass `logging` from host {@link StackLoggingOptions} (logxer 4.5+ stack pass-through).
+ */
+export function createGraphEngineLogxer(options) {
+    return createLogxer({
+        packageName: EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME,
+        envPrefix: GRAPH_ENGINE_LOGXER_ENV_PREFIX,
+        debugNamespace: 'graph-engine',
+    }, buildGraphEngineLogxerConfig(options?.logging));
+}
+/** Default process logger (env / host registry). Lazily created without stack overrides. */
+export function getGraphEngineLogxer() {
+    if (!defaultLogxer) {
+        defaultLogxer = createGraphEngineLogxer();
+    }
+    return activeRunLogxer ?? defaultLogxer;
+}
+/** Bind the logger used for the current graph run (cleared in {@link clearGraphEngineRunLogxer}). */
+export function bindGraphEngineRunLogxer(logxer) {
+    activeRunLogxer = logxer;
+}
+export function clearGraphEngineRunLogxer() {
+    activeRunLogxer = undefined;
+}
+/** Queryable client surface for {@link RuntimeObjects.logxerClient}. */
+export function createGraphEngineLogxerClient(logxer) {
+    const target = logxer ?? getGraphEngineLogxer();
+    return {
+        getJobLogs(input) {
+            return target.getJobLogs(input);
+        },
+    };
+}
+/** Attach graph-level Logxer query client when hosts omit one on runtimeObjects. */
+export function ensureGraphEngineLogxerOnRuntimeObjects(runtimeObjects, logxer) {
+    if (!runtimeObjects || runtimeObjects.logxerClient != null)
+        return;
+    runtimeObjects.logxerClient = createGraphEngineLogxerClient(logxer);
+}
+/** Run graph work with Logxer correlation ids (jobId, taskId, graphId, runId). */
+export function runGraphWithLogContext(ctx, fn) {
+    return runWithLogContext(ctx, fn);
+}
+/** Narrow node-scoped correlation inside an active graph run context. */
+export function patchGraphNodeLogContext(nodeId) {
+    patchLogContext({ nodeId });
+}
+/** Gated verbose/state traces (replaces DEBUG_EXECUTION_MEMORY / DEBUG_OUTPUT_MAPPING console.log). */
+export function traceExecutionMemory(scope, message, data) {
+    if (process.env.DEBUG_EXECUTION_MEMORY !== 'true' &&
+        process.env.DEBUG_OUTPUT_MAPPING !== 'true') {
+        return;
+    }
+    getGraphEngineLogxer().verbose(message, {
+        scope,
+        ...data,
+        debugKind: DebugLogAbstract.STATE,
+    });
+}
+/** Emit a catalog-backed graph error log when a node/graph failure occurs. */
+export function logGraphEngineErrorCode(code, _message, ctx) {
+    const logxer = getGraphEngineLogxer();
+    const evidence = [
+        ...(ctx.error != null ? [exceptionEvidence(ctx.error)] : []),
+        ...Object.entries(ctx.evidence ?? {}).map(([path, value]) => fieldEvidence(path, value)),
+    ];
+    logxer.errorCode(code, {
+        graphId: ctx.graphId,
+        nodeId: ctx.nodeId,
+        jobId: ctx.jobId,
+        taskId: ctx.taskId,
+        debugKind: DebugLogAbstract.ANOMALY,
+        ...(evidence.length ? { evidence } : {}),
+    });
+}
+export { DebugLogAbstract, fieldEvidence, exceptionEvidence, runWithLogContext, patchLogContext };

package/dist/src/runtime/mergeExellixGraphRuntimeInvocation.js

@@ -28,5 +28,6 @@ export function mergeExellixGraphRuntimeInvocation(input, opts) {
         runtimeObjects: input.runtimeObjects ?? opts.runtimeObjects,
         stepRetryPolicy: input.stepRetryPolicy ?? opts.stepRetryPolicy,
         mainReadinessPolicy: input.mainReadinessPolicy ?? opts.mainReadinessPolicy,
+        logging: input.logging ?? opts.logging,
     };
 }

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

@@ -2,6 +2,7 @@
  * Runtime Objects Observability — types and composition for graph + downstream packages.
  * Callers (playground, UIs) use {@link RuntimeObjects} and queryable clients instead of reading Mongo directly.
  */
+import type { GetJobLogsInput, GetJobLogsResult, QueryableLogLine } from '@x12i/logxer';
 /** Published npm name of this package (root layer in composed observability). */
 export declare const EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME: "@exellix/graph-engine";
 /** Task layer package name in {@link RuntimeObjects.packagesRuntimeObjects}. */
@@ -18,25 +19,11 @@ export type ActivixQueryableClient = {
         activities: unknown[];
     }>;
 };
-export type LogxerLogLine = {
-    ts?: number | string;
-    level?: 'debug' | 'info' | 'warn' | 'error';
-    scope?: string;
-    packageName?: string;
-    nodeId?: string;
-    message: string;
-    data?: unknown;
-};
+/** Structured log envelope from `@x12i/logxer` `getJobLogs` (4.5.x). */
+export type LogxerLogLine = QueryableLogLine;
+/** Query surface aligned with `@x12i/logxer` `Logxer.getJobLogs` (diagnostic filters included). */
 export type LogxerQueryableClient = {
-    getJobLogs(input: {
-        jobId: string;
-        graphId?: string;
-        nodeId?: string;
-        limit?: number;
-    }): Promise<{
-        jobId: string;
-        lines: LogxerLogLine[];
-    }>;
+    getJobLogs(input: GetJobLogsInput): Promise<GetJobLogsResult>;
 };
 export type PackageRuntimeObjects = {
     name: string;

package/dist/src/runtime/runtimeObjects.js

@@ -1,7 +1,3 @@
-/**
- * Runtime Objects Observability — types and composition for graph + downstream packages.
- * Callers (playground, UIs) use {@link RuntimeObjects} and queryable clients instead of reading Mongo directly.
- */
 /** Published npm name of this package (root layer in composed observability). */
 export const EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME = '@exellix/graph-engine';
 /** Task layer package name in {@link RuntimeObjects.packagesRuntimeObjects}. */

package/dist/src/types/options.d.ts

@@ -1,4 +1,5 @@
 import type { Activix } from '@x12i/activix';
+import type { StackLoggingOptions } from '@x12i/logxer';
 import type { LlmCallConfig, RunTaskRequest as AiTasksRunTaskRequest, RunTaskResponse as AiTasksRunTaskResponse } from '@exellix/ai-tasks';
 import type { GraphModelAliasConfig, ModelConfigSelection, TaskNodeRuntimeObject } from './refs.js';
 import type { RuntimeObjects } from '../runtime/runtimeObjects.js';
@@ -79,6 +80,11 @@ export interface HostExecuteGraphRunOptions {
      * Node `taskConfiguration.mainReadinessPolicy` overrides. Default `off`.
      */
     mainReadinessPolicy?: MainReadinessPolicy;
+    /**
+     * Logxer 4.5+ stack pass-through (`GRAPH_ENGINE` and optional downstream package prefixes).
+     * Merged: per-invocation input → `createExellixGraphRuntime` defaults.
+     */
+    logging?: StackLoggingOptions;
 }
 /**
  * Optional Activix-backed persistence for per-node execution rows.

package/dist/src/types/runLog.d.ts

@@ -2,6 +2,7 @@
  * Structured run log for execution consoles (playground, Activix, HTTP APIs).
  * @see `.docs/exellix-graph-format.md` — Layer 08 / run log contract.
  */
+import type { DebugLogKind, DiagnosticEvidence, LogDiagnostics } from '@x12i/logxer';
 /**
  * NOTE: `@exellix/ai-tasks` 5.5+ no longer exports `RunLogCorrelationIds`.
  * We preserve the field for downstream consumers but keep it structurally typed.
@@ -28,6 +29,14 @@ export interface RunLogEntry {
     message: string;
     /** Optional structured payload; may be truncated (see buildRunLog / runtime options). */
     data?: unknown;
+    /** Diagnostic catalog code when merged from Logxer / ai-tasks metadata (@x12i/logxer 4.5.x). */
+    code?: string;
+    /** Structured diagnostic context (@x12i/logxer 4.5.x). */
+    diagnostics?: LogDiagnostics;
+    /** Semantic debug category (@x12i/logxer DebugLogAbstract). */
+    debugKind?: DebugLogKind;
+    /** Small diagnostic evidence samples (@x12i/logxer 4.5.x). */
+    evidence?: DiagnosticEvidence[];
 }
 /** How aggressively to populate `runLog` on {@link ExecuteGraphResult}. */
 export type RunLogMode = 'off' | 'summary' | 'full';

package/dist/src/types/runLog.js

@@ -1,7 +1,3 @@
-/**
- * Structured run log for execution consoles (playground, Activix, HTTP APIs).
- * @see `.docs/exellix-graph-format.md` — Layer 08 / run log contract.
- */
 /**
  * Canonical key on `runTask` response metadata for buffered run-log lines.
  * 5.x: only this key is read; the legacy `exellixRunLog` alias is no longer accepted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "7.2.10",
+  "version": "7.2.13",
   "type": "module",
   "description": "Graph executor SDK",
   "main": "dist/src/index.js",
@@ -25,7 +25,7 @@
   "scripts": {
     "prebuild": "node scripts/clean-dist.mjs",
     "build": "tsc",
-    "test": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit tests/model-alias-contract.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/passthrough-parity.test.ts tests/step-retry-llm-call.test.ts",
+    "test": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit tests/model-alias-contract.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/passthrough-parity.test.ts tests/step-retry-llm-call.test.ts tests/run-log-diagnostics.test.ts",
     "test:full": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit tests/graph-engine.test.ts tests/passthrough-parity.test.ts tests/task-node-run-task-preflight.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/model-alias-contract.test.ts tests/step-retry-llm-call.test.ts",
     "test:live": "npm run run:pre-synthesis",
     "run:pre-synthesis": "npm run build && node --env-file=.env scripts/run-pre-synthesis-graph.mjs",
@@ -50,19 +50,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@exellix/ai-tasks": "^8.1.10",
+    "@exellix/ai-tasks": "^8.1.12",
     "@x12i/activix": "8.3.1",
     "@x12i/ai-profiles": "1.6.0",
     "@x12i/catalox": "5.1.1",
     "@x12i/env": "4.0.1",
-    "@x12i/funcx": "4.2.0",
+    "@x12i/funcx": "4.2.2",
     "@x12i/graphenix": "2.5.0",
     "@x12i/graphenix-format": "2.0.0",
-    "@x12i/logxer": "4.4.0",
+    "@x12i/logxer": "^4.5.0",
     "@x12i/memorix-descriptors": "1.6.0",
-    "@x12i/memorix-retrieval": "1.10.0",
+    "@x12i/memorix-retrieval": "1.11.0",
     "@x12i/memorix-writer": "1.0.0",
-    "@x12i/optimixer": "^2.4.1",
+    "@x12i/optimixer": "^2.4.2",
     "@x12i/rendrix": "4.3.0",
     "@x12i/runx": "1.3.0"
   },