deadbyte-mcp 0.15.47 → 0.15.49

package/src/authority-continuity-r65.mjs

@@ -1,5 +1,5 @@
 import {createHash,createPrivateKey,createPublicKey,randomBytes,sign as cryptoSign,verify as cryptoVerify} from 'node:crypto';
-import {mkdir,open,readFile,readdir,rename,rm,writeFile} from 'node:fs/promises';
+import {lstat,mkdir,open,readFile,readdir,rename,rm,writeFile} from 'node:fs/promises';
 import path from 'node:path';
 import {canonicalJson} from './canonical-json.mjs';
 import {decodeUtf8Strict} from './text-policy.mjs';
@@ -214,10 +214,63 @@ const durablePublicKeys=new Map();
 const RESTORE_BINDING_FIELDS=Object.freeze(['prior_grant_sha256','prior_grant_instance_nonce','predecessor_policy_envelope_sha256','successor_policy_envelope_sha256','candidate_manifest_sha256','continuity_subject_sha256']);
 function normalizeRestoreBinding(value,{required=false}={}){
   if(value===undefined||value===null){if(required)throw new Error('authority epoch transaction restore binding required');return null;}
-  if(!plain(value)||Object.keys(value).length!==RESTORE_BINDING_FIELDS.length||RESTORE_BINDING_FIELDS.some(key=>!SHAPAT.test(String(value[key]))))
+  if(!plain(value)||Object.keys(value).length!==RESTORE_BINDING_FIELDS.length||
+      RESTORE_BINDING_FIELDS.some(key=>typeof value[key]!=='string'||!SHAPAT.test(value[key])))
     throw new Error('authority epoch transaction restore binding invalid');
   for(const key of Object.keys(value))if(!RESTORE_BINDING_FIELDS.includes(key))throw new Error('authority epoch transaction restore binding invalid');
-  return Object.freeze(Object.fromEntries(RESTORE_BINDING_FIELDS.map(key=>[key,String(value[key])])));
+  return Object.freeze(Object.fromEntries(RESTORE_BINDING_FIELDS.map(key=>[key,value[key]])));
+}
+
+function assertEpochActionIdentity(current){
+  const action=current?.action;
+  if(!DURABLE_EPOCH_ACTIONS.has(action)||
+      (action.startsWith('transaction_')?
+        typeof current.update_id!=='string'||!/^[A-Za-z0-9._-]{1,96}$/.test(current.update_id):
+        current.update_id!==null))
+    throw new Error('authority epoch transition invalid');
+  if(action==='transaction_restore')normalizeRestoreBinding(current.restore_binding,{required:true});
+  else if(current.restore_binding!==null)throw new Error('authority epoch transition invalid');
+}
+
+function assertEpochPredecessorIdentity(event){
+  if(event.schema!==DURABLE_EPOCH_SCHEMA||
+      typeof event.grant_sha256!=='string'||!SHAPAT.test(event.grant_sha256)||
+      typeof event.grant_instance_nonce!=='string'||!SHAPAT.test(event.grant_instance_nonce)||
+      (event.seq===1?event.previous_event_sha256!==null:
+        typeof event.previous_event_sha256!=='string'||!SHAPAT.test(event.previous_event_sha256))||
+      ((event.policy_sha256!==undefined||event.policy_envelope_sha256!==undefined)&&
+        (typeof event.policy_sha256!=='string'||!SHAPAT.test(event.policy_sha256)||
+         typeof event.policy_envelope_sha256!=='string'||!SHAPAT.test(event.policy_envelope_sha256))))
+    throw new Error('authority epoch transition invalid');
+  assertEpochActionIdentity(event);
+}
+
+function assertEpochTransition(current,previous){
+  assertEpochActionIdentity(current);
+  const action=current.action;
+  if(!previous){
+    if(action.startsWith('transaction_'))throw new Error('authority epoch transition invalid');
+    return;
+  }
+  if(action==='transaction_revoke'&&
+      (!['grant','transaction_restore'].includes(previous.action)||
+       current.grant_sha256!==previous.grant_sha256||
+       current.grant_instance_nonce!==previous.grant_instance_nonce))
+    throw new Error('authority epoch transition invalid');
+  if(action==='transaction_restore'){
+    const binding=normalizeRestoreBinding(current.restore_binding,{required:true});
+    if(previous.action!=='transaction_revoke'||current.update_id!==previous.update_id||
+        binding.prior_grant_sha256!==previous.grant_sha256||
+        binding.prior_grant_instance_nonce!==previous.grant_instance_nonce||
+        current.grant_instance_nonce===previous.grant_instance_nonce||
+        (previous.policy_envelope_sha256!==undefined&&
+          binding.predecessor_policy_envelope_sha256!==previous.policy_envelope_sha256)||
+        (current.policy_envelope_sha256!==undefined&&
+          binding.successor_policy_envelope_sha256!==current.policy_envelope_sha256))
+      throw new Error('authority epoch transition invalid');
+  }
+  if(action==='grant'&&current.grant_instance_nonce===previous.grant_instance_nonce)
+    throw new Error('authority epoch transition invalid');
 }
 
 async function durableEpochKeys(runtimeDir,{privateRequired=false}={}){
@@ -271,38 +324,159 @@ function processAlive(pid){
   if(pid===process.pid)return true;
   try{process.kill(pid,0);return true;}catch(error){return error?.code==='EPERM';}
 }
-async function atomicJsonWrite(file,value){
+let cachedEpochOwnerIdentity=null;
+async function windowsEpochOwnerIdentity(pid){
+  const {queryForegroundIdentity,validForegroundIdentity}=await import('./foreground-process-identity.mjs');
+  const identity=queryForegroundIdentity(pid);
+  if(identity!==null&&!validForegroundIdentity(identity))throw new Error('authority epoch owner process identity incomplete');
+  return identity;
+}
+async function currentEpochOwnerIdentity(){
+  if(process.platform!=='win32')return null;
+  if(!cachedEpochOwnerIdentity)cachedEpochOwnerIdentity=await windowsEpochOwnerIdentity(process.pid);
+  if(!cachedEpochOwnerIdentity||cachedEpochOwnerIdentity.pid!==process.pid)
+    throw new Error('authority epoch owner process identity unavailable');
+  return cachedEpochOwnerIdentity;
+}
+// R80: A successful file write is not a durability barrier. Flush the exact
+// open file handle BEFORE publishing an event or replacing the signed head.
+// Node on Windows does not expose a verified directory-metadata flush: keep
+// that limitation explicit instead of treating rename() as a power-loss proof.
+export function authorityEpochDurabilityAssessment(){
+  return Object.freeze({
+    event_file:'FLUSH_REQUIRED',head_temp_file:'FLUSH_REQUIRED',
+    directory_metadata:process.platform==='win32'?'UNVERIFIED_ON_WINDOWS':'FSYNC_REQUIRED',
+    power_loss:'NOT_VERIFIED_BY_TESTS'
+  });
+}
+async function syncDirectoryMetadata(dir){
+  if(process.platform==='win32')return false; // No verified Node directory FlushFileBuffers contract.
+  const handle=await open(dir,'r');
+  try{await handle.sync();}
+  finally{await handle.close();}
+  return true;
+}
+async function writeDurableEvent(file,bytes,{stage=async()=>{}}={}){
+  const handle=await open(file,'wx'); // immutable identity, exclusive creation
+  try{
+    await stage('event_created');
+    await handle.writeFile(bytes);
+    await stage('event_written');
+    await handle.sync(); // event bytes must be flushed BEFORE head visibility
+    await stage('event_file_synced');
+  }finally{await handle.close();}
+  await syncDirectoryMetadata(path.dirname(file));
+  await stage('event_directory_barrier');
+}
+async function atomicJsonWrite(file,value,{stage=async()=>{}}={}){
   const dir=path.dirname(file);
   await mkdir(dir,{recursive:true});
   const tmp=`${file}.tmp-${process.pid}-${randomBytes(8).toString('hex')}`;
   try{
-    await writeFile(tmp,canonicalJson(value),{encoding:'utf8',flag:'wx'});
+    const handle=await open(tmp,'wx');
+    try{
+      await stage('head_temp_created');
+      await handle.writeFile(Buffer.from(canonicalJson(value),'utf8'));
+      await stage('head_temp_written');
+      await handle.sync(); // temp head content flushed BEFORE rename
+      await stage('head_temp_file_synced');
+    }finally{await handle.close();}
     await rename(tmp,file);
+    await stage('head_renamed'); // rename succeeded: caller outcome may now be ambiguous
+    await syncDirectoryMetadata(dir);
+    await stage('head_directory_barrier');
   }finally{
     await rm(tmp,{force:true}).catch(()=>{});
   }
 }
-async function acquireEpochLock(dir){
+// R82: On Windows, lock reclamation/release MUST be conditional on the
+// exact observed lock bytes and must dispose through one pinned native handle.
+// The R78 implementation also pins every non-reparse ancestor directory.
+// R83: Windows lock snapshots now bind owner bytes + native FileIdInfo to
+// the same pinned handle. The later pinned deletion compares BOTH identity
+// and content before disposition, defeating byte-identical file replacement.
+// POSIX remains legacy/unsupported against adversarial lock-path replacement.
+async function epochLockSnapshot(lockPath){
+  if(process.platform==='win32'){
+    const {readPinnedEpochLockSnapshot}=await import('./foreground-marker-cas-win32.mjs');
+    return readPinnedEpochLockSnapshot(lockPath);
+  }
+  try{return {bytes:await readFile(lockPath),fileId:null};}
+  catch(error){if(error?.code==='ENOENT')return null;throw error;}
+}
+async function disposeObservedEpochLock(lockPath,snapshot){
+  if(process.platform==='win32'){
+    if(!snapshot?.fileId)throw new Error('epoch lock native identity snapshot is required');
+    const {deletePinnedRemoteMarker}=await import('./foreground-marker-cas-win32.mjs');
+    return deletePinnedRemoteMarker(lockPath,hashBytes(snapshot.bytes),{expectedFileId:snapshot.fileId});
+  }
+  throw new Error('authority epoch POSIX lock disposition unsupported');
+}
+
+async function acquireEpochLock(dir,{allowStaleRecovery=true,onLockDispositionStage=null}={}){
+  // POSIX open('wx') protects creation, but a later read/check followed by
+  // unlink(path) cannot atomically prove the pathname still denotes our lock.
+  // Until a kernel-held, identity-bound POSIX protocol exists, no authority
+  // epoch mutation may start there. Read-only head verification remains usable.
+  if(process.platform!=='win32')
+    throw new Error('authority epoch POSIX mutation unsupported: lock pathname cannot be disposed atomically');
   await mkdir(dir,{recursive:true});
   const lockPath=path.join(dir,'.lock');
+  const stage=async label=>{if(onLockDispositionStage)await onLockDispositionStage(label,lockPath);};
   for(let attempt=0;attempt<2;attempt++){
     const token=randomBytes(16).toString('hex');
     try{
-      const handle=await open(lockPath,'wx');
-      try{await handle.writeFile(canonicalJson({schema:'deadbyte.authority-epoch-lock.r65.v1',pid:process.pid,token,created_at_utc:new Date().toISOString()}),'utf8');}
-      finally{await handle.close();}
-      return async()=>{
-        try{
-          const current=JSON.parse(await readFile(lockPath,'utf8'));
-          if(current?.token===token)await rm(lockPath,{force:true});
-        }catch(error){if(error?.code!=='ENOENT')throw error;}
+      const ownerIdentity=await currentEpochOwnerIdentity();
+      const lockBytes=Buffer.from(canonicalJson({schema:'deadbyte.authority-epoch-lock.r65.v1',pid:process.pid,token,
+        created_at_utc:new Date().toISOString(),...(ownerIdentity?{owner_identity:ownerIdentity}:{})}),'utf8');
+      let nativeLease=null;
+      if(process.platform==='win32'){
+        const {acquireHeldEpochLock}=await import('./epoch-lock-r85.mjs');
+        nativeLease=await acquireHeldEpochLock(lockPath,lockBytes);
+        if(!nativeLease)throw Object.assign(new Error('authority epoch lock exists'),{code:'EEXIST'});
+      }else throw new Error('authority epoch POSIX mutation unsupported');
+      const verifyOwned=async()=>{
+        // On Windows the in-process native handle holds the leaf and every
+        // non-reparse ancestor through the mutation. No pathname recheck can
+        // improve that atomic ownership guarantee.
+        if(!nativeLease)throw new Error('authority epoch lock ownership unverified');
+        return null;
       };
+      const release=async()=>{
+        if(nativeLease){
+          let stageError=null;
+          try{await stage('release_before_cas');}catch(error){stageError=error;}
+          let releaseError=null;
+          try{await nativeLease.release();}catch(error){releaseError=error;}
+          if(stageError&&releaseError)throw new AggregateError([stageError,releaseError],
+            'authority epoch release observer and native cleanup both failed');
+          if(stageError)throw stageError;
+          if(releaseError)throw releaseError;
+          return;
+        }
+        throw new Error('authority epoch lock release without native ownership denied');
+      };
+      release.verifyOwned=verifyOwned;
+      return release;
     }catch(error){
       if(error?.code!=='EEXIST')throw error;
+      const snapshot=await epochLockSnapshot(lockPath);
       let owner=null;
-      try{owner=JSON.parse(await readFile(lockPath,'utf8'));}catch{}
-      if(attempt===0&&owner&&Number.isInteger(owner.pid)&&!processAlive(owner.pid)){
-        await rm(lockPath,{force:true});
+      try{if(snapshot)owner=JSON.parse(snapshot.bytes.toString('utf8'));}catch{}
+      if(attempt===0&&allowStaleRecovery&&snapshot&&owner&&Number.isInteger(owner.pid)&&owner.pid>0){
+        if(process.platform!=='win32')throw new Error('authority epoch mutation locked (POSIX automatic recovery disabled)');
+        const {validForegroundIdentity,foregroundIdentityMatches}=await import('./foreground-process-identity.mjs');
+        if(!validForegroundIdentity(owner.owner_identity)||owner.owner_identity.pid!==owner.pid)
+          throw new Error('authority epoch mutation locked (owner identity unverified)');
+        const observed=await windowsEpochOwnerIdentity(owner.pid);
+        if(observed){
+          if(!foregroundIdentityMatches(owner.owner_identity,observed))
+            throw new Error('authority epoch mutation locked (owner process birth changed)');
+          throw new Error('authority epoch mutation locked (owner still active)');
+        }
+        await stage('stale_before_cas');
+        const disposition=await disposeObservedEpochLock(lockPath,snapshot);
+        if(disposition!=='REMOVED')throw new Error(`authority epoch mutation locked (stale owner changed: ${disposition})`);
         continue;
       }
       throw new Error('authority epoch mutation locked');
@@ -310,12 +484,40 @@ async function acquireEpochLock(dir){
   }
   throw new Error('authority epoch mutation locked');
 }
-async function readDurableHead(runtimeDir,plane){
+const MAX_DURABLE_EPOCH_RECORD_BYTES=1048576;
+
+async function readBoundedEpochHandle(handle,label){
+    const stat=await handle.stat();
+    if(!stat.isFile()||!Number.isSafeInteger(stat.size)||stat.size>MAX_DURABLE_EPOCH_RECORD_BYTES)
+      throw new Error(`authority epoch ${label} oversized`);
+    // Read at most the observed size plus one byte. A concurrent extension
+    // cannot turn this into an unbounded read, and is rejected rather than
+    // silently truncating the record that will be hashed or parsed.
+    const bytes=Buffer.alloc(stat.size+1);
+    let used=0;
+    while(used<bytes.length){
+      const {bytesRead}=await handle.read(bytes,used,bytes.length-used,used);
+      if(bytesRead===0)break;
+      used+=bytesRead;
+    }
+    if(used!==stat.size)throw new Error(`authority epoch ${label} changed during read`);
+    return bytes.subarray(0,used);
+}
+
+async function readBoundedEpochRecord(file,label){
+  const handle=await open(file,'r');
+  try{
+    return await readBoundedEpochHandle(handle,label);
+  }finally{await handle.close();}
+}
+
+async function readDurableHead(runtimeDir,plane,{recoveryOrphanFile=null}={}){
   const dir=durableEpochDir(runtimeDir,plane),headPath=path.join(dir,'head.json');
   let head;
-  try{head=JSON.parse(await readFile(headPath,'utf8'));}
+  try{head=JSON.parse(decodeUtf8Strict(await readBoundedEpochRecord(headPath,'head')));}
   catch(error){
     if(error?.code==='ENOENT')return null;
+    if(String(error?.message??'').includes('authority epoch head oversized'))throw error;
     throw new Error('authority epoch head invalid');
   }
   if(!plain(head)||head.schema!==DURABLE_HEAD_SCHEMA||head.plane!==plane||
@@ -334,7 +536,8 @@ async function readDurableHead(runtimeDir,plane){
   // the head. The head remains freshly read on every authority decision.
   const [eventNames,eventRead,keys]=await Promise.all([
     readdir(path.join(dir,'events')),
-    readFile(path.join(dir,'events',head.event_file)).then(bytes=>({bytes}),()=>({bytes:null})),
+    readBoundedEpochRecord(path.join(dir,'events',head.event_file),'event')
+      .then(bytes=>({bytes}),error=>({error})),
     durableEpochKeys(runtimeDir)
   ]);
   if(eventNames.length>10000)throw new Error('authority epoch event budget exceeded');
@@ -342,11 +545,14 @@ async function readDurableHead(runtimeDir,plane){
     const match=/^(\d{16})-([0-9a-f]{64})\.json$/.exec(name);
     if(!match)throw new Error('authority epoch unexpected event file');
     const seq=Number(match[1]);
-    if(!Number.isSafeInteger(seq)||seq>head.seq||(seq===head.seq&&name!==head.event_file))
+    if(!Number.isSafeInteger(seq)||(seq>head.seq&&name!==recoveryOrphanFile)||(seq===head.seq&&name!==head.event_file))
       throw new Error('authority epoch head replay or incomplete write');
   }
+  if(eventRead.error){
+    if(eventRead.error.code==='ENOENT')throw new Error('authority epoch event missing');
+    throw eventRead.error;
+  }
   const eventBytes=eventRead.bytes;
-  if(!eventBytes)throw new Error('authority epoch event missing');
   if(hashBytes(eventBytes)!==head.event_sha256)throw new Error('authority epoch event hash mismatch');
   let event;
   try{event=JSON.parse(decodeUtf8Strict(eventBytes));}catch{throw new Error('authority epoch event invalid');}
@@ -363,30 +569,223 @@ async function readDurableHead(runtimeDir,plane){
       (!SHAPAT.test(String(head.policy_sha256))||!SHAPAT.test(String(head.policy_envelope_sha256))||
        head.policy_sha256!==event.policy_sha256||head.policy_envelope_sha256!==event.policy_envelope_sha256))
     throw new Error('authority epoch policy binding invalid');
-  if(head.seq===1&&head.previous_event_sha256!==null)throw new Error('authority epoch genesis chain invalid');
+  if(head.seq===1){
+    if(head.previous_event_sha256!==null)throw new Error('authority epoch genesis chain invalid');
+    assertEpochTransition(head,null);
+  }
   if(head.seq>1){
     if(!SHAPAT.test(String(head.previous_event_sha256)))throw new Error('authority epoch predecessor missing');
     const priorName=durableEventName(head.seq-1,head.previous_event_sha256);
     let priorBytes;
-    try{priorBytes=await readFile(path.join(dir,'events',priorName));}
-    catch{throw new Error('authority epoch predecessor event missing');}
+    try{priorBytes=await readBoundedEpochRecord(path.join(dir,'events',priorName),'predecessor event');}
+    catch(error){
+      if(error?.code==='ENOENT')throw new Error('authority epoch predecessor event missing');
+      throw error;
+    }
     if(hashBytes(priorBytes)!==head.previous_event_sha256)throw new Error('authority epoch predecessor hash mismatch');
     let prior;
     try{prior=JSON.parse(decodeUtf8Strict(priorBytes));}catch{throw new Error('authority epoch predecessor invalid');}
     if(!verifyDurableEvent(prior,publicKey,keyId)||prior.seq!==head.seq-1||prior.plane!==plane)
       throw new Error('authority epoch predecessor signature invalid');
+    assertEpochPredecessorIdentity(prior);
+    if(prior.seq===1)assertEpochTransition(prior,null);
+    assertEpochTransition(head,prior);
   }
   return Object.freeze({...head});
 }
 
-export function createAuthorityEpochStore({runtimeDir,policyBytes=null}={}){
+// Deliberately separate from the per-request authority decision. This is an
+// independent, bounded audit of the complete signed chain, including events
+// older than the immediate predecessor checked by readDurableHead().
+async function auditDurableHistory(runtimeDir,plane){
+  const dir=durableEpochDir(runtimeDir,plane),events=path.join(dir,'events');
+  const head=await readDurableHead(runtimeDir,plane);
+  if(!head){
+    let names;
+    try{names=await readdir(events);}catch(error){if(error?.code==='ENOENT')return Object.freeze({status:'EMPTY',plane,verified_events:0});throw error;}
+    if(names.length)throw new Error('authority epoch history events exist without head');
+    return Object.freeze({status:'EMPTY',plane,verified_events:0});
+  }
+  if(head.seq>10000)throw new Error('authority epoch history event budget exceeded');
+  const headPath=path.join(dir,'head.json'),headBytes=await readBoundedEpochRecord(headPath,'head');
+  let pinnedHead;
+  try{pinnedHead=JSON.parse(decodeUtf8Strict(headBytes));}catch{throw new Error('authority epoch history head changed');}
+  if(canonicalJson(pinnedHead)!==canonicalJson(head))throw new Error('authority epoch history head changed');
+  const names=await readdir(events);
+  if(names.length!==head.seq)throw new Error('authority epoch history event count mismatch');
+  const namesSet=new Set(names);
+  const {publicKey,keyId}=await durableEpochKeys(runtimeDir);
+  let expectedSha=head.event_sha256,totalBytes=0,newer=null;
+  for(let seq=head.seq;seq>=1;seq--){
+    const name=durableEventName(seq,expectedSha);
+    if(!namesSet.has(name))throw new Error('authority epoch history event missing');
+    const file=path.join(events,name),st=await lstat(file);
+    if(!st.isFile()||st.isSymbolicLink()||st.size>1048576)
+      throw new Error('authority epoch history event identity invalid');
+    totalBytes+=st.size;
+    if(totalBytes>67108864)throw new Error('authority epoch history byte budget exceeded');
+    const bytes=await readBoundedEpochRecord(file,'event');
+    if(hashBytes(bytes)!==expectedSha)throw new Error('authority epoch history hash mismatch');
+    let event;
+    try{event=JSON.parse(decodeUtf8Strict(bytes));}catch{throw new Error('authority epoch history event invalid');}
+    if(!verifyDurableEvent(event,publicKey,keyId)||event.schema!==DURABLE_EPOCH_SCHEMA||
+        event.plane!==plane||event.seq!==seq||!DURABLE_EPOCH_ACTIONS.has(event.action)||
+        !SHAPAT.test(String(event.grant_sha256))||!SHAPAT.test(String(event.grant_instance_nonce)))
+      throw new Error('authority epoch history event signature or identity invalid');
+    normalizeRestoreBinding(event.restore_binding,{required:event.action==='transaction_restore'});
+    if((event.action.startsWith('transaction_')?!/^[A-Za-z0-9._-]{1,96}$/.test(String(event.update_id??'')):event.update_id!==null))
+      throw new Error('authority epoch history update identity invalid');
+    if(event.policy_sha256!==undefined||event.policy_envelope_sha256!==undefined){
+      if(!SHAPAT.test(String(event.policy_sha256))||!SHAPAT.test(String(event.policy_envelope_sha256)))
+        throw new Error('authority epoch history policy binding invalid');
+    }
+    if(seq===1){
+      if(event.previous_event_sha256!==null)throw new Error('authority epoch history genesis chain invalid');
+    }else if(!SHAPAT.test(String(event.previous_event_sha256)))
+      throw new Error('authority epoch history predecessor missing');
+    if(newer)assertEpochTransition(newer,event);
+    else if(seq===1)assertEpochTransition(event,null);
+    newer=event;
+    expectedSha=event.previous_event_sha256;
+  }
+  if(newer&&head.seq>1)assertEpochTransition(newer,null);
+  if(!(await readBoundedEpochRecord(headPath,'head')).equals(headBytes))throw new Error('authority epoch history head changed during audit');
+  if((await durableEpochKeys(runtimeDir)).keyId!==keyId)throw new Error('authority epoch history trust changed during audit');
+  return Object.freeze({status:'PASS',plane,seq:head.seq,event_sha256:head.event_sha256,
+    verified_events:head.seq,verified_bytes:totalBytes});
+}
+
+// R79: An orphan event is not a committed head. Ordinary reads, verification
+// and appends MUST keep rejecting it. Only explicit revocation-only recovery
+// can use the bounded exception to inspect an older, still-signed head.
+async function inspectOrphanRevocation(runtimeDir,plane,{expectedHeadSha256,expectedOrphanSha256}){
+  if(!SCHEMAS[plane]||!SHAPAT.test(String(expectedHeadSha256))||!SHAPAT.test(String(expectedOrphanSha256)))
+    throw new Error('authority epoch recovery requires exact signed event identities');
+  const dir=durableEpochDir(runtimeDir,plane),events=path.join(dir,'events');
+  // Reject known static reparse/junction boundaries. Handle-pinned directory
+  // protection for concurrent substitutions is a separate Windows requirement.
+  for(const parent of [path.resolve(runtimeDir),path.join(path.resolve(runtimeDir),'authority-epochs'),dir,events]){
+    const st=await lstat(parent);
+    if(!st.isDirectory()||st.isSymbolicLink())throw new Error('authority epoch recovery directory identity invalid');
+  }
+  const headPath=path.join(dir,'head.json');
+  const headStat=await lstat(headPath);
+  if(!headStat.isFile()||headStat.isSymbolicLink())throw new Error('authority epoch recovery head identity invalid');
+  const rawHead=await readBoundedEpochRecord(headPath,'head');
+  let untrusted;
+  try{untrusted=JSON.parse(decodeUtf8Strict(rawHead));}catch{throw new Error('authority epoch recovery head invalid');}
+  if(!Number.isSafeInteger(untrusted?.seq)||untrusted.seq<1)
+    throw new Error('authority epoch recovery head invalid');
+  const names=await readdir(events);
+  // Do not accept more than one event beyond the old head, even if signed.
+  const orphanNames=names.filter(name=>{
+    const m=/^(\d{16})-([0-9a-f]{64})\.json$/.exec(name);
+    return m&&Number(m[1])>untrusted.seq;
+  });
+  if(orphanNames.length!==1)throw new Error('authority epoch recovery requires exactly one orphan event');
+  const orphanFile=orphanNames[0];
+  if(orphanFile!==durableEventName(untrusted.seq+1,expectedOrphanSha256))
+    throw new Error('authority epoch recovery orphan identity mismatch');
+  const previous=await readDurableHead(runtimeDir,plane,{recoveryOrphanFile:orphanFile});
+  if(!previous||previous.event_sha256!==expectedHeadSha256||previous.seq!==untrusted.seq)
+    throw new Error('authority epoch recovery previous head mismatch');
+  if(!['grant','transaction_restore','transaction_revoke'].includes(previous.action))
+    throw new Error('authority epoch recovery previous action invalid');
+  const orphanPath=path.join(events,orphanFile);
+  const orphanStat=await lstat(orphanPath);
+  if(!orphanStat.isFile()||orphanStat.isSymbolicLink())throw new Error('authority epoch recovery orphan file identity invalid');
+  const orphanBytes=await readBoundedEpochRecord(orphanPath,'event');
+  if(hashBytes(orphanBytes)!==expectedOrphanSha256)
+    throw new Error('authority epoch recovery orphan bytes mismatch');
+  let event;
+  try{event=JSON.parse(decodeUtf8Strict(orphanBytes));}catch{throw new Error('authority epoch recovery orphan invalid');}
+  const {publicKey,keyId}=await durableEpochKeys(runtimeDir);
+  if(!verifyDurableEvent(event,publicKey,keyId))
+    throw new Error('authority epoch recovery orphan signature invalid');
+  if(event.schema!==DURABLE_EPOCH_SCHEMA||event.plane!==plane||event.seq!==previous.seq+1||
+      !['transaction_revoke','user_revoke'].includes(event.action)||
+      (event.action==='transaction_revoke'&&!/^[A-Za-z0-9._-]{1,96}$/.test(String(event.update_id??'')))||
+      (event.action==='user_revoke'&&event.update_id!==null)||
+      event.previous_event_sha256!==previous.event_sha256||
+      event.grant_sha256!==previous.grant_sha256||event.grant_instance_nonce!==previous.grant_instance_nonce||
+      event.policy_sha256!==previous.policy_sha256||event.policy_envelope_sha256!==previous.policy_envelope_sha256||
+      event.restore_binding!==null||
+      (event.action==='transaction_revoke'&&!['grant','transaction_restore'].includes(previous.action)))
+    throw new Error('authority epoch recovery orphan revocation binding invalid');
+  // Head cannot be promoted unless it is still exactly the same committed
+  // predecessor. No authority-creating action is ever eligible.
+  const replay=await readBoundedEpochRecord(headPath,'head');
+  if(!replay.equals(rawHead))throw new Error('authority epoch recovery head changed');
+  const newHead={schema:DURABLE_HEAD_SCHEMA,plane,seq:event.seq,action:event.action,
+    update_id:event.update_id,grant_sha256:event.grant_sha256,
+    grant_instance_nonce:event.grant_instance_nonce,restore_binding:null,
+    ...(event.policy_sha256===undefined?{}:{policy_sha256:event.policy_sha256,policy_envelope_sha256:event.policy_envelope_sha256}),
+    previous_event_sha256:event.previous_event_sha256,event_sha256:expectedOrphanSha256,event_file:orphanFile};
+  return Object.freeze({previous,newHead,headBytes:rawHead,orphanBytes});
+}
+
+export function createAuthorityEpochStore({runtimeDir,policyBytes=null,onDurabilityStage=null,onLockDispositionStage=null}={}){
   const root=path.resolve(String(runtimeDir??''));
   if(!runtimeDir)throw new Error('authority epoch runtime directory invalid');
   if(policyBytes!==null&&!Buffer.isBuffer(policyBytes))throw new Error('authority epoch policy bytes invalid');
+  if(onDurabilityStage!==null&&(typeof onDurabilityStage!=='function'||process.env.NODE_TEST_CONTEXT!=='child-v8'))
+    throw new Error('authority epoch stage observer is restricted to node test workers');
+  if(onLockDispositionStage!==null&&(typeof onLockDispositionStage!=='function'||process.env.NODE_TEST_CONTEXT!=='child-v8'))
+    throw new Error('authority epoch lock observer is restricted to node test workers');
+  // Node-test-worker-only fault observer. It can abort, never bypass, flush/order checks.
+  const stage=async name=>{if(onDurabilityStage)await onDurabilityStage(name);};
   return Object.freeze({
     async readHead({plane}){
       return readDurableHead(root,plane);
     },
+    async auditHistory({plane}){
+      return auditDurableHistory(root,plane);
+    },
+    async reconcileOrphanedRevocation({plane,expectedHeadSha256,expectedOrphanSha256,operatorConfirmed=false}){
+      // NOT called from grant verification, append, startup or automatic
+      // recovery. The operator must supply two observed event identities.
+      if(operatorConfirmed!==true)throw new Error('authority epoch recovery requires explicit operator confirmation');
+      const dir=durableEpochDir(root,plane);
+      // Reject wrong or stale operator evidence before even reclaiming a dead
+      // owner's lock. This is a read-only preflight, not an ownership proof;
+      // the same exact evidence is independently rechecked under the lock.
+      await inspectOrphanRevocation(root,plane,{expectedHeadSha256,expectedOrphanSha256});
+      // Explicit, identity-bound revocation reconciliation may reclaim a
+      // verified dead owner's lock through the same native stale-owner CAS as
+      // append. A live or unverified owner still fails closed. The orphan
+      // itself is inspected only after exclusive ownership is established.
+      const release=await acquireEpochLock(dir,{allowStaleRecovery:true,onLockDispositionStage});
+      try{
+        const {newHead,headBytes,orphanBytes}=await inspectOrphanRevocation(root,plane,{expectedHeadSha256,expectedOrphanSha256});
+        // Windows FlushFileBuffers requires a writable file handle. The old
+        // read-only ('r') handle returned EPERM on Windows even for a valid,
+        // signed revocation. 'r+' grants the handle sync rights; we do not
+        // write event bytes. Revalidate exact bytes through this same handle
+        // before syncing, refusing a replaced or modified orphan event.
+        // Directory/power-loss durability is NOT proven here.
+        const fh=await open(path.join(dir,'events',newHead.event_file),'r+');
+        try{
+          const st=await fh.stat();
+          if(!st.isFile()||st.size!==orphanBytes.length)
+            throw new Error('authority epoch recovery pinned orphan identity invalid');
+          const pinnedBytes=await readBoundedEpochHandle(fh,'event');
+          if(!pinnedBytes.equals(orphanBytes)||hashBytes(pinnedBytes)!==expectedOrphanSha256)
+            throw new Error('authority epoch recovery orphan changed before sync');
+          await fh.sync();
+        }finally{await fh.close();}
+        if(!(await readBoundedEpochRecord(path.join(dir,'head.json'),'head')).equals(headBytes))
+          throw new Error('authority epoch recovery head changed before commit');
+        await release.verifyOwned();
+        await atomicJsonWrite(path.join(dir,'head.json'),newHead,{stage});
+        const committed=await readDurableHead(root,plane);
+        if(committed.event_sha256!==expectedOrphanSha256||
+            !['transaction_revoke','user_revoke'].includes(committed.action))
+          throw new Error('authority epoch recovered head re-verification failed');
+        return Object.freeze({status:'REVOKED_ONLY_RECONCILED',plane,seq:committed.seq,
+          action:committed.action,event_sha256:committed.event_sha256,
+          standing_grant_authorized:false});
+      }finally{await release();}
+    },
     async append({plane,action,grantBytes,grantInstanceNonce,updateId=null,expectedHeadSha256=undefined,restoreBinding=null}){
       const transactional=action?.startsWith('transaction_')===true;
       if(!SCHEMAS[plane]||!DURABLE_EPOCH_ACTIONS.has(action)||!Buffer.isBuffer(grantBytes)||
@@ -409,8 +808,13 @@ export function createAuthorityEpochStore({runtimeDir,policyBytes=null}={}){
         if(parsedGrant?.policy_sha256!==policySha256)throw new Error('authority epoch grant policy digest mismatch');
         policyBinding={policy_sha256:policySha256,policy_envelope_sha256:deriveSecurityEnvelope(plane,parsedPolicy).sha256};
       }
+      // A mismatched successor envelope is known before acquiring a native
+      // lock or writing any signed event. Refuse it without side effects.
+      if(action==='transaction_restore'&&policyBinding?.policy_envelope_sha256!==undefined&&
+          normalizedRestoreBinding.successor_policy_envelope_sha256!==policyBinding.policy_envelope_sha256)
+        throw new Error('authority epoch transaction restore successor policy envelope mismatch');
       const dir=durableEpochDir(root,plane),events=path.join(dir,'events');
-      const release=await acquireEpochLock(dir);
+      const release=await acquireEpochLock(dir,{onLockDispositionStage});
       try{
         await mkdir(events,{recursive:true});
         const previous=await readDurableHead(root,plane);
@@ -433,6 +837,12 @@ export function createAuthorityEpochStore({runtimeDir,policyBytes=null}={}){
             throw new Error('authority epoch transaction restore predecessor grant binding mismatch');
           if(previous.grant_instance_nonce===grantInstanceNonce)
             throw new Error('authority epoch transaction restore requires fresh nonce; revoked nonce cannot be resurrected');
+          if(previous.policy_envelope_sha256!==undefined&&
+              normalizedRestoreBinding.predecessor_policy_envelope_sha256!==previous.policy_envelope_sha256)
+            throw new Error('authority epoch transaction restore predecessor policy envelope mismatch');
+          if(policyBinding?.policy_envelope_sha256!==undefined&&
+              normalizedRestoreBinding.successor_policy_envelope_sha256!==policyBinding.policy_envelope_sha256)
+            throw new Error('authority epoch transaction restore successor policy envelope mismatch');
         }
         if(action==='grant'&&previous?.grant_instance_nonce===grantInstanceNonce)
           throw new Error('authority epoch grant requires fresh nonce; prior nonce cannot be resurrected');
@@ -445,12 +855,15 @@ export function createAuthorityEpochStore({runtimeDir,policyBytes=null}={}){
         const event={...body,attestation:{algorithm:'ed25519',domain:'DEADBYTE-AUTHORITY-DURABLE-EPOCH-R65-V1',key_id:keyId,signature_base64:signature.toString('base64')}};
         const eventBytes=Buffer.from(canonicalJson(event),'utf8'),eventSha256=hashBytes(eventBytes);
         const eventFile=durableEventName(seq,eventSha256);
-        await writeFile(path.join(events,eventFile),eventBytes,{flag:'wx'});
+        await writeDurableEvent(path.join(events,eventFile),eventBytes,{stage});
         const head={schema:DURABLE_HEAD_SCHEMA,plane,seq,action,update_id:updateId,
           grant_sha256:grantSha256,grant_instance_nonce:grantInstanceNonce,restore_binding:normalizedRestoreBinding,
           ...(policyBinding??{}),
           previous_event_sha256:event.previous_event_sha256,event_sha256:eventSha256,event_file:eventFile};
-        await atomicJsonWrite(path.join(dir,'head.json'),head);
+        // A replaced lock observed before publication must not authorize a
+        // head commit. This narrows the window but is not a held-handle lock.
+        await release.verifyOwned();
+        await atomicJsonWrite(path.join(dir,'head.json'),head,{stage});
         return Object.freeze({...head});
       }finally{await release();}
     },