@6reduk/workspace-pipeline 0.1.0

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

@@ -0,0 +1,120 @@
+import {mkdir,open,readdir} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {createSwitchContinuationCursor} from './switch-continuation-journal.js';
+import {verifySwitchContinuationApproval} from './switch-continuation.js';
+import {assertLockHeld} from './lock.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {readRecord} from './state.js';
+import {sha256} from '../source/inventory.js';
+import {fail,ContractError} from '../contracts/parse.js';
+
+const nameFor=n=>String(n).padStart(6,'0')+'.json';
+const ioError=e=>e instanceof ContractError?e:new ContractError('switch-continuation-store.io');
+function directoryFor(workspace,relative,preview) {
+  if(preview.workspace!==workspace || typeof relative!=='string' ||
+      !/^\.pipeline\/journals\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?![\s\S])/.test(relative) ||
+      relative===preview.predecessor.journal)fail('switch-continuation-store.path');
+  return resolveChild(workspace,relative);
+}
+
+// Audit events only; caller supplies the verified preview. No history resolution
+// or proof of provider writes is inferred from a valid event stream.
+export async function readSwitchContinuationJournal(workspace,relative,preview) {
+  const cursor=createSwitchContinuationCursor(preview),directory=directoryFor(workspace,relative,preview);
+  try {
+    await inspectDirectory(directory);
+    const names=(await readdir(directory)).sort();
+    if(!names.length || names.length>cursor.maxEvents)fail('switch-continuation-store.count');
+    let lastFileHash=null;
+    for(let seq=0;seq<names.length;seq++) {
+      if(names[seq]!==nameFor(seq))fail('switch-continuation-store.sequence');
+      const record=await readRecord(resolveChild(workspace,relative+'/'+names[seq]));
+      cursor.append(record.value);lastFileHash=record.digest;
+    }
+    if(JSON.stringify((await readdir(directory)).sort())!==JSON.stringify(names))fail('switch-continuation-store.drift');
+    return {...cursor.inspect(),lastFileHash};
+  }catch(error){throw ioError(error);}
+}
+
+// Internal evidence writer only. No target writes or pending-state transition.
+// New chain only: no reopen, retry or automatic deletion of partial evidence.
+export async function createSwitchContinuationJournal(lock,preview,approval,{ioBoundary=async()=>{},onLocation=async()=>{}}={}) {
+  return continuationWriter(lock,preview,approval,{ioBoundary,onLocation});
+}
+
+// Reopen only a fully audited open chain with an exact byte head. Selection and
+// target checks belong to the executor; uncertain/failed chains never reopen.
+export async function openSwitchContinuationJournal(lock,preview,relative,expectedFileHash) {
+  return continuationWriter(lock,preview,null,{}, {relative,expectedFileHash});
+}
+
+async function continuationWriter(lock,preview,approval,{ioBoundary=async()=>{},onLocation=async()=>{}}={},existing=null) {
+  if(existing) {preview=structuredClone(preview);await assertLockHeld(lock);}
+  else {
+    const checked=await verifySwitchContinuationApproval(lock,preview,approval);
+    preview=checked.preview;approval=checked.approval;
+  }
+  const cursor=createSwitchContinuationCursor(preview),relative=existing?.relative??'.pipeline/journals/'+randomUUID();
+  const directory=directoryFor(lock.workspace,relative,preview);
+  let state=cursor.inspect(),lastFileHash=null,busy=false,broken=false;
+  const metrics={headReads:0,recordReadbacks:0,fullAudits:0};
+  async function audit() {
+    metrics.fullAudits++;
+    const result=await readSwitchContinuationJournal(lock.workspace,relative,preview);
+    if(result.sequence!==state.sequence || result.head!==state.head || result.lastFileHash!==lastFileHash)
+      fail('switch-continuation-store.drift');
+  }
+  async function append(kind,payload) {
+    if(busy || broken)fail('switch-continuation-store.unavailable');busy=true;
+    try {
+      await assertLockHeld(lock);await inspectDirectory(directory);
+      if(state.sequence) {
+        const record=await readRecord(resolveChild(lock.workspace,relative+'/'+nameFor(state.sequence-1)));metrics.headReads++;
+        if(record.digest!==lastFileHash)fail('switch-continuation-store.drift');
+      }
+      const event={schemaVersion:1,seq:state.sequence,previous:state.head,previewDigest:preview.digest,kind,payload};
+      const next=cursor.append(event),bytes=Buffer.from(JSON.stringify(event)+'\n');
+      const detail={path:relative+'/'+nameFor(state.sequence)};
+      const handle=await open(resolveChild(lock.workspace,detail.path),'wx',0o600);
+      try {
+        await ioBoundary('opened',detail);await handle.writeFile(bytes);await ioBoundary('written',detail);
+        await handle.sync();await ioBoundary('synced',detail);
+      }finally{await handle.close();}
+      const record=await readRecord(resolveChild(lock.workspace,detail.path));metrics.recordReadbacks++;
+      if(record.digest!==sha256(bytes))fail('switch-continuation-store.readback');
+      await ioBoundary('readback',detail);
+      await assertLockHeld(lock);
+      state=next;lastFileHash=record.digest;
+      if(kind==='phase-checked' || ['failed','uncertain'].includes(payload?.status))await audit();
+      return {...state,pending:state.pending?{...state.pending}:null,lastFileHash};
+    }catch(error){broken=true;throw ioError(error);}finally{busy=false;}
+  }
+  try {
+    if(existing) {
+      const inspected=await readSwitchContinuationJournal(lock.workspace,relative,preview);
+      if(inspected.status!=='open' || inspected.lastFileHash!==existing.expectedFileHash)fail('switch-continuation-store.reopen');
+      for(let seq=0;seq<inspected.sequence;seq++) {
+        const entry=await readRecord(resolveChild(lock.workspace,relative+'/'+nameFor(seq)));
+        state=cursor.append(entry.value);lastFileHash=entry.digest;
+      }
+      if(state.head!==inspected.head || state.sequence!==inspected.sequence)fail('switch-continuation-store.drift');
+      await audit();await assertLockHeld(lock);
+    }else {
+    await onLocation({relative,directory,status:'planned'});
+    await verifySwitchContinuationApproval(lock,preview,approval);
+    const parent=resolveChild(lock.workspace,'.pipeline/journals');
+    try{await mkdir(parent);}catch(error){if(error.code!=='EEXIST')throw error;}
+    await inspectDirectory(parent);await mkdir(directory);
+    await onLocation({relative,directory,status:'created'});
+    await verifySwitchContinuationApproval(lock,preview,approval);
+    await append('start',preview.predecessor);await audit();
+    await onLocation({relative,directory,status:'initialized'});
+    await verifySwitchContinuationApproval(lock,preview,approval);
+    }
+    return Object.freeze({relative,directory,metrics:()=>({...metrics}),
+      intent:(phase,operationId)=>append('intent',{phase,operationId}),
+      outcome:(phase,operationId,status,observedHash)=>append('outcome',{phase,operationId,status,observedHash}),
+      readback:(phase,operationId,status,observedHash)=>append('readback',{phase,operationId,status,observedHash}),
+      phaseChecked:(phase,projectionDigest)=>append('phase-checked',{phase,projectionDigest})});
+  }catch(error){broken=true;throw ioError(error);}
+}

package/src/operations/switch-continuation.js

@@ -0,0 +1,76 @@
+import {inspectPendingSwitch} from './switch-inspect.js';
+import {readSwitchLineage} from './switch-continuation-recovery.js';
+import {inspectSwitchContinuation} from './switch-continuation-runtime.js';
+import {assertSwitchContinuationPredecessor,boundaryRemaining} from './switch-continuation-records.js';
+import {readState} from './state.js';
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {parse,fail} from '../contracts/parse.js';
+import {requestShape} from './ownership.js';
+import {assertLockHeld} from './lock.js';
+import {assertContinuationCapacity} from './lineage-guard.js';
+
+// Exact approval is checked against a freshly reconstructed preview under lock.
+// This remains read-only and does not authorize an old journal to be amended.
+export async function verifySwitchContinuationApproval(lock,preview,approval) {
+  const copy=parse(JSON.stringify(preview),'json'),decision=parse(JSON.stringify(approval),'json');
+  requestShape(copy,['kind','workspace','recoveryPath','recoveryHash','predecessor','stateFileHash','observations','uncertain','remaining',
+    'requiresFreshApproval','applySupported','runtime','digest'],[],'switch-continuation.preview');
+  requestShape(decision,['decision','previewDigest'],[],'switch-continuation.approval');
+  const {digest,...body}=copy;
+  if(copy.kind!=='switch-continuation-preview' || copy.requiresFreshApproval!==true || copy.applySupported!==false ||
+      copy.runtime!=='not-run' || contractDigest(body)!==digest)fail('switch-continuation.preview');
+  if(decision.decision!=='approve' || decision.previewDigest!==digest)fail('switch-continuation.approval');
+  await assertLockHeld(lock);
+  if(copy.workspace!==lock.workspace)fail('switch-continuation.workspace');
+  const fresh=await prepareSwitchContinuation(lock.workspace,copy.recoveryPath);
+  if(contractDigest(fresh)!==contractDigest(copy))fail('switch-continuation.plan-drift');
+  await assertLockHeld(lock);
+  return {preview:fresh,approval:decision,applySupported:false,runtime:'not-run'};
+}
+
+// Read-only proposal for a NEW continuation, never an amendment to the old
+// uncertain journal. A future executor needs separate approval and evidence.
+export async function prepareSwitchContinuation(workspace,recoveryPath) {
+  workspace=absoluteRoot(workspace);
+  const evidence=await readSwitchLineage(workspace,recoveryPath),record=evidence.record;
+  assertContinuationCapacity(evidence.ancestors.length);
+  const continuation=record.kind==='switch-continuation-recovery';
+  const inspect=async()=>{
+    if(!continuation)return inspectPendingSwitch(workspace,recoveryPath);
+    const result=await inspectSwitchContinuation(workspace,recoveryPath);
+    return {...result,targets:result.observations};
+  };
+  const inspection=await inspect();
+  if(inspection.conflicts.length || !(inspection.uncertain?['uncertain']:['open','completed']).includes(inspection.journalStatus))fail('switch-continuation.state');
+  if(evidence.fileHash!==inspection.recoveryHash)fail('switch-continuation.drift');
+  const state=await readState(resolveChild(workspace,'.pipeline/state.json'));
+  const expected={...evidence.root.record.previous,status:'needs-reconciliation',pending:record.digest,runtime:'not-run'};
+  if(contractDigest(state.value)!==contractDigest(expected))fail('switch-continuation.binding');
+  const {phase,operationId,path,beforeHash,desiredHash}=inspection.uncertain??{};
+  const uncertain={phase,operationId,path,beforeHash,desiredHash},observed=inspection.targets.find(t=>t.path===uncertain.path);
+  // Equal before/desired bytes need readback only, not an unnecessary write.
+  const resolution=observed?.hash===uncertain.desiredHash?'verify-desired':'retry-approved-target';
+  const phases=continuation?record.preview.remaining.map(p=>({name:p.phase,preview:{plan:{targets:
+    p.operations.map(t=>({...t,id:t.operationId}))}}})):record.prepared.preview.phases;
+  const phaseIndex=phases.findIndex(p=>p.name===uncertain.phase);
+  if(inspection.uncertain && phaseIndex<0)fail('switch-continuation.target');
+  const targetIndex=inspection.uncertain?phases[phaseIndex].preview.plan.targets.findIndex(t=>t.id===uncertain.operationId):0;
+  if(inspection.uncertain && targetIndex<0)fail('switch-continuation.target');
+  const remaining=!inspection.uncertain?boundaryRemaining(phases,evidence.journal):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}));
+  const body={kind:'switch-continuation-preview',workspace,recoveryPath,recoveryHash:evidence.fileHash,
+    predecessor:{pending:record.digest,journal:record.journal,sequence:evidence.journal.sequence,
+      head:evidence.journal.head,lastFileHash:evidence.journal.lastFileHash},
+    stateFileHash:state.digest,observations:inspection.targets.map(t=>({path:t.path,hash:t.hash})),
+    uncertain:inspection.uncertain?{...uncertain,observedHash:observed.hash,resolution}:null,remaining,
+    requiresFreshApproval:true,applySupported:false,runtime:'not-run'};
+  assertSwitchContinuationPredecessor(body,evidence);
+  const repeated=await inspect(),after=await readSwitchLineage(workspace,recoveryPath);
+  if(contractDigest(repeated)!==contractDigest(inspection) || after.fileHash!==evidence.fileHash ||
+      contractDigest(after.journal)!==contractDigest(evidence.journal) ||
+      (await readState(resolveChild(workspace,'.pipeline/state.json'))).digest!==state.digest)fail('switch-continuation.drift');
+  const copy=parse(JSON.stringify(body),'json');return {...copy,digest:contractDigest(copy)};
+}

package/src/operations/switch-execute.js

@@ -0,0 +1,68 @@
+import {readSwitchRecovery} from './switch-recovery-store.js';
+import {validateSwitchRecord} from './switch-records.js';
+import {inspectPendingSwitch} from './switch-inspect.js';
+import {openSwitchJournal} from './switch-journal-store.js';
+import {assertLockHeld} from './lock.js';
+import {writeCheckedFile,deleteCheckedFile} from './apply.js';
+import {observeTargets,readState,readRecord} from './state.js';
+import {resolveChild} from '../workspace/paths.js';
+import {sha256} from '../source/inventory.js';
+import {fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+
+// Execute exactly the explicitly selected current phase. No activation, automatic
+// phase chaining or uncertain-operation continuation. Public routing is absent.
+export async function executeSwitchPhase(lock,recoveryPath,recoveryHash,approval,phaseName,{boundary=async()=>{}}={}) {
+  approval=structuredClone(approval);
+  await assertLockHeld(lock);
+  const evidence=await readSwitchRecovery(lock.workspace,recoveryPath),record=evidence.record;
+  if(evidence.fileHash!==recoveryHash)fail('switch-execute.recovery');
+  validateSwitchRecord(record.prepared,approval,record.previous);
+  const phase=record.prepared.preview.phases.find(p=>p.name===phaseName);
+  if(!phase)fail('switch-execute.phase');
+  if(phase.preview.plan.targets.some(t=>!['delete','create','replace','edit-fields'].includes(t.action)))fail('switch-execute.action');
+  async function inspect(allowIntent=false) {
+    await assertLockHeld(lock);
+    const current=await inspectPendingSwitch(lock.workspace,recoveryPath);
+    if(current.recoveryHash!==recoveryHash || current.conflicts.length || current.phase!==phaseName ||
+        (!allowIntent && current.journalStatus!=='open'))fail('switch-execute.state');
+    return current;
+  }
+  const initial=await inspect();
+  const currentState=await readState(resolveChild(lock.workspace,'.pipeline/state.json'));
+  if(contractDigest(currentState.value)!==contractDigest({...record.previous,status:'needs-reconciliation',pending:record.digest,runtime:'not-run'}))fail('switch-execute.state');
+  const stateHash=currentState.digest;
+  const expected=new Map(initial.targets.map(t=>[t.path,t.hash]));
+  async function guard() {
+    await assertLockHeld(lock);
+    if((await readState(resolveChild(lock.workspace,'.pipeline/state.json'))).digest!==stateHash ||
+        (await readRecord(resolveChild(lock.workspace,recoveryPath))).digest!==recoveryHash)fail('switch-execute.state');
+    const observations=await observeTargets(lock.workspace,[...expected.keys()]);
+    if(observations.some(o=>(o.bytes===null?null:sha256(o.bytes))!==expected.get(o.path)))fail('switch-execute.before');
+  }
+  const journal=await openSwitchJournal(lock,record.prepared.preview,record.previous,record.journal,evidence.journal.lastFileHash);
+  const outputs=new Map(phase.preview.outputs.map(o=>[o.path,Buffer.from(o.bytes,'base64')]));
+  for(const target of phase.preview.plan.targets.slice(evidence.journal.nextIndex)) {
+    await guard();
+    await journal.intent(phaseName,target.id);
+    await boundary('intent',{phase:phaseName,path:target.path});
+    await guard();
+    if(expected.get(target.path)!==target.beforeHash)fail('switch-execute.before');
+    if(target.action==='delete')await deleteCheckedFile(lock,target.path,target.beforeHash,async()=>{});
+    else if(['create','replace','edit-fields'].includes(target.action))await writeCheckedFile(lock,target.path,target.beforeHash,outputs.get(target.path));
+    else fail('switch-execute.action');
+    await boundary('target-written',{phase:phaseName,path:target.path});
+    expected.set(target.path,target.desiredHash);
+    await guard();
+    const [observed]=await observeTargets(lock.workspace,[target.path]);
+    if((observed.bytes===null?null:sha256(observed.bytes))!==target.desiredHash)fail('switch-execute.readback');
+    await journal.outcome(phaseName,target.id,'completed',target.desiredHash);
+  }
+  await inspect();
+  const fresh=await readSwitchRecovery(lock.workspace,recoveryPath);
+  await journal.phaseChecked(phaseName,fresh.journal.expectedProjectionDigest);
+  const result=await inspectPendingSwitch(lock.workspace,recoveryPath);
+  if(result.conflicts.length)fail('switch-execute.final-drift');
+  return {status:'needs-reconciliation',completedPhase:phaseName,nextPhase:result.phase,
+    journalCompleted:result.journalCompleted,recoveryPath,activationSupported:false,runtime:'not-run'};
+}

package/src/operations/switch-inspect.js

@@ -0,0 +1,45 @@
+import {readSwitchRecovery} from './switch-recovery-store.js';
+import {readState,observeTargets} from './state.js';
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {fail} from '../contracts/parse.js';
+
+// Read-only pending inspection; observed desired bytes cannot turn an unfinished
+// intent into a successful outcome. No continuation, repair or activation grant.
+export async function inspectPendingSwitch(workspace,recoveryPath) {
+  workspace=absoluteRoot(workspace);
+  const before=await readState(resolveChild(workspace,'.pipeline/state.json'));
+  const evidence=await readSwitchRecovery(workspace,recoveryPath),{record,journal}=evidence;
+  const pending={...record.previous,status:'needs-reconciliation',pending:record.digest,runtime:'not-run'};
+  if(contractDigest(before.value)!==contractDigest(pending))fail('switch-inspect.activation-binding');
+  const preview=record.prepared.preview,expected=new Map(preview.observations.map(o=>[o.path,o.hash]));
+  const stoppedOutcome=journal.pending===null && ['failed','uncertain'].includes(journal.status);
+  for(let phase=0;phase<preview.phases.length;phase++) {
+    const targets=preview.phases[phase].preview.plan.targets;
+    const count=phase<journal.verifiedPhases?targets.length:phase===journal.verifiedPhases?journal.nextIndex-(stoppedOutcome?1:0):0;
+    for(let i=0;i<count;i++)expected.set(targets[i].path,targets[i].desiredHash);
+  }
+  let uncertain=null;
+  if(journal.status==='uncertain') {
+    const phase=preview.phases[journal.verifiedPhases];
+    const target=phase.preview.plan.targets[journal.pending?journal.nextIndex:journal.nextIndex-1];
+    uncertain={phase:phase.name,operationId:target.id,path:target.path,beforeHash:target.beforeHash,desiredHash:target.desiredHash};
+  }
+  const observed=await observeTargets(workspace,[...expected.keys()]);
+  const hashes=items=>items.map(o=>({path:o.path,hash:o.bytes===null?null:sha256(o.bytes)}));
+  const targets=hashes(observed).map(o=>({...o,expectedHash:expected.get(o.path),
+    disposition:uncertain?.path===o.path?
+      o.hash===uncertain.beforeHash?'uncertain-before':o.hash===uncertain.desiredHash?'uncertain-desired':'conflict':
+      o.hash===expected.get(o.path)?'intact':'conflict'}));
+  // Repeat dependency and current-file checks; this is still not an atomic OS
+  // snapshot and is not a reusable capability for subsequent writes.
+  const after=await readSwitchRecovery(workspace,recoveryPath);
+  if(after.fileHash!==evidence.fileHash || contractDigest(after.journal)!==contractDigest(journal) ||
+      (await readState(resolveChild(workspace,'.pipeline/state.json'))).digest!==before.digest ||
+      contractDigest(hashes(await observeTargets(workspace,[...expected.keys()])))!==contractDigest(hashes(observed)))fail('switch-inspect.drift');
+  return {status:'needs-reconciliation',recoveryPath,recoveryHash:evidence.fileHash,pending:record.digest,
+    phase:journal.phase,journalStatus:journal.status,journalCompleted:journal.status==='completed',
+    targets,conflicts:targets.filter(t=>t.disposition==='conflict').map(t=>t.path),uncertain,
+    executionAllowed:false,runtime:'not-run'};
+}

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

@@ -0,0 +1,109 @@
+import {mkdir,open,readdir} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {createSwitchEventCursor} from './switch-journal.js';
+import {assertLockHeld} from './lock.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {readRecord} from './state.js';
+import {sha256} from '../source/inventory.js';
+import {fail,ContractError} from '../contracts/parse.js';
+
+const nameFor=n=>String(n).padStart(6,'0')+'.json';
+const ioError=e=>e instanceof ContractError?e:new ContractError('switch-journal.io');
+function directoryFor(workspace,relative,preview) {
+  if(preview.workspace!==workspace || !/^\.pipeline\/journals\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(?![\s\S])/.test(relative))fail('switch-journal.path');
+  return resolveChild(workspace,relative);
+}
+
+// Full read-only audit of persisted events; never resumes execution or activates.
+export async function readSwitchJournal(workspace,relative,preview,previous) {
+  const cursor=createSwitchEventCursor(preview,previous),directory=directoryFor(workspace,relative,preview);
+  try {
+    await inspectDirectory(directory);
+    const names=(await readdir(directory)).sort();
+    if(!names.length || names.length>cursor.maxEvents)fail('switch-journal.count');
+    let lastFileHash=null;
+    for(let seq=0;seq<names.length;seq++) {
+      if(names[seq]!==nameFor(seq))fail('switch-journal.sequence');
+      const record=await readRecord(resolveChild(workspace,relative+'/'+names[seq]));
+      cursor.append(record.value);lastFileHash=record.digest;
+    }
+    if(JSON.stringify((await readdir(directory)).sort())!==JSON.stringify(names))fail('switch-journal.drift');
+    return {...cursor.inspect(),lastFileHash};
+  }catch(error){throw ioError(error);}
+}
+
+// Internal persistence only. This writes journal evidence, not provider targets.
+// No auto-resume/approval or integration with normal recovery is implied.
+export async function createSwitchJournal(lock,preview,previous,{ioBoundary=async()=>{},onLocation=async()=>{}}={}) {
+  return journalWriter(lock,preview,previous,{ioBoundary,onLocation});
+}
+
+// Explicit reopening of an intact open chain only, never uncertain continuation.
+export async function openSwitchJournal(lock,preview,previous,relative,expectedFileHash) {
+  return journalWriter(lock,preview,previous,{}, {relative,expectedFileHash});
+}
+
+async function journalWriter(lock,preview,previous,{ioBoundary=async()=>{},onLocation=async()=>{}}={},existing=null) {
+  const cursor=createSwitchEventCursor(preview,previous);
+  await assertLockHeld(lock);
+  const relative=existing?.relative??'.pipeline/journals/'+randomUUID(),directory=directoryFor(lock.workspace,relative,preview);
+  preview=structuredClone(preview);previous=structuredClone(previous);
+  let state=cursor.inspect(),lastFileHash=null,busy=false,broken=false;
+  const metrics={headReads:0,recordReadbacks:0,fullAudits:0};
+  async function audit() {
+    metrics.fullAudits++;
+    const result=await readSwitchJournal(lock.workspace,relative,preview,previous);
+    if(result.sequence!==state.sequence || result.head!==state.head || result.lastFileHash!==lastFileHash)fail('switch-journal.drift');
+    return result;
+  }
+  async function append(kind,payload) {
+    if(busy || broken)fail('switch-journal.unavailable');busy=true;
+    try {
+      await assertLockHeld(lock);await inspectDirectory(directory);
+      if(state.sequence) {
+        const head=await readRecord(resolveChild(lock.workspace,relative+'/'+nameFor(state.sequence-1)));metrics.headReads++;
+        if(head.digest!==lastFileHash)fail('switch-journal.drift');
+      }
+      const event={schemaVersion:1,seq:state.sequence,previous:state.head,previewDigest:preview.digest,kind,payload};
+      // Validate before disk writes. A later IO failure poisons this writer.
+      const next=cursor.append(event),bytes=Buffer.from(JSON.stringify(event)+'\n');
+      const detail={path:relative+'/'+nameFor(state.sequence)};
+      const handle=await open(resolveChild(lock.workspace,detail.path),'wx',0o600);
+      try {
+        await ioBoundary('opened',detail);await handle.writeFile(bytes);await ioBoundary('written',detail);
+        await handle.sync();await ioBoundary('synced',detail);
+      }finally{await handle.close();}
+      const record=await readRecord(resolveChild(lock.workspace,detail.path));metrics.recordReadbacks++;
+      if(record.digest!==sha256(bytes))fail('switch-journal.readback');
+      await ioBoundary('readback',detail);
+      state=next;lastFileHash=record.digest;
+      // Full audit at both phase boundaries (before allowing install) and stop.
+      if(kind==='phase-checked' || ['failed','uncertain'].includes(payload?.status))await audit();
+      return {...state,pending:state.pending?{...state.pending}:null,lastFileHash};
+    }catch(error){broken=true;throw ioError(error);}finally{busy=false;}
+  }
+  try {
+    if(existing) {
+      const inspected=await readSwitchJournal(lock.workspace,relative,preview,previous);
+      if(inspected.status!=='open' || inspected.lastFileHash!==existing.expectedFileHash)fail('switch-journal.reopen');
+      for(let seq=0;seq<inspected.sequence;seq++) {
+        const entry=await readRecord(resolveChild(lock.workspace,relative+'/'+nameFor(seq)));
+        state=cursor.append(entry.value);lastFileHash=entry.digest;
+      }
+      if(state.head!==inspected.head || state.sequence!==inspected.sequence)fail('switch-journal.drift');
+      await audit();
+    }else {
+    await onLocation({relative,directory,status:'planned'});
+    const parent=resolveChild(lock.workspace,'.pipeline/journals');
+    try{await mkdir(parent);}catch(error){if(error.code!=='EEXIST')throw error;}
+    await inspectDirectory(parent);await mkdir(directory);
+    await onLocation({relative,directory,status:'created'});
+    await append('start',null);await audit();
+    await onLocation({relative,directory,status:'initialized'});
+    }
+    return Object.freeze({relative,directory,metrics:()=>({...metrics}),
+      intent:(phase,operationId)=>append('intent',{phase,operationId}),
+      outcome:(phase,operationId,status,observedHash)=>append('outcome',{phase,operationId,status,observedHash}),
+      phaseChecked:(phase,projectionDigest)=>append('phase-checked',{phase,projectionDigest})});
+  }catch(error){throw ioError(error);}
+}

package/src/operations/switch-journal.js

@@ -0,0 +1,71 @@
+import {composeSwitchPreview} from './switch.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {parse,fail} from '../contracts/parse.js';
+import {requestShape} from './ownership.js';
+
+// Pure event interpretation only. Hash assertions do not replace filesystem
+// readback, trusted preparation, approval, locking, or durable journal storage.
+export function inspectSwitchEvents(preview,previous,events) {
+  if(!Array.isArray(events))fail('switch-journal.count');
+  const cursor=createSwitchEventCursor(preview,previous);
+  for(const event of parse(JSON.stringify(events),'json'))cursor.append(event);
+  return cursor.inspect();
+}
+
+// Internal incremental cursor. A failed append poisons it; durable writers must
+// never continue a cursor whose disk append/readback failed either.
+export function createSwitchEventCursor(preview,previous) {
+  const copy=parse(JSON.stringify(preview),'json');
+  if(!Array.isArray(copy.phases) || copy.phases.length!==2)fail('switch-journal.preview');
+  const fresh=composeSwitchPreview({previous,removal:copy.phases[0].preview,replacement:copy.phases[1].preview});
+  if(contractDigest(copy)!==contractDigest(fresh))fail('switch-journal.preview');
+  const maxEvents=3+2*fresh.phases.reduce((n,p)=>n+p.preview.plan.targets.length,0);
+  const projected=new Map(fresh.observations.map(o=>[o.path,o.hash]));
+  const projectionDigest=()=>contractDigest([...projected].sort(([a],[b])=>a<b?-1:a>b?1:0).map(([path,hash])=>({path,hash})));
+  let head=null,phaseIndex=0,nextIndex=0,pending=null,stopped=null,started=false,sequence=0,broken=false;
+  function append(value) {
+    if(broken)fail('switch-journal.unavailable');
+    try {
+    if(sequence>=maxEvents)fail('switch-journal.count');
+    const event=parse(JSON.stringify(value),'json'),seq=sequence;
+    requestShape(event,['schemaVersion','seq','previous','previewDigest','kind','payload'],[],'switch-journal.event');
+    if(event.schemaVersion!==1 || event.seq!==seq || event.previous!==head || event.previewDigest!==fresh.digest)fail('switch-journal.binding');
+    if(seq===0) {
+      if(event.kind!=='start' || event.payload!==null)fail('switch-journal.sequence');
+      started=true;
+    }else {
+      if(stopped!==null || phaseIndex===2)fail('switch-journal.sequence');
+      const phase=fresh.phases[phaseIndex],targets=phase.preview.plan.targets,target=targets[nextIndex];
+      if(event.kind==='intent') {
+        requestShape(event.payload,['phase','operationId'],[],'switch-journal.payload');
+        if(pending!==null || !target || event.payload.phase!==phase.name || event.payload.operationId!==target.id)fail('switch-journal.sequence');
+        pending={phase:phase.name,operationId:target.id};
+      }else if(event.kind==='outcome') {
+        requestShape(event.payload,['phase','operationId','status','observedHash'],[],'switch-journal.payload');
+        const p=event.payload;
+        if(pending===null || p.phase!==pending.phase || p.operationId!==pending.operationId)fail('switch-journal.sequence');
+        if(!['completed','failed','uncertain'].includes(p.status) ||
+            (p.observedHash!==null && !/^sha256:[a-f0-9]{64}(?![\s\S])/.test(p.observedHash)) ||
+            (p.status==='completed' && p.observedHash!==target.desiredHash) ||
+            (p.status==='failed' && p.observedHash!==target.beforeHash))fail('switch-journal.outcome');
+        if(p.status==='completed')projected.set(target.path,target.desiredHash);
+        else stopped=p.status;
+        nextIndex++;pending=null;
+      }else if(event.kind==='phase-checked') {
+        requestShape(event.payload,['phase','projectionDigest'],[],'switch-journal.payload');
+        if(pending!==null || nextIndex!==targets.length || event.payload.phase!==phase.name ||
+            event.payload.projectionDigest!==projectionDigest())fail('switch-journal.phase-check');
+        phaseIndex++;nextIndex=0;
+      }else fail('switch-journal.sequence');
+    }
+    head=contractDigest(event);
+    sequence++;
+    return position();
+    }catch(error){broken=true;throw error;}
+  }
+  function position(){return {kind:'switch-event-inspection',previewDigest:fresh.digest,sequence,head,
+    status:!started?'not-started':stopped??(pending!==null?'uncertain':phaseIndex===2?'completed':'open'),
+    phase:phaseIndex===2?null:fresh.phases[phaseIndex].name,nextIndex,pending:pending?{...pending}:null,
+    verifiedPhases:phaseIndex,activationSupported:false,runtime:'not-run'};}
+  return Object.freeze({maxEvents,append,inspect:()=>({...position(),pending:pending?{...pending}:null,expectedProjectionDigest:projectionDigest()})});
+}

package/src/operations/switch-lifecycle.js

@@ -0,0 +1,72 @@
+import {prepareSwitch} from './switch-prepare.js';
+import {persistSwitchRecovery} from './switch-recovery-store.js';
+import {markSwitchPending} from './switch-pending.js';
+import {executeSwitchPhase} from './switch-execute.js';
+import {activateSwitch} from './switch-activate.js';
+import {validateSwitchRecord} from './switch-records.js';
+import {acquireWorkspaceLock} from './lock.js';
+import {inspectHistory} from './history.js';
+import {readState} from './state.js';
+import {requestShape} from './ownership.js';
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {ContractError,fail} from '../contracts/parse.js';
+
+function guard(input,registry,apply=false) {
+  requestShape(input,apply?['command','wrapper','prepared','approval']:['command','wrapper','manifestPath'],apply?[]:['network'],'switch-lifecycle.input');
+  if(input.command!=='switch')fail('switch-lifecycle.command');
+  requestShape(registry,['adapters','sharedAdapter'],[],'provider.interface');
+  return absoluteRoot(input.wrapper);
+}
+async function historyGuard(workspace) {
+  const history=await inspectHistory(workspace);
+  if(!history.complete || history.diagnostics.length)fail('switch-lifecycle.history');
+}
+export async function prepareSwitchLifecycle(input,registry) {
+  const wrapper=guard(input,registry);await historyGuard(wrapper);
+  const {command,...options}=input;return prepareSwitch({...options,wrapper},registry);
+}
+
+// One approved transaction, two checked phases. No resume, rollback, source
+// reacquisition, provider code loading or automatic history cleanup here.
+export async function applySwitchLifecycle(input,registry,{report=async()=>{}}={}) {
+  const workspace=guard(input,registry,true);
+  if(typeof report!=='function')fail('switch-lifecycle.reporter');
+  const result={command:'switch',workspace,status:'failed',journal:null,recovery:null,
+    completedPhases:[],error:null,lockRelease:'not-acquired',runtime:'not-run'};
+  const emit=async event=>{try{await report(structuredClone(event));}catch{fail('switch-lifecycle.report');}};
+  let lock;
+  try {
+    if(input.prepared?.preview?.workspace!==workspace)fail('switch-lifecycle.prepared-binding');
+    const previous=(await readState(resolveChild(workspace,'.pipeline/state.json'))).value;
+    const {prepared,approval}=validateSwitchRecord(input.prepared,input.approval,previous);
+    lock=await acquireWorkspaceLock(workspace);result.lockRelease='pending';await historyGuard(workspace);
+    const saved=await persistSwitchRecovery(lock,prepared,approval,registry,previous,{
+      onJournal:async location=>{
+        const runId=location.relative.split('/').at(-1);
+        result.journal={runId,path:location.directory,status:location.status};
+        result.recovery={path:resolveChild(workspace,'.pipeline/transactions/'+runId+'/recovery.json'),status:'not-created'};
+        await emit({kind:'journal-location',...result.journal,recovery:result.recovery});
+      },
+      boundary:async stage=>{
+        if(stage==='recovery-written') {
+          result.recovery.status='created-unverified';await emit({kind:'recovery-location',...result.recovery});
+        }
+      }
+    });
+    result.recovery={path:resolveChild(workspace,saved.recoveryPath),status:'verified',hash:saved.recoveryHash};
+    await emit({kind:'recovery-location',...result.recovery});
+    await markSwitchPending(lock,saved.recoveryPath,saved.recoveryHash,approval,registry);
+    for(const phase of ['remove-old','install-new']) {
+      await emit({kind:'phase-start',phase});
+      await executeSwitchPhase(lock,saved.recoveryPath,saved.recoveryHash,approval,phase);
+      result.completedPhases.push(phase);await emit({kind:'phase-completed',phase});
+    }
+    await activateSwitch(lock,saved.recoveryPath,saved.recoveryHash,approval);result.status='ready';
+  }catch(error){result.error=error instanceof ContractError?error.code:'switch-lifecycle.io';}
+  finally {
+    if(lock)try{await lock.release();result.lockRelease='released';}
+    catch(error){result.lockRelease='failed';result.releaseError=error instanceof ContractError?error.code:'lock.release';}
+  }
+  try{await emit({kind:'operation-result',...result});}catch{result.outputError='switch-lifecycle.report';}
+  return result;
+}

package/src/operations/switch-pending.js

@@ -0,0 +1,43 @@
+import {open,rename} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {readSwitchRecovery} from './switch-recovery-store.js';
+import {verifySwitchApproval} from './switch-preflight.js';
+import {assertLockHeld} from './lock.js';
+import {readState,observeTargets} from './state.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {validateState} from '../contracts/semantic.js';
+import {parse,fail,ContractError} from '../contracts/parse.js';
+import {sha256} from '../source/inventory.js';
+
+// Internal state transition only. The caller supplies genuine current approval.
+// No provider writes, phase execution, automatic retry or active-state promotion.
+export async function markSwitchPending(lock,recoveryPath,recoveryHash,approval,registry,{boundary=async()=>{}}={}) {
+  await assertLockHeld(lock);
+  const evidence=await readSwitchRecovery(lock.workspace,recoveryPath),record=evidence.record;
+  if(evidence.fileHash!==recoveryHash || evidence.journal.sequence!==1 || evidence.journal.status!=='open')fail('switch-pending.evidence');
+  await verifySwitchApproval(lock,record.prepared,approval,registry,record.previous);
+  // Bind this exact transaction, not just equal desired bytes or equal preview.
+  // The record digest includes its UUID journal identity.
+  const pending={...record.previous,status:'needs-reconciliation',pending:record.digest,runtime:'not-run'};
+  validateState(pending);
+  const bytes=Buffer.from(JSON.stringify(parse(JSON.stringify(pending),'json'))+'\n');
+  const relative='.pipeline/state.json',scratch='.pipeline/.switch-state-'+randomUUID()+'.tmp';
+  const filename=resolveChild(lock.workspace,relative),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:relative,stagedPath:scratch});
+    await verifySwitchApproval(lock,record.prepared,approval,registry,record.previous);
+    const fresh=await readSwitchRecovery(lock.workspace,recoveryPath);
+    if(fresh.fileHash!==recoveryHash || fresh.journal.sequence!==1 || fresh.journal.head!==evidence.journal.head)fail('switch-pending.evidence');
+    const [temp]=await observeTargets(lock.workspace,[scratch]);
+    if(temp.bytes===null || sha256(temp.bytes)!==sha256(bytes))fail('switch-pending.staging');
+    await assertLockHeld(lock);
+    if((await readState(filename)).digest!==record.prepared.stateFileHash)fail('switch-pending.state-drift');
+    await rename(staged,filename);
+    await boundary('renamed',{path:relative});
+    if((await readState(filename)).digest!==sha256(bytes))fail('switch-pending.readback');
+    return {status:'needs-reconciliation',pending:record.digest,stateFileHash:sha256(bytes),recoveryPath,applySupported:false,runtime:'not-run'};
+  }catch(error){throw error instanceof ContractError?error:new ContractError('switch-pending.io');}
+}