@6reduk/workspace-pipeline 0.1.0

package/src/operations/repository-apply.js

@@ -0,0 +1,122 @@
+import path from 'node:path';
+import { mkdir,open,rename,lstat } from 'node:fs/promises';
+import { fail,ContractError,MAX_INPUT_BYTES } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { sha256 } from '../source/inventory.js';
+import { inspectDirectory,resolveChild } from '../workspace/paths.js';
+import { inventoryRepository } from '../workspace/repository-inventory.js';
+import { inspectRepositoryDestination } from '../workspace/repository-preflight.js';
+import { revalidateRepositoryPreview } from '../workspace/repository-preview.js';
+import { acquireBootstrapLock,assertBootstrapLockHeld } from './bootstrap-lock.js';
+import { acquireWorkspaceLock,assertLockHeld } from './lock.js';
+import { createRepositoryJournal,readRepositoryJournal } from './repository-journal.js';
+import { readRecord } from './state.js';
+import { runGit } from '../source/git.js';
+import { inspectRepositoryGit } from '../workspace/repository-preflight.js';
+import { materializeRepositoryClone,verifyClonedRepository } from './repository-clone.js';
+import { persistRepositoryInputs } from './repository-inputs.js';
+import {summarizeInventory,repositoryContentDigest} from '../workspace/repository-observation.js';
+export {repositoryContentDigest} from '../workspace/repository-observation.js';
+
+const absent=async filename=>{try{await lstat(filename);return false;}catch(e){if(e.code==='ENOENT')return true;throw e;}};
+// Rename changes root timestamps. Content/mode projection is deliberately separate
+// from exact prewrite identity inventory; every file and empty directory remains.
+const content=repositoryContentDigest;
+export function matchesInitializedRepository(operation,inventory) {
+  return operation.initialization?.initialBranch==='main' && operation.initialization?.templates==='disabled' &&
+    inventory.entries.some(e=>e.path==='.git' && e.type==='directory') &&
+    inventory.entries.some(e=>e.path==='.git/HEAD' && e.sha256===sha256(Buffer.from('ref: refs/heads/main\n')).slice(7)) &&
+    inventory.entries.every(e=>e.path==='.' || e.path==='.git' || e.path.startsWith('.git/')) &&
+    !inventory.entries.some(e=>e.type==='file' && (e.path.startsWith('.git/refs/') || e.path==='.git/index' || e.path==='.git/packed-refs'));
+}
+async function persist(filename,value) {
+  const bytes=Buffer.from(JSON.stringify(value)+'\n');if(bytes.length>MAX_INPUT_BYTES)fail('repository-apply.evidence-size');
+  const handle=await open(filename,'wx',0o600);
+  try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+  const record=await readRecord(filename);if(record.digest!==sha256(bytes))fail('repository-apply.readback');return record.digest;
+}
+
+// Internal first execution slice: existing wrapper, existing direct target parents,
+// keep/directory/init/pinned clone/same-device move. Unsupported actions refuse BEFORE lock writes.
+// An unresolved operation marker always blocks a new run; recovery owns its removal.
+export async function applyRepositoryOperations({pipeline,workspace,wrapper,choices,options={},previewText,approval,
+  onLocation=async()=>{},ioBoundary=async()=>{}}) {
+  if(!approval || Object.keys(approval).sort().join(',')!=='decision,previewDigest' || approval.decision!=='approve')fail('repository-apply.approval');
+  const validate=()=>revalidateRepositoryPreview(previewText,approval.previewDigest,pipeline,workspace,wrapper,choices,options);
+  const preview=await validate();
+  if(!preview.manifest)fail('repository-apply.manifest-required');
+  if(!(await inspectDirectory(preview.wrapper)).exists)fail('repository-apply.bootstrap-required');
+  for(const op of preview.operations) {
+    if(!['keep','directory','init','clone','move'].includes(op.action))fail('repository-apply.action-not-implemented');
+    if(!(await inspectDirectory(path.dirname(op.target))).exists)fail('repository-apply.parent-required');
+  }
+  const marker=resolveChild(preview.wrapper,'.pipeline/repository-operation.json');
+  if(!await absent(marker))fail('repository-apply.pending');
+  let bootstrap,lock,journal;
+  try {
+    bootstrap=await acquireBootstrapLock(preview.wrapper,{onLocation});
+    lock=await acquireWorkspaceLock(preview.wrapper,{repositoryOperation:bootstrap});
+    await assertBootstrapLockHeld(bootstrap);await validate();
+    if(!await absent(marker))fail('repository-apply.pending');
+    journal=await createRepositoryJournal(lock,preview,{onLocation});
+    await persistRepositoryInputs(preview.wrapper,journal.relative,preview);
+    await ioBoundary('repository-inputs-persisted',{journal:journal.relative,previewDigest:preview.digest});
+    await persist(marker,{schemaVersion:1,previewDigest:preview.digest,journal:journal.relative,status:'requires-reconciliation'});
+    const authorization=await ioBoundary('repository-run-started',{journal:journal.relative,previewDigest:preview.digest});
+    if(authorization!==undefined)await journal.authorize(authorization);
+    await assertBootstrapLockHeld(bootstrap);await assertLockHeld(lock);
+    const evidenceRoot=resolveChild(preview.wrapper,'.pipeline/repository-evidence');
+    try{await mkdir(evidenceRoot);}catch(e){if(e.code!=='EEXIST')throw e;}
+    await inspectDirectory(evidenceRoot);
+    const evidenceDirectory=path.join(evidenceRoot,path.basename(journal.directory));await mkdir(evidenceDirectory);
+    await onLocation({directory:evidenceDirectory,status:'evidence-created'});
+    for(let index=0;index<preview.operations.length;index++) {
+      const op=preview.operations[index];
+      await assertBootstrapLockHeld(bootstrap);await assertLockHeld(lock);
+      await journal.intent(op.repository);
+      // Error here leaves an intent without outcome: uncertain, never auto-retry.
+      await ioBoundary('before-effect',{repository:op.repository});
+      await assertBootstrapLockHeld(bootstrap);await assertLockHeld(lock);
+      if(op.existing && (await inventoryRepository(op.existing.inventory.root)).digest!==op.existing.inventory.digest)fail('repository-apply.source-drift');
+      if(op.destination && contractDigest(await inspectRepositoryDestination(op.target))!==contractDigest(op.destination))fail('repository-apply.destination-drift');
+      if(op.action==='directory')await mkdir(op.target);
+      else if(op.action==='clone')await materializeRepositoryClone(op,lock,bootstrap,ioBoundary);
+      else if(op.action==='init') {
+        await mkdir(op.target);
+        await ioBoundary('init-directory-created',{repository:op.repository});
+        await assertBootstrapLockHeld(bootstrap);await assertLockHeld(lock);
+        if((await inventoryRepository(op.target)).entries.length!==1)fail('repository-apply.init-target-drift');
+        await runGit(op.target,['init','--template=','--initial-branch='+op.initialization.initialBranch]);
+      }
+      else if(op.action==='move')await rename(op.from,op.target);
+      await ioBoundary('after-effect',{repository:op.repository});
+      await assertBootstrapLockHeld(bootstrap);await assertLockHeld(lock);
+      const observed=await inventoryRepository(op.target);
+      if(op.action==='directory' && observed.entries.length!==1)fail('repository-apply.postcondition');
+      if(op.action==='clone' && !await verifyClonedRepository(op,observed))fail('repository-apply.postcondition');
+      if(op.action==='init') {
+        const git=await inspectRepositoryGit(op.target);
+        if(!matchesInitializedRepository(op,observed) || git.head!==null || git.dirty || git.blockers.length || git.inventory.digest!==observed.digest)
+          fail('repository-apply.postcondition');
+      }
+      if(op.action==='move' && (!await absent(op.from) || content(observed)!==content(op.existing.inventory)))fail('repository-apply.postcondition');
+      if(op.action==='keep' && observed.digest!==op.existing.inventory.digest)fail('repository-apply.postcondition');
+      const evidence={schemaVersion:1,previewDigest:preview.digest,repository:op.repository,action:op.action,
+        target:op.target,sourceAbsent:op.action==='move'?true:null,contentDigest:content(observed),inventory:summarizeInventory(observed)};
+      const evidenceDigest=await persist(path.join(evidenceDirectory,String(index).padStart(6,'0')+'.json'),evidence);
+      await ioBoundary('evidence-persisted',{repository:op.repository});
+      await journal.outcome('completed',evidenceDigest);
+    }
+    const result=await readRepositoryJournal(preview.wrapper,journal.relative,preview);
+    return {status:'effects-completed',journal:journal.relative,evidenceDirectory,result,
+      requiresReconciliation:true,pipelineActivated:false};
+  }catch(cause){
+    const error=cause instanceof ContractError?cause:new ContractError(cause.code==='EBUSY'?
+      'repository-apply.busy':['EACCES','EPERM'].includes(cause.code)?'repository-apply.access-denied':'repository-apply.io');
+    if(journal)error.repositoryJournal=journal.relative;
+    throw error;
+  }finally{
+    // Exact lock releases only, never rollback filesystem effects or clear marker.
+    try{if(lock)await lock.release();}finally{if(bootstrap)await bootstrap.release();}
+  }
+}

package/src/operations/repository-authorization.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { fail } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { resolveChild,inspectDirectory } from '../workspace/paths.js';
+import { readRecord } from './state.js';
+
+const same=(a,b)=>contractDigest(a)===contractDigest(b);
+const exact=(value,keys)=>value && typeof value==='object' && !Array.isArray(value) &&
+  Object.keys(value).sort().join(',')===[...keys].sort().join(',');
+export async function verifyRepositoryAuthorization(wrapper,journal,preview,binding) {
+  if(!binding)return [];
+  const expectedPath=journal.replace('/repository-journals/','/repository-authorizations/')+'.json';
+  if(!exact(binding,['path','digest']) || binding.path!==expectedPath)fail('repository-authorization.binding');
+  const record=await readRecord(resolveChild(wrapper,binding.path)),chain=record.value;
+  if(record.digest!==binding.digest || !exact(chain,['schemaVersion','kind','originalPreview','originalApproval','derivedPreview',
+    'bootstrapReceiptDigest','bootstrapIntentDigest','journal','newHumanApproval']) || chain.schemaVersion!==1 ||
+    chain.kind!=='wrapper-creation-projection' || chain.journal!==journal || chain.newHumanApproval!==false ||
+    !same(chain.derivedPreview,preview))fail('repository-authorization.chain');
+  const original=chain.originalPreview;
+  if(!original || typeof original!=='object' || Array.isArray(original))fail('repository-authorization.original');
+  const {digest,...body}=original;
+  if(contractDigest(body)!==digest || original.wrapper!==wrapper || original.wrapperObservation?.action!=='create' ||
+    original.wrapperObservation.target!==wrapper || original.kind!=='repository-preview-candidate' ||
+    original.executionAuthorized!==false || original.status!=='review-only' || !Array.isArray(original.blockers) ||
+    original.blockers.length || !Array.isArray(original.operations) ||
+    !same(chain.originalApproval,{decision:'approve',previewDigest:digest}))fail('repository-authorization.original');
+  const receiptPath='.pipeline/repository-bootstrap.json',intentPath='.pipeline/repository-bootstrap-intent.json';
+  const receipt=await readRecord(resolveChild(wrapper,receiptPath)),intent=await readRecord(resolveChild(wrapper,intentPath));
+  if(receipt.digest!==chain.bootstrapReceiptDigest || intent.digest!==chain.bootstrapIntentDigest ||
+    !same(intent.value,{schemaVersion:1,kind:'wrapper-create-intent',previewDigest:digest,wrapper,
+      before:original.wrapperObservation,compensation:'no-automatic-rollback'}))fail('repository-authorization.bootstrap');
+  await inspectDirectory(wrapper);await inspectDirectory(path.join(wrapper,'.pipeline'));
+  const root=await lstat(wrapper,{bigint:true}),metadata=await lstat(path.join(wrapper,'.pipeline'),{bigint:true});
+  const identity={dev:String(root.dev),ino:String(root.ino)};
+  if(!same(receipt.value,{schemaVersion:1,kind:'wrapper-created',previewDigest:digest,wrapper,identity,
+    metadataIdentity:{dev:String(metadata.dev),ino:String(metadata.ino)},intentDigest:intent.digest,
+    pipelineActivated:false,repositoryEffectsPerformed:false}))fail('repository-authorization.bootstrap');
+  const derived=structuredClone(body);
+  derived.wrapperObservation={action:'keep',path:wrapper,identity};
+  for(const op of derived.operations) {
+    if(path.dirname(op.target)!==wrapper || !op.destination || op.destination.ancestor!==path.dirname(wrapper) ||
+      !same(op.destination.ancestorIdentity,original.wrapperObservation.ancestorIdentity))fail('repository-authorization.projection');
+    op.destination={...op.destination,ancestor:wrapper,ancestorIdentity:identity};
+  }
+  if(!same({...derived,digest:contractDigest(derived)},preview))fail('repository-authorization.projection');
+  return [binding,{path:receiptPath,digest:receipt.digest},{path:intentPath,digest:intent.digest}];
+}

package/src/operations/repository-bootstrap-continuation.js

@@ -0,0 +1,190 @@
+import path from 'node:path';
+import {hostname} from 'node:os';
+import {lstat,open,rename,readdir} from 'node:fs/promises';
+import {fail,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {absoluteRoot,inspectDirectory,pathBudget} from '../workspace/paths.js';
+import {inventoryRepository} from '../workspace/repository-inventory.js';
+import {bootstrapLockDirectory} from './bootstrap-lock.js';
+import {readRecord} from './state.js';
+import {withRecoveryLease,assertRecoveryLeaseHeld} from './recovery-lease.js';
+import {sha256} from '../source/inventory.js';
+
+const equal=(a,b)=>contractDigest(a)===contractDigest(b);
+const rootId=inv=>{const s=inv?.entries.find(e=>e.path==='.')?.identity;return s?{dev:s.dev,ino:s.ino}:null;};
+const stopped=owner=>{
+  if(owner?.host!==hostname() || !Number.isSafeInteger(owner.pid) || owner.pid<=0)return false;
+  try{process.kill(owner.pid,0);return false;}catch(e){return e.code==='ESRCH';}
+};
+async function inventory(directory){return (await inspectDirectory(directory)).exists?inventoryRepository(directory,{entries:512,bytes:16*1024*1024,depth:8}):null;}
+async function record(filename){try{await lstat(filename);}catch(e){if(e.code==='ENOENT')return null;throw e;}return readRecord(filename);}
+function routes(wrapper,initial) {
+  const retry=initial.status==='before-state-observed',base=bootstrapLockDirectory(wrapper),metadata=path.join(wrapper,'.pipeline');
+  const archive=retry?path.join(path.dirname(wrapper),'.wpc-bootstrap-history-'+initial.digest.slice(7)):
+    path.join(metadata,'repository-bootstrap-recovered-lock');
+  const result={base,gate:base+'.recovery',metadata,archive,retry,
+    history:path.join(path.dirname(wrapper),'.wpc-bootstrap-recovery-'+initial.digest.slice(7)),
+    intent:path.join(metadata,'repository-bootstrap-intent.json'),
+    receipt:retry?path.join(archive,'recovery.json'):path.join(metadata,'repository-bootstrap-recovery.json')};
+  for(const value of Object.values(result))if(typeof value==='string')pathBudget(value);
+  return result;
+}
+function expectedReceipt(wrapper,initial,r) {
+  return r.retry?{schemaVersion:1,kind:'wrapper-bootstrap-attempt-archived',wrapper,previewDigest:initial.previewDigest,
+    reconciliationDigest:initial.digest,archive:r.archive,ownerDigest:initial.recordDigests.owner,
+    intentDigest:initial.recordDigests.externalIntent,ownerLiveness:'local-pid-absent',wrapperAbsentAtCheck:true,
+    attemptCompleted:false,pipelineActivated:false}:{schemaVersion:1,kind:'wrapper-bootstrap-recovered',wrapper,
+    previewDigest:initial.previewDigest,reconciliationDigest:initial.digest,ownerDigest:initial.recordDigests.owner,
+    originalReceiptDigest:initial.recordDigests.receipt,archive:r.archive,ownerLiveness:'local-pid-absent',
+    pipelineActivated:false,repositoryEffectsPerformed:false};
+}
+
+// Read-only reconstruction from the original request, not inference from an empty
+// wrapper. Completed history requires its exact initial reconciliation digest.
+export async function inspectBootstrapRecovery({wrapper,initialDigest}) {
+  wrapper=absoluteRoot(wrapper);
+  if(initialDigest!==undefined && !/^sha256:[a-f0-9]{64}$/.test(initialDigest))fail('bootstrap-continue.initial-digest');
+  const observe=async()=>{
+    const gate=bootstrapLockDirectory(wrapper)+'.recovery',active=await inventory(gate);
+    if(!active && !initialDigest)fail('bootstrap-continue.initial-digest-required');
+    const directory=active?gate:path.join(path.dirname(wrapper),'.wpc-bootstrap-recovery-'+initialDigest.slice(7));
+    const guard=active??await inventory(directory);
+    if(!guard)fail('bootstrap-continue.missing');
+    const request=await record(path.join(directory,'request.json')),owner=await record(path.join(directory,'owner.json'));
+    if(!request || !owner)fail('bootstrap-continue.request-incomplete');
+    const value=request.value,initial=value.initial,preview=value.preview;
+    if(!initial || !preview)fail('bootstrap-continue.request');
+    const {digest,...body}=initial,{digest:pd,...pb}=preview;
+    if(value.schemaVersion!==1 || Object.keys(value).sort().join(',')!=='approval,initial,preview,schemaVersion' ||
+      !equal(value.approval,{decision:'approve',reconciliationDigest:digest}) || contractDigest(body)!==digest ||
+      contractDigest(pb)!==pd || initial.previewDigest!==pd || preview.wrapper!==wrapper || initial.wrapper!==wrapper ||
+      (initialDigest!==undefined && initialDigest!==digest) || initial.directory!==bootstrapLockDirectory(wrapper) ||
+      initial.kind!=='repository-bootstrap-reconciliation' || initial.executionAuthorized!==false ||
+      preview.kind!=='repository-preview-candidate' || preview.executionAuthorized!==false ||
+      preview.wrapperObservation?.target!==wrapper || !equal(initial.conflicts,[]) ||
+      !['before-state-observed','receipt-consistent-lock-retained'].includes(initial.status) ||
+      preview.wrapperObservation?.ancestor!==path.dirname(wrapper) || preview.wrapperObservation.action!=='create' ||
+      !equal(owner.value,{pid:owner.value.pid,host:owner.value.host,wrapper,reconciliationDigest:digest}))
+      fail('bootstrap-continue.request');
+    const r=routes(wrapper,initial);
+    if(active && await inventory(r.history))fail('bootstrap-continue.duplicate-gate');
+    const parent=await lstat(path.dirname(wrapper),{bigint:true});
+    if(!equal({dev:String(parent.dev),ino:String(parent.ino)},preview.wrapperObservation.ancestorIdentity))fail('bootstrap-continue.parent-drift');
+    const source=await inventory(r.base),archive=await inventory(r.archive),currentWrapper=await inventory(wrapper);
+    if(Boolean(source)===Boolean(archive))fail('bootstrap-continue.lock-location');
+    const lock=source??archive,lockPath=source?r.base:r.archive;
+    if(!equal(rootId(lock),rootId(initial.observations.lock)))fail('bootstrap-continue.lock-identity');
+    const originalOwner=await record(path.join(lockPath,'owner.json'));
+    if(originalOwner?.digest!==initial.recordDigests.owner)fail('bootstrap-continue.owner-drift');
+    const ext=await record(path.join(lockPath,'intent.json')),hist=r.retry?null:await record(r.intent);
+    const intentDigest=initial.recordDigests.externalIntent??initial.recordDigests.history;
+    if(r.retry ? ext?.digest!==intentDigest : Boolean(ext)===Boolean(hist) || (ext??hist)?.digest!==intentDigest)
+      fail('bootstrap-continue.intent-drift');
+    if(!r.retry && archive && ext)fail('bootstrap-continue.order');
+    const receipt=await record(r.receipt),expected=expectedReceipt(wrapper,initial,r);
+    if(receipt && (!archive || !equal(receipt.value,expected)))fail('bootstrap-continue.receipt');
+    const lockNames=['.','owner.json',...(ext?['intent.json']:[]),...(r.retry && receipt?['recovery.json']:[])].sort();
+    if(!equal(lock.entries.map(e=>e.path).sort(),lockNames))fail('bootstrap-continue.foreign-lock-entry');
+    if(r.retry){if(currentWrapper)fail('bootstrap-continue.wrapper-appeared');}
+    else {
+      const old=initial.observations.wrapper;
+      if(!currentWrapper || !equal(rootId(currentWrapper),rootId(old)))fail('bootstrap-continue.wrapper-drift');
+      const md=inv=>{const e=inv.entries.find(e=>e.path==='.pipeline')?.identity;return e?{dev:e.dev,ino:e.ino}:null;};
+      if(!equal(md(currentWrapper),md(old)))fail('bootstrap-continue.wrapper-drift');
+      const originalReceipt=await record(path.join(r.metadata,'repository-bootstrap.json'));
+      if(originalReceipt?.digest!==initial.recordDigests.receipt)fail('bootstrap-continue.wrapper-drift');
+      const allowed=['.','.pipeline','.pipeline/repository-bootstrap.json',...(hist?['.pipeline/repository-bootstrap-intent.json']:[]),
+        ...(archive?['.pipeline/repository-bootstrap-recovered-lock','.pipeline/repository-bootstrap-recovered-lock/owner.json']:[]),
+        ...(receipt?['.pipeline/repository-bootstrap-recovery.json']:[])];
+      if(!equal(currentWrapper.entries.map(e=>e.path).sort(),allowed.sort()))fail('bootstrap-continue.foreign-wrapper-entry');
+    }
+    if(!active && !receipt)fail('bootstrap-continue.order');
+    const authorizations=[];
+    const names=guard.entries.map(e=>e.path).filter(n=>!['.','owner.json','request.json'].includes(n)).sort();
+    if(names.length>64 || names.some((n,i)=>n!=='authorization-'+String(i+1).padStart(4,'0')+'.json'))fail('bootstrap-continue.authorization-entries');
+    for(const name of names) {
+      const saved=await record(path.join(directory,name)),v=saved?.value,o=v?.observation;
+      if(!o)fail('bootstrap-continue.authorization');
+      const {digest:od,...ob}=o;
+      if(!equal(v,{schemaVersion:1,approval:{decision:'approve',recoveryDigest:od},observation:o}) ||
+        contractDigest(ob)!==od || o.kind!=='bootstrap-recovery-observation' || o.wrapper!==wrapper ||
+        o.initialDigest!==digest || o.requestDigest!==request.digest || o.ownerDigest!==owner.digest ||
+        !equal(o.authorizations,authorizations) || o.ownerStopped!==true || o.originalOwnerStopped!==true ||
+        o.status==='complete' || o.executionAuthorized!==false)fail('bootstrap-continue.authorization');
+      authorizations.push({name,digest:saved.digest});
+    }
+    const result={kind:'bootstrap-recovery-observation',wrapper,initialDigest:digest,requestDigest:request.digest,
+      ownerDigest:owner.digest,ownerStopped:stopped(owner.value),originalOwnerStopped:stopped(originalOwner.value),
+      status:!active?'complete':receipt?'receipt-recorded':archive?'lock-archived':!r.retry && hist?'intent-archived':'request-recorded',
+      routes:r,directory,guard,source,archive,currentWrapper,receiptDigest:receipt?.digest??null,
+      intentExternal:Boolean(ext),authorizations,executionAuthorized:false};
+    return {...result,digest:contractDigest(result)};
+  };
+  const first=await observe();if(!equal(first,await observe()))fail('bootstrap-continue.drift');return first;
+}
+
+async function persist(filename,value){
+  const bytes=Buffer.from(JSON.stringify(value)+'\n');if(bytes.length>MAX_INPUT_BYTES)fail('bootstrap-continue.input-size');
+  const h=await open(filename,'wx',0o600);try{await h.writeFile(bytes);await h.sync();}finally{await h.close();}
+  if((await readRecord(filename)).digest!==sha256(bytes))fail('bootstrap-continue.readback');
+}
+
+// One remaining-action engine. Initial recovery must prove that this process
+// owns the existing gate; resumed recovery must prove the recorded owner stopped.
+// Both modes still require the kernel lease and revalidate all evidence.
+export async function executeBootstrapRecovery({args,lease,current,initialOwner=false}) {
+  assertRecoveryLeaseHeld(lease);
+  const original=current,r=current.routes,request=await readRecord(path.join(current.directory,'request.json'));
+  const boundary=args.ioBoundary??(async()=>{});
+  const check=async()=>{
+    assertRecoveryLeaseHeld(lease);const next=await inspectBootstrapRecovery({...args,initialDigest:original.initialDigest});
+    const owner=await readRecord(path.join(next.directory,'owner.json'));
+    const ownerConfirmed=initialOwner?owner.value.pid===process.pid && owner.value.host===hostname():next.ownerStopped;
+    if(next.requestDigest!==original.requestDigest || next.ownerDigest!==original.ownerDigest ||
+      !equal(rootId(next.guard),rootId(original.guard)) || !ownerConfirmed || !next.originalOwnerStopped ||
+      !equal(next,current))fail('bootstrap-continue.drift');
+  };
+  await check();
+  if(!r.retry && current.intentExternal){
+    await check();await rename(path.join(r.base,'intent.json'),r.intent);
+    current=await inspectBootstrapRecovery({...args,initialDigest:original.initialDigest});await boundary('bootstrap-continuation-intent-archived',current);
+  }
+  if(current.source){
+    await check();await rename(r.base,r.archive);
+    current=await inspectBootstrapRecovery({...args,initialDigest:original.initialDigest});await boundary('bootstrap-continuation-lock-archived',current);
+  }
+  if(!current.receiptDigest){
+    await check();await persist(r.receipt,expectedReceipt(original.wrapper,request.value.initial,r));
+    current=await inspectBootstrapRecovery({...args,initialDigest:original.initialDigest});await boundary('bootstrap-continuation-receipt-persisted',current);
+  }
+  await check();await rename(r.gate,r.history);
+  current=await inspectBootstrapRecovery({...args,initialDigest:original.initialDigest});await boundary('bootstrap-continuation-gate-archived',current);
+  await check();return {status:'bootstrap-recovery-complete',history:r.history,receipt:r.receipt,
+    archive:r.archive,requiresRepositoryPreview:true,repositoryEffectsPerformed:false,pipelineActivated:false};
+}
+
+export async function finishBootstrapRecovery(args) {
+  return withRecoveryLease(args.wrapper,async lease=>{
+    let current=await inspectBootstrapRecovery(args);
+    if(!equal(args.approval,{decision:'approve',recoveryDigest:current.digest}))fail('bootstrap-continue.stale-approval');
+    if(current.status==='complete')return {status:'bootstrap-recovery-complete',history:current.directory,repositoryEffectsPerformed:false,pipelineActivated:false};
+    if(!current.ownerStopped || !current.originalOwnerStopped)fail('bootstrap-continue.owner-unconfirmed');
+    const original=current,r=current.routes;
+    const boundary=args.ioBoundary??(async()=>{});
+    const check=async()=>{
+      assertRecoveryLeaseHeld(lease);const next=await inspectBootstrapRecovery({...args,initialDigest:original.initialDigest});
+      if(next.requestDigest!==original.requestDigest || next.ownerDigest!==original.ownerDigest ||
+        !equal(rootId(next.guard),rootId(original.guard)) || !next.ownerStopped || !next.originalOwnerStopped)
+        fail('bootstrap-continue.drift');
+      if(!equal(next,current))fail('bootstrap-continue.drift');return next;
+    };
+    await check();if(current.authorizations.length>=64)fail('bootstrap-continue.authorization-limit');
+    const authorization={schemaVersion:1,approval:args.approval,observation:current};
+    if(current.guard.bytes+Buffer.byteLength(JSON.stringify(authorization))+1>16*1024*1024)
+      fail('bootstrap-continue.authorization-limit');
+    await persist(path.join(r.gate,'authorization-'+String(current.authorizations.length+1).padStart(4,'0')+'.json'),authorization);
+    current=await inspectBootstrapRecovery({...args,initialDigest:original.initialDigest});
+    await boundary('bootstrap-continuation-authorized',current);
+    await check();return executeBootstrapRecovery({args,lease,current});
+  });
+}

package/src/operations/repository-bootstrap-reconcile.js

@@ -0,0 +1,106 @@
+import path from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { parse,fail } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { absoluteRoot,inspectDirectory } from '../workspace/paths.js';
+import { inventoryRepository } from '../workspace/repository-inventory.js';
+import { bootstrapLockDirectory } from './bootstrap-lock.js';
+import { readRecord } from './state.js';
+
+const id=s=>({dev:String(s.dev),ino:String(s.ino)});
+const equal=(a,b)=>contractDigest(a)===contractDigest(b);
+async function inventory(root) {
+  return (await inspectDirectory(root)).exists?await inventoryRepository(root):null;
+}
+async function optional(file) {
+  try{await lstat(file);}catch(e){if(e.code==='ENOENT')return null;throw e;}
+  return readRecord(file);
+}
+
+// Read-only recovery evidence. A consistent receipt is not a capability, proof
+// of process death, or permission to remove/reuse a lock. No PID probing or writes.
+export async function inspectRepositoryBootstrap(wrapper,previewText,expectedDigest) {
+  wrapper=absoluteRoot(wrapper);
+  if(!/^sha256:[a-f0-9]{64}$/.test(expectedDigest??''))fail('repository-bootstrap.expected-digest');
+  const preview=parse(previewText,'json');
+  if(!preview || typeof preview!=='object' || Array.isArray(preview))fail('repository-bootstrap.preview');
+  const {digest,...body}=preview;
+  if(digest!==expectedDigest || contractDigest(body)!==expectedDigest || preview.wrapper!==wrapper ||
+    preview.kind!=='repository-preview-candidate' || preview.executionAuthorized!==false ||
+    preview.wrapperObservation?.action!=='create' || preview.wrapperObservation.target!==wrapper)
+    fail('repository-bootstrap.preview');
+  const directory=bootstrapLockDirectory(wrapper),metadata=path.join(wrapper,'.pipeline');
+  const before={wrapper:await inventory(wrapper),lock:await inventory(directory),recoveryGate:await inventory(directory+'.recovery')};
+  const files={owner:path.join(directory,'owner.json'),externalIntent:path.join(directory,'intent.json'),
+    history:path.join(metadata,'repository-bootstrap-intent.json'),receipt:path.join(metadata,'repository-bootstrap.json'),
+    recovery:path.join(metadata,'repository-bootstrap-recovery.json'),
+    archivedOwner:path.join(metadata,'repository-bootstrap-recovered-lock','owner.json')};
+  const records={};for(const [key,file] of Object.entries(files))records[key]=await optional(file);
+  const conflicts=[];
+  const owner=records.owner?.value;
+  if(before.lock && (!owner || owner.schemaVersion!==1 || owner.workspace!==wrapper ||
+    typeof owner.token!=='string' || !Number.isSafeInteger(owner.pid) || owner.pid<=0 ||
+    typeof owner.host!=='string' || typeof owner.createdAt!=='string'))conflicts.push('owner-invalid');
+  const expectedIntent={schemaVersion:1,kind:'wrapper-create-intent',previewDigest:expectedDigest,
+    wrapper,before:preview.wrapperObservation,compensation:'no-automatic-rollback'};
+  for(const key of ['externalIntent','history'])
+    if(records[key] && !equal(records[key].value,expectedIntent))conflicts.push(key+'-binding');
+  if(records.externalIntent && records.history)conflicts.push('duplicate-intent');
+  const intent=records.externalIntent??records.history;
+  if(before.lock?.entries.some(e=>!['.','owner.json','intent.json'].includes(e.path)))conflicts.push('lock-foreign-entry');
+  const allowed=['.','.pipeline','.pipeline/repository-bootstrap.json','.pipeline/repository-bootstrap-intent.json',
+    '.pipeline/repository-bootstrap-recovery.json','.pipeline/repository-bootstrap-recovered-lock',
+    '.pipeline/repository-bootstrap-recovered-lock/owner.json'];
+  if(before.wrapper?.entries.some(e=>!allowed.includes(e.path)))conflicts.push('wrapper-foreign-entry');
+  let receiptConsistent=false;
+  if(records.receipt) {
+    const wrapperId=before.wrapper?.entries.find(e=>e.path==='.')?.identity;
+    const metadataId=before.wrapper?.entries.find(e=>e.path==='.pipeline' && e.type==='directory')?.identity;
+    const value=records.receipt.value;
+    receiptConsistent=Boolean(intent && wrapperId && metadataId && equal(value,{
+      schemaVersion:1,kind:'wrapper-created',previewDigest:expectedDigest,wrapper,
+      identity:{dev:wrapperId.dev,ino:wrapperId.ino},metadataIdentity:{dev:metadataId.dev,ino:metadataId.ino},
+      intentDigest:intent.digest,pipelineActivated:false,repositoryEffectsPerformed:false}));
+    if(!receiptConsistent)conflicts.push('receipt-binding');
+  }
+  const parent=path.dirname(wrapper);
+  if(!(await inspectDirectory(parent)).exists ||
+    !equal(id(await lstat(parent,{bigint:true})),preview.wrapperObservation.ancestorIdentity) ||
+    preview.wrapperObservation.ancestor!==parent)conflicts.push('parent-binding');
+  if(records.externalIntent && !before.lock)conflicts.push('intent-without-lock');
+  if(records.history && !records.receipt)conflicts.push('history-without-receipt');
+  let recovered=false;
+  if(records.recovery || records.archivedOwner) {
+    const value=records.recovery?.value,oldOwner=records.archivedOwner?.value;
+    recovered=Boolean(receiptConsistent && records.history && records.archivedOwner && oldOwner?.workspace===wrapper &&
+      oldOwner.schemaVersion===1 && typeof oldOwner.token==='string' && Number.isSafeInteger(oldOwner.pid) && oldOwner.pid>0 &&
+      /^sha256:[a-f0-9]{64}$/.test(value?.reconciliationDigest??'') && equal(value,{
+        schemaVersion:1,kind:'wrapper-bootstrap-recovered',wrapper,previewDigest:expectedDigest,
+        reconciliationDigest:value.reconciliationDigest,ownerDigest:records.archivedOwner.digest,
+        originalReceiptDigest:records.receipt.digest,archive:path.join(metadata,'repository-bootstrap-recovered-lock'),
+        ownerLiveness:'local-pid-absent',pipelineActivated:false,repositoryEffectsPerformed:false}));
+    if(!recovered || before.lock)conflicts.push('recovery-binding');
+  }
+  let status='missing-records';
+  if(conflicts.length)status='conflict';
+  else if(before.recoveryGate)status='recovery-incomplete';
+  else if(recovered)status='recovery-handoff-recorded';
+  else if(receiptConsistent)status=before.lock?'receipt-consistent-lock-retained':'handoff-recorded';
+  else if(intent && !before.wrapper)status='before-state-observed';
+  else if(intent && before.wrapper)status='effect-compatible-unconfirmed';
+  else if(before.lock)status='owner-only-unconfirmed';
+  else if(before.wrapper)status='unattributed-wrapper';
+  // Recheck all byte/identity observations, including missing records. No atomic
+  // snapshot or protection from a malicious concurrent writer is claimed.
+  for(const [key,file] of Object.entries(files)) {
+    const current=await optional(file);
+    if((current?.digest??null)!==(records[key]?.digest??null))fail('repository-bootstrap.observation-drift');
+  }
+  if(!equal(before,{wrapper:await inventory(wrapper),lock:await inventory(directory),recoveryGate:await inventory(directory+'.recovery')}))
+    fail('repository-bootstrap.observation-drift');
+  const result={kind:'repository-bootstrap-reconciliation',wrapper,previewDigest:expectedDigest,directory,status,
+    conflicts,receiptConsistent,observations:before,
+    recordDigests:Object.fromEntries(Object.entries(records).map(([key,value])=>[key,value?.digest??null])),
+    ownerLiveness:'not-verified',executionAuthorized:false,canReleaseLock:false,canResume:false};
+  return {...result,digest:contractDigest(result)};
+}

package/src/operations/repository-bootstrap-recover.js

@@ -0,0 +1,114 @@
+import path from 'node:path';
+import { hostname } from 'node:os';
+import { mkdir,open,lstat } from 'node:fs/promises';
+import { fail,ContractError,parse,MAX_INPUT_BYTES } from '../contracts/parse.js';
+import { sha256 } from '../source/inventory.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { inspectDirectory,pathBudget } from '../workspace/paths.js';
+import { readRecord } from './state.js';
+import { inspectRepositoryBootstrap } from './repository-bootstrap-reconcile.js';
+import { inspectBootstrapRecovery,executeBootstrapRecovery } from './repository-bootstrap-continuation.js';
+import { withRecoveryLease,assertRecoveryLeaseHeld } from './recovery-lease.js';
+
+async function persist(file,bytes) {
+  if(bytes.length>MAX_INPUT_BYTES)fail('bootstrap-recover.input-size');
+  const handle=await open(file,'wx',0o600);
+  try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+  if((await readRecord(file)).digest!==sha256(bytes))fail('bootstrap-recover.readback');
+  return sha256(bytes);
+}
+async function absent(file) {
+  try{await lstat(file);}catch(e){if(e.code==='ENOENT')return;throw e;}
+  fail('bootstrap-recover.destination-exists');
+}
+function requireStopped(owner) {
+  if(owner.host!==hostname() || !Number.isSafeInteger(owner.pid) || owner.pid<=0)fail('bootstrap-recover.owner-unknown');
+  try {process.kill(owner.pid,0);}catch(e){if(e.code==='ESRCH')return;fail('bootstrap-recover.owner-unknown');}
+  fail('bootstrap-recover.owner-live');
+}
+
+// Completed receipt or still-absent wrapper. Preserve the original lock as history, do not
+// steal it or infer completion from an empty directory. The gate excludes new
+// cooperative bootstrap creators while the old lock is relocated.
+export async function recoverRepositoryBootstrap(args) {
+  return withRecoveryLease(args.wrapper,lease=>recoverBootstrap(args,lease));
+}
+async function recoverBootstrap({wrapper,previewText,previewDigest,approval,
+  ioBoundary=async()=>{},onLocation=async()=>{}},lease) {
+  assertRecoveryLeaseHeld(lease);
+  if(!approval || Object.keys(approval).sort().join(',')!=='decision,reconciliationDigest' || approval.decision!=='approve')
+    fail('bootstrap-recover.approval');
+  const inspect=()=>inspectRepositoryBootstrap(wrapper,previewText,previewDigest);
+  const initial=await inspect();
+  if(initial.digest!==approval.reconciliationDigest)fail('bootstrap-recover.stale-approval');
+  const retry=initial.status==='before-state-observed';
+  if(!retry && initial.status!=='receipt-consistent-lock-retained')fail('bootstrap-recover.unconfirmed');
+  const ownerFile=path.join(initial.directory,'owner.json');
+  requireStopped((await readRecord(ownerFile)).value);
+  const gate=initial.directory+'.recovery',metadata=path.join(initial.wrapper,'.pipeline');
+  const archive=retry?path.join(path.dirname(initial.wrapper),'.wpc-bootstrap-history-'+initial.digest.slice(7)):
+    path.join(metadata,'repository-bootstrap-recovered-lock');
+  const receipt=retry?path.join(archive,'recovery.json'):path.join(metadata,'repository-bootstrap-recovery.json');
+  const recoveryHistory=path.join(path.dirname(initial.wrapper),'.wpc-bootstrap-recovery-'+initial.digest.slice(7));
+  pathBudget(gate);pathBudget(archive);pathBudget(receipt);pathBudget(recoveryHistory);
+  await absent(archive);await absent(receipt);await absent(recoveryHistory);
+  let acquired=false,gateDigest,gateIdentity,requestDigest;
+  const identity=s=>String(s.dev)+':'+String(s.ino);
+  const checkGate=async(directory=gate)=>{
+    assertRecoveryLeaseHeld(lease);
+    await inspectDirectory(directory);
+    if(identity(await lstat(directory,{bigint:true}))!==gateIdentity ||
+      (await readRecord(path.join(directory,'owner.json'))).digest!==gateDigest ||
+      (await readRecord(path.join(directory,'request.json'))).digest!==requestDigest)fail('bootstrap-recover.gate-drift');
+  };
+  try {
+    await onLocation({directory:gate,status:'planned'});
+    try{await mkdir(gate);acquired=true;}catch(e){if(e.code==='EEXIST')fail('bootstrap-recover.busy');throw e;}
+    gateIdentity=identity(await lstat(gate,{bigint:true}));
+    gateDigest=await persist(path.join(gate,'owner.json'),Buffer.from(JSON.stringify({pid:process.pid,host:hostname(),
+      wrapper:initial.wrapper,reconciliationDigest:initial.digest})+'\n'));
+    requestDigest=await persist(path.join(gate,'request.json'),Buffer.from(JSON.stringify({schemaVersion:1,
+      approval,initial,preview:parse(previewText,'json')})+'\n'));
+    await ioBoundary('recovery-gate-created',{directory:gate});
+    await checkGate();
+    const current=await inspect();
+    const {digest:ignored,...projected}=current;
+    projected.observations={...current.observations,recoveryGate:null};
+    projected.status=initial.status;
+    if(current.status!=='recovery-incomplete' || contractDigest(projected)!==initial.digest)fail('bootstrap-recover.drift');
+    const owner=await readRecord(ownerFile);
+    if(owner.digest!==initial.recordDigests.owner)fail('bootstrap-recover.drift');
+    requireStopped(owner.value);
+    if(retry) {
+      // Current absence is not a claim that mkdir never happened historically.
+      // Archive the attempt without creating/deleting the wrapper or replaying it.
+      const intent=await readRecord(path.join(initial.directory,'intent.json'));
+      if(intent.digest!==initial.recordDigests.externalIntent)fail('bootstrap-recover.drift');
+      await absent(initial.wrapper);await absent(archive);
+      await onLocation({directory:archive,status:'history-planned'});
+      await checkGate();
+      const finalBefore=await inspect();
+      const {digest:unused,...projectedBefore}=finalBefore;
+      projectedBefore.observations={...finalBefore.observations,recoveryGate:null};
+      projectedBefore.status=initial.status;
+      if(finalBefore.status!=='recovery-incomplete' || contractDigest(projectedBefore)!==initial.digest)
+        fail('bootstrap-recover.drift');
+    }
+    const recovery=await inspectBootstrapRecovery({wrapper:initial.wrapper,initialDigest:initial.digest});
+    const phases={
+      'bootstrap-continuation-intent-archived':'recovery-intent-archived',
+      'bootstrap-continuation-lock-archived':'recovery-lock-archived',
+      'bootstrap-continuation-receipt-persisted':'recovery-receipt-persisted',
+      'bootstrap-continuation-gate-archived':'recovery-gate-archived'
+    };
+    await executeBootstrapRecovery({lease,current:recovery,initialOwner:true,args:{
+      wrapper:initial.wrapper,initialDigest:initial.digest,
+      ioBoundary:async phase=>ioBoundary(phases[phase],{archive,recoveryHistory})
+    }});
+    return {status:retry?'bootstrap-attempt-archived':'bootstrap-recovered',
+      receipt,archive,recoveryHistory,requiresRepositoryPreview:true,pipelineActivated:false};
+  }catch(cause){
+    const error=cause instanceof ContractError?cause:new ContractError('bootstrap-recover.io');
+    if(acquired)error.recoveryDirectory=gate;throw error;
+  }
+}