specrails-core 6.0.1 → 6.1.0

package/dist/agent-runtime/engine/checkpoint/saver.js

@@ -0,0 +1,146 @@
+import { BaseCheckpointSaver, copyCheckpoint, WRITES_IDX_MAP } from '@langchain/langgraph-checkpoint';
+import { EngineError } from '../contracts.js';
+const configOf = (row) => ({ configurable: { thread_id: row.thread_id, checkpoint_ns: row.checkpoint_ns, checkpoint_id: row.checkpoint_id } });
+function identity(config, taskId) {
+    const { thread_id, checkpoint_ns = '', checkpoint_id = '' } = config.configurable ?? {};
+    if (typeof thread_id !== 'string' || !thread_id || typeof checkpoint_ns !== 'string' || typeof checkpoint_id !== 'string')
+        throw new EngineError('invalid_arguments', 'Checkpoint thread, namespace and ID must be strings');
+    if (taskId !== undefined && (!taskId || !checkpoint_id))
+        throw new EngineError('invalid_arguments', 'Pending writes require checkpoint and task IDs');
+    return { checkpointThreadId: thread_id, taskCheckpointNs: checkpoint_ns, checkpointId: checkpoint_id, taskId: taskId ?? '' };
+}
+/** LangGraph adapter. Terminal evidence and pending writes have exactly one commit owner. */
+export class SqliteRunSaver extends BaseCheckpointSaver {
+    database;
+    ledger;
+    options;
+    constructor(database, ledger, options = {}) {
+        super();
+        this.database = database;
+        this.ledger = ledger;
+        this.options = options;
+    }
+    assertWriter() {
+        if (!this.ledger)
+            throw new EngineError('read_only', 'Read-only saver cannot mutate checkpoints');
+        this.ledger.lease.assert(this.ledger.token);
+        return this.ledger;
+    }
+    async tuple(row) {
+        const pendingWrites = [];
+        for (const write of this.database.sqlite.prepare('SELECT * FROM writes WHERE thread_id=? AND checkpoint_ns=? AND checkpoint_id=? ORDER BY task_id,idx').all(row.thread_id, row.checkpoint_ns, row.checkpoint_id)) {
+            pendingWrites.push([String(write.task_id), String(write.channel), await this.serde.loadsTyped(String(write.type), write.value)]);
+        }
+        return { config: configOf(row), checkpoint: await this.serde.loadsTyped(String(row.type), row.checkpoint),
+            metadata: await this.serde.loadsTyped(String(row.metadata_type), row.metadata),
+            pendingWrites, ...(row.parent_checkpoint_id ? { parentConfig: configOf({ ...row, checkpoint_id: row.parent_checkpoint_id }) } : {}) };
+    }
+    async getTuple(config) {
+        const task = identity(config);
+        const row = task.checkpointId ? this.database.sqlite.prepare('SELECT * FROM checkpoints WHERE thread_id=? AND checkpoint_ns=? AND checkpoint_id=?').get(task.checkpointThreadId, task.taskCheckpointNs, task.checkpointId)
+            : this.database.sqlite.prepare('SELECT * FROM checkpoints WHERE thread_id=? AND checkpoint_ns=? ORDER BY checkpoint_id DESC LIMIT 1').get(task.checkpointThreadId, task.taskCheckpointNs);
+        return row ? this.tuple(row) : undefined;
+    }
+    async *list(config, options = {}) {
+        const clauses = [], values = [];
+        for (const key of ['thread_id', 'checkpoint_ns', 'checkpoint_id']) {
+            const value = config.configurable?.[key];
+            if (value !== undefined) {
+                if (typeof value !== 'string')
+                    throw new EngineError('invalid_arguments', 'Checkpoint selectors must be strings');
+                clauses.push(`${key}=?`);
+                values.push(value);
+            }
+        }
+        if (options.before?.configurable?.checkpoint_id) {
+            clauses.push('checkpoint_id<?');
+            values.push(String(options.before.configurable.checkpoint_id));
+        }
+        if (options.limit !== undefined && (!Number.isSafeInteger(options.limit) || options.limit < 0))
+            throw new EngineError('invalid_arguments', 'Checkpoint limit must be a non-negative integer');
+        let remaining = options.limit ?? Infinity;
+        const rows = this.database.sqlite.prepare('SELECT * FROM checkpoints' + (clauses.length ? ' WHERE ' + clauses.join(' AND ') : '') + ' ORDER BY checkpoint_id DESC').all(...values);
+        for (const row of rows) {
+            if (remaining === 0)
+                break;
+            const tuple = await this.tuple(row);
+            if (options.filter && !Object.entries(options.filter).every(([key, value]) => JSON.stringify(tuple.metadata?.[key]) === JSON.stringify(value)))
+                continue;
+            remaining--;
+            yield tuple;
+        }
+    }
+    async put(config, checkpoint, metadata) {
+        const task = identity(config), ledger = this.assertWriter();
+        const [[type, bytes], [metadataType, metadataBytes]] = await Promise.all([this.serde.dumpsTyped(copyCheckpoint(checkpoint)), this.serde.dumpsTyped(metadata)]);
+        const next = { configurable: { thread_id: task.checkpointThreadId, checkpoint_ns: task.taskCheckpointNs, checkpoint_id: checkpoint.id } };
+        this.options.fault?.('before-snapshot');
+        this.database.transaction('checkpoint-snapshot', () => {
+            this.assertWriter();
+            this.database.put('checkpoints', { thread_id: task.checkpointThreadId, checkpoint_ns: task.taskCheckpointNs, checkpoint_id: checkpoint.id,
+                parent_checkpoint_id: task.checkpointId || null, type, checkpoint: bytes, metadata: metadataBytes, metadata_type: metadataType });
+            if (task.taskCheckpointNs === '')
+                this.database.put('runs', { ...ledger.run(), head_checkpoint_json: JSON.stringify(next), current_revision: this.database.transactionRevision });
+        });
+        this.options.fault?.('after-snapshot');
+        return next;
+    }
+    async putWrites(config, writes, taskId) {
+        const task = identity(config, taskId), ledger = this.assertWriter();
+        // Serializer callbacks never run with a SQLite transaction held.
+        const dumped = await Promise.all(writes.map(async ([channel, value], index) => ({ channel, value, index: WRITES_IDX_MAP[channel] ?? index, blob: await this.serde.dumpsTyped(value) })));
+        const markers = dumped.filter(write => write.channel === '$commit');
+        if (markers.length > 1)
+            throw new EngineError('terminal_conflict', 'One physical task may settle only one terminal marker');
+        const marker = markers[0]?.value;
+        if (marker && (!marker.frame || !marker.result || typeof marker.digest !== 'string'))
+            throw new EngineError('terminal_mismatch', 'Malformed terminal marker');
+        this.options.fault?.('before-writes');
+        const events = this.database.transaction('pending-writes-and-ledger', () => {
+            this.assertWriter();
+            for (const write of dumped) {
+                const key = { thread_id: task.checkpointThreadId, checkpoint_ns: task.taskCheckpointNs, checkpoint_id: task.checkpointId, task_id: taskId, idx: write.index };
+                const prior = this.database.get('writes', key);
+                if (prior && write.index >= 0) {
+                    if (marker && (prior.channel !== write.channel || prior.type !== write.blob[0] || !Buffer.from(prior.value).equals(Buffer.from(write.blob[1]))))
+                        throw new EngineError('terminal_conflict', 'A settled task cannot change its pending writes');
+                    continue;
+                }
+                this.database.put('writes', { ...key, channel: write.channel, type: write.blob[0], value: write.blob[1] });
+            }
+            this.options.fault?.('between-writes-ledger');
+            const committed = marker ? ledger.commitTerminal(marker, task) : [];
+            for (const write of dumped.filter(write => write.channel === '__interrupt__')) {
+                // LangGraph's public PendingWrite contains one interrupt per channel write.
+                const value = write.value;
+                if (!value || typeof value.id !== 'string')
+                    throw new EngineError('interrupt_invalid', 'LangGraph interrupt IDs are required');
+                committed.push(...ledger.commitInterrupts(task, [value]));
+            }
+            for (const write of dumped.filter(write => write.channel === '__error__'))
+                committed.push(...ledger.commitError(task, write.value));
+            return committed;
+        });
+        this.options.fault?.('after-writes');
+        if (events.length && this.options.onEvents) {
+            try {
+                await this.options.onEvents(events);
+            }
+            catch (error) {
+                try {
+                    this.options.onObserverError?.(error);
+                }
+                catch { /* Delivery cannot roll back durable execution. */ }
+            }
+        }
+    }
+    async deleteThread(threadId) {
+        this.database.transaction('checkpoint-thread-deleted', () => {
+            this.assertWriter();
+            for (const table of ['writes', 'checkpoints']) {
+                for (const row of this.database.sqlite.prepare(`SELECT * FROM ${table} WHERE thread_id=?`).all(threadId))
+                    this.database.delete(table, row);
+            }
+        });
+    }
+}

package/dist/agent-runtime/engine/cli.d.ts

@@ -0,0 +1,10 @@
+import { NODE_KINDS_VERSION } from './piece-registry.js';
+export { NODE_KINDS_VERSION };
+type Flags = Record<string, string | boolean>;
+/**
+ * Resume and status select the engine from the frozen request (`workflow.engine`). A request
+ * without the block is a legacy run. A definition database without a request (a fork destination
+ * created before its request was materialized) still resolves to this engine.
+ */
+export declare function isDefinitionCommand(flags: Flags, command: string): boolean;
+export declare function runDefinitionCommand(flags: Flags, positionals: string[], emit: (value: unknown) => void): Promise<number>;

package/dist/agent-runtime/engine/cli.js

@@ -0,0 +1,172 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { validatePipelineContext } from '../../pipeline/pipeline-state.js';
+import { validateRuntimeConfig } from '../config.js';
+import { CORE_WORKFLOW_VERSION } from '../core-host.js';
+import { EngineError } from './contracts.js';
+import { workflowDefinitionSchema } from './definition-schema.js';
+import { MAX_STEERING_BYTES } from './steering/inbox.js';
+import { MAX_DEFINITION_BYTES } from './canonical-json.js';
+import { validateWorkflowDefinition } from './definition-validator.js';
+import { configuredRoles } from './preflight.js';
+import { validationPieceRegistry } from './pieces/index.js';
+import { NODE_KINDS_VERSION } from './piece-registry.js';
+import { cancelRun, createRun, definitionRunDirectory, freezeRunRequest, frozenRequestEngine, frozenRequestFile, resumeRun, signalRun } from './runs.js';
+import { statusRun } from './run-status.js';
+import { forkRun } from './fork.js';
+export { NODE_KINDS_VERSION };
+const required = (flags, key) => {
+    const value = flags[key];
+    if (typeof value !== 'string' || !value.trim())
+        throw new EngineError('invalid_arguments', `--${key} requires a value`);
+    return value;
+};
+const optional = (flags, key) => flags[key] === undefined ? undefined : required(flags, key);
+const read = (filename) => JSON.parse(readFileSync(filename, 'utf8'));
+/** Keep definition bytes intact so duplicate keys and malformed UTF-8 are rejected. */
+async function stdinBytes(maximum = MAX_DEFINITION_BYTES) {
+    const chunks = [];
+    let size = 0;
+    for await (const value of process.stdin) {
+        const chunk = Buffer.isBuffer(value) ? value : Buffer.from(String(value));
+        size += chunk.length;
+        if (size > maximum)
+            throw new EngineError('invalid_arguments', `Standard input exceeds ${maximum} bytes`);
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+function directory(flags) {
+    if (flags['run-dir'] !== undefined && flags.context !== undefined)
+        throw new EngineError('invalid_arguments', 'Use --run-dir or --context, not both');
+    return flags['run-dir'] !== undefined ? path.resolve(required(flags, 'run-dir')) : definitionRunDirectory(validatePipelineContext(read(required(flags, 'context'))));
+}
+/**
+ * Resume and status select the engine from the frozen request (`workflow.engine`). A request
+ * without the block is a legacy run. A definition database without a request (a fork destination
+ * created before its request was materialized) still resolves to this engine.
+ */
+export function isDefinitionCommand(flags, command) {
+    if (['workflows', 'fork', 'signal', 'cancel'].includes(command) || flags.definition !== undefined && command === 'run')
+        return true;
+    if (!['resume', 'status'].includes(command))
+        return false;
+    if (flags['run-dir'] !== undefined)
+        return true;
+    if (flags.context === undefined)
+        return false;
+    const context = validatePipelineContext(read(required(flags, 'context'))), requestFile = frozenRequestFile(context);
+    if (existsSync(requestFile))
+        return frozenRequestEngine(read(requestFile)) === 2;
+    return existsSync(path.join(definitionRunDirectory(context), 'run.sqlite'));
+}
+/** Public workflow identity carried by status and results, matching the frozen request block. */
+const workflowIdentity = (workflow) => ({ ...workflow, definitionHash: workflow.version, engine: 2 });
+export async function runDefinitionCommand(flags, positionals, emit) {
+    const command = positionals[0];
+    if (command === 'workflows') {
+        if (!positionals[1] || positionals[1] === 'list') {
+            emit({ type: 'runtime-workflows', nodeKindsVersion: NODE_KINDS_VERSION, nodeKinds: validationPieceRegistry().catalog(), definitionSchema: workflowDefinitionSchema,
+                builtins: [{ id: 'specrails-implementation', version: CORE_WORKFLOW_VERSION, deprecated: false }] });
+            return 0;
+        }
+        if (positionals[1] !== 'validate' || flags.stdin !== true)
+            throw new EngineError('invalid_arguments', 'Use workflows validate --stdin [--config file | --structural]');
+        if (flags.structural !== undefined && flags.structural !== true)
+            throw new EngineError('invalid_arguments', '--structural is a boolean flag');
+        const roles = flags.config === undefined ? {} : configuredRoles(validateRuntimeConfig(read(required(flags, 'config'))));
+        const validation = validateWorkflowDefinition(await stdinBytes(), validationPieceRegistry(), roles, { structural: flags.structural === true });
+        emit({ ...validation, ...(flags.structural ? { roleResolution: 'deferred' } : {}) });
+        return validation.ok ? 0 : 1;
+    }
+    if (command === 'status') {
+        const status = await statusRun(directory(flags), flags.compact === true);
+        emit({ ...status, workflow: workflowIdentity(status.workflow) });
+        return 0;
+    }
+    if (command === 'signal') {
+        if (flags.stdin !== true)
+            throw new EngineError('invalid_arguments', 'Signal requires --stdin');
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(await stdinBytes(MAX_STEERING_BYTES));
+        const message = await signalRun(directory(flags), text, optional(flags, 'request-id'));
+        emit({ type: 'runtime-signal-accepted', id: message.id, acceptedAt: message.createdAt });
+        return 0;
+    }
+    if (command === 'cancel') {
+        emit({ type: 'runtime-cancellation-accepted', ...await cancelRun(directory(flags), optional(flags, 'request-id')) });
+        return 0;
+    }
+    const cutOptions = () => ({ ...(flags['scope-id'] === undefined ? {} : { scopeId: required(flags, 'scope-id') }),
+        ...(flags.visit === undefined ? {} : { visit: Number(required(flags, 'visit')) }) });
+    if (command === 'fork') {
+        const fork = await forkRun(directory(flags), { fromNodePath: required(flags, 'from'), runId: required(flags, 'run-id'), ...cutOptions(),
+            ...(flags['request-id'] === undefined ? {} : { requestId: required(flags, 'request-id') }),
+            ...(flags.state === undefined ? {} : { state: read(required(flags, 'state')) }) });
+        await freezeRunRequest(fork.directory);
+        emit(fork);
+        return 0;
+    }
+    const controller = new AbortController(), abort = () => controller.abort(new EngineError('aborted', 'Process termination requested'));
+    process.on('SIGINT', abort);
+    process.on('SIGTERM', abort);
+    try {
+        let previous;
+        let result;
+        if (command === 'run') {
+            if (flags.workflow !== undefined)
+                throw new EngineError('invalid_arguments', '--definition and --workflow are mutually exclusive');
+            result = await createRun({ context: read(required(flags, 'context')), config: read(required(flags, 'config')),
+                definition: readFileSync(required(flags, 'definition')), change: optional(flags, 'change'), signal: controller.signal, onEvent: emit });
+        }
+        else if (command === 'resume') {
+            if (flags.definition !== undefined || flags.config !== undefined)
+                throw new EngineError('invalid_arguments', 'Resume uses the frozen definition and config');
+            if ((flags.answer !== undefined || flags.approve !== undefined) && (flags.recover !== undefined || flags.invalidate !== undefined))
+                throw new EngineError('invalid_arguments', 'Human answers and recovery cannot be combined');
+            let target = directory(flags);
+            previous = await statusRun(target);
+            if (flags.invalidate !== undefined) {
+                if (flags.recover !== undefined)
+                    throw new EngineError('invalid_arguments', 'Invalidate selects a new historical run; use recovery separately on that run');
+                const fork = await forkRun(target, { fromNodePath: required(flags, 'invalidate'),
+                    runId: optional(flags, 'run-id') ?? previous.state.runId.slice(0, 96) + '-invalidate-' + randomUUID().slice(0, 8), ...cutOptions() });
+                await freezeRunRequest(fork.directory);
+                emit(fork);
+                target = fork.directory;
+                previous = await statusRun(target);
+            }
+            const answers = {}, pending = previous.state.pendingInterrupts;
+            if (flags.answer !== undefined) {
+                const matches = pending.filter(item => item.kind === 'question' && (flags['interrupt-id'] === undefined || item.id === required(flags, 'interrupt-id')));
+                if (matches.length !== 1)
+                    throw new EngineError('interrupt_ambiguous', 'Select one pending question with --interrupt-id');
+                answers[matches[0].id] = { answer: required(flags, 'answer') };
+            }
+            if (flags.approve !== undefined)
+                for (const node of required(flags, 'approve').split(',')) {
+                    const matches = pending.filter(item => ['approval', 'gate'].includes(item.kind) && (item.nodePath === node || item.id === node));
+                    if (matches.length !== 1)
+                        throw new EngineError('interrupt_ambiguous', 'Approval must identify exactly one pending node or interrupt');
+                    answers[matches[0].id] = { approved: true };
+                }
+            result = await resumeRun(target, { signal: controller.signal, onEvent: emit, answers,
+                recover: optional(flags, 'recover')?.split(','),
+                ...(flags.context && flags.invalidate === undefined ? { context: validatePipelineContext(read(required(flags, 'context'))) } : {}) });
+        }
+        else
+            throw new EngineError('invalid_arguments', `Unsupported definition command ${command}`);
+        const delta = (key) => {
+            const current = result.state.usage[key], prior = previous ? previous.state.usage[key] : 0;
+            return current === null || prior === null ? null : Math.max(0, current - prior);
+        };
+        emit({ type: 'runtime-result', engineVersion: 2, ...result.state, revision: result.revision, eventCursor: result.eventCursor, workflow: workflowIdentity(result.workflow), completion: result.completion,
+            ...('forkOf' in result ? { forkOf: result.forkOf } : {}), ...('error' in result ? { error: result.error } : {}),
+            usage: result.state.usage, invocationUsage: { costUsd: delta('costUsd'), inputTokens: delta('inputTokens'), outputTokens: delta('outputTokens') }, metrics: result.metrics, efficiencySummary: result.efficiencySummary });
+        return result.state.status === 'succeeded' ? 0 : result.state.status === 'paused' ? 2 : 1;
+    }
+    finally {
+        process.off('SIGINT', abort);
+        process.off('SIGTERM', abort);
+    }
+}

package/dist/agent-runtime/engine/compiler.d.ts

@@ -0,0 +1,23 @@
+import { type BaseCheckpointSaver, type CompiledStateGraph } from '@langchain/langgraph';
+import { type CoreDefinitionState, type JsonValue, type NodeExecutionPort } from './contracts.js';
+import type { RoleCatalog, WorkflowDefinition } from './definition-types.js';
+import type { PieceRegistry } from './piece-registry.js';
+import { definitionStateSchema } from './state.js';
+import type { ImplementationAdapter } from './pieces/implementation.js';
+import type { JsonObject } from './contracts.js';
+type DefinitionSchema = ReturnType<typeof definitionStateSchema>;
+export type CompiledDefinitionGraph = CompiledStateGraph<CoreDefinitionState, Partial<CoreDefinitionState>, string, DefinitionSchema['spec'], DefinitionSchema['spec']>;
+export interface CompileDefinitionOptions {
+    roles?: RoleCatalog;
+    checkpointer?: BaseCheckpointSaver;
+    /** Frozen host context collections available to map; never fetched by the compiler. */
+    collections?: {
+        tickets?: JsonValue[];
+        repositories?: JsonValue[];
+    };
+    /** Bound to the admitted change and real Core journal by the composition root. */
+    implementation?: (params: JsonObject) => ImplementationAdapter;
+}
+/** No provider or persistence side effects occur while compiling a validated document. */
+export declare function compileWorkflowDefinition(definition: WorkflowDefinition, registry: PieceRegistry, execution: NodeExecutionPort, options?: CompileDefinitionOptions): CompiledDefinitionGraph;
+export {};

package/dist/agent-runtime/engine/compiler.js

@@ -0,0 +1,261 @@
+import { END, interrupt, isGraphInterrupt, Send, START, StateGraph } from '@langchain/langgraph';
+import { EngineError } from './contracts.js';
+import { validateWorkflowDefinition } from './definition-validator.js';
+import { interpolateParams } from './expressions.js';
+import { definitionStateSchema, initialDefinitionState, mergeHistory } from './state.js';
+import { boundPieceOutput } from './output.js';
+import { compileImplementationGraph, implementationContext, implementationInput } from './implementation-compiler.js';
+class ClassifiedRetry extends Error {
+    cause;
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.cause = cause;
+        this.name = 'ClassifiedRetry';
+    }
+}
+/** No provider or persistence side effects occur while compiling a validated document. */
+export function compileWorkflowDefinition(definition, registry, execution, options = {}) {
+    const validated = validateWorkflowDefinition(definition, registry, options.roles, { published: true });
+    if (!validated.ok)
+        throw new EngineError('invalid_definition', 'Cannot compile an invalid definition', validated.errors.map(error => ({ ...error })));
+    const frozen = validated.definition;
+    return compileBody(frozen, true);
+    function compileBody(body, root) {
+        const schema = definitionStateSchema(frozen.policies?.historyMaxChars, root ? { id: 'root', nodePathPrefix: '' } : null);
+        const graph = new StateGraph(schema);
+        for (const [id, node] of Object.entries(body.nodes)) {
+            const piece = registry.get(node.kind);
+            const componentBody = node.kind === 'component' || node.kind === 'map' ? frozen.components?.[String(node.params[node.kind === 'map' ? 'body' : 'ref'])] : undefined;
+            const child = componentBody ? compileBody(componentBody, false) : undefined;
+            const implementation = node.kind === 'implementation' ? options.implementation?.(node.params) : undefined;
+            if (node.kind === 'implementation' && !implementation)
+                throw new EngineError('implementation_adapter_required', 'Implementation requires the real Core journal adapter');
+            const implementationChild = implementation ? compileImplementationGraph(implementation, execution) : undefined;
+            const effect = child || implementationChild ? 'read' : registry.effect(node.kind, node.params, options.roles ?? {});
+            const outcomes = node.kind === 'component' ? componentBody?.outputs ?? ['next', 'failed'] : registry.outcomes(node.kind, node.params);
+            const branchName = '_core_map_' + id;
+            const mapPredecessor = node.kind === 'join' ? Object.entries(body.nodes).find(([, value]) => value.kind === 'map' && value.ends.next === id)?.[0] : undefined;
+            const retry = { maxAttempts: node.retry?.maxAttempts ?? (piece.descriptor.requiresAI ? 2 : 1), retrySafe: effect === 'read', initialIntervalMs: node.retry?.backoffMs ?? 5000 };
+            graph.addNode(id, async (state, config) => {
+                const info = config.executionInfo;
+                if (!info?.threadId)
+                    throw new EngineError('execution_identity_missing', 'Durable definitions require public task identity and a checkpoint thread');
+                const nodePath = state.$scope.nodePathPrefix ? state.$scope.nodePathPrefix + '/' + id : id;
+                const frame = await execution.enter({ nodePath, kind: node.kind, effect, requiresAI: piece.descriptor.requiresAI,
+                    acceptsSteering: piece.descriptor.requiresAI && ['prompt', 'role-turn'].includes(node.kind) && node.params.appendSteering !== false, scope: state.$scope,
+                    task: { checkpointThreadId: info.threadId, checkpointId: info.checkpointId, taskCheckpointNs: info.checkpointNs, taskId: info.taskId }, retry });
+                let result;
+                let mapPlan;
+                try {
+                    const interpolated = interpolateParams(node.params, state.$vars);
+                    const params = node.kind === 'end' && root ? { ...interpolated, requiresVerified: interpolated.requiresVerified === true || frozen.delivery?.requiresVerified === true } : interpolated;
+                    if (node.kind === 'map') {
+                        const items = mapItems(params.over, state, options.collections);
+                        result = { outcome: 'next', output: { total: items.length }, branches: { [id]: { total: items.length, results: [], visitId: frame.visitId, transition: frame.transition } } };
+                        // The item vector is stored once in the parent checkpoint, not once per Send argument.
+                        mapPlan = { frame, items };
+                    }
+                    else if (node.kind === 'join' && mapPredecessor) {
+                        const branch = state.$branches[mapPredecessor];
+                        if (!branch || branch.results.length !== branch.total)
+                            throw new EngineError('join_incomplete', 'Join cannot run before every branch has settled');
+                        const ok = branch.results.filter(value => value.outcome === 'next' || value.outcome === 'success').length;
+                        const passes = params.reduce === 'collect' || (params.reduce === 'any-ok' ? ok > 0 : ok === branch.total);
+                        result = { outcome: passes ? 'next' : 'fail', output: { total: branch.total, ok, failed: branch.total - ok, results: branch.results.map(value => ({ index: value.index, outcome: value.outcome, output: value.output })) } };
+                    }
+                    else if (implementationChild && implementation) {
+                        result = await execution.execute(frame, 'read', async (signal) => {
+                            const context = implementationContext(state, frame, signal, execution);
+                            const initial = await implementation.initialize(context);
+                            const completed = await implementationChild.invoke({ ...implementationInput(state, frame), ...initial }, config);
+                            const summarized = await implementation.summarize(completed, context);
+                            if (completed.$nodeResult?.status === 'blocked')
+                                summarized.status = 'blocked';
+                            if (completed.$nodeResult?.error)
+                                summarized.error = { code: summarized.status === 'blocked' ? 'implementation_blocked' : 'implementation_failed', message: completed.$nodeResult.error };
+                            return summarized;
+                        });
+                    }
+                    else if (child && componentBody) {
+                        const input = componentInput(state, frame, params.inputs, componentBody);
+                        const completed = await child.invoke(input, config);
+                        const exit = completed.$exit;
+                        if (!exit)
+                            throw new EngineError('component_exit_missing', `Component ${nodePath} did not produce an exit`);
+                        result = { outcome: exit.outcome, status: exit.status, output: { outputs: completed.$outputs, completion: { ...exit.completion } },
+                            candidate: completed.$candidate ?? undefined, verified: completed.$verified, usage: completed.$usage, completion: exit.completion,
+                            ...(exit.error ? { error: exit.error } : {}) };
+                        if (!result.candidate)
+                            delete result.candidate;
+                    }
+                    else
+                        result = await execution.execute(frame, effect, signal => piece.execute(params, {
+                            state: structuredClone(state), frame, signal, progress: event => execution.progress({ ...event, payload: {
+                                    ...(event.payload && typeof event.payload === 'object' && !Array.isArray(event.payload) ? event.payload : { payload: event.payload }),
+                                    runId: frame.runId, nodePath: frame.nodePath, scopeId: frame.scope.id,
+                                    ...(frame.scope.branchId ? { branch: frame.scope.branchId } : {}),
+                                    attemptId: frame.attemptId, attempt: frame.attempt, visit: frame.visit,
+                                } }),
+                            interrupt: request => interrupt(request),
+                        }));
+                    if (!outcomes.includes(result.outcome) && node.kind !== 'end' && result.status !== 'failed')
+                        throw new EngineError('invalid_piece_outcome', `Piece ${id} returned undeclared outcome ${result.outcome}`);
+                    result = { ...result, ...(result.output !== undefined ? { output: boundPieceOutput(result.output) } : {}),
+                        ...(result.history ? { history: mergeHistory([], result.history, frozen.policies?.historyMaxChars ?? 1500) } : {}) };
+                }
+                catch (error) {
+                    if (isGraphInterrupt(error)) {
+                        await execution.interrupted(frame, error);
+                        throw error;
+                    }
+                    if (child || implementationChild) {
+                        await execution.interrupted(frame, error);
+                        throw error;
+                    }
+                    const code = error instanceof EngineError || (error && typeof error === 'object' && 'code' in error) ? String(error.code) : 'piece_failed';
+                    if (effect === 'write' && ['aborted', 'timeout', 'idle_timeout', 'lease_lost'].includes(code)) {
+                        await execution.interrupted(frame, error);
+                        throw error;
+                    }
+                    const allowedCodes = node.retry?.retryOn ?? ['idle_timeout', 'provider_request_error'];
+                    const failure = await execution.failed(frame, error, { retry: frame.attempt < retry.maxAttempts && allowedCodes.includes(code) });
+                    if (failure.retryable)
+                        throw new ClassifiedRetry(error);
+                    result = { outcome: 'failed', status: 'failed', error: { code, message: error instanceof Error ? error.message : String(error) } };
+                }
+                const exitsBody = node.kind === 'end' || node.ends[result.outcome] === null || (!Object.hasOwn(node.ends, result.outcome) && result.status === 'failed');
+                result = { ...result, completesRun: root && exitsBody, ...(exitsBody && !result.completion ? { completion: implicitCompletion(result, state) } : {}) };
+                if (root && exitsBody && frozen.delivery?.requiresVerified && result.completion && !result.completion.verified) {
+                    result.completion = { ...result.completion, ok: false, reasons: [...new Set([...result.completion.reasons, 'unverified'])] };
+                }
+                const marker = execution.terminal(frame, result);
+                const patch = resultPatch(id, frame, marker.result, marker);
+                if (mapPlan)
+                    patch.$maps = { [id]: mapPlan };
+                if (node.kind === 'join' && mapPredecessor && state.$maps[mapPredecessor])
+                    patch.$maps = { [mapPredecessor]: { ...state.$maps[mapPredecessor], items: [] } };
+                if (exitsBody) {
+                    const completion = marker.result.completion ?? implicitCompletion(result, state);
+                    patch.$exit = { outcome: typeof node.params.exit === 'string' ? node.params.exit : completion.ok ? 'next' : 'failed',
+                        transition: frame.transition, completion, status: marker.result.status ?? 'succeeded', ...(result.error ? { error: result.error } : {}) };
+                }
+                return patch;
+            }, { ...(implementationChild ? { subgraphs: [implementationChild] } : child && node.kind !== 'map' ? { subgraphs: [child] } : {}), ...(node.kind === 'join' ? { defer: true } : {}), retryPolicy: { maxAttempts: retry.maxAttempts, initialInterval: retry.initialIntervalMs, jitter: false, retryOn: error => error instanceof ClassifiedRetry } });
+            if (node.kind === 'map' && child && componentBody) {
+                graph.addNode(branchName, async (task, config) => {
+                    const input = componentInput(task.seed, task.frame, undefined, componentBody);
+                    input.$scope.id += '/' + task.index;
+                    input.$scope.branchId = task.frame.visitId + ':' + task.index;
+                    input.$scope.limits = [...(task.frame.scope.limits ?? []), { id: task.frame.visitId, concurrency: Number(node.params.concurrency ?? frozen.policies?.concurrency ?? 1) }];
+                    input.$item = { index: task.index, value: task.item };
+                    input.$vars.item = task.item;
+                    input.$vars.index = task.index;
+                    const completed = await child.invoke(input, config);
+                    if (!completed.$exit)
+                        throw new EngineError('component_exit_missing', 'Map body did not produce an exit');
+                    return { $branches: { [id]: { total: task.total, visitId: task.frame.visitId, transition: task.frame.transition,
+                                results: [{ id: task.frame.visitId + ':' + task.index, transition: task.frame.transition, attempt: task.frame.attempt, ordinal: task.index,
+                                        index: task.index, outcome: completed.$exit.completion.ok ? 'next' : 'failed', output: boundPieceOutput({ outputs: completed.$outputs, completion: { ...completed.$exit.completion } }) }] } } };
+                }, { subgraphs: [child] });
+            }
+        }
+        // Dynamic IDs are validated above; LangGraph's builder generic accumulates only literal IDs.
+        const edges = graph;
+        edges.addEdge(START, body.entry);
+        for (const [id, node] of Object.entries(body.nodes)) {
+            if (node.kind === 'end') {
+                edges.addEdge(id, END);
+                continue;
+            }
+            if (node.kind === 'map') {
+                const branchName = '_core_map_' + id;
+                const join = node.ends.next;
+                edges.addConditionalEdges(id, state => {
+                    if (state.$lastOutcome[id] !== 'next')
+                        return END;
+                    const plan = state.$maps[id];
+                    if (!plan || !plan.items.length)
+                        return join;
+                    const seed = initialDefinitionState(state.$vars, state.$scope);
+                    seed.$candidate = state.$candidate;
+                    seed.$verified = state.$verified;
+                    seed.$usage = state.$usage;
+                    return plan.items.map((item, index) => new Send(branchName, { seed, frame: plan.frame, item, index, total: plan.items.length }));
+                }, [branchName, join, END]);
+                edges.addEdge(branchName, join);
+                continue;
+            }
+            const mapping = Object.fromEntries(Object.entries(node.ends).map(([outcome, target]) => [outcome, target ?? END]));
+            mapping.__engine_failure = END;
+            edges.addConditionalEdges(id, state => {
+                const outcome = state.$lastOutcome[id];
+                return Object.hasOwn(node.ends, outcome) ? outcome : '__engine_failure';
+            }, mapping);
+        }
+        return edges.compile(root ? { checkpointer: options.checkpointer } : {});
+    }
+}
+function resultPatch(id, frame, result, marker) {
+    return {
+        $outputs: { [id]: result.output ?? null }, $lastOutcome: { [id]: result.outcome },
+        $attempts: { [id]: frame.attempt }, $transitions: frame.transition, $commit: marker,
+        ...(result.vars ? { $vars: result.vars } : {}), ...(result.history ? { $history: result.history } : {}),
+        ...(result.session ? { $sessions: { [id]: result.session } } : {}), ...(result.usage ? { $usage: result.usage } : {}),
+        ...(result.candidate ? { $candidate: result.candidate } : {}),
+        ...(Object.hasOwn(result, 'verified') ? { $verified: result.verified ?? null } : {}),
+        ...(result.answers ? { $answers: result.answers } : {}), ...(result.branches ? { $branches: result.branches } : {}),
+    };
+}
+function componentInput(state, frame, mapping, body) {
+    const vars = {};
+    for (const name of body.inputs ?? [])
+        if (Object.hasOwn(state.$vars, name))
+            vars[name] = state.$vars[name];
+    if (mapping && typeof mapping === 'object' && !Array.isArray(mapping))
+        for (const [key, value] of Object.entries(mapping)) {
+            if (typeof value === 'string' && value.startsWith('$')) {
+                const parts = value.split('.');
+                if (!['$vars', '$outputs', '$history', '$answers', '$candidate', '$verified', '$item'].includes(parts[0]))
+                    throw new EngineError('invalid_component_input', `Unsupported input channel ${parts[0]}`);
+                let resolved = state;
+                for (const part of parts) {
+                    if (['__proto__', 'constructor', 'prototype'].includes(part) || !resolved || typeof resolved !== 'object' || !Object.hasOwn(resolved, part))
+                        throw new EngineError('run_var_missing', `Component input ${value} is missing`);
+                    resolved = resolved[part];
+                }
+                vars[key] = resolved;
+            }
+            else
+                vars[key] = value;
+        }
+    const input = initialDefinitionState(vars, { id: frame.scope.id + '/' + frame.visitId, nodePathPrefix: frame.nodePath,
+        ...(frame.scope.branchId ? { branchId: frame.scope.branchId } : {}), ...(frame.scope.limits ? { limits: frame.scope.limits } : {}) });
+    input.$candidate = state.$candidate;
+    input.$verified = state.$verified;
+    input.$usage = state.$usage;
+    return input;
+}
+function implicitCompletion(result, state) {
+    const candidate = result.candidate ?? state.$candidate;
+    const verified = Object.hasOwn(result, 'verified') ? result.verified : state.$verified;
+    return { ok: !result.status || result.status === 'succeeded' ? ['success', 'next', 'pass', 'stop', 'ok', 'true'].includes(result.outcome) : false,
+        reasons: result.error ? [result.error.code] : [], verified: Boolean(candidate && verified && candidate.hash === verified.candidateHash) };
+}
+function mapItems(over, state, collections) {
+    let items;
+    if (over === 'tickets' || over === 'repositories')
+        items = collections?.[over];
+    else if (over && typeof over === 'object' && !Array.isArray(over) && typeof over.outputsOf === 'string' && typeof over.path === 'string') {
+        items = Object.hasOwn(state.$outputs, over.outputsOf) ? state.$outputs[over.outputsOf] : undefined;
+        for (const part of over.path ? over.path.split('.') : []) {
+            if (['__proto__', 'constructor', 'prototype'].includes(part) || !items || typeof items !== 'object' || !Object.hasOwn(items, part))
+                throw new EngineError('map_input_missing', 'Map output path is missing');
+            items = items[part];
+        }
+    }
+    if (!Array.isArray(items))
+        throw new EngineError('map_input_missing', 'Map requires a frozen array collection');
+    if (items.length > 10_000)
+        throw new EngineError('map_input_limit', 'Map item count cannot exceed the global maximum transition bound');
+    return structuredClone(items);
+}

package/dist/agent-runtime/engine/composition.d.ts

@@ -0,0 +1,16 @@
+import type { RunDatabase } from './checkpoint/database.js';
+import type { RunLedger } from './checkpoint/ledger.js';
+import { SqliteRunSaver } from './checkpoint/saver.js';
+import type { EngineEventStream } from './events.js';
+import { DefinitionExecution } from './execution.js';
+import { RunPieceDependencies } from './piece-dependencies.js';
+import type { preflightDefinition } from './preflight.js';
+export type DefinitionAdmission = Awaited<ReturnType<typeof preflightDefinition>>;
+/** Infrastructure is bound once to the frozen project and the current execution lease. */
+export declare function composeDefinitionRuntime(database: RunDatabase, ledger: RunLedger, admitted: DefinitionAdmission, stream: EngineEventStream, signal: AbortSignal): Promise<{
+    deps: RunPieceDependencies;
+    execution: DefinitionExecution;
+    saver: SqliteRunSaver;
+    graph: import("./compiler.js").CompiledDefinitionGraph;
+    close: () => void;
+}>;