@entrorove/skill 0.1.22 → 0.1.24

package/workflow-local-contracts.mjs

@@ -0,0 +1,58 @@
+import { array, enumeration, integer, ledgerIdentifier, object, relativePath, sha256 } from './local-contract-types.mjs';
+
+const exact = properties => object(properties, Object.keys(properties));
+const boundedArray = (items, minimum, maximum) => ({ ...array(items, minimum), maxItems: maximum });
+const id = ledgerIdentifier;
+const absolutePath = { type: 'string', minLength: 2, maxLength: 4096, pattern: '^/[^\\u0000-\\u001f\\u007f]+$' };
+const timestamp = { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$' };
+const uuid = { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' };
+const shortText = { type: 'string', minLength: 1, maxLength: 4096, pattern: '\\S' };
+const authorityReceipt = exact({ schemaVersion: { const: 'entrorove.workflow-authority-receipt/1.0' },
+  keyId: sha256, payloadDigest: sha256, signature: { type: 'string', pattern: '^[A-Za-z0-9_-]{86}$' } });
+const manifestFile = exact({ path: { ...relativePath, maxLength: 500 }, sha256 });
+const testEntry = exact({ testId: id, path: { ...relativePath, maxLength: 500 } });
+const executionPolicy = exact({ executable: absolutePath, executableSha256: sha256,
+  args: boundedArray({ type: 'string', maxLength: 4096, pattern: '^[^\\u0000]*$' }, 0, 128),
+  environment: { type: 'object', maxProperties: 64, propertyNames: { pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+    additionalProperties: { type: 'string', maxLength: 16_384, pattern: '^[^\\u0000]*$' } },
+  timeoutMs: integer(1, 300_000), maxOutputBytes: integer(1, 1024 * 1024), requiredExitCode: { const: 0 },
+});
+const baseline = exact({ schemaVersion: { const: 'validator.golden-baseline/1.0' }, baselineId: id,
+  source: exact({ kind: enumeration(['repository-commit', 'artifact', 'approved-record']), locator: shortText, digestSha256: sha256 }),
+  version: id, frozen: { const: true }, frozenAt: timestamp, frozenBy: id, testsSha256: sha256,
+});
+const brainFields = ['planSha256', 'reportSha256', 'checksSha256', 'scopeContractSha256', 'snapshotSha256', 'adapterSha256'];
+const contracts = object({
+  brain: exact({ schemaVersion: { const: 'brain.frozen-runner/1.0' }, planId: uuid, reportId: uuid,
+    ...Object.fromEntries(brainFields.map(field => [field, sha256])) }),
+  aimlock: exact({ goalId: id, scopeContractSha256: sha256, snapshotSha256: sha256 }),
+  blueprint: exact({ blueprintId: id, acceptanceReportSha256: sha256 }),
+  archguard: exact({ contractSha256: sha256, ledgerSha256: sha256, driftStatus: enumeration(['green', 'yellow', 'red']) }),
+});
+contracts.anyOf = [{ required: ['aimlock'] }, { required: ['brain'] }];
+export const WORKFLOW_EXECUTION_PLAN_SCHEMA = exact({ schemaVersion: { const: 'validator.execution-plan/1.0' }, frozen: { const: true },
+  planId: id, validationRunId: id, memberId: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$' },
+  chainId: { type: 'string', pattern: '^chn-[0-9a-f-]{36}$' }, artifactSha256: sha256,
+  files: boundedArray(manifestFile, 1, 512), tests: boundedArray(testEntry, 1, 512), policy: executionPolicy,
+  goldenBaseline: baseline, contracts,
+});
+export const WORKFLOW_ACCEPTED_PLAN_SCHEMA = exact({ schemaVersion: { const: 'entrorove.workflow-local-plan/1.0' },
+  planId: id, flowId: id, ownerId: id, taskDigest: sha256, chainDigest: sha256, chainRevision: integer(1),
+  acceptedAt: timestamp, expiresAt: timestamp, runnerKeyId: sha256,
+  steps: boundedArray(exact({ stepId: id, sequence: integer(1, 128),
+    dependsOn: { ...boundedArray(id, 0, 128), uniqueItems: true }, executionPlan: WORKFLOW_EXECUTION_PLAN_SCHEMA,
+    executionPlanSha256: sha256 }), 1, 128), authorityReceipt,
+});
+WORKFLOW_ACCEPTED_PLAN_SCHEMA.properties.blueprintBinding = exact({
+  schemaVersion: { const: 'entrorove.blueprint-plan-binding/1.0' }, blueprintId: id, revision: integer(0),
+  blueprintSha256: { type: 'string', pattern: '^sha256:[0-9a-f]{64}$' }, machineTasksDigest: sha256,
+});
+export const WORKFLOW_LOCAL_LEASE_SCHEMA = exact({ schemaVersion: { const: 'entrorove.workflow-local-lease/1.0' },
+  leaseId: id, planId: id, planDigest: sha256, flowId: id, ownerId: id, taskDigest: sha256, chainDigest: sha256,
+  chainRevision: integer(1), stepId: id, sequence: integer(1, 128), generation: integer(1), issuedAt: timestamp, expiresAt: timestamp,
+  verifiedDependencies: { ...boundedArray(exact({ stepId: id, evidenceDigest: sha256 }), 0, 128), uniqueItems: true }, authorityReceipt,
+});
+export const WORKFLOW_LOCAL_OPERATION_SCHEMA = object({ repositoryRoot: absolutePath, home: absolutePath,
+  acceptedPlan: WORKFLOW_ACCEPTED_PLAN_SCHEMA, lease: WORKFLOW_LOCAL_LEASE_SCHEMA, stepId: id,
+  approvalPath: absolutePath, signerConfigPath: absolutePath,
+}, ['repositoryRoot', 'acceptedPlan', 'lease', 'stepId', 'approvalPath', 'signerConfigPath']);

package/workflow-local-request.mjs

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { withStateLock } from './local-state-lock.mjs';
+import { buildInvocation } from './remote-client.mjs';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { context, regular, atomic } from './local-task-handoff-storage.mjs';
+
+function original(output, requestId) {
+  if (!output || output.requestId !== requestId || output.schemaVersion !== 'entrorove.skill.response/1.0'
+    || output.status !== 'reported' || output.engineeringAuthorization !== 'cloud-required') {
+    throw new Error(`Original execution authority is unavailable; reconcile requestId=${requestId} without a new attempt`);
+  }
+  return output;
+}
+export async function managedExecutionAuthority(input, task, client) {
+  const ctx = await context({ ...input, flowId: task.flowId }, true);
+  const identity = { taskId: task.taskId, flowId: task.flowId, ownerId: task.ownerId,
+    leaseId: input.lease.leaseId, generation: input.lease.generation, leaseDigest: sha256(canonical(input.lease)) };
+  const file = path.join(path.dirname(ctx.file), `workflow-request-${sha256(canonical(identity))}.json`);
+  return withStateLock(file, async () => {
+    let record;
+    try {
+      const { bytes, stat } = await regular(file);
+      if (stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600
+        || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) throw new Error('Original workflow request must be an owned private file');
+      record = JSON.parse(bytes.toString('utf8'));
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (record) {
+      if (record.schemaVersion !== 'entrorove.workflow-local-request/1.0' || canonical(record.identity) !== canonical(identity)
+        || typeof record.attempt?.attemptNonce !== 'string' || Object.keys(record).sort().join('|') !== 'attempt|identity|requestId|schemaVersion') {
+        throw new Error('Original workflow request binding is invalid; do not create a replacement execution nonce');
+      }
+      const { requestId } = buildInvocation('handoff-execution-authority', record.attempt);
+      const { attemptNonce: _nonce, ...binding } = record.attempt;
+      if (requestId !== record.requestId || canonical(binding)
+        !== canonical({ taskId: task.taskId, flowId: task.flowId, leaseId: identity.leaseId, generation: identity.generation })) {
+        throw new Error('Original execution request lost its frozen task, lease or generation');
+      }
+      return { attempt: record.attempt, output: original(await client.status(record.requestId), record.requestId) };
+    }
+    const attempt = { taskId: task.taskId, flowId: task.flowId, leaseId: identity.leaseId,
+      generation: identity.generation, attemptNonce: randomUUID() };
+    const { requestId } = buildInvocation('handoff-execution-authority', attempt);
+    await atomic(file, { schemaVersion: 'entrorove.workflow-local-request/1.0', identity, attempt, requestId });
+    let output;
+    try { output = await client.invoke('handoff-execution-authority', attempt); }
+    catch (error) {
+      if (!error?.outcomeUnknown || error.requestId !== requestId) throw error;
+      output = await client.status(requestId);
+    }
+    return { attempt, output: original(output, requestId) };
+  });
+}

package/workflow-local-runner.mjs

@@ -0,0 +1,350 @@
+import { createHash, createPrivateKey, createPublicKey, randomUUID, sign, verify } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import * as approvedRunner from './local-approved-plan.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { assertBudgetRunnerAllowed } from './local-budget-reads.mjs';
+import { beginTaskHandoffExecution, finishTaskHandoffExecution, readTaskHandoffFence, withTaskHandoffReadFence } from './local-task-handoff-fence.mjs';
+import { WORKFLOW_LOCAL_OPERATION_SCHEMA } from './workflow-local-contracts.mjs';
+
+export const WORKFLOW_LOCAL_PLAN_SCHEMA = 'entrorove.workflow-local-plan/1.0';
+export const WORKFLOW_LOCAL_LEASE_SCHEMA = 'entrorove.workflow-local-lease/1.0';
+export const WORKFLOW_LOCAL_RESULT_SCHEMA = 'entrorove.workflow-local-result/1.0';
+const STATE_SCHEMA = 'entrorove.workflow-local-state/1.0';
+const AUTHORITY_SCHEMA = 'entrorove.workflow-authority-receipt/1.0';
+const BINDING_SCHEMA = 'entrorove.workflow-local-binding/1.0';
+const SHA = /^[0-9a-f]{64}$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const MAX_CONTROL_BYTES = 1024 * 1024;
+const MAX_STATE_BYTES = 8 * 1024 * 1024;
+const MAX_PLAN_MS = 86_400_000;
+const MAX_LEASE_MS = 600_000;
+
+function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
+function sha(value) { return createHash('sha256').update(value).digest('hex'); }
+function canonical(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (!value || typeof value !== 'object' || ![null, Object.prototype].includes(Object.getPrototypeOf(value))) fail('ENTROROVE_WORKFLOW_JSON', 'workflow values must be finite JSON');
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+}
+function exact(value, fields, code, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join('|') !== [...fields].sort().join('|')) fail(code, `${label} has invalid fields`);
+  return value;
+}
+function safeId(value, label) { if (typeof value !== 'string' || !ID.test(value)) fail('ENTROROVE_WORKFLOW_BINDING', `${label} must be a safe identifier`); return value; }
+function unsigned(value) { return Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'authorityReceipt')); }
+function positive(value) { return Number.isSafeInteger(value) && value > 0; }
+function publicKey(encoded, code) {
+  try {
+    if (typeof encoded !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) fail(code, 'configured public key is invalid');
+    const bytes = Buffer.from(encoded, 'base64'); const key = createPublicKey({ key: bytes, format: 'der', type: 'spki' });
+    if (key.asymmetricKeyType !== 'ed25519' || key.export({ format: 'der', type: 'spki' }).toString('base64') !== encoded) fail(code, 'configured public key must be canonical Ed25519 SPKI');
+    return { key, keyId: sha(bytes), encoded };
+  } catch { fail(code, 'configured public key must be canonical Ed25519 SPKI'); }
+}
+function verifyAuthority(value, configured) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('ENTROROVE_WORKFLOW_AUTHORITY', 'signed workflow authority must be an object');
+  const payload = unsigned(value); const receipt = exact(value.authorityReceipt,
+    ['schemaVersion', 'keyId', 'payloadDigest', 'signature'], 'ENTROROVE_WORKFLOW_AUTHORITY', 'authority receipt');
+  const bytes = Buffer.from(canonical(payload));
+  const signature = typeof receipt.signature === 'string' ? Buffer.from(receipt.signature, 'base64url') : Buffer.alloc(0);
+  if (bytes.length > MAX_CONTROL_BYTES || receipt.schemaVersion !== AUTHORITY_SCHEMA || receipt.keyId !== configured.keyId
+    || receipt.payloadDigest !== sha(bytes) || typeof receipt.signature !== 'string' || !/^[A-Za-z0-9_-]{86}$/.test(receipt.signature)
+    || signature.length !== 64 || signature.toString('base64url') !== receipt.signature
+    || !verify(null, bytes, configured.key, signature)) fail('ENTROROVE_WORKFLOW_AUTHORITY', 'workflow authority signature or payload binding is invalid');
+  return payload;
+}
+function lifetime(start, end, max, now, permitExpired = false) {
+  const issued = Date.parse(start); const expires = Date.parse(end);
+  if (typeof start !== 'string' || typeof end !== 'string' || !Number.isFinite(issued) || !Number.isFinite(expires)
+    || issued > now || expires <= issued || expires - issued > max || (!permitExpired && expires <= now)) fail('ENTROROVE_WORKFLOW_EXPIRED', 'workflow authority is expired or has invalid issuance');
+}
+function validatePlan(plan) {
+  exact(plan, ['schemaVersion', 'planId', 'flowId', 'ownerId', 'taskDigest', 'chainDigest', 'chainRevision', 'acceptedAt', 'expiresAt', 'runnerKeyId', 'steps',
+    ...(plan.blueprintBinding ? ['blueprintBinding'] : [])], 'ENTROROVE_WORKFLOW_PLAN_FIELDS', 'accepted plan');
+  if (plan.blueprintBinding) {
+    const binding = exact(plan.blueprintBinding, ['schemaVersion', 'blueprintId', 'revision', 'blueprintSha256', 'machineTasksDigest'],
+      'ENTROROVE_WORKFLOW_BLUEPRINT_BINDING', 'Blueprint binding');
+    safeId(binding.blueprintId, 'blueprintId');
+    if (binding.schemaVersion !== 'entrorove.blueprint-plan-binding/1.0' || !Number.isSafeInteger(binding.revision) || binding.revision < 0
+      || !/^sha256:[0-9a-f]{64}$/.test(binding.blueprintSha256) || !SHA.test(binding.machineTasksDigest)) {
+      fail('ENTROROVE_WORKFLOW_BLUEPRINT_BINDING', 'Blueprint plan binding is invalid');
+    }
+  }
+  if (plan.schemaVersion !== WORKFLOW_LOCAL_PLAN_SCHEMA || !SHA.test(plan.taskDigest) || !SHA.test(plan.chainDigest)
+    || !SHA.test(plan.runnerKeyId) || !positive(plan.chainRevision) || !Array.isArray(plan.steps) || !plan.steps.length || plan.steps.length > 128) fail('ENTROROVE_WORKFLOW_PLAN_FIELDS', 'accepted plan contract is invalid');
+  for (const field of ['planId', 'flowId', 'ownerId']) safeId(plan[field], field);
+  const seen = new Set();
+  for (const [index, step] of plan.steps.entries()) {
+    exact(step, ['stepId', 'sequence', 'dependsOn', 'executionPlan', 'executionPlanSha256'], 'ENTROROVE_WORKFLOW_PLAN_STEPS', 'accepted step');
+    safeId(step.stepId, 'stepId');
+    if (step.sequence !== index + 1 || seen.has(step.stepId) || !Array.isArray(step.dependsOn) || new Set(step.dependsOn).size !== step.dependsOn.length
+      || step.dependsOn.some(id => !seen.has(id))) fail('ENTROROVE_WORKFLOW_PLAN_STEPS', 'accepted steps must have unique ordered identities and earlier dependencies');
+    if (!SHA.test(step.executionPlanSha256) || sha(canonical(step.executionPlan) + '\n') !== step.executionPlanSha256) fail('ENTROROVE_WORKFLOW_PLAN_HASH', 'frozen execution plan SHA-256 does not match its bytes');
+    if (step.executionPlan?.schemaVersion !== 'validator.execution-plan/1.0' || step.executionPlan.frozen !== true
+      || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/.test(step.executionPlan.memberId) || !/^chn-[0-9a-f-]{36}$/.test(step.executionPlan.chainId)) fail('ENTROROVE_WORKFLOW_PLAN_FIELDS', 'execution plan must have compatible Validator member and chain identifiers');
+    seen.add(step.stepId);
+  }
+  return plan;
+}
+function validateLease(lease, plan, stepId) {
+  exact(lease, ['schemaVersion', 'leaseId', 'planId', 'planDigest', 'flowId', 'ownerId', 'taskDigest', 'chainDigest', 'chainRevision',
+    'stepId', 'sequence', 'generation', 'issuedAt', 'expiresAt', 'verifiedDependencies'], 'ENTROROVE_WORKFLOW_BINDING', 'local lease');
+  safeId(lease.leaseId, 'leaseId'); safeId(stepId, 'stepId');
+  const step = plan.steps.find(item => item.stepId === stepId);
+  if (!step || lease.schemaVersion !== WORKFLOW_LOCAL_LEASE_SCHEMA || lease.stepId !== stepId || lease.sequence !== step.sequence
+    || lease.planDigest !== sha(canonical(plan)) || !positive(lease.generation)
+    || ['planId', 'flowId', 'ownerId', 'taskDigest', 'chainDigest', 'chainRevision'].some(key => lease[key] !== plan[key])) fail('ENTROROVE_WORKFLOW_BINDING', 'lease does not match the exact original plan, task, chain, owner and step');
+  if (!Array.isArray(lease.verifiedDependencies) || lease.verifiedDependencies.length !== step.dependsOn.length) fail('ENTROROVE_WORKFLOW_DEPENDENCY', 'cloud verified dependency receipts are required');
+  const dependencies = lease.verifiedDependencies.map(item => {
+    exact(item, ['stepId', 'evidenceDigest'], 'ENTROROVE_WORKFLOW_DEPENDENCY', 'verified dependency');
+    if (!step.dependsOn.includes(item.stepId) || !SHA.test(item.evidenceDigest)) fail('ENTROROVE_WORKFLOW_DEPENDENCY', 'cloud verified dependency proof does not match the accepted step');
+    return item.stepId;
+  });
+  if (new Set(dependencies).size !== dependencies.length) fail('ENTROROVE_WORKFLOW_DEPENDENCY', 'cloud verified dependencies must be unique');
+  return step;
+}
+async function realDirectory(value, code) {
+  if (typeof value !== 'string' || !path.isAbsolute(value)) fail(code, 'directory must be absolute');
+  const stat = await fs.lstat(value);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail(code, 'directory must be a real directory');
+  return fs.realpath(value);
+}
+async function privateHierarchy(home, parts, create = true) {
+  let directory = home;
+  for (const part of parts) {
+    directory = path.join(directory, part);
+    if (create) await fs.mkdir(directory, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+    let stat;
+    try { stat = await fs.lstat(directory); } catch (error) {
+      if (!create && error.code === 'ENOENT') return path.join(home, ...parts);
+      throw error;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'workflow state directory must be real and owned');
+    if (create) await fs.chmod(directory, 0o700);
+    else if ((stat.mode & 0o777) !== 0o700) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'existing workflow state directory must be private');
+  }
+  return directory;
+}
+async function external(root, file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file)) fail('ENTROROVE_WORKFLOW_SIGNER', 'signer control path must be absolute');
+  const stat = await fs.lstat(file); const real = await fs.realpath(file); const relative = path.relative(root, real);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_CONTROL_BYTES || stat.nlink !== 1
+    || (typeof process.getuid === 'function' && stat.uid !== process.getuid()) || (stat.mode & 0o777) !== 0o600
+    || relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`))) fail('ENTROROVE_WORKFLOW_SIGNER', 'signer controls must be external owned regular 0600 files');
+  return { path: real, bytes: await fs.readFile(real) };
+}
+async function loadSigner(root, signerConfigPath, runnerKeyId) {
+  const file = await external(root, signerConfigPath); let config;
+  try { config = JSON.parse(file.bytes.toString('utf8')); } catch { fail('ENTROROVE_WORKFLOW_SIGNER', 'signer configuration JSON is invalid'); }
+  exact(config, ['schemaVersion', 'privateKeyPath', 'keyId', 'receiptTtlMs'], 'ENTROROVE_WORKFLOW_SIGNER', 'runner signer');
+  if (config.schemaVersion !== 'validator.runner-signer/1.0' || config.keyId !== runnerKeyId
+    || !positive(config.receiptTtlMs) || config.receiptTtlMs > MAX_LEASE_MS) fail('ENTROROVE_WORKFLOW_SIGNER', 'runner signer does not match the accepted runner key');
+  const secret = await external(root, config.privateKeyPath);
+  try {
+    const privateKey = createPrivateKey(secret.bytes); const der = createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
+    if (privateKey.asymmetricKeyType !== 'ed25519' || sha(der) !== runnerKeyId) fail('ENTROROVE_WORKFLOW_SIGNER', 'runner private key fingerprint does not match the accepted plan');
+    return { privateKey, publicKey: der.toString('base64'), config };
+  } catch (error) { if (error.code === 'ENTROROVE_WORKFLOW_SIGNER') throw error; fail('ENTROROVE_WORKFLOW_SIGNER', 'runner private key is invalid'); }
+  finally { secret.bytes.fill(0); }
+}
+function identity(authority) {
+  return { repositoryDigest: sha(authority.root).slice(0, 32), planId: authority.plan.planId, planDigest: authority.lease.planDigest,
+    flowId: authority.plan.flowId, ownerId: authority.plan.ownerId, stepId: authority.step.stepId,
+    sequence: authority.step.sequence, leaseId: authority.lease.leaseId, generation: authority.lease.generation,
+    leaseDigest: sha(canonical(authority.lease)) };
+}
+function binding(authority, processResult) {
+  const { plan, lease, step } = authority;
+  return { schemaVersion: BINDING_SCHEMA, planId: plan.planId, planDigest: lease.planDigest, flowId: plan.flowId, ownerId: plan.ownerId,
+    taskDigest: plan.taskDigest, chainDigest: plan.chainDigest, chainRevision: plan.chainRevision, stepId: step.stepId, sequence: step.sequence,
+    executionPlanSha256: step.executionPlanSha256, leaseId: lease.leaseId, leaseDigest: sha(canonical(lease)), generation: lease.generation,
+    verifiedDependencies: lease.verifiedDependencies, processResultSha256: sha(canonical(processResult)),
+    executionAuthorityDigest: sha(canonical(authority.executionAuthority)),
+    executionAttemptNonce: authority.executionAuthority.attemptNonce, executionStartedAt: processResult.startedAt };
+}
+function executionAuthority(value, authority) {
+  const configured = publicKey(process.env.ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY?.trim(), 'ENTROROVE_WORKFLOW_AUTHORITY_KEY');
+  const payload = verifyAuthority(value, configured);
+  exact(payload, ['schemaVersion', 'authorityId', 'attemptNonce', 'taskId', 'flowId', 'ownerId', 'taskDigest', 'chainDigest',
+    'leaseId', 'generation', 'epoch', 'status', 'runnerKeyId', 'localRepositoryDigest', 'issuedAt', 'expiresAt'],
+  'ENTROROVE_WORKFLOW_AUTHORITY', 'execution authority');
+  for (const field of ['authorityId', 'attemptNonce', 'taskId']) safeId(payload[field], field);
+  const { plan, lease } = authority;
+  if (payload.schemaVersion !== 'entrorove.task-execution-epoch-authority/1.0' || payload.status !== 'active'
+    || !Number.isSafeInteger(payload.epoch) || payload.epoch < 0 || payload.localRepositoryDigest !== sha(authority.root).slice(0, 32)
+    || ['flowId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId'].some(key => payload[key] !== plan[key])
+    || payload.leaseId !== lease.leaseId || payload.generation !== lease.generation) {
+    fail('ENTROROVE_WORKFLOW_AUTHORITY', 'execution authority does not match the original signed plan and lease');
+  }
+  lifetime(payload.issuedAt, payload.expiresAt, 30_000, Date.now(), true);
+  return value;
+}
+async function readState(file) {
+  try {
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > MAX_STATE_BYTES || (stat.mode & 0o777) !== 0o600
+      || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'workflow state must be an owned regular 0600 file');
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (error) { if (error.code === 'ENOENT') return null; if (error.code === 'ENTROROVE_WORKFLOW_STATE_INVALID') throw error; fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'workflow state is unreadable or invalid'); }
+}
+async function writeState(file, state) {
+  const bytes = canonical(state) + '\n'; if (Buffer.byteLength(bytes) > MAX_STATE_BYTES) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'workflow state exceeds its bounded storage limit');
+  const temporary = `${file}.${randomUUID()}.tmp`; const handle = await fs.open(temporary, 'wx', 0o600);
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+  await fs.rename(temporary, file); const directory = await fs.open(path.dirname(file), 'r');
+  try { await directory.sync(); } finally { await directory.close(); }
+}
+function checkState(state, authority) {
+  exact(state, ['schemaVersion', ...Object.keys(identity(authority)), 'executionAuthority', 'status', 'pid', 'startedAt', 'finishedAt', 'result', 'resultDigest'],
+    'ENTROROVE_WORKFLOW_STATE_INVALID', 'workflow state');
+  if (state.schemaVersion !== STATE_SCHEMA || !['running', 'reported', 'failed'].includes(state.status)
+    || Object.entries(identity(authority)).some(([key, value]) => state[key] !== value)) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'workflow state does not match this original lease');
+  if (state.executionAuthority !== null) authority.executionAuthority = executionAuthority(state.executionAuthority, authority);
+  if (state.status === 'running') return;
+  if (!authority.executionAuthority) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'completed workflow has no original fresh cloud execution authority');
+  const result = state.result;
+  if (!result || result.status !== state.status || state.resultDigest !== sha(canonical(result)) || result.cached !== false
+    || result.statePath !== authority.file || !Array.isArray(result.evidence)) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'completed workflow result digest is invalid');
+  if (result.evidence.length === 0 && result.status === 'failed' && result.error && result.receipt === null) return;
+  const item = result.evidence[0]; const receipt = result.receipt; const key = publicKey(result.receiptPublicKey, 'ENTROROVE_WORKFLOW_STATE_INVALID');
+  if (result.evidence.length !== 1 || key.keyId !== authority.plan.runnerKeyId || receipt?.keyId !== key.keyId
+    || !result.subject?.policy || !result.process || receipt.schemaVersion !== 'validator.execution-receipt/1.0'
+    || item?.subjectDigest !== sha(canonical(result.subject)) || receipt.subjectDigest !== item.subjectDigest
+    || canonical(item.subject) !== canonical(result.subject) || canonical(item.receipt) !== canonical(receipt)
+    || item.command !== result.subject.policy.command || item.artifactSha256 !== result.subject.artifactSha256
+    || item.exitCode !== result.process.exitCode || receipt.result?.exitCode !== item.exitCode
+    || receipt.result.durationMs !== item.durationMs || receipt.result.summary !== item.summary
+    || receipt.result.runner !== 'trusted-runner' || item.runner !== 'trusted-runner'
+    || receipt.result.passed !== (result.status === 'reported') || (result.process.status === 'succeeded') !== (result.status === 'reported')
+    || canonical(result.subject.policy.workflowBinding) !== canonical(binding(authority, result.process))) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'completed workflow evidence binding is invalid');
+  const { signature, ...core } = receipt;
+  const bytes = typeof signature === 'string' ? Buffer.from(signature, 'base64url') : Buffer.alloc(0);
+  if (typeof signature !== 'string' || !/^[A-Za-z0-9_-]{86}$/.test(signature)
+    || bytes.length !== 64 || bytes.toString('base64url') !== signature
+    || !verify(null, Buffer.from(canonical(core)), key.key, bytes)) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'completed workflow evidence signature is invalid');
+}
+function live(pid) { if (!positive(pid)) return false; try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; } }
+async function claim(authority, authorizeMutation, checkBudget) {
+  return withStateLock(authority.file, async () => {
+    const state = await readState(authority.file);
+    if (state) {
+      checkState(state, authority);
+      if (state.status !== 'running') return { ...structuredClone(state.result), cached: true };
+      await checkBudget();
+      fail(live(state.pid) ? 'ENTROROVE_WORKFLOW_BUSY' : 'ENTROROVE_WORKFLOW_RECOVERY_REQUIRED', live(state.pid)
+        ? 'workflow local step is still running' : 'workflow local outcome is unknown; cloud reconciliation is required before any new execution');
+    }
+    await checkBudget(); await authorizeMutation();
+    const now = Date.now(); lifetime(authority.plan.acceptedAt, authority.plan.expiresAt, MAX_PLAN_MS, now);
+    lifetime(authority.lease.issuedAt, authority.lease.expiresAt, MAX_LEASE_MS, now);
+    await writeState(authority.file, { schemaVersion: STATE_SCHEMA, ...identity(authority), executionAuthority: null, status: 'running', pid: process.pid,
+      startedAt: new Date(now).toISOString(), finishedAt: null, result: null, resultDigest: null });
+    return null;
+  });
+}
+function signedResult(authority, execution, signer) {
+  if (!Number.isInteger(execution.process.exitCode)) return { schemaVersion: WORKFLOW_LOCAL_RESULT_SCHEMA, status: 'failed',
+    cached: false, statePath: authority.file, process: execution.process, evidence: [], receipt: null,
+    error: { code: 'ENTROROVE_WORKFLOW_PROCESS_INTERRUPTED', message: 'actual process ended without a completed integer exit code' } };
+  const { execution: _execution, ...originalSubject } = execution.subject;
+  const subject = { ...originalSubject, executedAt: execution.process.finishedAt, policy: { ...originalSubject.policy, workflowBinding: binding(authority, execution.process) } };
+  const original = execution.evidence[0]; const { receipt: _receipt, subject: _subject, subjectDigest: _digest, ...base } = original;
+  const evidence = { ...base, subject, subjectDigest: sha(canonical(subject)), runner: 'trusted-runner' };
+  const issuedAtMs = Date.now(), issuedAt = new Date(issuedAtMs).toISOString();
+  const core = { schemaVersion: 'validator.execution-receipt/1.0', keyId: signer.config.keyId, subjectDigest: evidence.subjectDigest,
+    nonce: randomUUID(), issuedAt, expiresAt: new Date(issuedAtMs + signer.config.receiptTtlMs).toISOString(),
+    result: { runner: 'trusted-runner', passed: execution.process.status === 'succeeded', exitCode: evidence.exitCode,
+      durationMs: evidence.durationMs, summary: evidence.summary } };
+  const receipt = { ...core, signature: sign(null, Buffer.from(canonical(core)), signer.privateKey).toString('base64url') };
+  return { schemaVersion: WORKFLOW_LOCAL_RESULT_SCHEMA, status: execution.process.status === 'succeeded' ? 'reported' : 'failed',
+    cached: false, statePath: authority.file, subject, process: execution.process, evidence: [{ ...evidence, receipt }], receipt,
+    receiptPublicKey: signer.publicKey, approvalSha256: execution.approvalSha256, approvedBy: execution.approvedBy };
+}
+async function finalize(authority, result) {
+  return withStateLock(authority.file, async () => {
+    const state = await readState(authority.file); if (!state) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'running state disappeared');
+    checkState(state, authority);
+    if (state.status !== 'running' || state.pid !== process.pid) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'running state ownership changed');
+    await writeState(authority.file, { ...state, status: result.status, finishedAt: new Date().toISOString(), result, resultDigest: sha(canonical(result)) });
+    return result;
+  });
+}
+async function prepare(input, create = true) {
+  const fields = ['repositoryRoot', 'acceptedPlan', 'lease', 'stepId', 'approvalPath', 'signerConfigPath',
+    ...(input?.executionAttemptNonce === undefined ? [] : ['executionAttemptNonce'])];
+  exact(input, input?.home === undefined ? fields : [...fields, 'home'], 'ENTROROVE_WORKFLOW_PLAN_FIELDS', 'workflow runner input');
+  if (input.executionAttemptNonce !== undefined) safeId(input.executionAttemptNonce, 'executionAttemptNonce');
+  if (process.platform === 'win32' || typeof process.getuid !== 'function') fail('ENTROROVE_POSIX_REQUIRED', 'workflow local runner requires POSIX');
+  const configured = publicKey(process.env.ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY?.trim(), 'ENTROROVE_WORKFLOW_AUTHORITY_KEY');
+  const plan = validatePlan(verifyAuthority(input.acceptedPlan, configured)); const lease = verifyAuthority(input.lease, configured);
+  const step = validateLease(lease, plan, input.stepId);
+  lifetime(plan.acceptedAt, plan.expiresAt, MAX_PLAN_MS, Date.now(), true); lifetime(lease.issuedAt, lease.expiresAt, MAX_LEASE_MS, Date.now(), true);
+  const root = await realDirectory(input.repositoryRoot, 'ENTROROVE_ROOT_INVALID');
+  const home = await realDirectory(input.home ?? os.homedir(), 'ENTROROVE_HOME_INVALID');
+  const directory = await privateHierarchy(home, ['.entrorove', 'workflow-local', sha(root).slice(0, 32), plan.flowId, step.stepId], create);
+  return { root, plan, lease, step, file: path.join(directory, 'state.json') };
+}
+
+export async function observeWorkflowLocalStep(rawInput) {
+  const authority = await prepare(structuredClone(rawInput), false);
+  const checkBudget = () => assertBudgetRunnerAllowed({ repositoryRoot: authority.root, home: rawInput.home, flowId: authority.plan.flowId });
+  if (!await readState(authority.file)) { await checkBudget(); return null; }
+  const original = { home: rawInput.home, repositoryRoot: authority.root, flowId: authority.plan.flowId };
+  const fence = { ...original, epoch: (await readTaskHandoffFence(original)).epoch, leaseId: authority.lease.leaseId };
+  return withTaskHandoffReadFence(fence, () => withStateLock(authority.file, async () => {
+    const state = await readState(authority.file); if (!state) { await checkBudget(); return null; }
+    checkState(state, authority);
+    if (state.status === 'running') { await checkBudget(); fail('ENTROROVE_WORKFLOW_RECOVERY_REQUIRED', 'original process outcome must be reconciled; a fresh nonce cannot restart its lease'); }
+    return { ...structuredClone(state.result), cached: true };
+  }));
+}
+export async function runWorkflowLocalStep(rawInput) {
+  let input; try { input = structuredClone(rawInput); } catch { fail('ENTROROVE_WORKFLOW_JSON', 'workflow values must be finite JSON'); }
+  const authority = await prepare(input);
+  const checkBudget = () => assertBudgetRunnerAllowed({ repositoryRoot: authority.root, home: input.home, flowId: authority.plan.flowId });
+  const original = { home: input.home, repositoryRoot: authority.root, flowId: authority.plan.flowId };
+  const fence = { ...original, epoch: (await readTaskHandoffFence(original)).epoch, leaseId: authority.lease.leaseId };
+  const cached = await withTaskHandoffReadFence(fence, (_state, { authorizeMutation }) => claim(authority, authorizeMutation, checkBudget));
+  if (cached) return cached;
+  let execution, activity;
+  try {
+    activity = await beginTaskHandoffExecution({ ...fence, stepId: authority.step.stepId, generation: authority.lease.generation,
+      attemptNonce: input.executionAttemptNonce, executionId: `run-${sha(canonical(authority.lease)).slice(0, 48)}` });
+    authority.executionAuthority = executionAuthority(activity.authority, authority);
+    await withStateLock(authority.file, async () => {
+      const state = await readState(authority.file); if (!state) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'running state disappeared before its authority binding');
+      checkState(state, authority);
+      if (state.status !== 'running' || state.pid !== process.pid || state.executionAuthority !== null) fail('ENTROROVE_WORKFLOW_STATE_INVALID', 'running authority ownership changed');
+      await writeState(authority.file, { ...state, executionAuthority: activity.authority });
+    });
+    const signer = await loadSigner(authority.root, input.signerConfigPath, authority.plan.runnerKeyId);
+    if (typeof approvedRunner.runApprovedPlanObject !== 'function') fail('ENTROROVE_WORKFLOW_RUNNER_UNAVAILABLE', 'approved object plan runner is unavailable');
+    execution = await approvedRunner.runApprovedPlanObject({ repositoryRoot: authority.root, executionPlan: authority.step.executionPlan,
+      approvalPath: input.approvalPath, signerConfigPath: input.signerConfigPath, executionDeadlineAt: authority.lease.expiresAt });
+    return await finalize(authority, signedResult(authority, execution, signer));
+  } catch (error) {
+    if (!error.execution && !execution) {
+      await withStateLock(authority.file, async () => {
+        const state = await readState(authority.file); if (state?.status === 'running' && state.pid === process.pid) { checkState(state, authority); await fs.unlink(authority.file); }
+      });
+      throw error;
+    }
+    return await finalize(authority, { schemaVersion: WORKFLOW_LOCAL_RESULT_SCHEMA, status: 'failed', cached: false, statePath: authority.file,
+      process: error.execution?.process ?? execution.process, evidence: [], receipt: null,
+      error: { code: error.code ?? 'ENTROROVE_WORKFLOW_EXECUTION_FAILED', message: error.message } });
+  } finally {
+    if (activity) await finishTaskHandoffExecution({ ...fence, ...activity });
+  }
+}
+
+export const WORKFLOW_LOCAL_CAPABILITIES = Object.freeze({ schemaVersion: 'entrorove.workflow-local-runner/1.0',
+  operations: ['workflow-run-step'], operationSchemas: { 'workflow-run-step': WORKFLOW_LOCAL_OPERATION_SCHEMA },
+  acceptedPlanSchema: WORKFLOW_LOCAL_PLAN_SCHEMA, leaseSchema: WORKFLOW_LOCAL_LEASE_SCHEMA,
+  authorityKeyEnvironment: 'ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY', stateDirectory: '~/.entrorove/workflow-local',
+  reportedIsVerified: false, limits: { maxSteps: 128, maxControlBytes: MAX_CONTROL_BYTES, maxStateBytes: MAX_STATE_BYTES,
+    maxPlanLifetimeMs: MAX_PLAN_MS, maxLeaseLifetimeMs: MAX_LEASE_MS },
+});