@6reduk/workspace-pipeline 0.1.0

package/src/operations/repository-resumption-approvals.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import {opendir,open} from 'node:fs/promises';
+import {fail,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {inspectDirectory} from '../workspace/paths.js';
+import {readRecord} from './state.js';
+import {sha256} from '../source/inventory.js';
+import {assertRecoveryLeaseHeld} from './recovery-lease.js';
+
+const exact=(value,keys)=>value && typeof value==='object' && !Array.isArray(value) &&
+  Object.keys(value).sort().join(',')===[...keys].sort().join(',');
+const name=index=>'continuation-'+String(index+1).padStart(6,'0')+'.json';
+const MAX_APPROVALS=128,MAX_BYTES=32*1024*1024;
+
+function validate(value,binding,bindings) {
+  if(!exact(value,['schemaVersion','kind','approval','observation']) || value.schemaVersion!==1 ||
+    value.kind!=='repository-lock-continuation-authorization' ||
+    !exact(value.approval,['decision','resumptionDigest']) || value.approval.decision!=='approve' ||
+    !value.observation || typeof value.observation!=='object')fail('repository-lock.continuation-record');
+  const {digest,...body}=value.observation;
+  if(digest!==value.approval.resumptionDigest || contractDigest(body)!==digest ||
+    body.kind!=='repository-lock-resumption-observation' ||
+    !['resumption-in-progress','gate-archived-resumption-pending'].includes(body.status) ||
+    body.executionAuthorized!==false || body.canResume!==false || body.canReleaseLock!==false ||
+    body.resumptionOwnerLiveness!=='local-pid-absent' ||
+    ['wrapper','lockDigest','recoveryDigest','ownerDigest','approvalDigest'].some(k=>body[k]!==binding[k]) ||
+    contractDigest(body.continuationApprovals??[])!==contractDigest(bindings))
+    fail('repository-lock.continuation-binding');
+}
+
+// Historical approvals are evidence, never permission to execute again. Each new
+// record binds the complete fresh observation and the immutable preceding prefix.
+export async function readResumptionApprovals(directory,binding) {
+  await inspectDirectory(directory);
+  const names=[];
+  for await(const entry of await opendir(directory)) {
+    if(names.length>=MAX_APPROVALS+2)fail('repository-lock.continuation-limit');
+    names.push(entry.name);
+  }
+  const records=names.filter(n=>!['owner.json','approval.json'].includes(n)).sort();
+  if(records.some((n,i)=>n!==name(i)))fail('repository-lock.continuation-entries');
+  const bindings=[];let bytes=0;
+  for(const filename of records) {
+    const record=await readRecord(path.join(directory,filename)),value=record.value;
+    bytes+=Buffer.byteLength(JSON.stringify(value));
+    if(bytes>MAX_BYTES)fail('repository-lock.continuation-limit');
+    validate(value,binding,bindings);
+    bindings.push({name:filename,digest:record.digest});
+  }
+  return bindings;
+}
+
+export async function persistResumptionApproval(directory,observation,approval,lease) {
+  assertRecoveryLeaseHeld(lease);
+  const before=await readResumptionApprovals(directory,observation);
+  if(contractDigest(before)!==contractDigest(observation.continuationApprovals??[]))
+    fail('repository-lock.continuation-drift');
+  if(before.length>=MAX_APPROVALS)fail('repository-lock.continuation-limit');
+  const value={schemaVersion:1,kind:'repository-lock-continuation-authorization',approval,observation};
+  validate(value,observation,before);
+  const bytes=Buffer.from(JSON.stringify(value)+'\n');
+  if(bytes.length>MAX_INPUT_BYTES)fail('repository-lock.continuation-size');
+  let total=bytes.length;
+  for(const prior of before) {
+    const record=await readRecord(path.join(directory,prior.name));
+    if(record.digest!==prior.digest)fail('repository-lock.continuation-drift');
+    total+=Buffer.byteLength(JSON.stringify(record.value));
+  }
+  if(total>MAX_BYTES)fail('repository-lock.continuation-limit');
+  const filename=name(before.length);assertRecoveryLeaseHeld(lease);
+  const handle=await open(path.join(directory,filename),'wx',0o600);
+  try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+  const expected=[...before,{name:filename,digest:sha256(bytes)}];
+  if(contractDigest(await readResumptionApprovals(directory,observation))!==contractDigest(expected))
+    fail('repository-lock.continuation-readback');
+  assertRecoveryLeaseHeld(lease);return expected;
+}

package/src/operations/repository-retention-apply.js

@@ -0,0 +1,75 @@
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {mkdir,unlink,rmdir,lstat} from 'node:fs/promises';
+import {scanRepositoryRetention,inspectRepositoryRetentionFiles} from './repository-retention.js';
+import {assertLockHeld} from './lock.js';
+import {withRecoveryLease,assertRecoveryLeaseHeld} from './recovery-lease.js';
+import {writeCheckedFile} from './apply.js';
+import {readRecord} from './state.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {parse,fail} from '../contracts/parse.js';
+import {inspectDirectory} from '../workspace/paths.js';
+
+// Caller holds an ordinary workspace lock; the kernel lease also excludes
+// recovery writers. Every deletion is an exact inspected file or empty directory.
+export async function applyRepositoryRetention(lock,preview,approval,{boundary=async()=>{},report=async()=>{}}={}) {
+  await assertLockHeld(lock);
+  return withRecoveryLease(lock.workspace,async lease=>{
+    const p=parse(JSON.stringify(preview),'json'),{digest,...body}=p;
+    if(p.kind!=='repository-retention-preview'||!p.complete||p.workspace!==lock.workspace||contractDigest(body)!==digest||
+      contractDigest(approval)!==contractDigest({decision:'approve',previewDigest:digest}))fail('repository-retention.approval');
+    const fresh=await scanRepositoryRetention(lock.workspace,{policy:p.retention.policy,now:p.retention.now,currentRuns:p.currentRuns});
+    if(contractDigest(fresh)!==contractDigest(p))fail('repository-retention.drift');
+    const selected=p.retention.selected.map(s=>p.groups.find(g=>g.id===s.id));
+    if(selected.some(g=>!g||g.status!=='completed'||g.protectionReasons.length||g.paths.length!==2))fail('repository-retention.scope');
+    if(!selected.length)return {status:'completed',removedGroups:0,removedFiles:0,reclaimedBytes:0,receiptPath:null,recoverable:false};
+    const runId=randomUUID(),relative='.pipeline/repository-cleanup/'+runId+'.json',filename=path.join(lock.workspace,relative),directory=path.dirname(filename);
+    const receipt={schemaVersion:1,kind:'repository-retention-result',runId,workspace:lock.workspace,previewDigest:digest,
+      authorization:approval,policy:p.retention.policy,status:'in-progress',recoverable:false,
+      selected:selected.map(g=>({id:g.id,files:g.files.map(f=>({path:f.path,hash:f.hash})),paths:g.paths})),
+      removedFiles:[],removedDirectories:[],completedGroups:[],currentFile:null,reclaimedBytes:0,error:null};
+    parse(JSON.stringify(receipt),'json');
+    let receiptHash=null,created=false,directoryCreated=false;const removed=new Set();
+    const save=async()=>{
+      await assertRecoveryLeaseHeld(lease);const bytes=Buffer.from(JSON.stringify(receipt)+'\n');
+      await writeCheckedFile(lock,relative,receiptHash,bytes,undefined,async phase=>{if(phase==='opened')created=true;});receiptHash=sha256(bytes);created=true;
+    };
+    const guard=async()=>{
+      await assertLockHeld(lock);await assertRecoveryLeaseHeld(lease);
+      const actual=await inspectRepositoryRetentionFiles(lock.workspace);
+      if(created) {
+        if((await readRecord(filename)).digest!==receiptHash)fail('repository-retention.receipt-drift');
+        actual.files=actual.files.filter(f=>f.path!==filename);
+      }
+      if(directoryCreated)actual.directories=actual.directories.filter(d=>d.path!==directory);
+      const expected={files:p.inventory.files.filter(f=>!removed.has(f.path)),directories:p.inventory.directories.filter(d=>!removed.has(d.path))};
+      if(contractDigest(actual)!==contractDigest(expected))fail('repository-retention.drift');
+    };
+    try {
+      await report({kind:'cleanup-location',runId,path:filename,status:'planned'});await guard();
+      directoryCreated=!(await inspectDirectory(directory)).exists;
+      if(directoryCreated)await mkdir(directory);
+      await save();await report({kind:'cleanup-location',runId,path:filename,status:'created'});
+      for(const group of selected) {
+        await boundary('before-group',{id:group.id});await guard();
+        for(const file of group.files) {
+          receipt.currentFile=file.path;await save();await boundary('before-file',{path:file.path});await guard();
+          await inspectDirectory(path.dirname(file.path));const info=await lstat(file.path);
+          if(!info.isFile()||info.isSymbolicLink()||info.nlink!==1||String(info.dev)!==file.dev||String(info.ino)!==file.ino)fail('repository-retention.drift');
+          await unlink(file.path);removed.add(file.path);receipt.removedFiles.push(file.path);receipt.reclaimedBytes+=file.bytes;
+          await boundary('file-removed',{path:file.path});receipt.currentFile=null;await save();
+        }
+        for(const dir of [...group.paths].sort((a,b)=>b.length-a.length)) {
+          await guard();await inspectDirectory(dir);await rmdir(dir);removed.add(dir);receipt.removedDirectories.push(dir);await save();
+        }
+        receipt.completedGroups.push(group.id);await save();
+      }
+      await guard();receipt.status='completed';await save();
+    }catch(error){receipt.status='failed';receipt.error=error.code??'repository-retention.io';try{if(created)await save();}catch{receipt.receiptUpdate='failed';}}
+    const result={status:receipt.status,error:receipt.error,runId,receiptPath:filename,receiptCreated:created,
+      removedGroups:receipt.completedGroups.length,removedFiles:receipt.removedFiles.length,reclaimedBytes:receipt.reclaimedBytes,
+      uncompletedGroups:selected.filter(g=>!receipt.completedGroups.includes(g.id)).map(g=>g.id),recoverable:false,receiptUpdate:receipt.receiptUpdate??'saved'};
+    try{await report({kind:'cleanup-result',...result});}catch{result.outputError='repository-retention.report';}return result;
+  });
+}

package/src/operations/repository-retention.js

@@ -0,0 +1,137 @@
+import path from 'node:path';
+import {lstat,readdir,open} from 'node:fs/promises';
+import {absoluteRoot,inspectDirectory,resolveChild} from '../workspace/paths.js';
+import {fail,parse} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {readRecord,readState} from './state.js';
+import {readRepositoryJournal} from './repository-journal.js';
+import {readRepositoryInputs} from './repository-inputs.js';
+import {verifyRepositoryAuthorization} from './repository-authorization.js';
+import {repositoryContentDigest} from './repository-apply.js';
+import {listRepositoryHistory} from './repository-history.js';
+import {planRetention} from './retention.js';
+import {bootstrapLockDirectory} from './bootstrap-lock.js';
+import {validateInventorySummary} from '../workspace/repository-observation.js';
+
+function validEvidenceInventory(v) {
+  if(v?.kind==='repository-inventory-summary'){validateInventorySummary(v);return true;}
+  return Array.isArray(v?.entries) && v.digest===sha256(Buffer.from(JSON.stringify(v.entries)));
+}
+
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const same=(a,b)=>contractDigest(a)===contractDigest(b);
+const namespaces=['repository-journals','repository-evidence','repository-inputs','repository-authorizations','repository-completions'];
+const idFor=relative=>{const m=/^\.pipeline\/(repository-journals|repository-evidence|repository-inputs|repository-authorizations|repository-completions)\/([a-f0-9-]{36})(?:\/|\.pending\.json$|\.json$|$)/.exec(relative);return m&&uuid.test(m[2])?m[2]:null;};
+
+// Bounded reference scan includes arbitrary retained metadata, not only known
+// recovery formats. Parsed strings catch JSON-escaped identifiers. No contents
+// are returned. Runtime repositories/provider roots are outside this inventory.
+export async function inspectRepositoryRetentionFiles(workspace) {
+  workspace=absoluteRoot(workspace);await inspectDirectory(workspace);
+  const files=[],directories=[];let count=0,total=0;
+  const walk=async(filename,depth)=>{
+    if(depth>32||++count>20000)fail('repository-retention.limit');
+    const before=await lstat(filename);
+    if(before.isSymbolicLink()||(!before.isFile()&&!before.isDirectory())||(before.isFile()&&before.nlink!==1))fail('repository-retention.type');
+    if(before.isDirectory()) {
+      await inspectDirectory(filename);
+      directories.push({path:filename,dev:String(before.dev),ino:String(before.ino)});
+      for(const name of (await readdir(filename)).sort()) {
+        if(filename===path.join(workspace,'.pipeline')&&name==='lock')continue;
+        await walk(path.join(filename,name),depth+1);
+      }
+      const after=await lstat(filename);
+      if(after.dev!==before.dev||after.ino!==before.ino||after.mtimeMs!==before.mtimeMs)fail('repository-retention.drift');
+      return;
+    }
+    total+=before.size;if(before.size>8*1024*1024||total>128*1024*1024)fail('repository-retention.limit');
+    const handle=await open(filename,'r');let bytes;
+    try {
+      const opened=await handle.stat();if(!opened.isFile()||opened.nlink!==1||opened.dev!==before.dev||opened.ino!==before.ino||opened.size!==before.size)fail('repository-retention.drift');
+      const buffer=Buffer.alloc(before.size+1);let length=0;
+      while(length<buffer.length){const read=await handle.read(buffer,length,buffer.length-length,null);if(!read.bytesRead)break;length+=read.bytesRead;}
+      bytes=buffer.subarray(0,length);
+    }finally{await handle.close();}
+    const after=await lstat(filename);
+    if(after.dev!==before.dev||after.ino!==before.ino||after.mtimeMs!==before.mtimeMs||bytes.length!==before.size)fail('repository-retention.drift');
+    let text=bytes.toString('utf8');if(filename.endsWith('.json'))text=JSON.stringify(parse(text,'json'));
+    const references=[...new Set([
+      ...(text.match(/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/gi)??[]).map(s=>s.toLowerCase()),
+      ...(text.match(/[a-f0-9]{64}/gi)??[]).map(s=>'sha256:'+s.toLowerCase())])].sort();
+    files.push({path:filename,hash:sha256(bytes),bytes:bytes.length,mtimeMs:before.mtimeMs,dev:String(before.dev),ino:String(before.ino),references});
+  };
+  const metadata=path.join(workspace,'.pipeline');if((await inspectDirectory(metadata)).exists)await walk(metadata,0);
+  const history=await listRepositoryHistory(workspace);
+  if(!history.complete)fail('repository-retention.history-incomplete');
+  for(const entry of history.entries)if(!entry.path.startsWith(metadata+path.sep))await walk(entry.path,0);
+  files.sort((a,b)=>a.path.localeCompare(b.path));directories.sort((a,b)=>a.path.localeCompare(b.path));
+  return {files,directories};
+}
+
+async function verifyHistoricalGroup(workspace,id,files) {
+  const journal='.pipeline/repository-journals/'+id,base='.pipeline/repository-completions/'+id;
+  const receipt=await readRecord(resolveChild(workspace,base+'.json')),r=receipt.value;
+  const digest=r.reconciliation?.previewDigest,input=await readRepositoryInputs(workspace,journal,digest),preview=parse(input.previewText,'json');
+  const history=await readRepositoryJournal(workspace,journal,preview);
+  if(history.phase!=='terminal'||history.operations.some(o=>o.status!=='completed'))fail('repository-retention.incomplete');
+  const pending=await readRecord(resolveChild(workspace,base+'.pending.json'));
+  if(!same(pending.value,{schemaVersion:1,previewDigest:digest,journal,status:'requires-reconciliation'}))fail('repository-retention.marker');
+  const bindings=await verifyRepositoryAuthorization(workspace,journal,preview,history.authorization),observations=[];
+  const allowed=new Set([base+'.json',base+'.pending.json','.pipeline/repository-inputs/'+id+'.json',
+    ...Array.from({length:history.sequence},(_,i)=>journal+'/'+String(i).padStart(6,'0')+'.json')]);
+  if(history.authorization)allowed.add(history.authorization.path);
+  for(let i=0;i<preview.operations.length;i++) {
+    const op=preview.operations[i],relative='.pipeline/repository-evidence/'+id+'/'+String(i).padStart(6,'0')+'.json';
+    allowed.add(relative);const record=await readRecord(resolveChild(workspace,relative)),e=record.value;
+    if(Object.keys(e).sort().join(',')!=='action,contentDigest,inventory,previewDigest,repository,schemaVersion,sourceAbsent,target'||
+      !validEvidenceInventory(e.inventory)||
+      record.digest!==history.operations[i].evidenceDigest||e.schemaVersion!==1||e.previewDigest!==digest||e.repository!==op.repository||
+      e.action!==op.action||e.target!==op.target||e.inventory?.root!==op.target||e.sourceAbsent!==(op.action==='move'?true:null)||
+      e.contentDigest!==repositoryContentDigest(e.inventory))fail('repository-retention.evidence');
+    bindings.push({path:relative,digest:record.digest});observations.push({repository:op.repository,claimedStatus:'completed',state:'completed-verified',targetDigest:e.inventory.digest,sourceDigest:null});
+  }
+  const body={kind:'repository-reconciliation',wrapper:workspace,previewDigest:digest,markerDigest:pending.digest,journal,
+    journalHead:history.lastHash,evidenceBindings:bindings,observations,canFinalize:true,executionAuthorized:false};
+  if(!same(r,{schemaVersion:1,status:'repository-effects-verified',reconciliation:{...body,digest:contractDigest(body)},pipelineActivated:false}))fail('repository-retention.completion');
+  const actual=files.map(f=>path.relative(workspace,f.path).split(path.sep).join('/'));
+  if(actual.length!==allowed.size||actual.some(p=>!allowed.has(p)))fail('repository-retention.foreign');
+}
+
+export async function scanRepositoryRetention(workspace,{policy,now,currentRuns=[]}) {
+  workspace=absoluteRoot(workspace);planRetention({journals:[],policy,now});
+  if(!Array.isArray(currentRuns)||currentRuns.some(id=>!uuid.test(id)))fail('repository-retention.current-runs');
+  const diagnostics=[],groups=[];let inventory;
+  try{inventory=await inspectRepositoryRetentionFiles(workspace);}catch(error){diagnostics.push({code:error.code??'repository-retention.io'});inventory={files:[],directories:[]};}
+  try {
+    const state=await readState(resolveChild(workspace,'.pipeline/state.json'));
+    if(state.value.pending!==null)diagnostics.push({code:'repository-retention.configuration-pending'});
+  }catch(error){if(error.code!=='record.missing')diagnostics.push({code:error.code??'repository-retention.state'});}
+  const relative=f=>path.relative(workspace,f.path).split(path.sep).join('/');
+  const ids=[...new Set([...inventory.files,...inventory.directories].map(f=>idFor(relative(f))).filter(Boolean))].sort();
+  for(const id of ids) {
+    const files=inventory.files.filter(f=>idFor(relative(f))===id),paths=inventory.directories.filter(d=>idFor(relative(d))===id).map(d=>d.path);
+    const reasons=[];let status='completed';
+    try {
+      if(paths.length!==2||!['repository-journals','repository-evidence'].every(n=>paths.includes(path.join(workspace,'.pipeline',n,id))))fail('repository-retention.foreign');
+      await verifyHistoricalGroup(workspace,id,files);
+    }catch(error){status='unknown';reasons.push('inspection-failed');diagnostics.push({code:error.code??'repository-retention.invalid',subject:id});}
+    if(currentRuns.includes(id))reasons.push('current-run');
+    const subjects=new Set([id,...files.map(f=>f.hash)]);
+    if(inventory.files.some(f=>idFor(relative(f))!==id&&f.references.some(ref=>subjects.has(ref))))reasons.push('retained-reference');
+    groups.push({id,status,files,paths,bytes:files.reduce((n,f)=>n+f.bytes,0),completedAt:status==='completed'?Math.floor(Math.max(...files.map(f=>f.mtimeMs))):null,protectionReasons:reasons});
+  }
+  const marker=inventory.files.some(f=>relative(f)==='.pipeline/repository-operation.json');
+  if(marker)diagnostics.push({code:'repository-retention.pending'});
+  const bootstrap=bootstrapLockDirectory(workspace);
+  if(inventory.directories.some(d=>[bootstrap,bootstrap+'.recovery',bootstrap+'.recovery-resume'].includes(d.path)))
+    diagnostics.push({code:'repository-retention.recovery-pending'});
+  for(const f of [...inventory.files,...inventory.directories]) {
+    const p=relative(f);if(namespaces.some(n=>p.startsWith('.pipeline/'+n+'/'))&&!idFor(p))diagnostics.push({code:'repository-retention.foreign',subject:f.path});
+  }
+  if(diagnostics.length)for(const g of groups)g.protectionReasons=[...new Set([...g.protectionReasons,'inspection-failed'])];
+  if(!diagnostics.length&&!same(inventory,await inspectRepositoryRetentionFiles(workspace)))fail('repository-retention.drift');
+  const retention=planRetention({now,policy,journals:groups.map(({id,status,bytes,completedAt,protectionReasons})=>({id,status,bytes,completedAt,protectionReasons}))});
+  const body={kind:'repository-retention-preview',workspace,currentRuns,groups,inventory,retention,diagnostics,complete:diagnostics.length===0,
+    runtimeVerified:false,automaticActions:false};return {...body,digest:contractDigest(body)};
+}

package/src/operations/repository-workspace.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { lstat,mkdir,open } from 'node:fs/promises';
+import { fail,MAX_INPUT_BYTES } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { sha256 } from '../source/inventory.js';
+import { inspectDirectory } from '../workspace/paths.js';
+import { revalidateRepositoryPreview } from '../workspace/repository-preview.js';
+import { inspectRepositoryBootstrap } from './repository-bootstrap-reconcile.js';
+import { createRepositoryWrapper } from './repository-bootstrap.js';
+import { applyRepositoryOperations } from './repository-apply.js';
+import { readRecord } from './state.js';
+
+// Internal orchestration of already-authorized wrapper + repository effects.
+// Only the newly created wrapper's identity/ancestor observations may change.
+// This is a mechanical authorization projection, never a new human approval.
+export async function applyRepositoryWorkspace(args) {
+  const {pipeline,workspace,wrapper,choices,options={},previewText,approval,
+    ioBoundary=async()=>{}}=args;
+  if(!approval || Object.keys(approval).sort().join(',')!=='decision,previewDigest' || approval.decision!=='approve')
+    fail('repository-workspace.approval');
+  const original=await revalidateRepositoryPreview(previewText,approval.previewDigest,pipeline,workspace,wrapper,choices,options);
+  if(original.wrapperObservation.action==='keep')return applyRepositoryOperations(args);
+  // Refuse unsupported missing ancestors before creating anything.
+  if(!(await inspectDirectory(path.dirname(original.wrapper))).exists ||
+    original.operations.some(op=>path.dirname(op.target)!==original.wrapper))fail('repository-workspace.ancestors-unsupported');
+  const bootstrap=await createRepositoryWrapper(args);
+  const checked=await inspectRepositoryBootstrap(original.wrapper,previewText,original.digest);
+  if(checked.status!=='handoff-recorded')fail('repository-workspace.bootstrap-state');
+  const receipt=await readRecord(bootstrap.receipt);
+  if(receipt.digest!==checked.recordDigests.receipt)fail('repository-workspace.bootstrap-drift');
+  await ioBoundary('workspace-bootstrap-completed',{receipt:bootstrap.receipt});
+  const identity=receipt.value.identity;
+  const {digest:oldDigest,...body}=structuredClone(original);
+  body.wrapperObservation={action:'keep',path:original.wrapper,identity};
+  for(const op of body.operations) {
+    if(!op.destination || op.destination.ancestor!==path.dirname(original.wrapper) ||
+      contractDigest(op.destination.ancestorIdentity)!==contractDigest(original.wrapperObservation.ancestorIdentity))
+      fail('repository-workspace.projection');
+    op.destination={...op.destination,ancestor:original.wrapper,ancestorIdentity:identity};
+  }
+  const derived={...body,digest:contractDigest(body)};
+  const derivedText=JSON.stringify(derived);
+  // Reconstruct all semantics from the original inputs. Source bytes/commit,
+  // manifest bytes, target absence, and prepared remote bindings remain exact.
+  await revalidateRepositoryPreview(derivedText,derived.digest,pipeline,workspace,wrapper,choices,options);
+  let authorizationFile,authorizationDigest;
+  const result=await applyRepositoryOperations({...args,previewText:derivedText,
+    approval:{decision:'approve',previewDigest:derived.digest},ioBoundary:async(phase,detail)=>{
+      if(phase==='repository-run-started') {
+        const current=await readRecord(bootstrap.receipt);
+        const history=await readRecord(path.join(original.wrapper,'.pipeline/repository-bootstrap-intent.json'));
+        if(current.digest!==receipt.digest || history.digest!==checked.recordDigests.history)
+          fail('repository-workspace.bootstrap-drift');
+        const stat=await lstat(original.wrapper,{bigint:true});
+        if(String(stat.dev)!==identity.dev || String(stat.ino)!==identity.ino)fail('repository-workspace.bootstrap-drift');
+        const directory=path.join(original.wrapper,'.pipeline/repository-authorizations');
+        try{await mkdir(directory);}catch(e){if(e.code!=='EEXIST')throw e;}
+        await inspectDirectory(directory);
+        authorizationFile=path.join(directory,path.basename(detail.journal)+'.json');
+        const bytes=Buffer.from(JSON.stringify({schemaVersion:1,kind:'wrapper-creation-projection',
+          originalPreview:original,originalApproval:{decision:'approve',previewDigest:original.digest},derivedPreview:derived,
+          bootstrapReceiptDigest:receipt.digest,bootstrapIntentDigest:history.digest,
+          journal:detail.journal,newHumanApproval:false})+'\n');
+        if(bytes.length>MAX_INPUT_BYTES)fail('repository-workspace.authorization-size');
+        const handle=await open(authorizationFile,'wx',0o600);
+        try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+        authorizationDigest=sha256(bytes);
+        if((await readRecord(authorizationFile)).digest!==authorizationDigest)fail('repository-workspace.authorization-readback');
+      }
+      await ioBoundary(phase,detail);
+      if(authorizationFile && (await readRecord(authorizationFile)).digest!==authorizationDigest)
+        fail('repository-workspace.authorization-drift');
+      if(phase==='repository-run-started')return {
+        path:detail.journal.replace('/repository-journals/','/repository-authorizations/')+'.json',digest:authorizationDigest};
+    }});
+  return {...result,originalPreviewDigest:original.digest,executionPreview:derived,
+    authorizationFile,authorizationDigest,bootstrapReceipt:bootstrap.receipt};
+}

package/src/operations/retention-apply.js

@@ -0,0 +1,133 @@
+import {mkdir,readdir,lstat,unlink,rmdir} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {scanRetention} from './retention-scan.js';
+import {scanCombinedRetention} from './retention-combined-scan.js';
+import {assertLockHeld} from './lock.js';
+import {readRecord} from './state.js';
+import {writeCheckedFile} from './apply.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {parse,fail,ContractError} from '../contracts/parse.js';
+import {requestShape} from './ownership.js';
+import {sha256} from '../source/inventory.js';
+import {readRetentionPolicy,retentionLimits} from './retention-policy.js';
+
+// Exact approved journal-group deletion only. No recursive deletion, snapshot or
+// backup cleanup, lock stealing, rollback, or provider/project writes.
+export async function applyRetention(lock,preview,approval,{boundary=async()=>{},report=async()=>{}}={}) {
+  const p=parse(JSON.stringify(preview),'json'),a=parse(JSON.stringify(approval),'json');
+  const combined=p.kind==='combined-retention-filesystem-preview';
+  const key=g=>combined?g.type+':'+g.id:g.id;
+  const automatic=a.decision==='workspace-policy';
+  requestShape(a,automatic?['decision','policyHash']:['decision','previewDigest'],[],'retention-apply.approval');
+  const {digest,...body}=p;
+  if(!['retention-filesystem-preview','combined-retention-filesystem-preview'].includes(p.kind) || contractDigest(body)!==digest || !p.complete ||
+      p.workspace!==lock.workspace || (!automatic && (a.decision!=='approve' || a.previewDigest!==digest)))fail('retention-apply.approval');
+  async function guardPolicy() {
+    if(!automatic)return;
+    const current=await readRetentionPolicy(lock.workspace);
+    if(current.mode!=='automatic' || current.hash!==a.policyHash ||
+        (current.policy.schemaVersion===2)!==combined ||
+        contractDigest(retentionLimits(current.policy))!==contractDigest(p.retention.policy))fail('retention-apply.policy-drift');
+  }
+  const options={policy:p.retention.policy,now:p.retention.now,currentRuns:p.currentRuns};
+  await assertLockHeld(lock);
+  await guardPolicy();
+  if(contractDigest(await (combined?scanCombinedRetention:scanRetention)(lock.workspace,options))!==contractDigest(p))fail('retention-apply.drift');
+  const selected=p.retention.selected.map(s=>p.groups.find(g=>key(g)===key(s)));
+  if(selected.some(g=>!g || g.status!=='journal-completed' || g.protectionReasons.length ||
+      (g.type==='cleanup-receipt'?(g.paths.length!==0||g.files.length!==1):g.paths.length!==2)))fail('retention-apply.scope');
+  // Neither policy version creates persistent receipts for a no-work pass.
+  // Approval and fresh inventory checks above still apply; emit only the result.
+  if(selected.length===0) {
+    const result={status:'completed',error:null,runId:null,receiptPath:null,receiptCreated:false,
+      removedGroups:0,removedFiles:0,reclaimedBytes:0,selectedGroups:0,uncompletedGroups:[],recoverable:false,receiptUpdate:'not-created'};
+    try{await report({kind:'cleanup-result',...result});}catch{result.outputError='retention-apply.report';}
+    return result;
+  }
+  const runId=randomUUID(),relative='.pipeline/cleanup/'+runId+'.json',filename=resolveChild(lock.workspace,relative);
+  const receipt={schemaVersion:combined?2:1,kind:'retention-result',runId,workspace:lock.workspace,previewDigest:digest,
+    policy:p.retention.policy,authorization:a,status:'in-progress',recoverable:false,
+    groups:selected.map(g=>({id:g.id,...combined?{type:g.type}:{},paths:g.paths,files:g.files})),removedFiles:[],removedDirectories:[],completedGroups:[],
+    currentFile:null,error:null,reclaimedBytes:0};
+  // Bound receipt size before even creating its directory; no payload secrets.
+  parse(JSON.stringify(receipt),'json');
+  let receiptHash=null,created=false;
+  const removedFiles=new Set(),removedDirectories=new Set();
+  async function save() {
+    const bytes=Buffer.from(JSON.stringify(receipt)+'\n');parse(bytes.toString('utf8'),'json');
+    await writeCheckedFile(lock,relative,receiptHash,bytes,undefined,async phase=>{
+      if(receiptHash===null && phase==='opened')created=true;
+    });receiptHash=sha256(bytes);created=true;
+  }
+  async function checkFile(file) {
+    const target=resolveChild(lock.workspace,file.path),info=await lstat(target);
+    if(!info.isFile() || info.isSymbolicLink() || info.nlink!==1 || info.size!==file.bytes || info.mtimeMs!==file.mtimeMs ||
+        (await readRecord(target)).digest!==file.hash)fail('retention-apply.drift');
+  }
+  async function guardReferences() {
+    await assertLockHeld(lock);
+    await guardPolicy();
+    let stateHash=null;
+    try{stateHash=(await readRecord(resolveChild(lock.workspace,'.pipeline/state.json'))).digest;}
+    catch(error){if(error.code!=='record.missing')throw error;}
+    if(stateHash!==p.stateFileHash)fail('retention-apply.state-drift');
+    for(const base of ['.pipeline/journals','.pipeline/transactions']) {
+      const expected=p.groups.flatMap(g=>g.paths).filter(d=>d.startsWith(base+'/') && !removedDirectories.has(d)).map(d=>d.slice(base.length+1)).sort();
+      const directory=resolveChild(lock.workspace,base),exists=(await inspectDirectory(directory)).exists;
+      const names=exists?(await readdir(directory)).sort():[];
+      if(JSON.stringify(names)!==JSON.stringify(expected))fail('retention-apply.inventory-drift');
+    }
+    // Bound to the inspected records: new references invalidate cleanup. This is
+    // a conservative per-file record check, not a claim of linear overall cost.
+    for(const group of p.groups)for(const file of group.files)
+      if((file.path.endsWith('/recovery.json') || group.type==='cleanup-receipt') && !removedFiles.has(file.path))await checkFile(file);
+    if(combined) {
+      const base='.pipeline/cleanup',directory=resolveChild(lock.workspace,base);
+      const expected=p.groups.filter(g=>g.type==='cleanup-receipt').flatMap(g=>g.files)
+        .filter(f=>!removedFiles.has(f.path)).map(f=>f.path.slice(base.length+1));
+      if(created)expected.push(runId+'.json');
+      const actual=(await inspectDirectory(directory)).exists?await readdir(directory):[];
+      if(JSON.stringify(actual.sort())!==JSON.stringify(expected.sort()))fail('retention-apply.inventory-drift');
+      if(created&&(await readRecord(filename)).digest!==receiptHash)fail('retention-apply.receipt-drift');
+    }
+  }
+  try {
+    await report({kind:'cleanup-location',runId,path:filename,status:'planned'});
+    await guardReferences();
+    const parent=resolveChild(lock.workspace,'.pipeline/cleanup');
+    try{await mkdir(parent);}catch(error){if(error.code!=='EEXIST')throw error;}
+    await inspectDirectory(parent);await save();
+    await report({kind:'cleanup-location',runId,path:filename,status:'created'});
+    for(const group of selected) {
+      await boundary('before-group',{id:group.id});await guardReferences();
+      for(const directory of group.paths) {
+        const expected=group.files.filter(f=>f.path.startsWith(directory+'/')).map(f=>f.path.slice(directory.length+1)).sort();
+        if(JSON.stringify((await readdir(resolveChild(lock.workspace,directory))).sort())!==JSON.stringify(expected))fail('retention-apply.inventory-drift');
+      }
+      for(const file of group.files) {
+        receipt.currentFile=file.path;await save();
+        await boundary('before-file',{path:file.path});await guardReferences();await checkFile(file);
+        await unlink(resolveChild(lock.workspace,file.path));
+        removedFiles.add(file.path);receipt.removedFiles.push(file.path);receipt.reclaimedBytes+=file.bytes;
+        await boundary('file-removed',{path:file.path});receipt.currentFile=null;await save();
+      }
+      for(const directory of group.paths) {
+        await guardReferences();await inspectDirectory(resolveChild(lock.workspace,directory));
+        await rmdir(resolveChild(lock.workspace,directory)); // empty only; never recursive
+        removedDirectories.add(directory);receipt.removedDirectories.push(directory);await save();
+      }
+      receipt.completedGroups.push(key(group));await save();
+    }
+    await guardReferences();receipt.status='completed';await save();
+  }catch(error) {
+    receipt.status='failed';receipt.error=error instanceof ContractError?error.code:'retention-apply.io';
+    try{if(created)await save();}catch{receipt.receiptUpdate='failed';}
+  }
+  const result={status:receipt.status,error:receipt.error,runId,receiptPath:filename,receiptCreated:created,
+    removedGroups:receipt.completedGroups.length,removedFiles:receipt.removedFiles.length,reclaimedBytes:receipt.reclaimedBytes,
+    selectedGroups:selected.length,uncompletedGroups:selected.filter(g=>!receipt.completedGroups.includes(key(g))).map(key),
+    recoverable:false,receiptUpdate:receipt.receiptUpdate??'saved'};
+  try{await report({kind:'cleanup-result',...result});}catch{result.outputError='retention-apply.report';}
+  return result;
+}

package/src/operations/retention-combined-scan.js

@@ -0,0 +1,30 @@
+import {scanRetention} from './retention-scan.js';
+import {scanCleanupReceipts} from './retention-receipts.js';
+import {planCombinedRetention} from './retention-combined.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail} from '../contracts/parse.js';
+
+export async function scanCombinedRetention(workspace,{policy,now,currentRuns=[]}) {
+  planCombinedRetention({journals:[],receipts:[],policy,now});
+  const journals=await scanRetention(workspace,{policy:{...policy.journals,maxDeletesPerRun:policy.maxDeletesPerRun},now,currentRuns});
+  const receipts=await scanCleanupReceipts(workspace,{currentRuns});
+  for(const binding of receipts.bindings) {
+    const expected=binding.path==='.pipeline/state.json'?journals.stateFileHash:
+      journals.groups.flatMap(g=>g.files).find(f=>f.path===binding.path)?.hash;
+    if(expected!==binding.hash)fail('retention-combined.drift');
+  }
+  const complete=journals.complete&&receipts.complete;
+  const groups=[...journals.groups.map(g=>({...g,type:'journal'})),...receipts.records.map(r=>({
+    id:r.id,type:'cleanup-receipt',status:r.status==='completed'?'journal-completed':r.status,
+    paths:[],files:r.hash?[{path:r.path,hash:r.hash,bytes:r.bytes,mtimeMs:r.mtimeMs}]:[],
+    protectionReasons:[...r.protectionReasons],bytes:r.bytes,completedAt:r.completedAt
+  }))].map(g=>({...g,protectionReasons:[...new Set([...g.protectionReasons,...complete?[]:['inspection-failed']])].sort()}));
+  const observations=type=>groups.filter(g=>g.type===type).map(g=>({id:g.id,
+    status:g.status==='journal-completed'?'completed':g.status==='uncertain'?'uncertain':'unknown',
+    completedAt:g.completedAt,bytes:g.bytes,protectionReasons:g.protectionReasons}));
+  const retention=planCombinedRetention({journals:observations('journal'),receipts:observations('cleanup-receipt'),policy,now});
+  const body={kind:'combined-retention-filesystem-preview',workspace:journals.workspace,
+    stateFileHash:journals.stateFileHash,currentRuns:[...currentRuns],groups,retention,
+    diagnostics:[...journals.diagnostics,...receipts.diagnostics],complete,applySupported:false,automaticActions:false};
+  return {...body,digest:contractDigest(body)};
+}

package/src/operations/retention-combined.js

@@ -0,0 +1,41 @@
+import {planRetention} from './retention.js';
+import {requestShape} from './ownership.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail} from '../contracts/parse.js';
+
+// Pure planning only: observations must come from verified filesystem scanners.
+// Never grants permission to delete or treats an observed completed flag as proof.
+export function planCombinedRetention(input) {
+  requestShape(input,['journals','receipts','policy','now'],[],'retention-combined.input');
+  const {journals,receipts,policy,now}=input;
+  requestShape(policy,['journals','cleanupReceipts','maxDeletesPerRun'],[],'retention-combined.policy');
+  requestShape(policy.journals,['maxAgeDays','maxJournals'],[],'retention-combined.policy');
+  requestShape(policy.cleanupReceipts,['maxAgeDays','maxReceipts'],[],'retention-combined.policy');
+  if(!Number.isSafeInteger(policy.maxDeletesPerRun) || policy.maxDeletesPerRun<0)fail('retention-combined.policy');
+  const classes=[
+    ['journal',journals,policy.journals.maxAgeDays,policy.journals.maxJournals],
+    ['cleanup-receipt',receipts,policy.cleanupReceipts.maxAgeDays,policy.cleanupReceipts.maxReceipts]
+  ].map(([type,items,maxAgeDays,maxJournals])=>({type,maxAgeDays,maxCount:maxJournals,
+    plan:planRetention({journals:items,now,policy:{maxAgeDays,maxJournals,maxDeletesPerRun:Number.MAX_SAFE_INTEGER}})}));
+  const order=(a,b)=>a.completedAt-b.completedAt || (a.type<b.type?-1:a.type>b.type?1:a.id<b.id?-1:a.id>b.id?1:0);
+  const candidates=classes.flatMap(c=>c.plan.selected.map(item=>({...item,type:c.type}))).sort(order);
+  const selected=candidates.slice(0,policy.maxDeletesPerRun),deferred=candidates.slice(policy.maxDeletesPerRun);
+  const selectedKeys=new Set(selected.map(item=>item.type+':'+item.id));
+  const perClass=classes.map(c=>{
+    const chosen=selected.filter(item=>item.type===c.type);
+    const remaining=c.plan.observed.filter(item=>!selectedKeys.has(c.type+':'+item.id));
+    return {type:c.type,observedCount:c.plan.observed.length,observedBytes:c.plan.totals.observedBytes,
+      selectedCount:chosen.length,selectedBytes:chosen.reduce((n,item)=>n+item.bytes,0),
+      protectedCount:c.plan.protected.length,remainingCount:remaining.length,
+      remainingOverCount:Math.max(0,remaining.length-c.maxCount),
+      remainingOverAge:remaining.filter(item=>item.completedAt!==null && now-item.completedAt>c.maxAgeDays*86400000).length};
+  });
+  const observedBytes=perClass.reduce((n,c)=>n+c.observedBytes,0);
+  if(!Number.isSafeInteger(observedBytes))fail('retention-combined.bytes');
+  const body={kind:'combined-retention-preview',now,policy:structuredClone(policy),selected,deferred,
+    protected:classes.flatMap(c=>c.plan.protected.map(item=>({...item,type:c.type}))),perClass,
+    totals:{observedCount:perClass.reduce((n,c)=>n+c.observedCount,0),observedBytes,
+      selectedCount:selected.length,selectedBytes:selected.reduce((n,item)=>n+item.bytes,0)},
+    requiresFilesystemValidation:true,automaticActions:false};
+  return {...body,digest:contractDigest(body)};
+}