@exellix/exellix-runtime 3.5.1

package/dist/execution-matrix/orchestrator.js

@@ -0,0 +1,656 @@
+import { activixActivityIo, activixOuterTier } from '@x12i/activix';
+import { buildMatrixJobForGraphRun, resolveGraphEntryFromGraph, setRuntimeObjectsLastJobId, isEmptyConditionWhen, isModelConfigSelection, } from '@exellix/graph-engine';
+import { DEFAULT_GRAPH_OPERATIONAL_STATE, DEFAULT_GRAPH_PUBLICATION_STATUS } from './contracts.js';
+import { getExecutionMatrixLogxer } from './matrix-logxer.js';
+import { buildExecutionSeedFromGraphEntry } from './materializer.js';
+import { assertGraphSchedulable, GraphNotSchedulableError } from './graph-operational-lifecycle.js';
+async function resolveShouldClaimNext(deps) {
+    if (!deps.shouldClaimNext)
+        return true;
+    return deps.shouldClaimNext();
+}
+async function assertGraphSchedulableForClaim(deps, graphId) {
+    if (!deps.resolveGraphSchedulability)
+        return;
+    const rec = await deps.resolveGraphSchedulability(graphId);
+    if (!rec) {
+        if (deps.graphSchedulabilityRequireConfig) {
+            throw new GraphNotSchedulableError(`Graph '${graphId}' has no configuration record (graphSchedulabilityRequireConfig is true)`, graphId, DEFAULT_GRAPH_PUBLICATION_STATUS, DEFAULT_GRAPH_OPERATIONAL_STATE);
+        }
+        return;
+    }
+    assertGraphSchedulable(rec);
+}
+/**
+ * @returns whether this graph may be claimed (false = skip this graphId without throwing).
+ */
+async function isGraphSchedulableForClaim(deps, graphId) {
+    if (!deps.resolveGraphSchedulability)
+        return true;
+    const rec = await deps.resolveGraphSchedulability(graphId);
+    if (!rec) {
+        if (deps.graphSchedulabilityRequireConfig) {
+            throw new GraphNotSchedulableError(`Graph '${graphId}' has no configuration record (graphSchedulabilityRequireConfig is true)`, graphId, DEFAULT_GRAPH_PUBLICATION_STATUS, DEFAULT_GRAPH_OPERATIONAL_STATE);
+        }
+        return true;
+    }
+    try {
+        assertGraphSchedulable(rec);
+        return true;
+    }
+    catch (e) {
+        if (e instanceof GraphNotSchedulableError)
+            return false;
+        throw e;
+    }
+}
+function resolveGraphEntryForClaim(deps, ctx, graphModel) {
+    if (deps.resolveGraphEntry)
+        return deps.resolveGraphEntry(ctx);
+    return resolveGraphEntryFromGraph(graphModel);
+}
+async function resolveGraphModelForClaim(deps, ctx) {
+    const model = (await deps.resolveGraphModel?.(ctx)) ?? deps.graphModel;
+    if (!model) {
+        throw new Error(`executeMatrixGraphForClaim: graph model resolver returned no model for graphId '${ctx.graphId}'`);
+    }
+    if (model.id !== ctx.graphId) {
+        throw new Error(`executeMatrixGraphForClaim: resolved graph model id '${model.id}' does not match claimed graphId '${ctx.graphId}'`);
+    }
+    return model;
+}
+/** Merge per-call `extraFilter` with deps `runtimeScope`; `runtimeScope` wins on duplicate keys. */
+export function mergeClaimExtraFilter(claimExtra, runtimeScope) {
+    const a = claimExtra && Object.keys(claimExtra).length ? claimExtra : undefined;
+    const b = runtimeScope && Object.keys(runtimeScope).length ? runtimeScope : undefined;
+    if (!a && !b)
+        return undefined;
+    return { ...a, ...b };
+}
+function mergeSkillKeyResolution(depsLevel, callLevel) {
+    if (!depsLevel && !callLevel)
+        return undefined;
+    const out = {};
+    if (callLevel?.allowFallbackToNodeId !== undefined) {
+        out.allowFallbackToNodeId = callLevel.allowFallbackToNodeId;
+    }
+    else if (depsLevel?.allowFallbackToNodeId !== undefined) {
+        out.allowFallbackToNodeId = depsLevel.allowFallbackToNodeId;
+    }
+    if (callLevel?.fallbackPrefix !== undefined) {
+        out.fallbackPrefix = callLevel.fallbackPrefix;
+    }
+    else if (depsLevel?.fallbackPrefix !== undefined) {
+        out.fallbackPrefix = depsLevel.fallbackPrefix;
+    }
+    const aliases = { ...(depsLevel?.aliases ?? {}), ...(callLevel?.aliases ?? {}) };
+    if (Object.keys(aliases).length > 0) {
+        out.aliases = aliases;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function mergeRuntimeNodeConfig(depsLevel, callLevel) {
+    if (!depsLevel && !callLevel)
+        return undefined;
+    const out = {};
+    const modelConfig = {
+        ...(depsLevel?.modelConfig ?? {}),
+        ...(callLevel?.modelConfig ?? {}),
+    };
+    if (Object.keys(modelConfig).length > 0) {
+        out.modelConfig = modelConfig;
+    }
+    const aliasConfig = { ...(depsLevel?.aliasConfig ?? {}), ...(callLevel?.aliasConfig ?? {}) };
+    if (Object.keys(aliasConfig).length > 0) {
+        out.aliasConfig = aliasConfig;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function mergeRuntimeNodes(depsLevel, callLevel) {
+    if (!depsLevel && !callLevel)
+        return undefined;
+    const out = {};
+    for (const nodeId of new Set([...Object.keys(depsLevel ?? {}), ...Object.keys(callLevel ?? {})])) {
+        const merged = mergeRuntimeNodeConfig(depsLevel?.[nodeId], callLevel?.[nodeId]);
+        if (merged)
+            out[nodeId] = merged;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+const DEFAULT_MATRIX_RUNTIME_AGENT_ID = 'exellix-runtime';
+const DEFAULT_MATRIX_RUNTIME_JOB_TYPE_ID = 'execution-matrix-graph-run';
+function mergeDefinedRecord(base, override) {
+    if (!override)
+        return base;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function buildRuntimeJobForClaim(deps, record, graphId, jobId) {
+    const base = {
+        id: jobId,
+        jobId,
+        agentId: DEFAULT_MATRIX_RUNTIME_AGENT_ID,
+        jobTypeId: DEFAULT_MATRIX_RUNTIME_JOB_TYPE_ID,
+        matrixRowId: record.matrixRowId,
+        matrixCatalogId: record.matrixCatalogId,
+        ...(record.matrixRunId ? { matrixRunId: record.matrixRunId } : {}),
+        graphId,
+    };
+    const hostJob = deps.buildJob?.({
+        matrixRowId: record.matrixRowId,
+        graphId,
+        jobId,
+        matrixCatalogId: record.matrixCatalogId,
+        ...(record.matrixRunId ? { matrixRunId: record.matrixRunId } : {}),
+    });
+    return {
+        ...mergeDefinedRecord(base, hostJob),
+        id: jobId,
+        jobId,
+    };
+}
+/**
+ * Merge matrix → graph-engine runtime overrides before building `GraphExecutionRequest.runtime`.
+ *
+ * Precedence:
+ *   - Per-call (`callLevel`) wins over deps-level (`depsLevel`).
+ *   - **Record fields** (`modelConfig`, `aliasConfig`, `llmCall`, `runTaskIdentity`,
+ *     `runTaskDiagnostics`, `variables`, `initialVariables`, `playgroundMeta`):
+ *     `{ ...depsLevel, ...callLevel }` per field.
+ *   - **`nodes`**: node ids shallow-merge; per-node `aliasConfig` and `modelConfig` shallow-merge.
+ *   - **`skillKeyResolution`**: top-level keys prefer call when set; `aliases` shallow-merge.
+ *   - **Scalars** (`runTaskExecutionMode`, `runLogMode`, `maxRunLogEntries`, `maxRunLogDataJsonChars`,
+ *     `mode`, `goalNodeId`, `dimension`, `failFast`, `nodeTimeoutMs`,
+ *     `clearSynthesizedContextPerNode`, `debugMode`): per-call wins when `!== undefined`; otherwise deps.
+ *   - **Replace blobs / arrays / handles** (`jobMemory`, `taskMemory`, `outputsMemory`, `initialState`,
+ *     `executionPipeline`, `runtimeObjects`, `playgroundReporter`, `eventEmitter`, `stepRetryPolicy`):
+ *     per-call wins when `!== undefined`; otherwise deps.
+ *   - When the merged object would be empty, returns `undefined` (no extra keys on the executor call).
+ */
+export function mergeMatrixGraphExecuteOverrides(depsLevel, callLevel) {
+    if (!depsLevel && !callLevel)
+        return undefined;
+    const out = {};
+    const recordMergeKeys = [
+        'modelConfig',
+        'aliasConfig',
+        'llmCall',
+        'runTaskIdentity',
+        'runTaskDiagnostics',
+        'variables',
+        'initialVariables',
+        'playgroundMeta',
+    ];
+    for (const key of recordMergeKeys) {
+        const d = depsLevel?.[key];
+        const c = callLevel?.[key];
+        if (d || c) {
+            out[key] = { ...(d ?? {}), ...(c ?? {}) };
+        }
+    }
+    const nodes = mergeRuntimeNodes(depsLevel?.nodes, callLevel?.nodes);
+    if (nodes) {
+        out.nodes = nodes;
+    }
+    const skill = mergeSkillKeyResolution(depsLevel?.skillKeyResolution, callLevel?.skillKeyResolution);
+    if (skill) {
+        out.skillKeyResolution = skill;
+    }
+    const replaceKeys = [
+        'runTaskExecutionMode',
+        'runLogMode',
+        'maxRunLogEntries',
+        'maxRunLogDataJsonChars',
+        'mode',
+        'goalNodeId',
+        'dimension',
+        'failFast',
+        'nodeTimeoutMs',
+        'clearSynthesizedContextPerNode',
+        'debugMode',
+        'jobMemory',
+        'taskMemory',
+        'outputsMemory',
+        'initialState',
+        'executionPipeline',
+        'runtimeObjects',
+        'playgroundReporter',
+        'eventEmitter',
+        'stepRetryPolicy',
+    ];
+    for (const key of replaceKeys) {
+        const c = callLevel?.[key];
+        const d = depsLevel?.[key];
+        if (c !== undefined) {
+            out[key] = c;
+        }
+        else if (d !== undefined) {
+            out[key] = d;
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** Keys orchestrator supplies — strip if callers sneak them through untyped overrides at runtime. */
+const BLOCKED_EXECUTE_OVERRIDE_KEYS = [
+    'jobId',
+    'job',
+    'graphId',
+    'input',
+    'execution',
+    'executionMemory',
+    'model',
+    'runtime',
+    'graph',
+];
+/**
+ * Removes {@link BLOCKED_EXECUTE_OVERRIDE_KEYS} from merged overrides so matrix correlation ids cannot be
+ * overridden via {@link MatrixGraphExecuteOverrides} (defense in depth for casts / dynamic payloads).
+ */
+export function sanitizeMatrixGraphExecuteOverrides(o) {
+    if (!o)
+        return undefined;
+    const raw = o;
+    let touched = false;
+    const next = { ...raw };
+    for (const k of BLOCKED_EXECUTE_OVERRIDE_KEYS) {
+        if (k in next) {
+            delete next[k];
+            touched = true;
+        }
+    }
+    if (!touched)
+        return o;
+    return Object.keys(next).length ? next : undefined;
+}
+/**
+ * Try {@link ExecutionMatrixRuntime.claimNext} for each `graphId` in order until one succeeds.
+ * Use for "execute next" across a matrix when multiple graphs share the same runtime rows.
+ */
+export async function claimNextAcrossGraphs(runtime, opts, runtimeScope) {
+    const extraFilter = mergeClaimExtraFilter(opts.extraFilter, runtimeScope);
+    for (const graphId of opts.graphIds) {
+        if (opts.beforeClaimGraph) {
+            const proceed = await opts.beforeClaimGraph(graphId);
+            if (!proceed)
+                continue;
+        }
+        const claim = await runtime.claimNext({
+            matrixCatalogId: opts.matrixCatalogId,
+            matrixRunId: opts.matrixRunId,
+            graphId,
+            fromStatuses: opts.fromStatuses,
+            workerId: opts.workerId,
+            extraFilter,
+        });
+        if (claim.ok)
+            return claim;
+    }
+    return { ok: false, reason: 'no_eligible_row' };
+}
+function isCompleted(result) {
+    return result.status === 'completed';
+}
+function getFinalOutput(result) {
+    return result.finalOutput;
+}
+function getRunLog(result) {
+    return result.runLog;
+}
+function getLogxerCorrelationId(result) {
+    return result.logxerCorrelationId;
+}
+function getExecutionSnapshot(result) {
+    return result.execution;
+}
+function getEngineSnapshot(result) {
+    return result.engineSnapshot;
+}
+function getFailureSummary(result) {
+    return result.errors;
+}
+function getGraphEngineTaskId(result) {
+    const t = result.taskId;
+    return typeof t === 'string' && t.length > 0 ? t : undefined;
+}
+/**
+ * Run graph-engine for an already-claimed slot (updates row status / inferences / failures).
+ *
+ * `runtime.executeOverrides` (per-call) is shallow-merged over `deps.executeOverrides`
+ * (orchestrator-level default) by {@link mergeMatrixGraphExecuteOverrides} and the result
+ * is merged into the single `executeGraph` call. When neither is set, no extra runtime
+ * override fields are added.
+ *
+ * Forwards graph-engine {@link ExecuteGraphInput}: `{ model, runtime }`, where `runtime` contains
+ * `jobId`, `job`, active row `input`, seeded `executionMemory`, optional `runtimeObjects`, plus merged
+ * overrides (`jobMemory`, `taskMemory`, `variables`, …). When `debugMode` is requested, it is forwarded as
+ * `runtime.debugMode` (graph-engine populates `ExecuteGraphResult.debug` only when it is true). Does not
+ * assemble ai-tasks run-task wire payloads —
+ * graph-engine owns that translation.
+ */
+export async function executeMatrixGraphForClaim(deps, claim, runtime) {
+    const { record, graphId } = claim;
+    const hasRuntimeJobId = typeof runtime?.jobId === 'string' && runtime.jobId.length > 0;
+    if (!hasRuntimeJobId && runtime?.debugMode) {
+        throw new Error('executeMatrixGraphForClaim: debugMode requires runtime jobId (runtime mode)');
+    }
+    const jobId = (hasRuntimeJobId ? runtime?.jobId : undefined) ??
+        deps.resolveJobId?.({
+            matrixRowId: record.matrixRowId,
+            graphId,
+            matrixCatalogId: record.matrixCatalogId,
+            matrixRunId: record.matrixRunId,
+        }) ??
+        buildMatrixJobForGraphRun({
+            matrixId: record.matrixCatalogId,
+            rowId: record.matrixRowId,
+            graphId,
+            attempt: 0,
+        }).jobId;
+    if (typeof jobId !== 'string' || jobId.length === 0) {
+        throw new Error('executeMatrixGraphForClaim: resolveJobId returned empty jobId');
+    }
+    const job = buildRuntimeJobForClaim(deps, record, graphId, jobId);
+    await deps.runtime.setExecutionStepJobId(record.matrixRowId, graphId, jobId);
+    const log = deps.matrixLogxer ?? getExecutionMatrixLogxer();
+    const logMeta = {
+        jobId,
+        graphId,
+        matrixRowId: record.matrixRowId,
+        matrixCatalogId: record.matrixCatalogId,
+    };
+    const ax = deps.matrixActivix;
+    let matrixActivityId;
+    let attemptMeta = { jobId };
+    try {
+        const graphModel = await resolveGraphModelForClaim(deps, {
+            graphId,
+            matrixRowId: record.matrixRowId,
+            matrixCatalogId: record.matrixCatalogId,
+            matrixRunId: record.matrixRunId,
+        });
+        const graphEntry = resolveGraphEntryForClaim(deps, { graphId, matrixRowId: record.matrixRowId }, graphModel);
+        const executionMemory = buildExecutionSeedFromGraphEntry(graphEntry, record.input);
+        const mergedOverrides = sanitizeMatrixGraphExecuteOverrides(mergeMatrixGraphExecuteOverrides(deps.executeOverrides, runtime?.executeOverrides));
+        const effectiveRuntimeObjects = mergedOverrides?.runtimeObjects ?? deps.runtimeObjects;
+        if (effectiveRuntimeObjects) {
+            setRuntimeObjectsLastJobId(effectiveRuntimeObjects, jobId);
+        }
+        if (ax) {
+            try {
+                const started = await ax.startRecord({
+                    runContext: {
+                        sessionId: jobId,
+                        jobId,
+                        graphId,
+                        matrixRowId: record.matrixRowId,
+                        matrixCatalogId: record.matrixCatalogId,
+                        instance: '@exellix/exellix-runtime',
+                    },
+                    ...activixActivityIo(activixOuterTier({ phase: 'matrix_graph_execute', matrixRowId: record.matrixRowId, graphId }, null, { graphId, matrixCatalogId: record.matrixCatalogId })),
+                });
+                matrixActivityId = started.activityId;
+            }
+            catch (e) {
+                log.warn('execution_matrix.activix.start_record_failed', { ...logMeta, data: { error: String(e) } });
+            }
+        }
+        log.info('execution_matrix.graph_execute.start', logMeta);
+        const modelProfile = extractModelProfile(mergedOverrides);
+        attemptMeta = { jobId, ...(modelProfile ? { modelProfile } : {}) };
+        const extras = mergedOverrides ?? {};
+        const debugRequested = hasRuntimeJobId && runtime?.debugMode === true;
+        const graphRuntime = {
+            jobId,
+            job,
+            input: record.input,
+            executionMemory,
+            ...(effectiveRuntimeObjects != null ? { runtimeObjects: effectiveRuntimeObjects } : {}),
+            ...(debugRequested ? { debugMode: true } : {}),
+            ...extras,
+        };
+        const input = {
+            model: graphModel,
+            runtime: graphRuntime,
+        };
+        const result = await deps.executeGraph(input);
+        if (isCompleted(result)) {
+            log.info('execution_matrix.graph_execute.completed', logMeta);
+            if (ax && matrixActivityId) {
+                try {
+                    await ax.completeRecord(matrixActivityId, {
+                        outer: { output: { status: 'completed', graphId } },
+                    });
+                }
+                catch (e) {
+                    log.warn('execution_matrix.activix.complete_record_failed', { ...logMeta, data: { error: String(e) } });
+                }
+            }
+            await deps.runtime.markCompleted(record.matrixRowId, graphId, {
+                graphId,
+                knowledge: getFinalOutput(result),
+                metadata: {
+                    matrixJobId: jobId,
+                    runLog: getRunLog(result),
+                    logxerCorrelationId: getLogxerCorrelationId(result),
+                    engineSnapshot: getEngineSnapshot(result),
+                },
+            }, attemptMeta);
+        }
+        else {
+            log.warn('execution_matrix.graph_execute.graph_failed', {
+                ...logMeta,
+                data: { errors: getFailureSummary(result) },
+            });
+            if (ax && matrixActivityId) {
+                try {
+                    await ax.failRecord(matrixActivityId, 'graph_failed', {
+                        outer: { output: { status: 'failed', graphId, errors: getFailureSummary(result) } },
+                    });
+                }
+                catch (e) {
+                    log.warn('execution_matrix.activix.fail_record_failed', { ...logMeta, data: { error: String(e) } });
+                }
+            }
+            const fail = getFailureSummary(result);
+            await deps.runtime.markFailed(record.matrixRowId, graphId, fail ?? 'graph_failed', {
+                jobId,
+                taskId: getGraphEngineTaskId(result),
+                errors: fail,
+                trace: getExecutionSnapshot(result),
+                runLog: getRunLog(result),
+            }, attemptMeta);
+        }
+        return { ok: true, graphResult: result, jobId };
+    }
+    catch (err) {
+        log.error('execution_matrix.graph_execute.threw', { ...logMeta, data: { error: String(err) } });
+        if (ax && matrixActivityId) {
+            try {
+                await ax.failRecord(matrixActivityId, err instanceof Error ? err : String(err), {
+                    outer: { output: { status: 'executor_threw', graphId } },
+                });
+            }
+            catch (e) {
+                log.warn('execution_matrix.activix.fail_record_failed', { ...logMeta, data: { error: String(e) } });
+            }
+        }
+        await deps.runtime.markFailed(record.matrixRowId, graphId, err, {
+            jobId,
+            errors: err,
+        }, attemptMeta);
+        return {
+            ok: false,
+            reason: 'executor_threw',
+            error: err,
+            matrixRowId: record.matrixRowId,
+            graphId,
+            jobId,
+        };
+    }
+}
+/**
+ * Best-effort extraction of a stable model profile string from merged overrides.
+ *
+ * Uses the graph-engine 5.1 model selector shape. Returns `undefined` when no
+ * non-empty model selector is set. Persisted on `lastAttempt.modelProfile` so
+ * eligibility filters can re-claim only when the profile differs.
+ */
+function profileFromGraphAiModelConfig(mc) {
+    const xynthesisModel = mc.xynthesisModel;
+    const skillModel = mc.skillModel;
+    if (typeof xynthesisModel === 'string' && xynthesisModel.length > 0) {
+        if (typeof skillModel === 'string' && skillModel.length > 0) {
+            return `${xynthesisModel}/${skillModel}`;
+        }
+        return xynthesisModel;
+    }
+    if (typeof skillModel === 'string' && skillModel.length > 0)
+        return skillModel;
+    return undefined;
+}
+function extractModelProfile(overrides) {
+    if (!overrides?.modelConfig)
+        return undefined;
+    const mc = overrides.modelConfig;
+    if (isModelConfigSelection(mc)) {
+        const selected = mc.cases.find((c) => isEmptyConditionWhen(c.when)) ?? mc.cases[0];
+        if (!selected?.modelConfig)
+            return undefined;
+        return profileFromGraphAiModelConfig(selected.modelConfig);
+    }
+    return profileFromGraphAiModelConfig(mc);
+}
+/**
+ * Claim the next eligible row for `graphId`, run the graph, persist completion or failure.
+ */
+export async function processNextMatrixClaim(deps, claimOpts) {
+    if (claimOpts.debugMode && !claimOpts.jobId) {
+        throw new Error('processNextMatrixClaim: debugMode requires jobId (runtime mode)');
+    }
+    await assertGraphSchedulableForClaim(deps, claimOpts.graphId);
+    if (!(await resolveShouldClaimNext(deps))) {
+        return { ok: false, reason: 'claim_paused' };
+    }
+    const claim = await deps.runtime.claimNext({
+        ...claimOpts,
+        extraFilter: mergeClaimExtraFilter(claimOpts.extraFilter, deps.runtimeScope),
+    });
+    if (!claim.ok)
+        return claim;
+    return executeMatrixGraphForClaim(deps, claim, {
+        jobId: claimOpts.jobId,
+        debugMode: claimOpts.debugMode,
+        executeOverrides: claimOpts.executeOverrides,
+    });
+}
+/**
+ * Claim a specific row for `graphId`, run the graph, persist completion or failure.
+ */
+export async function processMatrixClaimForRow(deps, claimOpts) {
+    if (claimOpts.debugMode && !claimOpts.jobId) {
+        throw new Error('processMatrixClaimForRow: debugMode requires jobId (runtime mode)');
+    }
+    await assertGraphSchedulableForClaim(deps, claimOpts.graphId);
+    if (!(await resolveShouldClaimNext(deps))) {
+        return { ok: false, reason: 'claim_paused' };
+    }
+    const claim = await deps.runtime.claimRecord({
+        ...claimOpts,
+        extraFilter: mergeClaimExtraFilter(claimOpts.extraFilter, deps.runtimeScope),
+    });
+    if (!claim.ok)
+        return claim;
+    return executeMatrixGraphForClaim(deps, claim, {
+        jobId: claimOpts.jobId,
+        debugMode: claimOpts.debugMode,
+        executeOverrides: claimOpts.executeOverrides,
+    });
+}
+/**
+ * Execute up to `limit` graph runs (claim + execute). When `graphId` is set, only that graph is claimed;
+ * otherwise {@link claimNextAcrossGraphs} is used with `graphIds` (required in that mode).
+ *
+ * - **Execute next one**: `limit: 1`, omit `graphId`, pass `graphIds` in priority order.
+ * - **Execute specific graph**: set `graphId` (same as repeated {@link processNextMatrixClaim} up to `limit`).
+ * - **Execute all**: omit `limit` or set a high `maxIterations`.
+ *
+ * When {@link ProcessMatrixClaimDeps.shouldClaimNext} returns **`false`** at the start of an iteration,
+ * the loop exits without claiming; any **`executeGraph`** from the prior iteration has already completed.
+ */
+export async function processMatrixGraphBatch(deps, opts) {
+    if (opts.debugMode && !opts.jobId) {
+        throw new Error('processMatrixGraphBatch: debugMode requires jobId (runtime mode)');
+    }
+    if (opts.jobId && (opts.limit ?? Number.MAX_SAFE_INTEGER) !== 1) {
+        throw new Error('processMatrixGraphBatch: jobId is only supported when limit === 1 (single run)');
+    }
+    const maxIterations = opts.maxIterations ?? 10_000;
+    const targetCount = opts.limit ?? Number.MAX_SAFE_INTEGER;
+    const out = [];
+    let iterations = 0;
+    const batchExtra = mergeClaimExtraFilter(opts.extraFilter, deps.runtimeScope);
+    const schedGate = deps.resolveGraphSchedulability !== undefined;
+    while (iterations < maxIterations && out.length < targetCount) {
+        iterations += 1;
+        if (!(await resolveShouldClaimNext(deps))) {
+            break;
+        }
+        let claim;
+        if (opts.graphId) {
+            if (schedGate) {
+                const proceed = await isGraphSchedulableForClaim(deps, opts.graphId);
+                if (!proceed)
+                    break;
+            }
+            claim = await deps.runtime.claimNext({
+                matrixCatalogId: opts.matrixCatalogId,
+                matrixRunId: opts.matrixRunId,
+                graphId: opts.graphId,
+                fromStatuses: opts.fromStatuses,
+                workerId: opts.workerId,
+                extraFilter: batchExtra,
+            });
+        }
+        else {
+            const graphIds = opts.graphIds;
+            if (!graphIds?.length) {
+                throw new Error('processMatrixGraphBatch: graphIds is required when graphId is omitted');
+            }
+            claim = await claimNextAcrossGraphs(deps.runtime, {
+                matrixCatalogId: opts.matrixCatalogId,
+                matrixRunId: opts.matrixRunId,
+                graphIds,
+                fromStatuses: opts.fromStatuses,
+                workerId: opts.workerId,
+                extraFilter: opts.extraFilter,
+                ...(schedGate
+                    ? {
+                        beforeClaimGraph: (gid) => isGraphSchedulableForClaim(deps, gid),
+                    }
+                    : {}),
+            }, deps.runtimeScope);
+        }
+        if (!claim.ok)
+            break;
+        const ran = await executeMatrixGraphForClaim(deps, claim, {
+            jobId: opts.jobId,
+            debugMode: opts.debugMode,
+            executeOverrides: opts.executeOverrides,
+        });
+        out.push(ran);
+    }
+    return out;
+}
+/** Convenience: run at most one eligible graph across `graphIds` (execute-next-one). */
+export async function processNextMatrixGraphExecution(deps, opts) {
+    return processMatrixGraphBatch(deps, { ...opts, limit: 1 });
+}
+/** Convenience: run until no eligible claims remain (execute-all). */
+export async function processAllMatrixGraphExecutions(deps, opts) {
+    return processMatrixGraphBatch(deps, { ...opts });
+}
+//# sourceMappingURL=orchestrator.js.map