@entrorove/skill 0.1.23 → 0.1.25

package/local-mutation-batch-receipt.mjs

@@ -0,0 +1,84 @@
+import { createPublicKey, randomUUID, sign, verify } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { loadTaskHandoffSigner } from './local-task-handoff-observation.mjs';
+import { canonicalHandoffSignature } from './local-task-handoff-overlay-wire.mjs';
+import { mutationFail14, mutationPath14 } from './local-mutation-files.mjs';
+import { mutationLifetime14 } from './local-mutation-wire.mjs';
+
+const identity = ['flowId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'chainRevision', 'stepId', 'leaseId',
+  'generation', 'epoch', 'planId', 'planDigest', 'runnerId', 'runnerKeyId', 'repositoryId', 'repositoryDigest',
+  'scopeBindingDigest', 'scopeArtifactDigest', 'scopeContractDigest', 'paths'];
+function cloudContract(contract, pass) {
+  const rollback = contract?.schemaVersion === 'entrorove.merge-rollback-authorization/1.0';
+  try {
+    const encoded = process.env.ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY, der = Buffer.from(encoded ?? '', 'base64');
+    const key = createPublicKey({ key: der, type: 'spki', format: 'der' });
+    const { signature, ...payload } = contract;
+    if (key.asymmetricKeyType !== 'ed25519' || key.export({ type: 'spki', format: 'der' }).toString('base64') !== encoded
+      || (!rollback && contract.schemaVersion !== 'entrorove.merge-contract/1.0') || (rollback && contract.schemaVersion !== 'entrorove.merge-rollback-authorization/1.0')
+      || contract.keyId !== pass.authorityReceipt.keyId
+      || contract.keyId !== sha256(der) || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(contract.nonce)
+      || !verify(null, Buffer.from(canonical(payload)), key, canonicalHandoffSignature(signature))) throw new Error();
+  } catch { mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Batch merge contract requires its original pinned cloud signature'); }
+  mutationLifetime14(contract);
+  if (identity.some(field => canonical(contract[field] ?? null) !== canonical(pass[field] ?? null))
+    || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(contract.mergeId)) {
+    mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Batch merge contract differs from the original signed pass identity');
+  }
+}
+function contractImages(contract, pass, before, after) {
+  const rollback = contract?.schemaVersion === 'entrorove.merge-rollback-authorization/1.0';
+  if (rollback) {
+    if (!Array.isArray(contract.beforeFiles) || !Array.isArray(contract.restoreFiles)) mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Rollback authorization has no frozen current and restore images');
+    const priorRollback = contract.beforeFiles.filter(file => pass.paths.includes(file?.path));
+    const nextRollback = contract.restoreFiles.filter(file => pass.paths.includes(file?.path));
+    if (canonical(priorRollback) !== canonical(before) || canonical(nextRollback) !== canonical(after)) mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Rollback images differ from the original cloud-frozen restore images');
+    return;
+  }
+  if (!Array.isArray(contract.beforeFullManifest) || !Array.isArray(contract.sourceFiles)) {
+    mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Original merge contract has no frozen physical file images');
+  }
+  const prior = contract.beforeFullManifest.filter(file => pass.paths.includes(file?.path));
+  const next = contract.sourceFiles.filter(file => pass.paths.includes(file?.path)).map(file => ({
+    path: mutationPath14(file.path), exists: true, sha256: file.sha256, mode: file.mode }));
+  if (canonical(prior) !== canonical(before) || canonical(next) !== canonical(after)) {
+    mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Batch images differ from the original cloud-frozen merge images');
+  }
+}
+export async function mutationBatchReceiptBinding14(input, original, options, before, after) {
+  const pass = original.pass, contractDigest = pass.executionPlanSha256;
+  let transactionId = pass.passId, contractExpiresAt;
+  if (options.contract !== undefined) {
+    cloudContract(options.contract, pass);
+    if (sha256(canonical(options.contract)) !== contractDigest) {
+      mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Batch cannot replace the original pass-bound merge contract');
+    }
+    contractImages(options.contract, pass, before, after);
+    transactionId = options.contract.mergeId; contractExpiresAt = options.contract.expiresAt;
+  } else if (options.contractDigest !== undefined || options.transactionId !== undefined) {
+    mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Caller receipt bindings require the original cloud-signed merge contract');
+  }
+  if (options.contractDigest !== undefined && options.contractDigest !== contractDigest
+    || options.transactionId !== undefined && options.transactionId !== transactionId) {
+    mutationFail14('ENTROROVE_MUTATION_BATCH_CONTRACT', 'Caller cannot redefine the original batch contract or transaction');
+  }
+  const signer = await loadTaskHandoffSigner(original.binding.context,
+    input.runnerSignerConfigPath ?? input.signerConfigPath, pass.runnerKeyId);
+  return { signer, contractDigest, transactionId, contractExpiresAt };
+}
+export function signMutationBatchReceipt14(state, status, actual, failure = {}) {
+  const now = Date.now(), pass = state.pass;
+  const expires = status === 'written' ? Math.min(now + state.signer.config.receiptTtlMs,
+    Date.parse(pass.expiresAt), state.contractExpiresAt ? Date.parse(state.contractExpiresAt) : Infinity)
+    : now + state.signer.config.receiptTtlMs;
+  if (expires <= now) mutationFail14('ENTROROVE_MUTATION_AUTHORITY_EXPIRED', 'Original batch authority expired before its successful consumption proof');
+  const payload = { schemaVersion: 'entrorove.mutation-batch-consumption-receipt/1.0', status, consumed: true,
+    batchId: state.batchId, flowId: pass.flowId, taskId: pass.taskId, stepId: pass.stepId, leaseId: pass.leaseId,
+    generation: pass.generation, passDigest: state.passDigest, contractDigest: state.contractDigest,
+    transactionId: state.transactionId, executionAuthorityDigest: pass.executionAuthorityDigest,
+    executionAttemptNonce: pass.executionAttemptNonce, paths: [...pass.paths],
+    writes: actual.map(file => ({ path: file.path, status, contentDigest: file.sha256 })),
+    ...(status === 'written' ? { afterFiles: actual } : { currentFiles: actual, ...failure }),
+    keyId: pass.runnerKeyId, nonce: randomUUID(), issuedAt: new Date(now).toISOString(), expiresAt: new Date(expires).toISOString() };
+  return { ...payload, signature: sign(null, Buffer.from(canonical(payload)), state.signer.privateKey).toString('base64url') };
+}

package/local-mutation-batch.mjs

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { assertTaskHandoffSnapshotBinding } from './local-task-handoff-fence.mjs';
+import { mutationFail14, mutationPath14, mutationRead14, mutationTarget14 } from './local-mutation-files.mjs';
+import { mutationPass14, mutationLifetime14 } from './local-mutation-wire.mjs';
+import { mutationOriginalBinding14, mutationSnapshotBinding14 } from './local-mutation-binding.mjs';
+import { readStoredMutationPass14, mutationPassLocations14, readMutationConsumption14,
+  saveMutationConsumption14 } from './local-mutation-pass-store.mjs';
+import { auditMutation14, withMutationAudit14 } from './local-mutation-audit.mjs';
+import { mutationBatchReceiptBinding14, signMutationBatchReceipt14 } from './local-mutation-batch-receipt.mjs';
+
+const tokens = new WeakMap(), MISSING = sha256('entrorove.missing-file/1.0');
+function clone(value) {
+  try { return structuredClone(value); }
+  catch { mutationFail14('ENTROROVE_MUTATION_BATCH_INPUT', 'Batch authority must be finite original data'); }
+}
+function files(value, paths) {
+  if (!Array.isArray(value) || canonical(value.map(file => file?.path)) !== canonical(paths)
+    || value.some(file => !file || Object.keys(file).sort().join('|') !== 'exists|mode|path|sha256'
+      || mutationPath14(file.path) !== file.path || typeof file.exists !== 'boolean' || !/^[0-9a-f]{64}$/.test(file.sha256)
+      || (file.exists ? !Number.isInteger(file.mode) || file.mode < 0 || file.mode > 0o777 : file.mode !== null || file.sha256 !== MISSING))) {
+    mutationFail14('ENTROROVE_MUTATION_BATCH_FILES', 'Batch images require the exact original sorted pass paths and complete file facts');
+  }
+  return value;
+}
+function options(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(field => !['mutationPass', 'beforeFiles', 'afterFiles', 'contract', 'contractDigest', 'transactionId'].includes(field))) {
+    mutationFail14('ENTROROVE_MUTATION_BATCH_INPUT', 'Batch begin requires its original pass and exact before and after images');
+  }
+  return value;
+}
+function tokenState(token, permitted) {
+  const state = token && typeof token === 'object' ? tokens.get(token) : null;
+  if (!state) mutationFail14('ENTROROVE_MUTATION_BATCH_TOKEN', 'Only the internal token of this real original batch can complete consumption');
+  if (!permitted.includes(state.status)) mutationFail14('ENTROROVE_MUTATION_BATCH_CLOSED', 'Original batch has already completed or failed; consumed paths cannot be reused');
+  return state;
+}
+async function authority(input, supplied) {
+  const pass = await readStoredMutationPass14(input);
+  for (const value of [supplied, input.mutationPass]) if (value !== undefined && canonical(mutationPass14(value)) !== canonical(pass)) {
+    mutationFail14('ENTROROVE_MUTATION_PASS_CHANGED', 'Batch cannot replace its stored original signed pass');
+  }
+  const binding = await mutationOriginalBinding14(input, pass), snapshot = await mutationSnapshotBinding14(input, pass);
+  assertTaskHandoffSnapshotBinding(binding.state, pass.snapshotReceipt);
+  return { pass, binding, snapshot, locations: await mutationPassLocations14(input, binding, pass) };
+}
+function batchEntry(state, file, status = 'pending') {
+  return { status, contentDigest: file.sha256, at: state.at, batchId: state.batchId, batchDigest: state.batchDigest,
+    beforeDigest: state.beforeDigest, afterDigest: state.afterDigest };
+}
+async function originalLedger(state) {
+  const ledger = await readMutationConsumption14(state.pass, state.locations);
+  const status = state.status === 'completed' ? 'written' : 'pending';
+  if (state.after.some(file => canonical(ledger.writes[file.path]) !== canonical(batchEntry(state, file, status)))) {
+    mutationFail14('ENTROROVE_MUTATION_BATCH_CHANGED', 'Persistent pending paths differ from the original indivisible batch consumption');
+  }
+  return ledger;
+}
+async function image(input, root, expected) {
+  const actual = [];
+  for (const file of expected) {
+    const target = await mutationTarget14(root, file.path, true);
+    if (!target.exists) actual.push({ path: file.path, exists: false, sha256: MISSING, mode: null });
+    else { const read = await mutationRead14(input, root, file.path);
+      actual.push({ path: file.path, exists: true, sha256: read.sha256, mode: read.mode }); }
+  }
+  return actual;
+}
+// The native transaction retains its physical/fence locks. This module reserves
+// consumption only; no input can authorize skipping a signature or before image.
+export async function beginMutationBatch14(rawInput, rawOptions) {
+  const input = clone(rawInput);
+  return withMutationAudit14(input, 'mutation-batch-begin', async () => {
+    const value = options(clone(rawOptions)), original = await authority(input, value.mutationPass);
+    const before = files(value.beforeFiles, original.pass.paths), after = files(value.afterFiles, original.pass.paths);
+    const receiptBinding = await mutationBatchReceiptBinding14(input, original, value, before, after);
+    return withStateLock(original.locations.consumptionPath, async () => {
+      const fresh = await authority(input, value.mutationPass);
+      if (canonical(fresh.pass) !== canonical(original.pass)) mutationFail14('ENTROROVE_MUTATION_PASS_CHANGED', 'Batch pass changed while reserving original consumption');
+      const ledger = await readMutationConsumption14(fresh.pass, fresh.locations);
+      if (fresh.pass.paths.some(target => Object.hasOwn(ledger.writes, target))) {
+        mutationFail14('ENTROROVE_MUTATION_PASS_CONSUMED', 'Batch contains an already consumed or unresolved original path');
+      }
+      const snapshot = await mutationSnapshotBinding14(input, fresh.pass, { allSources: true });
+      if (canonical(before) !== canonical(snapshot.manifest.files)) mutationFail14('ENTROROVE_MUTATION_BATCH_BEFORE', 'Batch before image differs from the real original signed snapshot');
+      mutationLifetime14(fresh.pass);
+      const state = { ...fresh, ...receiptBinding, input, before, after, status: 'pending', batchId: randomUUID(), at: new Date().toISOString(),
+        passDigest: sha256(canonical(fresh.pass)), beforeDigest: sha256(canonical(before)), afterDigest: sha256(canonical(after)) };
+      state.batchDigest = sha256(canonical({ passDigest: state.passDigest, beforeDigest: state.beforeDigest,
+        afterDigest: state.afterDigest, batchId: state.batchId }));
+      const writes = { ...ledger.writes };
+      for (const file of after) writes[file.path] = batchEntry(state, file);
+      await saveMutationConsumption14(fresh.locations, { ...ledger, writes });
+      await auditMutation14(input, 'mutation-batch-pending', { passId: fresh.pass.passId, batchId: state.batchId,
+        beforeDigest: state.beforeDigest, afterDigest: state.afterDigest });
+      const token = Object.freeze({ schemaVersion: 'entrorove.mutation-batch-token/1.0', batchId: state.batchId });
+      tokens.set(token, state); return token;
+    });
+  });
+}
+export async function finishMutationBatch14(token) {
+  const state = tokenState(token, ['pending']);
+  return withMutationAudit14(state.input, 'mutation-batch-finish', () => withStateLock(state.locations.consumptionPath, async () => {
+    tokenState(token, ['pending']);
+    const fresh = await authority(state.input, state.pass);
+    if (fresh.binding.root !== state.binding.root || fresh.binding.home !== state.binding.home
+      || fresh.locations.anchor !== state.locations.anchor || fresh.locations.consumptionPath !== state.locations.consumptionPath) {
+      mutationFail14('ENTROROVE_MUTATION_BATCH_CONTEXT', 'Batch cannot move its original registered repository, home or trusted consumption anchor');
+    }
+    const ledger = await originalLedger(state), actual = await image(state.input, state.binding.root, state.after);
+    if (canonical(actual) !== canonical(state.after)) mutationFail14('ENTROROVE_MUTATION_BATCH_AFTER', 'Only the actual complete original after image can finish consumption');
+    mutationLifetime14(fresh.pass);
+    const writes = { ...ledger.writes };
+    for (const file of state.after) writes[file.path] = batchEntry(state, file, 'written');
+    await saveMutationConsumption14(state.locations, { ...ledger, writes });
+    state.status = 'completed';
+    await auditMutation14(state.input, 'mutation-batch-finished', { passId: state.pass.passId, batchId: state.batchId,
+      beforeDigest: state.beforeDigest, afterDigest: state.afterDigest });
+    return signMutationBatchReceipt14(state, 'written', actual);
+  }));
+}
+export async function failMutationBatch14(token, value = {}) {
+  const state = tokenState(token, ['pending', 'completed']), failure = clone(value);
+  return withMutationAudit14(state.input, 'mutation-batch-fail', () => withStateLock(state.locations.consumptionPath, async () => {
+    tokenState(token, ['pending', 'completed']);
+    if (!failure || typeof failure !== 'object' || Array.isArray(failure) || Object.keys(failure).some(field => !['code', 'rollbackOutcome'].includes(field))
+      || failure.code !== undefined && (typeof failure.code !== 'string' || !/^[A-Z][A-Z0-9_]{0,127}$/.test(failure.code))
+      || failure.rollbackOutcome !== undefined && !['retained', 'restored', 'restoration-failed'].includes(failure.rollbackOutcome)) {
+      mutationFail14('ENTROROVE_MUTATION_BATCH_FAILURE', 'Batch failure accepts only an explicit code and reported recovery outcome');
+    }
+    const ledger = await originalLedger(state), writes = { ...ledger.writes };
+    for (const file of state.after) writes[file.path] = batchEntry(state, file, 'failed');
+    await saveMutationConsumption14(state.locations, { ...ledger, writes }); state.status = 'failed';
+    const code = failure.code ?? 'ENTROROVE_MUTATION_BATCH_FAILED';
+    await auditMutation14(state.input, 'mutation-batch-failed', { passId: state.pass.passId, batchId: state.batchId, code,
+      ...(failure.rollbackOutcome ? { reportedRollbackOutcome: failure.rollbackOutcome } : {}) });
+    const actual = await image(state.input, state.binding.root, state.after);
+    return signMutationBatchReceipt14(state, 'failed', actual, { code,
+      ...(failure.rollbackOutcome ? { reportedRollbackOutcome: failure.rollbackOutcome } : {}) });
+  }));
+}

package/local-mutation-binding.mjs

@@ -0,0 +1,89 @@
+import { sign } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { context, readRegistry } from './local-task-handoff-storage.mjs';
+import { readTaskHandoffFence, assertTaskHandoffSnapshotBinding } from './local-task-handoff-fence.mjs';
+import { loadTaskHandoffSigner } from './local-task-handoff-observation.mjs';
+import { mutationFail14, mutationHome14, mutationRoot14, mutationStateRoot14 } from './local-mutation-files.mjs';
+import { snapshotAuthority14, snapshotVerify14, verifySnapshotSources14 } from './local-mutation-snapshot.mjs';
+import { mutationChallenge14, mutationPass14 } from './local-mutation-wire.mjs';
+import { withMutationAudit14 } from './local-mutation-audit.mjs';
+
+export async function mutationOriginalBinding14(input, authority, state) {
+  const root = await mutationRoot14(input.repositoryRoot), home = await mutationHome14(input.home);
+  await mutationStateRoot14(input);
+  const ctx = await context({ ...input, repositoryRoot: root });
+  const registration = (await readRegistry(ctx.registry)).bindings[ctx.registryKey];
+  const current = state ?? await readTaskHandoffFence(input);
+  if (authority.flowId !== input.flowId || authority.stepId !== input.stepId || authority.repositoryDigest !== sha256(root).slice(0, 32)
+    || authority.epoch !== current.epoch || current.status !== 'active'
+    || input.taskId !== undefined && input.taskId !== authority.taskId
+    || ['taskId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId'].some(field => registration?.[field] !== authority[field])) {
+    mutationFail14('ENTROROVE_MUTATION_ORIGINAL_BINDING', 'Mutation authority differs from the original accepted task, step or registered receiver');
+  }
+  if (['leaseId', 'generation', 'executionAttemptNonce'].some(field => input[field] !== undefined && input[field] !== authority[field])) {
+    mutationFail14('ENTROROVE_MUTATION_ORIGINAL_ATTEMPT', 'Caller context differs from the original mutation lease, generation or execution nonce');
+  }
+  const attempt = current.executionAttempts.find(value => value.authority.leaseId === authority.leaseId
+    && value.authority.generation === authority.generation);
+  if (!attempt || !['ready', 'used'].includes(attempt.status) || attempt.executionHome !== home
+    || attempt.authority.authorityId !== authority.executionAuthorityId
+    || sha256(canonical(attempt.authority)) !== authority.executionAuthorityDigest
+    || attempt.authority.attemptNonce !== authority.executionAttemptNonce
+    || attempt.authority.epoch !== authority.epoch) {
+    mutationFail14('ENTROROVE_MUTATION_ORIGINAL_ATTEMPT', 'Mutation authority must retain its original execution attempt and actual home');
+  }
+  if (current.revokedLeaseIds.includes(authority.leaseId)
+    || authority.passId && current.revokedPassIds.includes(authority.passId)
+    || current.receiverClaim && !current.receiverRestoration) {
+    mutationFail14('ENTROROVE_MUTATION_REVOKED', 'Original mutation authority is revoked or its receiver is temporarily handed off');
+  }
+  return { root, home, context: ctx, state: current };
+}
+export async function mutationSnapshotBinding14(input, pass, { allSources = false, targetPath, allowTargetDrift = false } = {}) {
+  mutationPass14(pass);
+  const root = await mutationRoot14(input.repositoryRoot);
+  const snapshot = await snapshotAuthority14(input, root, pass.snapshotReceipt);
+  const receipt = pass.snapshotReceipt;
+  if (receipt.snapshotId !== pass.snapshotId || receipt.snapshotDigest !== pass.snapshotDigest
+    || receipt.receiptDigest !== pass.snapshotReceiptDigest || receipt.contractDigest !== pass.scopeContractDigest
+    || sha256(canonical(snapshot.manifest)) !== pass.snapshotManifestDigest
+    || canonical(receipt.paths) !== canonical(pass.paths)) {
+    mutationFail14('ENTROROVE_MUTATION_SNAPSHOT_BINDING', 'Mutation pass is bound to another snapshot, contract or path set');
+  }
+  if (snapshot.manifest.files.some(file => !file.exists && !pass.newFilePaths.includes(file.path))) {
+    mutationFail14('ENTROROVE_MUTATION_NEW_FILE_SCOPE', 'Missing source is outside the original planned new-file set');
+  }
+  // ArchGuard validates the changed target after a guarded write. The original
+  // snapshot still binds the pass, while its target source is expected to drift
+  // before checkpoint evaluation. Ordinary mutation paths keep the hash check.
+  if (allSources || targetPath && !allowTargetDrift) await verifySnapshotSources14(input, root, snapshot.manifest,
+    { paths: allSources ? snapshot.manifest.paths : [targetPath] });
+  return { ...snapshot, root };
+}
+export async function attestMutationSnapshot14(input) {
+  return withMutationAudit14(input, 'mutation-snapshot-attest', async () => {
+    const challenge = mutationChallenge14(input.challenge);
+    const binding = await mutationOriginalBinding14(input, challenge);
+    if (input.snapshotId !== challenge.snapshotId) mutationFail14('ENTROROVE_MUTATION_SNAPSHOT_BINDING', 'Snapshot attestation requires the cloud-assigned original snapshot identifier');
+    const verified = await snapshotVerify14(input);
+    const snapshot = await snapshotAuthority14(input, binding.root, verified.receipt);
+    assertTaskHandoffSnapshotBinding(binding.state, verified.receipt);
+    if (snapshot.manifest.contractDigest !== challenge.scopeContractDigest
+      || canonical(snapshot.manifest.paths) !== canonical(challenge.paths)
+      || snapshot.manifest.files.some(file => !file.exists && !challenge.newFilePaths.includes(file.path))) {
+      mutationFail14('ENTROROVE_MUTATION_SNAPSHOT_BINDING', 'Snapshot attestation differs from its original cloud scope challenge');
+    }
+    const signer = await loadTaskHandoffSigner(binding.context, input.signerConfigPath, challenge.runnerKeyId);
+    const now = Date.now(), expires = Math.min(now + signer.config.receiptTtlMs, Date.parse(challenge.expiresAt));
+    if (expires <= now) mutationFail14('ENTROROVE_MUTATION_AUTHORITY_EXPIRED', 'Snapshot challenge expired before runner attestation');
+    const payload = { schemaVersion: 'entrorove.mutation-snapshot-attestation/1.0', challengeId: challenge.challengeId,
+      challengeDigest: sha256(canonical(challenge)), nonce: challenge.nonce, runnerId: challenge.runnerId,
+      keyId: challenge.runnerKeyId, flowId: challenge.flowId, taskId: challenge.taskId, ownerId: challenge.ownerId,
+      stepId: challenge.stepId, leaseId: challenge.leaseId, generation: challenge.generation,
+      repositoryId: challenge.repositoryId, repositoryDigest: challenge.repositoryDigest, snapshotId: challenge.snapshotId,
+      paths: [...challenge.paths], manifest: snapshot.manifest, receipt: verified.receipt,
+      issuedAt: new Date(now).toISOString(), expiresAt: new Date(expires).toISOString() };
+    return { schemaVersion: 'entrorove.local-execution/1.0', verified: true,
+      attestation: { ...payload, signature: sign(null, Buffer.from(canonical(payload)), signer.privateKey).toString('base64url') } };
+  });
+}

package/local-mutation-files.mjs

@@ -0,0 +1,270 @@
+import { constants, promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { readBudgetedProjectFile } from './local-budget-reads.mjs';
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const mutationFail14 = (code, message) => { throw Object.assign(new Error(message), { code }); };
+export function mutationId14(value, field) {
+  if (typeof value !== 'string' || !ID.test(value)) mutationFail14('ENTROROVE_ID_INVALID', `${field} must be a safe identifier`);
+  return value;
+}
+export function mutationPath14(value, field = 'path') {
+  if (typeof value !== 'string' || !value || value !== value.normalize('NFC') || path.isAbsolute(value)
+    || /^[A-Za-z]:/.test(value) || value.includes('\\') || /[\u0000-\u001f\u007f]/.test(value)
+    || value.split('/').some(part => !part || part === '.' || part === '..')) {
+    mutationFail14('ENTROROVE_PATH_UNSAFE', `${field} is unsafe`);
+  }
+  return value;
+}
+export function mutationPaths14(values) {
+  if (!Array.isArray(values) || !values.length) mutationFail14('ENTROROVE_PATHS_REQUIRED', 'paths must be a non-empty array');
+  const paths = [...new Set(values.map(value => mutationPath14(value)))].sort();
+  if (paths.length !== values.length) mutationFail14('ENTROROVE_PATHS_DUPLICATE', 'paths must be unique');
+  const selected = new Set(paths);
+  if (paths.some(value => value.split('/').slice(0, -1).some((_, index, parts) => selected.has(parts.slice(0, index + 1).join('/'))))) {
+    mutationFail14('ENTROROVE_PATHS_CONFLICT', 'file paths cannot contain another selected file path');
+  }
+  return paths;
+}
+const sameNode = (left, right) => left.dev === right.dev && left.ino === right.ino;
+const sameFile = (left, right) => sameNode(left, right) && left.size === right.size
+  && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs && left.mode === right.mode;
+function absolute(value, field) {
+  if (typeof value !== 'string' || !value || !path.isAbsolute(value) || /[\u0000-\u001f\u007f]/.test(value)) {
+    mutationFail14('ENTROROVE_PATH_UNSAFE', `${field} must be an absolute path`);
+  }
+  return path.resolve(value);
+}
+export function mutationInside14(root, target, field = 'path') {
+  const relative = path.relative(root, target);
+  if (relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`))) return;
+  mutationFail14('ENTROROVE_PATH_ESCAPE', `${field} escapes its bound directory`);
+}
+async function inspectPath(target, { allowMissing = false, final = 'file', code = 'ENTROROVE_FILE_INVALID' } = {}) {
+  const resolved = absolute(target, 'filesystem path');
+  const base = path.parse(resolved).root; const parts = path.relative(base, resolved).split(path.sep).filter(Boolean);
+  let current = base; const ancestors = [{ path: base, stat: await fs.lstat(base) }];
+  if (!parts.length) return { target: resolved, stat: ancestors[0].stat, exists: true, ancestors };
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part); let stat;
+    try { stat = await fs.lstat(current); } catch (error) {
+      if (error.code === 'ENOENT' && allowMissing) return { target: resolved, exists: false, stat: null, ancestors };
+      throw error;
+    }
+    const last = index === parts.length - 1;
+    if (stat.isSymbolicLink() || (!last && !stat.isDirectory())
+      || (last && final === 'file' && !stat.isFile()) || (last && final === 'directory' && !stat.isDirectory())) {
+      mutationFail14(code, 'mutation paths refuse symlink, non-directory ancestors, and invalid file types');
+    }
+    if (!last) ancestors.push({ path: current, stat });
+    else return { target: resolved, exists: true, stat, ancestors };
+  }
+}
+async function canonicalDirectoryPath(value, { allowMissing = false, code }) {
+  const resolved = absolute(value, 'filesystem path');
+  const base = path.parse(resolved).root;
+  const parts = path.relative(base, resolved).split(path.sep).filter(Boolean);
+  let current = base;
+  for (const [index, part] of parts.entries()) {
+    const candidate = path.join(current, part);
+    let stat;
+    try { stat = await fs.lstat(candidate); } catch (error) {
+      if (error.code === 'ENOENT' && allowMissing) return path.join(current, ...parts.slice(index));
+      throw error;
+    }
+    if (stat.isSymbolicLink()) {
+      const linked = await fs.realpath(candidate);
+      const systemAlias = process.platform === 'darwin' && current === base
+        && ['/var', '/tmp', '/etc'].includes(candidate) && linked === path.join('/private', candidate);
+      if (!systemAlias) mutationFail14(code, 'mutation paths refuse symlink, non-directory ancestors, and invalid file types');
+      current = linked;
+      continue;
+    }
+    if (!stat.isDirectory()) mutationFail14(code, 'mutation paths refuse symlink, non-directory ancestors, and invalid file types');
+    current = candidate;
+  }
+  return current;
+}
+async function assertAncestors(item, code = 'ENTROROVE_STATE_CHANGED') {
+  for (const ancestor of item.ancestors) {
+    const stat = await fs.lstat(ancestor.path);
+    if (stat.isSymbolicLink() || !stat.isDirectory() || !sameNode(stat, ancestor.stat)) {
+      mutationFail14(code, 'mutation path ancestors changed during filesystem access');
+    }
+  }
+}
+export async function mutationRoot14(value) {
+  const canonicalRoot = await canonicalDirectoryPath(value, { code: 'ENTROROVE_ROOT_INVALID' });
+  await inspectPath(canonicalRoot, { final: 'directory', code: 'ENTROROVE_ROOT_INVALID' });
+  return canonicalRoot;
+}
+export async function mutationHome14(value = os.homedir()) {
+  const home = await canonicalDirectoryPath(value, { allowMissing: true, code: 'ENTROROVE_HOME_INVALID' });
+  await inspectPath(home, { allowMissing: true, final: 'directory', code: 'ENTROROVE_HOME_INVALID' });
+  return home;
+}
+export async function mutationTarget14(root, relative, allowMissing = false) {
+  const target = path.join(root, mutationPath14(relative));
+  mutationInside14(root, target);
+  return { ...await inspectPath(target, { allowMissing }), path: relative };
+}
+export const mutationFile14 = (file, options = {}) => inspectPath(file, options);
+export async function mutationRead14(input, root, relative) {
+  const item = await mutationTarget14(root, relative);
+  const handle = await fs.open(item.target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || !sameFile(before, item.stat)) mutationFail14('ENTROROVE_FILE_CHANGED', 'file changed before snapshot reading');
+    const content = await readBudgetedProjectFile(input, item.target, { sourcePath: relative });
+    const after = await handle.stat(); const latest = await mutationTarget14(root, relative);
+    await assertAncestors(item, 'ENTROROVE_FILE_CHANGED');
+    if (!sameFile(before, after) || !sameFile(after, latest.stat) || content.length !== after.size) {
+      mutationFail14('ENTROROVE_FILE_CHANGED', 'file changed during snapshot reading');
+    }
+    return { ...item, content, sha256: sha256(content), mode: after.mode & 0o777 };
+  } finally { await handle.close(); }
+}
+export async function privateMutationDirectory14(directory, { exclusive = false, privateFrom = directory } = {}) {
+  const target = absolute(directory, 'state directory'); const privateRoot = absolute(privateFrom, 'private state root');
+  mutationInside14(privateRoot, target, 'state directory');
+  const base = path.parse(target).root; const parts = path.relative(base, target).split(path.sep).filter(Boolean);
+  let current = base;
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part); const last = index === parts.length - 1;
+    await inspectPath(path.dirname(current), { final: 'directory', code: 'ENTROROVE_STATE_INVALID' });
+    if (last && exclusive) {
+      try { await fs.mkdir(current, { mode: 0o700 }); } catch (error) {
+        if (error.code === 'EEXIST') mutationFail14('ENTROROVE_SNAPSHOT_EXISTS', 'snapshotId already exists and cannot be reused');
+        throw error;
+      }
+    } else {
+      try { await fs.mkdir(current, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    }
+    const checked = await inspectPath(current, { final: 'directory', code: 'ENTROROVE_STATE_INVALID' });
+    if (current === privateRoot || current.startsWith(`${privateRoot}${path.sep}`)) {
+      if (process.platform !== 'win32') await fs.chmod(current, 0o700);
+      await assertAncestors(checked);
+    }
+  }
+  return inspectPath(target, { final: 'directory', code: 'ENTROROVE_STATE_INVALID' });
+}
+export async function mutationStateRoot14(input) {
+  return path.join(await mutationHome14(input.home), '.entrorove');
+}
+async function cleanupTemporary(file, saved) {
+  try {
+    await assertAncestors(saved);
+    const latest = await inspectPath(file, { allowMissing: true, code: 'ENTROROVE_STATE_INVALID' });
+    if (latest.exists && sameNode(latest.stat, saved.stat)) await fs.unlink(file);
+  } catch { /* Refuse cleanup through a changed or linked state ancestor. */ }
+}
+export async function writeMutationFile14(file, content, { privateFrom = path.dirname(file) } = {}) {
+  const parent = await privateMutationDirectory14(path.dirname(file), { privateFrom });
+  await inspectPath(file, { allowMissing: true, code: 'ENTROROVE_STATE_INVALID' });
+  const handle = await fs.open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+  const saved = { target: file, stat: await handle.stat(), ancestors: [...parent.ancestors, { path: parent.target, stat: parent.stat }] };
+  try {
+    if (process.platform !== 'win32') await handle.chmod(0o600);
+    await handle.writeFile(content); await handle.sync();
+    await assertAncestors(saved);
+    const latest = await inspectPath(file, { code: 'ENTROROVE_STATE_INVALID' });
+    if (!sameNode(latest.stat, saved.stat)) mutationFail14('ENTROROVE_STATE_CHANGED', 'state file changed while writing');
+    return latest;
+  } catch (error) { await cleanupTemporary(file, saved); throw error; }
+  finally { await handle.close(); }
+}
+export async function atomicMutationJson14(file, value, { privateFrom = path.dirname(file), replace = false } = {}) {
+  const parent = await privateMutationDirectory14(path.dirname(file), { privateFrom });
+  const destination = await inspectPath(file, { allowMissing: true, code: 'ENTROROVE_STATE_INVALID' });
+  if (destination.exists && !replace) mutationFail14('ENTROROVE_STATE_EXISTS', 'state file already exists');
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  const saved = await writeMutationFile14(temporary, `${canonical(value)}\n`, { privateFrom });
+  try {
+    await assertAncestors(parent);
+    const latest = await inspectPath(file, { allowMissing: true, code: 'ENTROROVE_STATE_INVALID' });
+    if (replace && (latest.exists !== destination.exists || latest.exists && !sameFile(latest.stat, destination.stat))) {
+      mutationFail14('ENTROROVE_STATE_CHANGED', 'state destination changed before atomic publication');
+    }
+    if (replace) await fs.rename(temporary, file);
+    else { await fs.link(temporary, file); await fs.unlink(temporary); }
+    await assertAncestors(saved);
+    const published = await inspectPath(file, { code: 'ENTROROVE_STATE_INVALID' });
+    if (!sameNode(published.stat, saved.stat)) mutationFail14('ENTROROVE_STATE_CHANGED', 'state changed during atomic publication');
+    return file;
+  } finally { await cleanupTemporary(temporary, saved); }
+}
+export async function readMutationJson14(file) {
+  const item = await inspectPath(file, { code: 'ENTROROVE_STATE_INVALID' });
+  if (process.platform !== 'win32' && (item.stat.mode & 0o077) || process.getuid && item.stat.uid !== process.getuid()) {
+    mutationFail14('ENTROROVE_STATE_INVALID', 'state files must be private and owned by the current user');
+  }
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = await handle.stat();
+    if (!sameFile(before, item.stat)) mutationFail14('ENTROROVE_STATE_CHANGED', 'state file changed before reading');
+    const bytes = await handle.readFile(); const after = await handle.stat();
+    await assertAncestors(item);
+    const latest = await inspectPath(file, { code: 'ENTROROVE_STATE_INVALID' });
+    if (!sameFile(before, after) || !sameFile(after, latest.stat)) mutationFail14('ENTROROVE_STATE_CHANGED', 'state file changed during reading');
+    let value;
+    try { value = JSON.parse(bytes.toString('utf8')); } catch { mutationFail14('ENTROROVE_STATE_INVALID', 'state file must contain valid JSON'); }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) mutationFail14('ENTROROVE_STATE_INVALID', 'state file must contain an object');
+    return value;
+  } finally { await handle.close(); }
+}
+export async function cleanupMutationDirectory14(saved) {
+  await assertAncestors(saved);
+  const latest = await inspectPath(saved.target, { allowMissing: true, final: 'directory', code: 'ENTROROVE_STATE_INVALID' });
+  if (!latest.exists) return;
+  if (!sameNode(latest.stat, saved.stat)) mutationFail14('ENTROROVE_STATE_CHANGED', 'snapshot cleanup refuses a replaced directory');
+  await fs.rm(saved.target, { recursive: true, force: false });
+}
+async function projectParents(root, relative) {
+  let current = root;
+  for (const part of relative.split('/').slice(0, -1)) {
+    current = path.join(current, part);
+    await inspectPath(path.dirname(current), { final: 'directory' });
+    try { await fs.mkdir(current, { mode: 0o755 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    await inspectPath(current, { final: 'directory' });
+  }
+}
+async function expectedProjectFile(input, root, relative, expected) {
+  const source = await mutationTarget14(root, relative, true);
+  if (source.exists !== expected.exists) mutationFail14('ENTROROVE_SNAPSHOT_CHANGED', `${relative} changed before guarded writing`);
+  if (source.exists) {
+    const read = await mutationRead14(input, root, relative);
+    if (read.sha256 !== expected.sha256 || read.mode !== expected.mode) mutationFail14('ENTROROVE_SNAPSHOT_CHANGED', `${relative} changed before guarded writing`);
+    return read;
+  }
+  if (expected.sha256 !== sha256('entrorove.missing-file/1.0') || expected.mode !== null) {
+    mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'missing guarded-write baseline is invalid');
+  }
+  return source;
+}
+export async function writeMutationProjectFile14(input, root, relative, content, expected) {
+  if (await mutationRoot14(input.repositoryRoot) !== root) mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'guarded-write root is not bound');
+  mutationPath14(relative, 'targetPath');
+  if (!expected || expected.path !== relative || typeof expected.exists !== 'boolean') mutationFail14('ENTROROVE_SNAPSHOT_BINDING', 'guarded-write requires its exact snapshot file entry');
+  await expectedProjectFile(input, root, relative, expected);
+  await projectParents(root, relative);
+  const before = await expectedProjectFile(input, root, relative, expected);
+  const temporary = `${before.target}.${randomUUID()}.entrorove.tmp`;
+  const handle = await fs.open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), expected.mode ?? 0o644);
+  const saved = { stat: await handle.stat(), ancestors: before.ancestors };
+  try {
+    if (process.platform !== 'win32') await handle.chmod(expected.mode ?? 0o644);
+    await handle.writeFile(content); await handle.sync();
+    await assertAncestors(saved, 'ENTROROVE_FILE_CHANGED');
+    const latest = await expectedProjectFile(input, root, relative, expected);
+    if (before.exists && !sameNode(before.stat, latest.stat)) mutationFail14('ENTROROVE_FILE_CHANGED', 'guarded-write target changed before publication');
+    if (expected.exists) await fs.rename(temporary, before.target);
+    else { await fs.link(temporary, before.target); await fs.unlink(temporary); }
+    await assertAncestors(saved, 'ENTROROVE_FILE_CHANGED');
+    const published = await mutationTarget14(root, relative);
+    if (!sameNode(published.stat, saved.stat)) mutationFail14('ENTROROVE_FILE_CHANGED', 'guarded-write target changed during publication');
+    return { target: published.target, sha256: sha256(content), mode: published.stat.mode & 0o777 };
+  } finally { await handle.close(); await cleanupTemporary(temporary, saved); }
+}