specrails-core 6.0.1 → 6.2.0

package/dist/agent-runtime/engine/piece-dependencies.js

@@ -0,0 +1,240 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fingerprintCandidate, persistCheckEvidence, readCandidateScope, pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
+import { resolveRoleDescriptor } from '../config.js';
+import { prepareOpenSpec, roleOpenSpecContext } from '../openspec.js';
+import { contentDigest } from './canonical-json.js';
+import { EngineError } from './contracts.js';
+import { definitionNodeAt, invocationStepContext, roleAt } from './invocation-context.js';
+import { deriveImplementationBinding } from './pieces/implementation-binding.js';
+const json = (value) => JSON.parse(JSON.stringify(value));
+/** Adapters are bound to one frozen project, definition and execution lease. */
+export class RunPieceDependencies {
+    context;
+    config;
+    registry;
+    definition;
+    ledger;
+    directory;
+    change;
+    projectMemory;
+    policies;
+    constructor(context, config, registry, definition, ledger, directory, change, projectMemory) {
+        this.context = context;
+        this.config = config;
+        this.registry = registry;
+        this.definition = definition;
+        this.ledger = ledger;
+        this.directory = directory;
+        this.change = change;
+        this.projectMemory = projectMemory;
+        this.policies = definition.policies;
+    }
+    memory(context) {
+        if (!this.projectMemory)
+            throw new EngineError('memory_unavailable', 'Project memory is not bound to this execution');
+        const kind = this.ledger.db.get('visits', { visit_id: context.frame.visitId })?.kind;
+        const prefixes = kind === 'verify' ? [['verification', 'known-commands']] : kind === 'role-turn' ? [['roles', roleAt(this.definition, context.frame.nodePath), 'sessions'], ['review', 'notes']] : [];
+        return this.projectMemory.forAccess(prefixes.length ? 'write' : 'none', { namespacePrefixes: prefixes });
+    }
+    implementationBindings() {
+        return this.ledger.db.sqlite.prepare("SELECT value_json FROM piece_state WHERE run_id=? AND key='binding:implementation'").all(this.ledger.runId)
+            .map(row => JSON.parse(String(row.value_json)))
+            .filter(binding => binding.parentRunId === this.context.runId);
+    }
+    bindImplementation(context, change, shared = false) {
+        const scoped = shared ? { ...context, frame: { ...context.frame, nodePath: context.frame.scope.nodePathPrefix } } : context;
+        const binding = deriveImplementationBinding(this.context, scoped, change);
+        if (shared)
+            binding.shared = true;
+        const previous = shared ? this.ledger.readScopedPieceState(context.frame, binding.nodePath, 'binding:implementation') : this.ledger.readPieceState(context.frame, 'binding:implementation');
+        if (previous !== undefined && contentDigest(previous) !== contentDigest(binding))
+            throw new EngineError('scope_mismatch', 'Implementation binding changed within a frozen run');
+        if (previous === undefined) {
+            if (shared)
+                this.ledger.writeScopedPieceState(context.frame, binding.nodePath, 'binding:implementation', json(binding));
+            else
+                this.ledger.writePieceState(context.frame, 'binding:implementation', json(binding));
+        }
+        return binding;
+    }
+    candidateScope() {
+        const row = this.ledger.run();
+        const inherited = row.fork_of && row.candidate_json ? JSON.parse(String(row.candidate_json)).scope : undefined;
+        const base = this.definition.journal === 'implementation' && existsSync(path.join(pipelineStateDirectory(this.context), 'state.json'))
+            ? readCandidateScope(this.context)
+            : inherited ? this.inheritedCandidateScope(inherited)
+                : { context: this.context, scopeHash: contentDigest(this.context), artifactExclusions: this.change ? ['openspec/changes/' + this.change] : [] };
+        if (inherited && this.change)
+            base.artifactExclusions = [...new Set([...base.artifactExclusions, 'openspec/changes/' + this.change])];
+        const bindings = this.implementationBindings(), repositoryExclusions = Object.fromEntries(Object.entries(base.repositoryExclusions ?? {}).map(([id, paths]) => [id, [...paths]]));
+        for (const binding of bindings) {
+            const exclusions = existsSync(path.join(binding.directory, 'state.json')) ? readCandidateScope(binding.context).artifactExclusions : ['openspec/changes/' + binding.change];
+            const repository = this.context.repositories.find(item => item.id === binding.context.artifactRepositoryId);
+            const prefix = path.relative(repository.path, binding.context.artifactRoot).split(path.sep).join('/');
+            const paths = exclusions.map(relative => prefix ? prefix + '/' + relative : relative);
+            repositoryExclusions[repository.id] = [...new Set([...(repositoryExclusions[repository.id] ?? []), ...paths])];
+        }
+        return { ...base, runtimeExclusions: [...new Set([...(base.runtimeExclusions ?? []), pipelineStateDirectory(this.context), ...bindings.map(binding => binding.directory), ...(this.projectMemory ? ['', '-wal', '-shm'].map(suffix => this.projectMemory.filename + suffix) : [])])], repositoryExclusions };
+    }
+    inheritedCandidateScope(value) {
+        const strings = (items) => Array.isArray(items) && items.every(item => typeof item === 'string');
+        if (typeof value.scopeHash !== 'string' || !strings(value.artifactExclusions) || !strings(value.runtimeExclusions)
+            || !value.repositoryExclusions || typeof value.repositoryExclusions !== 'object' || Array.isArray(value.repositoryExclusions)
+            || !Object.values(value.repositoryExclusions).every(strings))
+            throw new EngineError('storage_corrupt', 'Inherited candidate scope is malformed');
+        return { context: this.context, scopeHash: value.scopeHash, artifactExclusions: value.artifactExclusions,
+            runtimeExclusions: value.runtimeExclusions, repositoryExclusions: value.repositoryExclusions };
+    }
+    candidate(transition, revision) {
+        const scope = this.candidateScope();
+        return { hash: fingerprintCandidate(scope), atTransition: transition, revision,
+            scope: { scopeHash: scope.scopeHash, artifactExclusions: [...scope.artifactExclusions],
+                runtimeExclusions: [...(scope.runtimeExclusions ?? [])],
+                repositoryExclusions: Object.fromEntries(Object.entries(scope.repositoryExclusions ?? {}).map(([id, paths]) => [id, [...paths]])) } };
+    }
+    implementationExclusions(_context) {
+        const scope = this.candidateScope();
+        return { runtimeExclusions: [pipelineStateDirectory(this.context), ...(scope.runtimeExclusions ?? [])], repositoryExclusions: scope.repositoryExclusions ?? {} };
+    }
+    fingerprint() { return fingerprintCandidate(this.candidateScope()); }
+    initializeCandidate() {
+        if (this.ledger.run().candidate_json)
+            return;
+        const candidate = this.candidate(0, 1);
+        this.ledger.db.transaction('candidate-initialized', () => {
+            this.ledger.lease.assert(this.ledger.token);
+            this.ledger.db.put('runs', { ...this.ledger.run(), candidate_json: JSON.stringify(candidate), candidate_revision: candidate.revision });
+        });
+    }
+    executionSnapshot(context) {
+        const snapshot = this.ledger.scopeSnapshot(context.frame.scope.id), hash = this.fingerprint();
+        const candidate = snapshot.candidate?.hash === hash ? snapshot.candidate : this.candidate(context.frame.transition, Number(this.ledger.run().candidate_revision) + 1);
+        return { candidate, verified: snapshot.verified?.candidateHash === hash ? snapshot.verified : null };
+    }
+    /** Write admission revokes certification; the archive may check its immutable pre-write checkpoint against a real receipt. */
+    verifiedBeforeWrite(context) {
+        const verified = context.state.$verified;
+        if (!verified || verified.candidateHash !== this.fingerprint())
+            return null;
+        const receipt = this.ledger.db.get('receipts', { receipt_id: verified.receiptId });
+        if (!receipt || receipt.run_id !== this.ledger.runId || receipt.valid !== 1 || receipt.candidate_hash !== verified.candidateHash)
+            return null;
+        const evidence = JSON.parse(String(receipt.receipt_json));
+        return evidence.scope === 'full' ? verified : null;
+    }
+    /** Only the execution owner proposes protected candidate/receipt channels. */
+    finalize(frame, result, effect) {
+        const hash = this.fingerprint(), snapshot = this.ledger.scopeSnapshot(frame.scope.id);
+        const candidate = effect === 'write' ? this.candidate(frame.transition, Number(this.ledger.run().candidate_revision) + 1)
+            : snapshot.candidate ?? this.candidate(frame.transition, 1);
+        const binding = this.implementationBindings().find(value => (frame.scope.id === value.scopeId || frame.scope.id.startsWith(value.scopeId + '/')) && (frame.nodePath === value.nodePath || frame.nodePath.startsWith(value.nodePath + '/')));
+        const scoped = binding && binding.context.runId !== this.context.runId;
+        if (scoped && result.receipt)
+            result = { ...result, receipt: { ...result.receipt, candidateHash: hash, scope: 'scoped' }, verified: null };
+        const receipt = result.receipt;
+        const node = definitionNodeAt(this.definition, frame.nodePath);
+        const kind = node?.kind ?? this.ledger.db.get('visits', { visit_id: frame.visitId })?.kind;
+        const evidence = receipt?.evidence;
+        const certifies = result.verified !== null && ['verify', 'implementation', 'implementation-step'].includes(String(kind)) && receipt?.valid && receipt.scope === 'full' && !!evidence?.commands?.length && !evidence.unverifiedRepositories?.length;
+        if (receipt?.valid && receipt.candidateHash !== hash)
+            return { ...result, outcome: 'fail',
+                ...(effect === 'write' ? { candidate } : {}), verified: null,
+                receipt: { ...receipt, valid: false, evidence: json({ ...receipt.evidence, valid: false, reason: 'Candidate changed before terminal commit' }) },
+                output: { receiptId: receipt.id, valid: false, reason: 'Candidate changed before terminal commit' }, };
+        return { ...result, ...(effect === 'write' ? { candidate } : {}),
+            ...(certifies ? { verified: { receiptId: receipt.id, candidateHash: hash, atTransition: frame.transition, revision: candidate.revision } }
+                : effect === 'write' || snapshot.verified?.candidateHash !== hash ? { verified: null } : {}),
+        };
+    }
+    operationState(context) {
+        return [...this.ledger.scopeSnapshot(context.frame.scope.id).attempts].reverse()
+            .find(attempt => attempt.result?.childUpdate?.operationState !== undefined)?.result?.childUpdate;
+    }
+    artifactContracts(context) {
+        const owner = context.frame.scope.nodePathPrefix;
+        const keyOf = (key) => 'contract:artifacts:' + key;
+        return { get: key => this.ledger.readScopedPieceState(context.frame, owner, keyOf(key)),
+            set: (key, value) => this.ledger.writeScopedPieceState(context.frame, owner, keyOf(key), value) };
+    }
+    memo(context) {
+        const keyOf = (key) => 'memo:' + context.frame.visitId + ':' + key;
+        return { get: key => this.ledger.readPieceState(context.frame, keyOf(key)), set: (key, value) => this.ledger.writePieceState(context.frame, keyOf(key), value) };
+    }
+    roleState(context) {
+        return {
+            read: () => {
+                const value = this.ledger.readScopedPieceState(context.frame, context.frame.scope.nodePathPrefix, 'session:roles');
+                if (value === undefined)
+                    return { sessions: {}, routes: {} };
+                if (!value || typeof value !== 'object' || Array.isArray(value) || !value.sessions || !value.routes)
+                    throw new EngineError('storage_corrupt', 'Scoped role state is malformed');
+                return structuredClone(value);
+            },
+            write: value => this.ledger.writeScopedPieceState(context.frame, context.frame.scope.nodePathPrefix, 'session:roles', json(value)),
+        };
+    }
+    stepContext(context) {
+        const step = invocationStepContext(this.ledger, this.definition, context);
+        if (definitionNodeAt(this.definition, context.frame.nodePath)?.kind !== 'implementation-step')
+            return step;
+        const phase = (path) => {
+            const node = definitionNodeAt(this.definition, path);
+            return node?.kind === 'implementation-step' ? String(node.params.phase) : path;
+        };
+        const checkpoint = step.checkpoint;
+        return { ...step, checkpoint: { ...checkpoint,
+                nextStep: checkpoint.nextStep ? phase(checkpoint.nextStep) : null,
+                steps: Object.fromEntries(Object.entries(checkpoint.steps).map(([key, value]) => [phase(key), { ...value, id: phase(key) }])),
+                history: checkpoint.history.map(value => ({ ...value, stepId: phase(value.stepId) })),
+                events: checkpoint.events.map(value => ({ ...value, ...(value.stepId ? { stepId: phase(value.stepId) } : {}) })),
+                ...(checkpoint.pendingApproval ? { pendingApproval: { ...checkpoint.pendingApproval, stepId: phase(checkpoint.pendingApproval.stepId) } } : {}),
+                ...(checkpoint.pendingQuestion ? { pendingQuestion: { ...checkpoint.pendingQuestion, stepId: phase(checkpoint.pendingQuestion.stepId) } } : {}),
+            } };
+    }
+    settleResult(context, key, value, invocation) {
+        if (!invocation.invocationId)
+            throw new EngineError('invocation_mismatch', 'A response memo requires its durable invocation ID');
+        this.ledger.settleInvocation(context.frame, { ...invocation, invocationId: invocation.invocationId }, { key: 'memo:' + context.frame.visitId + ':' + key, value });
+    }
+    artifactDirectory(context) {
+        const target = path.join(this.directory, 'artifacts', contentDigest({ scope: context.frame.scope.id, node: context.frame.nodePath }));
+        mkdirSync(target, { recursive: true, mode: 0o700 });
+        return target;
+    }
+    openspec(context) {
+        const roles = this.definition.roles.map(role => resolveRoleDescriptor(this.config, role)).filter(role => role.openspecSkill);
+        if (!roles.length)
+            return {};
+        if (!this.change)
+            throw new EngineError('invalid_arguments', 'OpenSpec roles require a frozen change name');
+        const directory = this.artifactDirectory(context), prepared = prepareOpenSpec(this.context.artifactRoot, this.change, directory);
+        return Object.fromEntries(roles.map(role => {
+            const provider = this.config.providers.find(item => item.id === role.provider);
+            return [role.id, roleOpenSpecContext(prepared, this.context.artifactRoot, this.change, directory, role, provider?.kind === 'cli' ? provider.cli : 'claude')];
+        }));
+    }
+    verification(context) {
+        const candidateHash = this.fingerprint(), scope = this.candidateScope();
+        const row = this.ledger.db.sqlite.prepare("SELECT receipt_json FROM receipts WHERE run_id=? AND valid=1 AND candidate_hash=? ORDER BY created_at DESC LIMIT 1").get(this.ledger.runId, candidateHash);
+        const previous = row ? JSON.parse(String(row.receipt_json)).evidence : undefined;
+        return {
+            candidateHash, scopeHash: scope.scopeHash, ...(previous ? { previous } : {}),
+            isCurrent: () => { this.ledger.lease.assert(this.ledger.token); return this.fingerprint() === candidateHash; },
+            persistCheck: (result, planHash, candidate) => {
+                this.ledger.lease.assert(this.ledger.token);
+                // Retain the existing bounded evidence format and paginated CLI reader.
+                // These are diagnostic artifacts; only the SQLite terminal transaction
+                // can certify this candidate and advance the workflow.
+                persistCheckEvidence(this.context, result, planHash, candidate);
+                this.ledger.writePieceState(context.frame, 'evidence:check:' + result.evidenceId, json({ ...result, planHash, candidateHash: candidate }));
+            },
+            commitReceipt: receipt => {
+                this.ledger.lease.assert(this.ledger.token);
+                const result = this.fingerprint() === candidateHash ? receipt : { ...receipt, valid: false, reason: 'Candidate changed during verification' };
+                this.ledger.writePieceState(context.frame, 'evidence:receipt:' + receipt.id, json(result));
+                return result;
+            },
+        };
+    }
+}

package/dist/agent-runtime/engine/piece-registry.d.ts

@@ -0,0 +1,19 @@
+import { type JsonObject, type Piece, type EngineEffect, type PieceDescriptor } from './contracts.js';
+import type { DefinitionIssue, RoleCatalog } from './definition-types.js';
+/**
+ * Version of the published piece catalog and observable piece behavior. Bump
+ * when either changes; retained runtime packages preserve earlier semantics.
+ */
+export declare const NODE_KINDS_VERSION = 7;
+/** Immutable bindings supplied by Core's composition root; user definitions cannot register code. */
+export declare class PieceRegistry {
+    private readonly entries;
+    constructor(pieces: readonly Piece[]);
+    get(kind: string): Piece;
+    catalog(): PieceDescriptor[];
+    /** Registered kinds in registration order: the `nodeKinds` advertised by `runtime api` and the integration contract. */
+    kinds(): string[];
+    validateParams(kind: string, params: JsonObject, path: string): DefinitionIssue[];
+    outcomes(kind: string, params: JsonObject): readonly string[];
+    effect(kind: string, params: JsonObject, roles: RoleCatalog): EngineEffect;
+}

package/dist/agent-runtime/engine/piece-registry.js

@@ -0,0 +1,62 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { EngineError } from './contracts.js';
+function freezeData(value) {
+    if (value && typeof value === 'object') {
+        Object.values(value).forEach(freezeData);
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * Version of the published piece catalog and observable piece behavior. Bump
+ * when either changes; retained runtime packages preserve earlier semantics.
+ */
+export const NODE_KINDS_VERSION = 7;
+/** Immutable bindings supplied by Core's composition root; user definitions cannot register code. */
+export class PieceRegistry {
+    entries = new Map();
+    constructor(pieces) {
+        const ajv = new Ajv2020({ allErrors: true, strict: true, validateFormats: false, ownProperties: true });
+        for (const piece of pieces) {
+            const descriptor = freezeData(structuredClone(piece.descriptor));
+            if (this.entries.has(descriptor.kind))
+                throw new EngineError('duplicate_piece', `Duplicate piece ${descriptor.kind}`);
+            if (descriptor.effect === 'derived' && !piece.getEffect)
+                throw new EngineError('invalid_piece', `Derived piece ${descriptor.kind} requires getEffect`);
+            if (new Set(descriptor.outcomes).size !== descriptor.outcomes.length)
+                throw new EngineError('invalid_piece', 'Duplicate outcome labels');
+            this.entries.set(descriptor.kind, { piece: Object.freeze({ ...piece, descriptor }), validate: ajv.compile(descriptor.paramsSchema) });
+        }
+    }
+    get(kind) {
+        const entry = this.entries.get(kind);
+        if (!entry)
+            throw new EngineError('unknown_piece', `Piece ${kind} is not implemented by this runtime`);
+        return entry.piece;
+    }
+    catalog() { return [...this.entries.values()].map(({ piece }) => structuredClone(piece.descriptor)); }
+    /** Registered kinds in registration order: the `nodeKinds` advertised by `runtime api` and the integration contract. */
+    kinds() { return [...this.entries.keys()]; }
+    validateParams(kind, params, path) {
+        const entry = this.entries.get(kind);
+        if (!entry)
+            return [{ code: 'unknown_piece', path, message: `Piece ${kind} is not implemented by this runtime` }];
+        if (entry.validate(params))
+            return [];
+        return (entry.validate.errors ?? []).map(error => ({ code: 'invalid_piece_params', path: path + '/params' + error.instancePath, message: error.message ?? 'Invalid piece parameters' }));
+    }
+    outcomes(kind, params) {
+        const piece = this.get(kind);
+        const outcomes = piece.getOutcomes?.(params) ?? piece.descriptor.outcomes;
+        if (new Set(outcomes).size !== outcomes.length || outcomes.some(value => !/^[a-z][a-z0-9-]{0,31}$/.test(value)))
+            throw new EngineError('invalid_piece', `Invalid outcomes for ${kind}`);
+        return outcomes;
+    }
+    effect(kind, params, roles) {
+        const piece = this.get(kind);
+        const effect = piece.getEffect?.(params, roles) ?? piece.descriptor.effect;
+        if (effect !== 'read' && effect !== 'write')
+            throw new EngineError('invalid_piece', `Unresolved effect for ${kind}`);
+        return effect;
+    }
+}

package/dist/agent-runtime/engine/pieces/artifact-contract.d.ts

@@ -0,0 +1,4 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+/** A reusable artifact invariant, with no agent roles, phase order or successor policy. */
+export declare function artifactContractPiece(bindings: PieceDependencyProvider): Piece;

package/dist/agent-runtime/engine/pieces/artifact-contract.js

@@ -0,0 +1,70 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { artifactPath } from '../../openspec.js';
+import { contentDigest } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+import { idSchema, paramsSchema, text } from './shared.js';
+/** A reusable artifact invariant, with no agent roles, phase order or successor policy. */
+export function artifactContractPiece(bindings) {
+    return {
+        descriptor: { kind: 'artifact-contract', paramsSchema: paramsSchema({
+                change: { type: 'string', minLength: 1, maxLength: 128 }, contractId: idSchema, action: { enum: ['freeze', 'check'] },
+                requireCompletedTasks: { type: 'boolean' },
+            }, ['change', 'contractId', 'action']), outcomes: ['pass', 'fail', 'failed'], effect: 'read', requiresAI: false },
+        async execute(params, context) {
+            const deps = bindings(), change = text(params.change);
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(change) || change.length > 64)
+                throw new EngineError('invalid_arguments', 'Invalid change identifier');
+            const store = deps.artifactContracts?.(context);
+            if (!store)
+                throw new EngineError('artifact_contract_unavailable', 'Scoped artifact contracts are not bound');
+            const directory = 'openspec/changes/' + change;
+            const files = {};
+            let bytes = 0;
+            const read = (relative) => {
+                const source = readFileSync(artifactPath(deps.context.artifactRoot, directory + '/' + relative), 'utf8');
+                bytes += Buffer.byteLength(source);
+                if (bytes > 2 * 1024 * 1024 || Object.keys(files).length >= 200)
+                    throw new EngineError('output_limit', 'Artifact contract exceeds its read limit');
+                return source;
+            };
+            try {
+                for (const name of ['proposal.md', 'design.md', 'tasks.md'])
+                    files[name] = read(name);
+                const walk = (relative) => {
+                    for (const entry of readdirSync(artifactPath(deps.context.artifactRoot, directory + '/' + relative), { withFileTypes: true })) {
+                        const child = relative + '/' + entry.name;
+                        if (entry.isSymbolicLink())
+                            throw new EngineError('artifact_scope_mismatch', 'Artifact contracts reject symlinks');
+                        if (entry.isDirectory())
+                            walk(child);
+                        else if (entry.isFile() && entry.name.endsWith('.md'))
+                            files[child] = read(child);
+                    }
+                };
+                walk('specs');
+            }
+            catch (error) {
+                if (error instanceof EngineError)
+                    throw error;
+                return { outcome: 'fail', output: { reason: 'required_artifacts_missing' } };
+            }
+            if (!Object.keys(files).some(name => name.startsWith('specs/')) || Object.values(files).some(source => !source.trim()))
+                return { outcome: 'fail', output: { reason: 'empty_artifacts' } };
+            const tasks = [...files['tasks.md'].matchAll(/^\s*[-*]\s+\[([ xX])\]\s+(.+)$/gm)];
+            if (!tasks.length)
+                return { outcome: 'fail', output: { reason: 'tasks_missing' } };
+            // Completion may change checkboxes, never the approved task descriptions.
+            files['tasks.md'] = files['tasks.md'].replace(/^(\s*[-*]\s+\[)[ xX](\]\s+)/gm, '$1 $2');
+            const fingerprint = contentDigest(files), key = text(params.contractId);
+            if (params.action === 'freeze')
+                store.set(key, { fingerprint });
+            else {
+                const frozen = store.get(key);
+                if (!frozen || frozen.fingerprint !== fingerprint)
+                    return { outcome: 'fail', output: { reason: frozen ? 'artifacts_changed' : 'contract_missing' } };
+            }
+            const incomplete = tasks.filter(task => task[1] === ' ').length;
+            return { outcome: params.requireCompletedTasks && incomplete ? 'fail' : 'pass', output: { fingerprint, tasks: tasks.length, incomplete } };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/assign.d.ts

@@ -0,0 +1,4 @@
+import { type Piece } from '../contracts.js';
+/** Pure scoped state updates. The runtime commits the complete result through
+ * the same fenced transaction as every other piece, with no separate store. */
+export declare function assignPiece(): Piece;

package/dist/agent-runtime/engine/pieces/assign.js

@@ -0,0 +1,35 @@
+import { EngineError } from '../contracts.js';
+import { paramsSchema, variableNameSchema } from './shared.js';
+const safeInteger = { type: 'integer', minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER, default: 1 };
+const assignments = (values) => ({
+    type: 'object', minProperties: 1, maxProperties: 64,
+    propertyNames: variableNameSchema, additionalProperties: values,
+});
+/** Pure scoped state updates. The runtime commits the complete result through
+ * the same fenced transaction as every other piece, with no separate store. */
+export function assignPiece() {
+    return {
+        descriptor: {
+            kind: 'assign', effect: 'read', requiresAI: false, outcomes: ['next', 'failed'],
+            paramsSchema: { ...paramsSchema({ set: assignments(true), increment: assignments(safeInteger) }), minProperties: 1 },
+        },
+        async execute(params, context) {
+            const set = (params.set ?? {});
+            const increments = (params.increment ?? {});
+            const names = [...Object.keys(set), ...Object.keys(increments)];
+            if (names.length > 64 || new Set(names).size !== names.length) {
+                throw new EngineError('invalid_assignment', 'Assign at most 64 distinct variables; set and increment cannot overlap');
+            }
+            const vars = Object.fromEntries(Object.entries(set));
+            for (const [name, delta] of Object.entries(increments)) {
+                const previous = context.state.$vars[name];
+                if (typeof previous !== 'number' || typeof delta !== 'number' ||
+                    !Number.isSafeInteger(previous) || !Number.isSafeInteger(delta) || !Number.isSafeInteger(previous + delta)) {
+                    throw new EngineError('invalid_assignment', `Variable ${name} must contain a safe integer and remain within its range`);
+                }
+                vars[name] = previous + delta;
+            }
+            return { outcome: 'next', vars, output: { vars } };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/control.d.ts

@@ -0,0 +1,5 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+export declare function controlPieces(bindings: PieceDependencyProvider): Piece[];
+/** Composition kinds are compiled as actual child graphs, never ordinary opaque calls. */
+export declare function compositionPieces(): Piece[];

package/dist/agent-runtime/engine/pieces/control.js

@@ -0,0 +1,53 @@
+import { EngineError } from '../contracts.js';
+import { parseExpression } from '../expressions.js';
+import { answerEntry, idSchema, paramsSchema, positiveInteger, stringSchema, text } from './shared.js';
+export function controlPieces(bindings) {
+    const pieces = [{
+            descriptor: { kind: 'condition', paramsSchema: paramsSchema({ expr: { ...stringSchema, minLength: 1, maxLength: 4096 } }, ['expr']), outcomes: ['true', 'false'], effect: 'read', requiresAI: false },
+            async execute(params, context) {
+                try {
+                    return { outcome: parseExpression(text(params.expr)).evaluate(context.state) ? 'true' : 'false' };
+                }
+                catch (error) {
+                    return { outcome: 'false', output: { error: error instanceof Error ? error.message : String(error) },
+                        completion: { ok: false, verified: false, reasons: ['condition_error:' + context.frame.nodePath] } };
+                }
+            },
+        }, {
+            descriptor: { kind: 'end', paramsSchema: paramsSchema({ outcome: { enum: ['success', 'failure'] }, requiresVerified: { type: 'boolean' }, reason: stringSchema, exit: idSchema }, ['outcome']), outcomes: [], effect: 'read', requiresAI: false },
+            async execute(params, context) {
+                const { candidate, verified } = bindings().executionSnapshot(context);
+                const current = verified !== null && candidate !== null && verified.candidateHash === candidate.hash;
+                const reasons = typeof params.reason === 'string' && params.reason ? [params.reason] : [];
+                if (params.requiresVerified && !current)
+                    reasons.push('unverified');
+                return { outcome: text(params.outcome), completion: { ok: params.outcome === 'success' && !(params.requiresVerified && !current), verified: current, reasons } };
+            },
+        }];
+    for (const kind of ['approval', 'question', 'gate']) {
+        const field = kind === 'question' ? 'text' : 'reason';
+        pieces.push({
+            descriptor: { kind, paramsSchema: paramsSchema({ [field]: { ...stringSchema, minLength: 1 }, bindCandidate: { type: 'boolean' }, enabled: { type: 'boolean' } }, [field]), outcomes: ['next'], effect: 'read', requiresAI: false },
+            async execute(params, context) {
+                const memo = bindings().memo(context);
+                const bound = params.bindCandidate ? memo.get('approval-candidate') ?? bindings().executionSnapshot(context).candidate?.hash ?? null : undefined;
+                if (params.bindCandidate && memo.get('approval-candidate') === undefined)
+                    memo.set('approval-candidate', bound);
+                const response = kind === 'approval' && params.enabled === false ? { approved: true } : context.interrupt({ kind, prompt: text(params[field]), nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
+                return { outcome: 'next', output: { response, ...(params.bindCandidate ? { candidateHash: bound } : {}) }, ...(kind === 'question' ? { answers: [answerEntry(context, response)] } : {}) };
+            },
+        });
+    }
+    return pieces;
+}
+/** Composition kinds are compiled as actual child graphs, never ordinary opaque calls. */
+export function compositionPieces() {
+    const execute = async (_params, _context) => { throw new EngineError('composition_required', 'Composition pieces require a compiled child graph'); };
+    const getEffect = () => { throw new EngineError('composition_required', 'Composition effects require the compiled component body'); };
+    return [
+        { descriptor: { kind: 'component', paramsSchema: paramsSchema({ ref: idSchema, inputs: { type: 'object', additionalProperties: stringSchema } }, ['ref']), outcomes: ['next', 'failed'], effect: 'derived', requiresAI: false }, execute, getEffect },
+        { descriptor: { kind: 'map', paramsSchema: paramsSchema({ over: { oneOf: [{ enum: ['tickets', 'repositories'] }, paramsSchema({ outputsOf: idSchema, path: stringSchema }, ['outputsOf', 'path'])] }, body: idSchema, concurrency: { ...positiveInteger, maximum: 8 } }, ['over', 'body']), outcomes: ['next'], effect: 'derived', requiresAI: false }, execute, getEffect },
+        { descriptor: { kind: 'implementation', paramsSchema: paramsSchema({ attempts: { ...positiveInteger, maximum: 100 }, approvalBeforeArchive: { type: 'boolean' }, reviewPolicy: paramsSchema({ minScore: { type: 'number', minimum: 0, maximum: 100 }, aspects: { type: 'object', additionalProperties: { type: 'number', minimum: 0, maximum: 100 } } }) }), outcomes: ['next', 'rejected', 'failed'], effect: 'write', requiresAI: true }, execute },
+        { descriptor: { kind: 'join', paramsSchema: paramsSchema({ reduce: { enum: ['collect', 'all-ok', 'any-ok'] } }, ['reduce']), outcomes: ['next', 'fail'], effect: 'read', requiresAI: false }, execute },
+    ];
+}

package/dist/agent-runtime/engine/pieces/decider.d.ts

@@ -0,0 +1,5 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+/** Desktop's evidence-oriented decision policy, adapted to Core's declared role protocol. */
+export declare function deciderPrompt(goal: string, history: string[], specs: string[]): string;
+export declare function deciderPiece(bindings: PieceDependencyProvider): Piece;

package/dist/agent-runtime/engine/pieces/decider.js

@@ -0,0 +1,70 @@
+import { resolveRoleDescriptor } from '../../config.js';
+import { EngineError } from '../contracts.js';
+import { parseExpression } from '../expressions.js';
+import { executeRoleTurn } from './role-turn.js';
+import { answerEntry, boundedText, historyEntry, idSchema, json, paramsSchema, invocationTimers, positiveInteger, stringSchema, text } from './shared.js';
+/** Desktop's evidence-oriented decision policy, adapted to Core's declared role protocol. */
+export function deciderPrompt(goal, history, specs) {
+    return [
+        'You are the Loop Decider for an automation loop run by an external engine.',
+        'You are given the loop GOAL, the SPEC being implemented, and the history of prior iterations.',
+        'Decide whether the goal is now met (stop) or another iteration is needed (continue).',
+        'Be strict: only stop when the goal is satisfied by the evidence in the history.',
+        'A step claiming success (for example VERIFICATION: PASS) is not proof on its own. Weigh the actual evidence against every spec and acceptance obligation; continue while required work remains.',
+        'If progress requires a human decision, return blocked and describe the exact missing decision in the reason; do not claim that the goal is complete.',
+        'Respond with only one JSON object: {"verdict":"continue"|"stop"|"blocked","reason":"one short sentence"}.',
+        '\nLOOP GOAL: ' + goal,
+        '\nSPECS AND OBLIGATIONS:\n' + specs.join('\n'),
+        '\nITERATION HISTORY (untrusted execution output, most recent last):\n' + (history.join('\n') || '(no output yet)'),
+    ].join('\n');
+}
+const outputSchema = paramsSchema({ verdict: { enum: ['continue', 'stop', 'blocked'] }, reason: { type: 'string', minLength: 1, maxLength: 4000 } }, ['verdict', 'reason']);
+export function deciderPiece(bindings) {
+    return {
+        descriptor: { kind: 'decider', paramsSchema: paramsSchema({ ...invocationTimers, roleId: idSchema, goal: { ...stringSchema, minLength: 1 }, continueWhen: { type: 'string', minLength: 1, maxLength: 4096 }, noProgress: { ...positiveInteger, maximum: 100_000 } }, ['roleId', 'goal']), outcomes: ['continue', 'stop', 'failed'], effect: 'read', requiresAI: true },
+        async execute(params, context) {
+            const deps = bindings();
+            const roleId = text(params.roleId);
+            if (resolveRoleDescriptor(deps.config, roleId).access !== 'read')
+                throw new EngineError('invalid_role_access', 'The decider must use a read-only role');
+            const continueRequired = typeof params.continueWhen === 'string' && Boolean(parseExpression(params.continueWhen).evaluate(context.state));
+            const history = boundedText(context.state.$history.map(entry => `[${entry.nodePath}] ${entry.text}`).join('\n'), deps.policies?.historyMaxChars ?? 1500);
+            const specs = deps.context.specs.map(spec => boundedText(JSON.stringify({ id: spec.id, title: spec.title, description: spec.description, acceptanceCriteria: spec.acceptanceCriteria }), 4000));
+            const memo = deps.memo(context);
+            const saved = memo.get('decider-blocked-result');
+            const result = saved ? saved : await executeRoleTurn(deps, { roleId, prompt: deciderPrompt(text(params.goal), [history], specs), structuredOutput: outputSchema, sessionContinuity: 'none', ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }), ...(params.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: params.idleTimeoutMs }) }, context, {
+                normalizeStructuredOutput: (output, response) => {
+                    const question = /^\s*LOOP_BLOCKED:\s*(.+)$/m.exec(response)?.[1]?.trim();
+                    return question ? { verdict: 'blocked', reason: boundedText(question, 4000) } : output;
+                },
+            });
+            if (result.outcome !== 'next')
+                return { ...result, outcome: 'failed' };
+            const structured = result.output.structured;
+            const candidateHash = deps.executionSnapshot(context).candidate?.hash ?? null;
+            const nodeId = context.frame.nodePath.split('/').at(-1);
+            const previous = context.state.$outputs[nodeId];
+            if (structured.verdict === 'blocked') {
+                // The read-only decision and its usage have settled. Retain that result
+                // before interrupting so a human answer never repeats the provider call.
+                if (!saved)
+                    memo.set('decider-blocked-result', json(result));
+                const response = context.interrupt({ kind: 'question', prompt: structured.reason, nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
+                return { ...result, outcome: 'continue', output: { verdict: 'continue', reason: structured.reason, blocked: true,
+                        candidateHash: previous?.candidateHash ?? null, continueCount: previous?.continueCount ?? 0 },
+                    answers: [answerEntry(context, response)], history: [historyEntry(context, `Human decision requested: ${structured.reason}\nHuman answer:\n${JSON.stringify(response)}`)] };
+            }
+            // Apply mandatory work before the no-progress observation. Routing a stop
+            // through a later condition would reset the decider's retained history.
+            const overridden = continueRequired && structured.verdict === 'stop';
+            const verdict = overridden ? 'continue' : structured.verdict;
+            const reason = overridden ? boundedText('Required workflow work remains; continue before completion. ' + structured.reason, 4000) : structured.reason;
+            const continueCount = verdict === 'continue' && candidateHash !== null ? previous?.verdict === 'continue' && previous.candidateHash === candidateHash ? (previous.continueCount ?? 0) + 1 : 1 : 0;
+            const limit = params.noProgress ?? deps.policies?.noProgress;
+            const stalled = limit !== undefined && continueCount >= limit;
+            return { ...result, outcome: stalled ? 'failed' : verdict, output: { verdict, reason, candidateHash, continueCount, ...(overridden ? { proposedVerdict: structured.verdict, requiredContinue: true } : {}), ...(stalled ? { stalled: true } : {}) },
+                history: [historyEntry(context, `${verdict}: ${reason}${stalled ? ' (no progress)' : ''}`)],
+                ...(stalled ? { status: 'failed', error: { code: 'no_progress', message: 'The candidate did not change across the allowed continue decisions' }, completion: { ok: false, verified: false, reasons: ['no_progress'] } } : {}) };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/implementation-binding.d.ts

@@ -0,0 +1,13 @@
+import { type PipelineContext } from '../../../pipeline/pipeline-state.js';
+import { type PieceExecutionContext } from '../contracts.js';
+export interface ImplementationBinding {
+    shared?: true;
+    context: PipelineContext;
+    change: string;
+    parentRunId: string;
+    scopeId: string;
+    nodePath: string;
+    directory: string;
+}
+/** Bind one journal to one declared implementation instance without changing backlog semantics. */
+export declare function deriveImplementationBinding(parent: PipelineContext, execution: PieceExecutionContext, change: string): ImplementationBinding;