@entrorove/skill 0.1.22 → 0.1.24

package/local-merge-snapshot-rollback.mjs

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { verifySnapshotManifest } from './local-integrity.mjs';
+import { readSnapshotCopy14 } from './local-mutation-snapshot.mjs';
+import { context, identifier, json, read, fail } from './local-merge-storage.mjs';
+
+export async function readSnapshotRollbackImages(input) {
+  const ctx = await context({ ...input, stepId: input.stepId ?? 'snapshot-rollback' });
+  const directory = path.join(ctx.home, '.entrorove', 'snapshots', ctx.repo, ctx.flowId, identifier(input.snapshotId));
+  const manifest = await json(path.join(directory, 'manifest.json'));
+  const check = verifySnapshotManifest(manifest, { snapshotId: input.snapshotId, flowId: ctx.flowId,
+    stepId: input.stepId ?? manifest.stepId, repositoryDigest: ctx.repo });
+  if (!check.verified) fail('MERGE_SNAPSHOT_CORRUPT', check.reason);
+  ctx.stepId = manifest.stepId; ctx.input.stepId = manifest.stepId; ctx.input.paths = manifest.paths;
+  const before = [], after = [];
+  for (const file of manifest.files) {
+      const copy = await readSnapshotCopy14(ctx.input, directory, manifest, file.path);
+      const value = { sha256: copy.sha256, bytes: copy.content };
+      if (value.sha256 !== file.sha256) fail('MERGE_SNAPSHOT_CORRUPT', 'Every original snapshot backup must match before restoration starts');
+      before.push({ path: file.path, ...await read(path.join(ctx.root, file.path), ctx.input, file.path, true) });
+      after.push({ ...file, bytes: value.bytes });
+  }
+  return { ctx, manifest, before, after };
+}
+export async function atomicSnapshotRollback(input) {
+  fail('MERGE_ROLLBACK_AUTHORITY_REQUIRED', 'Legacy snapshot hashes do not authorize restoration; use the original durable merge transaction and its fresh cloud-signed rollback authorization');
+}

package/local-merge-storage.mjs

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+import { constants, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { readBudgetedProjectFile, budgetBindingForRead } from './local-budget-reads.mjs';
+import { withExclusiveLock } from './local-archguard-state.mjs';
+import { context as handoffContext, readRegistry } from './local-task-handoff-storage.mjs';
+import { readTaskHandoffFence, assertTaskHandoffActive } from './local-task-handoff-fence.mjs';
+
+export { canonical, sha256 };
+export const MISSING_SHA256 = sha256('entrorove.missing-file/1.0');
+export function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+export function identifier(value) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) fail('MERGE_ID_INVALID', 'Merge identifier is invalid');
+  return value;
+}
+export function safePath(value) {
+  if (typeof value !== 'string' || !value || value.length > 500 || value !== value.trim() || value !== value.normalize('NFC') || path.isAbsolute(value)
+    || /^[~]/.test(value) || /[:\\\u0000-\u001f\u007f]/.test(value)
+    || value.split('/').some(part => !part || part === '.' || part === '..')) fail('MERGE_PATH_INVALID', 'Merge path is unsafe');
+  return value;
+}
+export function paths(value) {
+  if (!Array.isArray(value) || !value.length || value.length > 512) fail('MERGE_PATHS_REQUIRED', 'Merge paths must be nonempty and bounded');
+  const sorted = value.map(safePath).sort();
+  if (new Set(sorted).size !== sorted.length || sorted.some((item, index) => sorted.slice(index + 1).some(other => other.startsWith(`${item}/`)))) {
+    fail('MERGE_PATHS_OVERLAP', 'Merge paths must be unique and cannot overlap');
+  }
+  return sorted;
+}
+export async function noLinks(file, missing = false) {
+  let current = path.parse(path.resolve(file)).root;
+  for (const part of path.resolve(file).slice(current.length).split(path.sep)) {
+    current = path.join(current, part);
+    try { const stat = await fs.lstat(current); if (stat.isSymbolicLink()) fail('MERGE_SYMLINK_REJECTED', 'Merge paths and private state forbid symbolic links'); }
+    catch (error) { if (missing && error.code === 'ENOENT') return; throw error; }
+  }
+}
+export async function directory(file) {
+  await noLinks(file, true); await fs.mkdir(file, { recursive: true, mode: 0o700 }); await noLinks(file);
+  if (!(await fs.lstat(file)).isDirectory()) fail('MERGE_STATE_INVALID', 'Merge directory must be real');
+}
+export async function read(file, input = null, sourcePath = null, missing = false) {
+  await noLinks(file, missing); let handle;
+  try {
+    handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const before = await handle.stat();
+    if (!before.isFile() || before.size > 32 * 1024 * 1024) fail('MERGE_FILE_INVALID', 'Merge input must be a bounded regular file');
+    const bytes = input ? await budgetedSource(input, file, sourcePath) : await handle.readFile();
+    const after = await handle.stat(), named = await fs.lstat(file);
+    if (before.ino !== named.ino || before.dev !== named.dev || before.size !== after.size || before.size !== named.size || before.mtimeMs !== after.mtimeMs
+      || before.mtimeMs !== named.mtimeMs || before.mode !== after.mode || before.mode !== named.mode
+      || bytes.length !== before.size || named.isSymbolicLink()) fail('MERGE_READ_RACE', 'Merge input changed while reading');
+    return { exists: true, sha256: sha256(bytes), mode: before.mode & 0o777, bytes,
+      fileId: `${before.dev}:${before.ino}`, nlink: before.nlink };
+  } catch (error) { if (missing && error.code === 'ENOENT') return { exists: false, sha256: MISSING_SHA256, mode: null, bytes: null }; throw error; }
+  finally { await handle?.close(); }
+}
+async function budgetedSource(input, file, sourcePath) {
+  if (!await budgetBindingForRead(input) || path.resolve(file) === path.join(input.repositoryRoot, safePath(sourcePath))) {
+    return readBudgetedProjectFile(input, file, { sourcePath });
+  }
+  const proxy = path.join(input.home, '.entrorove', 'snapshots', sha256(input.repositoryRoot).slice(0, 32), input.flowId, `merge-read-${randomUUID()}`);
+  await directory(path.dirname(proxy)); await fs.mkdir(proxy, { mode: 0o700 });
+  const target = path.join(proxy, safePath(sourcePath));
+  try { await directory(path.dirname(target)); await fs.link(file, target);
+    return await readBudgetedProjectFile(input, target, { sourcePath }); }
+  finally { await fs.rm(proxy, { recursive: true, force: true }); }
+}
+export async function atomic(file, bytes, mode = 0o600, beforePublish = null) {
+  await noLinks(file, true); await directory(path.dirname(file));
+  const temporary = `${file}.${randomUUID()}.tmp`; const handle = await fs.open(temporary, 'wx', mode);
+  try { await handle.writeFile(bytes); await handle.chmod(mode); await handle.sync(); } finally { await handle.close(); }
+  try { await noLinks(file, true); if (beforePublish) await beforePublish(); await fs.rename(temporary, file); }
+  finally { await fs.rm(temporary, { force: true }); }
+}
+export const json = async file => JSON.parse((await read(file)).bytes.toString('utf8'));
+export const writeJson = (file, value) => atomic(file, canonical(value) + '\n');
+export async function context(input) {
+  if (typeof input.repositoryRoot !== 'string' || !path.isAbsolute(input.repositoryRoot)) fail('MERGE_ROOT_INVALID', 'Merge repository root must be absolute');
+  await noLinks(input.repositoryRoot); const root = await fs.realpath(input.repositoryRoot); await noLinks(root);
+  if (!(await fs.stat(root)).isDirectory()) fail('MERGE_ROOT_INVALID', 'Merge repository root must be a real directory');
+  const suppliedHome = input.home ?? os.homedir(); await noLinks(suppliedHome);
+  if (typeof suppliedHome !== 'string' || !path.isAbsolute(suppliedHome)) fail('MERGE_HOME_INVALID', 'Merge home must be an absolute private directory');
+  const home = await fs.realpath(suppliedHome); await noLinks(home);
+  const repo = sha256(root).slice(0, 32), flowId = identifier(input.flowId), stepId = identifier(input.stepId);
+  const state = path.join(home, '.entrorove', 'merges', repo, flowId); await directory(state);
+  for (const file of [path.join(home, '.entrorove'), path.join(home, '.entrorove', 'merges'), path.dirname(state), state]) {
+    const stat = await fs.lstat(file);
+    if (process.platform !== 'win32' && stat.mode & 0o077 || typeof process.getuid === 'function' && stat.uid !== process.getuid()) fail('MERGE_STATE_PERMISSIONS', 'Merge private hierarchy must remain privately owned');
+  }
+  return { root, home, repo, flowId, stepId, state, input: { ...input, repositoryRoot: root, home } };
+}
+export async function withMergeFence(ctx, action) {
+  const fence = await handoffContext(ctx.input, true);
+  return withExclusiveLock(`${fence.file}.lock`, async () => {
+    const state = await readTaskHandoffFence(ctx.input);
+    await assertTaskHandoffActive({ ...ctx.input, epoch: state.epoch });
+    const registration = (await readRegistry(fence.registry)).bindings[fence.registryKey];
+    return withExclusiveLock(path.join(ctx.home, '.entrorove', 'merges', ctx.repo, 'repository.lock'), () => action(state, registration));
+  });
+}

package/local-merge-targets.mjs

@@ -0,0 +1,47 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fail, noLinks, paths, context, directory } from './local-merge-storage.mjs';
+
+async function assertFileIdentities(input, names) {
+  const identities = new Set();
+  for (const name of names) {
+    const file = path.join(input.repositoryRoot, name); await noLinks(file, true);
+    try {
+      const stat = await fs.lstat(file), identity = `${stat.dev}:${stat.ino}`;
+      if (stat.isFile() && (stat.nlink !== 1 || identities.has(identity))) {
+        fail('MERGE_TARGET_ALIAS', 'Merge targets must be distinct files without shared hard-link identities');
+      }
+      if (stat.isFile()) identities.add(identity);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}
+async function assertFilesystemNames(input, names) {
+  const root = input.repositoryRoot; await noLinks(root);
+  const original = await fs.lstat(root), ctx = await context(input), privateRoot = path.join(ctx.state, 'filesystem-probes');
+  await directory(privateRoot);
+  if ((await fs.lstat(privateRoot)).dev !== original.dev) fail('MERGE_TARGET_FILESYSTEM_MISMATCH', 'Private alias validation must use the actual target filesystem device');
+  const probe = path.join(privateRoot, randomUUID());
+  await fs.mkdir(probe, { mode: 0o700 }); const owner = await fs.lstat(probe);
+  try {
+    for (const name of names) {
+      const file = path.join(probe, name); await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+      try { const handle = await fs.open(file, 'wx', 0o600); await handle.close(); }
+      catch (error) {
+        if (['EEXIST', 'EISDIR', 'ENOTDIR'].includes(error.code)) fail('MERGE_TARGET_ALIAS', 'Target filesystem maps different batch paths to an overlapping name');
+        throw error;
+      }
+    }
+    const current = await fs.lstat(root);
+    if (current.ino !== original.ino || current.dev !== original.dev || current.isSymbolicLink()) fail('MERGE_TARGET_CAS', 'Target repository changed during filesystem alias validation');
+  } finally {
+    const current = await fs.lstat(probe);
+    if (current.ino !== owner.ino || current.dev !== owner.dev || current.isSymbolicLink()) fail('MERGE_TARGET_CAS', 'Owned filesystem probe changed before cleanup');
+    await fs.rm(probe, { recursive: true });
+  }
+}
+export async function assertDistinctMergeTargets(input, files) {
+  const names = paths(files.map(file => file.path));
+  await assertFileIdentities(input, names); await assertFilesystemNames(input, names);
+  await assertFileIdentities(input, names);
+}

package/local-merge-transaction.mjs

@@ -0,0 +1,133 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256, fail, paths, MISSING_SHA256, read, atomic, noLinks } from './local-merge-storage.mjs';
+import { assertDistinctMergeTargets } from './local-merge-targets.mjs';
+
+export const metadata = file => ({ path: file.path, exists: file.exists, sha256: file.sha256, mode: file.mode });
+function validate(files) {
+  if (canonical(paths(files.map(file => file.path))) !== canonical(files.map(file => file.path))) fail('MERGE_BATCH_PATHS', 'Atomic batch paths must be sorted, unique and nonoverlapping');
+  for (const file of files) {
+    if (typeof file.exists !== 'boolean' || file.exists && (!Buffer.isBuffer(file.bytes) || sha256(file.bytes) !== file.sha256
+      || !Number.isInteger(file.mode) || file.mode < 0 || file.mode > 0o777)
+      || !file.exists && (file.bytes !== null || file.sha256 !== MISSING_SHA256 || file.mode !== null)) {
+      fail('MERGE_BATCH_BACKUP', 'Every atomic batch image must have its original existence, bytes, mode and digest');
+    }
+  }
+}
+async function current(input, image) {
+  const value = await read(path.join(input.repositoryRoot, image.path), input, image.path, true);
+  return { path: image.path, ...value };
+}
+export async function assertBatchImage(input, files) {
+  validate(files);
+  for (const file of files) {
+    if (canonical(metadata(await current(input, file))) !== canonical(metadata(file))) fail('MERGE_TARGET_CAS', 'A target differs from its actual frozen batch image');
+  }
+}
+async function createParents(input, file, parents) {
+  let currentPath = input.repositoryRoot;
+  for (const part of path.relative(input.repositoryRoot, path.dirname(file)).split(path.sep).filter(Boolean)) {
+    currentPath = path.join(currentPath, part); await noLinks(currentPath, true);
+    try { await fs.mkdir(currentPath, { mode: 0o700 });
+      const stat = await fs.lstat(currentPath); parents.push({ path: currentPath, ino: stat.ino, dev: stat.dev }); }
+    catch (error) { if (error.code !== 'EEXIST' || !(await fs.lstat(currentPath)).isDirectory()) throw error; }
+  }
+}
+async function cleanupParents(parents) {
+  const failures = [];
+  for (const entry of [...parents].reverse()) {
+    try { const stat = await fs.lstat(entry.path);
+      if (stat.isSymbolicLink() || stat.ino !== entry.ino || stat.dev !== entry.dev) fail('MERGE_RECOVERY_CAS', 'Created parent directory changed before restoration');
+      await fs.rmdir(entry.path); }
+    catch (error) { if (error.code !== 'ENOENT') failures.push({ path: entry.path, code: error.code ?? 'MERGE_PARENT_RESTORE_IO', message: error.message }); }
+  }
+  return failures;
+}
+async function writeImage(input, image, parents = [], expected = null) {
+  const file = path.join(input.repositoryRoot, image.path); await noLinks(file, true);
+  if (image.exists) { await createParents(input, file, parents);
+    await atomic(file, image.bytes, image.mode, expected ? () => assertBatchImage(input, [expected]) : null); }
+  else { if (expected) await assertBatchImage(input, [expected]);
+    try { await fs.unlink(file); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+}
+async function restoreTouched(input, before, after, touched) {
+  const errors = [];
+  for (const index of [...touched].reverse()) {
+    try {
+      const actual = metadata(await current(input, before[index]));
+      if (canonical(actual) === canonical(metadata(before[index]))) continue;
+      if (canonical(actual) !== canonical(metadata(after[index]))) fail('MERGE_RECOVERY_CAS', 'Recovery refuses to overwrite an unknown third-party target');
+      await writeImage(input, before[index], [], after[index]);
+    } catch (error) { errors.push({ path: before[index].path, code: error.code ?? 'MERGE_RESTORE_IO', message: error.message }); }
+  }
+  return errors;
+}
+async function restorationFailures(input, before) {
+  try { await assertBatchImage(input, before); return []; }
+  catch (error) { return [{ path: 'batch', code: error.code ?? 'MERGE_RESTORATION_INCOMPLETE', message: error.message }]; }
+}
+export async function applyFileBatch(input, before, after, effects = {}) {
+  validate(before); validate(after);
+  if (canonical(before.map(file => file.path)) !== canonical(after.map(file => file.path))) fail('MERGE_BATCH_SCOPE', 'Atomic before/after scopes differ');
+  const changed = before.map((file, index) => canonical(metadata(file)) !== canonical(metadata(after[index])) ? index : -1).filter(index => index >= 0);
+  if (!changed.length) fail('MERGE_CHANGES_REQUIRED', 'An atomic merge or rollback cannot be an empty change');
+  await assertDistinctMergeTargets(input, before);
+  await assertBatchImage(input, before);
+  const touched = [], createdParents = [];
+  try {
+    if (effects.prepare) await effects.prepare();
+    for (const index of changed) {
+      await assertBatchImage(input, [before[index]]); touched.push(index);
+      if (after[index].exists) await createParents(input, path.join(input.repositoryRoot, after[index].path), createdParents);
+      if (effects.progress) await effects.progress({ touched: [...touched], createdParents: [...createdParents] });
+      await assertBatchImage(input, [before[index]]);
+      await writeImage(input, after[index], createdParents, before[index]);
+    }
+    await assertBatchImage(input, after);
+    const result = effects.finish ? await effects.finish() : null;
+    return { applied: true, before: before.map(metadata), after: after.map(metadata), createdParents, result };
+  } catch (error) {
+    const failures = [...await restoreTouched(input, before, after, touched), ...await cleanupParents(createdParents), ...await restorationFailures(input, before)];
+    const outcome = { applied: false, code: error.code ?? 'MERGE_BATCH_IO', reason: error.message,
+      rollbackOutcome: failures.length ? 'restoration-failed' : 'restored', recoveryRequired: failures.length > 0, touched, createdParents, failures };
+    if (effects.failed) {
+      try { await effects.failed(outcome); }
+      catch (auditError) { outcome.auditFailure = { code: auditError.code ?? 'MERGE_AUDIT_IO', reason: auditError.message }; outcome.recoveryRequired = true; }
+    }
+    return outcome;
+  }
+}
+export async function recoverFileBatch(input, before, after, touched, createdParents = []) {
+  validate(before); validate(after);
+  if (!Array.isArray(touched) || touched.some(index => !Number.isSafeInteger(index) || index < 0 || index >= before.length)
+    || new Set(touched).size !== touched.length || canonical(before.map(file => file.path)) !== canonical(after.map(file => file.path))) fail('MERGE_RECOVERY_INVALID', 'Recovery requires the exact original batch journal');
+  if (!Array.isArray(createdParents) || createdParents.some(entry => typeof entry.path !== 'string'
+    || path.relative(input.repositoryRoot, entry.path).startsWith('..') || !Number.isSafeInteger(entry.ino) || !Number.isSafeInteger(entry.dev))) fail('MERGE_RECOVERY_INVALID', 'Recovery directory ownership is invalid');
+  const failures = [...await restoreTouched(input, before, after, touched), ...await cleanupParents(createdParents), ...await restorationFailures(input, before)];
+  return { restored: failures.length === 0, rollbackOutcome: failures.length ? 'restoration-failed' : 'restored', failures };
+}
+export async function rollbackFileBatch(input, before, after, createdParents, effects = {}) {
+  const original = [];
+  for (const entry of createdParents) {
+    if (typeof entry.path !== 'string' || path.relative(input.repositoryRoot, entry.path).startsWith('..')
+      || entry.path === input.repositoryRoot) fail('MERGE_PARENT_CHANGED', 'Rollback parent is outside its original repository');
+    await noLinks(entry.path); const stat = await fs.lstat(entry.path);
+    if (!stat.isDirectory() || stat.ino !== entry.ino || stat.dev !== entry.dev) fail('MERGE_PARENT_CHANGED', 'Rollback parent lost its original created-directory identity');
+    original.push({ ...entry, mode: stat.mode & 0o777 });
+  }
+  const outcome = await applyFileBatch(input, before, after, { ...effects, finish: async () => {
+    const failures = await cleanupParents(original);
+    if (failures.length) fail('MERGE_PARENT_RESTORE_IO', 'Rollback cannot remove a changed or nonempty created parent');
+    return effects.finish ? effects.finish() : null;
+  } });
+  if (!outcome.applied) {
+    outcome.restoredParents = [];
+    for (const entry of original) {
+      try { const stat = await fs.lstat(entry.path);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== entry.mode) fail('MERGE_PARENT_RESTORE_IO', 'Rollback failure did not retain its original parent mode and existence');
+        outcome.restoredParents.push({ path: entry.path, ino: stat.ino, dev: stat.dev }); }
+      catch (error) { outcome.failures.push({ path: entry.path, code: error.code, message: error.message }); outcome.recoveryRequired = true; outcome.rollbackOutcome = 'restoration-failed'; }
+    }
+  }
+  return outcome;
+}

package/local-mutation-audit.mjs

@@ -0,0 +1,34 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { mutationRoot14, mutationStateRoot14, mutationTarget14, privateMutationDirectory14 } from './local-mutation-files.mjs';
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const CODE = /^[A-Z][A-Z0-9_]{0,127}$/;
+function safeId(value) { return typeof value === 'string' && ID.test(value) ? value : null; }
+export async function auditMutation14(input, event, fields = {}) {
+  const root = await mutationRoot14(input.repositoryRoot); const stateRoot = await mutationStateRoot14(input);
+  await privateMutationDirectory14(stateRoot, { privateFrom: stateRoot });
+  const file = await mutationTarget14(stateRoot, 'invocations.jsonl', true);
+  const handle = await fs.open(file.target, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | (constants.O_NOFOLLOW ?? 0), 0o600);
+  try {
+    const opened = await handle.stat(); const current = await mutationTarget14(stateRoot, 'invocations.jsonl');
+    if (!opened.isFile() || opened.dev !== current.stat.dev || opened.ino !== current.stat.ino) throw new Error('Mutation audit file changed during open');
+    const record = { schemaVersion: 'entrorove.local-execution/1.0', at: new Date().toISOString(), event,
+      repositoryDigest: sha256(root).slice(0, 32), flowId: safeId(input.flowId), stepId: safeId(input.stepId),
+      ...(typeof input.targetPath === 'string' ? { targetPathDigest: sha256(input.targetPath) } : {}), ...fields };
+    await handle.write(`${canonical(record)}\n`); await handle.sync();
+    if (process.platform !== 'win32') await handle.chmod(0o600);
+    const after = await mutationTarget14(stateRoot, path.basename(file.target));
+    if (after.stat.dev !== opened.dev || after.stat.ino !== opened.ino) throw new Error('Mutation audit file changed during append');
+  } finally { await handle.close(); }
+}
+export async function recordMutationDenied14(input, cause, operation = 'guarded-write') {
+  const code = typeof cause?.code === 'string' && CODE.test(cause.code) ? cause.code : 'ENTROROVE_MUTATION_REJECTED';
+  try { await auditMutation14(input, `${operation}-rejected`, { code }); }
+  catch { throw Object.assign(new Error('Mutation was refused and its audit could not be persisted safely'), { code: 'ENTROROVE_MUTATION_AUDIT_FAILED' }); }
+}
+export async function withMutationAudit14(input, operation, action) {
+  try { return await action(); }
+  catch (cause) { await recordMutationDenied14(input, cause, operation); throw cause; }
+}

package/local-mutation-authority.mjs

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { appendLedgerRecord } from './local-ledger.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { withTaskHandoffIssueFence, withTaskHandoffWriteFence, assertTaskHandoffSnapshotBinding } from './local-task-handoff-fence.mjs';
+import { mutationFail14, mutationPath14, mutationStateRoot14,
+  privateMutationDirectory14, writeMutationProjectFile14 } from './local-mutation-files.mjs';
+import { mutationPass14, mutationLifetime14 } from './local-mutation-wire.mjs';
+import { mutationOriginalBinding14, mutationSnapshotBinding14 } from './local-mutation-binding.mjs';
+import { installMutationPass14, mutationPassLocations14, readMutationConsumption14,
+  readStoredMutationPass14, saveMutationConsumption14 } from './local-mutation-pass-store.mjs';
+import { auditMutation14, withMutationAudit14 } from './local-mutation-audit.mjs';
+import { withSwarmMutationLease } from './local-swarm-mutation.mjs';
+export { beginMutationBatch14, finishMutationBatch14, failMutationBatch14 } from './local-mutation-batch.mjs';
+
+const SCHEMA = 'entrorove.local-execution/1.0';
+function suppliedPass(input) {
+  if (!input.mutationPass) mutationFail14('ENTROROVE_MUTATION_AUTHORITY_REQUIRED', 'Mutation requires its original short-lived cloud-signed pass');
+  return mutationPass14(input.mutationPass);
+}
+export async function mutateGate14(input) {
+  return withMutationAudit14(input, 'mutate-gate', async () => {
+    const pass = suppliedPass(input), binding = await mutationOriginalBinding14(input, pass);
+    const snapshot = await mutationSnapshotBinding14(input, pass, { allSources: true });
+    assertTaskHandoffSnapshotBinding(binding.state, pass.snapshotReceipt);
+    return { schemaVersion: SCHEMA, status: 'verified', allowed: true, snapshotId: snapshot.manifest.snapshotId,
+      receiptDigest: pass.snapshotReceiptDigest, paths: [...pass.paths], coordinationRequired: false };
+  });
+}
+export async function issueMutationPass14(input) {
+  return withMutationAudit14(input, 'mutation-pass-issue', async () => {
+    const pass = suppliedPass(input);
+    return withTaskHandoffIssueFence(input, async state => {
+      const binding = await mutationOriginalBinding14(input, pass, state);
+      await mutationSnapshotBinding14(input, pass, { allSources: true });
+      assertTaskHandoffSnapshotBinding(state, pass.snapshotReceipt);
+      mutationLifetime14(pass);
+      const locations = await installMutationPass14(input, binding, pass);
+      await auditMutation14(input, 'mutation-pass-issued', { passId: pass.passId, leaseId: pass.leaseId,
+        generation: pass.generation, executionAttemptNonce: pass.executionAttemptNonce });
+      return { schemaVersion: SCHEMA, gatePassPath: locations.gatePassPath, pass };
+    });
+  });
+}
+async function checkedPass(input, state) {
+  const pass = await readStoredMutationPass14(input), target = mutationPath14(input.targetPath, 'targetPath');
+  if (!pass.paths.includes(target)) mutationFail14('ENTROROVE_MUTATION_WRITE_SCOPE', 'Guarded writing is outside the cloud pass path set');
+  const binding = await mutationOriginalBinding14(input, pass, state);
+  const snapshot = await mutationSnapshotBinding14(input, pass, { targetPath: target });
+  assertTaskHandoffSnapshotBinding(binding.state, pass.snapshotReceipt);
+  const locations = await mutationPassLocations14(input, binding, pass);
+  const ledger = await readMutationConsumption14(pass, locations);
+  if (Object.hasOwn(ledger.writes, target)) mutationFail14('ENTROROVE_MUTATION_PASS_CONSUMED', 'Mutation pass was already consumed or has an unresolved physical write');
+  return { pass, target, binding, snapshot, locations, ledger };
+}
+export async function verifyMutationPass14(input) {
+  return withMutationAudit14(input, 'mutation-pass-verify', async () => {
+    const value = await checkedPass(input);
+    return { schemaVersion: SCHEMA, verified: true, pass: value.pass, targetPath: value.target };
+  });
+}
+function contentFor(input, baseline) {
+  if (input.expectedSha256 !== undefined && input.expectedSha256 !== null && input.expectedSha256 !== baseline.sha256) {
+    mutationFail14('ENTROROVE_WRITE_BASELINE', 'Target differs from the expected snapshot hash');
+  }
+  let content; try { content = typeof input.content === 'string' ? input.content : JSON.stringify(input.content); }
+  catch { mutationFail14('ENTROROVE_CONTENT_INVALID', 'Guarded-write content must be finite JSON or text'); }
+  if (typeof content !== 'string') mutationFail14('ENTROROVE_CONTENT_INVALID', 'Guarded-write content must be JSON or text');
+  return content;
+}
+async function performWrite(input, state, value) {
+  const current = await checkedPass(input, state), { pass, target, binding, snapshot, locations, ledger } = current;
+  if (canonical(value.pass) !== canonical(pass)) mutationFail14('ENTROROVE_MUTATION_PASS_CHANGED', 'Mutation pass changed while waiting for its original write lock');
+  return withSwarmMutationLease(input, pass, async () => {
+    const baseline = snapshot.manifest.files.find(file => file.path === target), content = contentFor(input, baseline);
+    const entry = { status: 'pending', contentDigest: sha256(content), at: new Date().toISOString() };
+    await saveMutationConsumption14(locations, { ...ledger, writes: { ...ledger.writes, [target]: entry } });
+    await auditMutation14(input, 'guarded-write-authorized', { passId: pass.passId, sha256: entry.contentDigest });
+    mutationLifetime14(pass);
+    const written = await writeMutationProjectFile14(input, binding.root, target, content, baseline);
+    await saveMutationConsumption14(locations, { ...ledger, writes: { ...ledger.writes, [target]: { ...entry, status: 'written' } } });
+    await auditMutation14(input, 'guarded-write', { passId: pass.passId, sha256: written.sha256 });
+    const stateRoot = await mutationStateRoot14(input);
+    await privateMutationDirectory14(path.join(stateRoot, 'ledgers', pass.repositoryDigest), { privateFrom: stateRoot });
+    await appendLedgerRecord(input, 'guarded-write', { flowId: pass.flowId, stepId: pass.stepId, targetPath: target,
+      sha256: written.sha256, passId: pass.passId });
+    return { schemaVersion: SCHEMA, status: 'verified', written: true, targetPath: target, sha256: written.sha256 };
+  });
+}
+export async function guardedWrite14(input) {
+  return withMutationAudit14(input, 'guarded-write', async () => {
+    const value = await checkedPass(input), pass = value.pass;
+    return withStateLock(value.locations.consumptionPath, () => withTaskHandoffWriteFence({ ...input,
+      epoch: pass.epoch, passId: pass.passId, leaseId: pass.leaseId }, state => performWrite(input, state, value)));
+  });
+}

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