@entrorove/skill 0.1.23 → 0.1.25

package/local-calctool.mjs

@@ -0,0 +1,103 @@
+import Ajv from 'ajv';
+import { CALCTOOL_LOCAL_NAMES, CALCTOOL_LOCAL_OPERATION_SCHEMAS } from './local-calctool-contracts.mjs';
+import { withBudgetReadContext } from './local-budget-reads.mjs';
+import { formulaError } from './local-decimal.mjs';
+import { buildFormulaEngine, compileFormulaEngine, verifyFormulaProgram, evaluateFormulaProgram, formulaImpact, formulaDigest } from './local-formula-engine.mjs';
+import { formulaFinalGate, readFormulaFile } from './local-formula.mjs';
+import { storeFormula, loadStoredFormula, formulaInventory, purgeStoredFormula } from './local-calctool-storage.mjs';
+import { loadCalctoolRuntime, calctoolRuntimeBytes } from './local-calctool-runtime.mjs';
+
+const schemaVersion = 'entrorove.local-execution/1.0';
+const ajv = new Ajv({ strict: true, strictRequired: false, allErrors: true });
+const validators = new Map(Object.entries(CALCTOOL_LOCAL_OPERATION_SCHEMAS).map(([name, schema]) => [name, ajv.compile(schema)]));
+export function validateCalctoolLocalInput(operation, input) {
+  if (typeof operation !== 'string') throw formulaError('ENTROROVE_OPERATION_UNKNOWN', 'Calctool operation must be a string');
+  const name = operation.startsWith('calctool-') ? operation : `calctool-${operation}`;
+  const validator = validators.get(name);
+  if (!validator) throw formulaError('ENTROROVE_OPERATION_UNKNOWN', 'unsupported Calctool operation');
+  if (!validator(input)) throw formulaError('ENTROROVE_INPUT_INVALID', `Invalid ${name} input: ${validator.errors.map(item => `${item.instancePath || '/'} ${item.message}`).join('; ')}`);
+  return input;
+}
+async function programFrom(input) {
+  if (input.program) return verifyFormulaProgram(input.program, input);
+  if (input.engineId) return (await loadStoredFormula(input)).program;
+  const engine = input.engine ?? (input.enginePath ? (await readFormulaFile(input)).engine : buildFormulaEngine(input.requirements));
+  return verifyFormulaProgram(compileFormulaEngine(engine), input);
+}
+function validatedPlan(plan, completed = []) {
+  if (!plan || !Array.isArray(plan.tasks)) throw formulaError('RUN_PLAN_INVALID', 'runPlan tasks are required');
+  const definitions = new Map();
+  for (const task of plan.tasks) {
+    if (!task || typeof task.workItemId !== 'string' || definitions.has(task.workItemId) || !Array.isArray(task.dependsOn)) throw formulaError('RUN_PLAN_INVALID', 'runPlan requires unique work items and explicit dependencies');
+    definitions.set(task.workItemId, task);
+  }
+  const visiting = new Set(); const done = new Set();
+  const visit = key => {
+    if (done.has(key)) return;
+    if (!definitions.has(key)) throw formulaError('RUN_PLAN_INVALID', 'runPlan contains an unknown dependency');
+    if (visiting.has(key)) throw formulaError('RUN_PLAN_INVALID', 'runPlan dependency cycle');
+    visiting.add(key); for (const dependency of definitions.get(key).dependsOn) visit(dependency); visiting.delete(key); done.add(key);
+  };
+  for (const key of definitions.keys()) visit(key);
+  for (const key of completed) if (!definitions.has(key)) throw formulaError('RUN_PLAN_INVALID', 'completed work item is not part of the runPlan');
+}
+const TOOL_SOURCE = `import { readFile } from 'node:fs/promises';
+import { evaluateCompiledProgram, verifyCompiledProgram } from './runtime.mjs';
+let input = ''; for await (const chunk of process.stdin) input += chunk;
+try { const program = JSON.parse(await readFile(new URL('./program.json', import.meta.url), 'utf8')); if(process.argv.includes('--verify')) { const result=verifyCompiledProgram(program); process.stdout.write(JSON.stringify(result)+'\\n'); process.exitCode=result.computationsPassed?0:2; } else { const values = evaluateCompiledProgram(program, JSON.parse(input)); process.stdout.write(JSON.stringify({status:'reported',programDigest:program.programDigest,values})+'\\n'); } }
+catch (error) { const code=error.code??'FORMULA_INPUT_INVALID'; const status=/(?:AUTHORITY_REQUIRED|LEASE_EXPIRED|NOT_ACCEPTED|REVOKED)$/.test(code)?'blocked':'failed'; process.stderr.write(JSON.stringify({schemaVersion:'entrorove.local-error/1.0',status,code,message:error instanceof SyntaxError?'Formula input or artifact must be valid JSON':error.message})+'\\n'); process.exitCode=status==='blocked'?2:1; }
+`;
+async function store(input, generate) {
+  const program = await programFrom(input);
+  const files = generate ? [{ path: 'runtime.mjs', bytes: await calctoolRuntimeBytes() }, { path: 'tool.mjs', bytes: Buffer.from(TOOL_SOURCE) }] : undefined;
+  const stored = await storeFormula(input, program, files);
+  return { schemaVersion, status: 'reported', engineId: program.engineId, engineVersion: program.engineVersion, runtimeVersion: program.runtimeVersion,
+    engineDigest: program.engineDigest, programDigest: program.programDigest, directory: stored.directory, files: stored.manifest.files,
+    ...(generate ? { executable: `${stored.directory}/tool.mjs`, validatorCommand: { executable: process.execPath, args: [`${stored.directory}/tool.mjs`, '--verify'] } } : {}), reused: stored.reused };
+}
+async function execute(operation, input) {
+  if (['compile', 'generate'].includes(operation)) return store(input, operation !== 'compile');
+  if (operation === 'compile-tool') {
+    const generated = await store(input, true); const stored = await loadStoredFormula({ ...input, engineId: generated.engineId, engineVersion: generated.engineVersion });
+    const runtime = await loadCalctoolRuntime(); const project = await runtime.runLocalCore('compile-tool', { engine: stored.program.engine });
+    return { ...generated, pages: project.pages, commands: project.commands, environment: project.environment,
+      projectFiles: project.files.map(file => file.kind === 'engine' ? { ...file, digest: stored.program.engineDigest } : file), projectStatus: 'planned' };
+  }
+  if (operation === 'inventory') return { schemaVersion, status: 'reported', engines: await formulaInventory(input) };
+  if (operation === 'purge') return { schemaVersion, status: 'reported', ...await purgeStoredFormula(input) };
+  if (operation === 'status') { const stored = await loadStoredFormula(input); return { schemaVersion, status: 'reported', ...stored.manifest }; }
+  if (operation === 'final-gate' && input.gateId) {
+    const { runFinalGate16 } = await import('./local-final-gate16.mjs');
+    return runFinalGate16(input);
+  }
+  if (['run', 'verify', 'final-gate', 'estimate', 'impact', 'blueprint-orchestrate'].includes(operation)) {
+    const program = await programFrom(input);
+    if (operation === 'run') {
+      const values = evaluateFormulaProgram(program, input.inputs, input);
+      return { schemaVersion, status: 'reported', engineId: program.engineId, engineVersion: program.engineVersion, programDigest: program.programDigest,
+        values, artifactSha256: formulaDigest({ programDigest: program.programDigest, inputs: input.inputs, values }) };
+    }
+    if (['verify', 'final-gate'].includes(operation)) return formulaFinalGate(program.engine, input);
+    if (operation === 'impact') return { schemaVersion, status: 'reported', programDigest: program.programDigest, affected: formulaImpact(program, input.changedKeys) };
+    if (operation === 'estimate') return { schemaVersion, status: 'reported', programDigest: program.programDigest, formulas: program.formulas.length,
+      fields: program.engine.fields.length, dependencies: Object.values(program.dependencies).reduce((total, refs) => total + refs.length, 0), order: program.order };
+    const core = await loadCalctoolRuntime(); const output = await core.runLocalCore(operation, { engine: program.engine, goal: input.goal });
+    return { ...output, status: 'reported', source: 'calctool-plan', executed: false };
+  }
+  const core = await loadCalctoolRuntime();
+  if (operation === 'probe-env') return { schemaVersion, status: 'reported', probe: core.probeLocalEnvironment() };
+  if (operation === 'adapt-config') return { schemaVersion, status: 'reported', adapted: core.adaptLocalEnvironment(input.probe ?? core.probeLocalEnvironment()) };
+  if (input.runPlan) validatedPlan(input.runPlan, input.completedWorkItemIds);
+  const output = await core.runLocalCore(operation, input);
+  if (output.status === 'blocked' || output.status === 'failed') return output;
+  if (output.status === 'incomplete') return { ...output, source: 'calctool-plan', executed: false };
+  if (output.runPlan) validatedPlan(output.runPlan);
+  return { ...output, status: 'reported', source: 'calctool-plan', executed: false, ...(operation === 'brain-handshake' ? { brainUsed: false } : {}) };
+}
+export async function runCalctoolLocal(operation, input = {}) {
+  if (typeof operation !== 'string') throw formulaError('ENTROROVE_OPERATION_UNKNOWN', 'Calctool operation must be a string');
+  const name = operation.replace(/^calctool-/, '');
+  validateCalctoolLocalInput(name, input);
+  return withBudgetReadContext(input, () => execute(name, input));
+}
+export const CALCTOOL_LOCAL_OPERATIONS = Object.freeze(Object.fromEntries(CALCTOOL_LOCAL_NAMES.map(name => [`calctool-${name}`, input => runCalctoolLocal(name, input)])));

package/local-chain-bindings.mjs

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateLocalInput } from './local-contracts.mjs';
+import { observeWorkflowLocalStep } from './workflow-local-runner.mjs';
+import { validateLocalChainPlan } from './local-chain-plan.mjs';
+
+export const CHAIN_PACKAGE_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = await fs.realpath(CHAIN_PACKAGE_ROOT);
+const SKILLS = ['aimlock', 'archguard', 'blueprint', 'calctool', 'confirm-protocol', 'mergeguard', 'swarm', 'validator'];
+export function chainFail(code, message) { throw Object.assign(new Error(message), { code }); }
+export function chainCanonical(value) {
+  if (Array.isArray(value)) return `[${value.map(chainCanonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${chainCanonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+export const chainSha = value => createHash('sha256').update(value).digest('hex');
+export function chainExact(value, required, optional = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || required.some(key => !Object.hasOwn(value, key))
+    || Object.keys(value).some(key => !required.includes(key) && !optional.includes(key))) {
+    chainFail('ENTROROVE_CHAIN_FIELDS', 'chain input has missing or unknown fields');
+  }
+}
+export async function chainControlFile(file, maximum = 8 * 1024 * 1024) {
+  const descriptor = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const before = await descriptor.stat();
+    if (!before.isFile() || before.nlink !== 1 || before.size > maximum
+      || (typeof process.getuid === 'function' && before.uid !== process.getuid())) {
+      chainFail('ENTROROVE_CHAIN_CONTROL_INVALID', 'chain control must be a bounded owned regular file');
+    }
+    const bytes = await descriptor.readFile(), after = await descriptor.stat(), current = await fs.lstat(file);
+    if (bytes.length !== before.size || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs || current.isSymbolicLink() || current.dev !== before.dev || current.ino !== before.ino) {
+      chainFail('ENTROROVE_CHAIN_CONTROL_CHANGED', 'chain control changed during its actual read');
+    }
+    return { bytes, stat: after };
+  } finally { await descriptor.close(); }
+}
+async function sourceNames() {
+  const rootNames = (await fs.readdir(ROOT)).filter(name => name.endsWith('.mjs'));
+  const runtimeNames = (await fs.readdir(path.join(ROOT, 'runtime'))).filter(name => name.endsWith('.mjs')).map(name => `runtime/${name}`);
+  return [...rootNames, ...runtimeNames, 'package.json', 'manifest.json'].sort();
+}
+export async function captureChainPackage(plan) {
+  for (const skill of plan.skills) {
+    if (!SKILLS.includes(skill.skillId) || await fs.realpath(skill.packageRoot) !== ROOT) {
+      chainFail('ENTROROVE_CHAIN_SKILL_PACKAGE', 'native chain skills must use the current fixed Entrorove package');
+    }
+  }
+  const files = [];
+  for (const name of await sourceNames()) files.push({ path: name, sha256: chainSha((await chainControlFile(path.join(ROOT, name))).bytes) });
+  const metadata = JSON.parse((await chainControlFile(path.join(ROOT, 'package.json'))).bytes.toString('utf8'));
+  if (metadata.name !== '@entrorove/skill') chainFail('ENTROROVE_CHAIN_SKILL_PACKAGE', 'installed native package identity is invalid');
+  return { packageRoot: ROOT, name: metadata.name, version: metadata.version, files,
+    authorityKeyDigest: chainSha(process.env.ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY ?? '') };
+}
+export async function checkChainPackage(snapshot) {
+  const current = await captureChainPackage(snapshot.plan);
+  if (chainCanonical(current) !== chainCanonical(snapshot.package)) chainFail('ENTROROVE_CHAIN_PACKAGE_CHANGED', 'installed source, metadata or authority changed after chain initialization');
+}
+export async function validateChainBindings(planValue, values, identity) {
+  const plan = validateLocalChainPlan(planValue);
+  if (!Array.isArray(values)) chainFail('ENTROROVE_CHAIN_BINDING', 'command bindings must be an explicit array');
+  const commands = plan.steps.filter(step => step.kind === 'command'), bindings = [];
+  if (values.length !== commands.length) chainFail('ENTROROVE_CHAIN_BINDING', 'every command requires exactly one original signed workflow mapping');
+  for (const step of commands) {
+    const selected = values.filter(value => value.stepId === step.stepId);
+    if (selected.length !== 1) chainFail('ENTROROVE_CHAIN_BINDING', 'command mapping must have a unique original step ID');
+    chainExact(selected[0], ['stepId', 'workflowInput']);
+    const input = validateLocalInput('workflow-run-step', structuredClone(selected[0].workflowInput));
+    const native = input.acceptedPlan.steps.find(value => value.stepId === input.stepId);
+    if (input.repositoryRoot !== identity.repositoryRoot || input.home !== identity.home || input.stepId !== step.stepId
+      || input.acceptedPlan.flowId !== identity.flowId || input.acceptedPlan.ownerId !== identity.ownerId
+      || input.lease.stepId !== step.stepId || !native || chainCanonical(native.dependsOn) !== chainCanonical(step.dependsOn)) {
+      chainFail('ENTROROVE_CHAIN_BINDING', 'command mapping changed its original home, repository, flow, owner or step dependencies');
+    }
+    const policy = native.executionPlan.policy;
+    if (chainCanonical([step.input.executable, step.input.args, step.input.environment, step.input.timeoutMs, step.input.evidenceKind])
+      !== chainCanonical([policy.executable, policy.args, policy.environment, policy.timeoutMs, native.executionPlan.evidencePolicy?.kind ?? 'test'])) {
+      chainFail('ENTROROVE_CHAIN_BINDING', 'command policy differs from its actual frozen workflow plan');
+    }
+    if (path.resolve(identity.repositoryRoot, step.input.workingDirectory) !== identity.repositoryRoot) {
+      chainFail('ENTROROVE_CHAIN_COMMAND_CWD_UNSUPPORTED', 'the fixed native workflow runner currently executes only at its original repository root');
+    }
+    // This real observer verifies the configured Ed25519 plan and lease without
+    // starting a process or inventing an execution authority.
+    await observeWorkflowLocalStep(input);
+    bindings.push({ stepId: step.stepId, workflowInput: input });
+  }
+  return bindings;
+}

package/local-chain-broker.mjs

@@ -0,0 +1,61 @@
+import Ajv from 'ajv';
+import { chainCanonical as canonical, chainFail as fail } from './local-chain-bindings.mjs';
+import { inspectLocalChainResult } from './local-chain-plan.mjs';
+
+const STAGES = Object.freeze({ 'workflow-gate': 'aimlock', 'workflow-contract': 'aimlock',
+  'workflow-plan': 'blueprint', 'workflow-dispatch': 'swarm', 'workflow-verdict': 'validator' });
+function nativeSchema(runtime, operation) {
+  const schemas = runtime.operationSchemas;
+  const selected = Array.isArray(schemas) ? schemas.find(value => value.operation === operation) : schemas?.[operation];
+  return selected?.inputSchema ?? selected?.input ?? selected;
+}
+export async function captureChainCloud(plan, client) {
+  if (!plan.skills.length) return null;
+  const output = await client.invoke('capabilities', {}), capabilities = output.capabilities;
+  if (output.status !== 'succeeded' || !capabilities?.operationSchemas?.continue
+    || !Array.isArray(capabilities.runtimes)) fail('ENTROROVE_CHAIN_DISCOVERY', 'original cloud discovery is incomplete');
+  const runtimes = plan.skills.map(skill => {
+    const matches = capabilities.runtimes.filter(runtime => runtime.slug === skill.skillId);
+    if (matches.length !== 1 || typeof matches[0].version !== 'string' || typeof matches[0].endpoint !== 'string') {
+      fail('ENTROROVE_CHAIN_DISCOVERY', 'declared native skill has no unique original runtime metadata');
+    }
+    return structuredClone(matches[0]);
+  });
+  return { runtimes, operationSchemas: structuredClone(capabilities.operationSchemas),
+    workflowOperations: structuredClone(capabilities.workflowOperations ?? null) };
+}
+export async function checkChainCloud(state, client) {
+  if (canonical(await captureChainCloud(state.plan, client)) !== canonical(state.cloud)) {
+    fail('ENTROROVE_CHAIN_DISCOVERY_CHANGED', 'original cloud runtime or operation metadata changed after initialization');
+  }
+}
+export function checkChainSkillDispatch(original, state, resumed, input) {
+  const next = resumed.nextStep;
+  if (resumed.canContinue !== true || next?.operation !== 'continue'
+    || next.input?.flowId !== state.identity.flowId || next.input.operation !== original.operation) {
+    fail('ENTROROVE_CHAIN_STAGE_BINDING', 'declared skill must be the exact next operation of its original workflow');
+  }
+  const slug = STAGES[original.operation] ?? resumed.route?.slug;
+  if (slug !== original.skillId) fail('ENTROROVE_CHAIN_SKILL_BINDING', 'declared skill differs from the original native workflow stage');
+  const runtime = state.cloud.runtimes.find(value => value.slug === original.skillId);
+  const schema = state.cloud.workflowOperations?.operationSchemas?.[original.operation] ?? nativeSchema(runtime, original.operation);
+  if (schema) {
+    const validate = new Ajv({ strict: true, strictRequired: false, allErrors: true }).compile(schema);
+    if (!validate(input)) fail('ENTROROVE_CHAIN_SKILL_INPUT', 'bound input violates its fixed original operation schema');
+  }
+  // Native operations without public nested schemas remain server-validated on
+  // the exact original active route; no arbitrary endpoint is opened here.
+}
+export function inspectChainSkillResponse(original, state, response) {
+  if (response.flowId !== state.identity.flowId || (response.taskId !== undefined && response.taskId !== state.identity.taskId)) {
+    fail('ENTROROVE_CHAIN_RESULT_BINDING', 'skill result lost its original flow or task identity');
+  }
+  if (!response.result || typeof response.result !== 'object' || Array.isArray(response.result)) {
+    fail('ENTROROVE_CHAIN_RESULT_BINDING', 'skill result must retain its actual native structured output');
+  }
+  const native = response.result;
+  if (native.source === 'needs-clarification' || native.intake?.complete === false) {
+    return { state: 'waiting', code: 'ENTROROVE_CHAIN_CLARIFICATION_REQUIRED', eligible: false };
+  }
+  return inspectLocalChainResult(original, response);
+}

package/local-chain-contracts.mjs

@@ -0,0 +1,21 @@
+import { WORKFLOW_LOCAL_OPERATION_SCHEMA } from './workflow-local-contracts.mjs';
+
+const id = { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$' };
+const text = { type: 'string', minLength: 1 };
+const object = (properties, required = Object.keys(properties)) => ({ type: 'object', additionalProperties: false, properties, required });
+const array = items => ({ type: 'array', items });
+const pointer = { type: 'string', pattern: '^(?:/(?:[^~]|~[01])*)*$' };
+const step = object({ stepId: id, kind: { enum: ['skill', 'coordinator', 'command'] },
+  skillId: { anyOf: [id, { type: 'null' }] }, operation: id, input: { type: 'object' }, dependsOn: array(id),
+  bindings: array(object({ stepId: id, source: pointer, target: { ...pointer, minLength: 1 } })),
+  continueWhen: object({ answer: { anyOf: [text, { ...array(text), minItems: 1, uniqueItems: true }] } }),
+}, ['stepId', 'kind', 'skillId', 'operation', 'input', 'dependsOn', 'bindings']);
+export const LOCAL_CHAIN_PLAN_INPUT_SCHEMA = object({ schemaVersion: { const: 'entrorove.execution-plan/1.0' }, chainId: id,
+  skills: array(object({ skillId: id, packageRoot: text })), steps: { ...array(step), minItems: 1 } });
+const identity = { repositoryRoot: text, home: text, chainId: id };
+export const LOCAL_CHAIN_OPERATION_SCHEMAS = Object.freeze({
+  'chain-init': object({ repositoryRoot: text, home: text, flowId: id, ownerId: id, taskId: id,
+    plan: LOCAL_CHAIN_PLAN_INPUT_SCHEMA, commandBindings: array(object({ stepId: id, workflowInput: WORKFLOW_LOCAL_OPERATION_SCHEMA })) }),
+  'chain-resume': object(identity), 'chain-status': object(identity),
+  'chain-answer': object({ ...identity, actorId: id }),
+});

package/local-chain-controller.mjs

@@ -0,0 +1,321 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { withChainLock } from './local-chain-lock.mjs';
+import { captureChainCloud, checkChainCloud, checkChainSkillDispatch, inspectChainSkillResponse } from './local-chain-broker.mjs';
+import { originalChainInteraction, readChainTerminalAnswer, inspectChainHumanResponse } from './local-chain-human.mjs';
+import { validateArchivedChainResults, revalidateArchivedChainSkill, revalidateArchivedChainCommand } from './local-chain-results.mjs';
+import { buildInvocation, createTaskMessageClient } from './remote-client.mjs';
+import { runManagedWorkflowLocalStep } from './workflow-local-client.mjs';
+import { observeWorkflowLocalStep } from './workflow-local-runner.mjs';
+import { bindLocalChainStepInput, localChainPlanDigest, validateLocalChainPlan } from './local-chain-plan.mjs';
+import { captureChainPackage, checkChainPackage, validateChainBindings, chainCanonical as canonical,
+  chainControlFile, chainExact as exact, chainFail as fail, chainSha as sha } from './local-chain-bindings.mjs';
+
+export const LOCAL_CHAIN_CONTROLLER_SCHEMA = 'entrorove.local-chain-controller/1.0';
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const SHA = /^[0-9a-f]{64}$/;
+const STATES = ['pending', 'running', 'waiting', 'reported', 'verified', 'uncertain', 'blocked', 'failed'];
+const MAX_BYTES = 8 * 1024 * 1024;
+function safeId(value) { if (typeof value !== 'string' || !ID.test(value)) fail('ENTROROVE_CHAIN_ID', 'chain identity must be explicit and safe'); }
+async function directory(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value)) fail('ENTROROVE_CHAIN_DIRECTORY', 'chain home and repository must be explicit absolute directories');
+  const stat = await fs.lstat(value);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_CHAIN_DIRECTORY', 'chain directories must be real directories');
+  return fs.realpath(value);
+}
+async function location(input, create = false) {
+  const repositoryRoot = await directory(input.repositoryRoot), home = await directory(input.home);
+  safeId(input.chainId ?? input.plan?.chainId);
+  let target = home;
+  for (const name of ['.entrorove', 'chain-controller', sha(repositoryRoot).slice(0, 32), input.chainId ?? input.plan.chainId]) {
+    target = path.join(target, name);
+    if (create) await fs.mkdir(target, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+    const stat = await fs.lstat(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o700
+      || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) fail('ENTROROVE_CHAIN_STORAGE', 'chain state directories must be owned, private and real');
+  }
+  return { repositoryRoot, home, file: path.join(target, 'state.json') };
+}
+async function atomic(file, value) {
+  const bytes = Buffer.from(canonical(value) + '\n');
+  if (bytes.length > MAX_BYTES) fail('ENTROROVE_CHAIN_JOURNAL_LIMIT', 'chain journal exceeds its control byte bound');
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  const descriptor = await fs.open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+  try { await descriptor.writeFile(bytes); await descriptor.sync(); }
+  finally { await descriptor.close(); }
+  try {
+    await fs.rename(temporary, file);
+    const directory = await fs.open(path.dirname(file), constants.O_RDONLY);
+    try { await directory.sync(); } finally { await directory.close(); }
+  }
+  finally { await fs.rm(temporary, { force: true }); }
+}
+function reduce(records) {
+  let state = null, head = null;
+  for (const [index, record] of records.entries()) {
+    exact(record, ['sequence', 'event', 'at', 'stepId', 'data', 'previousDigest', 'digest']);
+    const { digest, ...core } = record;
+    if (record.sequence !== index + 1 || record.previousDigest !== head || !SHA.test(digest) || sha(canonical(core)) !== digest) {
+      fail('ENTROROVE_CHAIN_JOURNAL_INVALID', 'chain journal hash lineage is invalid');
+    }
+    if (index === 0) {
+      if (record.event !== 'init' || record.stepId !== null) fail('ENTROROVE_CHAIN_JOURNAL_INVALID', 'chain journal must start with its original initialization');
+      state = structuredClone(record.data);
+      if (!state || typeof state !== 'object' || !Array.isArray(state.steps) || !state.identity) {
+        fail('ENTROROVE_CHAIN_JOURNAL_INVALID', 'chain initialization controls are invalid');
+      }
+    } else {
+      if (record.event !== 'step') fail('ENTROROVE_CHAIN_JOURNAL_INVALID', 'chain journal contains an unknown event');
+      const step = state.steps.find(value => value.stepId === record.stepId);
+      if (!step || !record.data || !STATES.includes(record.data.status)) fail('ENTROROVE_CHAIN_JOURNAL_INVALID', 'chain journal changed its original step or status');
+      if (record.data.phase === 'answer' && step.output?.interaction && !step.originalInteraction) {
+        step.originalInteraction = structuredClone(step.output);
+      }
+      Object.assign(step, structuredClone(record.data));
+    }
+    head = digest;
+  }
+  if (!state || state.steps.some(step => !step || typeof step !== 'object' || !STATES.includes(step.status))
+    || localChainPlanDigest(state.plan) !== state.planDigest || state.steps.length !== state.plan.steps.length
+    || state.steps.some((step, index) => step.stepId !== state.plan.steps[index].stepId)) fail('ENTROROVE_CHAIN_JOURNAL_INVALID', 'chain journal lost its immutable original plan');
+  return state;
+}
+async function load(ctx) {
+  const { bytes, stat } = await chainControlFile(ctx.file);
+  if ((stat.mode & 0o777) !== 0o600) fail('ENTROROVE_CHAIN_STORAGE', 'chain journal must remain private');
+  let journal; try { journal = JSON.parse(bytes.toString('utf8')); } catch { fail('ENTROROVE_CHAIN_JOURNAL_INVALID', 'chain journal JSON is invalid'); }
+  exact(journal, ['schemaVersion', 'records']);
+  if (journal.schemaVersion !== LOCAL_CHAIN_CONTROLLER_SCHEMA || !Array.isArray(journal.records) || !journal.records.length) fail('ENTROROVE_CHAIN_JOURNAL_INVALID', 'chain journal schema is invalid');
+  const state = reduce(journal.records);
+  if (state.identity.home !== ctx.home || state.identity.repositoryRoot !== ctx.repositoryRoot) fail('ENTROROVE_CHAIN_BINDING', 'chain journal belongs to another original home or repository');
+  await checkChainPackage(state);
+  await validateArchivedChainResults(state);
+  return { ctx, journal, state };
+}
+async function append(loaded, stepId, data, event = 'step') {
+  const records = loaded.journal.records;
+  const core = { sequence: records.length + 1, event, at: new Date().toISOString(), stepId, data,
+    previousDigest: records.at(-1)?.digest ?? null };
+  const journal = { schemaVersion: LOCAL_CHAIN_CONTROLLER_SCHEMA, records: [...records, { ...core, digest: sha(canonical(core)) }] };
+  await atomic(loaded.ctx.file, journal); loaded.journal = journal; loaded.state = reduce(journal.records);
+}
+function view(loaded) {
+  const steps = loaded.state.steps;
+  const status = steps.find(step => ['failed', 'blocked', 'uncertain', 'waiting', 'running', 'reported', 'pending'].includes(step.status))?.status ?? 'verified';
+  return { schemaVersion: LOCAL_CHAIN_CONTROLLER_SCHEMA, chainId: loaded.state.plan.chainId, status,
+    flowId: loaded.state.identity.flowId, steps: structuredClone(steps), sequence: loaded.journal.records.length,
+    head: loaded.journal.records.at(-1).digest, authority: 'original-workflow-step-results', taskCompletionVerified: false };
+}
+async function dependenciesFor(home, supplied) { return supplied ?? (await import('./cli.mjs')).remoteDependencies(home); }
+function checkCloudTask(output, identity) {
+  if (!output?.task || output.task.taskId !== identity.taskId || output.task.ownerId !== identity.ownerId
+    || output.task.flowId !== identity.flowId || output.flowId !== identity.flowId || output.continuity?.handoffPaused
+    || output.continuity?.activeTakeover || !['accepted', 'active'].includes(output.task.status)) {
+    fail('ENTROROVE_CHAIN_CLOUD_BINDING', 'original cloud task cannot authorize this local chain');
+  }
+}
+function originalResponse(output, requestId) {
+  if (!output || output.requestId !== requestId || output.schemaVersion !== 'entrorove.skill.response/1.0') {
+    fail('ENTROROVE_CHAIN_RESPONSE_BINDING', 'cloud result must retain its original canonical request ID');
+  }
+  return output;
+}
+async function cloudRequest(loaded, step, operation, input, client, phase) {
+  const expected = buildInvocation(operation, input), existing = step.request;
+  if (existing && (existing.requestId !== expected.requestId || existing.operation !== operation
+    || canonical(existing.input) !== canonical(input))) fail('ENTROROVE_CHAIN_REQUEST_BINDING', 'pending cloud request cannot be replaced');
+  const request = existing ?? { requestId: expected.requestId, operation, input };
+  if (!existing) await append(loaded, step.stepId, { ...step, request, phase, status: step.status });
+  try {
+    // A saved request can have been sent before an abrupt host exit. Recovery
+    // observes that exact durable result; it never issues another POST.
+    return originalResponse(await (existing ? client.status(request.requestId) : client.invoke(operation, input)), request.requestId);
+  } catch (error) {
+    await append(loaded, step.stepId, { ...loaded.state.steps.find(value => value.stepId === step.stepId),
+      status: 'uncertain', error: { code: error.code ?? 'ENTROROVE_CHAIN_CLOUD_UNKNOWN', requestId: request.requestId } });
+    return null;
+  }
+}
+
+export async function initLocalChain(input, suppliedDependencies) {
+  exact(input, ['repositoryRoot', 'home', 'flowId', 'ownerId', 'taskId', 'plan', 'commandBindings']);
+  for (const field of ['flowId', 'ownerId', 'taskId']) safeId(input[field]);
+  const plan = validateLocalChainPlan(input.plan), ctx = await location({ ...input, plan }, true);
+  return withChainLock(ctx.file, async () => {
+    try { await fs.lstat(ctx.file); fail('ENTROROVE_CHAIN_EXISTS', 'the original chain already exists; resume it without reinitializing'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const identity = { repositoryRoot: ctx.repositoryRoot, home: ctx.home, flowId: input.flowId, ownerId: input.ownerId, taskId: input.taskId };
+    const bindings = await validateChainBindings(plan, input.commandBindings, identity), packagePin = await captureChainPackage(plan);
+    const configured = await dependenciesFor(ctx.home, suppliedDependencies), client = createTaskMessageClient(configured);
+    const resumed = await client.invoke('task-resume', { flowId: identity.flowId }); checkCloudTask(resumed, identity);
+    const cloud = await captureChainCloud(plan, client);
+    const state = { identity, plan, planDigest: localChainPlanDigest(plan), commandBindings: bindings, package: packagePin, cloud,
+      apiOrigin: new URL(configured.apiOrigin()).origin,
+      steps: plan.steps.map(step => ({ stepId: step.stepId, status: 'pending', phase: 'execute', request: null, localResult: null, output: null, error: null })) };
+    const loaded = { ctx, journal: { schemaVersion: LOCAL_CHAIN_CONTROLLER_SCHEMA, records: [] }, state: null };
+    await append(loaded, null, state, 'init'); return view(loaded);
+  });
+}
+
+async function reconcileSkill(loaded, original, input, client) {
+  let step = loaded.state.steps.find(value => value.stepId === original.stepId);
+  if (step.status === 'waiting') return false;
+  if (!step.request) {
+    const resumed = await client.invoke('task-resume', { flowId: loaded.state.identity.flowId });
+    checkCloudTask(resumed, loaded.state.identity); checkChainSkillDispatch(original, loaded.state, resumed, input);
+    await append(loaded, step.stepId, { ...step, status: 'running' });
+    step = loaded.state.steps.find(value => value.stepId === original.stepId);
+  }
+  const invocation = { flowId: loaded.state.identity.flowId, operation: original.operation, payload: input };
+  const response = await cloudRequest(loaded, step, 'continue', invocation, client, 'skill');
+  if (!response) return false;
+  const observed = inspectChainSkillResponse(original, loaded.state, response);
+  await append(loaded, step.stepId, { ...step, status: observed.eligible ? 'verified' : observed.state,
+    phase: observed.eligible ? 'done' : 'skill', output: response.result, request: loaded.state.steps.find(value => value.stepId === step.stepId).request,
+    response, error: observed.eligible ? null : { code: observed.code } });
+  return observed.eligible;
+}
+
+async function reconcileAnswer(loaded, original, client) {
+  const step = loaded.state.steps.find(value => value.stepId === original.stepId);
+  const response = await cloudRequest(loaded, step, 'continue', step.request.input, client, 'answer');
+  if (!response) return false;
+  const observed = inspectChainHumanResponse(original, loaded.state, step, response);
+  await append(loaded, step.stepId, { ...step, status: observed.eligible ? 'verified' : observed.state,
+    phase: observed.eligible ? 'done' : 'answer', output: { ...response.result, answer: response.result.auditEntry.answer },
+    response, error: observed.eligible ? null : { code: observed.code } });
+  return observed.eligible;
+}
+
+export async function statusLocalChain(input, suppliedDependencies) {
+  exact(input, ['repositoryRoot', 'home', 'chainId']); const ctx = await location(input);
+  const loaded = await load(ctx), verified = loaded.state.plan.steps.filter(original =>
+    loaded.state.steps.find(step => step.stepId === original.stepId)?.status === 'verified');
+  if (verified.length) {
+    const configured = await dependenciesFor(ctx.home, suppliedDependencies);
+    if (new URL(configured.apiOrigin()).origin !== loaded.state.apiOrigin) fail('ENTROROVE_CHAIN_CLOUD_BINDING', 'status cannot switch its original cloud origin');
+    const client = createTaskMessageClient(configured);
+    for (const original of verified) await (original.kind === 'command' ? revalidateArchivedChainCommand : revalidateArchivedChainSkill)(
+      loaded.state, original, loaded.state.steps.find(step => step.stepId === original.stepId), client);
+  }
+  return view(loaded);
+}
+async function localCommand(loaded, step, binding, configured) {
+  let result;
+  try {
+    if (step.status !== 'pending') {
+      result = await observeWorkflowLocalStep(binding.workflowInput);
+      if (!result) { await append(loaded, step.stepId, { ...step, status: 'uncertain', error: { code: 'ENTROROVE_CHAIN_PROCESS_UNKNOWN' } }); return false; }
+    } else {
+      await append(loaded, step.stepId, { ...step, status: 'running' });
+      result = await runManagedWorkflowLocalStep(binding.workflowInput, configured);
+    }
+  } catch (error) {
+    const uncertain = error.outcomeUnknown || ['ENTROROVE_WORKFLOW_RECOVERY_REQUIRED', 'ENTROROVE_WORKFLOW_BUSY'].includes(error.code);
+    await append(loaded, step.stepId, { ...loaded.state.steps.find(value => value.stepId === step.stepId),
+      status: uncertain ? 'uncertain' : 'failed', error: { code: error.code ?? 'ENTROROVE_CHAIN_EXECUTION_REJECTED' } }); return false;
+  }
+  if (!result.receipt || !result.evidence?.length || !Number.isInteger(result.process?.exitCode)) {
+    await append(loaded, step.stepId, { ...step, status: 'uncertain', localResult: result, error: { code: 'ENTROROVE_CHAIN_PROCESS_UNKNOWN' } }); return false;
+  }
+  await append(loaded, step.stepId, { ...step, status: 'reported', phase: 'report', localResult: result, request: null, error: null }); return true;
+}
+function checkReported(output, loaded, step, binding, verified) {
+  const value = output.result, evidence = step.localResult.evidence[0], lease = binding.workflowInput.lease;
+  if (!['succeeded', 'reported'].includes(output.status) || !value || value.flowId !== loaded.state.identity.flowId
+    || value.stepId !== step.stepId || value.generation !== lease.generation || value.lease?.leaseId !== lease.leaseId
+    || value.evidenceDigest !== sha(canonical(evidence)) || value.status !== (verified ? 'verified' : step.localResult.status)) {
+    fail('ENTROROVE_CHAIN_RESULT_BINDING', 'cloud execution result differs from its original process, lease or evidence');
+  }
+  if (verified && (value.verification?.summary?.passed !== 1 || value.verification?.summary?.failed !== 0
+    || value.verification?.findings?.length !== 0)) fail('ENTROROVE_CHAIN_VERIFICATION', 'original independent verification did not pass the process receipt');
+  return value;
+}
+async function reconcileCommand(loaded, stepId, configured, client) {
+  let step = loaded.state.steps.find(value => value.stepId === stepId);
+  const binding = loaded.state.commandBindings.find(value => value.stepId === stepId);
+  if (step.phase === 'execute') {
+    if (!await localCommand(loaded, step, binding, configured)) return false;
+    step = loaded.state.steps.find(value => value.stepId === stepId);
+  }
+  if (step.phase === 'report') {
+    const input = { flowId: loaded.state.identity.flowId, operation: 'execution-report', payload: { stepId,
+      leaseId: binding.workflowInput.lease.leaseId, generation: binding.workflowInput.lease.generation, evidence: step.localResult.evidence[0] } };
+    const output = await cloudRequest(loaded, step, 'continue', input, client, 'report'); if (!output) return false;
+    const reported = checkReported(output, loaded, step, binding, false);
+    if (reported.status === 'failed') { await append(loaded, stepId, { ...step, status: 'failed', output: reported, request: null }); return false; }
+    await append(loaded, stepId, { ...step, status: 'reported', phase: 'verify', output: reported, request: null, error: null });
+    step = loaded.state.steps.find(value => value.stepId === stepId);
+  }
+  if (step.phase === 'verify') {
+    const input = { flowId: loaded.state.identity.flowId, operation: 'execution-verify', payload: { stepId } };
+    const output = await cloudRequest(loaded, step, 'continue', input, client, 'verify'); if (!output) return false;
+    const verified = checkReported(output, loaded, step, binding, true);
+    await append(loaded, stepId, { ...step, status: 'verified', phase: 'done', output: verified, request: null, error: null });
+  }
+  return true;
+}
+
+export async function resumeLocalChain(input, suppliedDependencies) {
+  exact(input, ['repositoryRoot', 'home', 'chainId']); const ctx = await location(input);
+  return withChainLock(ctx.file, async () => {
+    const loaded = await load(ctx), configured = await dependenciesFor(ctx.home, suppliedDependencies);
+    if (new URL(configured.apiOrigin()).origin !== loaded.state.apiOrigin) fail('ENTROROVE_CHAIN_CLOUD_BINDING', 'chain recovery cannot switch its original cloud origin');
+    const client = createTaskMessageClient(configured);
+    await checkChainCloud(loaded.state, client);
+    for (const original of loaded.state.plan.steps) {
+      const step = loaded.state.steps.find(value => value.stepId === original.stepId);
+      if (step.status === 'verified') {
+        await (original.kind === 'command' ? revalidateArchivedChainCommand : revalidateArchivedChainSkill)(loaded.state, original, step, client);
+        continue;
+      }
+      if (['failed', 'blocked'].includes(step.status)) return view(loaded);
+      const boundInput = bindLocalChainStepInput(loaded.state.plan, original.stepId, loaded.state.steps.filter(value => value.status === 'verified')
+        .map(value => ({ stepId: value.stepId, status: 'succeeded', output: value.output })));
+      if (original.kind === 'coordinator') {
+        await append(loaded, original.stepId, { ...step, status: 'blocked', error: { code: 'ENTROROVE_CHAIN_ADAPTER_PENDING', kind: original.kind } }); return view(loaded);
+      }
+      try {
+        const complete = original.kind === 'command' ? await reconcileCommand(loaded, original.stepId, configured, client)
+          : step.phase === 'answer' ? await reconcileAnswer(loaded, original, client) : await reconcileSkill(loaded, original, boundInput, client);
+        if (!complete) return view(loaded);
+      }
+      catch (error) {
+        const current = loaded.state.steps.find(value => value.stepId === original.stepId);
+        await append(loaded, original.stepId, { ...current, status: 'blocked', error: { code: error.code ?? 'ENTROROVE_CHAIN_RECONCILE_REJECTED' } }); return view(loaded);
+      }
+    }
+    return view(loaded);
+  });
+}
+
+export async function answerLocalChain(input, suppliedDependencies) {
+  exact(input, ['repositoryRoot', 'home', 'chainId', 'actorId']); safeId(input.actorId);
+  const ctx = await location(input);
+  return withChainLock(ctx.file, async () => {
+    const loaded = await load(ctx), configured = await dependenciesFor(ctx.home, suppliedDependencies);
+    if (new URL(configured.apiOrigin()).origin !== loaded.state.apiOrigin) fail('ENTROROVE_CHAIN_CLOUD_BINDING', 'answer cannot switch its original cloud origin');
+    const client = createTaskMessageClient(configured); await checkChainCloud(loaded.state, client);
+    const step = loaded.state.steps.find(value => value.status !== 'verified');
+    const original = loaded.state.plan.steps.find(value => value.stepId === step?.stepId);
+    if (original?.kind !== 'skill' || original.skillId !== 'confirm-protocol' || original.operation !== 'interaction-request') {
+      fail('ENTROROVE_CHAIN_DECISION_REQUIRED', 'only an original pending confirmation can accept a terminal answer');
+    }
+    if (step.phase === 'answer' && step.request) { await reconcileAnswer(loaded, original, client); return view(loaded); }
+    if (step.status !== 'waiting') fail('ENTROROVE_CHAIN_DECISION_REQUIRED', 'the original confirmation must be genuinely waiting');
+    const resumed = await client.invoke('task-resume', { flowId: loaded.state.identity.flowId }); checkCloudTask(resumed, loaded.state.identity);
+    const question = originalChainInteraction(step, loaded.state, resumed), payload = await readChainTerminalAnswer(question);
+    const invocation = { flowId: loaded.state.identity.flowId, operation: 'interaction-answer', payload };
+    await append(loaded, step.stepId, { ...step, phase: 'answer', status: 'running', request: null, humanActorLabel: input.actorId });
+    const current = loaded.state.steps.find(value => value.stepId === step.stepId);
+    const response = await cloudRequest(loaded, current, 'continue', invocation, client, 'answer');
+    if (response) {
+      const saved = loaded.state.steps.find(value => value.stepId === step.stepId), observed = inspectChainHumanResponse(original, loaded.state, saved, response);
+      await append(loaded, step.stepId, { ...saved, status: observed.eligible ? 'verified' : observed.state,
+        phase: observed.eligible ? 'done' : 'answer', output: { ...response.result, answer: response.result.auditEntry.answer }, response,
+        error: observed.eligible ? null : { code: observed.code } });
+    }
+    return view(loaded);
+  });
+}