specrails-core 6.0.1 → 6.1.0

package/dist/agent-runtime/engine/storage/fork-allocation.js

@@ -0,0 +1,143 @@
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import path from 'node:path';
+import { contentDigest } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+import { ensurePrivateDirectory, privateSqlitePath } from './private-path.js';
+function flushDirectory(directory) {
+    if (process.platform === 'win32')
+        return;
+    const fd = openSync(directory, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** SQLite holds the construction lock across awaits and releases it on process
+ * death. The separate, flushed manifest survives that rollback. Directories are
+ * recorded by inode before their atomic rename, so recovery never removes a
+ * replacement directory or a child already published by Core.
+ */
+export class ForkAllocation {
+    lock;
+    directory;
+    parents;
+    manifest;
+    constructor(lock, directory, parents, requestId, digest) {
+        this.lock = lock;
+        this.directory = directory;
+        this.parents = parents;
+        this.manifest = { version: 1, requestId: requestId ?? null, digest, allocations: [] };
+    }
+    static async open(target, artifactRoot, requestId, digest) {
+        const directory = path.join(path.dirname(target), '.fork-allocations', contentDigest(target));
+        await ensurePrivateDirectory(directory);
+        const filename = path.join(directory, 'lock.sqlite');
+        try {
+            closeSync(openSync(filename, 'wx', 0o600));
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        const lock = new DatabaseSync(await privateSqlitePath(filename));
+        try {
+            lock.exec('PRAGMA busy_timeout=0; BEGIN IMMEDIATE');
+        }
+        catch (error) {
+            lock.close();
+            throw new EngineError('lease_held', `Fork construction is already active: ${String(error)}`);
+        }
+        return new ForkAllocation(lock, directory, [path.dirname(target), path.join(artifactRoot, 'openspec', 'changes')], requestId, digest);
+    }
+    /** Call only after ruling out a published child. No request ID means no retry. */
+    recover() {
+        const filename = path.join(this.directory, 'intent.json');
+        if (!existsSync(filename))
+            return;
+        const previous = JSON.parse(readFileSync(filename, 'utf8'));
+        if (previous.version === 1 && Array.isArray(previous.allocations) && previous.allocations.length === 0)
+            return;
+        if (!this.manifest.requestId || previous.version !== 1 || previous.requestId !== this.manifest.requestId ||
+            previous.digest !== this.manifest.digest || !Array.isArray(previous.allocations))
+            throw new EngineError('run_exists', 'Unpublished fork belongs to another request');
+        this.validate(previous);
+        this.manifest = previous;
+        this.cleanup();
+    }
+    /** Reserve an empty directory before any journal/artifact writes occur. */
+    reserve(target) {
+        if (!this.parents.includes(path.dirname(target)) || existsSync(target))
+            throw new EngineError('run_exists', 'Fork refuses to replace an existing allocation');
+        mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+        const allocation = { target, temporary: path.join(path.dirname(target), `.${path.basename(target)}.fork-${randomUUID()}`) };
+        this.manifest.allocations.push(allocation);
+        this.save();
+        mkdirSync(allocation.temporary, { mode: 0o700 });
+        const info = lstatSync(allocation.temporary, { bigint: true });
+        allocation.inode = String(info.ino);
+        allocation.device = String(info.dev);
+        allocation.birth = String(info.birthtimeNs);
+        this.save();
+        // A single construction lock serializes every request for this child.
+        if (existsSync(target))
+            throw new EngineError('run_exists', 'Fork allocation was concurrently created');
+        renameSync(allocation.temporary, target);
+        flushDirectory(path.dirname(target));
+    }
+    cleanup() {
+        this.validate(this.manifest);
+        // Validate every path before removing any: uncertain ownership is preserved.
+        for (const allocation of this.manifest.allocations)
+            for (const target of [allocation.target, allocation.temporary]) {
+                if (!existsSync(target))
+                    continue;
+                const info = lstatSync(target, { bigint: true });
+                if (!allocation.inode && target === allocation.temporary && info.isDirectory() && !info.isSymbolicLink())
+                    continue;
+                if (!info.isDirectory() || info.isSymbolicLink() || String(info.ino) !== allocation.inode || String(info.dev) !== allocation.device || String(info.birthtimeNs) !== allocation.birth)
+                    throw new EngineError('run_exists', 'Fork allocation ownership changed');
+            }
+        for (const allocation of [...this.manifest.allocations].reverse())
+            for (const target of [allocation.target, allocation.temporary]) {
+                if (!existsSync(target))
+                    continue;
+                if (!allocation.inode)
+                    rmdirSync(target); // A crash before recording its inode can leave only an empty temporary directory.
+                else
+                    rmSync(target, { recursive: true });
+                flushDirectory(path.dirname(target));
+            }
+        this.manifest.allocations = [];
+        this.save();
+    }
+    close() { try {
+        this.lock.exec('ROLLBACK');
+    }
+    finally {
+        this.lock.close();
+    } }
+    validate(manifest) {
+        for (const entry of manifest.allocations) {
+            if (typeof entry.target !== 'string' || typeof entry.temporary !== 'string' || !this.parents.includes(path.dirname(entry.target)) ||
+                path.dirname(entry.temporary) !== path.dirname(entry.target) || !path.basename(entry.temporary).startsWith(`.${path.basename(entry.target)}.fork-`))
+                throw new EngineError('unsafe_storage_path', 'Fork allocation escapes its frozen roots');
+        }
+    }
+    save() {
+        const temporary = path.join(this.directory, 'intent.tmp');
+        const fd = openSync(temporary, 'w', 0o600);
+        try {
+            writeFileSync(fd, JSON.stringify(this.manifest));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path.join(this.directory, 'intent.json'));
+        flushDirectory(this.directory);
+    }
+}

package/dist/agent-runtime/engine/storage/private-path.d.ts

@@ -0,0 +1,11 @@
+import { EngineError } from '../contracts.js';
+export declare class PersistenceError extends EngineError {
+    constructor(code: string, message: string);
+}
+/** This directory belongs to one run. Never apply this to the user's repository root. */
+export declare function ensurePrivateDirectory(directory: string): Promise<string>;
+/** Storage adapters use this before opening SQLite; reads never alter permissions. */
+export declare function privateSqlitePath(filename: string, options?: {
+    create?: boolean;
+    readOnly?: boolean;
+}): Promise<string>;

package/dist/agent-runtime/engine/storage/private-path.js

@@ -0,0 +1,74 @@
+import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { runCliProcess } from '../../cli-process.js';
+import { EngineError } from '../contracts.js';
+export class PersistenceError extends EngineError {
+    constructor(code, message) { super(code, message); this.name = 'PersistenceError'; }
+}
+const aclScript = String.raw `$ErrorActionPreference='Stop'; $target=$env:SPECRAILS_PRIVATE_PATH;
+$identity=[System.Security.Principal.WindowsIdentity]::GetCurrent();
+$isFile=[System.IO.File]::Exists($target);
+$acl=if($isFile){New-Object System.Security.AccessControl.FileSecurity}else{New-Object System.Security.AccessControl.DirectorySecurity};
+$acl.SetOwner($identity.User); $acl.SetAccessRuleProtection($true,$false);
+$inherit=if($isFile){[System.Security.AccessControl.InheritanceFlags]::None}else{[System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'};
+foreach($sid in @($identity.User,(New-Object System.Security.Principal.SecurityIdentifier('S-1-5-18')))) {
+ $acl.AddAccessRule((New-Object System.Security.AccessControl.FileSystemAccessRule($sid,'FullControl',$inherit,[System.Security.AccessControl.PropagationFlags]::None,'Allow')))
+}; Set-Acl -LiteralPath $target -AclObject $acl;
+$actual=Get-Acl -LiteralPath $target;
+if($actual.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $identity.User.Value -or !$actual.AreAccessRulesProtected){throw 'Private directory owner/protection mismatch'};
+foreach($entry in $actual.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])) {
+ if($entry.IdentityReference.Value -notin @($identity.User.Value,'S-1-5-18') -or $entry.AccessControlType -ne 'Allow'){throw 'Private directory grants broad access'}
+}`;
+async function setPrivateWindowsAcl(target, cwd) {
+    const env = { ...process.env, SPECRAILS_PRIVATE_PATH: target };
+    for (const key of Object.keys(env))
+        if (key.toLowerCase() === 'psmodulepath')
+            delete env[key];
+    const result = await runCliProcess({ command: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(aclScript, 'utf16le').toString('base64')] }, { cwd, timeoutMs: 30_000, env });
+    if (result.exitCode !== 0)
+        throw new PersistenceError('private_storage_unavailable', `Cannot protect engine storage: ${result.stderr.slice(0, 2000)}`);
+}
+/** This directory belongs to one run. Never apply this to the user's repository root. */
+export async function ensurePrivateDirectory(directory) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (lstatSync(directory).isSymbolicLink())
+        throw new PersistenceError('unsafe_storage_path', 'A engine storage directory cannot be a symbolic link');
+    const resolved = realpathSync(directory);
+    if (process.platform === 'win32') {
+        await setPrivateWindowsAcl(resolved, resolved);
+    }
+    else
+        chmodSync(resolved, 0o700);
+    return resolved;
+}
+/** Storage adapters use this before opening SQLite; reads never alter permissions. */
+export async function privateSqlitePath(filename, options = {}) {
+    const absolute = path.resolve(filename);
+    if (!options.create && !existsSync(absolute))
+        throw new PersistenceError('run_not_found', 'Engine database does not exist');
+    if (options.create && existsSync(absolute))
+        throw new PersistenceError('run_exists', 'Engine database already exists');
+    if (options.readOnly && options.create)
+        throw new EngineError('invalid_arguments', 'Read-only mode cannot create a database');
+    const parentPath = path.dirname(absolute);
+    if (options.readOnly && lstatSync(parentPath).isSymbolicLink())
+        throw new PersistenceError('unsafe_storage_path', 'An engine storage directory cannot be a symbolic link');
+    const parent = options.readOnly ? realpathSync(parentPath) : await ensurePrivateDirectory(parentPath);
+    const target = path.join(parent, path.basename(absolute));
+    if (existsSync(target)) {
+        const info = lstatSync(target);
+        if (!info.isFile() || info.isSymbolicLink() || info.nlink > 1)
+            throw new PersistenceError('unsafe_storage_path', 'Engine database must be a regular unlinked file');
+    }
+    if (options.create) {
+        const fd = openSync(target, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | (constants.O_NOFOLLOW ?? 0), 0o600);
+        closeSync(fd);
+    }
+    if (!options.readOnly) {
+        if (process.platform !== 'win32')
+            chmodSync(target, 0o600);
+        else
+            await setPrivateWindowsAcl(target, parent);
+    }
+    return target;
+}

package/dist/agent-runtime/engine/store/sqlite-store.d.ts

@@ -0,0 +1,26 @@
+import { BaseStore, type Item, type Operation, type OperationResults, type SearchItem, type SearchOperation } from '@langchain/langgraph-checkpoint';
+import { type JsonObject } from '../contracts.js';
+export interface ProjectMemory {
+    get(namespace: string[], key: string): Promise<Item | null>;
+    search(namespace: string[], options?: Omit<SearchOperation, 'namespacePrefix'>): Promise<SearchItem[]>;
+    put(namespace: string[], key: string, value: JsonObject): Promise<void>;
+    delete(namespace: string[], key: string): Promise<void>;
+}
+/** One local project owns this store. It is independent of run history and is never copied by fork. */
+export declare class SqliteProjectStore extends BaseStore {
+    readonly filename: string;
+    private readonly sqlite;
+    private readonly readOnly;
+    private closed;
+    private constructor();
+    static open(backlogRoot: string, options?: {
+        readOnly?: boolean;
+    }): Promise<SqliteProjectStore>;
+    batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
+    private operation;
+    /** Composition grants only a declared capability and namespace subtree to a piece. */
+    forAccess(access: 'none' | 'read' | 'write', options?: {
+        namespacePrefixes?: readonly (readonly string[])[];
+    }): ProjectMemory;
+    close(): void;
+}

package/dist/agent-runtime/engine/store/sqlite-store.js

@@ -0,0 +1,227 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { BaseStore } from '@langchain/langgraph-checkpoint';
+import { canonicalJson } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+import { privateSqlitePath } from '../storage/private-path.js';
+const DEFAULT_NAMESPACES = [['roles', '*', 'sessions'], ['verification', 'known-commands'], ['review', 'notes']];
+const matchesPrefix = (namespace, prefix) => namespace.length >= prefix.length && prefix.every((part, index) => part === '*' || part === namespace[index]);
+const fail = (message) => { throw new EngineError('invalid_arguments', message); };
+function namespaceCheck(namespace, empty = false) {
+    if (!Array.isArray(namespace) || (!empty && !namespace.length) || namespace.length > 16 || namespace.some(part => typeof part !== 'string' || !part || part.length > 128 || part.includes('\0')))
+        fail('Store namespaces require 1–16 bounded string components');
+}
+function page(value, defaultValue, max) {
+    const result = value ?? defaultValue;
+    if (!Number.isSafeInteger(result) || result < 0 || result > max)
+        fail('Invalid bounded store pagination');
+    return result;
+}
+const equal = (a, b) => a !== undefined && b !== undefined && canonicalJson(a) === canonicalJson(b);
+function filterCheck(filter) {
+    if (filter === undefined)
+        return;
+    if (!filter || typeof filter !== 'object' || Array.isArray(filter))
+        fail('Store filters must be JSON objects');
+    canonicalJson(filter);
+    for (const expected of Object.values(filter)) {
+        if (expected && typeof expected === 'object' && !Array.isArray(expected) && Object.keys(expected).some(key => key.startsWith('$'))) {
+            for (const operator of Object.keys(expected))
+                if (!['$eq', '$ne', '$gt', '$gte', '$lt', '$lte'].includes(operator))
+                    fail(`Unsupported store filter ${operator}`);
+        }
+    }
+}
+function filtered(value, filter) {
+    return Object.entries(filter ?? {}).every(([key, expected]) => {
+        const actual = Object.hasOwn(value, key) ? value[key] : undefined;
+        if (expected && typeof expected === 'object' && !Array.isArray(expected) && Object.keys(expected).some(name => name.startsWith('$'))) {
+            return Object.entries(expected).every(([operator, operand]) => {
+                if (operator === '$eq')
+                    return equal(actual, operand);
+                if (operator === '$ne')
+                    return !equal(actual, operand);
+                if (!['$gt', '$gte', '$lt', '$lte'].includes(operator))
+                    return fail(`Unsupported store filter ${operator}`);
+                if (typeof actual !== typeof operand || !['number', 'string'].includes(typeof actual))
+                    return false;
+                const left = actual, right = operand;
+                return operator === '$gt' ? left > right : operator === '$gte' ? left >= right : operator === '$lt' ? left < right : left <= right;
+            });
+        }
+        return equal(actual, expected);
+    });
+}
+const item = (row) => ({ namespace: JSON.parse(String(row.namespace)), key: String(row.key), value: JSON.parse(String(row.value)), createdAt: new Date(String(row.created_at)), updatedAt: new Date(String(row.updated_at)) });
+/** One local project owns this store. It is independent of run history and is never copied by fork. */
+export class SqliteProjectStore extends BaseStore {
+    filename;
+    sqlite;
+    readOnly;
+    closed = false;
+    constructor(filename, sqlite, readOnly) {
+        super();
+        this.filename = filename;
+        this.sqlite = sqlite;
+        this.readOnly = readOnly;
+    }
+    static async open(backlogRoot, options = {}) {
+        const filename = path.join(path.resolve(backlogRoot), '.specrails', 'engine-store.sqlite');
+        let target;
+        try {
+            target = await privateSqlitePath(filename, { create: !options.readOnly && !existsSync(filename), readOnly: options.readOnly });
+        }
+        catch (error) {
+            // Independent runs may race to create the same project-owned file.
+            if (error.code !== 'EEXIST')
+                throw error;
+            target = await privateSqlitePath(filename, { readOnly: options.readOnly });
+        }
+        const sqlite = new DatabaseSync(target, { readOnly: options.readOnly ?? false });
+        try {
+            sqlite.exec('PRAGMA busy_timeout=5000; PRAGMA foreign_keys=ON;');
+            if (!options.readOnly) {
+                sqlite.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; BEGIN IMMEDIATE;');
+                try {
+                    const version = Number(sqlite.prepare('PRAGMA user_version').get().user_version);
+                    if (version === 0)
+                        sqlite.exec('CREATE TABLE items(namespace TEXT NOT NULL,key TEXT NOT NULL,value TEXT NOT NULL,created_at TEXT NOT NULL,updated_at TEXT NOT NULL,PRIMARY KEY(namespace,key)); PRAGMA user_version=1;');
+                    else if (version !== 1)
+                        throw new EngineError('store_incompatible', `Unsupported project store schema ${version}`);
+                    sqlite.exec('COMMIT');
+                }
+                catch (error) {
+                    sqlite.exec('ROLLBACK');
+                    throw error;
+                }
+            }
+            else if (Number(sqlite.prepare('PRAGMA user_version').get().user_version) !== 1)
+                throw new EngineError('store_incompatible', 'Unsupported project store schema');
+            return new SqliteProjectStore(target, sqlite, options.readOnly ?? false);
+        }
+        catch (error) {
+            sqlite.close();
+            throw error;
+        }
+    }
+    async batch(operations) {
+        if (!Array.isArray(operations) || operations.length > 1000)
+            fail('A store batch is limited to 1000 operations');
+        if (this.closed)
+            throw new EngineError('store_closed', 'Project store is closed');
+        const write = operations.some(operation => 'value' in operation);
+        if (write && this.readOnly)
+            throw new EngineError('store_access_denied', 'This store connection is read-only');
+        this.sqlite.exec(write ? 'BEGIN IMMEDIATE' : 'BEGIN');
+        try {
+            const results = operations.map(operation => this.operation(operation));
+            this.sqlite.exec('COMMIT');
+            return results;
+        }
+        catch (error) {
+            this.sqlite.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    operation(operation) {
+        if ('namespace' in operation) {
+            namespaceCheck(operation.namespace);
+            if (typeof operation.key !== 'string' || !operation.key || operation.key.length > 256 || operation.key.includes('\0'))
+                fail('Store keys require 1–256 characters');
+            const namespace = canonicalJson(operation.namespace);
+            if ('value' in operation) {
+                if (operation.index !== undefined && operation.index !== false)
+                    throw new EngineError('store_index_unsupported', 'Project memory does not configure semantic indexing');
+                if (operation.value === null)
+                    this.sqlite.prepare('DELETE FROM items WHERE namespace=? AND key=?').run(namespace, operation.key);
+                else {
+                    if (!operation.value || typeof operation.value !== 'object' || Array.isArray(operation.value))
+                        fail('Store values must be JSON objects');
+                    const encoded = canonicalJson(operation.value);
+                    if (Buffer.byteLength(encoded) > 2 * 1024 * 1024)
+                        throw new EngineError('output_limit', 'Project store item exceeds 2 MiB');
+                    const at = new Date().toISOString();
+                    this.sqlite.prepare('INSERT INTO items VALUES(?,?,?,?,?) ON CONFLICT(namespace,key) DO UPDATE SET value=excluded.value,updated_at=excluded.updated_at').run(namespace, operation.key, encoded, at, at);
+                }
+                return undefined;
+            }
+            const row = this.sqlite.prepare('SELECT * FROM items WHERE namespace=? AND key=?').get(namespace, operation.key);
+            return row ? item(row) : null;
+        }
+        if ('namespacePrefix' in operation) {
+            namespaceCheck(operation.namespacePrefix, true);
+            if (operation.query !== undefined)
+                throw new EngineError('store_query_unsupported', 'Project memory supports metadata filters, without semantic search');
+            const limit = page(operation.limit, 10, 1000), offset = page(operation.offset, 0, 1_000_000);
+            filterCheck(operation.filter);
+            if (!limit)
+                return [];
+            // Prefix predicates are parameterized JSON array components, never SQL identifiers.
+            const prefix = operation.namespacePrefix;
+            const where = ['json_array_length(namespace)>=?', ...prefix.map((_, i) => `json_extract(namespace,'$[${i}]')=?`)].join(' AND ');
+            const result = [];
+            let skipped = 0;
+            for (const row of this.sqlite.prepare(`SELECT * FROM items WHERE ${where} ORDER BY namespace,key`).iterate(prefix.length, ...prefix)) {
+                const found = item(row);
+                if (!filtered(found.value, operation.filter))
+                    continue;
+                if (skipped++ < offset)
+                    continue;
+                result.push(found);
+                if (result.length === limit)
+                    break;
+            }
+            return result;
+        }
+        const limit = page(operation.limit, 100, 1000), offset = page(operation.offset, 0, 1_000_000), maxDepth = operation.maxDepth === undefined ? 16 : page(operation.maxDepth, 16, 16);
+        if (!maxDepth)
+            fail('Namespace maximum depth must be positive');
+        const conditions = operation.matchConditions ?? [];
+        for (const condition of conditions) {
+            namespaceCheck(condition.path, true);
+            if (!['prefix', 'suffix'].includes(condition.matchType))
+                fail('Invalid namespace match type');
+        }
+        if (!limit)
+            return [];
+        const seen = new Set(), result = [];
+        let skipped = 0;
+        for (const row of this.sqlite.prepare('SELECT DISTINCT namespace FROM items ORDER BY namespace').iterate()) {
+            const namespace = JSON.parse(String(row.namespace));
+            if (!conditions.every(condition => condition.matchType === 'prefix' ? matchesPrefix(namespace, condition.path) : matchesPrefix([...namespace].reverse(), [...condition.path].reverse())))
+                continue;
+            const selected = namespace.slice(0, maxDepth), encoded = canonicalJson(selected);
+            if (seen.has(encoded))
+                continue;
+            seen.add(encoded);
+            if (skipped++ < offset)
+                continue;
+            result.push(selected);
+            if (result.length === limit)
+                break;
+        }
+        return result;
+    }
+    /** Composition grants only a declared capability and namespace subtree to a piece. */
+    forAccess(access, options = {}) {
+        const allowed = (options.namespacePrefixes ?? DEFAULT_NAMESPACES).map(prefix => [...prefix]);
+        for (const prefix of allowed)
+            namespaceCheck(prefix);
+        const authorize = (namespace, write = false) => {
+            namespaceCheck(namespace);
+            if (access === 'none' || (write && access !== 'write') || !allowed.some(prefix => matchesPrefix(namespace, prefix)))
+                throw new EngineError('store_access_denied', 'Piece has no declared access to this project memory namespace');
+        };
+        return Object.freeze({
+            get: async (namespace, key) => { authorize(namespace); return this.get(namespace, key); },
+            search: async (namespace, options) => { authorize(namespace); return this.search(namespace, options); },
+            put: async (namespace, key, value) => { authorize(namespace, true); await this.put(namespace, key, value); },
+            delete: async (namespace, key) => { authorize(namespace, true); await this.delete(namespace, key); },
+        });
+    }
+    close() { if (!this.closed) {
+        this.sqlite.close();
+        this.closed = true;
+    } }
+}

package/dist/agent-runtime/evaluation-corpus.d.ts

@@ -11,3 +11,128 @@ export interface EvaluationCase {
     correction?: 'verification' | 'review';
 }
 export declare const EVALUATION_CORPUS: EvaluationCase[];
+/** Published reference definitions use the same independently checked behavioral corpus. */
+export declare const DEFINITION_EVALUATION_CORPUS: readonly [{
+    schemaVersion: number;
+    id: string;
+    title: string;
+    journal: string;
+    change: string;
+    entry: string;
+    maxTransitions: number;
+    roles: string[];
+    nodes: {
+        implement: {
+            kind: string;
+            params: {
+                approvalBeforeArchive: boolean;
+            };
+            ends: {
+                next: string;
+                rejected: string;
+                failed: string;
+            };
+        };
+        done: {
+            kind: string;
+            params: {
+                outcome: string;
+                requiresVerified: boolean;
+            };
+            ends: {};
+        };
+        failed: {
+            kind: string;
+            params: {
+                outcome: string;
+            };
+            ends: {};
+        };
+    };
+    version: string;
+}, {
+    schemaVersion: number;
+    id: string;
+    title: string;
+    journal: string;
+    change: string;
+    entry: string;
+    maxTransitions: number;
+    roles: string[];
+    nodes: {
+        work: {
+            kind: string;
+            params: {
+                ref: string;
+            };
+            ends: {
+                next: string;
+                failed: string;
+            };
+        };
+        done: {
+            kind: string;
+            params: {
+                outcome: string;
+                requiresVerified: boolean;
+            };
+            ends: {};
+        };
+        failed: {
+            kind: string;
+            params: {
+                outcome: string;
+            };
+            ends: {};
+        };
+        verify: {
+            kind: string;
+            params: {
+                commands: string;
+            };
+            ends: {
+                pass: string;
+                fail: string;
+                failed: string;
+            };
+        };
+    };
+    components: {
+        work: {
+            entry: string;
+            nodes: {
+                implement: {
+                    kind: string;
+                    params: {
+                        approvalBeforeArchive: boolean;
+                    };
+                    ends: {
+                        next: string;
+                        rejected: string;
+                        failed: string;
+                    };
+                };
+                done: {
+                    kind: string;
+                    params: {
+                        outcome: string;
+                        exit: string;
+                    };
+                    ends: {};
+                };
+                failed: {
+                    kind: string;
+                    params: {
+                        outcome: string;
+                        exit: string;
+                    };
+                    ends: {};
+                };
+            };
+        };
+    };
+    delivery: {
+        requiresVerified: boolean;
+    };
+    version: string;
+}];

package/dist/agent-runtime/evaluation-corpus.js

@@ -1,3 +1,5 @@
+import implementation from './engine/__fixtures__/implementation.json' with { type: 'json' };
+import componentImplementation from './engine/__fixtures__/implementation-component.json' with { type: 'json' };
 export const EVALUATION_CORPUS = [
     { id: 'static-tetris', verification: 'assert.deepStrictEqual(api.clearRows([[1,1]]), [[0,0]])', description: 'Clear complete rows in a static browser game without removing partial rows.', repositories: ['game'], source: 'exports.clearRows = board => board', solution: 'exports.clearRows = board => { const remaining = board.filter(row => row.some(cell => !cell)); return [...Array.from({length: board.length - remaining.length}, () => Array(board[0].length).fill(0)), ...remaining.map(row => [...row])]; }', defects: ['exports.clearRows = board => board', 'exports.clearRows = board => board.filter(row => row.every(Boolean))'], oracle: 'assert.deepStrictEqual(api.clearRows([[1,1],[1,0],[1,1]]), [[0,0],[0,0],[1,0]]); assert.deepStrictEqual(api.clearRows([[0,1],[1,0]]), [[0,1],[1,0]]);' },
     { id: 'local-tested-feature', verification: 'assert.strictEqual(api.subtotal([]), 0)', description: 'Calculate an integer-cent subtotal including repeated quantities and empty baskets.', repositories: ['shop'], source: 'exports.subtotal = items => 0', solution: 'exports.subtotal = items => items.reduce((sum, item) => sum + item.cents * item.quantity, 0)', defects: ['exports.subtotal = items => items.length', 'exports.subtotal = items => items.reduce((sum, item) => sum + item.cents, 0)'], oracle: 'assert.strictEqual(api.subtotal([]), 0); assert.strictEqual(api.subtotal([{cents: 125, quantity: 3}, {cents: 20, quantity: 2}]), 415);' },
@@ -5,3 +7,5 @@ export const EVALUATION_CORPUS = [
     { id: 'verification-correction', verification: 'assert.strictEqual(api.clamp(11, 0, 10), 10)', description: 'Clamp values to both boundaries, including an already valid value.', repositories: ['math'], source: 'exports.clamp = value => value', solution: 'exports.clamp = (value, min, max) => Math.min(max, Math.max(min, value))', defects: ['exports.clamp = (value, min, max) => Math.max(min, value)', 'exports.clamp = (value, min, max) => Math.min(max, value)'], oracle: 'assert.strictEqual(api.clamp(-1, 0, 10), 0); assert.strictEqual(api.clamp(11, 0, 10), 10); assert.strictEqual(api.clamp(5, 0, 10), 5);', correction: 'verification' },
     { id: 'review-correction', verification: 'assert.strictEqual(typeof api.unique, "function")', description: 'Deduplicate stable values while preserving the first occurrence order.', repositories: ['collections'], source: 'exports.unique = values => values', solution: 'exports.unique = values => [...new Set(values)]', defects: ['exports.unique = values => [...new Set(values)].sort()', 'exports.unique = values => values'], oracle: 'assert.deepStrictEqual(api.unique([3, 1, 3, 2, 1]), [3, 1, 2]); assert.deepStrictEqual(api.unique([]), []);', correction: 'review' },
 ];
+/** Published reference definitions use the same independently checked behavioral corpus. */
+export const DEFINITION_EVALUATION_CORPUS = [implementation, componentImplementation];

package/dist/agent-runtime/evaluation.d.ts

@@ -1,5 +1,8 @@
 import type { RuntimeConfig } from './executor-types.js';
-interface EvaluationOptions {
+export interface EvaluationOptions {
+    capturePrompts?: boolean;
+    definition?: unknown;
+    caseIds?: string[];
     output: string;
     config?: RuntimeConfig;
     maxCostUsd?: number;
@@ -7,7 +10,8 @@ interface EvaluationOptions {
     repetitions?: number;
 }
 export declare function runEvaluation(options: EvaluationOptions): Promise<{
-    schemaVersion: number;
+    acceptedCases: number;
+    allCasesAccepted: boolean;
     experiment: string;
     noExtraInvocations: boolean;
     mode: string;
@@ -40,5 +44,7 @@ export declare function runEvaluation(options: EvaluationOptions): Promise<{
     stopReason: string | null;
     reportedSpendUsd: number;
     observations: Record<string, unknown>[];
+    definitionHash?: string | null | undefined;
+    schemaVersion: number;
+    isDefinitionEvaluation: boolean;
 }>;
-export {};