@exellix/graph-engine 7.3.3 → 7.3.9

package/README.md

@@ -35,6 +35,7 @@ A minimal, focused SDK for executing graphs in the exellix ecosystem.
 | Task-node `conditions` + conditional `modelConfig.cases` (runx) | [`.docs/task-node-conditions-evaluation.md`](.docs/task-node-conditions-evaluation.md) |
 | **Model profile aliases** (7.x: graph = profile names, runtime = concrete models) | [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) §7.0.0, [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md) (ai-tasks), [`.docs/fr-model-alias-descriptors.md`](.docs/fr-model-alias-descriptors.md) (upstream FRs) |
 | Platform vs implementation (no domain operators in schema) | [`.docs/platform-generic-vs-implementation.md`](.docs/platform-generic-vs-implementation.md) |
+| Activix records, `runContext`, collection tracking (`@x12i/activix` 8.4+) | [`.docs/activix-records.md`](.docs/activix-records.md) |
 | Bundled graph examples & bundle README | [`graphs/README.md`](graphs/README.md) |
 
 The **`runTask`** wire contract (identity, canonical **`input`**, optional extra ai-tasks PRE/POST utility calls vs `executionPipeline`) is summarized later under **Run identity** and **`runTask` request contract**, and expanded in the graph format doc’s [**Graph JSON vs outbound `runTask`**](.docs/exellix-graph-engine-format.md#graph-json-vs-outbound-runtask) section. Graph-engine integrates with **`@exellix/ai-tasks`** at the semver range declared in **`package.json`** (currently **`^7.6.4`**); use your **lockfile** as the tested line. Variable buckets align with ai-tasks **≥ 7.6.2** (two-scope passthrough). There is **no** minimum graph-engine ↔ ai-tasks matrix published inside ai-tasks — follow dependency semver and upstream **`CHANGELOG.md`**. Graph-engine does **not** import or invoke the Xynthesis SDK directly.
@@ -259,7 +260,7 @@ const markdown = playgroundReporter.getMarkdown();
 
 - **Results:** `ExecuteGraphResult` includes both **`jobId`** and **`taskId`** so callers and logs can correlate host scope vs engine run instance.
 
-- **Activix:** Graph-run integration persists **`jobId`**, **`taskId`**, and **`graphId`** on the record and in **`runContext`** (with **`sessionId`** still aligned to **`jobId`** for Activix v5). The in-memory correlation key for start → complete/fail is **`jobId:graphId:taskId`** so concurrent retries of the same host job against the same graph do not collide. Node activity integration keys rows by **`graphId:nodeId:taskId`** and includes **`taskId`** in **`runContext`** and top-level metadata.
+- **Activix (`@x12i/activix` 8.4+):** Graph-run and node integrations pass a top-level **`runContext`** on every `startRecord` (`sessionId` = **`jobId`**, plus **`taskId`**, **`graphId`**, and for nodes **`nodeId`** / **`skillKey`**). Activix owns **collection tracking state** (`track` / `off` on legend rows) — graph-engine **always** calls lifecycle APIs; do not branch on persistence in app code. In-process maps correlate start → complete/fail by **`activityId`** (`jobId:graphId:taskId` for graph runs; `graphId:nodeId:taskId` for nodes). Query rows via **`activixClient.getJobActivities`** (see [Activix integration](#activix-integration-graph-run-record)).
 
 - **Helpers:** **`assertHostJobId`** and **`newGraphRunTaskId`** are exported from the package root for hosts/tests that build inputs outside `executeGraph`.
 
@@ -428,12 +429,81 @@ Output shape (per item key):
 
 ## Activix integration (graph run record)
 
-When using `createActivixGraphRunIntegration()` / `createActivixExellixIntegration()`:
+Graph-engine depends on **`@x12i/activix`** (see **`package.json`**, currently **8.4.x**). Full wiring guide: [`.docs/activix-records.md`](.docs/activix-records.md). Activix README (collection tracking, `getJobActivities`, phased `outer` / `inner` I/O): `node_modules/@x12i/activix/README.md`.
+
+### Wiring (recommended)
+
+```typescript
+import {
+  createActivixFromEnv,
+  createActivixExellixIntegration,
+  createExellixGraphRuntime,
+  resolveActivixExellixCollectionNamesFromEnv,
+} from '@exellix/graph-engine';
+import { buildExellixGraphRuntimeObjects } from '@exellix/graph-engine/testkit';
+
+const ax = createActivixFromEnv({ strict: true });
+await ax.init();
+
+const { graphRuns, nodeActivity } = resolveActivixExellixCollectionNamesFromEnv();
+const { eventEmitter, activixClient } = createActivixExellixIntegration(ax, {
+  activixGraphRun: { collection: graphRuns },
+  activixNodeActivity: {
+    collection: nodeActivity,
+    includeInputSnapshot: true,
+    extractNarrixOutcome: true,
+  },
+});
+
+const runtime = createExellixGraphRuntime({
+  graphLoader,
+  engineFactory,
+  tasksClient,
+  eventEmitter,
+});
 
-- **Canonical response** is stored at `outer.output.response` and is **only** the graph’s `finalOutput`.
-- **Detailed execution data** (nodes, execution memory, errors, etc.) is stored under `outer.output.data`.
+const result = await runtime.executeGraph({
+  model: graph,
+  runtime: {
+    jobId: 'job-123',
+    job: { agentId: 'agent-1', jobType: 'analysis' },
+    input: entryInput,
+    aliasConfig: { /* … */ },
+    runtimeObjects: buildExellixGraphRuntimeObjects({ graphActivixClient: activixClient }),
+  },
+});
 
-This keeps the “business output” clean while preserving full diagnostics.
+// Playground / debug UI — no direct Mongo:
+const activities = await activixClient.getJobActivities({
+  jobId: result.jobId,
+  graphId: result.graphId,
+  limit: 500,
+});
+```
+
+**Exports:** `createActivixFromEnv`, `resolveActivixExellixCollectionNamesFromEnv`, `createActivixExellixIntegration`, `createActivixGraphRunIntegration`, `createActivixNodeActivityIntegration`, `createActivixQueryableClient`, `ensureActivixInitialized`, `ensureActivixClientOnRuntimeObjects`, `buildGraphRunActivixRunContext`, `buildNodeActivixRunContext`.
+
+### Collection tracking state (Activix 8.4+)
+
+Legend rows in **`activix-collections`** may set **`state: 'track' | 'off'`**.
+
+| Value | Meaning |
+|-------|---------|
+| **`track`** (default) | Mongo persistence for that collection |
+| **`off`** | Same APIs; Activix skips Mongo (ephemeral in-process rows only) |
+
+**Always** call `startRecord` / `completeRecord` / `failRecord` from integrations — never skip Activix in graph-engine when `off`. Toggle at runtime: `ax.setCollectionTrackingState(collectionName, 'off' | 'track')`. After external DB edits: `ax.refreshCollectionTrackingStates()`.
+
+`createActivixFromEnv()` registers both exellix streams with **`runContext`** indexes and **`collectionRegistry.owner`** = `@exellix/graph-engine`. Collection names default to **`exellix-graph-runs`** and **`exellix-node-activity`** (override with **`ACTIVIX_GRAPH_RUNS_COLLECTION`** / **`ACTIVIX_NODE_ACTIVITY_COLLECTION`**).
+
+### Record shape (graph run)
+
+When using `createActivixGraphRunIntegration()` / `createActivixExellixIntegration()`:
+
+- **Top-level `runContext`** on `startRecord` (not only nested inside custom fields).
+- **Canonical response** at `outer.output.response` — only the graph’s **`finalOutput`**.
+- **Diagnostics** under `outer.output.data` (nodes, execution, jobMemory, errors, …).
+- **Top-level `metadata`** on the row for orchestrator observability (e.g. `graphNodeCount`, `inputVariableKeys`); **`outer.metadata`** carries **`kind`** / **`type`** (`exellix-graph-run`, `graph-run`).
 
 ### Graph start — bounded input summaries (Activix)
 
@@ -448,6 +518,19 @@ Correlation fields (`jobId`, `graphId`, `agentId`, `jobType`, `inputVariableKeys
 
 **Not suitable to rely on for Activix persistence at graph start:** functions, class instances, streams, Buffers, live clients (HTTP/DB), circular graphs, or very large nested payloads — they are summarized or typed (e.g. `shape: "function"`, `shape: "instance"`) and never passed through to `startRecord` as raw references. For large memory, use `includeMemorySnapshots: true` only when you explicitly accept storing `outer.memory.start` / `end`; that remains opt-in and separate from `outer.input`.
 
+## Logxer integration (runtime logs)
+
+Graph-engine uses **`@x12i/logxer`** (4.6+) for structured logs and in-process **`getJobLogs`** (playground Logger, diagnostics).
+
+- **Per-run logger:** Each `executeGraph` creates a run-scoped Logxer (`createGraphEngineLogxer({ logging })`) and binds it for the duration of the run.
+- **Stack pass-through:** Pass **`logging?: StackLoggingOptions`** on `createExellixGraphRuntime` and/or per `executeGraph` to control downstream packages (`GRAPH_ENGINE`, `AI_TASKS`, …). The run is wrapped in **`runWithAiTasksStackLogging`** from `@exellix/ai-tasks`.
+- **Service filter (Logger UI):** Top-level **`runtimeIdentity.service`** identifies the component that emitted the line. Graph-engine native events use **`graph-engine`**. Proxied downstream records keep the **origin** service (e.g. `ai-skills`, `@exellix/ai-tasks`) with wrapper attribution in **`proxyRuntimeIdentity`** — do not rely on **`data.runtimeIdentity.service`** for filtering.
+- **Env:** `GRAPH_ENGINE_LOGS_LEVEL` (canonical); bulk stack levels via **`LOGXER_PACKAGE_LEVELS`** (see `@x12i/logxer` docs).
+
+**Exports:** `createGraphEngineLogxer`, `getGraphEngineLogxer`, `createGraphEngineLogxerClient`, `ensureGraphEngineLogxerOnRuntimeObjects`, `runGraphWithLogContext`, `GRAPH_ENGINE_RUNTIME_SERVICE`, `normalizeGraphEngineLogMeta`.
+
+Wire query surface on **`runtime.runtimeObjects.logxerClient`** (same pattern as Activix — see `buildExellixGraphRuntimeObjects` in testkit).
+
 ### `runtime.executeNode(input)`
 
 Execute a single node — useful for tests and for stepping through a node in the context of an existing graph run. Pass `node`, `job`, optional `graph` / `execution`, and (when continuing a parent run) `graphRunTaskId` from the parent `ExecuteGraphResult.taskId` so `runTask` correlation, Activix records, and `runLog` lines stay aligned.
@@ -826,6 +909,18 @@ To execute a graph, supply a `graphLoader` that resolves `graphId` to JSON, buil
 
 **`taskConfiguration.aiTasksOutputValidation`** on task nodes is forwarded as **`outputValidation`** on the `runTask` request (**`@exellix/ai-tasks` v7+**). Root **`outputConstraints`** is not part of the closed schema.
 
+## Runtime observability (`runtimeObjects`)
+
+Hosts and playgrounds compose a single **`runtimeObjects`** tree instead of querying Mongo or Logxer stores directly:
+
+| Client | Source | Query API |
+|--------|--------|-----------|
+| **`activixClient`** | Your `Activix` instance via `createActivixQueryableClient` / `createActivixExellixIntegration` | `getJobActivities({ jobId, graphId?, nodeId?, limit? })` |
+| **`logxerClient`** | Per-run graph-engine Logxer via `ensureGraphEngineLogxerOnRuntimeObjects` | `getJobLogs({ jobId, graphId?, nodeId?, level?, … })` |
+| **`packagesRuntimeObjects`** | Optional subtree from `@exellix/ai-tasks` | Package-owned clients when exported |
+
+Use **`buildExellixGraphRuntimeObjects({ graphActivixClient, graphLogxerClient, aiTasksRuntimeObjects })`** (testkit) and pass the result on **`runtime.runtimeObjects`**. **`setRuntimeObjectsLastJobId`** is applied automatically during `executeGraph`.
+
 ## Integration with Other Packages
 
 See `.reports/` directory for request documents:

package/dist/src/index.d.ts

@@ -23,7 +23,7 @@ export type { NodeExecutionResult, NodeTraceEntry, StepAttemptRecord, StepFailur
 export type { RunLogEntry, RunLogLevel, RunLogScope, RunLogMode, RunLogBuildOptions, RunLogBuildResult, } from './types/runLog.js';
 export { AI_TASKS_RUN_LOG_METADATA_KEY, AI_TASKS_LOGXER_RUN_ID_METADATA_KEY, DEFAULT_MAX_RUN_LOG_ENTRIES, DEFAULT_MAX_RUN_LOG_DATA_JSON_CHARS, } from './types/runLog.js';
 export { buildRunLog, resolveRunLogLimits, truncateRunLogData, parseRunLogEntryTs, normalizeExternalRunLogEntries, extractTaskRunLogFromMetadata, extractLogxerCorrelationFromMetadata, } from './runtime/buildRunLog.js';
-export { GRAPH_ENGINE_LOGXER_ENV_PREFIX, createGraphEngineLogxer, getGraphEngineLogxer, createGraphEngineLogxerClient, ensureGraphEngineLogxerOnRuntimeObjects, bindGraphEngineRunLogxer, clearGraphEngineRunLogxer, runGraphWithLogContext, patchGraphNodeLogContext, traceExecutionMemory, logGraphEngineErrorCode, DebugLogAbstract as GraphEngineDebugLogAbstract, fieldEvidence as graphEngineFieldEvidence, exceptionEvidence as graphEngineExceptionEvidence, } from './runtime/graphEngineLogxer.js';
+export { GRAPH_ENGINE_LOGXER_ENV_PREFIX, createGraphEngineLogxer, getGraphEngineLogxer, createGraphEngineLogxerClient, ensureGraphEngineLogxerOnRuntimeObjects, bindGraphEngineRunLogxer, clearGraphEngineRunLogxer, runGraphWithLogContext, patchGraphNodeLogContext, traceExecutionMemory, logGraphEngineErrorCode, DebugLogAbstract as GraphEngineDebugLogAbstract, fieldEvidence as graphEngineFieldEvidence, exceptionEvidence as graphEngineExceptionEvidence, GRAPH_ENGINE_RUNTIME_SERVICE, GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY, extractOriginRuntimeIdentity, normalizeGraphEngineLogMeta, } from './runtime/graphEngineLogxer.js';
 export type { GetJobLogsInput as GraphEngineGetJobLogsInput, GetJobLogsResult as GraphEngineGetJobLogsResult, LogRuntimeContext as GraphEngineLogRuntimeContext, StackLoggingOptions as GraphEngineStackLoggingOptions, } from './runtime/graphEngineLogxer.js';
 export type { GraphExecutionEvent, NodeExecutionEvent, } from './types/events.js';
 export { ExellixGraphError } from './errors/ExellixGraphError.js';
@@ -99,6 +99,8 @@ export type { CreateActivixGraphRunIntegrationOptions } from './integrations/Act
 export { createActivixFromEnv, resolveActivixExellixCollectionNamesFromEnv, } from './integrations/createActivixFromEnv.js';
 export { createActivixExellixIntegration } from './integrations/createActivixExellixIntegration.js';
 export type { CreateActivixExellixIntegrationOptions } from './integrations/createActivixExellixIntegration.js';
+export { createActivixQueryableClient, ensureActivixInitialized, buildGraphRunActivixRunContext, buildNodeActivixRunContext, } from './integrations/activixExellixShared.js';
+export { ensureActivixClientOnRuntimeObjects } from './integrations/ensureActivixOnRuntimeObjects.js';
 export { validateGraphPlanningCatalogDescriptorsInCatalox } from './integrations/cataloxGraphCatalog.js';
 export type { GraphCatalogValidationIssue } from './integrations/cataloxGraphCatalog.js';
 export { composeEventEmitters } from './runtime/events.js';

package/dist/src/index.js

@@ -16,7 +16,7 @@ export { mergeGraphDocumentModel, EXELLIX_GRAPH_MODEL_VARIABLE_KEY, EXELLIX_STRU
 export { getTaskConfiguration } from './types/taskNodeConfiguration.js';
 export { AI_TASKS_RUN_LOG_METADATA_KEY, AI_TASKS_LOGXER_RUN_ID_METADATA_KEY, DEFAULT_MAX_RUN_LOG_ENTRIES, DEFAULT_MAX_RUN_LOG_DATA_JSON_CHARS, } from './types/runLog.js';
 export { buildRunLog, resolveRunLogLimits, truncateRunLogData, parseRunLogEntryTs, normalizeExternalRunLogEntries, extractTaskRunLogFromMetadata, extractLogxerCorrelationFromMetadata, } from './runtime/buildRunLog.js';
-export { GRAPH_ENGINE_LOGXER_ENV_PREFIX, createGraphEngineLogxer, getGraphEngineLogxer, createGraphEngineLogxerClient, ensureGraphEngineLogxerOnRuntimeObjects, bindGraphEngineRunLogxer, clearGraphEngineRunLogxer, runGraphWithLogContext, patchGraphNodeLogContext, traceExecutionMemory, logGraphEngineErrorCode, DebugLogAbstract as GraphEngineDebugLogAbstract, fieldEvidence as graphEngineFieldEvidence, exceptionEvidence as graphEngineExceptionEvidence, } from './runtime/graphEngineLogxer.js';
+export { GRAPH_ENGINE_LOGXER_ENV_PREFIX, createGraphEngineLogxer, getGraphEngineLogxer, createGraphEngineLogxerClient, ensureGraphEngineLogxerOnRuntimeObjects, bindGraphEngineRunLogxer, clearGraphEngineRunLogxer, runGraphWithLogContext, patchGraphNodeLogContext, traceExecutionMemory, logGraphEngineErrorCode, DebugLogAbstract as GraphEngineDebugLogAbstract, fieldEvidence as graphEngineFieldEvidence, exceptionEvidence as graphEngineExceptionEvidence, GRAPH_ENGINE_RUNTIME_SERVICE, GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY, extractOriginRuntimeIdentity, normalizeGraphEngineLogMeta, } from './runtime/graphEngineLogxer.js';
 // Errors
 export { ExellixGraphError } from './errors/ExellixGraphError.js';
 export { ExellixGraphErrorCode } from './errors/exellixGraphErrorCodes.js';
@@ -74,6 +74,8 @@ export { createActivixNodeActivityIntegration } from './integrations/ActivixNode
 export { createActivixGraphRunIntegration } from './integrations/ActivixGraphRunIntegration.js';
 export { createActivixFromEnv, resolveActivixExellixCollectionNamesFromEnv, } from './integrations/createActivixFromEnv.js';
 export { createActivixExellixIntegration } from './integrations/createActivixExellixIntegration.js';
+export { createActivixQueryableClient, ensureActivixInitialized, buildGraphRunActivixRunContext, buildNodeActivixRunContext, } from './integrations/activixExellixShared.js';
+export { ensureActivixClientOnRuntimeObjects } from './integrations/ensureActivixOnRuntimeObjects.js';
 export { validateGraphPlanningCatalogDescriptorsInCatalox } from './integrations/cataloxGraphCatalog.js';
 export { composeEventEmitters } from './runtime/events.js';
 // Playground (full-visibility MD report)

package/dist/src/integrations/ActivixGraphRunIntegration.d.ts

@@ -23,8 +23,9 @@ export interface CreateActivixGraphRunIntegrationOptions {
 }
 /**
  * Returns an EventEmitter that persists graph lifecycle rows via Activix.
- * Correlates start → complete/fail via an in-memory map keyed by `jobId:graphId:taskId`
- * (host job id + graph id + engine-generated graph-run UUID).
+ * Correlates start → complete/fail via in-process `activityId` (returned from `startRecord`).
+ * Activix 8.4+ owns collection tracking state (`track` / `off` on legend rows); always call
+ * `startRecord` / `completeRecord` / `failRecord` — persistence is decided inside Activix.
  *
  * On `graph:start`, `outer.input` contains only bounded **`inputSummary`** / **`requestSummary`**
  * (JSON-serializable); raw event input/request objects are not copied to Activix.

package/dist/src/integrations/ActivixGraphRunIntegration.js

@@ -1,3 +1,4 @@
+import { buildGraphRunActivixRunContext, ensureActivixInitialized, } from './activixExellixShared.js';
 function summarizeValueForRecord(value) {
     if (value === null || value === undefined) {
         return { shape: 'empty' };
@@ -167,8 +168,9 @@ function summarizeForActivix(value, depth = 0, seen = new WeakSet()) {
 }
 /**
  * Returns an EventEmitter that persists graph lifecycle rows via Activix.
- * Correlates start → complete/fail via an in-memory map keyed by `jobId:graphId:taskId`
- * (host job id + graph id + engine-generated graph-run UUID).
+ * Correlates start → complete/fail via in-process `activityId` (returned from `startRecord`).
+ * Activix 8.4+ owns collection tracking state (`track` / `off` on legend rows); always call
+ * `startRecord` / `completeRecord` / `failRecord` — persistence is decided inside Activix.
  *
  * On `graph:start`, `outer.input` contains only bounded **`inputSummary`** / **`requestSummary`**
  * (JSON-serializable); raw event input/request objects are not copied to Activix.
@@ -179,22 +181,12 @@ export function createActivixGraphRunIntegration(ax, options) {
     const includeMemorySnapshots = options?.includeMemorySnapshots === true;
     const colOpts = collection ? { collection } : undefined;
     const graphRecordIds = new Map();
-    let initPromise = null;
-    function ensureInit() {
-        if (!initPromise) {
-            initPromise = ax.init().catch((err) => {
-                initPromise = null;
-                throw err;
-            });
-        }
-        return initPromise;
-    }
     const eventEmitter = {
         emit(event) {
             setImmediate(async () => {
                 try {
                     if (event.type === 'graph:start') {
-                        await ensureInit();
+                        await ensureActivixInitialized(ax);
                         const graphEvent = event;
                         const data = graphEvent.data;
                         const key = `${graphEvent.jobId}:${graphEvent.graphId}:${graphEvent.taskId}`;
@@ -203,56 +195,49 @@ export function createActivixGraphRunIntegration(ax, options) {
                         const agentId = data?.agentId;
                         const jobType = data?.jobType;
                         const graphNodeCount = getGraphNodeCount(data?.graphDefinition);
-                        // Activix v5+ correlation object is `runContext` and must include `sessionId`.
-                        // This SDK does not have a separate session id today, so we align it to `jobId`.
-                        const runContext = {
-                            sessionId: graphEvent.jobId,
+                        const runContext = buildGraphRunActivixRunContext({
                             jobId: graphEvent.jobId,
                             taskId: graphEvent.taskId,
                             graphId: graphEvent.graphId,
                             agentId,
-                            ...(jobType != null ? { jobType } : {}),
-                        };
+                            jobType,
+                        });
                         const outerMemoryStart = data?.memoryStart;
                         const outerMetadata = {
                             kind: 'exellix-graph-run',
+                            type: 'graph-run',
                             jobId: graphEvent.jobId,
                             taskId: graphEvent.taskId,
                             graphId: graphEvent.graphId,
-                            agentId,
+                            ...(agentId != null ? { agentId } : {}),
                             ...(jobType != null ? { jobType } : {}),
                             graphNodeCount,
                             inputVariableKeys,
                             eventTimestamp: graphEvent.timestamp,
                         };
-                        const base = {
-                            kind: 'exellix-graph-run',
-                            jobId: graphEvent.jobId,
-                            taskId: graphEvent.taskId,
-                            graphId: graphEvent.graphId,
-                            agentId,
-                            ...(jobType != null ? { jobType } : {}),
-                            graphNodeCount,
-                            inputVariableKeys,
-                            eventTimestamp: graphEvent.timestamp,
+                        const { activityId } = await ax.startRecord({
                             runContext,
                             outer: {
                                 input: {
                                     inputSummary: summarizeForActivix(data?.input),
                                     requestSummary: summarizeForActivix(data?.request),
                                 },
-                                output: undefined,
-                                memory: {
-                                    ...(includeMemorySnapshots ? { start: outerMemoryStart } : {}),
-                                },
+                                output: null,
                                 metadata: outerMetadata,
+                                ...(includeMemorySnapshots && outerMemoryStart != null
+                                    ? { memory: { start: outerMemoryStart } }
+                                    : {}),
                             },
-                        };
-                        const { recordId } = await ax.startRecord(base, colOpts);
-                        graphRecordIds.set(key, recordId);
+                            metadata: {
+                                graphNodeCount,
+                                inputVariableKeys,
+                                eventTimestamp: graphEvent.timestamp,
+                            },
+                        }, colOpts);
+                        graphRecordIds.set(key, activityId);
                     }
                     else if (event.type === 'graph:complete') {
-                        await ensureInit();
+                        await ensureActivixInitialized(ax);
                         const graphEvent = event;
                         const key = `${graphEvent.jobId}:${graphEvent.graphId}:${graphEvent.taskId}`;
                         const recordId = graphRecordIds.get(key);
@@ -291,7 +276,7 @@ export function createActivixGraphRunIntegration(ax, options) {
                         graphRecordIds.delete(key);
                     }
                     else if (event.type === 'graph:fail') {
-                        await ensureInit();
+                        await ensureActivixInitialized(ax);
                         const graphEvent = event;
                         const key = `${graphEvent.jobId}:${graphEvent.graphId}:${graphEvent.taskId}`;
                         const recordId = graphRecordIds.get(key);

package/dist/src/integrations/ActivixNodeActivityIntegration.d.ts

@@ -21,7 +21,8 @@ export interface CreateActivixNodeActivityIntegrationOptions {
 }
 /**
  * Returns an EventEmitter that persists node lifecycle rows via Activix.
- * Correlates start → complete/fail using `graphId:nodeId:taskId` (includes engine-generated graph-run `taskId`).
+ * Correlates start → complete/fail via in-process `activityId` from `startRecord`.
+ * Activix 8.4+ owns collection tracking state; always call lifecycle APIs (see `activixExellixShared`).
  */
 export declare function createActivixNodeActivityIntegration(ax: Activix, options?: CreateActivixNodeActivityIntegrationOptions): {
     eventEmitter: EventEmitter;

package/dist/src/integrations/ActivixNodeActivityIntegration.js

@@ -3,6 +3,7 @@
  *
  * Listens for `node:start`, `node:complete`, and `node:fail` only. Graph-level events are ignored.
  */
+import { buildNodeActivixRunContext, ensureActivixInitialized, } from './activixExellixShared.js';
 function summarizeValueForRecord(value) {
     if (value === null || value === undefined) {
         return { shape: 'empty' };
@@ -24,7 +25,8 @@ function isPlainObject(v) {
 }
 /**
  * Returns an EventEmitter that persists node lifecycle rows via Activix.
- * Correlates start → complete/fail using `graphId:nodeId:taskId` (includes engine-generated graph-run `taskId`).
+ * Correlates start → complete/fail via in-process `activityId` from `startRecord`.
+ * Activix 8.4+ owns collection tracking state; always call lifecycle APIs (see `activixExellixShared`).
  */
 export function createActivixNodeActivityIntegration(ax, options) {
     const collection = options?.collection;
@@ -32,16 +34,6 @@ export function createActivixNodeActivityIntegration(ax, options) {
     const extractNarrixOutcome = options?.extractNarrixOutcome === true;
     const colOpts = collection ? { collection } : undefined;
     const nodeRecordIds = new Map();
-    let initPromise = null;
-    function ensureInit() {
-        if (!initPromise) {
-            initPromise = ax.init().catch((err) => {
-                initPromise = null;
-                throw err;
-            });
-        }
-        return initPromise;
-    }
     const eventEmitter = {
         emit(event) {
             setImmediate(async () => {
@@ -52,22 +44,20 @@ export function createActivixNodeActivityIntegration(ax, options) {
                         const jobType = nodeEvent.data != null && typeof nodeEvent.data === 'object' && 'jobType' in nodeEvent.data
                             ? nodeEvent.data.jobType
                             : undefined;
-                        // Activix v5+ correlation object is `runContext` and must include `sessionId`.
-                        // This SDK does not have a separate session id today, so we align it to `jobId`.
-                        const runContext = {
-                            sessionId: nodeEvent.jobId,
+                        const runContext = buildNodeActivixRunContext({
                             jobId: nodeEvent.jobId,
                             taskId: nodeEvent.taskId,
                             graphId: nodeEvent.graphId,
                             nodeId: nodeEvent.nodeId,
                             skillKey: nodeEvent.skillKey,
-                            ...(jobType != null ? { jobType } : {}),
-                        };
+                            jobType,
+                        });
                         const outerInput = isPlainObject(input) ? input : {};
                         const outerRequest = nodeEvent.data?.input?.request;
                         const outerMemoryStart = nodeEvent.data?.input?.memoryStart;
                         const outerMetadata = {
                             kind: 'exellix-graph-node',
+                            type: 'task',
                             jobId: nodeEvent.jobId,
                             taskId: nodeEvent.taskId,
                             graphId: nodeEvent.graphId,
@@ -76,52 +66,42 @@ export function createActivixNodeActivityIntegration(ax, options) {
                             ...(jobType != null ? { jobType } : {}),
                             eventTimestamp: nodeEvent.timestamp,
                         };
-                        const base = {
-                            kind: 'exellix-graph-node',
-                            jobId: nodeEvent.jobId,
-                            taskId: nodeEvent.taskId,
-                            graphId: nodeEvent.graphId,
-                            nodeId: nodeEvent.nodeId,
-                            skillKey: nodeEvent.skillKey,
-                            ...(jobType != null ? { jobType } : {}),
+                        const topMetadata = {
                             eventTimestamp: nodeEvent.timestamp,
-                            runContext,
-                            outer: {
-                                input: {
-                                    ...outerInput,
-                                    request: outerRequest,
-                                },
-                                output: undefined,
-                                memory: {
-                                    start: outerMemoryStart,
-                                },
-                                metadata: outerMetadata,
-                            },
                         };
                         if (includeInputSnapshot && input && typeof input === 'object') {
                             const vars = input.variables;
                             if (vars && typeof vars === 'object') {
-                                base.inputVariableKeys = Object.keys(vars);
-                                if (isPlainObject(base.outer?.metadata)) {
-                                    base.outer.metadata.inputVariableKeys = base.inputVariableKeys;
-                                }
+                                const inputVariableKeys = Object.keys(vars);
+                                outerMetadata.inputVariableKeys = inputVariableKeys;
+                                topMetadata.inputVariableKeys = inputVariableKeys;
                             }
                             const jm = input.jobMemory;
                             const ex = jm?.execution;
                             if (ex != null && typeof ex === 'object') {
-                                base.executionKeys = Object.keys(ex);
-                                if (isPlainObject(base.outer?.metadata)) {
-                                    base.outer.metadata.executionKeys = base.executionKeys;
-                                }
+                                const executionKeys = Object.keys(ex);
+                                outerMetadata.executionKeys = executionKeys;
+                                topMetadata.executionKeys = executionKeys;
                             }
                         }
+                        const startPayload = {
+                            runContext,
+                            outer: {
+                                input: {
+                                    ...outerInput,
+                                    ...(outerRequest !== undefined ? { request: outerRequest } : {}),
+                                },
+                                output: null,
+                                metadata: outerMetadata,
+                                ...(outerMemoryStart !== undefined ? { memory: { start: outerMemoryStart } } : {}),
+                            },
+                            metadata: topMetadata,
+                        };
                         const key = `${nodeEvent.graphId}:${nodeEvent.nodeId}:${nodeEvent.taskId}`;
-                        // Start the record insert immediately (promise inserted into the map synchronously),
-                        // but defer actual DB work until `ax.init()` is ready.
                         const recordPromise = (async () => {
-                            await ensureInit();
-                            const { recordId } = await ax.startRecord(base, colOpts);
-                            return recordId;
+                            await ensureActivixInitialized(ax);
+                            const { activityId } = await ax.startRecord(startPayload, colOpts);
+                            return activityId;
                         })();
                         nodeRecordIds.set(key, recordPromise);
                         await recordPromise;

package/dist/src/integrations/activixExellixShared.d.ts

@@ -0,0 +1,58 @@
+import type { Activix, ActivixRunContext } from '@x12i/activix';
+import type { ActivixQueryableClient } from '../runtime/runtimeObjects.js';
+/** Recommended Mongo indexes for exellix-graph Activix streams (see `@x12i/activix` README). */
+export declare const ACTIVIX_EXELLIX_RUN_CONTEXT_INDEXES: readonly [{
+    readonly keys: {
+        readonly 'runContext.jobId': 1;
+    };
+}, {
+    readonly keys: {
+        readonly 'runContext.graphId': 1;
+    };
+}, {
+    readonly keys: {
+        readonly 'runContext.taskId': 1;
+    };
+}];
+export declare const ACTIVIX_EXELLIX_NODE_RUN_CONTEXT_INDEXES: readonly [{
+    readonly keys: {
+        readonly 'runContext.jobId': 1;
+    };
+}, {
+    readonly keys: {
+        readonly 'runContext.graphId': 1;
+    };
+}, {
+    readonly keys: {
+        readonly 'runContext.taskId': 1;
+    };
+}, {
+    readonly keys: {
+        readonly 'runContext.nodeId': 1;
+    };
+}];
+/**
+ * Single `init()` per Activix instance. Integrators always call Activix lifecycle APIs;
+ * collection `state` (track/off) is resolved inside Activix — do not branch in graph-engine.
+ */
+export declare function ensureActivixInitialized(ax: Activix): Promise<void>;
+/** Official query surface: delegate to `Activix.getJobActivities` (8.x). */
+export declare function createActivixQueryableClient(ax: Activix): ActivixQueryableClient;
+export declare function buildGraphRunActivixRunContext(args: {
+    jobId: string;
+    taskId: string;
+    graphId: string;
+    agentId?: string;
+    jobType?: string;
+}): ActivixRunContext;
+export declare function buildNodeActivixRunContext(args: {
+    jobId: string;
+    taskId: string;
+    graphId: string;
+    nodeId: string;
+    skillKey?: string;
+    jobType?: string;
+}): ActivixRunContext;
+export declare function activixExellixCollectionRegistryOwner(): {
+    package: "@exellix/graph-engine";
+};

package/dist/src/integrations/activixExellixShared.js

@@ -0,0 +1,59 @@
+import { EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME } from '../runtime/runtimeObjects.js';
+/** Recommended Mongo indexes for exellix-graph Activix streams (see `@x12i/activix` README). */
+export const ACTIVIX_EXELLIX_RUN_CONTEXT_INDEXES = [
+    { keys: { 'runContext.jobId': 1 } },
+    { keys: { 'runContext.graphId': 1 } },
+    { keys: { 'runContext.taskId': 1 } },
+];
+export const ACTIVIX_EXELLIX_NODE_RUN_CONTEXT_INDEXES = [
+    ...ACTIVIX_EXELLIX_RUN_CONTEXT_INDEXES,
+    { keys: { 'runContext.nodeId': 1 } },
+];
+let sharedInitByActivix = new WeakMap();
+/**
+ * Single `init()` per Activix instance. Integrators always call Activix lifecycle APIs;
+ * collection `state` (track/off) is resolved inside Activix — do not branch in graph-engine.
+ */
+export function ensureActivixInitialized(ax) {
+    let p = sharedInitByActivix.get(ax);
+    if (!p) {
+        p = ax.init().catch((err) => {
+            sharedInitByActivix.delete(ax);
+            throw err;
+        });
+        sharedInitByActivix.set(ax, p);
+    }
+    return p;
+}
+/** Official query surface: delegate to `Activix.getJobActivities` (8.x). */
+export function createActivixQueryableClient(ax) {
+    return {
+        getJobActivities(input) {
+            return ax.getJobActivities(input);
+        },
+    };
+}
+export function buildGraphRunActivixRunContext(args) {
+    return {
+        sessionId: args.jobId,
+        jobId: args.jobId,
+        taskId: args.taskId,
+        graphId: args.graphId,
+        ...(args.agentId != null && args.agentId !== '' ? { agentId: args.agentId } : {}),
+        ...(args.jobType != null ? { jobType: args.jobType } : {}),
+    };
+}
+export function buildNodeActivixRunContext(args) {
+    return {
+        sessionId: args.jobId,
+        jobId: args.jobId,
+        taskId: args.taskId,
+        graphId: args.graphId,
+        nodeId: args.nodeId,
+        ...(args.skillKey != null && args.skillKey !== '' ? { skillKey: args.skillKey } : {}),
+        ...(args.jobType != null ? { jobType: args.jobType } : {}),
+    };
+}
+export function activixExellixCollectionRegistryOwner() {
+    return { package: EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME };
+}

package/dist/src/integrations/createActivixExellixIntegration.d.ts

@@ -1,5 +1,6 @@
 import type { Activix } from '@x12i/activix';
 import type { EventEmitter } from '../runtime/events.js';
+import type { ActivixQueryableClient } from '../runtime/runtimeObjects.js';
 import { type CreateActivixNodeActivityIntegrationOptions } from './ActivixNodeActivityIntegration.js';
 import { type CreateActivixGraphRunIntegrationOptions } from './ActivixGraphRunIntegration.js';
 export interface CreateActivixExellixIntegrationOptions {
@@ -11,4 +12,6 @@ export interface CreateActivixExellixIntegrationOptions {
  */
 export declare function createActivixExellixIntegration(ax: Activix, options?: CreateActivixExellixIntegrationOptions): {
     eventEmitter: EventEmitter | undefined;
+    /** Use with {@link buildExellixGraphRuntimeObjects} as `graphActivixClient`. */
+    activixClient: ActivixQueryableClient;
 };

package/dist/src/integrations/createActivixExellixIntegration.js

@@ -1,4 +1,5 @@
 import { composeEventEmitters } from '../runtime/events.js';
+import { createActivixQueryableClient } from './activixExellixShared.js';
 import { createActivixNodeActivityIntegration, } from './ActivixNodeActivityIntegration.js';
 import { createActivixGraphRunIntegration, } from './ActivixGraphRunIntegration.js';
 /**
@@ -12,5 +13,5 @@ export function createActivixExellixIntegration(ax, options) {
         ? createActivixGraphRunIntegration(ax, options.activixGraphRun)
         : undefined;
     const eventEmitter = composeEventEmitters(node?.eventEmitter, graph?.eventEmitter);
-    return { eventEmitter };
+    return { eventEmitter, activixClient: createActivixQueryableClient(ax) };
 }

package/dist/src/integrations/createActivixFromEnv.js

@@ -1,4 +1,5 @@
 import { Activix } from '@x12i/activix';
+import { ACTIVIX_EXELLIX_NODE_RUN_CONTEXT_INDEXES, ACTIVIX_EXELLIX_RUN_CONTEXT_INDEXES, activixExellixCollectionRegistryOwner, } from './activixExellixShared.js';
 function requiredEnv(name, strict) {
     const v = process.env[name];
     if (v && v.trim().length > 0)
@@ -45,9 +46,18 @@ export function createActivixFromEnv(options) {
     return new Activix({
         mongoUri,
         defaultCollection: nodeActivityCollection,
+        collectionRegistry: {
+            owner: activixExellixCollectionRegistryOwner(),
+        },
         collections: [
-            { name: graphRunsCollection },
-            { name: nodeActivityCollection },
+            {
+                name: graphRunsCollection,
+                indexes: [...ACTIVIX_EXELLIX_RUN_CONTEXT_INDEXES],
+            },
+            {
+                name: nodeActivityCollection,
+                indexes: [...ACTIVIX_EXELLIX_NODE_RUN_CONTEXT_INDEXES],
+            },
         ],
     });
 }

package/dist/src/integrations/ensureActivixOnRuntimeObjects.d.ts

@@ -0,0 +1,4 @@
+import type { Activix } from '@x12i/activix';
+import type { RuntimeObjects } from '../runtime/runtimeObjects.js';
+/** Wires graph-level `getJobActivities` when a host supplies an Activix instance on `runtimeObjects`. */
+export declare function ensureActivixClientOnRuntimeObjects(runtimeObjects: RuntimeObjects | undefined, ax?: Activix): void;

package/dist/src/integrations/ensureActivixOnRuntimeObjects.js

@@ -0,0 +1,7 @@
+import { createActivixQueryableClient } from './activixExellixShared.js';
+/** Wires graph-level `getJobActivities` when a host supplies an Activix instance on `runtimeObjects`. */
+export function ensureActivixClientOnRuntimeObjects(runtimeObjects, ax) {
+    if (!runtimeObjects || runtimeObjects.activixClient != null || ax == null)
+        return;
+    runtimeObjects.activixClient = createActivixQueryableClient(ax);
+}

package/dist/src/runtime/ExellixGraphRuntime.js

@@ -25,6 +25,7 @@ import { buildRunTaskIdentityEnvelope, mergeDefinedLlmCallParts, shouldForwardRu
 import { buildRunLog, extractLogxerCorrelationFromMetadata, extractTaskRunLogFromMetadata, resolveRunLogLimits, } from "./buildRunLog.js";
 import { setRuntimeObjectsLastJobId, summarizeRuntimeObjectsForPlayground } from "./runtimeObjects.js";
 import { DebugLogAbstract, bindGraphEngineRunLogxer, clearGraphEngineRunLogxer, createGraphEngineLogxer, ensureGraphEngineLogxerOnRuntimeObjects, logGraphEngineErrorCode, patchGraphNodeLogContext, runGraphWithLogContext, traceExecutionMemory, } from "./graphEngineLogxer.js";
+import { runWithAiTasksStackLogging } from "@exellix/ai-tasks";
 import { assertHostJobId, newGraphRunTaskId } from "./graphRunIdentity.js";
 import { resolveTaskKey } from "./resolveTaskKey.js";
 import { buildPredicateEvalContextForNode, mirrorTaskVariablesOnExecution, readExecutionVariableBuckets, seedGraphVariableBucketsFromRuntime, } from "./variables.js";
@@ -1157,7 +1158,7 @@ export function createExellixGraphRuntime(opts) {
         }
         const resolvedGraphId = String(resolvedGraphIdRaw);
         const runLogxer = createGraphEngineLogxer({ logging: merged.logging });
-        return runGraphWithLogContext({ jobId, taskId: graphTaskId, graphId: resolvedGraphId, runId: graphTaskId }, async () => {
+        return runWithAiTasksStackLogging(merged.logging, () => runGraphWithLogContext({ jobId, taskId: graphTaskId, graphId: resolvedGraphId, runId: graphTaskId }, async () => {
             bindGraphEngineRunLogxer(runLogxer);
             try {
                 assertCanonicalGraphDocument(graph, { jobId, graphId: resolvedGraphId });
@@ -1721,7 +1722,7 @@ export function createExellixGraphRuntime(opts) {
             finally {
                 clearGraphEngineRunLogxer();
             }
-        });
+        }));
     }
     return {
         executeGraph,

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

@@ -0,0 +1,16 @@
+import type { LogMeta, RuntimeIdentity } from '@x12i/logxer';
+/** Canonical filter key for graph-engine's own log lines. */
+export declare const GRAPH_ENGINE_RUNTIME_SERVICE: "graph-engine";
+/** Wrapper attribution when graph-engine proxies a downstream Logxer record. */
+export declare const GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY: RuntimeIdentity;
+/**
+ * Resolve the originating component identity from meta or nested payload shapes
+ * (e.g. proxied envelopes stored under `data.runtimeIdentity`).
+ */
+export declare function extractOriginRuntimeIdentity(meta: LogMeta | undefined): RuntimeIdentity | undefined;
+/**
+ * Ensures top-level `runtimeIdentity.service` is the log origin for filtering.
+ * Graph-engine-native lines use `graph-engine`; proxied downstream lines keep the
+ * downstream service and record wrapper attribution on `proxyRuntimeIdentity`.
+ */
+export declare function normalizeGraphEngineLogMeta(meta?: LogMeta): LogMeta | undefined;

package/dist/src/runtime/graphEngineLogMeta.js

@@ -0,0 +1,75 @@
+import { EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME } from './runtimeObjects.js';
+/** Canonical filter key for graph-engine's own log lines. */
+export const GRAPH_ENGINE_RUNTIME_SERVICE = 'graph-engine';
+/** Wrapper attribution when graph-engine proxies a downstream Logxer record. */
+export const GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY = {
+    service: GRAPH_ENGINE_RUNTIME_SERVICE,
+    libraryPackage: EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME,
+};
+function isRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function readRuntimeIdentity(value) {
+    if (!isRecord(value))
+        return undefined;
+    const service = value.service;
+    if (typeof service !== 'string' || service.length === 0)
+        return undefined;
+    return value;
+}
+function isDownstreamOrigin(identity) {
+    const service = identity.service;
+    return typeof service === 'string' && service.length > 0 && service !== GRAPH_ENGINE_RUNTIME_SERVICE;
+}
+/**
+ * Resolve the originating component identity from meta or nested payload shapes
+ * (e.g. proxied envelopes stored under `data.runtimeIdentity`).
+ */
+export function extractOriginRuntimeIdentity(meta) {
+    if (!meta)
+        return undefined;
+    const candidates = [];
+    if (meta.runtimeIdentity != null)
+        candidates.push(meta.runtimeIdentity);
+    const data = meta.data;
+    if (isRecord(data)) {
+        if (data.runtimeIdentity != null)
+            candidates.push(data.runtimeIdentity);
+        if (isRecord(data.data) && data.data.runtimeIdentity != null) {
+            candidates.push(data.data.runtimeIdentity);
+        }
+    }
+    for (const raw of candidates) {
+        const identity = readRuntimeIdentity(raw);
+        if (identity != null && isDownstreamOrigin(identity))
+            return identity;
+    }
+    return undefined;
+}
+/**
+ * Ensures top-level `runtimeIdentity.service` is the log origin for filtering.
+ * Graph-engine-native lines use `graph-engine`; proxied downstream lines keep the
+ * downstream service and record wrapper attribution on `proxyRuntimeIdentity`.
+ */
+export function normalizeGraphEngineLogMeta(meta) {
+    if (meta == null)
+        return meta;
+    const origin = extractOriginRuntimeIdentity(meta);
+    if (origin != null) {
+        return {
+            ...meta,
+            runtimeIdentity: origin,
+            proxyRuntimeIdentity: GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY,
+        };
+    }
+    const existing = readRuntimeIdentity(meta.runtimeIdentity);
+    const runtimeIdentity = {
+        ...GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY,
+        ...(existing ?? {}),
+        service: GRAPH_ENGINE_RUNTIME_SERVICE,
+    };
+    return {
+        ...meta,
+        runtimeIdentity,
+    };
+}

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

@@ -4,6 +4,7 @@
  */
 import type { GetJobLogsInput, GetJobLogsResult, Logxer, LogRuntimeContext, StackLoggingOptions } from '@x12i/logxer';
 import type { LogxerQueryableClient, RuntimeObjects } from './runtimeObjects.js';
+export { GRAPH_ENGINE_RUNTIME_SERVICE, GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY, extractOriginRuntimeIdentity, normalizeGraphEngineLogMeta, } from './graphEngineLogMeta.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 (logxer 4.5+ stack pass-through). */

package/dist/src/runtime/graphEngineLogxer.js

@@ -1,6 +1,8 @@
 const logxer = await import('@x12i/logxer');
 import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
 import { EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME } from './runtimeObjects.js';
+import { normalizeGraphEngineLogMeta, } from './graphEngineLogMeta.js';
+export { GRAPH_ENGINE_RUNTIME_SERVICE, GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY, extractOriginRuntimeIdentity, normalizeGraphEngineLogMeta, } from './graphEngineLogMeta.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 = {
@@ -75,20 +77,50 @@ let defaultLogxer;
 let activeRunLogxer;
 function buildGraphEngineLogxerConfig(logging) {
     return {
-        runtimeIdentity: { service: 'graph-engine' },
         diagnostics: {
             catalog: GRAPH_ENGINE_DIAGNOSTIC_CATALOG,
         },
         ...(logging ? { stack: logging } : {}),
     };
 }
+const GRAPH_ENGINE_LOG_METHODS = new Set([
+    'verbose',
+    'debug',
+    'info',
+    'warn',
+    'error',
+    'success',
+    'infoCode',
+    'warnCode',
+    'errorCode',
+    'errorFromCaught',
+    'diagnostic',
+]);
+/** Preserve downstream `runtimeIdentity.service` on proxied records; tag graph-engine wrapper separately. */
+function wrapGraphEngineLogxer(inner) {
+    return new Proxy(inner, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== 'function' || !GRAPH_ENGINE_LOG_METHODS.has(String(prop))) {
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+            return (...args) => {
+                if (args.length >= 2 && args[1] != null) {
+                    args[1] = normalizeGraphEngineLogMeta(args[1]);
+                }
+                return Reflect.apply(value, target, args);
+            };
+        },
+    });
+}
 /** Factory for a graph-engine Logxer instance (logxer 4.5+ stack pass-through). */
 export function createGraphEngineLogxer(options) {
-    return logxer.createLogxer({
+    const inner = logxer.createLogxer({
         packageName: EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME,
         envPrefix: GRAPH_ENGINE_LOGXER_ENV_PREFIX,
         debugNamespace: 'graph-engine',
     }, buildGraphEngineLogxerConfig(options?.logging));
+    return wrapGraphEngineLogxer(inner);
 }
 /** Default process logger (env / host registry). Lazily created without stack overrides. */
 export function getGraphEngineLogxer() {
@@ -127,11 +159,11 @@ export function traceExecutionMemory(scope, message, data) {
         process.env.DEBUG_OUTPUT_MAPPING !== 'true') {
         return;
     }
-    getGraphEngineLogxer().verbose(message, {
+    getGraphEngineLogxer().verbose(message, normalizeGraphEngineLogMeta({
         scope,
         ...data,
         debugKind: logxer.DebugLogAbstract.STATE,
-    });
+    }));
 }
 export function logGraphEngineErrorCode(code, _message, ctx) {
     const instance = getGraphEngineLogxer();
@@ -139,14 +171,14 @@ export function logGraphEngineErrorCode(code, _message, ctx) {
         ...(ctx.error != null ? [logxer.exceptionEvidence(ctx.error)] : []),
         ...Object.entries(ctx.evidence ?? {}).map(([path, value]) => logxer.fieldEvidence(path, value)),
     ];
-    instance.errorCode(code, {
+    instance.errorCode(code, normalizeGraphEngineLogMeta({
         graphId: ctx.graphId,
         nodeId: ctx.nodeId,
         jobId: ctx.jobId,
         taskId: ctx.taskId,
         debugKind: logxer.DebugLogAbstract.ANOMALY,
         ...(evidence.length ? { evidence } : {}),
-    });
+    }));
 }
 export const DebugLogAbstract = logxer.DebugLogAbstract;
 export const fieldEvidence = logxer.fieldEvidence;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "7.3.3",
+  "version": "7.3.9",
   "type": "module",
   "description": "Graph executor SDK",
   "main": "dist/src/index.js",
@@ -50,12 +50,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@exellix/ai-tasks": "^8.2.2",
-    "@x12i/activix": "8.3.1",
+    "@exellix/ai-tasks": "^8.2.3",
+    "@x12i/activix": "8.4.1",
     "@x12i/ai-profiles": "1.7.2",
     "@x12i/catalox": "5.1.3",
     "@x12i/env": "4.0.1",
-    "@x12i/funcx": "4.2.7",
+    "@x12i/funcx": "4.2.8",
     "@x12i/graphenix": "2.5.0",
     "@x12i/graphenix-format": "2.0.0",
     "@x12i/logxer": "^4.6.0",