@6reduk/workspace-pipeline 0.1.0

package/src/operations/retention-policy.js

@@ -0,0 +1,65 @@
+import {readRecord} from './state.js';
+import {writeCheckedFile} from './apply.js';
+import {assertLockHeld} from './lock.js';
+import {requestShape} from './ownership.js';
+import {planRetention} from './retention.js';
+import {planCombinedRetention} from './retention-combined.js';
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {parse,fail} from '../contracts/parse.js';
+
+export const retentionPolicyPath='.pipeline/retention.json';
+export function validateRetentionPolicy(value,workspace) {
+  requestShape(value,['schemaVersion','kind','workspace','mode','journals'],['cleanupReceipts','maxDeletesPerRun'],'retention-policy.shape');
+  if(![1,2].includes(value.schemaVersion) || value.kind!=='workspace-retention-policy' ||
+      value.workspace!==absoluteRoot(workspace) || !['automatic','disabled'].includes(value.mode))fail('retention-policy.binding');
+  if(value.schemaVersion===1) {
+    if(Object.hasOwn(value,'cleanupReceipts')||Object.hasOwn(value,'maxDeletesPerRun'))fail('retention-policy.shape');
+    planRetention({journals:[],policy:value.journals,now:0});
+  }else planCombinedRetention({journals:[],receipts:[],policy:retentionLimits(value),now:0});
+  return structuredClone(value);
+}
+export function retentionLimits(policy) {
+  return policy.schemaVersion===1?policy.journals:{journals:policy.journals,
+    cleanupReceipts:policy.cleanupReceipts,maxDeletesPerRun:policy.maxDeletesPerRun};
+}
+export async function readRetentionPolicy(workspace) {
+  workspace=absoluteRoot(workspace);const path=resolveChild(workspace,retentionPolicyPath);
+  let record;
+  try{record=await readRecord(path);}catch(e){if(e.code!=='record.missing')throw e;}
+  const policy=record?validateRetentionPolicy(record.value,workspace):null;
+  return {workspace,path,hash:record?.digest??null,mode:policy?.mode??'disabled',policy};
+}
+export async function previewRetentionPolicy(workspace,request) {
+  requestShape(request,['action'],['mode','journals','cleanupReceipts','maxDeletesPerRun'],'retention-policy.request');
+  if(!['set','disable'].includes(request.action))fail('retention-policy.request');
+  const before=await readRetentionPolicy(workspace);let result;
+  if(request.action==='disable') {
+    if(Object.keys(request).length!==1)fail('retention-policy.request');
+    result=before.policy?{...before.policy,mode:'disabled'}:null;
+  }else {
+    const v2=Object.hasOwn(request,'cleanupReceipts');
+    if(!v2&&Object.hasOwn(request,'maxDeletesPerRun'))fail('retention-policy.request');
+    result=validateRetentionPolicy({schemaVersion:v2?2:1,kind:'workspace-retention-policy',
+      workspace:before.workspace,mode:request.mode,journals:request.journals,
+      ...v2?{cleanupReceipts:request.cleanupReceipts,maxDeletesPerRun:request.maxDeletesPerRun}:{}},before.workspace);
+  }
+  const body={kind:'retention-policy-preview',workspace:before.workspace,action:request.action,
+    beforeHash:before.hash,result,
+    warning:result?.schemaVersion===2?'Automatic mode authorizes future eligible journal and cleanup-receipt deletion under one shared cap; no cleanup is performed by this policy update.':
+      'Automatic mode authorizes future eligible journal deletion within these limits; no cleanup is performed by this policy update.'};
+  return {...body,digest:contractDigest(body)};
+}
+export async function applyRetentionPolicy(lock,preview,approval) {
+  await assertLockHeld(lock);
+  const p=parse(JSON.stringify(preview),'json');
+  requestShape(p,['kind','workspace','action','beforeHash','result','warning','digest'],[],'retention-policy.preview');
+  requestShape(approval,['decision','previewDigest'],[],'retention-policy.approval');
+  if(p.workspace!==lock.workspace || approval.decision!=='approve' || approval.previewDigest!==p.digest)fail('retention-policy.approval');
+  const request=p.action==='disable'?{action:'disable'}:{action:p.action,mode:p.result?.mode,journals:p.result?.journals,
+    ...p.result?.schemaVersion===2?{cleanupReceipts:p.result.cleanupReceipts,maxDeletesPerRun:p.result.maxDeletesPerRun}:{}};
+  const fresh=await previewRetentionPolicy(lock.workspace,request);
+  if(contractDigest(p)!==contractDigest(fresh))fail('retention-policy.drift');
+  if(p.result!==null)await writeCheckedFile(lock,retentionPolicyPath,p.beforeHash,Buffer.from(JSON.stringify(p.result)+'\n'));
+  return {status:'completed',...await readRetentionPolicy(lock.workspace),cleanupPerformed:false};
+}

package/src/operations/retention-receipts.js

@@ -0,0 +1,126 @@
+import {readdir,lstat} from 'node:fs/promises';
+import {readRecord,readState} from './state.js';
+import {inspectHistory} from './history.js';
+import {absoluteRoot,resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {requestShape} from './ownership.js';
+import {planRetention} from './retention.js';
+import {planCombinedRetention} from './retention-combined.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail} from '../contracts/parse.js';
+
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?![\s\S])/;
+const hash=/^sha256:[a-f0-9]{64}(?![\s\S])/;
+const integer=n=>Number.isSafeInteger(n)&&n>=0;
+function equalSet(a,b) {
+  return Array.isArray(a)&&Array.isArray(b)&&new Set(a).size===a.length&&
+    new Set(b).size===b.length&&a.length===b.length&&a.every(x=>b.includes(x));
+}
+// Recognizes the currently produced journal-cleanup receipt only. Future receipt
+// schemas remain protected until their own provenance rules are implemented.
+export function completedCleanupReceipt(r,workspace,id) {
+  requestShape(r,['schemaVersion','kind','runId','workspace','previewDigest','policy','status','recoverable',
+    'groups','removedFiles','removedDirectories','completedGroups','currentFile','error','reclaimedBytes'],
+    ['authorization','receiptUpdate'],'retention-receipts.shape');
+  if(![1,2].includes(r.schemaVersion)||r.kind!=='retention-result'||r.runId!==id||!uuid.test(id)||r.workspace!==workspace||
+      !hash.test(r.previewDigest)||r.recoverable!==false||!['completed','failed','in-progress'].includes(r.status))fail('retention-receipts.binding');
+  const combined=r.schemaVersion===2;
+  if(combined)planCombinedRetention({journals:[],receipts:[],policy:r.policy,now:0});
+  else planRetention({journals:[],policy:r.policy,now:0});
+  if(r.authorization!==undefined) {
+    const automatic=r.authorization?.decision==='workspace-policy';
+    requestShape(r.authorization,automatic?['decision','policyHash']:['decision','previewDigest'],[],'retention-receipts.authorization');
+    if(automatic?!hash.test(r.authorization.policyHash):r.authorization.decision!=='approve'||r.authorization.previewDigest!==r.previewDigest)
+      fail('retention-receipts.authorization');
+  }
+  // Incomplete known records are retained; no claim of successful deletion.
+  if(r.status!=='completed')return false;
+  if(r.error!==null||r.currentFile!==null||(r.receiptUpdate!==undefined&&r.receiptUpdate!=='saved')||
+      !integer(r.reclaimedBytes)||!Array.isArray(r.groups))fail('retention-receipts.completion');
+  if(r.groups.length>r.policy.maxDeletesPerRun)fail('retention-receipts.completion');
+  const ids=[],files=[],directories=[];let bytes=0;
+  for(const group of r.groups) {
+    requestShape(group,combined?['id','type','paths','files']:['id','paths','files'],[],'retention-receipts.group');
+    const receiptGroup=combined&&group.type==='cleanup-receipt';
+    if(combined&&!['journal','cleanup-receipt'].includes(group.type))fail('retention-receipts.group');
+    if(!uuid.test(group.id)||!equalSet(group.paths,receiptGroup?[]:['.pipeline/journals/'+group.id,'.pipeline/transactions/'+group.id])||!Array.isArray(group.files))
+      fail('retention-receipts.group');
+    if(receiptGroup&&(group.id===r.runId||group.files.length!==1))fail('retention-receipts.group');
+    ids.push(combined?group.type+':'+group.id:group.id);directories.push(...group.paths);let recovery=0,events=0;
+    for(const file of group.files) {
+      requestShape(file,['path','hash','bytes','mtimeMs'],[],'retention-receipts.file');
+      if(typeof file.path!=='string'||!hash.test(file.hash)||!integer(file.bytes)||!Number.isFinite(file.mtimeMs)||file.mtimeMs<0)
+        fail('retention-receipts.file');
+      if(receiptGroup) {
+        if(file.path!=='.pipeline/cleanup/'+group.id+'.json')fail('retention-receipts.file');
+      }else if(file.path==='.pipeline/transactions/'+group.id+'/recovery.json')recovery++;
+      else if(file.path.startsWith('.pipeline/journals/'+group.id+'/')&&/^\d{6}\.json(?![\s\S])/.test(file.path.slice(('.pipeline/journals/'+group.id+'/').length)))events++;
+      else fail('retention-receipts.file');
+      files.push(file.path);bytes+=file.bytes;if(!integer(bytes))fail('retention-receipts.bytes');
+    }
+    if(!receiptGroup&&(recovery!==1||events<1))fail('retention-receipts.group');
+  }
+  if(!equalSet(ids,r.completedGroups)||!equalSet(files,r.removedFiles)||!equalSet(directories,r.removedDirectories)||bytes!==r.reclaimedBytes)
+    fail('retention-receipts.completion');
+  return true;
+}
+
+function references(value,out) {
+  if(typeof value==='string') {
+    for(const m of value.replaceAll('\\','/').matchAll(/\.pipeline\/cleanup\/([a-f0-9-]{36})\.json/g))if(uuid.test(m[1]))out.add(m[1]);
+  }else if(value&&typeof value==='object')for(const part of Object.values(value))references(part,out);
+}
+
+export async function scanCleanupReceipts(workspace,{currentRuns=[]}={}) {
+  workspace=absoluteRoot(workspace);
+  if(!Array.isArray(currentRuns)||currentRuns.some(id=>typeof id!=='string'||!uuid.test(id)))fail('retention-receipts.current-run');
+  const directory=resolveChild(workspace,'.pipeline/cleanup'),records=[],diagnostics=[],bindings=[],referenced=new Set();
+  const history=await inspectHistory(workspace);let complete=history.complete&&history.diagnostics.length===0,total=0,stateHash=null;
+  try {
+    const state=await readState(resolveChild(workspace,'.pipeline/state.json'));
+    stateHash=state.digest;
+    bindings.push({path:'.pipeline/state.json',hash:state.digest});references(state.value,referenced);
+  }catch(e){if(e.code!=='record.missing'){complete=false;diagnostics.push({code:e.code??'retention-receipts.io',subject:'state'});}}
+  if(stateHash===null&&history.entries.length)complete=false;
+  for(const entry of history.entries)if(entry.recovery) {
+    try{const r=await readRecord(resolveChild(workspace,entry.recovery));bindings.push({path:entry.recovery,hash:r.digest});references(r.value,referenced);}
+    catch(e){complete=false;diagnostics.push({code:e.code??'retention-receipts.io',subject:entry.id});}
+  }
+  const names=(await inspectDirectory(directory)).exists?(await readdir(directory)).sort():[];
+  if(names.length>1000)fail('retention-receipts.limit');
+  for(const name of names) {
+    if(!name.endsWith('.json')||!uuid.test(name.slice(0,-5))){complete=false;diagnostics.push({code:'retention-receipts.foreign',subject:'.pipeline/cleanup'});continue;}
+    const id=name.slice(0,-5),relative='.pipeline/cleanup/'+name,filename=resolveChild(workspace,relative);
+    const item={id,path:relative,status:'unknown',completedAt:null,bytes:0,hash:null,mtimeMs:null,protectionReasons:[]};
+    try {
+      const before=await lstat(filename);total+=before.size;if(total>64*1024*1024)fail('retention-receipts.limit');
+      if(!before.isFile()||before.isSymbolicLink()||before.nlink!==1)fail('retention-receipts.type');
+      const r=await readRecord(filename),after=await lstat(filename);
+      if(before.ino!==after.ino||before.dev!==after.dev||before.size!==after.size||before.mtimeMs!==after.mtimeMs)fail('retention-receipts.drift');
+      item.bytes=before.size;item.hash=r.digest;item.mtimeMs=before.mtimeMs;
+      item.status=completedCleanupReceipt(r.value,workspace,id)?'completed':'uncertain';
+      if(item.status==='completed')item.completedAt=Math.floor(before.mtimeMs);
+    }catch(e){complete=false;diagnostics.push({code:e.code??'retention-receipts.io',subject:id});item.protectionReasons.push('inspection-failed');}
+    if(currentRuns.includes(id))item.protectionReasons.push('current-run');
+    if(referenced.has(id))item.protectionReasons.push('retained-reference');
+    records.push(item);
+  }
+  // Repeat identities: this is a preview, not a lock or deletion permission.
+  for(const binding of [...bindings,...records.filter(r=>r.hash!==null)]) {
+    if((await readRecord(resolveChild(workspace,binding.path))).digest!==binding.hash)fail('retention-receipts.drift');
+    if(binding.mtimeMs!==undefined) {
+      const info=await lstat(resolveChild(workspace,binding.path));
+      if(!info.isFile()||info.isSymbolicLink()||info.nlink!==1||info.size!==binding.bytes||info.mtimeMs!==binding.mtimeMs)fail('retention-receipts.drift');
+    }
+  }
+  let stateAfter=null;
+  try{stateAfter=(await readState(resolveChild(workspace,'.pipeline/state.json'))).digest;}
+  catch(e){if(e.code!=='record.missing'&&(stateHash!==null||complete))fail('retention-receipts.drift');}
+  if(stateAfter!==stateHash)fail('retention-receipts.drift');
+  if(contractDigest(await inspectHistory(workspace))!==contractDigest(history))fail('retention-receipts.drift');
+  const afterNames=(await inspectDirectory(directory)).exists?(await readdir(directory)).sort():[];
+  if(!equalSet(names,afterNames))fail('retention-receipts.drift');
+  if(!complete)for(const r of records)if(!r.protectionReasons.includes('inspection-failed'))r.protectionReasons.push('inspection-failed');
+  const body={kind:'cleanup-receipts-inventory',workspace,records,bindings,diagnostics,complete,
+    requiresLockedRecheck:true,automaticActions:false};
+  return {...body,digest:contractDigest(body)};
+}

package/src/operations/retention-scan.js

@@ -0,0 +1,86 @@
+import {readdir,lstat} from 'node:fs/promises';
+import {inspectHistory} from './history.js';
+import {readState,readRecord} from './state.js';
+import {planRetention} from './retention.js';
+import {absoluteRoot,resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail} from '../contracts/parse.js';
+
+const ref=/^\.pipeline\/(?:transactions|journals)\/([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})(?:\/|$)/;
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?![\s\S])/;
+function references(value,out=new Set()) {
+  if(typeof value==='string') {const m=ref.exec(value);if(m)out.add(m[1]);}
+  else if(value && typeof value==='object')for(const item of Object.values(value))references(item,out);
+  return out;
+}
+
+// Conservative read-only scan. Completed is not synonymous with disposable.
+// Referenced records remain protected even if the referring record is eligible.
+export async function scanRetention(workspace,{policy,now,currentRuns=[]}) {
+  workspace=absoluteRoot(workspace);
+  if(!Array.isArray(currentRuns) || currentRuns.some(id=>typeof id!=='string' || !uuid.test(id)))fail('retention-scan.current-run');
+  planRetention({journals:[],policy,now}); // validate policy before filesystem work
+  const history=await inspectHistory(workspace),groups=[],referenced=new Set(),current=new Set(currentRuns),diagnostics=[...history.diagnostics];
+  let state=null,unsafe=!history.complete || history.diagnostics.some(d=>d.code!=='history.unfinished'),count=0,total=0;
+  try {state=await readState(resolveChild(workspace,'.pipeline/state.json'));for(const id of references(state.value))current.add(id);}
+  catch(error){if(error.code!=='record.missing'){unsafe=true;diagnostics.push({code:error.code??'retention-scan.io',subject:'state'});}}
+  if((history.entries.length && !state) || (state?.value.active && !state.value.activation) ||
+      (state?.value.pending && !history.entries.some(e=>e.pendingDigest===state.value.pending)))unsafe=true;
+  const inspectGroup=async item=>{
+    const files=[];
+    for(const directory of [item.journal,item.recovery?.slice(0,-'/recovery.json'.length)].filter(Boolean)) {
+      await inspectDirectory(resolveChild(workspace,directory));
+      const names=(await readdir(resolveChild(workspace,directory))).sort();
+      if(names.length>10000 || count+names.length>10000)fail('retention-scan.limit');
+      for(const name of names) {
+        if(directory===item.journal?!/^\d{6}\.json(?![\s\S])/.test(name):name!=='recovery.json')fail('retention-scan.foreign');
+        const relative=directory+'/'+name,filename=resolveChild(workspace,relative),info=await lstat(filename);
+        if(!info.isFile() || info.isSymbolicLink() || info.nlink!==1)fail('retention-scan.type');
+        count++;total+=info.size;if(total>64*1024*1024)fail('retention-scan.limit');
+        const record=await readRecord(filename),after=await lstat(filename);
+        if(info.size!==after.size || info.mtimeMs!==after.mtimeMs || info.ino!==after.ino || info.dev!==after.dev)fail('retention-scan.drift');
+        files.push({path:relative,hash:record.digest,bytes:info.size,mtimeMs:info.mtimeMs});
+        if(name==='recovery.json')for(const id of references(record.value))if(id!==item.id)referenced.add(id);
+      }
+    }
+    return files;
+  };
+  for(const item of history.entries) {
+    const group={id:item.id,status:item.status,journalPath:item.journal?resolveChild(workspace,item.journal):null,
+      recoveryPath:item.recovery?resolveChild(workspace,item.recovery):null,
+      paths:[item.journal,item.recovery?.slice(0,-'/recovery.json'.length)].filter(Boolean),files:[],protectionReasons:[]};
+    try{group.files=await inspectGroup(item);}catch(error){unsafe=true;group.protectionReasons.push('inspection-failed');diagnostics.push({code:error.code??'retention-scan.io',subject:item.id});}
+    if(['unknown','orphan'].includes(item.status))unsafe=true;
+    if(state?.value.pending && item.pendingDigest===state.value.pending)current.add(item.id);
+    groups.push(group);
+  }
+  for(const group of groups) {
+    if(currentRuns.includes(group.id))group.protectionReasons.push('current-run');
+    if(current.has(group.id))group.protectionReasons.push('current-state');
+    if(referenced.has(group.id))group.protectionReasons.push('retained-reference');
+    if(unsafe)group.protectionReasons.push('inspection-failed');
+    group.protectionReasons=[...new Set(group.protectionReasons)].sort();
+    group.bytes=group.files.reduce((n,f)=>n+f.bytes,0);
+    // Local metadata age only; never used to select the active transaction.
+    group.completedAt=group.status==='journal-completed' && group.files.length?Math.floor(Math.max(...group.files.map(f=>f.mtimeMs))):null;
+  }
+  const after=await inspectHistory(workspace);
+  if(contractDigest(after)!==contractDigest(history))fail('retention-scan.drift');
+  for(const group of groups)for(const file of group.files) {
+    const filename=resolveChild(workspace,file.path),info=await lstat(filename);
+    if(info.size!==file.bytes || info.mtimeMs!==file.mtimeMs || (await readRecord(filename)).digest!==file.hash)fail('retention-scan.drift');
+  }
+  for(const group of groups)if(!group.protectionReasons.includes('inspection-failed'))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(workspace,directory))).sort())!==JSON.stringify(expected))fail('retention-scan.drift');
+  }
+  let stateAfter=null;
+  try{stateAfter=(await readState(resolveChild(workspace,'.pipeline/state.json'))).digest;}catch(error){if(error.code!=='record.missing')fail('retention-scan.drift');}
+  if(stateAfter!==(state?.digest??null))fail('retention-scan.drift');
+  const retention=planRetention({now,policy,journals:groups.map(g=>({id:g.id,
+    status:g.status==='journal-completed'?'completed':['uncertain','orphan'].includes(g.status)?g.status:g.status==='open'?'pending':'unknown',
+    completedAt:g.completedAt,bytes:g.bytes,protectionReasons:g.protectionReasons}))});
+  const body={kind:'retention-filesystem-preview',workspace,stateFileHash:stateAfter,currentRuns:[...currentRuns],groups,retention,
+    diagnostics,complete:history.complete && !unsafe,applySupported:false,automaticActions:false};
+  return {...body,digest:contractDigest(body)};
+}

package/src/operations/retention.js

@@ -0,0 +1,56 @@
+import { fail } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { requestShape } from './ownership.js';
+
+const dayMs = 86400000;
+const statuses = new Set(['completed','active','pending','uncertain','unknown','orphan']);
+const protections = new Set(['current-run','current-state','retained-reference','dependency','inspection-failed']);
+const integer = n => Number.isSafeInteger(n) && n >= 0;
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+
+// Pure selection over trusted, complete scanner observations. This function does
+// not inspect files, prove completion/references, grant deletion or acquire locks.
+// The later scanner/executor must independently establish those facts and recheck
+// them. No defaults: all user-policy limits and the clock are explicit inputs.
+export function planRetention(input) {
+  requestShape(input,['journals','policy','now'],[],'retention.input');
+  const {journals,policy,now}=input;
+  requestShape(policy,['maxAgeDays','maxJournals','maxDeletesPerRun'],[],'retention.policy');
+  if(!integer(now) || now>8640000000000000 || !Object.values(policy).every(integer) ||
+      policy.maxAgeDays>Math.floor(Number.MAX_SAFE_INTEGER/dayMs))fail('retention.policy');
+  if(!Array.isArray(journals))fail('retention.input');
+  const ids=new Set();let totalBytes=0;
+  const observed=journals.map(journal=>{
+    requestShape(journal,['id','status','completedAt','bytes','protectionReasons'],[],'retention.journal');
+    const {id,status,completedAt,bytes,protectionReasons}=journal;
+    if(typeof id!=='string' || !uuid.test(id) || ids.has(id) || !statuses.has(status) ||
+       !integer(bytes) || !Array.isArray(protectionReasons) ||
+       protectionReasons.some(r=>!protections.has(r)) || new Set(protectionReasons).size!==protectionReasons.length ||
+       (completedAt!==null && (!integer(completedAt) || completedAt>8640000000000000)) ||
+       (status==='completed' && completedAt===null))fail('retention.journal');
+    ids.add(id);totalBytes+=bytes;if(!integer(totalBytes))fail('retention.bytes');
+    const reasons=[...protectionReasons];
+    if(status!=='completed')reasons.push('status:'+status);
+    if(completedAt!==null && completedAt>now)reasons.push('future-timestamp');
+    return {id,status,completedAt,bytes,protectionReasons:reasons.sort()};
+  }).sort((a,b)=>a.id<b.id?-1:a.id>b.id?1:0);
+  const protectedJournals=observed.filter(j=>j.protectionReasons.length);
+  const eligible=observed.filter(j=>!j.protectionReasons.length)
+    .sort((a,b)=>a.completedAt-b.completedAt || (a.id<b.id?-1:a.id>b.id?1:0));
+  const excess=Math.max(0,observed.length-policy.maxJournals);
+  const candidates=eligible.map((j,index)=>({...j,reasons:[
+    ...(now-j.completedAt>policy.maxAgeDays*dayMs?['age']:[]),...(index<excess?['count']:[])
+  ]})).filter(j=>j.reasons.length);
+  const selected=candidates.slice(0,policy.maxDeletesPerRun),deferred=candidates.slice(policy.maxDeletesPerRun);
+  const selectedIds=new Set(selected.map(j=>j.id));
+  const remaining=observed.filter(j=>!selectedIds.has(j.id));
+  const aged=j=>j.completedAt!==null && now-j.completedAt>policy.maxAgeDays*dayMs;
+  const body={kind:'retention-preview',now,policy:{...policy},observed,
+    selected,deferred,protected:protectedJournals,
+    totals:{observedCount:observed.length,observedBytes:totalBytes,
+      selectedCount:selected.length,selectedBytes:selected.reduce((sum,j)=>sum+j.bytes,0),
+      remainingCount:remaining.length,remainingOverCount:Math.max(0,remaining.length-policy.maxJournals),
+      remainingOverAge:remaining.filter(aged).length},
+    requiresFilesystemValidation:true,automaticActions:false};
+  return {...body,digest:contractDigest(body)};
+}

package/src/operations/state.js

@@ -0,0 +1,210 @@
+import path from 'node:path';
+import { open, lstat, realpath, opendir } from 'node:fs/promises';
+import { parse, fail, ContractError, MAX_INPUT_BYTES } from '../contracts/parse.js';
+import { validateStructure } from '../contracts/validate.js';
+import { validateState, contractDigest } from '../contracts/semantic.js';
+import { validateSource } from '../source/git.js';
+import { sha256, utf8, verifyPackage, LIMITS, cap } from '../source/inventory.js';
+import { absoluteRoot, inspectDirectory, resolveChild } from '../workspace/paths.js';
+import {installedSelection,resolveProviders} from '../providers/bundles.js';
+
+// Verify the installed bytes, not merely the source identity in state. This is
+// an observation for preview; apply must recheck it under the S5 transaction.
+// No original manifest/source lookup or Git/network activity is required.
+export async function verifyInstalledSnapshot(previous) {
+  validateState(previous);
+  if (!previous.active || previous.pending !== null) fail('snapshot.state');
+  const snapshot = previous.active.snapshot;
+  const root = resolveChild(absoluteRoot(previous.workspace), snapshot.path);
+  const verified = await verifySnapshotDirectory(root, {...snapshot,pipelineId:previous.active.pipelineId,version:previous.active.version});
+  const selection=resolveProviders(verified.manifest,installedSelection(previous.active));
+  if(contractDigest(selection.providers)!==contractDigest([...previous.active.providers].sort()) ||
+      contractDigest(selection.bundles??null)!==contractDigest(previous.active.bundles??null)) fail('bundle.snapshot-binding');
+  return {...verified,snapshot:structuredClone(snapshot)};
+}
+export async function verifyPreparedSnapshot(acquired) {
+  return verifySnapshotDirectory(absoluteRoot(acquired.snapshotPath), {...acquired,pipelineId:acquired.manifest.id,version:acquired.manifest.version});
+}
+async function verifySnapshotDirectory(root, expected) {
+  const entries = [], files = new Map(), directories = new Set();
+  let nodes = 0, total = 0;
+  try {
+    if (!(await inspectDirectory(root)).exists) fail('snapshot.missing');
+    async function walk(directory, prefix = '') {
+      for await (const item of await opendir(directory)) {
+        // Count directories too: an empty-directory flood is still bounded.
+        cap(++nodes, LIMITS.files * 2, 'snapshot.nodes');
+        const relative = prefix + item.name, filename = resolveChild(root, relative);
+        const info = await lstat(filename);
+        if (info.isSymbolicLink()) fail('snapshot.link');
+        if (info.isDirectory()) {
+          directories.add(relative);
+          await inspectDirectory(filename);
+          await walk(filename, relative + '/');
+          continue;
+        }
+        if (!info.isFile() || info.nlink !== 1) fail('snapshot.type');
+        cap(entries.length + 1, LIMITS.files, 'source.files');
+        cap(info.size, LIMITS.blob, 'source.blob');
+        cap(total + info.size, LIMITS.total, 'source.total');
+        const handle = await open(filename, 'r');
+        let bytes;
+        try {
+          const opened = await handle.stat();
+          if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.nlink !== 1) fail('snapshot.drift');
+          // One extra byte detects growth without unbounded readFile allocation.
+          const buffer = Buffer.alloc(info.size + 1);
+          let length = 0;
+          while (length < buffer.length) {
+            const read = await handle.read(buffer, length, buffer.length - length, null);
+            if (read.bytesRead === 0) break;
+            length += read.bytesRead;
+          }
+          if (length !== info.size) fail('snapshot.drift');
+          bytes = buffer.subarray(0, length);
+        } finally { await handle.close(); }
+        total += bytes.length;
+        entries.push({ path: relative, size: bytes.length, mode: '100644', type: 'blob' });
+        files.set(relative, bytes);
+      }
+    }
+    await walk(root);
+    entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const verified = await verifyPackage(entries, async entry => files.get(entry.path));
+    const expectedDirectories = new Set();
+    for (const name of verified.files.keys()) {
+      const parts = name.split('/');
+      for (let i = 1; i < parts.length; i++) expectedDirectories.add(parts.slice(0, i).join('/'));
+    }
+    if (directories.size !== expectedDirectories.size || [...directories].some(name => !expectedDirectories.has(name))) fail('snapshot.extra-directory');
+    if (verified.digest !== expected.digest || verified.inventoryDigest !== expected.inventoryDigest ||
+        verified.manifest.id !== expected.pipelineId || verified.manifest.version !== expected.version) fail('snapshot.binding');
+    return { ...verified, root, runtime: 'not-run' };
+  } catch (error) {
+    throw error instanceof ContractError ? error : new ContractError('snapshot.io');
+  }
+}
+
+// Read-only bounded observation. Not an S5 lock or protection against concurrent
+// replacement. No native Git, network or configuration writes here.
+export async function readRecord(filename, format = 'json') {
+  filename = absoluteRoot(filename);
+  let handle;
+  try {
+    await inspectDirectory(path.dirname(filename));
+    const entry = await lstat(filename);
+    if (entry.isSymbolicLink() || !entry.isFile()) fail('record.type');
+    handle = await open(filename, 'r');
+    const buffer = Buffer.alloc(MAX_INPUT_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+      if (bytesRead === 0) break;
+      length += bytesRead;
+    }
+    if (length > MAX_INPUT_BYTES) fail('parse.size');
+    const bytes = buffer.subarray(0, length);
+    return { path: await realpath(filename), digest: sha256(bytes), value: parse(utf8(bytes), format) };
+  } catch (e) {
+    if (e instanceof ContractError) throw e;
+    fail(e.code === 'ENOENT' ? 'record.missing' : 'record.io');
+  } finally { if (handle) await handle.close(); }
+}
+export async function readState(filename) {
+  const record = await readRecord(filename);
+  validateState(record.value);
+  return { ...record, stateDigest: contractDigest(record.value) };
+}
+function previousGuard(previous, wrapper) {
+  if (!previous) return;
+  validateState(previous);
+  if (previous.pending !== null) fail('state.pending');
+  if (absoluteRoot(previous.workspace) !== wrapper) fail('source-rebind-required');
+}
+async function manifestRecord(filename, hasOriginal = false) {
+  const extension = path.extname(filename).toLowerCase();
+  if (!['.json', '.yaml', '.yml'].includes(extension)) fail('manifest.format');
+  const record = await readRecord(filename, extension === '.json' ? 'json' : 'yaml');
+  validateStructure('workspace', record.value); validateSource(record.value.pipeline);
+  const base = path.dirname(record.path), source = record.value.pipeline;
+  let resolvedSource = source.url;
+  if (source.transport === 'local') {
+    try { resolvedSource = await realpath(path.resolve(base, source.path)); }
+    catch (error) { fail(hasOriginal ? 'source-rebind-required' : error.code === 'ENOENT' ? 'source.missing-repository' : 'source.repository-unavailable'); }
+  }
+  return { manifest: record.value, origin: { path: record.path, base, digest: record.digest, resolvedSource } };
+}
+export async function resolveOrigin({ wrapper, previous = null, manifestPath, command = 'setup' }) {
+  wrapper = absoluteRoot(wrapper);
+  previousGuard(previous, wrapper);
+  if (!['setup', 'update', 'repair'].includes(command)) fail('origin.command');
+  const active = previous?.active;
+  if (command === 'repair') {
+    if (!active || manifestPath !== undefined) fail('origin.repair');
+    // Repair gets identity from installed state. Snapshot bytes still need a
+    // separate integrity check before planning/apply; this performs no source I/O.
+    return { mode: 'installed', snapshot: structuredClone(active.snapshot) };
+  }
+  const original = active?.snapshot.origin;
+  const filename = absoluteRoot(manifestPath ?? original?.path ?? path.join(wrapper, 'workspace.yaml'));
+  if (original && filename !== absoluteRoot(original.path)) fail('source-rebind-required');
+  let current;
+  try { current = await manifestRecord(filename, Boolean(original)); }
+  catch (e) { if (original && e.code === 'record.missing') fail('source-rebind-required'); throw e; }
+  if (original && (current.origin.path !== original.path || current.origin.base !== original.base ||
+      current.origin.resolvedSource !== original.resolvedSource)) fail('source-rebind-required');
+  return { mode: 'source', ...current };
+}
+// Explicit preview only. This never grants permission to acquire the proposed
+// source, changes state or bypasses resolveOrigin. Approval binding is S4 plan work.
+export async function previewRebind({ wrapper, previous, manifestPath }) {
+  validateState(previous);
+  if (!previous.active || previous.pending !== null || manifestPath === undefined) fail('origin.rebind');
+  const proposed = await manifestRecord(absoluteRoot(manifestPath));
+  return { kind: 'rebind-preview', beforeStateHash: contractDigest(previous),
+    previousWorkspace: previous.workspace, workspace: absoluteRoot(wrapper),
+    previousOrigin: structuredClone(previous.active.snapshot.origin), proposed,
+    requiresApproval: true, sourceAccessAuthorized: false };
+}
+
+// The CLI must obtain this decision from the user, not from package contents.
+// It authorizes source access only, never filesystem apply. Recompute the proposal
+// before access so edited manifests, relocated source or changed state invalidate it.
+export async function resolveApprovedRebind({wrapper,previous,manifestPath,proposal,approval}) {
+  if (!approval || approval.decision!=='approve' || Object.keys(approval).sort().join(',')!=='decision,proposalDigest' ||
+      approval.proposalDigest!==contractDigest(proposal)) fail('rebind.approval');
+  const fresh=await previewRebind({wrapper,previous,manifestPath});
+  if (contractDigest(fresh)!==approval.proposalDigest) fail('rebind.drift');
+  // Workspace relocation is S6; S1 plans cannot silently change previous.workspace.
+  if (fresh.workspace!==previous.workspace) fail('rebind.workspace-move');
+  return {mode:'source',...fresh.proposed,rebind:{proposal:fresh,approval:structuredClone(approval)}};
+}
+
+export async function observeTargets(wrapper, names) {
+  const result=[];let total=0;
+  cap(names.length,LIMITS.files,'preview.count');
+  for(const name of [...new Set(names)].sort()) {
+    const filename=resolveChild(absoluteRoot(wrapper),name);
+    let handle;
+    try {
+      const parent=await inspectDirectory(path.dirname(filename));
+      if (!parent.exists) {result.push({path:name,bytes:null});continue;}
+      // Probe the final filename spelling without treating it as a directory.
+      const directory=await opendir(path.dirname(filename));
+      for await(const entry of directory) if(entry.name.toLowerCase()===path.basename(filename).toLowerCase() && entry.name!==path.basename(filename)) fail('layout.case-alias');
+      let info;
+      try {info=await lstat(filename);} catch(error) {if(error.code==='ENOENT'){result.push({path:name,bytes:null});continue;}throw error;}
+      if(!info.isFile() || info.isSymbolicLink() || info.nlink!==1) fail('target.type');
+      cap(info.size,LIMITS.blob,'preview.size');cap(total+info.size,LIMITS.total,'preview.total');
+      handle=await open(filename,'r');
+      const opened=await handle.stat();
+      if(!opened.isFile() || opened.ino!==info.ino || opened.dev!==info.dev || opened.nlink!==1) fail('target.drift');
+      const buffer=Buffer.alloc(info.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;}
+      if(length!==info.size)fail('target.drift');
+      total+=length;result.push({path:name,bytes:buffer.subarray(0,length)});
+    } catch(error) {throw error instanceof ContractError ? error : new ContractError('target.io');}
+    finally {if(handle)await handle.close();}
+  }
+  return result;
+}

package/src/operations/switch-activate.js

@@ -0,0 +1,64 @@
+import {readSwitchRecovery} from './switch-recovery-store.js';
+import {inspectPendingSwitch} from './switch-inspect.js';
+import {validateSwitchRecord} from './switch-records.js';
+import {assertLockHeld} from './lock.js';
+import {readState,observeTargets} from './state.js';
+import {writeCheckedFile} from './apply.js';
+import {resolveChild,absoluteRoot} from '../workspace/paths.js';
+import {contractDigest,validateState} from '../contracts/semantic.js';
+import {parse,fail} from '../contracts/parse.js';
+import {sha256} from '../source/inventory.js';
+
+function readyState(evidence,recoveryPath) {
+  if(evidence.journal.status!=='completed' || evidence.journal.verifiedPhases!==2)fail('switch-activation.incomplete');
+  const state={...evidence.record.previous,status:'ready',pending:null,runtime:'not-run',
+    active:evidence.record.prepared.preview.phases[1].preview.plan.desired,
+    activation:{recovery:recoveryPath,recoveryHash:evidence.fileHash,
+      journalHead:{sequence:evidence.journal.sequence,hash:evidence.journal.lastFileHash}}};
+  validateState(state);return state;
+}
+
+// Read-only confirmation of this exact completed activation. No repair/retry.
+export async function inspectActivatedSwitch(workspace,recoveryPath) {
+  workspace=absoluteRoot(workspace);
+  const before=await readState(resolveChild(workspace,'.pipeline/state.json'));
+  const evidence=await readSwitchRecovery(workspace,recoveryPath),expected=readyState(evidence,recoveryPath);
+  if(contractDigest(before.value)!==contractDigest(expected))fail('switch-activation.binding');
+  const results=evidence.record.prepared.preview.results;
+  const observations=await observeTargets(workspace,results.map(o=>o.path));
+  if(observations.some(o=>(o.bytes===null?null:sha256(o.bytes))!==results.find(r=>r.path===o.path).hash))fail('switch-activation.target-drift');
+  const after=await readSwitchRecovery(workspace,recoveryPath);
+  const repeated=await observeTargets(workspace,results.map(o=>o.path));
+  if(after.fileHash!==evidence.fileHash || contractDigest(after.journal)!==contractDigest(evidence.journal) ||
+      repeated.some(o=>(o.bytes===null?null:sha256(o.bytes))!==results.find(r=>r.path===o.path).hash) ||
+      (await readState(resolveChild(workspace,'.pipeline/state.json'))).digest!==before.digest)fail('switch-activation.drift');
+  return {status:'applied',recoveryPath,recoveryHash:evidence.fileHash,stateFileHash:before.digest,runtime:'not-run'};
+}
+
+// Internal final transition. Both checked phases and unchanged final bytes are
+// mandatory. State activation is configuration evidence, never runtime readiness.
+export async function activateSwitch(lock,recoveryPath,recoveryHash,approval,{boundary=async()=>{}}={}) {
+  approval=structuredClone(approval);
+  async function check() {
+    await assertLockHeld(lock);
+    const evidence=await readSwitchRecovery(lock.workspace,recoveryPath);
+    if(evidence.fileHash!==recoveryHash)fail('switch-activation.recovery');
+    validateSwitchRecord(evidence.record.prepared,approval,evidence.record.previous);
+    const ready=readyState(evidence,recoveryPath),inspection=await inspectPendingSwitch(lock.workspace,recoveryPath);
+    if(inspection.conflicts.length || inspection.uncertain!==null)fail('switch-activation.target-drift');
+    const pending={...evidence.record.previous,status:'needs-reconciliation',pending:evidence.record.digest,runtime:'not-run'};
+    const state=await readState(resolveChild(lock.workspace,'.pipeline/state.json'));
+    if(contractDigest(state.value)!==contractDigest(pending))fail('switch-activation.binding');
+    return {ready,stateHash:state.digest};
+  }
+  const checked=await check(),bytes=Buffer.from(JSON.stringify(parse(JSON.stringify(checked.ready),'json'))+'\n');
+  await writeCheckedFile(lock,'.pipeline/state.json',checked.stateHash,bytes,undefined,async(phase,detail)=>{
+    await boundary(phase,detail);
+    if(phase==='before-rename') {
+      const fresh=await check();
+      if(fresh.stateHash!==checked.stateHash || contractDigest(fresh.ready)!==contractDigest(checked.ready))fail('switch-activation.drift');
+    }
+  });
+  const result=await inspectActivatedSwitch(lock.workspace,recoveryPath);
+  await assertLockHeld(lock);return result;
+}