@exellix/exellix-runtime 3.5.1

package/dist/execution-matrix/execution-matrix.spec.js

@@ -0,0 +1,1786 @@
+import { describe, expect, it, vi } from 'vitest';
+import { assertCanonicalGraphDocument, buildExellixGraphRuntimeObjects, EXELLIX_AI_TASKS_PACKAGE_NAME, EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME, mergeGraphDocumentModel, } from '@exellix/graph-engine';
+import { ExecutionMatrixCatalogValidationError, executionMatrixPayloadFromCatalogItem, graphCatalogPayloadFromCatalogItem, parseExecutionMatrixCatalogPayload, parseGraphCatalogPayload, } from './catalox-loader.js';
+import { buildMatrixMaterializeContext } from './catalox-matrix-host.js';
+import { MATRIX_FAILURE_PK, MATRIX_ROW_PK } from './constants.js';
+import { fetchExecutionMatrixMultiGraphOverview, fetchExecutionMatrixNavigatorPage, } from './navigator.js';
+import { createMatrixReadTierFromDataTier } from './matrix-read-tier.js';
+import { buildExecutionSeedFromGraphEntry, materializeExecutionMatrixRuntimeRows, mergeMappedInputEntries, resolveInputRowsWithResolver, sortGraphRecordsForMatrix, } from './materializer.js';
+import { MemoryMatrixCollection } from './memory-store.js';
+import { mergeClaimExtraFilter, mergeMatrixGraphExecuteOverrides, processMatrixGraphBatch, processNextMatrixClaim, sanitizeMatrixGraphExecuteOverrides, } from './orchestrator.js';
+import { buildExecutionMatrixRuntimeObjects } from './runtime-objects.js';
+import { buildFailureRecordsReadFilter, buildSnapshotsReadFilter, createExecutionMatrixRuntime, } from './runtime-store.js';
+import { normalizeExecutionMatrixStatus } from './status.js';
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Minimal injected-runtime graph result shape for orchestrator mocks (graph-engine 5.x `ExecuteGraphResult`). */
+function mockExecuteGraphSuccess(finalOutput = {}) {
+    return {
+        status: 'completed',
+        jobId: 'mock-job',
+        taskId: 'mock-task-id',
+        graphId: 'G',
+        outputsByNodeId: {},
+        engineSnapshot: {},
+        finalOutput,
+    };
+}
+function mockExecuteGraphFailed() {
+    return {
+        status: 'failed',
+        jobId: 'mock-job',
+        taskId: 'mock-task-fail',
+        graphId: 'G',
+        outputsByNodeId: {},
+        engineSnapshot: {},
+        errors: [{ nodeId: 'n1', error: 'boom' }],
+    };
+}
+function graphModelFor(graphId = 'G', graphEntry) {
+    return {
+        id: graphId,
+        response: { shape: { type: 'literal', value: {} } },
+        nodes: [],
+        ...(graphEntry ? { metadata: { graphEntry } } : {}),
+    };
+}
+function resolveGraphModelForTest({ graphId }) {
+    return graphModelFor(graphId);
+}
+describe('normalizeExecutionMatrixStatus', () => {
+    it('normalizes aliases', () => {
+        expect(normalizeExecutionMatrixStatus('not-strated')).toBe('not-started');
+        expect(normalizeExecutionMatrixStatus('NOT-STARTED')).toBe('not-started');
+    });
+});
+describe('parseExecutionMatrixCatalogPayload', () => {
+    it('accepts valid payload with graphs', () => {
+        const p = parseExecutionMatrixCatalogPayload({
+            input: { mode: 'batch' },
+            graphs: ['g.a', 'g.b'],
+        });
+        expect(p.graphs).toEqual(['g.a', 'g.b']);
+    });
+    it('rejects invalid payload', () => {
+        expect(() => parseExecutionMatrixCatalogPayload({})).toThrow(ExecutionMatrixCatalogValidationError);
+    });
+});
+describe('parseGraphCatalogPayload', () => {
+    it('accepts graph record', () => {
+        const g = parseGraphCatalogPayload({
+            graphId: 'my-graph',
+            mappedInput: [{ defaults: { x: 1 } }],
+            execution: {
+                priority: 5,
+                conditions: [{ conditionId: 'c1', condition: { op: 'eq' } }],
+                conditionRelations: 'c1',
+            },
+        });
+        expect(g.graphId).toBe('my-graph');
+        expect(g.execution.priority).toBe(5);
+        expect(g.execution.conditions).toHaveLength(1);
+    });
+});
+describe('buildMatrixMaterializeContext', () => {
+    it('pairs matrix item with graph items by graphId', () => {
+        const matrixItem = {
+            data: { input: {}, graphs: ['g.a'] },
+            metadata: { catalogType: 'execution-matrix' },
+        };
+        const graphItems = new Map([
+            [
+                'g.a',
+                {
+                    data: {
+                        graphId: 'g.a',
+                        mappedInput: [],
+                        execution: { priority: 1 },
+                    },
+                    metadata: { catalogType: 'graphs' },
+                },
+            ],
+        ]);
+        const { payload, graphRecords } = buildMatrixMaterializeContext(matrixItem, graphItems);
+        expect(payload.graphs).toEqual(['g.a']);
+        expect(graphRecords).toHaveLength(1);
+        expect(graphRecords[0].graphId).toBe('g.a');
+    });
+    it('throws when a referenced graph item is missing', () => {
+        const matrixItem = {
+            data: { input: {}, graphs: ['missing'] },
+            metadata: { catalogType: 'execution-matrix' },
+        };
+        expect(() => buildMatrixMaterializeContext(matrixItem, new Map())).toThrow(/missing graph catalog item/);
+    });
+});
+describe('executionMatrixPayloadFromCatalogItem', () => {
+    it('requires metadata marker', () => {
+        expect(() => executionMatrixPayloadFromCatalogItem({
+            data: { input: {}, graphs: ['x'] },
+            metadata: {},
+        })).toThrow(ExecutionMatrixCatalogValidationError);
+    });
+    it('loads when metadata.catalogType is set', () => {
+        const p = executionMatrixPayloadFromCatalogItem({
+            data: { input: {}, graphs: ['x'] },
+            metadata: { catalogType: 'execution-matrix' },
+        });
+        expect(p.graphs[0]).toBe('x');
+    });
+});
+describe('graphCatalogPayloadFromCatalogItem', () => {
+    it('requires graphs metadata', () => {
+        expect(() => graphCatalogPayloadFromCatalogItem({
+            data: { graphId: 'g', mappedInput: [{}], execution: { priority: 1 } },
+            metadata: { catalogType: 'execution-matrix' },
+        })).toThrow(ExecutionMatrixCatalogValidationError);
+    });
+    it('loads when metadata.catalogType is graphs', () => {
+        const g = graphCatalogPayloadFromCatalogItem({
+            data: {
+                graphId: 'g1',
+                mappedInput: [{ selector: { type: 'xmemory' } }],
+                execution: { priority: 2 },
+            },
+            metadata: { catalogType: 'graphs' },
+        });
+        expect(g.graphId).toBe('g1');
+        expect(g.execution.priority).toBe(2);
+    });
+});
+describe('materializer helpers', () => {
+    it('mergeMappedInputEntries merges in order', () => {
+        expect(mergeMappedInputEntries([{ a: 1 }, { b: 2 }, { a: 3 }])).toEqual({ a: 3, b: 2 });
+    });
+    it('sortGraphRecordsForMatrix orders by priority', () => {
+        const ordered = sortGraphRecordsForMatrix(['b', 'a'], [
+            { graphId: 'a', mappedInput: [], execution: { priority: 10 } },
+            { graphId: 'b', mappedInput: [], execution: { priority: 5 } },
+        ]);
+        expect(ordered.map((x) => x.graphId)).toEqual(['b', 'a']);
+    });
+});
+describe('materializer', () => {
+    it('builds execution seed from graphEntry paths', () => {
+        const graphEntry = {
+            inputs: [{ kind: 'record', path: 'input.raw', required: true }],
+        };
+        const seed = buildExecutionSeedFromGraphEntry(graphEntry, { raw: { a: 1 } });
+        expect(seed).toEqual({ input: { raw: { a: 1 } } });
+    });
+    it('maps nested Layer-01 paths using graph-engine path rules', () => {
+        const graphEntry = {
+            inputs: [{ kind: 'record', path: 'input.entity.meta.id', required: false }],
+        };
+        expect(buildExecutionSeedFromGraphEntry(graphEntry, { entity: { meta: { id: 'z' } } })).toEqual({
+            input: { entity: { meta: { id: 'z' } } },
+        });
+    });
+    it('materializes rows with stable ordering from graph priorities', () => {
+        const rows = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat-1',
+            matrixItemId: 'item-1',
+            matrixRunId: 'run-1',
+            payload: {
+                input: { template: true },
+                graphs: ['g2', 'g1'],
+            },
+            graphRecords: [
+                { graphId: 'g1', mappedInput: [{ tag: 'one' }], execution: { priority: 10 } },
+                { graphId: 'g2', mappedInput: [{ tag: 'two' }], execution: { priority: 20 } },
+            ],
+            inputRows: [{ entityId: 'e1' }, { entityId: 'e2' }],
+        });
+        expect(rows).toHaveLength(2);
+        expect(rows[0].materializationOrder).toBe(0);
+        expect(rows[0].execution.map((s) => s.graphId)).toEqual(['g1', 'g2']);
+        expect(rows[0].execution.every((s) => s.status === 'not-started')).toBe(true);
+        expect(rows[0].input).toMatchObject({
+            template: true,
+            entityId: 'e1',
+            mappedByGraph: {
+                g1: { tag: 'one' },
+                g2: { tag: 'two' },
+            },
+        });
+    });
+    it('merges runtimeScope onto input after row keys (scope wins collisions)', () => {
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: { input: { base: 1 }, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{ entityId: 'e1', tenantId: 'from-row' }],
+            runtimeScope: { tenantId: 'from-scope' },
+        });
+        expect(row.input.tenantId).toBe('from-scope');
+        expect(row.input.entityId).toBe('e1');
+    });
+});
+describe('fetchExecutionMatrixMultiGraphOverview', () => {
+    it('returns one slot per graph with stable ordering by priority', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['gLow', 'gHigh'] },
+            graphRecords: [
+                { graphId: 'gLow', mappedInput: [], execution: { priority: 5 } },
+                { graphId: 'gHigh', mappedInput: [], execution: { priority: 100 } },
+            ],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        await rt.claimNext({ matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'gLow' });
+        await rt.markCompleted(row.matrixRowId, 'gLow', { graphId: 'gLow', knowledge: { ok: 1 } });
+        const overview = await fetchExecutionMatrixMultiGraphOverview(rt, {
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+        });
+        expect(overview).toHaveLength(1);
+        expect(overview[0].slots.map((s) => s.graphId)).toEqual(['gLow', 'gHigh']);
+        expect(overview[0].slots[0].status).toBe('completed');
+        expect(overview[0].slots[0].inference?.knowledge).toEqual({ ok: 1 });
+        expect(overview[0].slots[1].status).toBe('not-started');
+    });
+});
+describe('mergeClaimExtraFilter', () => {
+    it('lets runtimeScope override claim extraFilter keys', () => {
+        expect(mergeClaimExtraFilter({ 'input.shard': 's1', 'input.tenantId': 'x' }, { 'input.tenantId': 't1' })).toEqual({
+            'input.shard': 's1',
+            'input.tenantId': 't1',
+        });
+    });
+});
+describe('resolveInputRowsWithResolver', () => {
+    it('forwards runtimeScope to the resolver', async () => {
+        const resolver = vi.fn().mockResolvedValue([{ ok: true }]);
+        await resolveInputRowsWithResolver({ q: 1 }, resolver, { tenantId: 'acme' });
+        expect(resolver).toHaveBeenCalledWith({ q: 1 }, { tenantId: 'acme' });
+    });
+});
+describe('ExecutionMatrixRuntime (memory)', () => {
+    it('claims next by materializationOrder and completes', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const r1 = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{ n: 'first' }, { n: 'second' }],
+        });
+        await rt.insertRuntimeRow(r1[1]);
+        await rt.insertRuntimeRow(r1[0]);
+        const c1 = await rt.claimNext({ matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' });
+        expect(c1.ok).toBe(true);
+        if (!c1.ok)
+            throw new Error('claim');
+        expect(c1.record.input.n).toBe('first');
+        await rt.markCompleted(c1.record.matrixRowId, 'G', { graphId: 'G', knowledge: { ok: true } });
+        const counts = await rt.getStatusCounts('cat', 'G', 'r1');
+        expect(counts.completed).toBe(1);
+        expect(counts['not-started']).toBe(1);
+        const page = await fetchExecutionMatrixNavigatorPage(rt, {
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphId: 'G',
+            limit: 10,
+            includeFailureCount: true,
+        });
+        expect(page.rows).toHaveLength(2);
+        expect(page.statusCounts?.completed).toBe(1);
+        expect(page.failureCount).toBe(0);
+    });
+    it('countFailureRecords counts failures (memory)', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const template = {
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+        };
+        const [rowA] = materializeExecutionMatrixRuntimeRows({ ...template, inputRows: [{}] });
+        const [rowB] = materializeExecutionMatrixRuntimeRows({
+            ...template,
+            matrixItemId: 'item2',
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(rowA);
+        await rt.insertRuntimeRow(rowB);
+        await rt.claimNext({ matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' });
+        await rt.markFailed(rowA.matrixRowId, 'G', 'e1');
+        await new Promise((r) => setTimeout(r, 15));
+        await rt.claimNext({ matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' });
+        await rt.markFailed(rowB.matrixRowId, 'G', 'e2');
+        expect(await rt.countFailureRecords({ matrixCatalogId: 'cat', matrixRunId: 'r1' })).toBe(2);
+        expect(await rt.countFailureRecords({ matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' })).toBe(2);
+        const listed = await rt.listFailureRecords({ matrixCatalogId: 'cat', matrixRunId: 'r1' }, 50_000);
+        expect(listed).toHaveLength(2);
+        expect(listed[0].reason).toBe('e2');
+        expect(listed[1].reason).toBe('e1');
+        const one = await rt.getFailureRecord(listed[0].failureId);
+        expect(one?.reason).toBe('e2');
+        const latest = await rt.getLatestFailureRecordForRowGraph(rowB.matrixRowId, 'G');
+        expect(latest?.failureId).toBe(listed[0].failureId);
+    });
+    it('listFailureRecords respects createdAt bounds (memory)', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        await fails.insert({
+            failureId: 'f_old',
+            matrixRowId: 'r1',
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            graphId: 'G',
+            reason: 'old',
+            createdAt: '2024-01-01T00:00:00.000Z',
+        });
+        await fails.insert({
+            failureId: 'f_new',
+            matrixRowId: 'r2',
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            graphId: 'G',
+            reason: 'new',
+            createdAt: '2025-06-01T00:00:00.000Z',
+        });
+        const mid = await rt.listFailureRecords({
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            createdAtMin: '2025-01-01T00:00:00.000Z',
+            createdAtMax: '2025-12-31T00:00:00.000Z',
+        });
+        expect(mid.map((f) => f.failureId)).toEqual(['f_new']);
+    });
+    it('buildFailureRecordsReadFilter maps optional bounds and matrixRowId', () => {
+        expect(buildFailureRecordsReadFilter({ matrixCatalogId: 'cat' })).toEqual({
+            matrixCatalogId: 'cat',
+        });
+        expect(buildFailureRecordsReadFilter({
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphId: 'G',
+            matrixRowId: 'row-1',
+            createdAtMin: '2024-01-01T00:00:00.000Z',
+            createdAtMax: '2025-01-01T00:00:00.000Z',
+        })).toEqual({
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphId: 'G',
+            matrixRowId: 'row-1',
+            createdAt: {
+                $gte: '2024-01-01T00:00:00.000Z',
+                $lte: '2025-01-01T00:00:00.000Z',
+            },
+        });
+    });
+    it('MatrixReadTier delegates failure audit reads to runtime', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const matrices = new MemoryMatrixCollection('matrixCatalogId');
+        const graphs = new MemoryMatrixCollection('graphId');
+        const snapshots = new MemoryMatrixCollection('snapshotId');
+        const tier = await createMatrixReadTierFromDataTier({
+            rows: rows.asCollection(),
+            failures: fails.asCollection(),
+            snapshots: snapshots.asCollection(),
+            matrices: matrices.asCollection(),
+            graphs: graphs.asCollection(),
+            close: async () => undefined,
+        });
+        await fails.insert({
+            failureId: 'f_tier',
+            matrixRowId: 'row-tier',
+            matrixCatalogId: 'cat-tier',
+            matrixItemId: 'item',
+            matrixRunId: 'r-tier',
+            graphId: 'G',
+            reason: 'tier-delegate',
+            createdAt: '2025-06-01T00:00:00.000Z',
+        });
+        const listed = await tier.listFailureRecords({ matrixCatalogId: 'cat-tier', limit: 10 });
+        expect(listed).toHaveLength(1);
+        expect(listed[0].reason).toBe('tier-delegate');
+        const one = await tier.getFailureRecord('f_tier');
+        expect(one?.failureId).toBe('f_tier');
+        const latest = await tier.getLatestFailureRecordForRowGraph('row-tier', 'G', {
+            matrixCatalogId: 'cat-tier',
+        });
+        expect(latest?.failureId).toBe('f_tier');
+    });
+    it('markFailed writes failure side-channel', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        await rt.claimNext({ matrixCatalogId: 'cat', graphId: 'G' });
+        await rt.markFailed(row.matrixRowId, 'G', 'boom');
+        const listed = await fails.readMany({}, { limit: 10 });
+        expect(listed.length).toBe(1);
+        expect(listed[0].reason).toBe('boom');
+    });
+});
+describe('buildExecutionMatrixRuntimeObjects', () => {
+    it('composes matrix root clients and preserves graph-engine package row first', () => {
+        const graphActivix = { getJobActivities: vi.fn() };
+        const graphLogxer = { getJobLogs: vi.fn() };
+        const graphRo = buildExellixGraphRuntimeObjects({
+            graphActivixClient: graphActivix,
+            graphLogxerClient: graphLogxer,
+        });
+        const matrixActivix = { getJobActivities: vi.fn() };
+        const matrixLogxer = { getJobLogs: vi.fn() };
+        const composed = buildExecutionMatrixRuntimeObjects({
+            matrixActivixClient: matrixActivix,
+            matrixLogxerClient: matrixLogxer,
+            graphRuntimeObjects: graphRo,
+        });
+        expect(composed.activixClient).toBe(matrixActivix);
+        expect(composed.logxerClient).toBe(matrixLogxer);
+        expect(composed.packagesRuntimeObjects[0]).toEqual({
+            name: EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME,
+            activixClient: graphActivix,
+            logxerClient: graphLogxer,
+        });
+        expect(composed.packagesRuntimeObjects[1]?.name).toBe(EXELLIX_AI_TASKS_PACKAGE_NAME);
+    });
+});
+describe('orchestrator batch', () => {
+    it('processMatrixGraphBatch with limit 1 invokes executeGraph once', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess({ done: true }));
+        const externalJobId = 'job_external_1';
+        const out = await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+        }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1, jobId: externalJobId });
+        expect(executeGraph).toHaveBeenCalledTimes(1);
+        expect(out).toHaveLength(1);
+        expect(out[0]).toMatchObject({ ok: true, jobId: externalJobId });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.model.id).toBe('G');
+        expect(call.runtime.jobId).toBe(externalJobId);
+        expect(call.runtime.job).toEqual({
+            id: externalJobId,
+            jobId: externalJobId,
+            agentId: 'exellix-runtime',
+            jobTypeId: 'execution-matrix-graph-run',
+            matrixRowId: row.matrixRowId,
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphId: 'G',
+        });
+        const after = await rt.getRecord(row.matrixRowId);
+        expect(after?.execution.find((e) => e.graphId === 'G')?.jobId).toBe(externalJobId);
+    });
+    it('forwards runtimeObjects to executeGraph and sets lastJobId on the composed root', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess({ done: true }));
+        const runtimeObjects = buildExellixGraphRuntimeObjects({});
+        const externalJobId = 'job_external_2';
+        await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+            runtimeObjects,
+        }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1, jobId: externalJobId });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.runtimeObjects).toBe(runtimeObjects);
+        expect(runtimeObjects.lastJobId).toBe(externalJobId);
+    });
+    it('processNextMatrixClaim still works for a fixed graphId', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        const externalJobId = 'job_external_3';
+        const res = await processNextMatrixClaim({ runtime: rt, executeGraph, graphModel: graphModelFor('G', { inputs: [] }) }, { matrixCatalogId: 'cat', graphId: 'G', jobId: externalJobId });
+        expect(res).toMatchObject({ ok: true, jobId: externalJobId });
+        expect(executeGraph).toHaveBeenCalled();
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.jobId).toBe(externalJobId);
+    });
+    it('processNextMatrixClaim merges deps.runtimeScope into claimNext extraFilter', async () => {
+        const claimNext = vi.fn().mockResolvedValue({ ok: false, reason: 'no_eligible_row' });
+        const rt = { claimNext };
+        await processNextMatrixClaim({
+            runtime: rt,
+            executeGraph: vi.fn(),
+            resolveGraphModel: resolveGraphModelForTest,
+            runtimeScope: { 'input.tenantId': 't1' },
+        }, { matrixCatalogId: 'c', graphId: 'g', extraFilter: { 'input.shard': 's1' } });
+        expect(claimNext).toHaveBeenCalledWith(expect.objectContaining({
+            extraFilter: { 'input.shard': 's1', 'input.tenantId': 't1' },
+        }));
+    });
+    it('autonomous mode generates a stable jobId when none is provided', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        const out = await processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1 });
+        expect(out[0]).toMatchObject({ ok: true, jobId: expect.stringMatching(/^matrix:/) });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.jobId).toMatch(/^matrix:/);
+    });
+    it('processMatrixGraphBatch: shouldClaimNext false exits before the next claim (in-flight run finishes first)', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const two = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{ sourceId: 'sa' }, { sourceId: 'sb' }],
+        });
+        expect(two).toHaveLength(2);
+        for (const r of two)
+            await rt.insertRuntimeRow(r);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        const gate = vi.fn().mockReturnValueOnce(true).mockReturnValueOnce(true).mockReturnValue(false);
+        const out = await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+            shouldClaimNext: () => gate(),
+        }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 10 });
+        expect(out).toHaveLength(2);
+        expect(out.every((o) => 'jobId' in o && o.ok === true)).toBe(true);
+        expect(executeGraph).toHaveBeenCalledTimes(2);
+        expect(gate).toHaveBeenCalledTimes(3);
+        const gateOff = vi.fn().mockReturnValue(false);
+        const outB = await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+            shouldClaimNext: () => gateOff(),
+        }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 10 });
+        expect(outB).toHaveLength(0);
+        expect(executeGraph).toHaveBeenCalledTimes(2);
+    });
+    it('runtime debugMode is forwarded on the single executeGraph input when jobId is provided', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1, jobId: 'job_rt_1', debugMode: true });
+        expect(executeGraph).toHaveBeenCalledTimes(1);
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.jobId).toBe('job_rt_1');
+        expect(call.runtime.debugMode).toBe(true);
+    });
+    it('debugMode is omitted from executeGraph input when not requested', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1, jobId: 'job_no_debug' });
+        const call = executeGraph.mock.calls[0][0];
+        expect('debugMode' in call.runtime).toBe(false);
+    });
+    it('debugMode without jobId throws (autonomous mode)', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const executeGraph = vi.fn();
+        await expect(processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1, debugMode: true })).rejects.toThrow(/debugMode requires jobId/i);
+    });
+    it('jobId in batch requires limit === 1', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const executeGraph = vi.fn();
+        await expect(processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 2, jobId: 'job_rt_2' })).rejects.toThrow(/limit === 1/i);
+    });
+});
+function matrixRuntimeModelConfig(xynth, skill) {
+    return {
+        cases: [{ modelConfig: { xynthesisModel: xynth, skillModel: skill } }],
+    };
+}
+describe('mergeMatrixGraphExecuteOverrides', () => {
+    it('returns undefined when neither side is set', () => {
+        expect(mergeMatrixGraphExecuteOverrides(undefined, undefined)).toBeUndefined();
+        expect(mergeMatrixGraphExecuteOverrides({}, {})).toBeUndefined();
+    });
+    it('returns deps-level only when per-call is absent', () => {
+        expect(mergeMatrixGraphExecuteOverrides({ modelConfig: matrixRuntimeModelConfig('xynth-a', 'skill-a') }, undefined)).toEqual({ modelConfig: matrixRuntimeModelConfig('xynth-a', 'skill-a') });
+    });
+    it('returns per-call only when deps is absent', () => {
+        expect(mergeMatrixGraphExecuteOverrides(undefined, {
+            modelConfig: matrixRuntimeModelConfig('xynth-override', 'skill-override'),
+        })).toEqual({
+            modelConfig: matrixRuntimeModelConfig('xynth-override', 'skill-override'),
+        });
+    });
+    it('shallow-merges object fields per key (per-call wins on collisions)', () => {
+        expect(mergeMatrixGraphExecuteOverrides({
+            modelConfig: matrixRuntimeModelConfig('xynth-a', 'skill-a'),
+            aliasConfig: { 'xynth-a': 'openrouter/xynth-a' },
+            llmCall: { topP: 0.9 },
+        }, {
+            modelConfig: matrixRuntimeModelConfig('xynth-b', 'skill-b'),
+            aliasConfig: { 'skill-b': 'openrouter/skill-b' },
+            llmCall: { topP: 0.5, maxTokensCap: 1024 },
+        })).toEqual({
+            modelConfig: matrixRuntimeModelConfig('xynth-b', 'skill-b'),
+            aliasConfig: { 'xynth-a': 'openrouter/xynth-a', 'skill-b': 'openrouter/skill-b' },
+            llmCall: { topP: 0.5, maxTokensCap: 1024 },
+        });
+    });
+    it('shallow-merges node runtime overrides by node id', () => {
+        expect(mergeMatrixGraphExecuteOverrides({
+            nodes: {
+                n1: {
+                    modelConfig: { xynthesisModel: 'xynth-a', skillModel: 'skill-a' },
+                    aliasConfig: { a: 'model-a' },
+                },
+            },
+        }, {
+            nodes: {
+                n1: {
+                    modelConfig: { xynthesisModel: 'xynth-b', skillModel: 'skill-b' },
+                    aliasConfig: { b: 'model-b' },
+                },
+                n2: { aliasConfig: { c: 'model-c' } },
+            },
+        })).toEqual({
+            nodes: {
+                n1: {
+                    modelConfig: { xynthesisModel: 'xynth-b', skillModel: 'skill-b' },
+                    aliasConfig: { a: 'model-a', b: 'model-b' },
+                },
+                n2: { aliasConfig: { c: 'model-c' } },
+            },
+        });
+    });
+    it('replaces scalar fields (per-call wins; otherwise deps)', () => {
+        expect(mergeMatrixGraphExecuteOverrides({ runLogMode: 'summary', maxRunLogEntries: 100 }, { runLogMode: 'full' })).toEqual({ runLogMode: 'full', maxRunLogEntries: 100 });
+    });
+    it('replaces runtime memory/output blobs (per-call wins; otherwise deps)', () => {
+        expect(mergeMatrixGraphExecuteOverrides({
+            jobMemory: { deps: true },
+            taskMemory: { deps: true },
+            outputsMemory: { answer: { deps: true } },
+        }, {
+            outputsMemory: { answer: { call: true } },
+        })).toEqual({
+            jobMemory: { deps: true },
+            taskMemory: { deps: true },
+            outputsMemory: { answer: { call: true } },
+        });
+    });
+    it('replaces stepRetryPolicy (per-call wins whole object; aligns with graph-engine HostExecuteGraphRunOptions)', () => {
+        expect(mergeMatrixGraphExecuteOverrides({ stepRetryPolicy: { maxAttempts: 5, retryOnTimeout: false } }, { stepRetryPolicy: { maxAttempts: 2 } })).toEqual({ stepRetryPolicy: { maxAttempts: 2 } });
+        expect(mergeMatrixGraphExecuteOverrides({ stepRetryPolicy: { maxAttempts: 4 } }, undefined)).toEqual({ stepRetryPolicy: { maxAttempts: 4 } });
+    });
+});
+describe('orchestrator executeOverrides', () => {
+    function setupSingleRow() {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        return { rt, row: row };
+    }
+    it('forwards per-call modelConfig to executeGraph (FR acceptance)', async () => {
+        const { rt, row } = setupSingleRow();
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        const out = await processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, {
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphIds: ['G'],
+            limit: 1,
+            executeOverrides: { modelConfig: matrixRuntimeModelConfig('test-xynth', 'test-skill') },
+        });
+        expect(out).toHaveLength(1);
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.modelConfig).toEqual(matrixRuntimeModelConfig('test-xynth', 'test-skill'));
+    });
+    it('uses deps-level executeOverrides when per-call is omitted', async () => {
+        const { rt, row } = setupSingleRow();
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+            executeOverrides: { modelConfig: matrixRuntimeModelConfig('xynth-a', 'skill-a'), runLogMode: 'full' },
+        }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1 });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.modelConfig).toEqual(matrixRuntimeModelConfig('xynth-a', 'skill-a'));
+        expect(call.runtime.runLogMode).toBe('full');
+    });
+    it('shallow-merges per-call over deps (per-call wins on collisions)', async () => {
+        const { rt, row } = setupSingleRow();
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+            executeOverrides: { modelConfig: matrixRuntimeModelConfig('xynth-a', 'skill-a') },
+        }, {
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphIds: ['G'],
+            limit: 1,
+            executeOverrides: { modelConfig: matrixRuntimeModelConfig('xynth-b', 'skill-b') },
+        });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.modelConfig).toEqual(matrixRuntimeModelConfig('xynth-b', 'skill-b'));
+    });
+    it('omits runtime override fields when neither side is set', async () => {
+        const { rt, row } = setupSingleRow();
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1 });
+        const call = executeGraph.mock.calls[0][0];
+        /** Keys introduced only via merged `executeOverrides` — not matrix-owned runtime fields from orchestrator. */
+        const noOverridesExpected = [
+            'failFast',
+            'skillKeyResolution',
+            'nodeTimeoutMs',
+            'executionPipeline',
+            'playgroundMeta',
+            'clearSynthesizedContextPerNode',
+            'modelConfig',
+            'aliasConfig',
+            'nodes',
+            'llmCall',
+            'runTaskIdentity',
+            'runTaskExecutionMode',
+            'runLogMode',
+            'maxRunLogEntries',
+            'maxRunLogDataJsonChars',
+            'runTaskDiagnostics',
+            'mode',
+            'goalNodeId',
+            'dimension',
+            'jobMemory',
+            'taskMemory',
+            'outputsMemory',
+            'variables',
+            'initialState',
+            'initialVariables',
+            'runtimeObjects',
+            'playgroundReporter',
+            'eventEmitter',
+            'stepRetryPolicy',
+        ];
+        for (const k of noOverridesExpected) {
+            expect(k in call.runtime).toBe(false);
+        }
+    });
+    it('forwards outputsMemory overrides to graph-engine runtime', async () => {
+        const { rt, row } = setupSingleRow();
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, {
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphIds: ['G'],
+            limit: 1,
+            executeOverrides: { outputsMemory: { seeded: { value: 1 } } },
+        });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.outputsMemory).toEqual({ seeded: { value: 1 } });
+    });
+    it('debugMode receives merged overrides on the same single executor', async () => {
+        const { rt, row } = setupSingleRow();
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+            executeOverrides: { modelConfig: matrixRuntimeModelConfig('xynth-a', 'skill-a') },
+        }, {
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphIds: ['G'],
+            limit: 1,
+            jobId: 'job_rt_dbg',
+            debugMode: true,
+            executeOverrides: {
+                modelConfig: matrixRuntimeModelConfig('xynth-b', 'skill-b'),
+                runTaskExecutionMode: 'trace',
+            },
+        });
+        expect(executeGraph).toHaveBeenCalledTimes(1);
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.jobId).toBe('job_rt_dbg');
+        expect(call.runtime.debugMode).toBe(true);
+        expect(call.runtime.modelConfig).toEqual(matrixRuntimeModelConfig('xynth-b', 'skill-b'));
+        expect(call.runtime.runTaskExecutionMode).toBe('trace');
+    });
+    it('processNextMatrixClaim forwards executeOverrides per-call', async () => {
+        const { rt, row } = setupSingleRow();
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processNextMatrixClaim({ runtime: rt, executeGraph, graphModel: graphModelFor('G', { inputs: [] }) }, {
+            matrixCatalogId: 'cat',
+            graphId: 'G',
+            executeOverrides: { llmCall: { maxTokensCap: 2048 }, runLogMode: 'full' },
+        });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.llmCall).toEqual({ maxTokensCap: 2048 });
+        expect(call.runtime.runLogMode).toBe('full');
+    });
+});
+describe('sanitizeMatrixGraphExecuteOverrides', () => {
+    it('strips job correlation keys after merge', () => {
+        const dirty = {
+            modelConfig: matrixRuntimeModelConfig('xynth-base', 'skill-base'),
+            jobId: 'evil',
+            graphId: 'evil-g',
+            job: { x: 1 },
+            input: { x: 1 },
+            executionMemory: { input: { x: 1 } },
+        };
+        expect(sanitizeMatrixGraphExecuteOverrides(dirty)).toEqual({
+            modelConfig: matrixRuntimeModelConfig('xynth-base', 'skill-base'),
+        });
+    });
+});
+describe('matrix boundaries (integration-style)', () => {
+    const executionMatrixSrcRoot = fileURLToPath(new URL('.', import.meta.url));
+    function listExecutionMatrixTsFiles(dir) {
+        const out = [];
+        for (const ent of readdirSync(dir, { withFileTypes: true })) {
+            const p = join(dir, ent.name);
+            if (ent.isDirectory())
+                out.push(...listExecutionMatrixTsFiles(p));
+            else if (ent.name.endsWith('.ts') && !ent.name.endsWith('.spec.ts'))
+                out.push(p);
+        }
+        return out;
+    }
+    it('runtime modules do not import @exellix/ai-tasks directly (graph-engine owns ai-tasks)', () => {
+        for (const f of listExecutionMatrixTsFiles(executionMatrixSrcRoot)) {
+            if (basename(f) === 'index.ts')
+                continue;
+            const text = readFileSync(f, 'utf8');
+            expect(text, basename(f)).not.toMatch(/from ['"]@exellix\/ai-tasks['"]/);
+        }
+    });
+    it('malicious executeOverrides cannot override jobId, job, or graphId on the executor call', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+            executeOverrides: {
+                jobId: 'evil-job',
+                graphId: 'evil-graph',
+                job: { injected: true },
+                input: { injected: true },
+                executionMemory: { injected: true },
+                variables: { only: 'allowed' },
+            },
+        }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1 });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.model.id).toBe('G');
+        expect(call.runtime.jobId).toMatch(/^matrix:/);
+        expect(call.runtime.job).toEqual({
+            id: call.runtime.jobId,
+            jobId: call.runtime.jobId,
+            agentId: 'exellix-runtime',
+            jobTypeId: 'execution-matrix-graph-run',
+            matrixRowId: row.matrixRowId,
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphId: 'G',
+        });
+        expect(call.runtime.input).toEqual(row.input);
+        expect(call.runtime.executionMemory).toEqual({});
+        expect(call.runtime.variables).toEqual({ only: 'allowed' });
+    });
+    it('persists graph-engine taskId on graph failure records', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphFailed());
+        await processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1 });
+        const audit = await fails.readMany({}, { limit: 5 });
+        expect(audit).toHaveLength(1);
+        expect(audit[0].taskId).toBe('mock-task-fail');
+        expect(audit[0].graphId).toBe('G');
+        expect(audit[0].matrixRunId).toBe('r1');
+        expect(typeof audit[0].jobId).toBe('string');
+    });
+    it('stores finalOutput as inference knowledge on success', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess({ verdict: 'ok' }));
+        await processMatrixGraphBatch({ runtime: rt, executeGraph, resolveGraphModel: resolveGraphModelForTest, resolveGraphEntry: () => ({ inputs: [] }) }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1 });
+        const after = await rt.getRecord(row.matrixRowId);
+        expect(after?.inferences).toHaveLength(1);
+        expect(after?.inferences[0].knowledge).toEqual({ verdict: 'ok' });
+        expect(after?.inferences[0].graphId).toBe('G');
+    });
+    it('passes matrix row input into executeGraph execution seed via graphEntry paths', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), { serializeClaims: true });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{ raw: { blob: 9 } }],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({
+                inputs: [{ kind: 'record', path: 'input.raw', required: true }],
+            }),
+        }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphIds: ['G'], limit: 1 });
+        const call = executeGraph.mock.calls[0][0];
+        expect(call.runtime.executionMemory.input.raw).toEqual({ blob: 9 });
+    });
+});
+/* ============================================================================
+ * New surface coverage: data sources, run loop, snapshots, eligibility, config CRUD.
+ * ==========================================================================*/
+describe('parseExecutionMatrixCatalogPayload (extended)', () => {
+    it('accepts a record dataSource with executionMode and eligibility', () => {
+        const p = parseExecutionMatrixCatalogPayload({
+            input: {},
+            graphs: ['g.a'],
+            dataSource: {
+                kind: 'record',
+                collectionRef: 'col.records',
+                recordsPerRun: 5,
+                pollWhenEmptySeconds: 60,
+                eligibility: { fromStatuses: ['not-started'], excludeStatuses: ['in-progress'] },
+            },
+            executionMode: { mode: 'continuous' },
+        });
+        expect(p.dataSource).toMatchObject({ kind: 'record', recordsPerRun: 5 });
+        expect(p.executionMode).toEqual({ mode: 'continuous' });
+    });
+    it('accepts a query-snapshot dataSource with transform', () => {
+        const p = parseExecutionMatrixCatalogPayload({
+            input: {},
+            graphs: ['g.a'],
+            dataSource: {
+                kind: 'query-snapshot',
+                collectionRef: 'col.q',
+                transform: { language: 'js', source: 'return records.length', version: 'v1', timeoutMs: 500 },
+                materialize: 'one-row',
+                pollWhenEmptySeconds: 3600,
+            },
+        });
+        expect(p.dataSource).toMatchObject({ kind: 'query-snapshot' });
+    });
+    it('rejects invalid recordsPerRun', async () => {
+        expect(() => parseExecutionMatrixCatalogPayload({
+            input: {},
+            graphs: ['g.a'],
+            dataSource: { kind: 'record', collectionRef: 'col.r', recordsPerRun: 0 },
+        })).toThrow(ExecutionMatrixCatalogValidationError);
+        expect(() => parseExecutionMatrixCatalogPayload({
+            input: {},
+            graphs: ['g.a'],
+            dataSource: { kind: 'record', collectionRef: 'col.r', recordsPerRun: 99999 },
+        })).toThrow(ExecutionMatrixCatalogValidationError);
+    });
+    it('rejects transform without source or version', () => {
+        expect(() => parseExecutionMatrixCatalogPayload({
+            input: {},
+            graphs: ['g.a'],
+            dataSource: {
+                kind: 'query-snapshot',
+                collectionRef: 'q',
+                transform: { language: 'js', source: '', version: 'v1' },
+            },
+        })).toThrow(ExecutionMatrixCatalogValidationError);
+        expect(() => parseExecutionMatrixCatalogPayload({
+            input: {},
+            graphs: ['g.a'],
+            dataSource: {
+                kind: 'query-snapshot',
+                collectionRef: 'q',
+                transform: { language: 'js', source: 'return 1', version: '' },
+            },
+        })).toThrow(ExecutionMatrixCatalogValidationError);
+    });
+    it('warns about unusual pollWhenEmptySeconds', async () => {
+        const { parseExecutionMatrixCatalogPayloadWithWarnings } = await import('./catalox-loader.js');
+        const r = parseExecutionMatrixCatalogPayloadWithWarnings({
+            input: {},
+            graphs: ['g.a'],
+            dataSource: {
+                kind: 'query-snapshot',
+                collectionRef: 'q',
+                transform: { language: 'js', source: 'return 1', version: 'v1' },
+                pollWhenEmptySeconds: 5,
+            },
+        });
+        expect(r.warnings.length).toBeGreaterThan(0);
+        expect(r.warnings[0]).toMatch(/unusually short/);
+    });
+    it('rejects executionMode unknown value', () => {
+        expect(() => parseExecutionMatrixCatalogPayload({
+            input: {},
+            graphs: ['g.a'],
+            executionMode: 'forever',
+        })).toThrow(ExecutionMatrixCatalogValidationError);
+    });
+});
+describe('eligibilityToClaim', () => {
+    it('defaults to fromStatuses=["not-started"]', async () => {
+        const { eligibilityToClaim } = await import('./eligibility.js');
+        expect(eligibilityToClaim(undefined).fromStatuses).toEqual(['not-started']);
+    });
+    it('subtracts excludeStatuses and merges extraFilter', async () => {
+        const { eligibilityToClaim } = await import('./eligibility.js');
+        const r = eligibilityToClaim({
+            fromStatuses: ['not-started', 'failed'],
+            excludeStatuses: ['failed'],
+            extraFilter: { 'input.tier': 'A' },
+        });
+        expect(r.fromStatuses).toEqual(['not-started']);
+        expect(r.extraFilter).toEqual({ 'input.tier': 'A' });
+    });
+    it('emits ageMinMinutes and modelProfileNotIn clauses', async () => {
+        const { eligibilityToClaim } = await import('./eligibility.js');
+        const fixed = new Date('2026-05-08T00:00:00Z');
+        const r = eligibilityToClaim({ ageMinMinutes: 30, modelProfileNotIn: ['gpt-4o-mini'] }, fixed);
+        expect(r.extraFilter?.['execution.lastAttempt.endedAt.$lte']).toBe('2026-05-07T23:30:00.000Z');
+        expect(r.extraFilter?.['execution.lastAttempt.modelProfile.$nin']).toEqual(['gpt-4o-mini']);
+    });
+});
+describe('chunkInputRowsForBatch + materializeBatchedRecordRows', () => {
+    it('bundles inputs by recordsPerRun and lifts sourceIds when present', async () => {
+        const { chunkInputRowsForBatch, materializeBatchedRecordRows } = await import('./materializer.js');
+        const chunks = chunkInputRowsForBatch([{ sourceId: 'a' }, { sourceId: 'b' }, { sourceId: 'c' }], 2);
+        expect(chunks).toHaveLength(2);
+        expect(chunks[0].records).toHaveLength(2);
+        expect(chunks[0].sourceIds).toEqual(['a', 'b']);
+        expect(chunks[1].sourceIds).toEqual(['c']);
+        const rows = materializeBatchedRecordRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{ sourceId: 'a' }, { sourceId: 'b' }, { sourceId: 'c' }],
+            recordsPerRun: 2,
+        });
+        expect(rows).toHaveLength(2);
+        expect(rows[0].input.records).toHaveLength(2);
+        expect(rows[0].input.sourceIds).toEqual(['a', 'b']);
+    });
+    it('falls back to one-row-per-input when recordsPerRun <= 1', async () => {
+        const { materializeBatchedRecordRows } = await import('./materializer.js');
+        const rows = materializeBatchedRecordRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{ x: 1 }, { x: 2 }],
+            recordsPerRun: 1,
+        });
+        expect(rows).toHaveLength(2);
+        expect(rows[0].input.x).toBe(1);
+    });
+});
+describe('snapshot runner', () => {
+    it('runs a JS transform and returns a payload', async () => {
+        const { runSnapshotTransform } = await import('./snapshot-runner.js');
+        const r = runSnapshotTransform({ language: 'js', source: 'return records.length', version: 'v1' }, { records: [{}, {}, {}] });
+        expect(r.payload).toBe(3);
+        expect(r.transformVersion).toBe('v1');
+    });
+    it('honors timeoutMs', async () => {
+        const { runSnapshotTransform } = await import('./snapshot-runner.js');
+        expect(() => runSnapshotTransform({
+            language: 'js',
+            source: 'while (true) { /* spin */ }',
+            version: 'v1',
+            timeoutMs: 50,
+        }, { records: [] })).toThrow(/execution failed/);
+    });
+    it('does not expose require / process', async () => {
+        const { runSnapshotTransform } = await import('./snapshot-runner.js');
+        const r = runSnapshotTransform({
+            language: 'js',
+            source: 'return typeof require + ":" + typeof process',
+            version: 'v1',
+        }, { records: [] });
+        expect(r.payload).toBe('undefined:undefined');
+    });
+    it('builds a snapshot record with stable hash', async () => {
+        const { buildSnapshotRecord, buildSourceQueryHash } = await import('./snapshot-runner.js');
+        const rec = buildSnapshotRecord({
+            matrixCatalogId: 'cat',
+            sourceIds: ['x', 'y'],
+            transformResult: { payload: [1, 2], transformVersion: 'v1' },
+        });
+        expect(rec.matrixCatalogId).toBe('cat');
+        expect(rec.payload).toEqual([1, 2]);
+        expect(rec.sourceQueryHash).toBe(buildSourceQueryHash(undefined, ['x', 'y']));
+    });
+});
+describe('per-status helpers + fetchSourceJoinView', () => {
+    async function setupRowsWithMixedStatus() {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        const tpl = {
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+        };
+        const [a] = materializeExecutionMatrixRuntimeRows({ ...tpl, inputRows: [{ sourceId: 'a' }] });
+        const [b] = materializeExecutionMatrixRuntimeRows({ ...tpl, matrixItemId: 'i2', inputRows: [{ sourceId: 'b' }] });
+        const [c] = materializeExecutionMatrixRuntimeRows({ ...tpl, matrixItemId: 'i3', inputRows: [{ sourceId: 'c' }] });
+        await rt.insertRuntimeRow(a);
+        await rt.insertRuntimeRow(b);
+        await rt.insertRuntimeRow(c);
+        const claim = await rt.claimNext({ matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' });
+        if (!claim.ok)
+            throw new Error('claim');
+        await rt.markCompleted(claim.record.matrixRowId, 'G', { graphId: 'G', knowledge: {} });
+        const claim2 = await rt.claimNext({ matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' });
+        if (!claim2.ok)
+            throw new Error('claim2');
+        await rt.markFailed(claim2.record.matrixRowId, 'G', 'boom');
+        return rt;
+    }
+    it('listWaiting / listCompleted / listFailed reflect status', async () => {
+        const rt = await setupRowsWithMixedStatus();
+        const waiting = await rt.listWaiting({ matrixCatalogId: 'cat', graphId: 'G', matrixRunId: 'r1' });
+        const completed = await rt.listCompleted({ matrixCatalogId: 'cat', graphId: 'G', matrixRunId: 'r1' });
+        const failed = await rt.listFailed({ matrixCatalogId: 'cat', graphId: 'G', matrixRunId: 'r1' });
+        expect(waiting).toHaveLength(1);
+        expect(completed).toHaveLength(1);
+        expect(failed).toHaveLength(1);
+    });
+    it('fetchSourceJoinView surfaces waitingInSource diff via resolver', async () => {
+        const { fetchSourceJoinView } = await import('./navigator.js');
+        const rt = await setupRowsWithMixedStatus();
+        const sourceResolver = {
+            listSourceIds: async () => ['a', 'b', 'c', 'd'],
+            fetchRecordsByIds: async (ids) => ids.map((id) => ({ sourceId: id })),
+        };
+        const view = await fetchSourceJoinView({ runtime: rt, sourceResolver }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' });
+        expect(view.waitingInSource).toEqual(['d']);
+        expect(view.processed).toHaveLength(1);
+        expect(view.failed).toHaveLength(1);
+        expect(view.waitingInMatrix).toHaveLength(1);
+    });
+    it('fetchSourceJoinView without resolver returns empty waitingInSource', async () => {
+        const { fetchSourceJoinView } = await import('./navigator.js');
+        const rt = await setupRowsWithMixedStatus();
+        const view = await fetchSourceJoinView({ runtime: rt }, { matrixCatalogId: 'cat', matrixRunId: 'r1', graphId: 'G' });
+        expect(view.waitingInSource).toEqual([]);
+    });
+});
+describe('snapshots CRUD on ExecutionMatrixRuntime', () => {
+    it('insert / get / list', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const snaps = new MemoryMatrixCollection('snapshotId');
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+            snapshots: snaps.asCollection(),
+        });
+        await rt.insertSnapshot({
+            snapshotId: 's1',
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            sourceQueryHash: 'h',
+            transformVersion: 'v1',
+            payload: { ok: 1 },
+            createdAt: new Date().toISOString(),
+        });
+        const got = await rt.getSnapshot('s1');
+        expect(got?.payload).toEqual({ ok: 1 });
+        const list = await rt.listSnapshots({ matrixCatalogId: 'cat' });
+        expect(list).toHaveLength(1);
+    });
+    it('listSnapshots filters by entityType and extraFilter; countSnapshots', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const snaps = new MemoryMatrixCollection('snapshotId');
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            snapshots: snaps.asCollection(),
+        });
+        await rt.insertSnapshot({
+            snapshotId: 's_a',
+            matrixCatalogId: 'cat',
+            entityType: 'etype_a',
+            sourceQueryHash: 'h1',
+            transformVersion: 'v1',
+            payload: {},
+            createdAt: new Date().toISOString(),
+        });
+        await rt.insertSnapshot({
+            snapshotId: 's_b',
+            matrixCatalogId: 'cat',
+            entityType: 'etype_b',
+            sourceQueryHash: 'h2',
+            transformVersion: 'v1',
+            payload: {},
+            createdAt: new Date().toISOString(),
+        });
+        const filtered = await rt.listSnapshots({ matrixCatalogId: 'cat', entityType: 'etype_a' });
+        expect(filtered.map((s) => s.snapshotId)).toEqual(['s_a']);
+        await expect(rt.countSnapshots({ matrixCatalogId: 'cat', entityType: 'etype_b' })).resolves.toBe(1);
+    });
+    it('buildSnapshotsReadFilter merges entityType and extraFilter', () => {
+        expect(buildSnapshotsReadFilter({
+            matrixCatalogId: 'c',
+            matrixRunId: 'r',
+            entityType: 'e',
+            extraFilter: { transformVersion: 'v2' },
+        })).toEqual({
+            matrixCatalogId: 'c',
+            matrixRunId: 'r',
+            entityType: 'e',
+            transformVersion: 'v2',
+        });
+    });
+    it('throws when snapshots collection is not configured', async () => {
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        await expect(rt.listSnapshots({})).rejects.toThrow(/snapshots collection not configured/);
+    });
+});
+describe('orchestrator writes lastAttempt on completion / failure', () => {
+    it('persists lastAttempt with status, endedAt, jobId, modelProfile', async () => {
+        const { processMatrixGraphBatch } = await import('./orchestrator.js');
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        const [row] = materializeExecutionMatrixRuntimeRows({
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: { input: {}, graphs: ['G'] },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            inputRows: [{}],
+        });
+        await rt.insertRuntimeRow(row);
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess({}));
+        await processMatrixGraphBatch({
+            runtime: rt,
+            executeGraph,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+        }, {
+            matrixCatalogId: 'cat',
+            matrixRunId: 'r1',
+            graphIds: ['G'],
+            limit: 1,
+            jobId: 'job-1',
+            executeOverrides: { modelConfig: matrixRuntimeModelConfig('gpt-4o-xynth', 'gpt-4o-skill') },
+        });
+        const after = await rt.getRecord(row.matrixRowId);
+        const step = after?.execution.find((e) => e.graphId === 'G');
+        expect(step?.lastAttempt?.status).toBe('completed');
+        expect(step?.lastAttempt?.endedAt).toMatch(/T/);
+        expect(step?.lastAttempt?.jobId).toBe('job-1');
+        expect(step?.lastAttempt?.modelProfile).toBe('gpt-4o-xynth/gpt-4o-skill');
+    });
+});
+describe('runMatrixOncePass', () => {
+    it('record kind: fetches via resolver, materializes, executes', async () => {
+        const { runMatrixOncePass } = await import('./run-loop.js');
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        const sourceResolver = {
+            listSourceIds: async () => ['a', 'b'],
+            fetchRecordsByIds: async (ids) => ids.map((id) => ({ sourceId: id, payload: id })),
+        };
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        const result = await runMatrixOncePass({
+            runtime: rt,
+            executeGraph,
+            sourceResolver,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+        }, {
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: {
+                input: {},
+                graphs: ['G'],
+                dataSource: { kind: 'record', collectionRef: 'col', recordsPerRun: 2 },
+                executionMode: { mode: 'single-pass' },
+            },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+        });
+        expect(result.fetched).toBe(2);
+        expect(result.materialized).toBe(1);
+        expect(result.executed).toBeGreaterThanOrEqual(1);
+        expect(result.emptyPass).toBe(false);
+    });
+    it('query-snapshot kind: runs transform, persists snapshot, materializes', async () => {
+        const { runMatrixOncePass } = await import('./run-loop.js');
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const snaps = new MemoryMatrixCollection('snapshotId');
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+            snapshots: snaps.asCollection(),
+        });
+        const sourceResolver = {
+            listSourceIds: async () => ['a', 'b', 'c'],
+            fetchRecordsByIds: async (ids) => ids.map((id) => ({ id })),
+        };
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        const result = await runMatrixOncePass({
+            runtime: rt,
+            executeGraph,
+            sourceResolver,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+        }, {
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            matrixRunId: 'r1',
+            payload: {
+                input: {},
+                graphs: ['G'],
+                dataSource: {
+                    kind: 'query-snapshot',
+                    collectionRef: 'col',
+                    transform: { language: 'js', source: 'return { count: records.length }', version: 'v1' },
+                },
+            },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+        });
+        expect(result.fetched).toBe(3);
+        expect(result.materialized).toBe(1);
+        expect(result.snapshotId).toMatch(/^snap_/);
+        const persistedSnapshot = await rt.getSnapshot(result.snapshotId);
+        expect(persistedSnapshot?.payload).toEqual({ count: 3 });
+    });
+    it('event kind: returns empty pass when nothing is supplied (no loop fetch)', async () => {
+        const { runMatrixOncePass } = await import('./run-loop.js');
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        const result = await runMatrixOncePass({
+            runtime: rt,
+            executeGraph: vi.fn().mockResolvedValue(mockExecuteGraphSuccess()),
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+        }, {
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: {
+                input: {},
+                graphs: ['G'],
+                dataSource: { kind: 'event', subKind: 'api' },
+            },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+        });
+        expect(result.emptyPass).toBe(true);
+        expect(result.fetched).toBe(0);
+        expect(result.materialized).toBe(0);
+    });
+});
+describe('runMatrixContinuously', () => {
+    it('returns event-source for event kind matrices', async () => {
+        const { runMatrixContinuously } = await import('./run-loop.js');
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        const ctrl = new AbortController();
+        const r = await runMatrixContinuously({
+            runtime: rt,
+            executeGraph: vi.fn(),
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+        }, {
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: { input: {}, graphs: ['G'], dataSource: { kind: 'event' } },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            signal: ctrl.signal,
+        });
+        expect(r.reason).toBe('event-source');
+    });
+    it('respects maxCycles', async () => {
+        const { runMatrixContinuously } = await import('./run-loop.js');
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        let calls = 0;
+        const sourceResolver = {
+            listSourceIds: async () => {
+                calls += 1;
+                return [`x_${calls}`];
+            },
+            fetchRecordsByIds: async (ids) => ids.map((id) => ({ sourceId: id })),
+        };
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        const ctrl = new AbortController();
+        const r = await runMatrixContinuously({
+            runtime: rt,
+            executeGraph,
+            sourceResolver,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+        }, {
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: {
+                input: {},
+                graphs: ['G'],
+                dataSource: { kind: 'record', collectionRef: 'col', pollWhenEmptySeconds: 1 },
+                executionMode: { mode: 'continuous' },
+            },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            signal: ctrl.signal,
+            maxCycles: 2,
+        });
+        expect(r.reason).toBe('maxCycles');
+        expect(r.cyclesRun).toBe(2);
+    });
+    it('aborts cleanly during empty-pass sleep', async () => {
+        const { runMatrixContinuously } = await import('./run-loop.js');
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        const sourceResolver = {
+            listSourceIds: async () => [],
+            fetchRecordsByIds: async () => [],
+        };
+        const ctrl = new AbortController();
+        const promise = runMatrixContinuously({
+            runtime: rt,
+            executeGraph: vi.fn(),
+            sourceResolver,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+        }, {
+            matrixCatalogId: 'cat',
+            matrixItemId: 'item',
+            payload: {
+                input: {},
+                graphs: ['G'],
+                dataSource: { kind: 'record', collectionRef: 'col', pollWhenEmptySeconds: 60 },
+                executionMode: { mode: 'continuous' },
+            },
+            graphRecords: [{ graphId: 'G', mappedInput: [], execution: { priority: 1 } }],
+            signal: ctrl.signal,
+        });
+        await new Promise((resolve) => setTimeout(resolve, 30));
+        ctrl.abort();
+        const r = await promise;
+        expect(r.reason).toBe('aborted');
+        expect(r.cyclesRun).toBeGreaterThanOrEqual(1);
+    });
+});
+describe('ExellixConfigStore CRUD + config-driven dispatch', () => {
+    async function setupConfigStore() {
+        const { createExellixConfigStore } = await import('./config-store.js');
+        const matrices = new MemoryMatrixCollection('matrixCatalogId');
+        const graphs = new MemoryMatrixCollection('graphId');
+        const configStore = createExellixConfigStore({
+            matrices: matrices.asCollection(),
+            graphs: graphs.asCollection(),
+        });
+        return configStore;
+    }
+    it('matrices.create / get / update / delete with versioning', async () => {
+        const { ConfigStoreConcurrencyError, ConfigStoreNotFoundError } = await import('./config-store.js');
+        const cs = await setupConfigStore();
+        const created = await cs.matrices.create({
+            matrixCatalogId: 'm1',
+            payload: { input: {}, graphs: ['g1'] },
+        });
+        expect(created.version).toBe(1);
+        const got = await cs.matrices.get('m1');
+        expect(got?.matrixCatalogId).toBe('m1');
+        const updated = await cs.matrices.update({
+            matrixCatalogId: 'm1',
+            expectedVersion: 1,
+            payload: { input: { tier: 'A' }, graphs: ['g1', 'g2'] },
+        });
+        expect(updated.version).toBe(2);
+        await expect(cs.matrices.update({
+            matrixCatalogId: 'm1',
+            expectedVersion: 1,
+            payload: { input: {}, graphs: ['g1'] },
+        })).rejects.toBeInstanceOf(ConfigStoreConcurrencyError);
+        await expect(cs.matrices.delete('m1', 99)).rejects.toBeInstanceOf(ConfigStoreConcurrencyError);
+        await expect(cs.matrices.delete('missing', 1)).rejects.toBeInstanceOf(ConfigStoreNotFoundError);
+    });
+    it('rejects invalid payload on create / update', async () => {
+        const cs = await setupConfigStore();
+        await expect(cs.matrices.create({
+            matrixCatalogId: 'm-bad',
+            payload: { input: {}, graphs: [] },
+        })).rejects.toThrow(ExecutionMatrixCatalogValidationError);
+    });
+    it('graphs.create / get with id mismatch rejection', async () => {
+        const cs = await setupConfigStore();
+        await cs.graphs.create({
+            graphId: 'g1',
+            payload: { graphId: 'g1', mappedInput: [], execution: { priority: 1 } },
+        });
+        let caught;
+        try {
+            await cs.graphs.create({
+                graphId: 'g2',
+                payload: { graphId: 'g3', mappedInput: [], execution: { priority: 1 } },
+            });
+        }
+        catch (err) {
+            if (err instanceof ExecutionMatrixCatalogValidationError)
+                caught = err;
+        }
+        expect(caught).toBeInstanceOf(ExecutionMatrixCatalogValidationError);
+        expect(caught?.issues.join('\n')).toMatch(/graphId mismatch/);
+    });
+    it('getEffectiveConfig applies defaults and reports kind', async () => {
+        const cs = await setupConfigStore();
+        await cs.matrices.create({
+            matrixCatalogId: 'm-eff',
+            payload: {
+                input: {},
+                graphs: ['g1'],
+                dataSource: { kind: 'record', collectionRef: 'r' },
+            },
+        });
+        const eff = await cs.matrices.getEffectiveConfig('m-eff');
+        expect(eff?.executionMode.mode).toBe('single-pass');
+        expect(eff?.pollWhenEmptySeconds).toBe(60);
+        expect(eff?.dataSourceKind).toBe('record');
+    });
+    it('runMatrixOncePassByCatalogId resolves config and runs cycle', async () => {
+        const { runMatrixOncePassByCatalogId } = await import('./run-loop.js');
+        const cs = await setupConfigStore();
+        await cs.matrices.create({
+            matrixCatalogId: 'm-rt',
+            payload: {
+                input: {},
+                graphs: ['g1'],
+                dataSource: { kind: 'record', collectionRef: 'r' },
+            },
+        });
+        await cs.graphs.create({
+            graphId: 'g1',
+            payload: { graphId: 'g1', mappedInput: [], execution: { priority: 1 } },
+        });
+        const rows = new MemoryMatrixCollection(MATRIX_ROW_PK);
+        const fails = new MemoryMatrixCollection(MATRIX_FAILURE_PK);
+        const rt = createExecutionMatrixRuntime(rows.asCollection(), fails.asCollection(), {
+            serializeClaims: true,
+        });
+        const sourceResolver = {
+            listSourceIds: async () => ['s1'],
+            fetchRecordsByIds: async (ids) => ids.map((id) => ({ sourceId: id })),
+        };
+        const executeGraph = vi.fn().mockResolvedValue(mockExecuteGraphSuccess());
+        const r = await runMatrixOncePassByCatalogId({
+            runtime: rt,
+            executeGraph,
+            sourceResolver,
+            resolveGraphModel: resolveGraphModelForTest,
+            resolveGraphEntry: () => ({ inputs: [] }),
+            configStore: cs,
+        }, { matrixCatalogId: 'm-rt', matrixItemId: 'item' });
+        expect(r.effective.dataSourceKind).toBe('record');
+        expect(r.fetched).toBe(1);
+        expect(r.materialized).toBe(1);
+    });
+});
+describe('graph-engine graph document round-trip', () => {
+    it('preserves smartInput, inputSynthesis, executionStrategies, and executionMemoryPath bindings under canonical rules', () => {
+        const graph = {
+            id: 'g.unit',
+            response: { shape: { type: 'literal', value: {} } },
+            nodes: [
+                {
+                    id: 't1',
+                    type: 'task',
+                    skillKey: 'sk.test',
+                    smartInput: { roots: ['input.raw'] },
+                    taskConfiguration: {
+                        aiTaskProfile: {
+                            inputSynthesis: { enabled: true, outputKey: 'synthesized', catalogId: 'x' },
+                        },
+                        executionStrategies: [{ strategyKey: 'planner', phase: 'before', priority: 0 }],
+                    },
+                    executionPipeline: [{ phase: 'main', type: 'direct' }],
+                    inputs: {
+                        body: { type: 'executionMemoryPath', path: 'input.raw' },
+                    },
+                },
+            ],
+            metadata: { name: 'UnitGraph' },
+        };
+        assertCanonicalGraphDocument(graph);
+        expect(mergeGraphDocumentModel(graph).name).toBe('UnitGraph');
+        const n = graph.nodes;
+        expect(n[0].smartInput).toBeDefined();
+        expect(n[0].taskConfiguration
+            ?.aiTaskProfile?.inputSynthesis).toBeDefined();
+        expect(n[0].executionPipeline).toHaveLength(1);
+        expect(n[0].inputs?.body).toMatchObject({
+            type: 'executionMemoryPath',
+            path: 'input.raw',
+        });
+    });
+});
+//# sourceMappingURL=execution-matrix.spec.js.map