specrails-core 6.0.1 → 6.1.0

package/dist/agent-runtime/engine/efficiency-summary.js

@@ -0,0 +1,31 @@
+import { efficiencySummary } from '../efficiency-summary.js';
+/** Derive diagnostics from committed records; status never inspects or mutates a journal. */
+export function definitionEfficiencySummary(ledger, state) {
+    const row = ledger.run(), request = JSON.parse(String(row.request_json));
+    const candidate = row.candidate_json ? JSON.parse(String(row.candidate_json)) : undefined;
+    const verified = row.verified_json ? JSON.parse(String(row.verified_json)) : undefined;
+    const completion = row.completion_json ? JSON.parse(String(row.completion_json)) : undefined;
+    const receipts = ledger.db.sqlite.prepare('SELECT receipt_json FROM receipts WHERE run_id=? ORDER BY created_at').all(ledger.runId)
+        .map(value => JSON.parse(String(value.receipt_json)));
+    const current = receipts.find(receipt => receipt.id === verified?.receiptId);
+    const evidence = current?.evidence;
+    const checks = new Map();
+    for (const entry of ledger.db.sqlite.prepare("SELECT value_json FROM piece_state WHERE run_id=? AND key LIKE 'evidence:check:%'").all(ledger.runId)) {
+        const value = JSON.parse(String(entry.value_json));
+        if (typeof value.evidenceId === 'string')
+            checks.set(value.evidenceId, { ...value, id: value.evidenceId });
+    }
+    for (const receipt of receipts) {
+        const source = receipt.evidence;
+        for (const command of source.commands ?? [])
+            if (typeof command.evidenceId === 'string' && !checks.has(command.evidenceId)) {
+                checks.set(command.evidenceId, { ...command, id: command.evidenceId, planHash: source.planHash, candidateHash: receipt.candidateHash });
+            }
+    }
+    const native = [...state.history].reverse().map(attempt => attempt.output?.completion).find(value => value?.archive !== undefined);
+    const projected = { implementation: completion?.ok ? 'complete' : 'incomplete',
+        validation: completion?.verified ? 'verified' : completion && !completion.ok ? 'blocked' : 'pending',
+        archive: native?.archive ?? 'pending', delivery: 'pending-host', reasons: completion?.reasons ?? [] };
+    return { ...efficiencySummary(state, request.context, request.config, projected, candidate ? { candidateHash: candidate.hash, ...(evidence?.planHash ? { planHash: evidence.planHash } : {}),
+            ...(evidence ? { verification: { receipt: { commands: evidence.commands ?? [], notRunEvidenceIds: evidence.notRunEvidenceIds } } } : {}) } : undefined, { items: [...checks.values()], available: true }), reservations: ledger.reservationStatus() };
+}

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

@@ -0,0 +1,19 @@
+import { type DurableEngineEvent, type JsonObject, type JsonValue, type TransientEngineEvent } from './contracts.js';
+export declare const MAX_EVENT_CHARACTERS = 1000000;
+export declare const spanIdFor: (runId: string, sequence: number) => string;
+export declare const traceIdFor: (runId: string) => string;
+/** Bound log strings without dropping lifecycle identity or inventing usage. */
+export declare function boundedJsonLine(value: JsonValue, maximum?: number): string;
+export declare function projectDurableEvent(event: DurableEngineEvent): JsonObject;
+/** The ledger supplies lifecycle truth. Provider progress is explicitly transient. */
+export declare class EngineEventStream {
+    private readonly read;
+    private readonly emit;
+    private readonly observerError;
+    private readonly onDurable?;
+    private cursor;
+    constructor(read: (after: number) => DurableEngineEvent[], emit: (value: JsonObject) => void, after?: number, observerError?: (error: unknown) => void, onDurable?: ((event: DurableEngineEvent) => void) | undefined);
+    send(value: JsonObject): void;
+    flush(): void;
+    progress(event: TransientEngineEvent): void;
+}

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

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+import { EngineError } from './contracts.js';
+export const MAX_EVENT_CHARACTERS = 1_000_000;
+export const spanIdFor = (runId, sequence) => createHash('sha256').update(`${runId}:${sequence}`).digest('hex').slice(0, 16);
+export const traceIdFor = (runId) => createHash('sha256').update(runId).digest('hex').slice(0, 32);
+/** Bound log strings without dropping lifecycle identity or inventing usage. */
+export function boundedJsonLine(value, maximum = MAX_EVENT_CHARACTERS) {
+    const trim = (entry, depth = 0) => {
+        if (depth > 64)
+            throw new EngineError('output_limit', 'Event nesting exceeds 64 levels');
+        if (typeof entry === 'string')
+            return entry.length > 64_000 ? entry.slice(0, 63_980) + '\n[output truncated]' : entry;
+        if (Array.isArray(entry))
+            return entry.map(item => trim(item, depth + 1));
+        if (entry && typeof entry === 'object')
+            return Object.fromEntries(Object.entries(entry).map(([key, item]) => [key, trim(item, depth + 1)]));
+        return entry;
+    };
+    const line = JSON.stringify(trim(value));
+    if (line.length + 1 > maximum)
+        throw new EngineError('output_limit', 'Event exceeds the JSONL transport limit');
+    return line + '\n';
+}
+export function projectDurableEvent(event) {
+    const payload = event.payload && typeof event.payload === 'object' && !Array.isArray(event.payload) ? event.payload : {};
+    if (event.type === 'efficiency_updated')
+        return {
+            type: 'runtime-efficiency-event', schemaVersion: 1, eventId: `${event.runId}:${event.sequence}`,
+            sequence: event.sequence, runId: event.runId, timestamp: event.timestamp, ...(event.attemptId ? { attemptId: event.attemptId } : {}),
+            ...(event.nodePath ? { nodePath: event.nodePath } : {}), ...(event.branchId ? { branch: event.branchId } : {}),
+            kind: 'role-context', payload: event.payload,
+        };
+    return { type: 'workflow-event', event: {
+            ...payload, id: `${event.runId}:${event.sequence}`, sequence: event.sequence, runId: event.runId, traceId: traceIdFor(event.runId), spanId: spanIdFor(event.runId, event.sequence),
+            type: event.type, timestamp: event.timestamp,
+            ...(event.nodePath ? { nodePath: event.nodePath, stepId: event.nodePath } : {}),
+            ...(event.scopeId ? { scopeId: event.scopeId } : {}), ...(event.branchId ? { branch: event.branchId } : {}),
+            ...(event.visit === undefined ? {} : { visit: event.visit }), ...(event.attempt === undefined ? {} : { attempt: event.attempt }),
+            ...(event.attemptId ? { attemptId: event.attemptId } : {}),
+        } };
+}
+/** The ledger supplies lifecycle truth. Provider progress is explicitly transient. */
+export class EngineEventStream {
+    read;
+    emit;
+    observerError;
+    onDurable;
+    cursor;
+    constructor(read, emit, after = 0, observerError = () => { }, onDurable) {
+        this.read = read;
+        this.emit = emit;
+        this.observerError = observerError;
+        this.onDurable = onDurable;
+        this.cursor = after;
+    }
+    send(value) {
+        try {
+            this.emit(JSON.parse(boundedJsonLine(value)));
+        }
+        catch (error) {
+            try {
+                this.observerError(error);
+            }
+            catch { /* Observers cannot replay committed effects. */ }
+        }
+    }
+    flush() {
+        for (const event of this.read(this.cursor)) {
+            if (event.sequence <= this.cursor)
+                throw new EngineError('event_sequence_conflict', 'Durable events must advance monotonically');
+            try {
+                this.onDurable?.(event);
+            }
+            catch (error) {
+                try {
+                    this.observerError(error);
+                }
+                catch { /* Optional telemetry cannot affect committed work. */ }
+            }
+            this.send(projectDurableEvent(event));
+            this.cursor = event.sequence;
+        }
+    }
+    progress(event) {
+        const payload = event.payload && typeof event.payload === 'object' && !Array.isArray(event.payload) ? event.payload : { payload: event.payload };
+        this.send({ ...payload, type: event.type });
+    }
+}

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

@@ -0,0 +1,29 @@
+import { type AttemptFrame, type DurableEngineEvent, type EngineEffect, type NodeAdmission, type NodeExecutionPort, type PieceResult, type TerminalCommit, type TransientEngineEvent } from './contracts.js';
+import type { RunLedger } from './checkpoint/ledger.js';
+import type { EngineEventStream } from './events.js';
+/** Owns effect/concurrency windows across execution AND durable terminal commit. */
+export declare class DefinitionExecution implements NodeExecutionPort {
+    readonly ledger: RunLedger;
+    private readonly stream;
+    private readonly signal;
+    private readonly finalize?;
+    private readonly admissions;
+    private readonly held;
+    private readonly effects;
+    private readonly agents;
+    private readonly groups;
+    constructor(ledger: RunLedger, stream: EngineEventStream, signal: AbortSignal, concurrency?: number, finalize?: ((frame: AttemptFrame, result: PieceResult, effect: EngineEffect) => PieceResult) | undefined);
+    enter(input: NodeAdmission): Promise<AttemptFrame>;
+    execute(frame: AttemptFrame, effect: EngineEffect, operation: (signal: AbortSignal) => Promise<PieceResult>): Promise<PieceResult>;
+    terminal(frame: AttemptFrame, result: PieceResult): TerminalCommit;
+    interrupted(frame: AttemptFrame, error: unknown): Promise<void>;
+    failed(frame: AttemptFrame, error: unknown, options: {
+        retry: boolean;
+    }): Promise<{
+        retryable: boolean;
+    }>;
+    committed(events: DurableEngineEvent[]): void;
+    progress(event: TransientEngineEvent): void;
+    close(): void;
+    private release;
+}

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

@@ -0,0 +1,121 @@
+import { isGraphInterrupt } from '@langchain/langgraph';
+import { AgentExecutionError } from '../executor-types.js';
+import { EngineError } from './contracts.js';
+import { ConcurrencyGate, RepositoryEffectGate } from './concurrency.js';
+const COORDINATORS = new Set(['component', 'map', 'join', 'implementation']);
+const UNCERTAIN_EFFECT = new Set(['aborted', 'timeout', 'idle_timeout', 'lease_lost']);
+const errorDetails = (error) => ({
+    code: error instanceof EngineError || error instanceof AgentExecutionError ? error.code : 'piece_failed',
+    message: error instanceof Error ? error.message : String(error),
+});
+/** Owns effect/concurrency windows across execution AND durable terminal commit. */
+export class DefinitionExecution {
+    ledger;
+    stream;
+    signal;
+    finalize;
+    admissions = new Map();
+    held = new Map();
+    effects = new RepositoryEffectGate();
+    agents;
+    groups = new Map();
+    constructor(ledger, stream, signal, concurrency = 1, finalize) {
+        this.ledger = ledger;
+        this.stream = stream;
+        this.signal = signal;
+        this.finalize = finalize;
+        this.agents = new ConcurrencyGate(concurrency);
+    }
+    async enter(input) {
+        if (this.signal.aborted)
+            throw new EngineError('aborted', 'Execution cancelled before node admission');
+        const frame = this.ledger.enter(input);
+        this.admissions.set(frame.attemptId, input);
+        this.stream.flush();
+        return frame;
+    }
+    async execute(frame, effect, operation) {
+        const completed = this.ledger.resultFor(frame);
+        if (completed)
+            return structuredClone(completed);
+        const admission = this.admissions.get(frame.attemptId);
+        if (!admission)
+            throw new EngineError('attempt_mismatch', 'Node has not been admitted by this executor');
+        let effectRelease = () => { }, agentRelease = () => { };
+        const groupReleases = [];
+        try {
+            if (!COORDINATORS.has(admission.kind))
+                effectRelease = await this.effects.acquire(effect, this.signal);
+            if (admission.requiresAI && !COORDINATORS.has(admission.kind)) {
+                for (const limit of frame.scope.limits ?? []) {
+                    let group = this.groups.get(limit.id);
+                    if (!group) {
+                        group = new ConcurrencyGate(limit.concurrency);
+                        this.groups.set(limit.id, group);
+                    }
+                    if (group.capacity !== limit.concurrency)
+                        throw new EngineError('scope_conflict', 'A map concurrency limit cannot change within a run');
+                    groupReleases.push(await group.acquire(this.signal));
+                }
+                agentRelease = await this.agents.acquire(this.signal);
+            }
+            this.ledger.lease.assert(this.ledger.token);
+            if (this.signal.aborted)
+                throw new EngineError('aborted', 'Execution cancelled before effects');
+        }
+        catch (error) {
+            effectRelease();
+            agentRelease();
+            for (const release of groupReleases.reverse())
+                release();
+            throw error;
+        }
+        // LangGraph's saver releases this only after pending writes and terminal
+        // evidence commit. Releasing on function return admits a later write before
+        // the previous verification receipt is durable and can certify stale work.
+        this.held.set(frame.attemptId, () => { agentRelease(); for (const release of groupReleases.reverse())
+            release(); effectRelease(); });
+        const result = await operation(this.signal);
+        const current = this.ledger.scopeSnapshot(frame.scope.id);
+        return { ...result, usage: current.usage,
+            ...(effect === 'write' && !result.receipt ? { verified: null } : {}),
+        };
+    }
+    terminal(frame, result) {
+        const completed = this.ledger.resultFor(frame);
+        if (completed)
+            return this.ledger.terminal(frame, completed);
+        const input = this.admissions.get(frame.attemptId);
+        return this.ledger.terminal(frame, this.finalize && input && (!COORDINATORS.has(input.kind) || input.kind === 'implementation') ? this.finalize(frame, result, input.effect) : result);
+    }
+    async interrupted(frame, error) {
+        if (!isGraphInterrupt(error))
+            this.ledger.prepareInterruption(frame, errorDetails(error));
+        // The saver settles __interrupt__/__error__ with its ledger event. Keep the
+        // effect window until that transaction; process shutdown releases it too.
+    }
+    async failed(frame, error, options) {
+        const input = this.admissions.get(frame.attemptId), details = errorDetails(error);
+        const retryable = options.retry && input?.retry.retrySafe === true && !['aborted', 'lease_lost'].includes(details.code) && !(input.effect === 'write' && UNCERTAIN_EFFECT.has(details.code));
+        if (retryable) {
+            this.ledger.fail(frame, details, true);
+            this.release(frame.attemptId);
+            this.stream.flush();
+        }
+        // A final failure stays running until its atomic terminal marker commits.
+        return { retryable };
+    }
+    committed(events) {
+        for (const event of events)
+            if (event.attemptId && /^step_(?:succeeded|failed|blocked|paused|interrupted)$/.test(event.type))
+                this.release(event.attemptId);
+        this.stream.flush();
+    }
+    progress(event) { this.stream.progress(event); }
+    close() { for (const attemptId of this.held.keys())
+        this.release(attemptId); }
+    release(attemptId) {
+        this.held.get(attemptId)?.();
+        this.held.delete(attemptId);
+    }
+}

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

@@ -0,0 +1,11 @@
+import { type CoreDefinitionState, type JsonObject, type JsonValue } from './contracts.js';
+type Expression = {
+    evaluate(state: CoreDefinitionState): unknown;
+};
+/** Bounded regex subset: no backreferences, lookaround or quantified groups. */
+export declare function boundedPattern(pattern: string): RegExp;
+/** Recursive descent over a closed grammar; no eval or executable expression callbacks. */
+export declare function parseExpression(source: string): Expression;
+export declare function validateInterpolations(value: JsonValue): void;
+export declare function interpolateParams(params: JsonObject, vars: Record<string, JsonValue>): JsonObject;
+export {};

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

@@ -0,0 +1,172 @@
+import { EngineError } from './contracts.js';
+import { matchesPattern } from './regex.js';
+const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
+function invalid(message) { throw new EngineError('invalid_expression', message); }
+/** Bounded regex subset: no backreferences, lookaround or quantified groups. */
+export function boundedPattern(pattern) {
+    if (pattern.length > 200 || /\\[1-9]|\(\?|\)[*+?{]/.test(pattern))
+        invalid('Pattern uses unsupported or unbounded regular-expression features');
+    try {
+        return new RegExp(pattern);
+    }
+    catch {
+        return invalid('Invalid regular expression');
+    }
+}
+function lookup(state, path) {
+    const parts = path.split('.');
+    if (!['$outputs', '$vars', '$verified', '$attempts', '$item'].includes(parts[0]))
+        invalid(`Unavailable state channel ${parts[0]}`);
+    let value = state;
+    for (const part of parts) {
+        if (forbiddenKeys.has(part))
+            invalid('Prototype property access is not permitted');
+        if (!value || typeof value !== 'object' || !Object.hasOwn(value, part))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+/** Recursive descent over a closed grammar; no eval or executable expression callbacks. */
+export function parseExpression(source) {
+    if (!source.trim() || source.length > 4096)
+        invalid('Expression must contain 1–4096 characters');
+    const tokens = [];
+    let cursor = 0;
+    while (cursor < source.length) {
+        if (/\s/.test(source[cursor])) {
+            cursor += 1;
+            continue;
+        }
+        const rest = source.slice(cursor);
+        let match;
+        if ((match = /^(?:&&|\|\||==|!=|<=|>=|[!<>() ,])/.exec(rest))) {
+            tokens.push({ value: match[0], kind: 'symbol' });
+        }
+        else if ((match = /^\$(?:outputs|vars|verified|attempts|item)(?:\.[A-Za-z0-9_-]+)*/.exec(rest))) {
+            if (match[0].split('.').some(part => forbiddenKeys.has(part)))
+                invalid('Prototype property access is not permitted');
+            tokens.push({ value: match[0], kind: 'path' });
+        }
+        else if ((match = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|"(?:[^"\\\x00-\x1f]|\\(?:["\\/bfnrt]|u[0-9a-fA-F]{4}))*")/.exec(rest))) {
+            tokens.push({ value: match[0], kind: 'literal', literal: JSON.parse(match[0]) });
+        }
+        else if ((match = /^(?:exists|matches)\b/.exec(rest))) {
+            tokens.push({ value: match[0], kind: 'function' });
+        }
+        else if ((match = /^\/(?:[^/\\\r\n]|\\.)*\//.exec(rest))) {
+            tokens.push({ value: match[0], kind: 'regex', literal: boundedPattern(match[0].slice(1, -1)) });
+        }
+        else
+            invalid(`Unexpected expression token at ${cursor}`);
+        cursor += match[0].length;
+        if (tokens.length > 512)
+            invalid('Expression has too many tokens');
+    }
+    let index = 0;
+    function take(value) { if (tokens[index++]?.value !== value)
+        invalid(`Expected ${value}`); }
+    function primary(depth) {
+        if (depth > 32)
+            invalid('Expression nesting exceeds 32');
+        const token = tokens[index++];
+        if (!token)
+            return invalid('Unexpected end of expression');
+        if (token.value === '!') {
+            const operand = primary(depth + 1);
+            return { evaluate: state => !operand.evaluate(state) };
+        }
+        if (token.value === '(') {
+            const body = binary(0, depth + 1);
+            take(')');
+            return body;
+        }
+        if (token.kind === 'literal')
+            return { evaluate: () => token.literal };
+        if (token.kind === 'path')
+            return { evaluate: state => lookup(state, token.value) };
+        if (token.kind === 'function') {
+            take('(');
+            const operand = binary(0, depth + 1);
+            if (token.value === 'exists') {
+                take(')');
+                return { evaluate: state => operand.evaluate(state) !== undefined && operand.evaluate(state) !== null };
+            }
+            take(',');
+            const pattern = tokens[index++];
+            if (pattern?.kind !== 'regex')
+                invalid('matches requires a literal regular expression');
+            take(')');
+            return { evaluate: state => { const value = operand.evaluate(state); return typeof value === 'string' && matchesPattern(pattern.literal.source, value); } };
+        }
+        return invalid(`Unexpected ${token.value}`);
+    }
+    const precedence = { '||': 1, '&&': 2, '==': 3, '!=': 3, '<': 4, '<=': 4, '>': 4, '>=': 4 };
+    function binary(min, depth) {
+        let left = primary(depth);
+        while ((precedence[tokens[index]?.value] ?? -1) >= min) {
+            const operator = tokens[index++].value;
+            const right = binary(precedence[operator] + 1, depth + 1);
+            const previous = left;
+            left = { evaluate: state => {
+                    const a = previous.evaluate(state);
+                    if (operator === '&&')
+                        return Boolean(a) && Boolean(right.evaluate(state));
+                    if (operator === '||')
+                        return Boolean(a) || Boolean(right.evaluate(state));
+                    const b = right.evaluate(state);
+                    if (operator === '==')
+                        return a === b;
+                    if (operator === '!=')
+                        return a !== b;
+                    if (!((typeof a === 'number' && typeof b === 'number') || (typeof a === 'string' && typeof b === 'string')))
+                        return false;
+                    if (operator === '<')
+                        return a < b;
+                    if (operator === '<=')
+                        return a <= b;
+                    if (operator === '>')
+                        return a > b;
+                    return a >= b;
+                } };
+        }
+        return left;
+    }
+    const expression = binary(0, 0);
+    if (index !== tokens.length)
+        invalid('Unexpected trailing expression tokens');
+    return expression;
+}
+export function validateInterpolations(value) {
+    if (typeof value === 'string') {
+        const tokens = value.replaceAll('{{{{', '').match(/\{\{[^}]*\}\}/g) ?? [];
+        for (const token of tokens)
+            if (token.startsWith('{{run.') && !/^\{\{run\.[A-Za-z][A-Za-z0-9_-]*\}\}$/.test(token))
+                throw new EngineError('invalid_interpolation', `Invalid runtime variable ${token}`);
+    }
+    else if (Array.isArray(value))
+        value.forEach(validateInterpolations);
+    else if (value && typeof value === 'object')
+        Object.values(value).forEach(validateInterpolations);
+}
+export function interpolateParams(params, vars) {
+    function resolve(value) {
+        if (typeof value === 'string')
+            return value.replace(/\{\{\{\{|\{\{run\.([A-Za-z][A-Za-z0-9_-]*)\}\}/g, (token, name) => {
+                if (token === '{{{{')
+                    return '{{';
+                if (!name || !Object.hasOwn(vars, name))
+                    throw new EngineError('run_var_missing', `Runtime variable ${name ?? ''} is missing`);
+                const replacement = vars[name];
+                if (replacement !== null && typeof replacement === 'object')
+                    return JSON.stringify(replacement);
+                return String(replacement);
+            });
+        if (Array.isArray(value))
+            return value.map(resolve);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolve(entry)]));
+        return value;
+    }
+    return resolve(params);
+}

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

@@ -0,0 +1,28 @@
+import { type PipelineContext } from '../../pipeline/pipeline-state.js';
+import { type ExecutorRegistry } from '../executors.js';
+import { type JsonValue } from './contracts.js';
+export interface ForkRunOptions {
+    fromNodePath: string;
+    runId: string;
+    scopeId?: string;
+    visit?: number;
+    /** Retry a published child after a lost host acknowledgement. */
+    requestId?: string;
+    state?: {
+        $vars?: Record<string, JsonValue>;
+        $outputs?: Record<string, JsonValue>;
+    };
+    registry?: ExecutorRegistry;
+}
+/** A fork publishes an independently leased historical cut; the source is opened read-only. */
+export declare function forkRun(directory: string, options: ForkRunOptions): Promise<{
+    type: "runtime-forked";
+    runId: string;
+    forkOf: string;
+    fromNodePath: string;
+    scopeId: string;
+    visit: number;
+    directory: string;
+    context: PipelineContext;
+    revision: number;
+}>;