deadbyte-mcp 0.8.7

package/src/machine-fs-smoke-client.mjs

@@ -0,0 +1,134 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/client/stdio';
+import { CODING_GRANT_SCHEMA, loadCodingPolicy } from './coding-plane.mjs';
+import { verifyMachineFsReceiptFile } from './machine-fs.mjs';
+import { generateTrustKeypair } from './trust.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, '..');
+const serverPath = path.join(repoRoot, 'src', 'mcp-server.mjs');
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+const structured = (result, label) => {
+  if (result.isError) throw new Error(`${label} returned error: ${JSON.stringify(result.structuredContent ?? result.content)}`);
+  if (!result.structuredContent || typeof result.structuredContent !== 'object') throw new Error(`${label} missing structured output`);
+  return result.structuredContent;
+};
+
+const scratch = await mkdtemp(path.join(os.tmpdir(), 'deadbyte-machine-fs-smoke-'));
+const coreRoot = path.join(scratch, 'core');
+const trustRoot = path.join(scratch, 'trust');
+await mkdir(coreRoot, { recursive: true });
+await mkdir(trustRoot, { recursive: true });
+const keys = await generateTrustKeypair({
+  privateKeyPath: path.join(trustRoot, 'private.pem'),
+  publicKeyPath: path.join(trustRoot, 'public.pem')
+});
+const policyPath = path.join(scratch, 'coding-policy.json');
+const grantPath = path.join(scratch, 'coding-grant.json');
+const evidenceDir = path.join(scratch, 'evidence');
+const rawPolicy = {
+  schema: 'deadbyte.coding-policy.v1', enabled: true,
+  lease_file: grantPath, evidence_dir: evidenceDir,
+  roots: { core: { path: coreRoot, read: true, write: true, exec: false, deny_paths: ['.deadbyte-machine-fs-recovery'] } },
+  commands: {}, max_read_bytes: 1024 * 1024, max_write_bytes: 1024 * 1024
+};
+const policyBytes = Buffer.from(`${JSON.stringify(rawPolicy, null, 2)}\n`, 'utf8');
+await writeFile(policyPath, policyBytes, { flag: 'wx' });
+const policy = await loadCodingPolicy(policyPath);
+await writeFile(grantPath, `${JSON.stringify({
+  schema: CODING_GRANT_SCHEMA, policy_sha256: policy.policy_sha256,
+  instance_nonce: randomBytes(32).toString('hex'), root_ids: ['core'],
+  granted_at_utc: new Date().toISOString()
+}, null, 2)}\n`, { flag: 'wx' });
+
+const client = new Client({ name: 'deadbyte-machine-fs-smoke', version: '0.8.0' },
+  { versionNegotiation: { mode: { pin: '2026-07-28' } } });
+const transport = new StdioClientTransport({
+  command: process.execPath, args: [serverPath], cwd: repoRoot,
+  env: { ...getDefaultEnvironment(), DEADBYTE_CODING_RUNTIME: '1', DEADBYTE_MACHINE_FS_RUNTIME: '1',
+    DEADBYTE_CODING_POLICY: policyPath, DEADBYTE_SIGNING_KEY: keys.privateKeyPath,
+    DEADBYTE_VERIFY_KEY: keys.publicKeyPath }, stderr: 'pipe'
+});
+const stderrChunks = [];
+transport.stderr?.on('data', chunk => stderrChunks.push(Buffer.from(chunk)));
+const baseTools = ['contained_transform','evidence_verify','file_read','proof_execute','workspace_open'];
+const codingTools = [
+  'coding_benchmark_run','coding_command_run','coding_file_read','coding_file_write',
+  'coding_receipt_verify','coding_search','coding_session_status','coding_stat',
+  'coding_task_approve','coding_task_cancel','coding_task_events','coding_task_run',
+  'coding_task_status','coding_task_submit','coding_task_verify','coding_text_replace','coding_tree'
+];
+const machineFsTools = [
+  'machine_fs_delete','machine_fs_edit_exact','machine_fs_list','machine_fs_mkdir',
+  'machine_fs_move','machine_fs_read','machine_fs_stat','machine_fs_write'
+];
+const expectedCatalog = [...baseTools, ...codingTools, ...machineFsTools].sort();
+const receipts = [];
+const remember = (operation, result) => {
+  if (result.status !== 'committed' || !/^[0-9a-f]{24}$/.test(result.receipt_id ?? '')) throw new Error(`${operation} missing committed receipt`);
+  receipts.push({ operation, receipt_id: result.receipt_id });
+  return result;
+};
+try {
+  await client.connect(transport);
+  const listed = await client.listTools();
+  const names = listed.tools.map(tool => tool.name).sort();
+  if (JSON.stringify(names) !== JSON.stringify(expectedCatalog)) throw new Error(`machine fs smoke catalog mismatch: ${JSON.stringify(names)}`);
+  for (const tool of listed.tools) {
+    if (tool.outputSchema?.type !== 'object' || tool.outputSchema?.additionalProperties !== false) throw new Error(`tool ${tool.name} missing strict output schema`);
+  }
+  const rootStat = structured(await client.callTool({ name:'machine_fs_stat', arguments:{ root_id:'core', path:'.', hash:false } }), 'machine_fs_stat(root)');
+  if (rootStat.status !== 'ok' || rootStat.kind !== 'directory') throw new Error('machine fs root stat malformed');
+  const made = remember('machine_fs_mkdir', structured(await client.callTool({
+    name:'machine_fs_mkdir', arguments:{ root_id:'core', path:'case' }
+  }), 'machine_fs_mkdir'));
+  const written = remember('machine_fs_write', structured(await client.callTool({
+    name:'machine_fs_write', arguments:{ root_id:'core', path:'case/a.txt', content:'alpha', encoding:'utf8', expected_sha256:'absent' }
+  }), 'machine_fs_write'));
+  if (written.sha256 !== sha256(Buffer.from('alpha'))) throw new Error('machine fs write digest mismatch');
+  const listedCase = structured(await client.callTool({
+    name:'machine_fs_list', arguments:{ root_id:'core', path:'case', cursor:null, limit:1, hash_files:true }
+  }), 'machine_fs_list');
+  if (listedCase.status !== 'ok' || listedCase.entries.length !== 1 || listedCase.entries[0].path !== 'case/a.txt') throw new Error('machine fs list malformed');
+  const read = structured(await client.callTool({
+    name:'machine_fs_read', arguments:{ root_id:'core', path:'case/a.txt', offset:0, max_bytes:5, hash_file:true }
+  }), 'machine_fs_read');
+  if (read.status !== 'ok' || Buffer.from(read.data_base64, 'base64').toString('utf8') !== 'alpha' || read.file_sha256 !== written.sha256) throw new Error('machine fs read malformed');
+  const edited = remember('machine_fs_edit_exact', structured(await client.callTool({
+    name:'machine_fs_edit_exact', arguments:{ root_id:'core', path:'case/a.txt', expected_sha256:written.sha256,
+      old_string:'alpha', new_string:'beta', expected_replacements:1 }
+  }), 'machine_fs_edit_exact'));
+  if (edited.sha256 !== sha256(Buffer.from('beta'))) throw new Error('machine fs edit digest mismatch');
+  const fileStat = structured(await client.callTool({
+    name:'machine_fs_stat', arguments:{ root_id:'core', path:'case/a.txt', hash:true }
+  }), 'machine_fs_stat(file)');
+  if (fileStat.status !== 'ok' || fileStat.sha256 !== edited.sha256 || !/^[0-9a-f]{64}$/.test(fileStat.identity_sha256 ?? '')) throw new Error('machine fs file stat malformed');
+  const moved = remember('machine_fs_move', structured(await client.callTool({
+    name:'machine_fs_move', arguments:{ root_id:'core', source_path:'case/a.txt', destination_path:'case/b.txt', expected_source_identity:fileStat.identity_sha256 }
+  }), 'machine_fs_move'));
+  if (moved.identity_sha256 !== fileStat.identity_sha256) throw new Error('machine fs move identity mismatch');
+  const deleted = remember('machine_fs_delete', structured(await client.callTool({
+    name:'machine_fs_delete', arguments:{ root_id:'core', path:'case/b.txt', expected_source_identity:moved.identity_sha256 }
+  }), 'machine_fs_delete'));
+  if (!/^[0-9a-f]{64}$/.test(deleted.recovery_key ?? '')) throw new Error('machine fs delete recovery key malformed');
+  for (const item of receipts) {
+    const verified = await verifyMachineFsReceiptFile({ policy, verifyKeyPath:keys.publicKeyPath, receiptId:item.receipt_id });
+    if (!verified.ok || verified.signature_valid !== true || verified.operation !== item.operation) throw new Error(`machine fs receipt verify failed for ${item.operation}`);
+  }
+  console.log(JSON.stringify({ status:'passed', protocol_revision:'2026-07-28', tool_count:names.length,
+    root_id:'core', mutation_receipts:receipts.length, delete_recovery_key:deleted.recovery_key,
+    policy_sha256:policy.policy_sha256, strict_output_schemas:true, signature_valid:true }, null, 2));
+} catch (error) {
+  const stderr = Buffer.concat(stderrChunks).toString('utf8').trim();
+  if (stderr) console.error(`server stderr:\n${stderr}`);
+  console.error(error instanceof Error ? error.stack : String(error));
+  process.exitCode = 1;
+} finally {
+  await client.close().catch(() => {});
+  await rm(scratch, { recursive:true, force:true }).catch(() => {});
+}

package/src/machine-fs.mjs

@@ -0,0 +1,475 @@
+import { createHash, randomBytes, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, mkdir as fsMkdir, open, readFile, readdir, realpath, rename, rm, rmdir } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical-json.mjs';
+import { assertCodingArmed } from './coding-plane.mjs';
+import { isInside, validatePortableRelativePath } from './path-policy.mjs';
+import { decodeUtf8Strict } from './text-policy.mjs';
+import { loadPrivateSigningKey, loadPublicVerifyKey } from './trust.mjs';
+
+export const MACHINE_FS_RECEIPT_SCHEMA = 'deadbyte.machine-fs-receipt.v1';
+const RECEIPT_DOMAIN = Buffer.from('DEADBYTE-MACHINE-FS-RECEIPT-V1\0', 'utf8');
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const RECEIPT_ID_RE = /^[0-9a-f]{24}$/;
+const MAX_LIST_LIMIT = 1000;
+const MAX_DIRECTORY_IDENTITY_ENTRIES = 4096;
+
+const sha256Bytes = bytes => createHash('sha256').update(bytes).digest('hex');
+const sha256Object = value => sha256Bytes(Buffer.from(canonicalJson(value), 'utf8'));
+const nowUtc = () => new Date().toISOString();
+async function sha256File(file) {
+  const hash = createHash('sha256');
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(file);
+    stream.on('data', chunk => hash.update(chunk));
+    stream.once('error', reject);
+    stream.once('end', resolve);
+  });
+  return hash.digest('hex');
+}
+
+function getRoot(policy, rootId, permission) {
+  const root = policy.roots[rootId];
+  if (!root) throw new Error(`machine fs root '${rootId}' is not allowed`);
+  if (root[permission] !== true) throw new Error(`machine fs root '${rootId}' does not allow ${permission}`);
+  return root;
+}
+
+function normalizeRelative(relativePath, allowDot = false) {
+  if (allowDot && relativePath === '.') return '.';
+  validatePortableRelativePath(relativePath);
+  return relativePath.replaceAll('\\', '/');
+}
+
+function assertNotDenied(root, relativePath) {
+  const normalized = relativePath.replaceAll('\\', '/').replace(/^\.\//, '');
+  for (const deniedRaw of root.deny_paths ?? []) {
+    const denied = deniedRaw.replaceAll('\\', '/').replace(/^\.\//, '').replace(/\/$/, '');
+    if (normalized === denied || normalized.startsWith(`${denied}/`)) throw new Error(`machine fs path '${relativePath}' is denied by policy`);
+  }
+}
+async function assertNoReparse(rootPath, target, allowMissingLeaf = false) {
+  const relative = path.relative(rootPath, target);
+  if (relative === '') return;
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('machine fs path escapes allowed root');
+  const parts = relative.split(path.sep).filter(Boolean);
+  let cursor = rootPath;
+  for (let i = 0; i < parts.length; i += 1) {
+    cursor = path.join(cursor, parts[i]);
+    try {
+      const info = await lstat(cursor);
+      if (info.isSymbolicLink()) throw new Error(`machine fs reparse point denied at '${parts.slice(0, i + 1).join('/')}'`);
+    } catch (error) {
+      if (allowMissingLeaf && i === parts.length - 1 && error?.code === 'ENOENT') return;
+      throw error;
+    }
+  }
+}
+
+async function resolveExisting(policy, grant, rootId, relativePath, permission, allowDot = false) {
+  const normalized = normalizeRelative(relativePath, allowDot);
+  if (!grant.root_ids.includes(rootId)) throw new Error(`machine fs root '${rootId}' is outside active grant`);
+  const root = getRoot(policy, rootId, permission);
+  if (normalized !== '.') assertNotDenied(root, normalized);
+  const lexical = normalized === '.' ? root.real_path : path.resolve(root.real_path, normalized);
+  if (!isInside(root.real_path, lexical) && lexical !== root.real_path) throw new Error('machine fs path escapes allowed root');
+  await assertNoReparse(root.real_path, lexical, false);
+  const resolved = await realpath(lexical);
+  if (!isInside(root.real_path, resolved) && resolved !== root.real_path) throw new Error('machine fs path resolves outside allowed root');
+  return { root, lexical, resolved, relative: normalized };
+}
+async function resolveTarget(policy, grant, rootId, relativePath, permission) {
+  const normalized = normalizeRelative(relativePath, false);
+  if (!grant.root_ids.includes(rootId)) throw new Error(`machine fs root '${rootId}' is outside active grant`);
+  const root = getRoot(policy, rootId, permission);
+  assertNotDenied(root, normalized);
+  const lexical = path.resolve(root.real_path, normalized);
+  if (!isInside(root.real_path, lexical)) throw new Error('machine fs target escapes allowed root');
+  const parent = path.dirname(lexical);
+  await assertNoReparse(root.real_path, parent, false);
+  const realParent = await realpath(parent);
+  if (!isInside(root.real_path, realParent) && realParent !== root.real_path) throw new Error('machine fs parent resolves outside allowed root');
+  const parentInfo = await lstat(realParent);
+  if (!parentInfo.isDirectory()) throw new Error('machine fs parent must be a directory');
+  await assertNoReparse(root.real_path, lexical, true);
+  return { root, lexical, relative: normalized };
+}
+
+function kindOf(info) {
+  if (info.isFile()) return 'file';
+  if (info.isDirectory()) return 'directory';
+  if (info.isSymbolicLink()) return 'reparse';
+  return 'other';
+}
+
+async function regularState(file) {
+  try {
+    const info = await lstat(file);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error('machine fs write target must be a regular file');
+    return { exists: true, sha256: await sha256File(file), bytes: info.size };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, sha256: null, bytes: 0 };
+    throw error;
+  }
+}
+function checkExpectedFile(state, expected) {
+  if (expected === 'absent') {
+    if (state.exists) throw new Error(`machine fs precondition mismatch: expected absent, found ${state.sha256}`);
+    return;
+  }
+  if (typeof expected !== 'string' || !SHA256_RE.test(expected)) throw new Error('expected_sha256 must be absent or lowercase SHA-256');
+  if (!state.exists) throw new Error('machine fs precondition mismatch: expected existing file, found absent');
+  if (state.sha256 !== expected) throw new Error(`machine fs precondition mismatch: expected ${expected}, found ${state.sha256}`);
+}
+
+function decodeContent(content, encoding) {
+  if (typeof content !== 'string') throw new Error('content must be a string');
+  if (encoding === 'utf8') return Buffer.from(content, 'utf8');
+  if (encoding === 'base64') {
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(content)) throw new Error('invalid base64 content');
+    return Buffer.from(content, 'base64');
+  }
+  throw new Error('encoding must be utf8 or base64');
+}
+
+async function objectIdentity(target, budget = { remaining: MAX_DIRECTORY_IDENTITY_ENTRIES }) {
+  if (budget.remaining <= 0) throw new Error('machine fs object identity entry limit exceeded');
+  budget.remaining -= 1;
+  const info = await lstat(target);
+  if (info.isSymbolicLink()) throw new Error('machine fs reparse target denied');
+  const kind = kindOf(info);
+  if (!['file', 'directory'].includes(kind)) throw new Error(`machine fs unsupported object kind '${kind}'`);
+  if (kind === 'file') {
+    const core = { kind, bytes: info.size, content_sha256: await sha256File(target) };
+    return { ...core, identity_sha256: sha256Object(core) };
+  }
+  const children = await readdir(target, { withFileTypes: true });
+  children.sort((a, b) => a.name.localeCompare(b.name));
+  const entries = [];
+  for (const child of children) {
+    if (child.isSymbolicLink()) throw new Error(`machine fs reparse point denied in identity: '${child.name}'`);
+    const childIdentity = await objectIdentity(path.join(target, child.name), budget);
+    entries.push({ name: child.name, kind: childIdentity.kind, identity_sha256: childIdentity.identity_sha256 });
+  }
+  const core = { kind, entries };
+  return { ...core, identity_sha256: sha256Object(core) };
+}
+
+function decodeCursor(cursor) {
+  if (cursor === null || cursor === undefined) return null;
+  if (typeof cursor !== 'string' || cursor.length < 1 || cursor.length > 2048) throw new Error('machine fs cursor invalid');
+  let decoded;
+  try { decoded = Buffer.from(cursor, 'base64url').toString('utf8'); }
+  catch { throw new Error('machine fs cursor invalid'); }
+  if (!decoded || Buffer.from(decoded, 'utf8').toString('base64url') !== cursor) throw new Error('machine fs cursor invalid');
+  return decoded;
+}
+
+function encodeCursor(name) { return Buffer.from(name, 'utf8').toString('base64url'); }
+
+async function signReceipt(policy, signingKeyPath, grant, operation, requestSha256, body) {
+  await fsMkdir(path.join(policy.evidence_dir, 'machine-fs'), { recursive: true });
+  const receiptId = randomBytes(12).toString('hex');
+  const core = {
+    schema: MACHINE_FS_RECEIPT_SCHEMA, receipt_id: receiptId,
+    policy_sha256: policy.policy_sha256, grant_instance_nonce: grant.instance_nonce,
+    operation, request_sha256: requestSha256, ...body
+  };
+  const receiptSha256 = sha256Object(core);
+  const signedBody = { ...core, receipt_sha256: receiptSha256 };
+  const signing = await loadPrivateSigningKey(signingKeyPath);
+  const bytes = Buffer.from(canonicalJson(signedBody), 'utf8');
+  const signature = cryptoSign(null, Buffer.concat([RECEIPT_DOMAIN, bytes]), signing.privateKey).toString('base64');
+  const receipt = {
+    ...signedBody,
+    attestation: { algorithm: 'ed25519', key_id: signing.keyId, signature_base64: signature }
+  };
+  const target = path.join(policy.evidence_dir, 'machine-fs', `${receiptId}.json`);
+  const handle = await open(target, 'wx', 0o600);
+  try { await handle.writeFile(`${canonicalJson(receipt)}\n`); await handle.sync(); }
+  finally { await handle.close(); }
+  return { receipt, receipt_path: target };
+}
+
+export async function verifyMachineFsReceiptFile({ policy, verifyKeyPath, receiptId }) {
+  if (!RECEIPT_ID_RE.test(receiptId ?? '')) return { ok: false, reason: 'invalid receipt_id' };
+  const file = path.join(policy.evidence_dir, 'machine-fs', `${receiptId}.json`);
+  let receipt;
+  try { receipt = JSON.parse(decodeUtf8Strict(await readFile(file))); }
+  catch { return { ok: false, reason: 'receipt missing or unreadable' }; }
+  if (receipt?.schema !== MACHINE_FS_RECEIPT_SCHEMA || receipt.receipt_id !== receiptId || receipt.policy_sha256 !== policy.policy_sha256) {
+    return { ok: false, reason: 'machine fs receipt identity mismatch' };
+  }
+  const { attestation, receipt_sha256: claimed, ...body } = receipt;
+  if (!SHA256_RE.test(claimed ?? '') || sha256Object(body) !== claimed) return { ok: false, reason: 'machine fs receipt hash mismatch' };
+  const verifyKey = await loadPublicVerifyKey(verifyKeyPath);
+  if (attestation?.algorithm !== 'ed25519' || attestation?.key_id !== verifyKey.keyId || typeof attestation?.signature_base64 !== 'string') {
+    return { ok: false, reason: 'machine fs receipt attestation mismatch' };
+  }
+  const signature = Buffer.from(attestation.signature_base64, 'base64');
+  const signedBytes = Buffer.from(canonicalJson({ ...body, receipt_sha256: claimed }), 'utf8');
+  const valid = signature.length === 64 && cryptoVerify(null, Buffer.concat([RECEIPT_DOMAIN, signedBytes]), verifyKey.publicKey, signature);
+  if (!valid) return { ok: false, reason: 'machine fs receipt signature mismatch' };
+  return { ok: true, signature_valid: true, receipt_sha256: claimed, operation: receipt.operation, request_sha256: receipt.request_sha256 };
+}
+
+function requestSha(operation, args) {
+  return sha256Object({ schema: 'deadbyte.machine-fs-request.v1', operation, args });
+}
+
+async function atomicWrite(target, bytes, expectedSha256) {
+  const before = await regularState(target);
+  checkExpectedFile(before, expectedSha256);
+  const temp = path.join(path.dirname(target), `.${path.basename(target)}.deadbyte-machine-fs-${process.pid}-${randomBytes(8).toString('hex')}.tmp`);
+  let handle;
+  try {
+    handle = await open(temp, 'wx', 0o600);
+    await handle.writeFile(bytes);
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    checkExpectedFile(await regularState(target), expectedSha256);
+    await rename(temp, target);
+  } catch (error) {
+    if (handle) await handle.close().catch(() => {});
+    await rm(temp, { force: true }).catch(() => {});
+    throw error;
+  }
+  const after = await regularState(target);
+  const expectedAfter = sha256Bytes(bytes);
+  if (!after.exists || after.sha256 !== expectedAfter) throw new Error('machine fs post-commit hash mismatch');
+  return { before, after };
+}
+
+export function createMachineFsRuntime({ policy, signingKeyPath, verifyKeyPath }) {
+  if (!policy) throw new Error('machine fs runtime requires coding policy');
+  if (!signingKeyPath || !verifyKeyPath) throw new Error('machine fs runtime requires trust key paths');
+
+  async function statPath({ rootId, relativePath = '.', hash = false }) {
+    const grant = await assertCodingArmed(policy, rootId);
+    const found = await resolveExisting(policy, grant, rootId, relativePath, 'read', true);
+    const info = await lstat(found.resolved);
+    const kind = kindOf(info);
+    if (kind === 'reparse') throw new Error('machine fs reparse target denied');
+    const identity = await objectIdentity(found.resolved);
+    return {
+      status: 'ok', root_id: rootId, path: found.relative, kind,
+      bytes: kind === 'file' ? info.size : 0,
+      mtime_utc: info.mtime.toISOString(), ctime_utc: info.ctime.toISOString(),
+      birthtime_utc: info.birthtime.toISOString(),
+      sha256: hash && kind === 'file' ? identity.content_sha256 : null,
+      identity_sha256: identity.identity_sha256
+    };
+  }
+  async function listPage({ rootId, relativePath = '.', cursor = null, limit = 100, hashFiles = false }) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIST_LIMIT) throw new Error(`machine fs list limit must be in [1, ${MAX_LIST_LIMIT}]`);
+    const grant = await assertCodingArmed(policy, rootId);
+    const found = await resolveExisting(policy, grant, rootId, relativePath, 'read', true);
+    const info = await lstat(found.resolved);
+    if (!info.isDirectory()) throw new Error('machine fs list path must be a directory');
+    const afterName = decodeCursor(cursor);
+    const children = await readdir(found.resolved, { withFileTypes: true });
+    children.sort((a, b) => a.name.localeCompare(b.name));
+    const filtered = children.filter(child => afterName === null || child.name.localeCompare(afterName) > 0);
+    const selected = filtered.slice(0, limit);
+    const entries = [];
+    for (const child of selected) {
+      const rel = found.relative === '.' ? child.name : `${found.relative}/${child.name}`;
+      if (child.isSymbolicLink()) {
+        entries.push({ path: rel, kind: 'reparse', bytes: 0, mtime_utc: null, sha256: null });
+        continue;
+      }
+      const childPath = path.join(found.resolved, child.name);
+      const childInfo = await lstat(childPath);
+      const kind = kindOf(childInfo);
+      const digest = hashFiles && kind === 'file' ? await sha256File(childPath) : null;
+      entries.push({ path: rel, kind, bytes: kind === 'file' ? childInfo.size : 0, mtime_utc: childInfo.mtime.toISOString(), sha256: digest });
+    }
+    const nextCursor = filtered.length > selected.length && selected.length ? encodeCursor(selected.at(-1).name) : null;
+    return { status: 'ok', root_id: rootId, path: found.relative, entries, next_cursor: nextCursor };
+  }
+  async function readRange({ rootId, relativePath, offset = 0, maxBytes = 65536, hashFile = false }) {
+    if (!Number.isInteger(offset) || offset < 0) throw new Error('machine fs read offset must be nonnegative integer');
+    if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > policy.max_read_bytes) throw new Error(`machine fs max_bytes must be in [1, ${policy.max_read_bytes}]`);
+    const grant = await assertCodingArmed(policy, rootId);
+    const found = await resolveExisting(policy, grant, rootId, relativePath, 'read', false);
+    const info = await lstat(found.resolved);
+    if (!info.isFile()) throw new Error('machine fs read target must be a regular file');
+    if (offset > info.size) throw new Error('machine fs read offset exceeds file size');
+    const handle = await open(found.resolved, 'r');
+    const length = Math.min(maxBytes, info.size - offset);
+    const buffer = Buffer.alloc(length);
+    try { if (length) await handle.read(buffer, 0, length, offset); }
+    finally { await handle.close(); }
+    const fileSha = hashFile ? await sha256File(found.resolved) : null;
+    return {
+      status: 'ok', root_id: rootId, path: found.relative,
+      offset, next_offset: offset + length, file_size: info.size,
+      eof: offset + length >= info.size, data_base64: buffer.toString('base64'),
+      data_sha256: sha256Bytes(buffer), file_sha256: fileSha
+    };
+  }
+
+  async function writePath({ rootId, relativePath, content, encoding = 'utf8', expectedSha256 }) {
+    const grant = await assertCodingArmed(policy, rootId);
+    const target = await resolveTarget(policy, grant, rootId, relativePath, 'write');
+    const bytes = decodeContent(content, encoding);
+    if (bytes.length > policy.max_write_bytes) throw new Error(`machine fs write exceeds ${policy.max_write_bytes} byte limit`);
+    const request = requestSha('machine_fs_write', {
+      root_id: rootId, path: target.relative, encoding, expected_sha256: expectedSha256,
+      content_sha256: sha256Bytes(bytes)
+    });
+    const started = nowUtc();
+    const { before, after } = await atomicWrite(target.lexical, bytes, expectedSha256);
+    const signed = await signReceipt(policy, signingKeyPath, grant, 'machine_fs_write', request, {
+      root_id: rootId, path: target.relative, started_at_utc: started, completed_at_utc: nowUtc(),
+      before_sha256: before.sha256, after_sha256: after.sha256, bytes: after.bytes
+    });
+    return {
+      status: 'committed', root_id: rootId, path: target.relative,
+      previous_sha256: before.sha256, sha256: after.sha256, bytes: after.bytes,
+      created: !before.exists, receipt_id: signed.receipt.receipt_id,
+      receipt_sha256: signed.receipt.receipt_sha256, request_sha256: request
+    };
+  }
+
+  async function editExact({ rootId, relativePath, expectedSha256, oldString, newString, expectedReplacements = 1 }) {
+    if (!SHA256_RE.test(expectedSha256 ?? '')) throw new Error('machine fs edit expected_sha256 must be lowercase SHA-256');
+    if (typeof oldString !== 'string' || oldString.length < 1 || oldString.length > 262144) throw new Error('machine fs old_string invalid');
+    if (typeof newString !== 'string' || newString.length > 524288) throw new Error('machine fs new_string invalid');
+    if (!Number.isInteger(expectedReplacements) || expectedReplacements < 1 || expectedReplacements > 64) throw new Error('machine fs expected_replacements must be in [1, 64]');
+    const grant = await assertCodingArmed(policy, rootId);
+    const found = await resolveExisting(policy, grant, rootId, relativePath, 'write', false);
+    const beforeBytes = await readFile(found.resolved);
+    if (beforeBytes.length > policy.max_write_bytes) throw new Error(`machine fs edit exceeds ${policy.max_write_bytes} byte limit`);
+    const beforeSha = sha256Bytes(beforeBytes);
+    if (beforeSha !== expectedSha256) throw new Error(`machine fs precondition mismatch: expected ${expectedSha256}, found ${beforeSha}`);
+    const text = decodeUtf8Strict(beforeBytes);
+    const count = text.split(oldString).length - 1;
+    if (count !== expectedReplacements) throw new Error(`machine fs replace count mismatch: expected ${expectedReplacements}, found ${count}`);
+    const next = text.split(oldString).join(newString);
+    const nextBytes = Buffer.from(next, 'utf8');
+    if (nextBytes.length > policy.max_write_bytes) throw new Error(`machine fs edit output exceeds ${policy.max_write_bytes} byte limit`);
+    const request = requestSha('machine_fs_edit_exact', {
+      root_id: rootId, path: found.relative, expected_sha256: expectedSha256,
+      expected_replacements: expectedReplacements,
+      old_sha256: sha256Bytes(Buffer.from(oldString, 'utf8')), new_sha256: sha256Bytes(Buffer.from(newString, 'utf8'))
+    });
+    const started = nowUtc();
+    const { after } = await atomicWrite(found.lexical, nextBytes, expectedSha256);
+    const signed = await signReceipt(policy, signingKeyPath, grant, 'machine_fs_edit_exact', request, {
+      root_id: rootId, path: found.relative, started_at_utc: started, completed_at_utc: nowUtc(),
+      before_sha256: beforeSha, after_sha256: after.sha256, replacements: count, bytes: after.bytes
+    });
+    return {
+      status: 'committed', root_id: rootId, path: found.relative, previous_sha256: beforeSha,
+      sha256: after.sha256, bytes: after.bytes, replacements: count,
+      receipt_id: signed.receipt.receipt_id, receipt_sha256: signed.receipt.receipt_sha256, request_sha256: request
+    };
+  }
+  async function mkdirPath({ rootId, relativePath }) {
+    const grant = await assertCodingArmed(policy, rootId);
+    const target = await resolveTarget(policy, grant, rootId, relativePath, 'write');
+    try { await lstat(target.lexical); throw new Error('machine fs mkdir precondition mismatch: expected absent'); }
+    catch (error) { if (error?.code !== 'ENOENT') throw error; }
+    const request = requestSha('machine_fs_mkdir', { root_id: rootId, path: target.relative, expected: 'absent' });
+    const started = nowUtc();
+    await fsMkdir(target.lexical, { recursive: false });
+    try {
+      const identity = await objectIdentity(target.lexical);
+      if (identity.kind !== 'directory') throw new Error('machine fs mkdir post-commit type mismatch');
+      const signed = await signReceipt(policy, signingKeyPath, grant, 'machine_fs_mkdir', request, {
+        root_id: rootId, path: target.relative, started_at_utc: started, completed_at_utc: nowUtc(),
+        before_identity_sha256: null, after_identity_sha256: identity.identity_sha256
+      });
+      return {
+        status: 'committed', root_id: rootId, path: target.relative, identity_sha256: identity.identity_sha256,
+        receipt_id: signed.receipt.receipt_id, receipt_sha256: signed.receipt.receipt_sha256, request_sha256: request
+      };
+    } catch (error) {
+      await rmdir(target.lexical).catch(() => {});
+      throw error;
+    }
+  }
+  async function movePath({ rootId, sourcePath, destinationPath, expectedSourceIdentity }) {
+    if (!SHA256_RE.test(expectedSourceIdentity ?? '')) throw new Error('machine fs expected_source_identity must be lowercase SHA-256');
+    const grant = await assertCodingArmed(policy, rootId);
+    const source = await resolveExisting(policy, grant, rootId, sourcePath, 'write', false);
+    const destination = await resolveTarget(policy, grant, rootId, destinationPath, 'write');
+    try { await lstat(destination.lexical); throw new Error('machine fs move destination precondition mismatch: expected absent'); }
+    catch (error) { if (error?.code !== 'ENOENT') throw error; }
+    const before = await objectIdentity(source.resolved);
+    if (before.identity_sha256 !== expectedSourceIdentity) throw new Error(`machine fs source identity mismatch: expected ${expectedSourceIdentity}, found ${before.identity_sha256}`);
+    const request = requestSha('machine_fs_move', {
+      root_id: rootId, source_path: source.relative, destination_path: destination.relative,
+      expected_source_identity: expectedSourceIdentity, destination_expected: 'absent'
+    });
+    const started = nowUtc();
+    const race = await objectIdentity(source.resolved);
+    if (race.identity_sha256 !== expectedSourceIdentity) throw new Error(`machine fs source identity mismatch before commit: expected ${expectedSourceIdentity}, found ${race.identity_sha256}`);
+    await rename(source.lexical, destination.lexical);
+    try {
+      const after = await objectIdentity(destination.lexical);
+      if (after.identity_sha256 !== expectedSourceIdentity) throw new Error('machine fs move post-commit identity mismatch');
+      const signed = await signReceipt(policy, signingKeyPath, grant, 'machine_fs_move', request, {
+        root_id: rootId, source_path: source.relative, destination_path: destination.relative,
+        started_at_utc: started, completed_at_utc: nowUtc(), source_identity_sha256: expectedSourceIdentity
+      });
+      return {
+        status: 'committed', root_id: rootId, source_path: source.relative, destination_path: destination.relative,
+        identity_sha256: expectedSourceIdentity, receipt_id: signed.receipt.receipt_id,
+        receipt_sha256: signed.receipt.receipt_sha256, request_sha256: request
+      };
+    } catch (error) {
+      try { await rename(destination.lexical, source.lexical); }
+      catch (restoreError) { throw new Error(`machine fs move rollback failed: ${String(error)}; restore=${String(restoreError)}`); }
+      throw error;
+    }
+  }
+
+  async function deletePath({ rootId, relativePath, expectedSourceIdentity }) {
+    if (!SHA256_RE.test(expectedSourceIdentity ?? '')) throw new Error('machine fs expected_source_identity must be lowercase SHA-256');
+    const grant = await assertCodingArmed(policy, rootId);
+    const source = await resolveExisting(policy, grant, rootId, relativePath, 'write', false);
+    const before = await objectIdentity(source.resolved);
+    if (before.identity_sha256 !== expectedSourceIdentity) throw new Error(`machine fs source identity mismatch: expected ${expectedSourceIdentity}, found ${before.identity_sha256}`);
+    const recoveryRoot = path.join(source.root.real_path, '.deadbyte-machine-fs-recovery');
+    await fsMkdir(recoveryRoot, { recursive: true });
+    const recoveryKey = sha256Object({ source_path: source.relative, identity_sha256: expectedSourceIdentity });
+    const recoveryTarget = path.join(recoveryRoot, recoveryKey);
+    try { await lstat(recoveryTarget); throw new Error('machine fs recovery collision'); }
+    catch (error) { if (error?.code !== 'ENOENT') throw error; }
+    const request = requestSha('machine_fs_delete', { root_id: rootId, path: source.relative, expected_source_identity: expectedSourceIdentity });
+    const started = nowUtc();
+    await rename(source.lexical, recoveryTarget);
+    try {
+      const recovered = await objectIdentity(recoveryTarget);
+      if (recovered.identity_sha256 !== expectedSourceIdentity) throw new Error('machine fs delete recovery identity mismatch');
+      const signed = await signReceipt(policy, signingKeyPath, grant, 'machine_fs_delete', request, {
+        root_id: rootId, path: source.relative, started_at_utc: started, completed_at_utc: nowUtc(),
+        source_identity_sha256: expectedSourceIdentity, recovery_key: recoveryKey
+      });
+      return { status: 'committed', root_id: rootId, path: source.relative, identity_sha256: expectedSourceIdentity,
+        recovery_key: recoveryKey, receipt_id: signed.receipt.receipt_id,
+        receipt_sha256: signed.receipt.receipt_sha256, request_sha256: request };
+    } catch (error) {
+      try { await rename(recoveryTarget, source.lexical); }
+      catch (restoreError) { throw new Error(`machine fs delete rollback failed: ${String(error)}; restore=${String(restoreError)}`); }
+      throw error;
+    }
+  }
+
+  return Object.freeze({
+    policy,
+    stat: statPath,
+    list: listPage,
+    read: readRange,
+    write: writePath,
+    editExact,
+    move: movePath,
+    mkdir: mkdirPath,
+    delete: deletePath,
+    verifyReceipt: receiptId => verifyMachineFsReceiptFile({ policy, verifyKeyPath, receiptId })
+  });
+}