@6reduk/workspace-pipeline 0.1.0

package/src/operations/switch-backups.js

@@ -0,0 +1,29 @@
+import {checkPreview} from './plan.js';
+import {readConfigField} from './config-fields.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail} from '../contracts/parse.js';
+import {sha256} from '../source/inventory.js';
+
+// Derive incoming backups from the approved post-removal observations, never
+// from still-installed old provider bytes. Pure; not an authorization to write.
+export function incomingSwitchBackups(preview) {
+  const observations=preview.observations.map(o=>({path:o.path,bytes:o.bytes===null?null:Buffer.from(o.bytes,'base64')}));
+  const checked=checkPreview(preview,null,observations);
+  if(checked.plan.command!=='setup' || !checked.plan.desired)fail('switch-backup.phase');
+  const observed=new Map(observations.map(o=>[o.path,o.bytes])),backups=new Map();
+  for(const owned of checked.plan.desired.owned) {
+    if(owned.backup===null)continue;
+    const bytes=observed.get(owned.path);
+    if(!Buffer.isBuffer(bytes))fail('switch-backup.missing');
+    const hash=sha256(bytes);
+    if(owned.kind==='file') {
+      if(hash!==owned.beforeHash)fail('switch-backup.before');
+    }else {
+      const field=readConfigField(owned.path,bytes,owned.pointer);
+      if(!field.present || contractDigest(field.value)!==owned.beforeHash)fail('switch-backup.before');
+    }
+    if(backups.has(owned.backup) && backups.get(owned.backup).hash!==hash)fail('switch-backup.conflict');
+    backups.set(owned.backup,{path:owned.backup,hash,bytes:Buffer.from(bytes)});
+  }
+  return [...backups.values()].sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);
+}

package/src/operations/switch-continuation-journal.js

@@ -0,0 +1,94 @@
+import {contractDigest,portablePath} from '../contracts/semantic.js';
+import {parse,fail} from '../contracts/parse.js';
+import {requestShape} from './ownership.js';
+
+const hash=v=>typeof v==='string' && /^sha256:[a-f0-9]{64}(?![\s\S])/.test(v);
+const nullableHash=v=>v===null || hash(v);
+const detach=v=>parse(JSON.stringify(v),'json');
+
+// Pure interpretation of an already verified continuation preview. This does
+// not establish source provenance, approval, locking or actual disk readback.
+// The future durable executor must verifySwitchContinuationApproval first.
+export function createSwitchContinuationCursor(preview) {
+  const p=detach(preview),{digest,...body}=p;
+  if(p.kind!=='switch-continuation-preview' || !hash(digest) || contractDigest(body)!==digest ||
+      p.applySupported!==false || p.requiresFreshApproval!==true || p.runtime!=='not-run' ||
+      !Array.isArray(p.observations) || !Array.isArray(p.remaining) || (p.uncertain!==null && !p.remaining.length) || p.remaining.length>2)
+    fail('switch-continuation-journal.preview');
+  const projected=new Map();
+  for(const o of p.observations) {
+    requestShape(o,['path','hash'],[],'switch-continuation-journal.observation');portablePath(o.path);
+    if(projected.has(o.path) || !nullableHash(o.hash))fail('switch-continuation-journal.observation');
+    projected.set(o.path,o.hash);
+  }
+  let count=0;
+  for(let i=0;i<p.remaining.length;i++) {
+    const phase=p.remaining[i],seen=new Set();
+    requestShape(phase,['phase','operations','phaseCheckRequired'],[],'switch-continuation-journal.phase');
+    if(phase.phase!==(p.remaining.length===2 && i===0?'remove-old':'install-new') ||
+        phase.phaseCheckRequired!==true || !Array.isArray(phase.operations))fail('switch-continuation-journal.phase');
+    for(let j=0;j<phase.operations.length;j++) {
+      const t=phase.operations[j];
+      requestShape(t,['operationId','path','resolution','beforeHash','desiredHash'],[],'switch-continuation-journal.target');
+      if(typeof t.operationId!=='string' || !t.operationId || seen.has(t.operationId) ||
+          !projected.has(t.path) || !nullableHash(t.beforeHash) || !nullableHash(t.desiredHash) ||
+          !(i===0 && j===0?(p.uncertain===null?['verify-desired','apply-approved-target']:['verify-desired','retry-approved-target']):['apply-approved-target']).includes(t.resolution))
+        fail('switch-continuation-journal.target');
+      seen.add(t.operationId);count++;
+    }
+  }
+  const first=p.remaining[0]?.operations[0];
+  if((p.uncertain!==null && !first) || (first && projected.get(first.path)!==(first.resolution==='verify-desired'?first.desiredHash:first.beforeHash)))
+    fail('switch-continuation-journal.observation');
+  const projectionDigest=()=>contractDigest([...projected].sort(([a],[b])=>a<b?-1:a>b?1:0).map(([path,hash])=>({path,hash})));
+  const maxEvents=1+p.remaining.length+2*count;
+  let sequence=0,head=null,phaseIndex=0,nextIndex=0,pending=null,stopped=null,broken=false;
+  const inspect=()=>({kind:'switch-continuation-event-inspection',previewDigest:digest,sequence,head,
+    status:sequence===0?'not-started':stopped??(pending?'uncertain':phaseIndex===p.remaining.length?'completed':'open'),
+    phase:phaseIndex===p.remaining.length?null:p.remaining[phaseIndex].phase,nextIndex,
+    pending:pending?{...pending}:null,verifiedPhases:phaseIndex,expectedProjectionDigest:projectionDigest(),
+    activationSupported:false,runtime:'not-run'});
+  function append(value) {
+    if(broken)fail('switch-continuation-journal.unavailable');
+    try {
+      const e=detach(value);
+      requestShape(e,['schemaVersion','seq','previous','previewDigest','kind','payload'],[],'switch-continuation-journal.event');
+      if(sequence>=maxEvents || e.schemaVersion!==1 || e.seq!==sequence || e.previous!==head || e.previewDigest!==digest)
+        fail('switch-continuation-journal.binding');
+      if(sequence===0) {
+        if(e.kind!=='start' || contractDigest(e.payload)!==contractDigest(p.predecessor))fail('switch-continuation-journal.start');
+      }else {
+        if(stopped || phaseIndex===p.remaining.length)fail('switch-continuation-journal.sequence');
+        const phase=p.remaining[phaseIndex],t=phase.operations[nextIndex];
+        if(e.kind==='phase-checked') {
+          requestShape(e.payload,['phase','projectionDigest'],[],'switch-continuation-journal.payload');
+          if(pending || t || e.payload.phase!==phase.phase || e.payload.projectionDigest!==projectionDigest())
+            fail('switch-continuation-journal.phase-check');
+          phaseIndex++;nextIndex=0;
+        }else {
+          const intent=e.kind==='intent',readback=e.kind==='readback';
+          requestShape(e.payload,intent?['phase','operationId']:['phase','operationId','status','observedHash'],[],
+            'switch-continuation-journal.payload');
+          const v=e.payload;
+          if(!t || v.phase!==phase.phase || v.operationId!==t.operationId)fail('switch-continuation-journal.sequence');
+          if(intent) {
+            if(pending || t.resolution==='verify-desired' || projected.get(t.path)!==t.beforeHash)
+              fail('switch-continuation-journal.sequence');
+            pending={phase:phase.phase,operationId:t.operationId};
+          }else {
+            if(readback?pending || t.resolution!=='verify-desired':e.kind!=='outcome' || !pending)
+              fail('switch-continuation-journal.sequence');
+            if(!['completed','failed','uncertain'].includes(v.status) || !nullableHash(v.observedHash) ||
+                (v.status==='completed' && v.observedHash!==t.desiredHash) ||
+                (v.status==='failed' && v.observedHash!==(readback?t.desiredHash:t.beforeHash)))
+              fail('switch-continuation-journal.outcome');
+            if(v.status==='completed')projected.set(t.path,t.desiredHash);else stopped=v.status;
+            nextIndex++;pending=null;
+          }
+        }
+      }
+      head=contractDigest(e);sequence++;return inspect();
+    }catch(error){broken=true;throw error;}
+  }
+  return Object.freeze({append,inspect,maxEvents});
+}

package/src/operations/switch-continuation-pending.js

@@ -0,0 +1,60 @@
+import {open,rename} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {readSwitchContinuationRecovery} from './switch-continuation-recovery.js';
+import {verifySwitchContinuationApproval} from './switch-continuation.js';
+import {assertLockHeld} from './lock.js';
+import {readState,observeTargets} from './state.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {validateState,contractDigest} from '../contracts/semantic.js';
+import {parse,fail,ContractError} from '../contracts/parse.js';
+import {sha256} from '../source/inventory.js';
+
+// Exact selection readback only, not a target-state or execution-readiness check.
+export async function inspectSelectedSwitchContinuation(workspace,recoveryPath,recoveryHash) {
+  const filename=resolveChild(workspace,'.pipeline/state.json'),before=await readState(filename);
+  const evidence=await readSwitchContinuationRecovery(workspace,recoveryPath),record=evidence.record;
+  if(evidence.fileHash!==recoveryHash)fail('switch-continuation-pending.evidence');
+  const parent=evidence.root;
+  const expected={...parent.record.previous,status:'needs-reconciliation',pending:record.digest,runtime:'not-run'};
+  if(contractDigest(before.value)!==contractDigest(expected))fail('switch-continuation-pending.selection');
+  const repeated=await readSwitchContinuationRecovery(workspace,recoveryPath);
+  if(repeated.fileHash!==evidence.fileHash || contractDigest(repeated.journal)!==contractDigest(evidence.journal) ||
+      (await readState(filename)).digest!==before.digest)fail('switch-continuation-pending.drift');
+  return {status:'needs-reconciliation',pending:record.digest,stateFileHash:before.digest,recoveryPath,
+    recoveryHash:evidence.fileHash,journalStatus:evidence.journal.status,executionAllowed:false,runtime:'not-run'};
+}
+
+// Select an initialized continuation from the exact old pending state. Neither
+// targets nor active deployment are changed; failed writes are never rolled back.
+export async function markSwitchContinuationPending(lock,recoveryPath,recoveryHash,approval,{boundary=async()=>{}}={}) {
+  approval=parse(JSON.stringify(approval),'json');
+  await assertLockHeld(lock);
+  const evidence=await readSwitchContinuationRecovery(lock.workspace,recoveryPath),record=evidence.record;
+  if(evidence.fileHash!==recoveryHash || evidence.journal.sequence!==1 || evidence.journal.status!==(record.preview.remaining.length?'open':'completed') ||
+      contractDigest(record.approval)!==contractDigest(approval))fail('switch-continuation-pending.evidence');
+  await verifySwitchContinuationApproval(lock,record.preview,approval);
+  const filename=resolveChild(lock.workspace,'.pipeline/state.json'),before=await readState(filename);
+  if(before.digest!==record.preview.stateFileHash)fail('switch-continuation-pending.state');
+  const pending={...before.value,pending:record.digest};validateState(pending);
+  const bytes=Buffer.from(JSON.stringify(pending)+'\n'),scratch='.pipeline/.continuation-state-'+randomUUID()+'.tmp';
+  const staged=resolveChild(lock.workspace,scratch);
+  try {
+    await assertLockHeld(lock);await inspectDirectory(resolveChild(lock.workspace,'.pipeline'));
+    const handle=await open(staged,'wx',0o600);
+    try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+    await boundary('before-rename',{path:'.pipeline/state.json',stagedPath:scratch});
+    await verifySwitchContinuationApproval(lock,record.preview,approval);
+    const fresh=await readSwitchContinuationRecovery(lock.workspace,recoveryPath);
+    if(fresh.fileHash!==recoveryHash || contractDigest(fresh.journal)!==contractDigest(evidence.journal))
+      fail('switch-continuation-pending.evidence');
+    const [temp]=await observeTargets(lock.workspace,[scratch]);
+    if(temp.bytes===null || sha256(temp.bytes)!==sha256(bytes))fail('switch-continuation-pending.staging');
+    await assertLockHeld(lock);
+    if((await readState(filename)).digest!==before.digest)fail('switch-continuation-pending.state');
+    await rename(staged,filename);
+    await boundary('renamed',{path:'.pipeline/state.json'});
+    if((await readState(filename)).digest!==sha256(bytes))fail('switch-continuation-pending.readback');
+    const result=await inspectSelectedSwitchContinuation(lock.workspace,recoveryPath,recoveryHash);
+    await assertLockHeld(lock);return result;
+  }catch(error){throw error instanceof ContractError?error:new ContractError('switch-continuation-pending.io');}
+}

package/src/operations/switch-continuation-records.js

@@ -0,0 +1,109 @@
+import {parse,fail} from '../contracts/parse.js';
+import {requestShape} from './ownership.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {createSwitchContinuationCursor} from './switch-continuation-journal.js';
+
+const hash=v=>typeof v==='string' && /^sha256:[a-f0-9]{64}(?![\s\S])/.test(v);
+const uuid='[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}';
+const journalPath=new RegExp('^\\.pipeline/journals/'+uuid+'(?![\\s\\S])');
+const recoveryPath=new RegExp('^\\.pipeline/transactions/('+uuid+')/recovery.json(?![\\s\\S])');
+const detach=v=>parse(JSON.stringify(v),'json');
+
+// Structural envelope only. Durable validation must also check the predecessor.
+export function createSwitchContinuationRecoveryRecord({preview,approval,journal}) {
+  const p=detach(preview),a=detach(approval);
+  requestShape(p,['kind','workspace','recoveryPath','recoveryHash','predecessor','stateFileHash','observations','uncertain','remaining',
+    'requiresFreshApproval','applySupported','runtime','digest'],[],'switch-continuation-record.preview');
+  requestShape(a,['decision','previewDigest'],[],'switch-continuation-record.approval');
+  requestShape(p.predecessor,['pending','journal','sequence','head','lastFileHash'],[],'switch-continuation-record.predecessor');
+  if(p.uncertain!==null)requestShape(p.uncertain,['phase','operationId','path','beforeHash','desiredHash','observedHash','resolution'],[],
+    'switch-continuation-record.uncertain');
+  absoluteRoot(p.workspace);createSwitchContinuationCursor(p);
+  const source=typeof p.recoveryPath==='string' && recoveryPath.exec(p.recoveryPath);
+  if(!source || p.predecessor.journal!=='.pipeline/journals/'+source[1] ||
+      ![p.recoveryHash,p.stateFileHash,p.predecessor.pending,p.predecessor.head,p.predecessor.lastFileHash].every(hash) ||
+      !Number.isSafeInteger(p.predecessor.sequence) || p.predecessor.sequence<(p.uncertain===null?1:2))fail('switch-continuation-record.predecessor');
+  if(a.decision!=='approve' || a.previewDigest!==p.digest)fail('switch-continuation-record.approval');
+  if(typeof journal!=='string' || !journalPath.test(journal) || journal===p.predecessor.journal)fail('switch-continuation-record.journal');
+  const body={schemaVersion:1,kind:'switch-continuation-recovery',preview:p,approval:a,journal,
+    activationSupported:false,runtime:'not-run'};
+  return detach({...body,digest:contractDigest(body)});
+}
+
+export function validateSwitchContinuationRecoveryRecord(value) {
+  const record=detach(value);
+  requestShape(record,['schemaVersion','kind','preview','approval','journal','activationSupported','runtime','digest'],[],
+    'switch-continuation-record.recovery');
+  const fresh=createSwitchContinuationRecoveryRecord(record);
+  if(contractDigest(record)!==contractDigest(fresh))fail('switch-continuation-record.recovery');
+  return fresh;
+}
+
+// Compare to verified immutable predecessor evidence, not current target bytes.
+export function assertSwitchContinuationPredecessor(preview,evidence) {
+  const {record,journal}=evidence,p=preview;
+  // The caller must first verify the predecessor envelope, journal and ancestry.
+  // This pure check accepts either kind but grants no filesystem authority.
+  const continuation=record.kind==='switch-continuation-recovery';
+  if(!continuation && record.kind!=='switch-recovery')fail('switch-continuation-record.lineage');
+  const base=continuation?{
+    observations:record.preview.observations,
+    phases:record.preview.remaining.map(phase=>({name:phase.phase,preview:{plan:{targets:
+      phase.operations.map(t=>({...t,id:t.operationId}))}}}))
+  }:record.prepared.preview;
+  const workspace=continuation?record.preview.workspace:record.previous.workspace;
+  const expectedParent={pending:record.digest,journal:record.journal,sequence:journal.sequence,
+    head:journal.head,lastFileHash:journal.lastFileHash};
+  if(!(p.uncertain===null?['open','completed']:['uncertain']).includes(journal.status) || evidence.fileHash!==p.recoveryHash || workspace!==p.workspace ||
+      contractDigest(expectedParent)!==contractDigest(p.predecessor))fail('switch-continuation-record.lineage');
+  if(p.uncertain===null) {
+    if(journal.pending)fail('switch-continuation-record.lineage');
+    const expected=new Map(base.observations.map(o=>[o.path,o.hash]));
+    for(let i=0;i<base.phases.length;i++) {
+      const targets=base.phases[i].preview.plan.targets;
+      const count=i<journal.verifiedPhases?targets.length:i===journal.verifiedPhases?journal.nextIndex:0;
+      for(let j=0;j<count;j++)expected.set(targets[j].path,targets[j].desiredHash);
+    }
+    const observations=[...expected].sort(([a],[b])=>a<b?-1:a>b?1:0).map(([path,hash])=>({path,hash}));
+    const remaining=boundaryRemaining(base.phases,journal);
+    if(contractDigest(observations)!==contractDigest(p.observations))fail('switch-continuation-record.observations');
+    if(contractDigest(remaining)!==contractDigest(p.remaining))fail('switch-continuation-record.plan');
+    return;
+  }
+  const phaseIndex=journal.verifiedPhases,phase=base.phases[phaseIndex];
+  const targetIndex=journal.pending?journal.nextIndex:journal.nextIndex-1;
+  const target=phase?.preview.plan.targets[targetIndex];
+  if(!target)fail('switch-continuation-record.lineage');
+  const expected=new Map(base.observations.map(o=>[o.path,o.hash]));
+  for(let i=0;i<=phaseIndex;i++) {
+    const targets=base.phases[i].preview.plan.targets,count=i<phaseIndex?targets.length:targetIndex;
+    for(let j=0;j<count;j++)expected.set(targets[j].path,targets[j].desiredHash);
+  }
+  const observed=p.observations.find(o=>o.path===target.path)?.hash;
+  if(observed!==target.beforeHash && observed!==target.desiredHash)fail('switch-continuation-record.observations');
+  // A previous readback-only approval cannot be widened into a write retry.
+  if(continuation && target.resolution==='verify-desired' && observed!==target.desiredHash)
+    fail('switch-continuation-record.observations');
+  expected.set(target.path,observed);
+  if(contractDigest(p.observations)!==contractDigest([...expected].sort(([a],[b])=>a<b?-1:a>b?1:0).map(([path,hash])=>({path,hash}))))
+    fail('switch-continuation-record.observations');
+  const resolution=observed===target.desiredHash?'verify-desired':'retry-approved-target';
+  const uncertain={phase:phase.name,operationId:target.id,path:target.path,beforeHash:target.beforeHash,
+    desiredHash:target.desiredHash,observedHash:observed,resolution};
+  const remaining=base.phases.slice(phaseIndex).map((phase,index)=>({phase:phase.name,
+    operations:phase.preview.plan.targets.slice(index===0?targetIndex:0).map((t,i)=>({operationId:t.id,path:t.path,
+      resolution:index===0 && i===0?resolution:'apply-approved-target',beforeHash:t.beforeHash,desiredHash:t.desiredHash})),
+    phaseCheckRequired:true}));
+  if(contractDigest(uncertain)!==contractDigest(p.uncertain) || contractDigest(remaining)!==contractDigest(p.remaining))
+    fail('switch-continuation-record.plan');
+}
+
+// Completed outcomes are skipped; unrecorded phase checks remain mandatory.
+// Empty remaining means both phase checks already exist, not inferred success.
+export function boundaryRemaining(phases,journal) {
+  return phases.slice(journal.verifiedPhases).map((phase,index)=>({phase:phase.name,
+    operations:phase.preview.plan.targets.slice(index===0?journal.nextIndex:0).map(t=>({operationId:t.id,path:t.path,
+      resolution:t.resolution==='verify-desired'?'verify-desired':'apply-approved-target',beforeHash:t.beforeHash,desiredHash:t.desiredHash})),
+    phaseCheckRequired:true}));
+}

package/src/operations/switch-continuation-recovery.js

@@ -0,0 +1,91 @@
+import {mkdir,open} from 'node:fs/promises';
+import {createSwitchContinuationRecoveryRecord,validateSwitchContinuationRecoveryRecord,assertSwitchContinuationPredecessor} from './switch-continuation-records.js';
+import {createSwitchContinuationJournal,readSwitchContinuationJournal} from './switch-continuation-store.js';
+import {verifySwitchContinuationApproval} from './switch-continuation.js';
+import {readSwitchRecovery} from './switch-recovery-store.js';
+import {readRecord} from './state.js';
+import {assertLockHeld} from './lock.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {fail,ContractError} from '../contracts/parse.js';
+import {MAX_CONTINUATION_DEPTH} from './lineage-guard.js';
+
+function checkPath(relative) {
+  const match=typeof relative==='string' && /^\.pipeline\/transactions\/([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})\/recovery.json(?![\s\S])/.exec(relative);
+  if(!match)fail('switch-continuation-recovery.path');
+  return match[1];
+}
+
+// Two bounded iterative passes, not recursively repeated ancestry reads.
+// Shared continuation limit plus the original switch; over-limit is fail-closed.
+async function readChain(workspace,relative) {
+  const chain=[],seen=new Set();
+  while(true) {
+    const id=checkPath(relative);
+    if(seen.has(relative))fail('switch-continuation-recovery.cycle');
+    if(chain.length>MAX_CONTINUATION_DEPTH)fail('switch-continuation-recovery.depth');
+    seen.add(relative);
+    const stored=await readRecord(resolveChild(workspace,relative));
+    if(stored.value?.kind==='switch-recovery') {
+      const root=await readSwitchRecovery(workspace,relative);
+      if(root.fileHash!==stored.digest)fail('switch-continuation-recovery.drift');
+      chain.push({relative,...root});break;
+    }
+    const record=validateSwitchContinuationRecoveryRecord(stored.value);
+    if(record.preview.workspace!==workspace || record.journal!=='.pipeline/journals/'+id)
+      fail('switch-continuation-recovery.binding');
+    const journal=await readSwitchContinuationJournal(workspace,record.journal,record.preview);
+    chain.push({relative,record,fileHash:stored.digest,journal});
+    relative=record.preview.recoveryPath;
+  }
+  for(let i=chain.length-2;i>=0;i--)assertSwitchContinuationPredecessor(chain[i].record.preview,chain[i+1]);
+  return chain;
+}
+
+export async function readSwitchLineage(workspace,relative) {
+  const before=await readChain(workspace,relative),after=await readChain(workspace,relative);
+  const binding=chain=>chain.map(e=>({relative:e.relative,fileHash:e.fileHash,journal:e.journal}));
+  if(contractDigest(binding(before))!==contractDigest(binding(after)))fail('switch-continuation-recovery.drift');
+  return {...after[0],root:after.at(-1),ancestors:after.slice(1),applySupported:false,runtime:'not-run'};
+}
+
+// Historical evidence audit, not current-target approval or active-chain selection.
+export async function readSwitchContinuationRecovery(workspace,relative) {
+  const evidence=await readSwitchLineage(workspace,relative);
+  if(evidence.record.kind!=='switch-continuation-recovery')fail('switch-continuation-recovery.binding');
+  return evidence;
+}
+
+// Persist prerequisites only. Partial evidence remains on failure. No mutable
+// journal writer is returned and no targets or active/pending state are changed.
+export async function persistSwitchContinuationRecovery(lock,preview,approval,{boundary=async()=>{},onJournal=async()=>{}}={}) {
+  const checked=await verifySwitchContinuationApproval(lock,preview,approval);
+  // Bound the whole envelope before writing. A different placeholder UUID avoids
+  // accidentally selecting the predecessor as the destination.
+  const placeholders=['00000000-0000-0000-0000-000000000000','00000000-0000-0000-0000-000000000001'];
+  const placeholder=placeholders.map(id=>'.pipeline/journals/'+id).find(p=>p!==checked.preview.predecessor.journal);
+  createSwitchContinuationRecoveryRecord({...checked,journal:placeholder});
+  const journal=await createSwitchContinuationJournal(lock,checked.preview,checked.approval,{onLocation:onJournal});
+  const uuid=journal.relative.split('/').at(-1),relative='.pipeline/transactions/'+uuid+'/recovery.json';
+  const record=createSwitchContinuationRecoveryRecord({...checked,journal:journal.relative});
+  const bytes=Buffer.from(JSON.stringify(record)+'\n');
+  try {
+    await verifySwitchContinuationApproval(lock,checked.preview,checked.approval);
+    const parent=resolveChild(lock.workspace,'.pipeline/transactions'),directory=resolveChild(lock.workspace,'.pipeline/transactions/'+uuid);
+    try{await mkdir(parent);}catch(error){if(error.code!=='EEXIST')throw error;}
+    await inspectDirectory(parent);await mkdir(directory);await inspectDirectory(directory);
+    const handle=await open(resolveChild(lock.workspace,relative),'wx',0o600);
+    try {
+      await boundary('opened',{path:relative});await handle.writeFile(bytes);await handle.sync();
+    }finally{await handle.close();}
+    await boundary('recovery-written',{path:relative});
+    if((await readRecord(resolveChild(lock.workspace,relative))).digest!==sha256(bytes))fail('switch-continuation-recovery.readback');
+    await verifySwitchContinuationApproval(lock,checked.preview,checked.approval);
+    const evidence=await readSwitchContinuationRecovery(lock.workspace,relative);
+    if(evidence.journal.sequence!==1 || evidence.journal.status!==(record.preview.remaining.length?'open':'completed'))fail('switch-continuation-recovery.journal');
+    await assertLockHeld(lock);
+    return {recoveryPath:relative,recoveryHash:evidence.fileHash,journalPath:record.journal,
+      applySupported:false,runtime:'not-run'};
+  }catch(error){throw error instanceof ContractError?error:new ContractError('switch-continuation-recovery.io');}
+}

package/src/operations/switch-continuation-runtime.js

@@ -0,0 +1,135 @@
+import {readSwitchContinuationRecovery} from './switch-continuation-recovery.js';
+import {openSwitchContinuationJournal} from './switch-continuation-store.js';
+import {assertLockHeld} from './lock.js';
+import {writeCheckedFile,deleteCheckedFile} from './apply.js';
+import {readState,readRecord,observeTargets} from './state.js';
+import {resolveChild} from '../workspace/paths.js';
+import {contractDigest,validateState} from '../contracts/semantic.js';
+import {fail} from '../contracts/parse.js';
+import {sha256} from '../source/inventory.js';
+
+const hashes=observations=>observations.map(o=>({path:o.path,hash:o.bytes===null?null:sha256(o.bytes)}));
+async function context(workspace,recoveryPath) {
+  const evidence=await readSwitchContinuationRecovery(workspace,recoveryPath);
+  const parent=evidence.root;
+  return {evidence,parent};
+}
+function pendingState(evidence,parent) {
+  return {...parent.record.previous,status:'needs-reconciliation',pending:evidence.record.digest,runtime:'not-run'};
+}
+function readyState(evidence,parent,recoveryPath) {
+  if(evidence.journal.status!=='completed' || evidence.journal.verifiedPhases!==evidence.record.preview.remaining.length)
+    fail('switch-continuation-runtime.incomplete');
+  const state={...parent.record.previous,status:'ready',pending:null,runtime:'not-run',
+    active:parent.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;
+}
+function projection(evidence) {
+  const p=evidence.record.preview,j=evidence.journal,map=new Map(p.observations.map(o=>[o.path,o.hash]));
+  const stopped=!j.pending && ['failed','uncertain'].includes(j.status);
+  let uncertain=null;
+  for(let i=0;i<p.remaining.length;i++) {
+    const phase=p.remaining[i],count=i<j.verifiedPhases?phase.operations.length:
+      i===j.verifiedPhases?j.nextIndex-(stopped?1:0):0;
+    for(let n=0;n<count;n++)map.set(phase.operations[n].path,phase.operations[n].desiredHash);
+    if(i===j.verifiedPhases && j.status==='uncertain')uncertain={...phase.operations[j.pending?j.nextIndex:j.nextIndex-1],phase:phase.phase};
+  }
+  return {map,uncertain};
+}
+
+export async function inspectSwitchContinuation(workspace,recoveryPath,{active=false}={}) {
+  const filename=resolveChild(workspace,'.pipeline/state.json'),before=await readState(filename);
+  const {evidence,parent}=await context(workspace,recoveryPath);
+  const expected=active?readyState(evidence,parent,recoveryPath):pendingState(evidence,parent);
+  if(contractDigest(before.value)!==contractDigest(expected))fail('switch-continuation-runtime.selection');
+  const {map,uncertain}=projection(evidence);
+  const observations=hashes(await observeTargets(workspace,[...map.keys()]));
+  const conflicts=observations.filter(o=>uncertain?.path===o.path?
+    o.hash!==uncertain.beforeHash && o.hash!==uncertain.desiredHash:o.hash!==map.get(o.path)).map(o=>o.path);
+  const after=await readSwitchContinuationRecovery(workspace,recoveryPath);
+  if(after.fileHash!==evidence.fileHash || contractDigest(after.journal)!==contractDigest(evidence.journal) ||
+      (await readState(filename)).digest!==before.digest ||
+      contractDigest(hashes(await observeTargets(workspace,[...map.keys()])))!==contractDigest(observations))
+    fail('switch-continuation-runtime.drift');
+  if(active && conflicts.length)fail('switch-continuation-runtime.target-drift');
+  return {status:active?'applied':'needs-reconciliation',recoveryHash:evidence.fileHash,recoveryPath,
+    stateFileHash:before.digest,observations,conflicts,uncertain,phase:evidence.journal.phase,
+    journalStatus:evidence.journal.status,journalCompleted:evidence.journal.status==='completed',runtime:'not-run'};
+}
+
+export async function executeSwitchContinuationPhase(lock,recoveryPath,recoveryHash,approval,phaseName,{boundary=async()=>{}}={}) {
+  approval=structuredClone(approval);await assertLockHeld(lock);
+  const {evidence,parent}=await context(lock.workspace,recoveryPath),record=evidence.record;
+  if(evidence.fileHash!==recoveryHash || contractDigest(record.approval)!==contractDigest(approval))fail('switch-continuation-runtime.approval');
+  const phase=record.preview.remaining.find(p=>p.phase===phaseName);
+  const original=parent.record.prepared.preview.phases.find(p=>p.name===phaseName);
+  if(!phase || !original)fail('switch-continuation-runtime.phase');
+  const initial=await inspectSwitchContinuation(lock.workspace,recoveryPath);
+  if(initial.conflicts.length || initial.uncertain || initial.journalStatus!=='open' || initial.phase!==phaseName)
+    fail('switch-continuation-runtime.state');
+  const expected=new Map(initial.observations.map(o=>[o.path,o.hash]));
+  async function guard() {
+    await assertLockHeld(lock);
+    if((await readState(resolveChild(lock.workspace,'.pipeline/state.json'))).digest!==initial.stateFileHash ||
+        (await readRecord(resolveChild(lock.workspace,recoveryPath))).digest!==recoveryHash ||
+        (await readRecord(resolveChild(lock.workspace,record.preview.recoveryPath))).digest!==record.preview.recoveryHash)
+      fail('switch-continuation-runtime.state');
+    for(const ancestor of evidence.ancestors) {
+      if((await readRecord(resolveChild(lock.workspace,ancestor.relative))).digest!==ancestor.fileHash)
+        fail('switch-continuation-runtime.state');
+    }
+    if(hashes(await observeTargets(lock.workspace,[...expected.keys()])).some(o=>o.hash!==expected.get(o.path)))
+      fail('switch-continuation-runtime.target-drift');
+  }
+  const journal=await openSwitchContinuationJournal(lock,record.preview,record.journal,evidence.journal.lastFileHash);
+  for(const op of phase.operations.slice(evidence.journal.nextIndex)) {
+    await guard();
+    if(op.resolution==='verify-desired') {
+      if(expected.get(op.path)!==op.desiredHash)fail('switch-continuation-runtime.target-drift');
+      await boundary('readback',{phase:phaseName,path:op.path});await guard();
+      await journal.readback(phaseName,op.operationId,'completed',op.desiredHash);
+    }else {
+      const target=original.preview.plan.targets.find(t=>t.id===op.operationId);
+      if(!target || !['delete','create','replace','edit-fields'].includes(target.action))fail('switch-continuation-runtime.action');
+      await journal.intent(phaseName,op.operationId);await boundary('intent',{phase:phaseName,path:op.path});await guard();
+      if(expected.get(op.path)!==op.beforeHash)fail('switch-continuation-runtime.target-drift');
+      if(target.action==='delete')await deleteCheckedFile(lock,op.path,op.beforeHash,async()=>{});
+      else {
+        const output=original.preview.outputs.find(o=>o.path===op.path);
+        if(!output)fail('switch-continuation-runtime.output');
+        await writeCheckedFile(lock,op.path,op.beforeHash,Buffer.from(output.bytes,'base64'));
+      }
+      await boundary('target-written',{phase:phaseName,path:op.path});expected.set(op.path,op.desiredHash);await guard();
+      await journal.outcome(phaseName,op.operationId,'completed',op.desiredHash);
+    }
+  }
+  await guard();
+  const fresh=await readSwitchContinuationRecovery(lock.workspace,recoveryPath);
+  await journal.phaseChecked(phaseName,fresh.journal.expectedProjectionDigest);
+  const result=await inspectSwitchContinuation(lock.workspace,recoveryPath);await assertLockHeld(lock);
+  if(result.conflicts.length)fail('switch-continuation-runtime.target-drift');
+  return result;
+}
+
+export async function activateSwitchContinuation(lock,recoveryPath,recoveryHash,approval,{boundary=async()=>{}}={}) {
+  approval=structuredClone(approval);
+  async function check() {
+    await assertLockHeld(lock);
+    const {evidence,parent}=await context(lock.workspace,recoveryPath);
+    if(evidence.fileHash!==recoveryHash || contractDigest(evidence.record.approval)!==contractDigest(approval))fail('switch-continuation-runtime.approval');
+    const ready=readyState(evidence,parent,recoveryPath),inspection=await inspectSwitchContinuation(lock.workspace,recoveryPath);
+    if(inspection.conflicts.length || inspection.uncertain)fail('switch-continuation-runtime.target-drift');
+    return {ready,stateHash:inspection.stateFileHash};
+  }
+  const checked=await check(),bytes=Buffer.from(JSON.stringify(checked.ready)+'\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-continuation-runtime.drift');
+    }
+  });
+  const result=await inspectSwitchContinuation(lock.workspace,recoveryPath,{active:true});await assertLockHeld(lock);return result;
+}