specrails-core 6.0.0 → 6.1.0

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

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { SqliteRunSaver } from './checkpoint/saver.js';
+import { compileWorkflowDefinition } from './compiler.js';
+import { DefinitionExecution } from './execution.js';
+import { RunPieceDependencies } from './piece-dependencies.js';
+import { createPieceRegistry } from './pieces/index.js';
+import { createImplementationAdapter } from './pieces/implementation.js';
+import { SqliteProjectStore } from './store/sqlite-store.js';
+/** Infrastructure is bound once to the frozen project and the current execution lease. */
+export async function composeDefinitionRuntime(database, ledger, admitted, stream, signal) {
+    const memory = await SqliteProjectStore.open(admitted.request.context.backlogRoot);
+    const deps = new RunPieceDependencies(admitted.request.context, admitted.request.config, admitted.registry, admitted.definition, ledger, path.dirname(database.filename), admitted.request.change, memory);
+    const execution = new DefinitionExecution(ledger, stream, signal, admitted.definition.policies?.concurrency ?? 1, (frame, result, effect) => deps.finalize(frame, result, effect));
+    try {
+        const saver = new SqliteRunSaver(database, ledger, { onEvents: events => execution.committed(events) });
+        const graph = compileWorkflowDefinition(admitted.definition, createPieceRegistry(deps), execution, {
+            roles: admitted.roles, checkpointer: saver,
+            collections: { tickets: JSON.parse(JSON.stringify(admitted.request.context.specs)), repositories: JSON.parse(JSON.stringify(admitted.request.context.repositories)) },
+            implementation: params => createImplementationAdapter(deps, { change: admitted.request.change, params }),
+        });
+        return { deps, execution, saver, graph, close: () => { execution.close(); memory.close(); } };
+    }
+    catch (error) {
+        execution.close();
+        memory.close();
+        throw error;
+    }
+}

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

@@ -0,0 +1,14 @@
+/** FIFO weighted permits prevent writers starving behind new read branches. */
+export declare class ConcurrencyGate {
+    readonly capacity: number;
+    private available;
+    private readonly queue;
+    constructor(capacity: number);
+    acquire(signal?: AbortSignal, weight?: number): Promise<() => void>;
+    private drain;
+}
+/** All branches share this gate; a write owns the complete repository effect window. */
+export declare class RepositoryEffectGate {
+    private readonly permits;
+    acquire(effect: 'read' | 'write', signal?: AbortSignal): Promise<() => void>;
+}

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

@@ -0,0 +1,55 @@
+import { EngineError } from './contracts.js';
+/** FIFO weighted permits prevent writers starving behind new read branches. */
+export class ConcurrencyGate {
+    capacity;
+    available;
+    queue = [];
+    constructor(capacity) {
+        this.capacity = capacity;
+        if (!Number.isSafeInteger(capacity) || capacity < 1)
+            throw new EngineError('invalid_arguments', 'Concurrency must be a positive integer');
+        this.available = capacity;
+    }
+    acquire(signal, weight = 1) {
+        if (!Number.isSafeInteger(weight) || weight < 1 || weight > this.capacity)
+            return Promise.reject(new EngineError('invalid_arguments', 'Invalid permit weight'));
+        if (signal?.aborted)
+            return Promise.reject(new EngineError('aborted', 'Execution cancelled while waiting for admission'));
+        return new Promise((resolve, reject) => {
+            const waiter = { weight, resolve, reject, signal, abort: () => {
+                    const index = this.queue.indexOf(waiter);
+                    if (index < 0)
+                        return;
+                    this.queue.splice(index, 1);
+                    signal?.removeEventListener('abort', waiter.abort);
+                    reject(new EngineError('aborted', 'Execution cancelled while waiting for admission'));
+                    this.drain();
+                } };
+            signal?.addEventListener('abort', waiter.abort, { once: true });
+            this.queue.push(waiter);
+            this.drain();
+        });
+    }
+    drain() {
+        while (this.queue.length && this.queue[0].weight <= this.available) {
+            const waiter = this.queue.shift();
+            waiter.signal?.removeEventListener('abort', waiter.abort);
+            this.available -= waiter.weight;
+            let released = false;
+            waiter.resolve(() => {
+                if (released)
+                    return;
+                released = true;
+                this.available += waiter.weight;
+                this.drain();
+            });
+        }
+    }
+}
+/** All branches share this gate; a write owns the complete repository effect window. */
+export class RepositoryEffectGate {
+    permits = new ConcurrencyGate(Number.MAX_SAFE_INTEGER);
+    acquire(effect, signal) {
+        return this.permits.acquire(signal, effect === 'write' ? this.permits.capacity : 1);
+    }
+}

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

@@ -0,0 +1,273 @@
+import type { JsonValue, WorkflowBudget } from '../workflow-types.js';
+export type { JsonValue, WorkflowBudget };
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type EngineEffect = 'read' | 'write';
+export type EngineStepStatus = 'running' | 'succeeded' | 'failed' | 'blocked' | 'paused' | 'interrupted';
+export type EngineRunStatus = EngineStepStatus | 'cancelled';
+/** Stable public LangGraph execution metadata; never parse private namespace keys. */
+export interface TaskIdentity {
+    checkpointThreadId: string;
+    checkpointId: string;
+    taskCheckpointNs: string;
+    taskId: string;
+}
+export interface ExecutionScope {
+    id: string;
+    nodePathPrefix: string;
+    branchId?: string;
+    /** Nested map limits; the run coordinator acquires them only around physical AI work. */
+    limits?: Array<{
+        id: string;
+        concurrency: number;
+    }>;
+}
+export interface ExecutionLease {
+    runId: string;
+    owner: string;
+    epoch: number;
+    expiresAt: number;
+}
+export interface AttemptFrame {
+    runId: string;
+    nodePath: string;
+    scope: ExecutionScope;
+    task: TaskIdentity;
+    visitId: string;
+    visit: number;
+    transition: number;
+    attemptId: string;
+    attempt: number;
+    leaseEpoch: number;
+}
+export interface NodeRetryPolicy {
+    maxAttempts: number;
+    retrySafe?: boolean;
+    initialIntervalMs?: number;
+}
+export interface NodeAdmission {
+    nodePath: string;
+    kind: string;
+    effect: EngineEffect;
+    requiresAI: boolean;
+    acceptsSteering?: boolean;
+    scope: ExecutionScope;
+    task: TaskIdentity;
+    retry: NodeRetryPolicy;
+}
+export interface HistoryEntry {
+    id: string;
+    transition: number;
+    attempt: number;
+    ordinal: number;
+    nodePath: string;
+    text: string;
+    truncated?: boolean;
+}
+/** Aggregate revision comes from the ledger; checkpoints cannot double-count it. */
+export interface EngineUsage {
+    revision: number;
+    invocations: number;
+    costUsd: number | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    knownCostUsd: number;
+    knownInputTokens: number;
+    knownOutputTokens: number;
+}
+export interface CandidateState {
+    hash: string;
+    atTransition: number;
+    revision: number;
+    /** Logical scope and exact metadata exclusions travel with a historical fork. */
+    scope?: JsonObject;
+}
+export interface VerifiedState {
+    receiptId: string;
+    candidateHash: string;
+    atTransition: number;
+    revision: number;
+}
+/** Evidence stays JSON; the verification adapter owns the legacy receipt format. */
+export interface ReceiptEvidence {
+    id: string;
+    candidateHash: string;
+    valid: boolean;
+    scope: 'full' | 'scoped';
+    evidence: JsonValue;
+}
+export interface EngineCompletion {
+    ok: boolean;
+    reasons: string[];
+    verified: boolean;
+}
+export interface EngineAnswer {
+    id: string;
+    transition: number;
+    attempt: number;
+    ordinal: number;
+    nodePath: string;
+    value: JsonValue;
+}
+export interface BranchResult {
+    id: string;
+    transition: number;
+    attempt: number;
+    ordinal: number;
+    index: number;
+    outcome: string;
+    output: JsonValue;
+}
+export interface BranchState {
+    total: number;
+    results: BranchResult[];
+    visitId?: string;
+    transition?: number;
+    done?: number;
+}
+export interface MapPlan {
+    frame: AttemptFrame;
+    items: JsonValue[];
+}
+export interface ComponentExit {
+    outcome: string;
+    transition: number;
+    completion: EngineCompletion;
+    status: 'succeeded' | 'failed' | 'blocked' | 'interrupted';
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface CoreDefinitionState {
+    $outputs: Record<string, JsonValue>;
+    $vars: Record<string, JsonValue>;
+    $history: HistoryEntry[];
+    $sessions: Record<string, {
+        sessionId: string;
+        identity: string;
+    }>;
+    $usage: EngineUsage;
+    $attempts: Record<string, number>;
+    $consecutiveFailures: {
+        revision: number;
+        count: number;
+    };
+    $candidate: CandidateState | null;
+    $verified: VerifiedState | null;
+    $answers: EngineAnswer[];
+    $branches: Record<string, BranchState>;
+    $maps: Record<string, MapPlan>;
+    $transitions: number;
+    $lastOutcome: Record<string, string>;
+    $item: {
+        index: number;
+        value: JsonValue;
+    } | null;
+    $scope: ExecutionScope;
+    $exit: ComponentExit | null;
+    $commit?: TerminalCommit;
+}
+/** Domain pieces propose results; only the execution adapter can settle them. */
+export interface PieceResult {
+    /** Native child-graph update, committed with its terminal marker; never a public output field. */
+    childUpdate?: JsonObject;
+    outcome: string;
+    status?: 'succeeded' | 'failed' | 'blocked' | 'interrupted';
+    output?: JsonValue;
+    history?: HistoryEntry[];
+    vars?: Record<string, JsonValue>;
+    session?: {
+        sessionId: string;
+        identity: string;
+    };
+    answers?: EngineAnswer[];
+    branches?: Record<string, BranchState>;
+    usage?: EngineUsage;
+    candidate?: CandidateState;
+    verified?: VerifiedState | null;
+    receipt?: ReceiptEvidence;
+    completion?: EngineCompletion;
+    /** Compiler-owned: a local component completion must never settle the parent run. */
+    completesRun?: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** This engine-owned channel is persisted with the matching task's pending writes. */
+export interface TerminalCommit {
+    schemaVersion: 1;
+    frame: AttemptFrame;
+    result: PieceResult;
+    digest: string;
+}
+export interface TransientEngineEvent {
+    type: 'agent-event' | 'verification-output' | 'span' | 'runtime-efficiency-event';
+    payload: JsonValue;
+}
+export interface HumanInterrupt {
+    kind: 'approval' | 'question' | 'gate';
+    prompt: string;
+    nodePath: string;
+    scopeId: string;
+    attemptId: string;
+}
+export interface PieceExecutionContext {
+    state: CoreDefinitionState;
+    frame: AttemptFrame;
+    signal: AbortSignal;
+    progress(event: TransientEngineEvent): void;
+    interrupt(request: HumanInterrupt): JsonValue;
+}
+export interface PieceDescriptor {
+    kind: string;
+    paramsSchema: JsonObject;
+    outcomes: readonly string[];
+    effect: EngineEffect | 'derived';
+    requiresAI: boolean;
+    storeAccess?: 'none' | 'read' | 'write';
+}
+export interface Piece {
+    descriptor: PieceDescriptor;
+    /** Exact labels can depend on sentinel mode, structured role output or component parameters. */
+    getOutcomes?(params: JsonObject): readonly string[];
+    getEffect?(params: JsonObject, roles: Readonly<Record<string, {
+        access: EngineEffect;
+    }>>): EngineEffect;
+    execute(params: JsonObject, context: PieceExecutionContext): Promise<PieceResult>;
+}
+/** Runtime coordination port; SQL, provider processes and locks stay out of compilation. */
+export interface NodeExecutionPort {
+    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>;
+    /** Only an approved retry settles here; final failure stays running until its marker commits. */
+    failed(frame: AttemptFrame, error: unknown, options: {
+        retry: boolean;
+    }): Promise<{
+        retryable: boolean;
+    }>;
+    progress(event: TransientEngineEvent): void;
+}
+export interface DurableEngineEvent {
+    sequence: number;
+    runId: string;
+    type: string;
+    timestamp: string;
+    nodePath?: string;
+    scopeId?: string;
+    branchId?: string;
+    visit?: number;
+    attempt?: number;
+    attemptId?: string;
+    payload: JsonValue;
+}
+/** Shared typed failure without leaking SQLite or LangGraph error objects into JSONL. */
+export declare class EngineError extends Error {
+    readonly code: string;
+    readonly details?: JsonValue | undefined;
+    constructor(code: string, message: string, details?: JsonValue | undefined);
+}

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

@@ -0,0 +1,11 @@
+/** Shared typed failure without leaking SQLite or LangGraph error objects into JSONL. */
+export class EngineError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'EngineError';
+    }
+}

package/dist/agent-runtime/engine/definition-schema.d.ts

@@ -0,0 +1,250 @@
+/** Public JSON schema; parity is checked against the packaged schema artifact. */
+export declare const workflowDefinitionSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://specrails.dev/schemas/workflow-definition/1";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schemaVersion", "id", "version", "title", "journal", "change", "entry", "maxTransitions", "roles", "nodes"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly const: 1;
+        };
+        readonly id: {
+            readonly type: "string";
+            readonly pattern: "^[a-z0-9][a-z0-9-]{0,63}$";
+        };
+        readonly version: {
+            readonly type: "string";
+            readonly pattern: "^[0-9a-f]{64}$";
+        };
+        readonly title: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 120;
+        };
+        readonly journal: {
+            readonly enum: readonly ["ledger-only", "implementation"];
+        };
+        readonly change: {
+            readonly enum: readonly ["new", "existing", "none"];
+        };
+        readonly entry: {
+            readonly $ref: "#/$defs/nodeId";
+        };
+        readonly maxTransitions: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 10000;
+        };
+        readonly budget: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly maxCostUsd: {
+                    readonly type: "number";
+                    readonly exclusiveMinimum: 0;
+                };
+                readonly maxTokens: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+                readonly maxDurationMs: {
+                    readonly type: "integer";
+                    readonly minimum: 1000;
+                };
+            };
+        };
+        readonly policies: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly failFast: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 10;
+                    readonly default: 2;
+                };
+                readonly noProgress: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 10;
+                    readonly default: 2;
+                };
+                readonly historyMaxChars: {
+                    readonly type: "integer";
+                    readonly minimum: 200;
+                    readonly maximum: 20000;
+                    readonly default: 1500;
+                };
+                readonly concurrency: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 8;
+                    readonly default: 1;
+                };
+            };
+        };
+        readonly roles: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/$defs/roleId";
+            };
+            readonly uniqueItems: true;
+        };
+        readonly nodes: {
+            readonly type: "object";
+            readonly minProperties: 1;
+            readonly propertyNames: {
+                readonly $ref: "#/$defs/nodeId";
+            };
+            readonly additionalProperties: {
+                readonly $ref: "#/$defs/node";
+            };
+        };
+        readonly components: {
+            readonly type: "object";
+            readonly propertyNames: {
+                readonly pattern: "^[a-z0-9][a-z0-9-]{0,63}$";
+            };
+            readonly additionalProperties: {
+                readonly $ref: "#/$defs/componentBody";
+            };
+        };
+        readonly delivery: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly requiresVerified: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+    };
+    readonly $defs: {
+        readonly nodeId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9][A-Za-z0-9_-]{0,119}$";
+            readonly not: {
+                readonly enum: readonly ["START", "END", "__start__", "__end__", "next"];
+            };
+        };
+        readonly roleId: {
+            readonly type: "string";
+            readonly pattern: "^[a-z][a-z0-9-]{0,63}$";
+        };
+        readonly engine: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["provider"];
+            readonly properties: {
+                readonly provider: {
+                    readonly type: "string";
+                };
+                readonly model: {
+                    readonly type: "string";
+                };
+                readonly effort: {
+                    readonly type: "string";
+                };
+                readonly thinking: {
+                    readonly enum: readonly ["on", "off"];
+                };
+            };
+        };
+        readonly retry: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly maxAttempts: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 10;
+                };
+                readonly backoffMs: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly maximum: 600000;
+                };
+                readonly retryOn: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly enum: readonly ["idle_timeout", "timeout", "provider_request_error", "session_not_found", "invalid_structured_output"];
+                    };
+                };
+            };
+        };
+        readonly ends: {
+            readonly type: "object";
+            readonly propertyNames: {
+                readonly pattern: "^[a-z][a-z0-9-]{0,31}$";
+            };
+            readonly additionalProperties: {
+                readonly oneOf: readonly [{
+                    readonly $ref: "#/$defs/nodeId";
+                }, {
+                    readonly type: "null";
+                }];
+            };
+        };
+        readonly node: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["kind", "params", "ends"];
+            readonly properties: {
+                readonly kind: {
+                    readonly enum: readonly ["prompt", "role-turn", "decider", "condition", "assign", "verify", "shell", "openspec-validate", "openspec-archive", "approval", "question", "gate", "map", "join", "component", "implementation", "end"];
+                };
+                readonly params: {
+                    readonly type: "object";
+                };
+                readonly ends: {
+                    readonly $ref: "#/$defs/ends";
+                };
+                readonly retry: {
+                    readonly $ref: "#/$defs/retry";
+                };
+                readonly label: {
+                    readonly type: "string";
+                    readonly maxLength: 80;
+                };
+            };
+        };
+        readonly componentBody: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["entry", "nodes"];
+            readonly properties: {
+                readonly entry: {
+                    readonly $ref: "#/$defs/nodeId";
+                };
+                readonly maxTransitions: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 10000;
+                };
+                readonly inputs: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly outputs: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly nodes: {
+                    readonly type: "object";
+                    readonly minProperties: 1;
+                    readonly propertyNames: {
+                        readonly $ref: "#/$defs/nodeId";
+                    };
+                    readonly additionalProperties: {
+                        readonly $ref: "#/$defs/node";
+                    };
+                };
+            };
+        };
+    };
+};