@6reduk/workspace-pipeline 0.1.0

package/src/operations/repair.js

@@ -0,0 +1,188 @@
+import {readState,verifyInstalledSnapshot,observeTargets} from './state.js';
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {planLayout} from '../workspace/resolve.js';
+import {assertRequestScope,bindPreview} from './plan.js';
+import {assertLockHeld} from './lock.js';
+import {requestShape,reconcileFields} from './ownership.js';
+import {readConfigField,reconcileConfigFields} from './config-fields.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail,parse} from '../contracts/parse.js';
+import {sha256,cap,LIMITS} from '../source/inventory.js';
+import {installedSelection} from '../providers/bundles.js';
+
+const hash=bytes=>bytes===null?null:sha256(bytes);
+const key=(name,pointer)=>JSON.stringify([name,pointer]);
+function at(root,pointer) {
+  let node=root;
+  for(const part of pointer.slice(1).split('/').map(p=>p.replace(/~1/g,'/').replace(/~0/g,'~'))) {
+    if(node===null || typeof node!=='object' || Array.isArray(node))fail('repair.field-ancestor');
+    if(!Object.hasOwn(node,part))return {present:false};
+    node=node[part];
+  }
+  return {present:true,value:node};
+}
+
+// Read-only inspection, NOT a prepared repair/apply envelope. All requests are
+// replayed from installed bytes by trusted adapters; owned value hashes must
+// match state. User changes become conflicts, never rewritten ownership records.
+async function observeRepair(workspace,registry) {
+  requestShape(registry,['adapters','sharedAdapter'],[],'provider.interface');
+  if(!registry.adapters || typeof registry.adapters!=='object' || Array.isArray(registry.adapters) ||
+      typeof registry.sharedAdapter?.plan!=='function')fail('provider.interface');
+  workspace=absoluteRoot(workspace);
+  const filename=resolveChild(workspace,'.pipeline/state.json'),record=await readState(filename),state=record.value;
+  if(state.workspace!==workspace || !state.active)fail('repair.state');
+  if(state.pending!==null)fail('repair.pending');
+  const active=state.active,installed=await verifyInstalledSnapshot(state);
+  const manifest={schemaVersion:1,pipeline:structuredClone(active.snapshot.source),
+    ...installedSelection(active),layout:structuredClone(active.layout),
+    ...(active.agentsDocument?{agentsDocument:structuredClone(active.agentsDocument)}:{})};
+  const layout=planLayout(installed.manifest,manifest,workspace,{adapters:registry.adapters});
+  const context=()=>({pipeline:structuredClone(installed.manifest),workspace:structuredClone(manifest),
+    installedAdapterVersions:structuredClone(active.adapterVersions),
+    layout:structuredClone(layout),snapshot:structuredClone(active.snapshot),
+    files:new Map([...installed.files].map(([name,bytes])=>[name,Buffer.from(bytes)]))});
+  const desired=new Map(),requests=[];let totalBytes=0;
+  for(const [owner,adapter] of [['shared',registry.sharedAdapter],...active.providers.map(id=>[id,registry.adapters[id]])]) {
+    if(owner!=='shared' && (await adapter.validate(context()))?.valid===false)fail('provider.validation');
+    const batch=await adapter.plan(context());
+    if(!Array.isArray(batch))fail('plan.adapter-output');
+    cap(requests.length+batch.length,LIMITS.files,'plan.count');
+    for(const request of batch) {
+      assertRequestScope(request,active.providers);
+      if(request.owner!==owner)fail('plan.adapter-owner');
+      if(requests.some(r=>r.path===request.path))fail('plan.overlap');
+      requests.push(request);
+      const add=(pointer,desiredHash,value)=>{
+        const id=key(request.path,pointer);if(desired.has(id))fail('repair.duplicate');
+        desired.set(id,{owner,hash:desiredHash,value});
+      };
+      if(request.kind==='file') {
+        if(!Buffer.isBuffer(request.bytes))fail('plan.bytes');
+        cap(request.bytes.length,LIMITS.blob,'preview.size');totalBytes+=request.bytes.length;
+        add(null,sha256(request.bytes),Buffer.from(request.bytes));
+      } else {
+        // Historical takeover decisions are not fresh authority. Inspection only
+        // reconstructs desired values, without reusing those decisions.
+        const fields=request.fields.map(f=>f.present?{pointer:f.pointer,present:true,value:f.value}:{pointer:f.pointer,present:false});
+        const reconciled=reconcileFields({},fields);
+        totalBytes+=Buffer.byteLength(JSON.stringify(reconciled.value));
+        for(const decision of reconciled.decisions) add(decision.pointer,decision.desiredHash,at(reconciled.value,decision.pointer).value);
+      }
+      cap(totalBytes,LIMITS.total,'preview.total');
+    }
+  }
+  planLayout(installed.manifest,manifest,workspace,{adapters:registry.adapters,managedPaths:requests.map(r=>r.path)});
+  const names=[...new Set(active.owned.map(o=>o.path))],observations=await observeTargets(workspace,names);
+  const current=new Map(observations.map(o=>[o.path,o.bytes])),entries=[];
+  for(const owned of active.owned) {
+    const expected=desired.get(key(owned.path,owned.pointer));
+    if(!expected || expected.owner!==owned.owner || expected.hash!==owned.managedHash)fail('repair.replay-mismatch');
+    const bytes=current.get(owned.path);let currentHash=null,malformed=false;
+    if(bytes!==null) {
+      if(owned.kind==='file')currentHash=sha256(bytes);
+      else {
+        try{const field=readConfigField(owned.path,bytes,owned.pointer);if(field.present)currentHash=contractDigest(field.value);}
+        catch{malformed=true;}
+      }
+    }
+    entries.push({path:owned.path,owner:owned.owner,kind:owned.kind,pointer:owned.pointer,
+      managedHash:owned.managedHash,currentHash,fileHash:hash(bytes),
+      disposition:malformed?'conflict':currentHash===owned.managedHash?'intact':currentHash===null?'missing':'conflict'});
+  }
+  if((await readState(filename)).digest!==record.digest)fail('repair.observation-drift');
+  await verifyInstalledSnapshot(state);
+  for(const observation of await observeTargets(workspace,names))
+    if(hash(observation.bytes)!==hash(current.get(observation.path)))fail('repair.observation-drift');
+  const body={kind:'repair-inspection',workspace,stateHash:record.digest,snapshot:active.snapshot.digest,entries,
+    runtime:'not-run',automaticActions:false,applySupported:false,requiresFreshApproval:true};
+  return {inspection:{...body,digest:contractDigest(body)},current,desired};
+}
+
+export async function inspectRepair(workspace,registry) {
+  return (await observeRepair(workspace,registry)).inspection;
+}
+
+// Private preview payloads can include foreign configuration siblings. Do not
+// print/publish this envelope as a diagnostic. No write/approval happens here.
+export async function prepareRepairPreview(workspace,registry) {
+  const {inspection,current,desired}=await observeRepair(workspace,registry);
+  const blockers=inspection.entries.filter(e=>e.disposition==='conflict'),targets=[],outputs=[];
+  // Whole-preview fail closed: no partial execution when another target conflicts.
+  if(!blockers.length) {
+    for(const name of [...new Set(inspection.entries.filter(e=>e.disposition==='missing').map(e=>e.path))].sort()) {
+      const entries=inspection.entries.filter(e=>e.path===name && e.disposition==='missing');
+      const before=current.get(name);let bytes;
+      if(entries[0].kind==='file')bytes=desired.get(key(name,null)).value;
+      else {
+        const fields=entries.map(e=>({pointer:e.pointer,present:true,value:desired.get(key(name,e.pointer)).value}));
+        bytes=reconcileConfigFields(name,before,fields).bytes;
+      }
+      targets.push({path:name,action:before===null?'create':'edit-fields',beforeHash:hash(before),desiredHash:sha256(bytes),
+        fields:entries.filter(e=>e.pointer!==null).map(e=>({pointer:e.pointer,desiredHash:e.managedHash}))});
+      outputs.push({path:name,bytes:bytes.toString('base64')});
+    }
+  }
+  const body={kind:'repair-preview',inspection,targets,outputs,blockers,
+    requiresFreshApproval:true,applySupported:false,automaticActions:false,runtime:'not-run'};
+  parse(JSON.stringify(body),'json');
+  return {...body,digest:contractDigest(body)};
+}
+
+// Native operation contract, deliberately distinct from a source-based prepared
+// setup/update. Preserve deployment identity and
+// original backup lineage; repair never converts observed drift into ownership.
+export async function prepareRepairPlan(workspace,registry) {
+  const candidate=await prepareRepairPreview(workspace,registry);
+  if(candidate.blockers.length)fail('repair.conflict');
+  workspace=candidate.inspection.workspace;
+  const record=await readState(resolveChild(workspace,'.pipeline/state.json'));
+  if(record.digest!==candidate.inspection.stateHash)fail('repair.observation-drift');
+  const previous=record.value;
+  const names=[...new Set(candidate.inspection.entries.map(e=>e.path))];
+  const observations=await observeTargets(workspace,names);
+  for(const observation of observations) {
+    const expected=candidate.inspection.entries.find(e=>e.path===observation.path);
+    if(hash(observation.bytes)!==expected.fileHash)fail('repair.observation-drift');
+  }
+  const targets=candidate.targets.map((t,i)=>({id:'target-'+String(i+1),path:t.path,
+    owner:candidate.inspection.entries.find(e=>e.path===t.path).owner,
+    action:t.action,beforeHash:t.beforeHash,desiredHash:t.desiredHash,
+    fields:t.action==='edit-fields'?t.fields.map(f=>({...f,beforeHash:null})):[]}));
+  const plan={schemaVersion:1,kind:'plan',workspace,command:'repair',
+    beforeStateHash:contractDigest(previous),source:structuredClone(previous.active.snapshot),
+    desired:structuredClone(previous.active),targets};
+  const preview=bindPreview(plan,previous,{observations,
+    outputs:candidate.outputs.map(o=>({path:o.path,bytes:Buffer.from(o.bytes,'base64')}))});
+  await verifyInstalledSnapshot(previous);
+  if((await readState(resolveChild(workspace,'.pipeline/state.json'))).digest!==record.digest)fail('repair.observation-drift');
+  const body={kind:'prepared-repair',preview,stateFileHash:record.digest,
+    runtime:'not-run',applySupported:true,requiresFreshApproval:true};
+  parse(JSON.stringify(body),'json');
+  return {...body,digest:contractDigest(body)};
+}
+
+// Read-only approval/preflight, not authority for a caller-provided payload.
+// Replay the entire plan under the caller's live lock, including unchanged
+// dependencies. No original source/manifest lookup and no old approval reuse.
+export function validateRepairRecord(prepared,approval) {
+  requestShape(prepared,['kind','preview','stateFileHash','runtime','applySupported','requiresFreshApproval','digest'],[],'repair.prepared');
+  requestShape(approval,['decision','preparedDigest'],[],'repair.approval');
+  const copy=parse(JSON.stringify(prepared),'json'),decision=structuredClone(approval);
+  const {digest,...body}=copy;
+  if(copy.kind!=='prepared-repair' || copy.runtime!=='not-run' || copy.applySupported!==true ||
+      copy.requiresFreshApproval!==true || contractDigest(body)!==digest)fail('repair.prepared');
+  if(decision.decision!=='approve' || decision.preparedDigest!==digest)fail('repair.approval');
+  if(copy.preview?.plan?.command!=='repair')fail('repair.prepared');
+  return structuredClone(copy);
+}
+
+export async function verifyRepairApproval(lock,prepared,approval,registry) {
+  const copy=validateRepairRecord(prepared,approval);
+  await assertLockHeld(lock);
+  if(copy.preview?.plan?.workspace!==lock.workspace)fail('repair.workspace');
+  const fresh=await prepareRepairPlan(lock.workspace,registry);
+  if(contractDigest(fresh)!==contractDigest(copy))fail('repair.plan-drift');
+  await assertLockHeld(lock);
+  return fresh;
+}

package/src/operations/repository-abandon.js

@@ -0,0 +1,192 @@
+import path from 'node:path';
+import {hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+import {mkdir,open,rename,lstat} from 'node:fs/promises';
+import {absoluteRoot,inspectDirectory} from '../workspace/paths.js';
+import {inventoryRepository} from '../workspace/repository-inventory.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {readRecord} from './state.js';
+import {readRepositoryInputs} from './repository-inputs.js';
+import {bootstrapLockDirectory} from './bootstrap-lock.js';
+import {withRecoveryLease,assertRecoveryLeaseHeld} from './recovery-lease.js';
+import {sha256} from '../source/inventory.js';
+import {inspectRepositoryReconciliation} from './repository-reconcile.js';
+
+const eq=(a,b)=>contractDigest(a)===contractDigest(b);
+const uuid=s=>typeof s==='string' && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(s);
+const id=s=>({dev:String(s.dev),ino:String(s.ino)});
+async function exists(p){try{await lstat(p);return true;}catch(e){if(e.code==='ENOENT')return false;throw e;}}
+// Renaming a root changes its timestamps. Content, nested identities and file
+// hashes remain bound; directory timestamps alone do not prove foreign writes.
+async function observe(p,omit=[]){
+  if(!await exists(p))return null;
+  const v=await inventoryRepository(p);
+  return v.entries.filter(e=>!omit.some(x=>e.path===x || e.path.startsWith(x+'/'))).map(e=>
+    ({path:e.path,type:e.type,identity:e.type==='directory'?{dev:e.identity.dev,ino:e.identity.ino}:e.identity,
+      ...(e.sha256?{sha256:e.sha256}:{})}));
+}
+function stopped(o){
+  if(o.host!==hostname() || !Number.isSafeInteger(o.pid) || o.pid<=0)fail('repository-abandon.owner-unknown');
+  try{process.kill(o.pid,0);}catch(e){if(e.code==='ESRCH')return;fail('repository-abandon.owner-unknown');}
+  fail('repository-abandon.owner-live');
+}
+function routes(w,attempt){return {gate:bootstrapLockDirectory(w)+'.recovery',
+  archive:path.join(path.dirname(w),'.wpc-repository-resolution-'+attempt),
+  sources:[path.join(w,'.pipeline/repository-operation.json'),path.join(w,'.pipeline/lock'),bootstrapLockDirectory(w)]};}
+async function lock(p,w){
+  const v=await observe(p);if(!v)return null;
+  if(!eq(v.map(e=>e.path).sort(),['.','owner.json']))fail('repository-abandon.lock-incomplete');
+  const o=(await readRecord(path.join(p,'owner.json'))).value;
+  if(Object.keys(o).sort().join(',')!=='createdAt,host,pid,schemaVersion,token,workspace' ||
+    o.workspace!==w || o.schemaVersion!==1 || !uuid(o.token) || typeof o.createdAt!=='string' ||
+    !Number.isFinite(Date.parse(o.createdAt)))fail('repository-abandon.owner-binding');stopped(o);return v;
+}
+async function data(w,input){
+  const preview=JSON.parse(input.previewText),trees=[];
+  if(!Array.isArray(preview.operations) || !preview.operations.length || preview.operations.length>128)fail('repository-abandon.inputs');
+  for(const op of preview.operations){
+    for(const p of [op.target,...(op.action==='move'?[op.from]:[])]){
+      absoluteRoot(p);if(trees.some(x=>x.path===p))continue;
+      const entries=await observe(p);
+      trees.push({path:p,inventory:entries===null?null:{entryCount:entries.length,digest:contractDigest(entries)}});
+    }
+  }
+  return {trees,metadata:await observe(path.join(w,'.pipeline'),['lock','repository-operation.json'])};
+}
+async function state(w){
+  const r=routes(w,'unused');
+  for(const p of [r.gate,bootstrapLockDirectory(w)+'.recovery-resume'])if(await exists(p))fail('repository-abandon.recovery-pending');
+  const m=await readRecord(r.sources[0]);
+  if(m.value.schemaVersion!==1 || m.value.status!=='requires-reconciliation')fail('repository-abandon.marker');
+  const input=await readRepositoryInputs(w,m.value.journal,m.value.previewDigest);
+  if((await inspectRepositoryReconciliation(w,input.previewText,m.value.previewDigest)).canFinalize)
+    fail('repository-abandon.finalizable');
+  return {parent:id(await lstat(path.dirname(w),{bigint:true})),wrapperIdentity:id(await lstat(w,{bigint:true})),
+    markerDigest:m.digest,inputDigest:input.recordDigest,journal:m.value.journal,previewDigest:m.value.previewDigest,
+    locks:[await lock(r.sources[1],w),await lock(r.sources[2],w)],...await data(w,input)};
+}
+export async function prepareRepositoryAbandon(wrapper){
+  wrapper=absoluteRoot(wrapper);await inspectDirectory(wrapper);
+  const before=await state(wrapper);if(!eq(before,await state(wrapper)))fail('repository-abandon.drift');
+  const value={schemaVersion:1,kind:'repository-abandon-preview',wrapper,attempt:randomUUID(),
+    decision:'preserve-current-state-abandon-operation',before,executionAuthorized:false,
+    completed:false,pipelineActivated:false,requiresNewRepositoryPreview:true};
+  return {...value,digest:contractDigest(value)};
+}
+function validate(p,w){
+  const {digest,...body}=p??{};
+  if(p?.kind!=='repository-abandon-preview' || p.wrapper!==w || p.schemaVersion!==1 ||
+    p.decision!=='preserve-current-state-abandon-operation' || !uuid(p.attempt) ||
+    contractDigest(body)!==digest)fail('repository-abandon.preview');
+}
+async function persist(p,value){
+  const b=Buffer.from(JSON.stringify(value)+'\n');if(b.length>MAX_INPUT_BYTES)fail('repository-abandon.size');
+  const h=await open(p,'wx',0o600);try{await h.writeFile(b);await h.sync();}finally{await h.close();}
+  if((await readRecord(p)).digest!==sha256(b))fail('repository-abandon.readback');
+}
+// Read-only observation for a fresh continuation approval. No successful-effect
+// claim: this route explicitly preserves partial/uncertain trees as user data.
+export async function inspectRepositoryAbandon(wrapper,attempt){
+  wrapper=absoluteRoot(wrapper);if(!uuid(attempt))fail('repository-abandon.attempt');
+  const r=routes(wrapper,attempt),request=await readRecord(path.join(r.archive,'request.json')),p=request.value;
+  validate(p,wrapper);if(p.attempt!==attempt)fail('repository-abandon.binding');
+  const gateActive=await exists(r.gate),guard=gateActive?r.gate:path.join(r.archive,'guard');
+  const owner=await readRecord(path.join(guard,'owner.json'));
+  if(owner.value.wrapper!==wrapper || owner.value.attempt!==attempt || owner.value.previewDigest!==p.digest)fail('repository-abandon.guard');
+  const contents=await observe(guard);if(!eq(contents.map(e=>e.path).sort(),['.','owner.json']))fail('repository-abandon.guard');
+  const locations=[];
+  for(let i=0;i<r.sources.length;i++){
+    const source=await exists(r.sources[i]),dest=path.join(r.archive,String(i));
+    const archived=await exists(dest),expected=i===0?true:p.before.locks[i-1]!==null;
+    if(expected?source===archived:source||archived)fail('repository-abandon.location');
+    const at=source?r.sources[i]:dest;
+    if(i===0){if((await readRecord(at)).digest!==p.before.markerDigest)fail('repository-abandon.marker-drift');}
+    else if(expected && !eq(await lock(at,wrapper),p.before.locks[i-1]))fail('repository-abandon.lock-drift');
+    locations.push(expected?(source?'source':'archived'):'absent');
+  }
+  const marker=await readRecord(locations[0]==='source'?r.sources[0]:path.join(r.archive,'0'));
+  const input=await readRepositoryInputs(wrapper,marker.value.journal,marker.value.previewDigest);
+  if(input.recordDigest!==p.before.inputDigest || !eq(await data(wrapper,input),{trees:p.before.trees,metadata:p.before.metadata}) ||
+    !eq(id(await lstat(wrapper,{bigint:true})),p.before.wrapperIdentity) ||
+    !eq(id(await lstat(path.dirname(wrapper),{bigint:true})),p.before.parent))fail('repository-abandon.subject-drift');
+  const receiptPath=path.join(r.archive,'receipt.json'),receipt=await exists(receiptPath)?await readRecord(receiptPath):null;
+  const expected={schemaVersion:1,status:'abandoned-preserving-current-state',previewDigest:p.digest,
+    completed:false,pipelineActivated:false,requiresNewRepositoryPreview:true};
+  if(receipt && (!eq(receipt.value,expected) || locations.includes('source')))fail('repository-abandon.receipt');
+  if(!gateActive && !receipt)fail('repository-abandon.order');
+  const archive=await observe(r.archive),approvals=archive.filter(e=>/^authorization-\d{4}\.json$/.test(e.path)).sort((a,b)=>a.path.localeCompare(b.path));
+  if(approvals.length>64)fail('repository-abandon.approval-limit');
+  const previousApprovals=[];
+  for(const [i,a] of approvals.entries()){
+    if(a.path!=='authorization-'+String(i+1).padStart(4,'0')+'.json')fail('repository-abandon.approval-sequence');
+    const record=await readRecord(path.join(r.archive,a.path)),v=record.value,o=v.observation;
+    const {digest,...body}=o??{};
+    if(Object.keys(v).sort().join(',')!=='decision,observation,previousApprovals,schemaVersion,sequence' ||
+      v.schemaVersion!==1 || v.sequence!==i+1 || !eq(v.previousApprovals,previousApprovals) ||
+      v.decision!=='preserve-current-state-abandon-operation' || o?.wrapper!==wrapper || o.attempt!==attempt ||
+      o.requestDigest!==request.digest || o.ownerDigest!==owner.digest || contractDigest(body)!==digest)
+      fail('repository-abandon.approval');
+    previousApprovals.push({name:a.path,digest:record.digest});
+  }
+  const allowed=['.','request.json',...approvals.map(a=>a.path),...locations.flatMap((s,i)=>s==='archived'?
+    (i===0?[String(i)]:[String(i),i+'/owner.json']):[]),...(receipt?['receipt.json']:[]),...(!gateActive?['guard','guard/owner.json']:[])].sort();
+  if(!eq(archive.map(e=>e.path).sort(),allowed))fail('repository-abandon.foreign-history');
+  const body={kind:'repository-abandon-observation',wrapper,attempt,requestDigest:request.digest,
+    ownerDigest:owner.digest,guard:contents,locations,archive,gateActive,receiptDigest:receipt?.digest??null,executionAuthorized:false};
+  return {...body,digest:contractDigest(body)};
+}
+export async function applyRepositoryAbandon(wrapper,preview,{ioBoundary=async()=>{},continuation=false}={}){
+  wrapper=absoluteRoot(wrapper);
+  return withRecoveryLease(wrapper,async lease=>{
+    const checkLease=()=>assertRecoveryLeaseHeld(lease);checkLease();
+    let p=preview,r,original;
+    if(!continuation){
+      validate(p,wrapper);if(!eq(await state(wrapper),p.before))fail('repository-abandon.stale');r=routes(wrapper,p.attempt);
+      if(await exists(r.archive))fail('repository-abandon.history-exists');
+      await mkdir(r.archive);await persist(path.join(r.archive,'request.json'),p);
+      await ioBoundary('abandon-request-retained');checkLease();
+      if(!eq(await state(wrapper),p.before))fail('repository-abandon.stale');
+      await mkdir(r.gate);await persist(path.join(r.gate,'owner.json'),{wrapper,attempt:p.attempt,previewDigest:p.digest,pid:process.pid,host:hostname()});
+      original=await inspectRepositoryAbandon(wrapper,p.attempt);
+      await ioBoundary('abandon-guard-created');
+    }else{
+      const fresh=await inspectRepositoryAbandon(wrapper,preview?.attempt);
+      if(!eq(fresh,preview))fail('repository-abandon.stale');original=fresh;r=routes(wrapper,preview.attempt);
+      if(!fresh.gateActive)return {status:'abandoned-preserving-current-state',archive:r.archive,completed:false,pipelineActivated:false};
+      stopped((await readRecord(path.join(r.gate,'owner.json'))).value);
+      p=(await readRecord(path.join(r.archive,'request.json'))).value;
+      const prior=fresh.archive.filter(e=>/^authorization-\d{4}\.json$/.test(e.path)).sort((a,b)=>a.path.localeCompare(b.path));
+      if(prior.length>=64)fail('repository-abandon.approval-limit');
+      const previousApprovals=[];
+      for(const a of prior)previousApprovals.push({name:a.path,digest:(await readRecord(path.join(r.archive,a.path))).digest});
+      await persist(path.join(r.archive,'authorization-'+String(prior.length+1).padStart(4,'0')+'.json'),{
+        schemaVersion:1,sequence:prior.length+1,previousApprovals,
+        decision:'preserve-current-state-abandon-operation',observation:fresh});
+      original=await inspectRepositoryAbandon(wrapper,p.attempt);await ioBoundary('abandon-continuation-approved');
+    }
+    let current=original;
+    const check=async()=>{checkLease();const next=await inspectRepositoryAbandon(wrapper,p.attempt);
+      if(continuation)stopped((await readRecord(path.join(r.gate,'owner.json'))).value);
+      if(!eq(next,current))fail('repository-abandon.drift');};
+    for(let i=0;i<3;i++){
+      await check();if(current.locations[i]!=='source')continue;
+      await rename(r.sources[i],path.join(r.archive,String(i)));
+      current=await inspectRepositoryAbandon(wrapper,p.attempt);await ioBoundary('abandon-moved-'+i);
+    }
+    await check();
+    if(!current.receiptDigest){
+      await persist(path.join(r.archive,'receipt.json'),{schemaVersion:1,status:'abandoned-preserving-current-state',previewDigest:p.digest,
+        completed:false,pipelineActivated:false,requiresNewRepositoryPreview:true});
+      current=await inspectRepositoryAbandon(wrapper,p.attempt);await ioBoundary('abandon-receipt');
+    }
+    await check();await rename(r.gate,path.join(r.archive,'guard'));await ioBoundary('abandon-guard-archived');
+    checkLease();
+    if(!eq(await observe(path.join(r.archive,'guard')),original.guard) ||
+      (await readRecord(path.join(r.archive,'request.json'))).digest!==original.requestDigest ||
+      (await readRecord(path.join(r.archive,'receipt.json'))).digest!==current.receiptDigest)
+      fail('repository-abandon.readback');
+    return {status:'abandoned-preserving-current-state',archive:r.archive,receipt:path.join(r.archive,'receipt.json'),
+      completed:false,pipelineActivated:false,requiresNewRepositoryPreview:true};
+  });
+}

package/src/operations/repository-ancestors.js

@@ -0,0 +1,158 @@
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {lstat,mkdir,open,opendir,rename} from 'node:fs/promises';
+import {absoluteRoot,inspectDirectory,pathBudget} from '../workspace/paths.js';
+import {fail,parse} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {readRecord} from './state.js';
+import {withRecoveryLease,assertRecoveryLeaseHeld} from './recovery-lease.js';
+
+const MAX_DEPTH=32,MAX_APPROVALS=64, id=s=>({dev:String(s.dev),ino:String(s.ino)});
+const same=(a,b)=>contractDigest(a)===contractDigest(b);
+async function directoryId(p){if(!(await inspectDirectory(p)).exists)fail('ancestors.missing');return id(await lstat(p,{bigint:true}));}
+async function names(p,limit=4){const values=[];for await(const entry of await opendir(p)){if(values.length>=limit)fail('ancestors.entries');values.push(entry.name);}return values.sort();}
+async function absent(p){try{await lstat(p);}catch(e){if(e.code==='ENOENT')return;throw e;}fail('ancestors.destination-exists');}
+async function persist(file,value){const h=await open(file,'wx',0o600);try{await h.writeFile(JSON.stringify(value)+'\n');await h.sync();}finally{await h.close();}if(!same((await readRecord(file)).value,value))fail('ancestors.readback');}
+function validate(p){
+  if(!p || p.schemaVersion!==1 || p.kind!=='repository-parent-preview' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(p.attemptId) ||
+    !Array.isArray(p.targets) || !p.targets.length || p.targets.length>MAX_DEPTH)fail('ancestors.preview');
+  const wrapper=absoluteRoot(p.wrapper),anchor=absoluteRoot(p.anchor),history=path.join(anchor,'.wpc-ancestors-'+p.attemptId);
+  const keys=['anchor','anchorIdentity','attemptId','history','kind','schemaVersion','targets','wrapper'];
+  if(!same(Object.keys(p).sort(),keys) || p.wrapper!==wrapper || p.anchor!==anchor || p.history!==history || !same(Object.keys(p.anchorIdentity??{}).sort(),['dev','ino']) ||
+    !Object.values(p.anchorIdentity).every(v=>typeof v==='string' && /^\d+$/.test(v)))fail('ancestors.preview');
+  let previous=anchor;
+  for(const target of p.targets){
+    if(absoluteRoot(target)!==target || path.dirname(target)!==previous || target===previous)fail('ancestors.preview');
+    pathBudget(target);previous=target;
+  }
+  if(previous!==path.dirname(wrapper) || path.dirname(wrapper)===wrapper || p.targets[0].toLowerCase()===history.toLowerCase())fail('ancestors.preview');
+  pathBudget(wrapper);pathBudget(history);pathBudget(path.join(history,'projection.json'));
+  pathBudget(path.join(history,'tree',...p.targets.slice(1).map(t=>path.basename(t))));
+  return p;
+}
+function input(value){return validate(typeof value==='string'?parse(value,'json'):structuredClone(value));}
+async function anchor(p){if(!same(await directoryId(p.anchor),p.anchorIdentity))fail('ancestors.anchor-drift');}
+function staged(p,index){return path.join(p.history,'tree',...p.targets.slice(1,index+1).map(t=>path.basename(t)));}
+
+export async function prepareRepositoryAncestors(wrapper){
+  wrapper=absoluteRoot(wrapper);pathBudget(wrapper);await inspectDirectory(wrapper);
+  let current=path.dirname(wrapper),targets=[];
+  while(!(await inspectDirectory(current)).exists){
+    targets.unshift(current);if(targets.length>MAX_DEPTH)fail('ancestors.depth');current=path.dirname(current);
+  }
+  if(!targets.length)fail('ancestors.parent-present');
+  const attemptId=randomUUID();
+  return validate({schemaVersion:1,kind:'repository-parent-preview',wrapper,anchor:current,
+    anchorIdentity:await directoryId(current),attemptId,history:path.join(current,'.wpc-ancestors-'+attemptId),targets});
+}
+
+async function projection(p){
+  const r=await readRecord(path.join(p.history,'projection.json')),v=r.value;
+  if(!same(Object.keys(v).sort(),['directories','previewDigest','schemaVersion']) || v.schemaVersion!==1 ||
+    v.previewDigest!==contractDigest(p) || !Array.isArray(v.directories) || v.directories.length!==p.targets.length)fail('ancestors.projection');
+  for(let i=0;i<v.directories.length;i++){
+    const d=v.directories[i];if(!same(Object.keys(d).sort(),['identity','target']) || d.target!==p.targets[i] ||
+      !same(Object.keys(d.identity??{}).sort(),['dev','ino']) || !Object.values(d.identity).every(x=>typeof x==='string' && /^\d+$/.test(x)))fail('ancestors.projection');
+  }
+  return r;
+}
+async function checkTree(p,v,applied){
+  for(let i=0;i<p.targets.length;i++){
+    const dir=applied?p.targets[i]:staged(p,i);
+    if(!same(await directoryId(dir),v.directories[i].identity))fail('ancestors.directory-drift');
+    const expected=i+1<p.targets.length?[path.basename(p.targets[i+1])]:[];
+    if(!same(await names(dir),expected))fail('ancestors.foreign-entry');
+  }
+}
+function receipt(p,v){return {schemaVersion:1,previewDigest:contractDigest(p),projectionDigest:contractDigest(v),
+  status:'parent-directories-created',wrapper:p.wrapper,targets:p.targets,repositoryEffectsPerformed:false,pipelineActivated:false};}
+async function observe(p){
+  await anchor(p);const historyIdentity=await directoryId(p.history);
+  const request=await readRecord(path.join(p.history,'request.json'));
+  if(!same(request.value,p))fail('ancestors.request-drift');
+  const record=await projection(p);
+  const hasStage=(await inspectDirectory(staged(p,0))).exists,hasTarget=(await inspectDirectory(p.targets[0])).exists;
+  if(hasStage===hasTarget)fail('ancestors.location');
+  await checkTree(p,record.value,hasTarget);
+  const entries=await names(p.history,MAX_APPROVALS+4),base=['projection.json','request.json',...(hasStage?['tree']:[])].sort();
+  const resultFile=path.join(p.history,'receipt.json');let result=null;
+  if(entries.includes('receipt.json')){result=await readRecord(resultFile);if(hasStage || !same(result.value,receipt(p,record.value)))fail('ancestors.receipt');base.push('receipt.json');base.sort();}
+  const stable={schemaVersion:1,previewDigest:contractDigest(p),historyIdentity,requestDigest:request.digest,projectionDigest:record.digest};
+  const continuationApprovals=[];
+  const approvals=entries.filter(n=>/^authorization-\d{4}\.json$/.test(n));
+  if(approvals.length>MAX_APPROVALS)fail('ancestors.approval-limit');
+  for(let i=0;i<approvals.length;i++){
+    const name='authorization-'+String(i+1).padStart(4,'0')+'.json';if(approvals[i]!==name)fail('ancestors.approval-chain');
+    const saved=await readRecord(path.join(p.history,name)),a=saved.value,{digest,...body}=a.observation??{};
+    if(!same(Object.keys(a).sort(),['decision','observation','schemaVersion','sequence']) || a.schemaVersion!==1 ||
+      a.decision!=='approve-remaining-parent-actions' || a.sequence!==i+1 || contractDigest(body)!==digest ||
+      !same(Object.keys(body).sort(),[...Object.keys(stable),'status','receiptDigest','continuationApprovals'].sort()) ||
+      !same(Object.fromEntries(Object.keys(stable).map(k=>[k,body[k]])),stable) ||
+      !['staged','applied-receipt-missing'].includes(body.status) || body.receiptDigest!==null ||
+      !same(body.continuationApprovals,continuationApprovals))fail('ancestors.approval-chain');
+    continuationApprovals.push({name,digest:saved.digest});base.push(name);
+  }
+  if(!same(entries,base.sort()))fail('ancestors.history-entry');
+  const value={...stable,status:result?'completed':hasTarget?'applied-receipt-missing':'staged',receiptDigest:result?.digest??null,continuationApprovals};
+  return {...value,digest:contractDigest(value)};
+}
+export async function inspectRepositoryAncestors(preview){const p=input(preview),a=await observe(p),b=await observe(p);if(!same(a,b))fail('ancestors.drift');return b;}
+
+async function finish(p,initial,lease,ioBoundary){
+  async function check(){assertRecoveryLeaseHeld(lease);const next=await inspectRepositoryAncestors(p);if(!same(next,initial))fail('ancestors.drift');}
+  if(initial.status==='completed')return {status:'parent-directories-created',history:p.history,requiresRepositoryPreview:true,repositoryEffectsPerformed:false,pipelineActivated:false};
+  await check();
+  if(initial.status==='staged'){
+    await absent(p.targets[0]);await rename(staged(p,0),p.targets[0]);
+    await ioBoundary('ancestors-published',{history:p.history});
+    const next=await inspectRepositoryAncestors(p);
+    if(next.status!=='applied-receipt-missing' || !same(next.historyIdentity,initial.historyIdentity) ||
+      next.requestDigest!==initial.requestDigest || next.projectionDigest!==initial.projectionDigest)fail('ancestors.drift');
+    initial=next;
+  }
+  await check();const v=(await projection(p)).value;await persist(path.join(p.history,'receipt.json'),receipt(p,v));
+  await ioBoundary('ancestors-receipt-persisted',{history:p.history});
+  const final=await inspectRepositoryAncestors(p);if(final.status!=='completed' || !same(final.historyIdentity,initial.historyIdentity) ||
+    final.requestDigest!==initial.requestDigest || final.projectionDigest!==initial.projectionDigest)fail('ancestors.readback');
+  return {status:'parent-directories-created',history:p.history,requiresRepositoryPreview:true,repositoryEffectsPerformed:false,pipelineActivated:false};
+}
+export async function applyRepositoryAncestors(preview,{ioBoundary=async()=>{}}={}){
+  const p=input(preview);
+  return withRecoveryLease(p.targets[0],async lease=>{
+    await anchor(p);await absent(p.targets[0]);await absent(p.history);
+    await mkdir(p.history,{mode:0o700});const historyId=await directoryId(p.history);
+    async function checkHistory(){assertRecoveryLeaseHeld(lease);await anchor(p);await absent(p.targets[0]);if(!same(await directoryId(p.history),historyId))fail('ancestors.history-drift');}
+    await ioBoundary('ancestors-history-created',{history:p.history});await checkHistory();
+    await persist(path.join(p.history,'request.json'),p);
+    await ioBoundary('ancestors-request-retained',{history:p.history});
+    const directories=[];
+    for(let i=0;i<p.targets.length;i++){
+      await checkHistory();if(!same((await readRecord(path.join(p.history,'request.json'))).value,p))fail('ancestors.request-drift');
+      await mkdir(staged(p,i),{mode:0o700});directories.push({target:p.targets[i],identity:await directoryId(staged(p,i))});
+      await ioBoundary('ancestors-staged-directory',{history:p.history,index:i});
+    }
+    const planned={schemaVersion:1,previewDigest:contractDigest(p),directories};
+    await checkHistory();await persist(path.join(p.history,'projection.json'),planned);
+    await ioBoundary('ancestors-projection-retained',{history:p.history});
+    await checkHistory();if(!same((await projection(p)).value,planned))fail('ancestors.projection-drift');
+    return finish(p,await inspectRepositoryAncestors(p),lease,ioBoundary);
+  });
+}
+export async function finishRepositoryAncestors(preview,observationDigest,{ioBoundary=async()=>{}}={}){
+  const p=input(preview);return withRecoveryLease(p.targets[0],async lease=>{
+    const current=await inspectRepositoryAncestors(p);if(current.digest!==observationDigest)fail('ancestors.approval-drift');
+    if(current.status==='completed')return finish(p,current,lease,ioBoundary);
+    const sequence=current.continuationApprovals.length+1;if(sequence>MAX_APPROVALS)fail('ancestors.approval-limit');
+    assertRecoveryLeaseHeld(lease);
+    if(!same(await inspectRepositoryAncestors(p),current))fail('ancestors.drift');
+    const name='authorization-'+String(sequence).padStart(4,'0')+'.json';
+    const authorization={schemaVersion:1,sequence,decision:'approve-remaining-parent-actions',observation:current};
+    await persist(path.join(p.history,name),authorization);
+    await ioBoundary('ancestors-continuation-authorized',{history:p.history,sequence});
+    if(!same((await readRecord(path.join(p.history,name))).value,authorization))fail('ancestors.approval-drift');
+    const next=await inspectRepositoryAncestors(p),{digest:unused,...withoutDigest}=next;
+    if(!same({...withoutDigest,continuationApprovals:current.continuationApprovals},(({digest,...v})=>v)(current)) ||
+      next.continuationApprovals.length!==sequence)fail('ancestors.drift');
+    return finish(p,next,lease,ioBoundary);
+  });
+}