@entrorove/skill 0.1.24 → 0.1.28

package/local-chain-plan.mjs

@@ -0,0 +1,232 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+export const LOCAL_CHAIN_PLAN_SCHEMA = 'entrorove.execution-plan/1.0';
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const KINDS = ['skill', 'coordinator', 'command'];
+const EVIDENCE_KINDS = ['test', 'build', 'lint', 'security', 'benchmark'];
+const RESERVED_ENV = /(?:TOKEN|SECRET|PASSWORD|PRIVATE.?KEY|AUTHORIZATION|CREDENTIAL)/i;
+const UNSAFE_TARGET = new Set(['__proto__', 'prototype', 'constructor']);
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![null, Object.prototype].includes(Object.getPrototypeOf(value))) fail('ENTROROVE_CHAIN_JSON', `${label} must be a JSON object`);
+  return value;
+}
+function fields(value, required, optional, label) {
+  object(value, label);
+  if (required.some(key => !Object.hasOwn(value, key))
+    || Object.keys(value).some(key => !required.includes(key) && !optional.includes(key))) {
+    fail('ENTROROVE_CHAIN_FIELDS', `${label} has missing or unknown fields`);
+  }
+}
+function identifier(value, label) {
+  if (typeof value !== 'string' || !ID.test(value)) fail('ENTROROVE_CHAIN_ID', `${label} must be a safe identifier`);
+}
+function jsonCopy(value) {
+  const seen = new WeakSet(); let entries = 0;
+  function visit(item, depth = 0) {
+    if (depth > 128) fail('ENTROROVE_CHAIN_JSON', 'plan JSON exceeds its nesting bound');
+    if (++entries > 100000) fail('ENTROROVE_CHAIN_JSON', 'plan JSON exceeds its control bound');
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return;
+    if (typeof item === 'number' && Number.isFinite(item)) return;
+    if (typeof item !== 'object' || seen.has(item)) fail('ENTROROVE_CHAIN_JSON', 'values must be finite acyclic JSON');
+    if (!Array.isArray(item)) object(item, 'value');
+    seen.add(item);
+    for (const child of Object.values(item)) visit(child, depth + 1);
+    seen.delete(item);
+  }
+  visit(value);
+  const bytes = JSON.stringify(value);
+  if (Buffer.byteLength(bytes) > 1024 * 1024) fail('ENTROROVE_CHAIN_JSON', 'plan JSON exceeds its control byte bound');
+  return JSON.parse(bytes);
+}
+function freeze(value) {
+  if (value && typeof value === 'object') { for (const child of Object.values(value)) freeze(child); Object.freeze(value); }
+  return value;
+}
+function pointer(value, target = false) {
+  if (typeof value !== 'string' || (value !== '' && !value.startsWith('/')) || /~(?![01])/u.test(value)) {
+    fail('ENTROROVE_CHAIN_POINTER', 'binding must use a valid RFC 6901 JSON Pointer');
+  }
+  const parts = value === '' ? [] : value.slice(1).split('/').map(part => part.replace(/~1/g, '/').replace(/~0/g, '~'));
+  if (target && (!parts.length || parts.some(part => UNSAFE_TARGET.has(part)))) {
+    fail('ENTROROVE_CHAIN_POINTER', 'binding target must name a declared safe input property');
+  }
+  return parts;
+}
+function position(value, part) {
+  if (Array.isArray(value)) {
+    if (!/^(0|[1-9][0-9]*)$/.test(part) || !Number.isSafeInteger(Number(part)) || Number(part) >= value.length) {
+      fail('ENTROROVE_CHAIN_POINTER', 'binding array index must identify an existing element');
+    }
+  } else object(value, 'pointer parent');
+  if (!Object.hasOwn(value, part)) fail('ENTROROVE_CHAIN_POINTER', 'binding pointer value is missing');
+  return part;
+}
+function readPointer(value, parts) {
+  let current = value;
+  for (const part of parts) current = current[position(current, part)];
+  return current;
+}
+function setPointer(value, parts, replacement) {
+  const parent = readPointer(value, parts.slice(0, -1));
+  const key = position(parent, parts.at(-1));
+  Object.defineProperty(parent, key, { value: jsonCopy(replacement), enumerable: true, configurable: true, writable: true });
+}
+function commandInput(input) {
+  fields(input, ['executable', 'args', 'workingDirectory', 'timeoutMs', 'evidenceKind', 'environment'], [], 'command input');
+  if (typeof input.executable !== 'string' || !input.executable || input.executable.includes('\0')
+    || !Array.isArray(input.args) || input.args.some(arg => typeof arg !== 'string' || arg.includes('\0'))
+    || typeof input.workingDirectory !== 'string' || !input.workingDirectory || input.workingDirectory.includes('\0')
+    || !Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > 3600000
+    || !EVIDENCE_KINDS.includes(input.evidenceKind)) fail('ENTROROVE_CHAIN_COMMAND', 'command policy is invalid');
+  object(input.environment, 'command environment');
+  for (const [key, value] of Object.entries(input.environment)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || RESERVED_ENV.test(key) || typeof value !== 'string' || value.includes('\0')) {
+      fail('ENTROROVE_CHAIN_ENVIRONMENT', 'command environment must contain explicit non-secret strings');
+    }
+  }
+  if (!path.isAbsolute(input.executable) && !input.environment.PATH) fail('ENTROROVE_CHAIN_COMMAND', 'relative executable requires an explicit PATH');
+  const directory = path.normalize(input.workingDirectory);
+  if (!path.isAbsolute(directory) && (directory === '..' || directory.startsWith(`..${path.sep}`))) {
+    fail('ENTROROVE_CHAIN_COMMAND', 'working directory cannot escape the original repository');
+  }
+}
+function validateBindings(step, previous) {
+  if (!Array.isArray(step.bindings)) fail('ENTROROVE_CHAIN_BINDING', 'step bindings must be an array');
+  if (step.kind === 'command' && step.bindings.length) fail('ENTROROVE_CHAIN_BINDING', 'command input cannot receive dynamic bindings');
+  const targets = [];
+  for (const binding of step.bindings) {
+    fields(binding, ['stepId', 'source', 'target'], [], 'binding');
+    if (!previous.has(binding.stepId)) fail('ENTROROVE_CHAIN_BINDING', 'binding source must name an earlier declared step');
+    pointer(binding.source);
+    const target = pointer(binding.target, true);
+    readPointer(step.input, target);
+    if (targets.some(parts => parts.every((part, index) => target[index] === part)
+      || target.every((part, index) => parts[index] === part))) fail('ENTROROVE_CHAIN_BINDING', 'binding targets cannot overlap');
+    targets.push(target);
+  }
+}
+function validateStep(step, previous, skills) {
+  fields(step, ['stepId', 'kind', 'skillId', 'operation', 'input', 'dependsOn', 'bindings'], ['continueWhen'], 'step');
+  identifier(step.stepId, 'stepId'); identifier(step.operation, 'operation'); object(step.input, 'step input');
+  if (previous.has(step.stepId) || !KINDS.includes(step.kind) || !Array.isArray(step.dependsOn)
+    || new Set(step.dependsOn).size !== step.dependsOn.length || step.dependsOn.some(id => !previous.has(id))) {
+    fail('ENTROROVE_CHAIN_TOPOLOGY', 'steps must have unique IDs and only earlier dependencies');
+  }
+  if (step.kind === 'skill' ? !skills.has(step.skillId) : step.skillId !== null) fail('ENTROROVE_CHAIN_SKILL', 'step skillId must match its declared kind and installed package declaration');
+  if (step.kind === 'command') {
+    if (step.operation !== 'exec') fail('ENTROROVE_CHAIN_COMMAND', 'command operation must be exec');
+    commandInput(step.input);
+  }
+  if (step.kind === 'coordinator' && step.operation === 'resolve-human') fail('ENTROROVE_CHAIN_DECISION', 'human resolution cannot be injected by a plan');
+  if (step.continueWhen !== undefined) {
+    if (step.kind !== 'skill' || step.skillId !== 'confirm-protocol' || step.operation !== 'interaction-request') {
+      fail('ENTROROVE_CHAIN_DECISION', 'continueWhen applies only to a declared confirmation request');
+    }
+    fields(step.continueWhen, ['answer'], [], 'continueWhen');
+    const answer = step.continueWhen.answer;
+    if (!(typeof answer === 'string' && answer.trim()) && !(Array.isArray(answer) && answer.length
+      && answer.every(item => typeof item === 'string' && item.trim()) && new Set(answer).size === answer.length)) {
+      fail('ENTROROVE_CHAIN_DECISION', 'continueWhen must declare an explicit string or unique choice IDs');
+    }
+  }
+  validateBindings(step, previous);
+}
+
+// Metadata validation never verifies installed packages, approves commands or
+// confers execution authority. The managed dispatcher retains those checks.
+export function validateLocalChainPlan(value) {
+  const plan = jsonCopy(value);
+  fields(plan, ['schemaVersion', 'chainId', 'skills', 'steps'], [], 'plan');
+  identifier(plan.chainId, 'chainId');
+  if (plan.schemaVersion !== LOCAL_CHAIN_PLAN_SCHEMA || !Array.isArray(plan.skills)
+    || !Array.isArray(plan.steps) || !plan.steps.length) fail('ENTROROVE_CHAIN_PLAN_INVALID', 'chain plan schema, skills and steps are required');
+  const skills = new Set();
+  for (const skill of plan.skills) {
+    fields(skill, ['skillId', 'packageRoot'], [], 'skill'); identifier(skill.skillId, 'skillId');
+    if (skills.has(skill.skillId) || typeof skill.packageRoot !== 'string' || !path.isAbsolute(skill.packageRoot)
+      || skill.packageRoot.includes('\0')) fail('ENTROROVE_CHAIN_SKILL', 'skills require unique IDs and absolute package declarations');
+    skills.add(skill.skillId);
+  }
+  const previous = new Set();
+  for (const step of plan.steps) { validateStep(step, previous, skills); previous.add(step.stepId); }
+  return freeze(plan);
+}
+
+// completed must come from the dispatcher's original durable outcomes. This
+// resolver does not authenticate caller-supplied results or advance a journal.
+export function bindLocalChainStepInput(value, stepId, completed) {
+  const plan = validateLocalChainPlan(value), index = plan.steps.findIndex(step => step.stepId === stepId);
+  if (index < 0) fail('ENTROROVE_CHAIN_STEP_UNKNOWN', 'binding target is outside the immutable plan');
+  if (!Array.isArray(completed)) fail('ENTROROVE_CHAIN_RESULT', 'completed outcomes must be an array');
+  const earlier = new Set(plan.steps.slice(0, index).map(step => step.stepId)), results = new Map();
+  for (const result of completed) {
+    fields(result, ['stepId', 'status', 'output'], [], 'completed outcome');
+    if (!earlier.has(result.stepId) || results.has(result.stepId)) fail('ENTROROVE_CHAIN_RESULT', 'outcomes must belong to unique earlier steps');
+    results.set(result.stepId, jsonCopy(result));
+  }
+  const step = plan.steps[index];
+  for (const dependency of new Set([...step.dependsOn, ...step.bindings.map(binding => binding.stepId)])) {
+    if (results.get(dependency)?.status !== 'succeeded') fail('ENTROROVE_CHAIN_DEPENDENCY', 'binding requires the original successful dependency outcome');
+  }
+  const input = jsonCopy(step.input);
+  for (const binding of step.bindings) setPointer(input, pointer(binding.target, true), readPointer(results.get(binding.stepId).output, pointer(binding.source)));
+  return input;
+}
+
+function statuses(value, found = new Set()) {
+  if (value && typeof value === 'object') {
+    if (typeof value.status === 'string') found.add(value.status);
+    for (const child of Object.values(value)) statuses(child, found);
+  }
+  return found;
+}
+function equal(left, right) { return JSON.stringify(left) === JSON.stringify(right); }
+function gate(state, code) { return Object.freeze({ state, code, eligible: state === 'eligible', executionVerified: false, authority: 'protocol-shape-only' }); }
+
+// A protocol-success envelope is necessary, never proof of actual execution.
+// The dispatcher must authenticate its broker/runner result before committing.
+export function inspectLocalChainResult(step, observed) {
+  object(step, 'step'); const response = jsonCopy(observed);
+  if (!KINDS.includes(step.kind)) fail('ENTROROVE_CHAIN_STEP_INVALID', 'result gate requires a declared step kind');
+  object(response, 'response');
+  const output = response.output ?? response.result ?? response;
+  object(output, 'protocol output');
+  const states = new Set([response.status, output.status]);
+  if (states.has('uncertain') || output.process?.status === 'uncertain') return gate('uncertain', 'ENTROROVE_CHAIN_OUTCOME_UNCERTAIN');
+  if (states.has('failed')) return gate('failed', 'ENTROROVE_CHAIN_RESULT_FAILED');
+  if (states.has('blocked')) return gate('blocked', 'ENTROROVE_CHAIN_RESULT_BLOCKED');
+  if (['waiting', 'pending', 'pending-execution', 'incomplete'].some(state => states.has(state))
+    || statuses(output).has('pending-execution')) return gate('waiting', 'ENTROROVE_CHAIN_RESULT_PENDING');
+  if (response.status !== 'succeeded') return gate('waiting', 'ENTROROVE_CHAIN_RESULT_UNVERIFIED');
+  if (step.kind === 'command') {
+    const process = output.process ?? output;
+    if (!Number.isInteger(process.exitCode)) return gate('uncertain', 'ENTROROVE_CHAIN_PROCESS_UNKNOWN');
+    if (process.exitCode !== 0 || process.signal || process.timedOut || process.outputLimitExceeded) return gate('failed', 'ENTROROVE_CHAIN_PROCESS_FAILED');
+  }
+  if (step.kind === 'skill' && step.skillId === 'validator') {
+    const verdict = output.report?.verdict ?? output.verdict;
+    if (step.operation === 'verdict' && !['pass', 'pass-with-risk'].includes(verdict)) return gate(verdict === 'blocked' ? 'blocked' : 'waiting', 'ENTROROVE_CHAIN_VALIDATOR_VERDICT');
+    if (step.operation === 'functional-verify') {
+      if (output.summary?.failed > 0 || output.evidence?.some(item => item.exitCode !== 0)) return gate('blocked', 'ENTROROVE_CHAIN_VALIDATOR_FAILED');
+      if (!Array.isArray(output.evidence) || !output.evidence.length || output.evidence.some(item => item.runner !== 'trusted-runner' || !item.receipt)) return gate('waiting', 'ENTROROVE_CHAIN_VALIDATOR_INCOMPLETE');
+    }
+  }
+  if (step.kind === 'skill' && step.skillId === 'confirm-protocol' && step.operation === 'interaction-request') {
+    if (!step.continueWhen || !Object.hasOwn(output, 'answer')) return gate('waiting', 'ENTROROVE_CHAIN_DECISION_REQUIRED');
+    if (!equal(output.answer, step.continueWhen.answer)) return gate('blocked', 'ENTROROVE_CHAIN_DECISION_DENIED');
+  }
+  return gate('eligible', 'ENTROROVE_CHAIN_AUTHENTICATION_REQUIRED');
+}
+
+export function localChainPlanDigest(plan) {
+  const value = validateLocalChainPlan(plan);
+  function canonical(item) {
+    if (Array.isArray(item)) return `[${item.map(canonical).join(',')}]`;
+    if (item && typeof item === 'object') return `{${Object.keys(item).sort().map(key => `${JSON.stringify(key)}:${canonical(item[key])}`).join(',')}}`;
+    return JSON.stringify(item);
+  }
+  return createHash('sha256').update(canonical(value)).digest('hex');
+}

package/local-chain-release-labels.mjs

@@ -0,0 +1,12 @@
+export const chainReleaseLabels = Object.freeze({
+  'local-chain-plan.mjs': { zh: '原链严格计划与结果门禁', en: 'strict original-chain plan and result gates' },
+  'local-chain-bindings.mjs': { zh: '原链安装元数据与执行映射', en: 'original-chain installed metadata and execution bindings' },
+  'local-chain-lock.mjs': { zh: '原链宿主锁与中断恢复', en: 'original-chain host locks and interruption recovery' },
+  'local-chain-broker.mjs': { zh: '原链同流程技能调用', en: 'original-chain skill calls on the same workflow' },
+  'local-chain-human.mjs': { zh: '原链终端确认与真实回调', en: 'original-chain terminal confirmation and original callbacks' },
+  'local-chain-controller.mjs': { zh: '原链持久受控执行器', en: 'durable original-chain controlled executor' },
+  'local-chain-contracts.mjs': { zh: '原链本地严格操作契约', en: 'strict original-chain local operation contracts' },
+  'local-chain-operations.mjs': { zh: '原链受控操作入口', en: 'original-chain controlled operation entry points' },
+  'local-chain-release-labels.mjs': { zh: '原链独立更新说明', en: 'independent original-chain release descriptions' },
+  'local-chain-results.mjs': { zh: '原链结果与退出状态', en: 'original-chain results and exit states' },
+});

package/local-chain-results.mjs

@@ -0,0 +1,75 @@
+import { observeWorkflowLocalStep } from './workflow-local-runner.mjs';
+import { buildInvocation } from './remote-client.mjs';
+import { inspectChainSkillResponse } from './local-chain-broker.mjs';
+import { inspectChainHumanResponse } from './local-chain-human.mjs';
+import { bindLocalChainStepInput } from './local-chain-plan.mjs';
+import { chainCanonical as canonical, chainFail as fail, chainSha as sha } from './local-chain-bindings.mjs';
+
+function denied(message) { fail('ENTROROVE_CHAIN_RESULT_BINDING', message); }
+async function commandResult(state, original, step) {
+  const binding = state.commandBindings.find(value => value.stepId === original.stepId);
+  if (!binding || step.phase !== 'done' || !step.localResult?.receipt || !step.output || step.error !== null) {
+    denied('verified command has no original process receipt and result');
+  }
+  let actual;
+  try { actual = await observeWorkflowLocalStep(binding.workflowInput); }
+  catch { denied('verified command has no independently valid original native cache'); }
+  if (!actual?.receipt || actual.status !== 'reported' || actual.receipt.result?.passed !== true
+    || ['process', 'evidence', 'receipt', 'subject', 'statePath'].some(key => canonical(actual[key]) !== canonical(step.localResult[key]))) {
+    denied('verified command differs from its actual signed native process');
+  }
+  const output = step.output, lease = binding.workflowInput.lease;
+  if (output.status !== 'verified' || output.flowId !== state.identity.flowId || output.stepId !== step.stepId
+    || output.generation !== lease.generation || canonical(output.lease) !== canonical(lease)
+    || output.evidenceDigest !== sha(canonical(actual.evidence[0])) || canonical(output.evidence) !== canonical(actual.evidence[0])
+    || output.verification?.summary?.passed !== 1 || output.verification.summary.failed !== 0
+    || output.verification.findings?.length !== 0) denied('verified command has no matching independent verification of its exact original receipt');
+}
+function skillRequest(state, original, step) {
+  if (step.phase !== 'done' || !step.response || !step.request || step.error !== null) denied('verified skill has no original durable request result');
+  const preceding = state.steps.filter(value => value.status === 'verified' && value.stepId !== original.stepId)
+    .map(value => ({ stepId: value.stepId, status: 'succeeded', output: value.output }));
+  const bound = bindLocalChainStepInput(state.plan, original.stepId, preceding);
+  const answer = original.skillId === 'confirm-protocol' && original.operation === 'interaction-request' && step.response.result?.auditEntry;
+  const expected = answer ? buildInvocation('continue', step.request.input)
+    : buildInvocation('continue', { flowId: state.identity.flowId, operation: original.operation, payload: bound });
+  if (step.request.operation !== 'continue' || step.request.requestId !== expected.requestId || step.response.requestId !== expected.requestId
+    || canonical(step.request.input) !== canonical(expected.body.input)) denied('verified skill lost its exact original canonical request');
+  if (answer) {
+    const saved = { ...step, output: step.originalInteraction };
+    if (!saved.output?.interaction || saved.output.interactionDigest !== sha(canonical(saved.output.interaction))
+      || step.request.input.flowId !== state.identity.flowId || step.request.input.operation !== 'interaction-answer'
+      || step.request.input.payload.interactionId !== saved.output.interactionId
+      || step.request.input.payload.interactionDigest !== saved.output.interactionDigest
+      || !inspectChainHumanResponse(original, state, saved, step.response).eligible) denied('verified answer lacks its original audited callback');
+    if (canonical(step.output) !== canonical({ ...step.response.result, answer: step.response.result.auditEntry.answer })) denied('verified answer changed its original audited output');
+  } else if (!inspectChainSkillResponse(original, state, step.response).eligible || canonical(step.output) !== canonical(step.response.result)) {
+    denied('verified skill changed its actual original protocol result');
+  }
+  return expected.requestId;
+}
+export async function validateArchivedChainResults(state) {
+  for (const original of state.plan.steps) {
+    const step = state.steps.find(value => value.stepId === original.stepId);
+    if (step.status !== 'verified') continue;
+    if (original.kind === 'command') await commandResult(state, original, step);
+    else if (original.kind === 'skill') skillRequest(state, original, step);
+    else denied('local ledger cannot manufacture a verified coordinator result');
+  }
+}
+export async function revalidateArchivedChainSkill(state, original, step, client) {
+  const requestId = skillRequest(state, original, step);
+  let observed;
+  try { observed = await client.status(requestId); } catch { denied('original verified skill result is unavailable; never replay its operation'); }
+  if (canonical(observed) !== canonical(step.response)) denied('archived skill differs from the actual durable original request result');
+}
+export async function revalidateArchivedChainCommand(state, original, step, client) {
+  await commandResult(state, original, step);
+  const request = buildInvocation('continue', { flowId: state.identity.flowId,
+    operation: 'execution-verify', payload: { stepId: original.stepId } });
+  let observed;
+  try { observed = await client.status(request.requestId); }
+  catch { denied('the original command has no actual durable independent verification; never manufacture or replay it'); }
+  if (observed.requestId !== request.requestId || !['succeeded', 'reported'].includes(observed.status)
+    || canonical(observed.result) !== canonical(step.output)) denied('archived command differs from the actual independently verified original request');
+}

package/local-cli.mjs

@@ -21,7 +21,9 @@ import { withBudgetReadContext } from './local-budget-reads.mjs';
 import { LOCAL_BUDGET_TRANSITION_OPERATIONS } from './local-budget-transition.mjs';
 import { ARCHGUARD_LOCAL_OPERATIONS } from './local-archguard-operations.mjs';
 import { LOCAL_BUDGET_HANDOFF_OPERATIONS } from './local-budget-handoff.mjs';
+import { LOCAL_CHAIN_OPERATIONS } from './local-chain-operations.mjs';
 import { runManagedWorkflowLocalStep } from './workflow-local-client.mjs';
+import { localErrorEnvelope } from './local-error.mjs';
 
 async function stdinJson() {
   let raw = '';
@@ -48,7 +50,7 @@ const operations = {
   'formula-final-gate': input => formulaFinalGate(input.engine, input), 'calculation-final-gate': formulaFinalGateFile,
   'run-approved-plan': runApprovedPlan,
   'workflow-run-step': runManagedWorkflowLocalStep,
-  ...LOCAL_LEDGER_OPERATIONS, ...LOCAL_BUDGET_TRANSITION_OPERATIONS,
+  ...LOCAL_LEDGER_OPERATIONS, ...LOCAL_CHAIN_OPERATIONS, ...LOCAL_BUDGET_TRANSITION_OPERATIONS,
   ...LOCAL_RENEWAL_OPERATIONS, ...LOCAL_PROBE_OPERATIONS,
   ...LOCAL_TASK_ROUTING_OPERATIONS,
   ...ARCHGUARD_LOCAL_OPERATIONS,
@@ -66,20 +68,25 @@ async function checkedLocalInput(operation, input) {
   }
 }
 
-export async function runLocal(args = []) {
-  const operation = args[0];
-  if (operation === 'capabilities' || operation === 'help') {
-    validateLocalInput(operation, process.stdin.isTTY ? {} : await stdinJson());
-    process.stdout.write(`${JSON.stringify(LOCAL_CAPABILITIES)}\n`); return;
+export async function runLocal(args = [], dependencies) {
+  try {
+    const operation = args[0];
+    if (operation === 'capabilities' || operation === 'help') {
+      validateLocalInput(operation, process.stdin.isTTY ? {} : await stdinJson());
+      process.stdout.write(`${JSON.stringify(LOCAL_CAPABILITIES)}\n`); return;
+    }
+    const handler = operations[operation];
+    if (!handler) throw new Error(`Usage: entrorove local <${['capabilities', ...Object.keys(operations)].join('|')}> [repositoryRoot]`);
+    const input = await stdinJson();
+    if (args[1] && input.repositoryRoot === undefined) input.repositoryRoot = args[1];
+    const validated = await checkedLocalInput(operation, input);
+    const supplied = operation === 'workflow-run-step' || Object.hasOwn(LOCAL_CHAIN_OPERATIONS, operation) ? dependencies : undefined;
+    const output = await withLocalInvocation(operation, validated, () => withBudgetReadContext(validated, () => handler(validated, supplied)));
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+    if (['pending', 'blocked', 'failed', 'incomplete'].includes(output?.status)) process.exitCode = 2;
+  } catch (cause) {
+    const error = localErrorEnvelope(cause); process.stderr.write(`${JSON.stringify(error)}\n`); process.exitCode = error.status === 'blocked' ? 2 : 1;
   }
-  const handler = operations[operation];
-  if (!handler) throw new Error(`Usage: entrorove local <${['capabilities', ...Object.keys(operations)].join('|')}> [repositoryRoot]`);
-  const input = await stdinJson();
-  if (args[1] && input.repositoryRoot === undefined) input.repositoryRoot = args[1];
-  const validated = await checkedLocalInput(operation, input);
-  const output = await withLocalInvocation(operation, validated, () => withBudgetReadContext(validated, () => handler(validated)));
-  process.stdout.write(`${JSON.stringify(output)}\n`);
-  if (output?.status === 'blocked' || output?.status === 'failed' || output?.status === 'incomplete') process.exitCode = 2;
 }
 
 export async function runLocalInput(operation, input, dependencies) {
@@ -87,5 +94,6 @@ export async function runLocalInput(operation, input, dependencies) {
   const handler = operations[operation];
   if (!handler) throw new Error(`Unsupported local operation: ${operation}`);
   const validated = await checkedLocalInput(operation, input);
-  return withLocalInvocation(operation, validated, () => withBudgetReadContext(validated, () => handler(validated, operation === 'workflow-run-step' ? dependencies : undefined)));
+  const supplied = operation === 'workflow-run-step' || Object.hasOwn(LOCAL_CHAIN_OPERATIONS, operation) ? dependencies : undefined;
+  return withLocalInvocation(operation, validated, () => withBudgetReadContext(validated, () => handler(validated, supplied)));
 }

package/local-contract-types.mjs

@@ -35,7 +35,7 @@ function expression(operators, minItems, maxItems) {
 }
 export const formulaDefinitions = { formula: { oneOf: [
   object({ ref: text }, ['ref']), object({ lit: decimal }, ['lit']),
-  expression(['add', 'mul'], 0), expression(['sub', 'div', 'safeDivide', 'percentOf'], 2, 2),
+  expression(['add', 'mul'], 1), expression(['sub', 'div', 'safeDivide', 'percentOf'], 2, 2),
   expression(['round'], 1, 1), expression(['if'], 3, 3),
 ] } };
 export const decimalValues = { type: 'object', additionalProperties: decimal };

package/local-contracts.mjs

@@ -7,6 +7,7 @@ import { ARCHGUARD_LOCAL_OPERATION_SCHEMAS } from './local-archguard-contracts.m
 import { MERGE_LOCAL_OPERATION_SCHEMAS } from './local-merge-contracts.mjs';
 import { WORKFLOW_LOCAL_OPERATION_SCHEMA } from './workflow-local-contracts.mjs';
 import { HANDOFF_WRITE_PASS_SCHEMA, HANDOFF_PROVISIONAL_LEASE_SCHEMA, HANDOFF_SNAPSHOT_CANDIDATE_SCHEMA } from './local-task-handoff-contracts.mjs';
+import { LOCAL_CHAIN_OPERATION_SCHEMAS } from './local-chain-contracts.mjs';
 import { array, binding, change, confirmation, enumeration, evidence, evidenceArray, executionContext, executionPlan,
   formula, formulaDefinitions, formulaEntry, decimalValues, identifier, integer, ledgerIdentifier, modes, nullable, object, paths, record, relativePath, sha256, text } from './local-contract-types.mjs';
 
@@ -72,6 +73,7 @@ const chain = { ...base, chainId: ledgerIdentifier };
 add('chain-resume', { ...chain, stepId: ledgerIdentifier, status: enumeration(['running', 'waiting', 'reported', 'verified', 'blocked', 'failed']), output: {}, error: {} }, ['repositoryRoot', 'chainId']);
 add('chain-status|chain-ledger-status', chain, ['repositoryRoot', 'chainId']);
 add('chain-answer', { ...chain, stepId: ledgerIdentifier, answer: { anyOf: [text, object({ id: text }, ['id'])] }, accepted: { type: 'boolean' }, actorId: nullable(text) }, ['repositoryRoot', 'chainId', 'answer']);
+Object.assign(schemas, LOCAL_CHAIN_OPERATION_SCHEMAS);
 const renewal = { ...flow, requestId: identifier, scope: object({ goal: text, allowedPaths: paths, forbiddenPaths: paths }, ['goal', 'allowedPaths']), policy: object({ intervalMs: integer(1), maxRenewals: integer(1, 100) }, ['intervalMs', 'maxRenewals']) };
 add('budget-auto-renew-request', renewal, ['repositoryRoot', 'flowId', 'requestId', 'scope', 'policy']);
 add('budget-auto-renew', { ...renewal, confirmation, grant: record }, ['repositoryRoot', 'flowId', 'requestId', 'scope', 'policy'], ['grant', 'confirmation']);

package/local-error.mjs

@@ -0,0 +1,23 @@
+export const LOCAL_ERROR_SCHEMA = 'entrorove.local-error/1.0';
+
+const BLOCKED_CODES = new Set([
+  'ENTROROVE_MUTATE_NOT_ACCEPTED', 'ENTROROVE_MUTATION_AUTHORITY_REQUIRED',
+  'ENTROROVE_MUTATION_PASS_INVALID', 'ENTROROVE_MUTATION_PASS_EXPIRED',
+  'ENTROROVE_BUDGET_LEASE_EXPIRED', 'ENTROROVE_BUDGET_AUTHORITY_REQUIRED',
+  'ENTROROVE_SWARM_AUTHORITY_INVALID', 'ENTROROVE_SWARM_CLOUD_AUTHORITY_REQUIRED',
+  'ENTROROVE_HANDOFF_FENCE', 'ENTROROVE_HANDOFF_WRITE_REVOKED',
+  'ENTROROVE_HANDOFF_WRITE_BINDING', 'ENTROROVE_HANDOFF_WRITE_SNAPSHOT',
+  'ENTROROVE_SNAPSHOT_CORRUPT', 'ENTROROVE_SNAPSHOT_INVALID',
+]);
+
+export function localErrorStatus(error) {
+  const code = typeof error?.code === 'string' ? error.code : '';
+  return BLOCKED_CODES.has(code) || /(?:AUTHORITY_REQUIRED|LEASE_EXPIRED|NOT_ACCEPTED|REVOKED)$/.test(code)
+    ? 'blocked' : 'failed';
+}
+
+export function localErrorEnvelope(error, fallbackCode = 'ENTROROVE_LOCAL_FAILURE') {
+  const code = typeof error?.code === 'string' && error.code ? error.code : fallbackCode;
+  const message = typeof error?.message === 'string' && error.message ? error.message : 'Local operation failed';
+  return { schemaVersion: LOCAL_ERROR_SCHEMA, status: localErrorStatus({ ...error, code }), code, message };
+}

package/local-execution.mjs

@@ -178,7 +178,7 @@ async function loadReceipt(input) { return loadSnapshotReceipt14(input.receipt);
 async function snapshotAuthority(input, root, receipt) { return snapshotAuthority14(input, root, receipt); }
 export async function mutateGate(input) { return mutateGate14(input); }
 export async function issueMutationPass(input) { return issueMutationPass14(input); }
-export async function verifyMutationPass(input) { return verifyMutationPass14(input); }
+export async function verifyMutationPass(input, options) { return verifyMutationPass14(input, options); }
 async function writeSnapshotFile(input, root, targetPath, baseline) {
   if (!baseline || input.expectedSha256 && input.expectedSha256 !== baseline.sha256) fail('ENTROROVE_WRITE_BASELINE', 'target does not match its exact expected snapshot baseline');
   const content = typeof input.content === 'string' ? input.content : JSON.stringify(input.content);

package/local-final-gate16-bundle.mjs

@@ -6,8 +6,8 @@ export const FINAL_GATE16_CHECKER_PINS = Object.freeze({
   'local-final-gate16-worker.mjs': '344d64b6c1c5552b96960e0d8514a876a3dbfa9762ab9eb749038e8351727121',
   'local-final-gate16-checks.mjs': '1dd30e9666d458d8b12ca6e4975f6f0ac8450c3ea9cbecc7401ae037f66b589a',
   'local-decimal.mjs': '93580b0cbdac2e881942658c1cd10394b432219f8657afaaaf4cb1c35c91d644',
-  'local-formula-ast.mjs': 'e7475176409f146f46eb8565be8df4108c88f12b46c9b600915834f9843089d7',
-  'local-formula-engine.mjs': '3b6ed599575b17d3da738e0c798804264540cbff87c58459e2ef3fa6072cd003',
+  'local-formula-ast.mjs': '768ec4aa88a127588035d5b94aa2721df00e3e0576dc7e341baaead44795f314',
+  'local-formula-engine.mjs': 'cfc44f03bb8dc4797f9f9e859a64a2dd5e4dd316db45624c03f7f8fad3202ede',
   'local-formula-tests.mjs': 'd6d2809572c46955e6b556023ed6a12362c8acd0ad0d5be3b1b2dd64439215c0',
 });
 export async function finalGate16Bundle() {

package/local-formula-ast.mjs

@@ -1,7 +1,8 @@
 import { Decimal, formulaError } from './local-decimal.mjs';
 
 export const FORMULA_OPERATORS = Object.freeze(['add', 'sub', 'mul', 'div', 'safeDivide', 'percentOf', 'round', 'if']);
-const ARITY = { add: [0, 1000], mul: [0, 1000], sub: [2, 2], div: [2, 2], safeDivide: [2, 2], percentOf: [2, 2], round: [1, 1], if: [3, 3] };
+export const FORMULA_ROUNDING_POLICY = Object.freeze({ decimalPlaces: 2, mode: 'half-away-from-zero' });
+const ARITY = { add: [1, 1000], mul: [1, 1000], sub: [2, 2], div: [2, 2], safeDivide: [2, 2], percentOf: [2, 2], round: [1, 1], if: [3, 3] };
 export function formulaKey(value) {
   if (typeof value !== 'string' || !value.trim() || value.length > 128 || /[\u0000-\u001f\u007f]/.test(value)) throw formulaError('FORMULA_KEY_INVALID', 'formula and field keys must be non-empty strings of at most 128 characters');
   return value;
@@ -30,28 +31,35 @@ export function formulaRefs(node, output = new Set()) {
   if (node.args) for (const item of node.args) formulaRefs(item, output);
   return [...output].sort();
 }
-function evaluateNode(node, resolve) {
+function roundPlaces(policy) {
+  const value = policy?.decimalPlaces;
+  if (!Number.isInteger(value) || value < 0 || value > 28) throw formulaError('ROUND_POLICY_INVALID', 'rounding policy decimalPlaces must be an integer from 0 to 28');
+  if (policy.mode !== 'half-away-from-zero') throw formulaError('ROUND_POLICY_INVALID', 'rounding policy mode must be half-away-from-zero');
+  return value;
+}
+function evaluateNode(node, resolve, policy) {
   if (Object.hasOwn(node, 'lit')) return Decimal.from(node.lit);
   if (Object.hasOwn(node, 'ref')) return Decimal.from(resolve(node.ref));
   const [left, right, alternate] = node.args;
   switch (node.op) {
-    case 'add': return node.args.reduce((total, item) => total.plus(evaluateNode(item, resolve)), Decimal.from('0'));
-    case 'mul': return node.args.reduce((total, item) => total.times(evaluateNode(item, resolve)), Decimal.from('1'));
-    case 'sub': return evaluateNode(left, resolve).minus(evaluateNode(right, resolve));
-    case 'div': return evaluateNode(left, resolve).div(evaluateNode(right, resolve));
-    case 'safeDivide': { const denominator = evaluateNode(right, resolve); return denominator.isZero() ? Decimal.from('0') : evaluateNode(left, resolve).div(denominator); }
-    case 'percentOf': return evaluateNode(left, resolve).div(evaluateNode(right, resolve)).times('100');
-    case 'round': return evaluateNode(left, resolve).rounded(2);
-    case 'if': return evaluateNode(left, resolve).isZero() ? evaluateNode(alternate, resolve) : evaluateNode(right, resolve);
+    case 'add': return node.args.reduce((total, item) => total.plus(evaluateNode(item, resolve, policy)), Decimal.from('0'));
+    case 'mul': return node.args.reduce((total, item) => total.times(evaluateNode(item, resolve, policy)), Decimal.from('1'));
+    case 'sub': return evaluateNode(left, resolve, policy).minus(evaluateNode(right, resolve, policy));
+    case 'div': return evaluateNode(left, resolve, policy).div(evaluateNode(right, resolve, policy));
+    case 'safeDivide': { const denominator = evaluateNode(right, resolve, policy); if (denominator.isZero()) throw formulaError('DIV_ZERO', 'division by zero', { nodeId: 'safeDivide' }); return evaluateNode(left, resolve, policy).div(denominator); }
+    case 'percentOf': return evaluateNode(left, resolve, policy).div(evaluateNode(right, resolve, policy)).times('100');
+    case 'round': return evaluateNode(left, resolve, policy).rounded(roundPlaces(policy));
+    case 'if': return evaluateNode(left, resolve, policy).isZero() ? evaluateNode(alternate, resolve, policy) : evaluateNode(right, resolve, policy);
     default: throw formulaError('UNSUPPORTED_OPERATOR', 'unsupported normalized formula operator');
   }
 }
-export function evaluateFormula(node, values = {}) {
+export function evaluateFormula(node, values = {}, options = {}) {
   formulaObject(values, 'formula values');
+  const policy = options.roundingPolicy ?? FORMULA_ROUNDING_POLICY;
   return evaluateNode(normalizeFormula(node), key => {
     if (!Object.hasOwn(values, key) || values[key] === null || values[key] === undefined || values[key] === '') throw formulaError('MISSING_INPUT', `missing input: ${key}`, { fieldId: key });
     return values[key];
-  });
+  }, policy);
 }
 export function compileFormulaGraph(formulas, fieldKeys) {
   if (!Array.isArray(formulas) || formulas.length > 1000) throw formulaError('FORMULA_GRAPH_INVALID', 'formulas must be an array of at most 1000 definitions');
@@ -78,8 +86,9 @@ export function compileFormulaGraph(formulas, fieldKeys) {
   for (const key of [...definitions.keys()].sort()) visit(key);
   return { formulas: [...definitions.values()].sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0), dependencies, order };
 }
-export function evaluateFormulaGraph(formulas, inputs = {}) {
+export function evaluateFormulaGraph(formulas, inputs = {}, options = {}) {
   formulaObject(inputs, 'formula inputs');
+  const policy = options.roundingPolicy ?? FORMULA_ROUNDING_POLICY;
   const values = new Map(Object.entries(inputs).map(([key, value]) => [key, Decimal.from(value)]));
   const graph = compileFormulaGraph(formulas);
   const definitions = new Map(graph.formulas.map(item => [item.key, item.expression]));
@@ -91,7 +100,7 @@ export function evaluateFormulaGraph(formulas, inputs = {}) {
       return values.get(key);
     }
     if (visiting.has(key)) throw formulaError('FORMULA_CYCLE', `formula cycle at ${key}`);
-    visiting.add(key); const value = evaluateNode(definitions.get(key), resolve); visiting.delete(key); results.set(key, value); return value;
+    visiting.add(key); const value = evaluateNode(definitions.get(key), resolve, policy); visiting.delete(key); results.set(key, value); return value;
   };
   return Object.fromEntries(graph.formulas.map(item => [item.key, resolve(item.key).toString()]));
 }

package/local-formula-engine.mjs

@@ -1,9 +1,10 @@
 import { createHash } from 'node:crypto';
 import { Decimal, DECIMAL_POLICY, formulaError } from './local-decimal.mjs';
-import { compileFormulaGraph, evaluateFormulaGraph, formulaKey, formulaObject } from './local-formula-ast.mjs';
+import { compileFormulaGraph, evaluateFormulaGraph, formulaKey, formulaObject, FORMULA_ROUNDING_POLICY } from './local-formula-ast.mjs';
 
 export const FORMULA_SCHEMA = 'entrorove.formula-engine/1.0';
 export const FORMULA_RUNTIME_VERSION = 'decimal28-ast/1.0';
+export { FORMULA_ROUNDING_POLICY };
 const TYPES = ['number', 'integer', 'money', 'percent', 'text', 'date', 'enum'];
 const NUMERIC = TYPES.slice(0, 4);
 const ID = /^[a-z0-9][a-z0-9._-]{0,127}$/;
@@ -21,6 +22,14 @@ function cloned(value) { return JSON.parse(formulaCanonical(value)); }
 function requiredText(value, field) {
   if (typeof value !== 'string' || !value.trim()) throw formulaError('ENGINE_REQUIRED_FIELD', `${field} is required`);
 }
+function normalizeRoundingPolicy(value) {
+  const policy = value ?? FORMULA_ROUNDING_POLICY;
+  formulaObject(policy, 'roundingPolicy');
+  if (Object.keys(policy).sort().join(',') !== 'decimalPlaces,mode'
+    || !Number.isInteger(policy.decimalPlaces) || policy.decimalPlaces < 0 || policy.decimalPlaces > 28
+    || policy.mode !== 'half-away-from-zero') throw formulaError('ROUND_POLICY_INVALID', 'roundingPolicy must declare decimalPlaces 0..28 and half-away-from-zero mode');
+  return { decimalPlaces: policy.decimalPlaces, mode: policy.mode };
+}
 export function normalizeEngine(engine) {
   formulaObject(engine, 'engine');
   if (engine.schemaVersion !== 'engine.spec/1') throw formulaError('ENGINE_SCHEMA_VERSION', 'Expected engine.spec/1');
@@ -41,12 +50,14 @@ export function normalizeEngine(engine) {
     if (NUMERIC.includes(field.type) && typeof field.unit !== 'string') throw formulaError('FIELD_UNIT_MISSING', 'numeric fields require an explicit unit');
     if (field.required !== undefined && typeof field.required !== 'boolean') throw formulaError('FIELD_REQUIRED_INVALID', 'field required must be boolean');
   }
+  const roundingPolicy = normalizeRoundingPolicy(engine.roundingPolicy);
   const graph = compileFormulaGraph(engine.formulas, [...keys]);
   for (const item of graph.formulas) for (const ref of graph.dependencies[item.key]) {
     const field = engine.fields.find(entry => entry.key === ref);
     if (field && !NUMERIC.includes(field.type)) throw formulaError('FORMULA_REF_TYPE', `formula reference ${ref} must be numeric`);
   }
   const normalized = cloned(engine);
+  normalized.roundingPolicy = roundingPolicy;
   normalized.formulas = engine.formulas.map(item => ({ ...cloned(item), expression: graph.formulas.find(entry => entry.key === item.key).expression }));
   return { engine: normalized, graph };
 }
@@ -62,7 +73,8 @@ export function buildFormulaEngine(requirements) {
     semanticVersion: requirements.semanticVersion ?? '1.0.0', status: 'draft', compatibilityProfile: 'legacy-compatible',
     decimalPolicy: requirements.decimalPolicy ?? 'decimal-string', defaultLocale: requirements.defaultLocale ?? 'zh-CN',
     category: requirements.category ?? 'general', inputMethod: requirements.inputMethod ?? 'manual', output: requirements.output ?? ['metric-cards'],
-    constraints: requirements.constraints ?? '', fields: requirements.inputs, formulas: requirements.formulas,
+    constraints: requirements.constraints ?? '', roundingPolicy: requirements.roundingPolicy ?? FORMULA_ROUNDING_POLICY,
+    fields: requirements.inputs, formulas: requirements.formulas,
     rules: requirements.rules ?? [], views: requirements.views ?? [], importProfiles: requirements.importProfiles ?? [],
     reports: requirements.reports ?? [], testSuites: requirements.testSuites ?? [], acceptance: requirements.acceptance ?? '',
   };
@@ -71,6 +83,7 @@ export function buildFormulaEngine(requirements) {
 export function compileFormulaEngine(engine) {
   const normalized = normalizeEngine(engine);
   const program = { schemaVersion: FORMULA_SCHEMA, runtimeVersion: FORMULA_RUNTIME_VERSION, decimalPolicy: DECIMAL_POLICY,
+    roundingPolicy: normalized.engine.roundingPolicy,
     engineId: normalized.engine.engineId, engineVersion: normalized.engine.semanticVersion,
     engineDigest: formulaDigest(normalized.engine), engine: normalized.engine,
     formulas: normalized.graph.formulas, dependencies: normalized.graph.dependencies, order: normalized.graph.order };
@@ -98,7 +111,8 @@ export function evaluateFormulaProgram(program, inputs = {}, expected = {}) {
     } else if (typeof value !== 'string') throw formulaError('ENGINE_INPUT_TYPE', `${key} must be text`);
   }
   for (const field of fields.values()) if (field.required && (!Object.hasOwn(inputs, field.key) || inputs[field.key] === '' || inputs[field.key] === null)) throw formulaError('MISSING_INPUT', `missing input: ${field.key}`, { fieldId: field.key });
-  return evaluateFormulaGraph(verified.formulas, Object.fromEntries(Object.entries(inputs).filter(([key]) => NUMERIC.includes(fields.get(key).type))));
+  return evaluateFormulaGraph(verified.formulas, Object.fromEntries(Object.entries(inputs).filter(([key]) => NUMERIC.includes(fields.get(key).type))),
+    { roundingPolicy: verified.roundingPolicy });
 }
 export function formulaImpact(program, changedKeys) {
   const verified = verifyFormulaProgram(program);

package/local-formula.mjs

@@ -6,7 +6,7 @@ import { formulaDigest } from './local-formula-engine.mjs';
 import { formulaFinalGate } from './local-formula-tests.mjs';
 
 export { Decimal, Decimal28, DECIMAL_POLICY } from './local-decimal.mjs';
-export { evaluateFormula, evaluateFormulaGraph, compileFormulaGraph, FORMULA_OPERATORS } from './local-formula-ast.mjs';
+export { evaluateFormula, evaluateFormulaGraph, compileFormulaGraph, FORMULA_OPERATORS, FORMULA_ROUNDING_POLICY } from './local-formula-ast.mjs';
 export { FORMULA_SCHEMA, FORMULA_RUNTIME_VERSION, compileFormulaEngine, verifyFormulaProgram,
   evaluateFormulaProgram, buildFormulaEngine, validateFormulaEngine, formulaImpact } from './local-formula-engine.mjs';
 export { FORMULA_GATE_SCHEMA, formulaFinalGate, verifyFormulaTests } from './local-formula-tests.mjs';