deadbyte-mcp 0.8.7

package/src/native-diff.mjs

@@ -0,0 +1,403 @@
+import { createHash, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { access, mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical-json.mjs';
+import { validatePortableRelativePath } from './path-policy.mjs';
+import { loadPrivateSigningKey, loadPublicVerifyKey } from './trust.mjs';
+import { assertAutonomousArmed } from './autonomous-policy.mjs';
+
+export const NATIVE_DIFF_SCHEMA = 'deadbyte.native-diff.v1';
+export const NATIVE_DIFF_PREIMAGE_SCHEMA = 'deadbyte.native-diff-preimage.v1';
+export const NATIVE_DIFF_EVENT_SCHEMA = 'deadbyte.native-diff-event.v1';
+export const NATIVE_DIFF_RECEIPT_SCHEMA = 'deadbyte.native-diff-receipt.v1';
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const DIFF_ID_RE = /^[0-9a-f]{64}$/;
+const ZERO_HASH = '0'.repeat(64);
+const DIFF_DOMAIN = Buffer.from('DEADBYTE-NATIVE-DIFF-V1\0');
+const PREIMAGE_DOMAIN = Buffer.from('DEADBYTE-NATIVE-DIFF-PREIMAGE-V1\0');
+const EVENT_DOMAIN = Buffer.from('DEADBYTE-NATIVE-DIFF-EVENT-V1\0');
+const RECEIPT_DOMAIN = Buffer.from('DEADBYTE-NATIVE-DIFF-RECEIPT-V1\0');
+const sha256Bytes = bytes => createHash('sha256').update(bytes).digest('hex');
+const sha256Object = value => sha256Bytes(Buffer.from(canonicalJson(value), 'utf8'));
+const exists = file => access(file).then(() => true, () => false);
+function signEnvelope(key, domain, body) {
+  const bytes = Buffer.from(canonicalJson(body), 'utf8');
+  const sig = cryptoSign(null, Buffer.concat([domain, bytes]), key.privateKey);
+  return { ...body, attestation:{ algorithm:'ed25519', key_id:key.keyId, signature_base64:sig.toString('base64') } };
+}
+function verifyEnvelope(key, domain, envelope, label) {
+  const { attestation, ...body } = envelope ?? {};
+  if (attestation?.algorithm !== 'ed25519' || attestation?.key_id !== key.keyId || typeof attestation?.signature_base64 !== 'string') {
+    throw new Error(`${label} signature metadata mismatch`);
+  }
+  const sig = Buffer.from(attestation.signature_base64, 'base64');
+  if (sig.length !== 64 || sig.toString('base64') !== attestation.signature_base64) throw new Error(`${label} signature encoding mismatch`);
+  const bytes = Buffer.from(canonicalJson(body), 'utf8');
+  if (!cryptoVerify(null, Buffer.concat([domain, bytes]), key.publicKey, sig)) throw new Error(`${label} signature verification failed`);
+  return body;
+}
+function receiptIdFor(diffId, index, phase) {
+  return sha256Object({ schema:'deadbyte.native-diff-coding-receipt-id.v1', diff_id:diffId, index, phase }).slice(0, 24);
+}
+function decodeWriteContent(content, encoding) {
+  if (typeof content !== 'string') throw new Error('native diff write content must be string');
+  if (encoding === 'utf8') return Buffer.from(content, 'utf8');
+  if (encoding === 'base64' && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(content)) return Buffer.from(content, 'base64');
+  throw new Error('native diff write encoding invalid');
+}
+function normalizeRawOperations(operations, policy) {
+  if (!Array.isArray(operations) || operations.length < 1 || operations.length > policy.limits.max_files_per_diff) {
+    throw new Error(`native diff operations must contain 1-${policy.limits.max_files_per_diff} entries`);
+  }
+  const seen = new Set(); let payloadBytes = 0;
+  const normalized = operations.map((raw, index) => {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error(`native diff operation ${index} malformed`);
+    validatePortableRelativePath(raw.path);
+    const portable = raw.path.replaceAll('\\','/');
+    if (seen.has(portable.toLowerCase())) throw new Error(`native diff path repeated '${portable}'`);
+    seen.add(portable.toLowerCase());
+    if (raw.kind === 'write') {
+      const encoding = raw.encoding ?? 'utf8';
+      const bytes = decodeWriteContent(raw.content, encoding);
+      payloadBytes += bytes.length;
+      if (raw.expected_sha256 !== 'absent' && !SHA256_RE.test(raw.expected_sha256 ?? '')) throw new Error('native diff write expected_sha256 invalid');
+      return { kind:'write', path:portable, content:raw.content, encoding, expected_sha256:raw.expected_sha256, content_sha256:sha256Bytes(bytes) };
+    }
+    if (raw.kind === 'replace') {
+      if (!SHA256_RE.test(raw.expected_sha256 ?? '')) throw new Error('native diff replace expected_sha256 invalid');
+      if (typeof raw.old_string !== 'string' || raw.old_string.length < 1 || raw.old_string.length > 262144) throw new Error('native diff old_string invalid');
+      if (typeof raw.new_string !== 'string' || raw.new_string.length > 524288) throw new Error('native diff new_string invalid');
+      const count = raw.expected_replacements ?? 1;
+      if (!Number.isInteger(count) || count < 1 || count > 64) throw new Error('native diff expected_replacements invalid');
+      payloadBytes += Buffer.byteLength(raw.old_string) + Buffer.byteLength(raw.new_string);
+      return { kind:'replace', path:portable, expected_sha256:raw.expected_sha256,
+        old_string:raw.old_string, new_string:raw.new_string, expected_replacements:count,
+        old_sha256:sha256Bytes(Buffer.from(raw.old_string)), new_sha256:sha256Bytes(Buffer.from(raw.new_string)) };
+    }
+    if (raw.kind === 'delete') {
+      if (!SHA256_RE.test(raw.expected_sha256 ?? '')) throw new Error('native diff delete expected_sha256 invalid');
+      return { kind:'delete', path:portable, expected_sha256:raw.expected_sha256 };
+    }
+    throw new Error(`native diff operation ${index} kind invalid`);
+  });
+  if (payloadBytes > policy.limits.max_diff_bytes) throw new Error(`native diff payload exceeds ${policy.limits.max_diff_bytes} bytes`);
+  return { normalized, payloadBytes };
+}
+function diffContext(policy, diffId) {
+  if (!DIFF_ID_RE.test(diffId ?? '')) throw new Error('invalid native diff_id');
+  const dir = path.join(policy.evidence_dir, 'native-diffs', diffId);
+  return { dir, diffPath:path.join(dir,'diff.json'), preimagePath:path.join(dir,'preimage.json'),
+    eventsDir:path.join(dir,'events'), receiptPath:path.join(dir,'apply-receipt.json') };
+}
+async function readEnvelope(file, key, domain, label) {
+  const parsed = JSON.parse(await readFile(file, 'utf8'));
+  verifyEnvelope(key, domain, parsed, label);
+  return parsed;
+}
+async function writeExclusive(file, value) {
+  await writeFile(file, `${canonicalJson(value)}\n`, { flag:'wx' });
+}
+export function createNativeDiffRuntime({ policy, codingRuntime, signingKeyPath, verifyKeyPath }) {
+  if (!policy || !codingRuntime?.policy) throw new Error('native diff runtime requires autonomous and coding policy');
+  if (!signingKeyPath || !verifyKeyPath) throw new Error('native diff runtime requires trust keys');
+
+  async function materializeOperations(rootId, rawOperations) {
+    if (!policy.root_ids.includes(rootId)) throw new Error(`native diff root '${rootId}' is not allowed`);
+    await assertAutonomousArmed(policy, rootId);
+    const { normalized, payloadBytes } = normalizeRawOperations(rawOperations, policy);
+    const operations = [];
+    for (const op of normalized) {
+      const current = await codingRuntime.fileState({ rootId, relativePath:op.path });
+      if (op.expected_sha256 === 'absent') {
+        if (current.exists) throw new Error(`native diff precondition '${op.path}' expected absent, found ${current.sha256}`);
+      } else if (!current.exists || current.sha256 !== op.expected_sha256) {
+        throw new Error(`native diff precondition '${op.path}' mismatch`);
+      }
+      if (op.kind === 'write') {
+        operations.push({ ...op, before_sha256:current.sha256, after_sha256:op.content_sha256 });
+      } else if (op.kind === 'delete') {
+        operations.push({ ...op, before_sha256:current.sha256, after_sha256:null });
+      } else {
+        const read = await codingRuntime.fileRead({ rootId, relativePath:op.path, encoding:'utf8' });
+        const count = read.content.split(op.old_string).length - 1;
+        if (count !== op.expected_replacements) throw new Error(`native diff replace '${op.path}' expected ${op.expected_replacements} matches, found ${count}`);
+        const next = read.content.split(op.old_string).join(op.new_string);
+        operations.push({ ...op, before_sha256:current.sha256, after_sha256:sha256Bytes(Buffer.from(next,'utf8')) });
+      }
+    }
+    return { operations, payloadBytes };
+  }
+
+  async function preview({ rootId, operations:rawOperations, title = '', applicationScope = null }) {
+    if (typeof title !== 'string' || title.length > 160) throw new Error('native diff title must be <=160 characters');
+    if (applicationScope !== null && !SHA256_RE.test(applicationScope)) throw new Error('native diff application_scope must be SHA-256 or null');
+    const { operations, payloadBytes } = await materializeOperations(rootId, rawOperations);
+    const identity = { schema:NATIVE_DIFF_SCHEMA, policy_sha256:policy.policy_sha256,
+      coding_policy_sha256:policy.coding_policy_sha256, root_id:rootId, title, operations,
+      ...(applicationScope === null ? {} : { application_scope:applicationScope }) };
+    const diffId = sha256Object(identity);
+    const ctx = diffContext(policy, diffId);
+    const signingKey = await loadPrivateSigningKey(signingKeyPath);
+    const envelope = signEnvelope(signingKey, DIFF_DOMAIN, { ...identity, diff_id:diffId, created_at_utc:new Date().toISOString() });
+    await mkdir(ctx.dir, { recursive:true }); await mkdir(ctx.eventsDir, { recursive:true });
+    if (await exists(ctx.diffPath)) {
+      const verifyKey = await loadPublicVerifyKey(verifyKeyPath);
+      const existing = await readEnvelope(ctx.diffPath, verifyKey, DIFF_DOMAIN, 'native diff');
+      const { created_at_utc:_a, attestation:_b, ...existingIdentity } = existing;
+      const { attestation:_c, created_at_utc:_d, ...newIdentity } = envelope;
+      if (canonicalJson(existingIdentity) !== canonicalJson(newIdentity)) throw new Error('native diff id collision');
+    } else {
+      await writeExclusive(ctx.diffPath, envelope);
+    }
+    return { status:'ready', diff_id:diffId, root_id:rootId, operation_count:operations.length,
+      payload_bytes:payloadBytes, paths:operations.map(op => op.path), operations:operations.map(({content,old_string,new_string,...op}) => op) };
+  }
+  async function loadDiff(diffId) {
+    const ctx = diffContext(policy, diffId);
+    const verifyKey = await loadPublicVerifyKey(verifyKeyPath);
+    const envelope = await readEnvelope(ctx.diffPath, verifyKey, DIFF_DOMAIN, 'native diff');
+    const { attestation:_att, created_at_utc:_created, diff_id:claimed, ...identity } = envelope;
+    if (claimed !== diffId || identity.schema !== NATIVE_DIFF_SCHEMA ||
+        identity.policy_sha256 !== policy.policy_sha256 || identity.coding_policy_sha256 !== policy.coding_policy_sha256 ||
+        sha256Object(identity) !== diffId) throw new Error('native diff identity/hash mismatch');
+    return { ctx, envelope, identity };
+  }
+  async function readEvents(ctx) {
+    const verifyKey = await loadPublicVerifyKey(verifyKeyPath);
+    const names = (await readdir(ctx.eventsDir)).filter(name => /^\d{6}\.json$/.test(name)).sort();
+    const events = []; let previous = ZERO_HASH;
+    for (let i = 0; i < names.length; i += 1) {
+      const expected = `${String(i + 1).padStart(6,'0')}.json`;
+      if (names[i] !== expected) throw new Error(`native diff event gap at ${expected}`);
+      const event = await readEnvelope(path.join(ctx.eventsDir, names[i]), verifyKey, EVENT_DOMAIN, 'native diff event');
+      const { attestation:_a, event_sha256:claimed, ...body } = event;
+      if (event.schema !== NATIVE_DIFF_EVENT_SCHEMA || event.seq !== i + 1 || event.prev_sha256 !== previous ||
+          !SHA256_RE.test(claimed ?? '') || sha256Object(body) !== claimed) throw new Error(`native diff event ${expected} invalid`);
+      events.push(event); previous = claimed;
+    }
+    return events;
+  }
+  async function appendEvent(ctx, events, diffId, type, payload = {}) {
+    const body = { schema:NATIVE_DIFF_EVENT_SCHEMA, diff_id:diffId, seq:events.length + 1,
+      created_at_utc:new Date().toISOString(), prev_sha256:events.at(-1)?.event_sha256 ?? ZERO_HASH, type, payload };
+    const signingKey = await loadPrivateSigningKey(signingKeyPath);
+    const event = signEnvelope(signingKey, EVENT_DOMAIN, { ...body, event_sha256:sha256Object(body) });
+    await writeExclusive(path.join(ctx.eventsDir, `${String(event.seq).padStart(6,'0')}.json`), event);
+    events.push(event); return event;
+  }
+  async function ensurePreimage(ctx, diffId, identity) {
+    const verifyKey = await loadPublicVerifyKey(verifyKeyPath);
+    if (await exists(ctx.preimagePath)) {
+      const stored = await readEnvelope(ctx.preimagePath, verifyKey, PREIMAGE_DOMAIN, 'native diff preimage');
+      const { attestation:_a, preimage_sha256:claimed, ...body } = stored;
+      if (body.schema !== NATIVE_DIFF_PREIMAGE_SCHEMA || body.diff_id !== diffId ||
+          !SHA256_RE.test(claimed ?? '') || sha256Object(body) !== claimed) throw new Error('native diff preimage hash mismatch');
+      return stored;
+    }
+    const snapshots = [];
+    for (const op of identity.operations) {
+      const state = await codingRuntime.fileState({ rootId:identity.root_id, relativePath:op.path });
+      const expected = op.before_sha256;
+      if ((expected === null && state.exists) || (expected !== null && (!state.exists || state.sha256 !== expected))) {
+        throw new Error(`native diff apply preimage changed for '${op.path}'`);
+      }
+      if (state.exists) {
+        const read = await codingRuntime.fileRead({ rootId:identity.root_id, relativePath:op.path, encoding:'base64' });
+        snapshots.push({ path:op.path, existed:true, sha256:state.sha256, bytes:read.bytes, content_base64:read.content });
+      } else {
+        snapshots.push({ path:op.path, existed:false, sha256:null, bytes:0, content_base64:null });
+      }
+    }
+    const body = { schema:NATIVE_DIFF_PREIMAGE_SCHEMA, diff_id:diffId, policy_sha256:policy.policy_sha256,
+      root_id:identity.root_id, created_at_utc:new Date().toISOString(), snapshots };
+    const signingKey = await loadPrivateSigningKey(signingKeyPath);
+    const envelope = signEnvelope(signingKey, PREIMAGE_DOMAIN, { ...body, preimage_sha256:sha256Object(body) });
+    await writeExclusive(ctx.preimagePath, envelope);
+    return envelope;
+  }
+  async function executeOperation(diffId, rootId, op, index) {
+    const receiptId = receiptIdFor(diffId, index, 'apply');
+    const existing = await codingRuntime.verifyReceiptDetailed(receiptId);
+    if (existing.ok) return { recovered:true, receipt_id:receiptId, receipt_sha256:existing.receipt_sha256,
+      request_sha256:existing.request_sha256, operation:existing.operation };
+    let result;
+    if (op.kind === 'write') {
+      result = await codingRuntime.fileWrite({ rootId, relativePath:op.path, content:op.content,
+        encoding:op.encoding, expectedSha256:op.expected_sha256, receiptId });
+    } else if (op.kind === 'replace') {
+      result = await codingRuntime.textReplace({ rootId, relativePath:op.path, oldString:op.old_string,
+        newString:op.new_string, expectedSha256:op.expected_sha256,
+        expectedReplacements:op.expected_replacements, receiptId });
+    } else {
+      result = await codingRuntime.fileDelete({ rootId, relativePath:op.path,
+        expectedSha256:op.expected_sha256, receiptId });
+    }
+    const checked = await codingRuntime.verifyReceiptDetailed(receiptId);
+    if (!checked.ok || checked.receipt_sha256 !== result.receipt_sha256 || checked.request_sha256 !== result.request_sha256) {
+      throw new Error(`native diff coding receipt verification failed for '${op.path}'`);
+    }
+    return { recovered:false, receipt_id:receiptId, receipt_sha256:checked.receipt_sha256,
+      request_sha256:checked.request_sha256, operation:checked.operation };
+  }
+  function stateMatches(state, expectedSha) {
+    return expectedSha === null ? !state.exists : state.exists && state.sha256 === expectedSha;
+  }
+  async function rollbackToPreimage(diffId, identity, preimage) {
+    const receipts = [];
+    for (let index = identity.operations.length - 1; index >= 0; index -= 1) {
+      const op = identity.operations[index]; const snap = preimage.snapshots[index];
+      const current = await codingRuntime.fileState({ rootId:identity.root_id, relativePath:op.path });
+      if (stateMatches(current, snap.sha256)) continue;
+      if (!stateMatches(current, op.after_sha256)) throw new Error(`native diff rollback_conflict '${op.path}'`);
+      const receiptId = receiptIdFor(diffId, index, 'rollback');
+      let result;
+      if (snap.existed) {
+        result = await codingRuntime.fileWrite({ rootId:identity.root_id, relativePath:op.path,
+          content:snap.content_base64, encoding:'base64', expectedSha256:current.exists ? current.sha256 : 'absent', receiptId });
+      } else {
+        result = await codingRuntime.fileDelete({ rootId:identity.root_id, relativePath:op.path,
+          expectedSha256:current.sha256, receiptId });
+      }
+      receipts.push({ index, path:op.path, receipt_id:receiptId, receipt_sha256:result.receipt_sha256 });
+    }
+    return receipts;
+  }
+  async function createApplyReceipt(ctx, diffId, identity, preimage, events) {
+    const committed = events.filter(event => event.type === 'operation_committed');
+    if (committed.length !== identity.operations.length) throw new Error('native diff cannot receipt incomplete transaction');
+    const finalStates = [];
+    for (const op of identity.operations) {
+      const state = await codingRuntime.fileState({ rootId:identity.root_id, relativePath:op.path });
+      if (!stateMatches(state, op.after_sha256)) throw new Error(`native diff final state mismatch '${op.path}'`);
+      finalStates.push({ path:op.path, sha256:state.sha256, exists:state.exists });
+    }
+    const body = {
+      schema:NATIVE_DIFF_RECEIPT_SCHEMA, diff_id:diffId, policy_sha256:policy.policy_sha256,
+      coding_policy_sha256:policy.coding_policy_sha256, preimage_sha256:preimage.preimage_sha256,
+      event_head_sha256:events.at(-1)?.event_sha256 ?? ZERO_HASH,
+      completed_at_utc:new Date().toISOString(),
+      coding_receipts:committed.map(event => ({ index:event.payload.index, path:event.payload.path,
+        receipt_id:event.payload.receipt_id, receipt_sha256:event.payload.receipt_sha256,
+        request_sha256:event.payload.request_sha256 })), final_states:finalStates
+    };
+    const receiptSha = sha256Object(body);
+    const signingKey = await loadPrivateSigningKey(signingKeyPath);
+    const receipt = signEnvelope(signingKey, RECEIPT_DOMAIN, { ...body, receipt_sha256:receiptSha });
+    await writeExclusive(ctx.receiptPath, receipt);
+    await appendEvent(ctx, events, diffId, 'transaction_completed', { receipt_sha256:receiptSha });
+    return receipt;
+  }
+
+  async function apply({ diffId }) {
+    const { ctx, identity } = await loadDiff(diffId);
+    await assertAutonomousArmed(policy, identity.root_id);
+    const codingStatus = await codingRuntime.sessionStatus();
+    if (!codingStatus.armed) throw new Error(`coding plane is disarmed: ${codingStatus.reason}`);
+    if (await exists(ctx.receiptPath)) {
+      const checked = await verify({ diffId });
+      if (!checked.ok) throw new Error(`existing native diff receipt invalid: ${checked.reason}`);
+      return { status:'existing', diff_id:diffId, receipt_sha256:checked.receipt_sha256,
+        operation_count:identity.operations.length, current_state_matches:checked.current_state_matches };
+    }
+    const preimage = await ensurePreimage(ctx, diffId, identity);
+    const events = await readEvents(ctx);
+    if (!events.some(event => event.type === 'transaction_started')) {
+      await appendEvent(ctx, events, diffId, 'transaction_started', { operation_count:identity.operations.length,
+        preimage_sha256:preimage.preimage_sha256 });
+    }
+    try {
+      for (let index = 0; index < identity.operations.length; index += 1) {
+        const op = identity.operations[index];
+        const priorEvent = events.find(event => event.type === 'operation_committed' && event.payload?.index === index);
+        if (priorEvent) {
+          const current = await codingRuntime.fileState({ rootId:identity.root_id, relativePath:op.path });
+          if (!stateMatches(current, op.after_sha256)) throw new Error(`native diff committed path changed '${op.path}'`);
+          continue;
+        }
+        const current = await codingRuntime.fileState({ rootId:identity.root_id, relativePath:op.path });
+        const receiptId = receiptIdFor(diffId, index, 'apply');
+        let executed;
+        if (stateMatches(current, op.after_sha256)) {
+          const checked = await codingRuntime.verifyReceiptDetailed(receiptId);
+          if (!checked.ok) throw new Error(`native diff unreceipted mutation '${op.path}'`);
+          executed = { recovered:true, receipt_id:receiptId, receipt_sha256:checked.receipt_sha256,
+            request_sha256:checked.request_sha256, operation:checked.operation };
+        } else if (stateMatches(current, op.before_sha256)) {
+          executed = await executeOperation(diffId, identity.root_id, op, index);
+        } else {
+          throw new Error(`native diff concurrent state conflict '${op.path}'`);
+        }
+        const after = await codingRuntime.fileState({ rootId:identity.root_id, relativePath:op.path });
+        if (!stateMatches(after, op.after_sha256)) throw new Error(`native diff post-operation mismatch '${op.path}'`);
+        await appendEvent(ctx, events, diffId, 'operation_committed', {
+          index, path:op.path, kind:op.kind, before_sha256:op.before_sha256,
+          after_sha256:op.after_sha256, receipt_id:executed.receipt_id,
+          receipt_sha256:executed.receipt_sha256, request_sha256:executed.request_sha256,
+          recovered:executed.recovered
+        });
+      }
+    } catch (error) {
+      try {
+        const rollbackReceipts = await rollbackToPreimage(diffId, identity, preimage);
+        await appendEvent(ctx, events, diffId, 'transaction_rolled_back', {
+          reason:String(error).slice(0,2048), rollback_receipts:rollbackReceipts
+        });
+      } catch (rollbackError) {
+        await appendEvent(ctx, events, diffId, 'transaction_paused', {
+          reason:String(error).slice(0,1024), rollback_error:String(rollbackError).slice(0,1024)
+        }).catch(() => {});
+        throw new Error(`native diff apply failed and rollback incomplete: ${String(error)}; ${String(rollbackError)}`);
+      }
+      throw new Error(`native diff apply rolled back: ${String(error)}`);
+    }
+    const receipt = await createApplyReceipt(ctx, diffId, identity, preimage, events);
+    return { status:'committed', diff_id:diffId, receipt_sha256:receipt.receipt_sha256,
+      operation_count:identity.operations.length,
+      coding_receipts:receipt.coding_receipts.map(item => ({ index:item.index, path:item.path, receipt_id:item.receipt_id, receipt_sha256:item.receipt_sha256 })) };
+  }
+
+  async function verify({ diffId }) {
+    try {
+      const { ctx, identity } = await loadDiff(diffId);
+      const verifyKey = await loadPublicVerifyKey(verifyKeyPath);
+      const preimage = await readEnvelope(ctx.preimagePath, verifyKey, PREIMAGE_DOMAIN, 'native diff preimage');
+      const events = await readEvents(ctx);
+      const receipt = await readEnvelope(ctx.receiptPath, verifyKey, RECEIPT_DOMAIN, 'native diff receipt');
+      const { attestation:_a, receipt_sha256:claimed, ...body } = receipt;
+      if (body.schema !== NATIVE_DIFF_RECEIPT_SCHEMA || body.diff_id !== diffId ||
+          body.policy_sha256 !== policy.policy_sha256 || body.coding_policy_sha256 !== policy.coding_policy_sha256 ||
+          !SHA256_RE.test(claimed ?? '') || sha256Object(body) !== claimed) return { ok:false, reason:'native diff receipt identity/hash mismatch' };
+      const completion = events.at(-1);
+      if (completion?.type !== 'transaction_completed' || completion.prev_sha256 !== receipt.event_head_sha256 ||
+          completion.payload?.receipt_sha256 !== claimed || receipt.preimage_sha256 !== preimage.preimage_sha256) {
+        return { ok:false, reason:'native diff receipt/event/preimage binding mismatch' };
+      }
+      if (!Array.isArray(receipt.coding_receipts) || receipt.coding_receipts.length !== identity.operations.length) {
+        return { ok:false, reason:'native diff receipt coding count mismatch' };
+      }
+      let verifiedReceipts = 0;
+      for (let index = 0; index < identity.operations.length; index += 1) {
+        const bound = receipt.coding_receipts.find(item => item.index === index);
+        if (!bound || bound.path !== identity.operations[index].path) return { ok:false, reason:`native diff receipt binding mismatch index ${index}` };
+        const checked = await codingRuntime.verifyReceiptDetailed(bound.receipt_id);
+        if (!checked.ok || checked.receipt_sha256 !== bound.receipt_sha256 || checked.request_sha256 !== bound.request_sha256) {
+          return { ok:false, reason:`native diff coding receipt invalid index ${index}` };
+        }
+        verifiedReceipts += 1;
+      }
+      let currentMatches = true;
+      for (const op of identity.operations) {
+        const current = await codingRuntime.fileState({ rootId:identity.root_id, relativePath:op.path });
+        if (!stateMatches(current, op.after_sha256)) currentMatches = false;
+      }
+      return { ok:true, diff_id:diffId, receipt_sha256:claimed, signature_valid:true,
+        root_id:identity.root_id, operation_count:identity.operations.length,
+        coding_receipts_verified:verifiedReceipts, final_states:receipt.final_states,
+        current_state_matches:currentMatches, journal_head_sha256:completion.event_sha256 };
+    } catch (error) {
+      return { ok:false, reason:String(error).slice(0,2048) };
+    }
+  }
+
+  return Object.freeze({ preview, apply, verify, policy });
+}

package/src/observation-mcp-tools.mjs

@@ -0,0 +1,44 @@
+import * as z from 'zod/v4';
+import {
+  observationProcessListOutputSchema,observationSearchCancelOutputSchema,observationSearchPageOutputSchema,
+  observationSearchStartOutputSchema,observationSearchStatusOutputSchema,observationStructuredResult,observationSystemStatusOutputSchema
+} from './observation-output-contracts.mjs';
+
+const hex64=z.string().regex(/^[0-9a-f]{64}$/);
+const id=z.string().regex(/^[A-Za-z0-9._-]{1,64}$/);
+const ok=(schema,value)=>observationStructuredResult(schema,value,false);
+const fail=(schema,error)=>observationStructuredResult(schema,{status:'failed',error:String(error)},true);
+
+export function registerObservationTools(server,{runtime}){
+  if(!server||!runtime) throw new Error('observation tool registration requires server/runtime');
+  server.registerTool('machine_search_start',{
+    description:'Start a bounded deterministic literal-content search inside one registered read-only root. Observation authority is independent of mutation leases.',
+    inputSchema:z.strictObject({root_id:id,path:z.string().min(1).max(512).default('.'),pattern:z.string().min(1).max(256),case_sensitive:z.boolean().default(false),
+      max_results:z.number().int().min(1).max(1000).default(200),max_files:z.number().int().min(1).max(10000).default(2000),
+      max_bytes:z.number().int().min(1).max(64*1024*1024).default(4*1024*1024),max_file_bytes:z.number().int().min(1).max(4*1024*1024).default(262144)}),
+    outputSchema:observationSearchStartOutputSchema
+  },async args=>{try{return ok(observationSearchStartOutputSchema,await runtime.searchStart({rootId:args.root_id,relativePath:args.path,pattern:args.pattern,
+    caseSensitive:args.case_sensitive,maxResults:args.max_results,maxFiles:args.max_files,maxBytes:args.max_bytes,maxFileBytes:args.max_file_bytes}));}catch(error){return fail(observationSearchStartOutputSchema,error);}});
+  server.registerTool('machine_search_page',{
+    description:'Read one bounded stable page from a DEADBYTE search session.',
+    inputSchema:z.strictObject({search_id:hex64,limit:z.number().int().min(1).max(500).default(100),cursor:z.string().max(512).nullable().default(null)}),
+    outputSchema:observationSearchPageOutputSchema
+  },async args=>{try{return ok(observationSearchPageOutputSchema,await runtime.searchPage({searchId:args.search_id,limit:args.limit,cursor:args.cursor}));}catch(error){return fail(observationSearchPageOutputSchema,error);}});
+  server.registerTool('machine_search_status',{
+    description:'Read bounded search progress, result-chain head, and signed completion evidence.',
+    inputSchema:z.strictObject({search_id:hex64}),outputSchema:observationSearchStatusOutputSchema
+  },async args=>{try{const value=await runtime.searchStatus({searchId:args.search_id});const {error:search_error,...rest}=value;return ok(observationSearchStatusOutputSchema,{...rest,search_error});}catch(error){return fail(observationSearchStatusOutputSchema,error);}});
+  server.registerTool('machine_search_cancel',{
+    description:'Request cooperative cancellation of one DEADBYTE search session. This cannot mutate searched roots.',
+    inputSchema:z.strictObject({search_id:hex64}),outputSchema:observationSearchCancelOutputSchema
+  },async args=>{try{return ok(observationSearchCancelOutputSchema,await runtime.searchCancel({searchId:args.search_id}));}catch(error){return fail(observationSearchCancelOutputSchema,error);}});
+  server.registerTool('machine_process_list',{
+    description:'Read a bounded immutable process snapshot. DEADBYTE-owned processes are distinguished from external OS state; external command lines and paths are withheld.',
+    inputSchema:z.strictObject({limit:z.number().int().min(1).max(256).default(100),include_external:z.boolean().default(false),cursor:z.string().max(512).nullable().default(null)}),
+    outputSchema:observationProcessListOutputSchema
+  },async args=>{try{return ok(observationProcessListOutputSchema,await runtime.processList({limit:args.limit,includeExternal:args.include_external,cursor:args.cursor}));}catch(error){return fail(observationProcessListOutputSchema,error);}});
+  server.registerTool('machine_system_status',{
+    description:'Read bounded timestamped system status with signed observation evidence. This tool cannot mutate or arm any authority.',
+    inputSchema:z.strictObject({}),outputSchema:observationSystemStatusOutputSchema
+  },async()=>{try{return ok(observationSystemStatusOutputSchema,await runtime.systemStatus());}catch(error){return fail(observationSystemStatusOutputSchema,error);}});
+}

package/src/observation-output-contracts.mjs

@@ -0,0 +1,50 @@
+import * as z from 'zod/v4';
+import { structuredToolResult } from './output-contracts.mjs';
+
+const hex64=z.string().regex(/^[0-9a-f]{64}$/);
+const receiptId=z.string().regex(/^[0-9a-f]{24}$/);
+const searchState=z.enum(['pending','running','completed','cancelled','failed']);
+const evidenceShape={request_sha256:hex64,result_head_sha256:hex64,receipt_id:receiptId.nullable(),receipt_sha256:hex64.nullable()};
+const resultSchema=z.strictObject({path:z.string().min(1).max(512),line:z.number().int().min(1),column:z.number().int().min(1),preview:z.string().max(512)});
+const processSchema=z.strictObject({pid:z.number().int().positive(),parent_pid:z.number().int().nonnegative(),name:z.string().max(260),
+  ownership:z.enum(['deadbyte-runtime','deadbyte-session','external']),executable_path:z.string().max(2048).nullable(),command_line:z.string().max(4096).nullable()});
+
+function statusContract(shape,successRequired=[]){
+  return z.strictObject({status:z.enum(['ok','failed']),error:z.string().optional(),...shape}).superRefine((value,ctx)=>{
+    if(value.status==='failed'){ if(!value.error) ctx.addIssue({code:'custom',path:['error'],message:'error required'}); return; }
+    for(const key of successRequired) if(value[key]===undefined) ctx.addIssue({code:'custom',path:[key],message:`${key} required`});
+  });
+}
+
+export const observationSearchStartOutputSchema=z.strictObject({
+  status:z.enum(['accepted','failed']),error:z.string().optional(),search_id:hex64.optional(),state:searchState.optional(),request_sha256:hex64.optional()
+}).superRefine((v,ctx)=>{if(v.status==='accepted'){for(const k of ['search_id','state','request_sha256']) if(v[k]===undefined) ctx.addIssue({code:'custom',path:[k],message:`${k} required`});} else if(!v.error) ctx.addIssue({code:'custom',path:['error'],message:'error required'});});
+export const observationSearchPageOutputSchema=statusContract({
+  search_id:hex64.optional(),state:searchState.optional(),results:z.array(resultSchema).max(500).optional(),next_cursor:z.string().max(512).nullable().optional(),
+  ...Object.fromEntries(Object.entries(evidenceShape).map(([k,v])=>[k,v.optional()]))
+},['search_id','state','results','next_cursor','request_sha256','result_head_sha256','receipt_id','receipt_sha256']);
+
+export const observationSearchStatusOutputSchema=statusContract({
+  search_id:hex64.optional(),state:searchState.optional(),result_count:z.number().int().nonnegative().optional(),files_scanned:z.number().int().nonnegative().optional(),
+  bytes_scanned:z.number().int().nonnegative().optional(),truncated:z.boolean().optional(),search_error:z.string().nullable().optional(),
+  ...Object.fromEntries(Object.entries(evidenceShape).map(([k,v])=>[k,v.optional()]))
+},['search_id','state','result_count','files_scanned','bytes_scanned','truncated','search_error','request_sha256','result_head_sha256','receipt_id','receipt_sha256']);
+
+export const observationSearchCancelOutputSchema=statusContract({
+  search_id:hex64.optional(),state:searchState.optional(),cancel_requested:z.boolean().optional()
+},['search_id','state','cancel_requested']);
+
+export const observationProcessListOutputSchema=statusContract({
+  snapshot_id:hex64.optional(),observed_at_utc:z.string().min(1).optional(),processes:z.array(processSchema).max(256).optional(),next_cursor:z.string().max(512).nullable().optional(),
+  ...Object.fromEntries(Object.entries(evidenceShape).map(([k,v])=>[k,v.optional()]))
+},['snapshot_id','observed_at_utc','processes','next_cursor','request_sha256','result_head_sha256','receipt_id','receipt_sha256']);
+export const observationSystemStatusOutputSchema=statusContract({
+  observed_at_utc:z.string().min(1).optional(),hostname:z.string().max(260).optional(),platform:z.string().max(64).optional(),architecture:z.string().max(64).optional(),
+  uptime_seconds:z.number().nonnegative().optional(),total_memory_bytes:z.number().nonnegative().optional(),free_memory_bytes:z.number().nonnegative().optional(),
+  cpu_count:z.number().int().min(1).optional(),load_average:z.array(z.number()).length(3).optional(),
+  ...Object.fromEntries(Object.entries(evidenceShape).map(([k,v])=>[k,v.optional()]))
+},['observed_at_utc','hostname','platform','architecture','uptime_seconds','total_memory_bytes','free_memory_bytes','cpu_count','load_average','request_sha256','result_head_sha256','receipt_id','receipt_sha256']);
+
+export function observationStructuredResult(schema,value,isError=false){
+  return structuredToolResult(schema,value,isError);
+}