@entrorove/skill 0.1.24 → 0.1.25

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);
+  });
+}

package/local-chain-human.mjs

@@ -0,0 +1,48 @@
+import { createInterface } from 'node:readline/promises';
+import { chainCanonical as canonical, chainFail as fail, chainSha as sha } from './local-chain-bindings.mjs';
+import { inspectLocalChainResult } from './local-chain-plan.mjs';
+
+export function originalChainInteraction(step, state, resumed) {
+  const value = step.output, current = resumed.result;
+  if (!value?.interaction || !value.interactionId || value.interactionDigest !== sha(canonical(value.interaction))
+    || current?.interactionId !== value.interactionId || current.interactionDigest !== value.interactionDigest
+    || canonical(current.interaction) !== canonical(value.interaction)
+    || resumed.nextStep?.operation !== 'continue' || resumed.nextStep.input?.flowId !== state.identity.flowId
+    || resumed.nextStep.input.operation !== 'interaction-answer') {
+    fail('ENTROROVE_CHAIN_INTERACTION_BINDING', 'answer must address the exact original live interaction');
+  }
+  const interaction = value.interaction;
+  if (interaction.callback?.operation !== 'interaction-answer' || canonical(interaction.callback.payload) !== '{}') {
+    fail('ENTROROVE_CHAIN_CALLBACK_UNSUPPORTED', 'this fixed host accepts only the original workflow interaction-answer callback');
+  }
+  return value;
+}
+export async function readChainTerminalAnswer(value) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) fail('ENTROROVE_CHAIN_TTY_REQUIRED', 'a real interactive terminal is required; redirected answers are rejected');
+  const interaction = value.interaction, ids = interaction.options?.map(option => option.id);
+  if (!['confirm', 'choice', 'multi', 'input'].includes(interaction.type) || !Array.isArray(ids)
+    || new Set(ids).size !== ids.length || (interaction.type !== 'input' && ids.length < 2)) {
+    fail('ENTROROVE_CHAIN_INTERACTION_BINDING', 'original interaction option contract is invalid');
+  }
+  process.stdout.write(`${interaction.question}\n${interaction.riskDescription ?? ''}\n`);
+  for (const option of interaction.options) process.stdout.write(`${option.id}: ${option.label}\n`);
+  const terminal = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  let answer; try { answer = (await terminal.question('Answer with the exact option ID: ')).trim(); } finally { terminal.close(); }
+  if (interaction.type === 'multi') answer = answer.split(',').map(value => value.trim());
+  if (interaction.type === 'input' ? !answer : Array.isArray(answer)
+    ? !answer.length || new Set(answer).size !== answer.length || answer.some(value => !ids.includes(value)) : !ids.includes(answer)) {
+    fail('ENTROROVE_CHAIN_ANSWER_INVALID', 'terminal answer must match explicit original option IDs');
+  }
+  return { interactionId: value.interactionId, interactionDigest: value.interactionDigest, answer, remembered: false };
+}
+export function inspectChainHumanResponse(original, state, step, response) {
+  const native = response.result, audit = native?.auditEntry, question = step.output.interaction;
+  if (response.flowId !== state.identity.flowId || native?.interactionId !== step.output.interactionId
+    || native.interactionDigest !== step.output.interactionDigest || audit?.schemaVersion !== 'confirm.audit-entry/1.0'
+    || audit.actorId !== state.identity.ownerId || audit.requestId !== question.requestId || audit.question !== question.question
+    || canonical(audit.answer) !== canonical(step.request.input.payload.answer) || audit.risk !== question.risk
+    || !audit.auditId || !Number.isFinite(Date.parse(audit.answeredAt))) {
+    fail('ENTROROVE_CHAIN_ANSWER_BINDING', 'answer has no matching original server-persisted audit and callback result');
+  }
+  return inspectLocalChainResult(original, { ...response, result: { ...native, answer: audit.answer } });
+}

package/local-chain-lock.mjs

@@ -0,0 +1,54 @@
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { chainControlFile, chainFail } from './local-chain-bindings.mjs';
+
+function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) chainFail('ENTROROVE_CHAIN_LOCK_INVALID', 'chain lock PID is invalid');
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+}
+async function owner(lock) {
+  const stat = await fs.lstat(lock);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o700
+    || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) {
+    chainFail('ENTROROVE_CHAIN_LOCK_INVALID', 'chain lock must be owned, private and real');
+  }
+  let value; try { value = JSON.parse((await chainControlFile(`${lock}/owner.json`, 1024)).bytes.toString()); }
+  catch { chainFail('ENTROROVE_CHAIN_LOCK_INVALID', 'chain lock owner is invalid'); }
+  if (!value || typeof value.token !== 'string' || !Number.isSafeInteger(value.pid)) {
+    chainFail('ENTROROVE_CHAIN_LOCK_INVALID', 'chain lock owner is invalid');
+  }
+  return { stat, value };
+}
+async function recover(lock) {
+  let original; try { original = await owner(lock); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  if (alive(original.value.pid)) return;
+  const removed = `${lock}.dead-${randomUUID()}`;
+  try { await fs.rename(lock, removed); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  const moved = await owner(removed);
+  if (moved.stat.ino !== original.stat.ino || moved.stat.dev !== original.stat.dev
+    || moved.value.token !== original.value.token) chainFail('ENTROROVE_CHAIN_LOCK_CHANGED', 'chain lock changed during recovery');
+  await fs.rm(removed, { recursive: true });
+}
+export async function withChainLock(file, action) {
+  const lock = `${file}.lock`, staging = `${lock}.private-${randomUUID()}`, token = randomUUID();
+  await fs.mkdir(staging, { mode: 0o700 });
+  const handle = await fs.open(`${staging}/owner.json`, 'wx', 0o600);
+  try { await handle.writeFile(JSON.stringify({ pid: process.pid, token })); await handle.sync(); } finally { await handle.close(); }
+  const deadline = Date.now() + 10_000;
+  try {
+    while (true) {
+      try { await fs.rename(staging, lock); break; }
+      catch (error) {
+        if (!['ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error;
+        await recover(lock);
+        if (Date.now() >= deadline) chainFail('ENTROROVE_CHAIN_BUSY', 'the original chain is running in another live host');
+        await new Promise(resolve => setTimeout(resolve, 25));
+      }
+    }
+    try { return await action(); }
+    finally {
+      if ((await owner(lock)).value.token !== token) chainFail('ENTROROVE_CHAIN_LOCK_CHANGED', 'chain lock ownership changed');
+      await fs.rm(lock, { recursive: true });
+    }
+  } finally { await fs.rm(staging, { recursive: true, force: true }); }
+}

package/local-chain-operations.mjs

@@ -0,0 +1,7 @@
+import { initLocalChain, resumeLocalChain, statusLocalChain, answerLocalChain, LOCAL_CHAIN_CONTROLLER_SCHEMA } from './local-chain-controller.mjs';
+export const LOCAL_CHAIN_OPERATIONS = Object.freeze({ 'chain-init': initLocalChain, 'chain-resume': resumeLocalChain,
+  'chain-status': statusLocalChain, 'chain-answer': answerLocalChain });
+export const LOCAL_CHAIN_CAPABILITIES = Object.freeze({ schemaVersion: LOCAL_CHAIN_CONTROLLER_SCHEMA,
+  operations: Object.keys(LOCAL_CHAIN_OPERATIONS), authority: 'original-workflow-step-results',
+  taskCompletionVerified: false, coordinatorStatus: 'adapter-pending', answerRequiresInteractiveTerminal: true,
+  legacyLedger: { operations: ['chain-ledger-init', 'chain-ledger-status', 'chain-ledger-query'], claimsExecution: false } });