@6reduk/workspace-pipeline 0.1.0

package/src/operations/backup.js

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import { mkdir, open } from 'node:fs/promises';
+import { fail, ContractError } from '../contracts/parse.js';
+import { portablePath } from '../contracts/semantic.js';
+import { sha256, LIMITS, cap } from '../source/inventory.js';
+import { resolveChild, inspectDirectory } from '../workspace/paths.js';
+import { observeTargets, verifyPreparedSnapshot } from './state.js';
+import { assertLockHeld } from './lock.js';
+
+function backupPath(workspace, relative) {
+  portablePath(relative);
+  if (!relative.startsWith('.pipeline/backups/')) fail('backup.path');
+  return resolveChild(workspace,relative);
+}
+
+// Read-only exact byte verification; digest refers to the whole containing file,
+// not a JSON-field value. Field ownership hashes cannot substitute for this hash.
+export async function verifyBackup(workspace, relative, expectedHash) {
+  backupPath(workspace,relative);
+  if(typeof expectedHash!=='string' || !/^sha256:[a-f0-9]{64}$/.test(expectedHash))fail('backup.hash');
+  const [{bytes}]=await observeTargets(workspace,[relative]);
+  if(bytes===null)fail('backup.missing');
+  if(sha256(bytes)!==expectedHash)fail('backup.mismatch');
+  return {path:relative,hash:expectedHash,size:bytes.length};
+}
+
+// Internal primitive, not plan authorization. Coordinator must bind relative and
+// expectedHash to an approved preview and run full preflight before target writes.
+// Copies bytes; no hardlink/shared mutable source. Existing entries are preserved,
+// even when mismatching. A torn newly created backup is retained, never auto-repaired.
+export async function saveBackup(lock, relative, bytes, expectedHash) {
+  await assertLockHeld(lock);
+  const filename=backupPath(lock.workspace,relative);
+  if(!Buffer.isBuffer(bytes))fail('backup.bytes');
+  cap(bytes.length,LIMITS.blob,'backup.size');
+  bytes=Buffer.from(bytes);
+  if(sha256(bytes)!==expectedHash)fail('backup.hash');
+  try {
+    const [{bytes:existing}]=await observeTargets(lock.workspace,[relative]);
+    if(existing!==null) return {...await verifyBackup(lock.workspace,relative,expectedHash),created:false};
+    // Create one inspected parent at a time; never recursive mkdir through a link.
+    let parent=lock.workspace;
+    for(const part of path.relative(lock.workspace,path.dirname(filename)).split(path.sep)) {
+      parent=path.join(parent,part);await assertLockHeld(lock);
+      try{await mkdir(parent);}catch(error){if(error.code!=='EEXIST')throw error;}
+      await inspectDirectory(parent);
+    }
+    await assertLockHeld(lock);
+    let handle;
+    try{handle=await open(filename,'wx',0o600);}
+    catch(error){if(error.code==='EEXIST')fail('backup.conflict');throw error;}
+    try{await handle.writeFile(bytes);await handle.sync();}
+    finally{await handle.close();}
+    return {...await verifyBackup(lock.workspace,relative,expectedHash),created:true};
+  }catch(error){throw error instanceof ContractError?error:new ContractError('backup.io');}
+}
+
+// Install verified file bytes, never copy a tree recursively or link source files.
+// No active-state change. A partially populated directory stays unusable until
+// verification succeeds; mismatching existing directories are never repaired here.
+export async function copySnapshot(lock, prepared) {
+  await assertLockHeld(lock);
+  const verified=await verifyPreparedSnapshot(prepared);
+  const relative='.pipeline/snapshots/'+verified.digest.slice(7);
+  const destination=resolveChild(lock.workspace,relative);
+  const expected={snapshotPath:destination,manifest:verified.manifest,digest:verified.digest,inventoryDigest:verified.inventoryDigest};
+  // Validate the complete resolved path budget before creating snapshot metadata.
+  for(const name of verified.files.keys())resolveChild(lock.workspace,relative+'/'+name);
+  try {
+    if((await inspectDirectory(destination)).exists) {
+      await verifyPreparedSnapshot(expected);
+      return {path:relative,digest:verified.digest,created:false};
+    }
+    const parent=resolveChild(lock.workspace,'.pipeline/snapshots');
+    await assertLockHeld(lock);
+    try{await mkdir(parent);}catch(error){if(error.code!=='EEXIST')throw error;}
+    await inspectDirectory(parent);
+    try{await mkdir(destination);}catch(error){if(error.code==='EEXIST')fail('snapshot.conflict');throw error;}
+    for(const [name,bytes] of verified.files) {
+      await assertLockHeld(lock);await inspectDirectory(destination);
+      const filename=resolveChild(lock.workspace,relative+'/'+name);
+      let directory=destination;
+      for(const segment of name.split('/').slice(0,-1)) {
+        directory=path.join(directory,segment);
+        try{await mkdir(directory);}catch(error){if(error.code!=='EEXIST')throw error;}
+        await inspectDirectory(directory);
+      }
+      const handle=await open(filename,'wx',0o600);
+      try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+    }
+    await verifyPreparedSnapshot(expected);
+    return {path:relative,digest:verified.digest,created:true};
+  }catch(error){throw error instanceof ContractError?error:new ContractError('snapshot.copy');}
+}

package/src/operations/bootstrap-lock.js

@@ -0,0 +1,87 @@
+import path from 'node:path';
+import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { lstat,mkdir,open,readdir,unlink,rmdir } from 'node:fs/promises';
+import { fail,ContractError } from '../contracts/parse.js';
+import { sha256 } from '../source/inventory.js';
+import { absoluteRoot,inspectDirectory,pathBudget } from '../workspace/paths.js';
+import { readRecord } from './state.js';
+
+const held=new WeakMap();
+const identity=s=>String(s.dev)+':'+String(s.ino);
+export function bootstrapLockDirectory(workspace) {
+  workspace=absoluteRoot(workspace);pathBudget(workspace);
+  if(path.dirname(workspace)===workspace)fail('bootstrap-lock.root');
+  const directory=path.join(path.dirname(workspace),'.wpc-bootstrap-'+sha256(workspace.toLowerCase()).slice(7));
+  pathBudget(directory);return directory;
+}
+export async function assertNoBootstrapRecovery(workspace) {
+  for(const suffix of ['.recovery','.recovery-resume']) {
+    try {await lstat(bootstrapLockDirectory(workspace)+suffix);}
+    catch(e){if(e.code==='ENOENT')continue;throw e;}
+    fail('bootstrap-lock.recovery-pending');
+  }
+}
+export async function assertBootstrapLockHeld(lock) {
+  const check=lock && held.get(lock);
+  if(!check)fail('bootstrap-lock.capability');
+  await check();
+}
+
+// Init/adopt exclusion before wrapper exists. Requires an existing direct parent;
+// ancestor creation must have its own approved bootstrap sequence, never recursive
+// mkdir here. Keep held through handoff to the ordinary S5 workspace lock.
+export async function acquireBootstrapLock(workspace,{onLocation=async()=>{},ioBoundary=async()=>{}}={}) {
+  workspace=absoluteRoot(workspace);pathBudget(workspace);
+  const parent=path.dirname(workspace);
+  if(parent===workspace)fail('bootstrap-lock.root');
+  await inspectDirectory(workspace);
+  if(!(await inspectDirectory(parent)).exists)fail('bootstrap-lock.parent-missing');
+  const parentId=identity(await lstat(parent,{bigint:true}));
+  const directory=bootstrapLockDirectory(workspace);
+  pathBudget(directory);
+  const ownerFile=path.join(directory,'owner.json');
+  let created=false;
+  try {
+    await assertNoBootstrapRecovery(workspace);
+    await onLocation({workspace,directory,status:'planned'});
+    await inspectDirectory(parent);
+    if(identity(await lstat(parent,{bigint:true}))!==parentId)fail('bootstrap-lock.parent-drift');
+    try {await mkdir(directory,{mode:0o700});created=true;}
+    catch(error){if(error.code==='EEXIST')fail('bootstrap-lock.busy');throw error;}
+    await ioBoundary('directory-created',{directory});
+    await inspectDirectory(directory);
+    const directoryId=identity(await lstat(directory,{bigint:true}));
+    const owner={schemaVersion:1,workspace,token:randomUUID(),pid:process.pid,host:hostname(),createdAt:new Date().toISOString()};
+    const bytes=Buffer.from(JSON.stringify(owner)+'\n'),digest=sha256(bytes);
+    const handle=await open(ownerFile,'wx',0o600);
+    try {await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+    if((await readRecord(ownerFile)).digest!==digest)fail('bootstrap-lock.readback');
+    await assertNoBootstrapRecovery(workspace);
+    let released=false;
+    const check=async()=>{
+      if(released)fail('bootstrap-lock.released');
+      await inspectDirectory(directory);
+      if(identity(await lstat(parent,{bigint:true}))!==parentId || identity(await lstat(directory,{bigint:true}))!==directoryId)
+        fail('bootstrap-lock.identity');
+      if((await readRecord(ownerFile)).digest!==digest)fail('bootstrap-lock.owner-changed');
+    };
+    const lock=Object.freeze({workspace,directory,token:owner.token,
+      async release() {
+        try {
+          await check();
+          const names=await readdir(directory);
+          if(names.length!==1 || names[0]!=='owner.json')fail('bootstrap-lock.foreign-entry');
+          await unlink(ownerFile);await rmdir(directory);released=true;
+        }catch(error){throw error instanceof ContractError?error:new ContractError('bootstrap-lock.release-failed');}
+      }});
+    held.set(lock,check);
+    await onLocation({workspace,directory,status:'held'});
+    return lock;
+  }catch(cause){
+    const error=cause instanceof ContractError?cause:new ContractError('bootstrap-lock.io');
+    // No rollback of an incomplete/unknown owner record. Location enables review.
+    if(created)error.bootstrapDirectory=directory;
+    throw error;
+  }
+}

package/src/operations/bootstrap-owner-retirement.js

@@ -0,0 +1,121 @@
+import path from 'node:path';
+import {hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+import {lstat,mkdir,open,rename,readdir} from 'node:fs/promises';
+import {fail,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {absoluteRoot,inspectDirectory,pathBudget} from '../workspace/paths.js';
+import {inventoryRepository} from '../workspace/repository-inventory.js';
+import {readRecord} from './state.js';
+import {bootstrapLockDirectory,assertNoBootstrapRecovery} from './bootstrap-lock.js';
+import {withRecoveryLease,assertRecoveryLeaseHeld} from './recovery-lease.js';
+import {sha256} from '../source/inventory.js';
+
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const equal=(a,b)=>contractDigest(a)===contractDigest(b);
+const id=s=>({dev:String(s.dev),ino:String(s.ino)});
+function stopped(owner){
+  if(owner.host!==hostname())return false;
+  try{process.kill(owner.pid,0);return false;}catch(e){return e.code==='ESRCH';}
+}
+function historyPath(wrapper,attempt){
+  if(!uuid.test(attempt??''))fail('bootstrap-retire.attempt');
+  const result=path.join(path.dirname(wrapper),'.wpc-bootstrap-abandoned-'+attempt);pathBudget(result);return result;
+}
+function ownerBinding(owner,wrapper){
+  if(!owner || Object.keys(owner).sort().join(',')!=='createdAt,host,pid,schemaVersion,token,workspace' ||
+    owner.schemaVersion!==1 || owner.workspace!==wrapper || !uuid.test(owner.token??'') ||
+    !Number.isSafeInteger(owner.pid) || owner.pid<=0 || typeof owner.host!=='string' ||
+    typeof owner.createdAt!=='string' || !Number.isFinite(Date.parse(owner.createdAt)))fail('bootstrap-retire.owner');
+}
+async function absent(filename){try{await lstat(filename);}catch(e){if(e.code==='ENOENT')return;throw e;}fail('bootstrap-retire.destination-exists');}
+
+// Only an absent wrapper and complete, stopped owner-only lock. Empty/torn owner
+// records cannot prove liveness and remain blocked. Never infer historical effects.
+export async function inspectBootstrapOwner(wrapper){
+  wrapper=absoluteRoot(wrapper);
+  const observe=async()=>{
+    await assertNoBootstrapRecovery(wrapper);
+    if((await inspectDirectory(wrapper)).exists)fail('bootstrap-retire.wrapper-exists');
+    const parent=path.dirname(wrapper);if(!(await inspectDirectory(parent)).exists)fail('bootstrap-retire.parent-missing');
+    const directory=bootstrapLockDirectory(wrapper);
+    const inventory=await inventoryRepository(directory,{entries:4,bytes:MAX_INPUT_BYTES,depth:1});
+    if(inventory.entries.map(e=>e.path).sort().join(',')!=='.,owner.json')fail('bootstrap-retire.not-owner-only');
+    const record=await readRecord(path.join(directory,'owner.json'));ownerBinding(record.value,wrapper);
+    await assertNoBootstrapRecovery(wrapper);
+    return {kind:'bootstrap-owner-observation',wrapper,directory,inventory,ownerDigest:record.digest,
+      parentIdentity:id(await lstat(parent,{bigint:true})),ownerStopped:stopped(record.value),
+      wrapperAbsentAtCheck:true,executionAuthorized:false};
+  };
+  const first=await observe();if(!equal(first,await observe()))fail('bootstrap-retire.drift');
+  return {...first,digest:contractDigest(first)};
+}
+export async function prepareBootstrapOwnerRetirement(wrapper){
+  const observation=await inspectBootstrapOwner(wrapper),attempt=randomUUID();
+  const body={schemaVersion:1,kind:'bootstrap-owner-retirement-preview',wrapper:observation.wrapper,attempt,
+    history:historyPath(observation.wrapper,attempt),observation,status:observation.ownerStopped?'review-only':'blocked',
+    executionAuthorized:false,pipelineActivated:false};
+  return {...body,digest:contractDigest(body)};
+}
+function validatePreview(wrapper,preview){
+  const {digest,...body}=preview??{};
+  if(body.kind!=='bootstrap-owner-retirement-preview' || body.schemaVersion!==1 || body.wrapper!==wrapper ||
+    body.status!=='review-only' || body.executionAuthorized!==false || body.pipelineActivated!==false ||
+    contractDigest(body)!==digest || body.history!==historyPath(wrapper,body.attempt))fail('bootstrap-retire.approval');
+  const {digest:od,...ob}=body.observation??{};
+  if(contractDigest(ob)!==od || ob.wrapper!==wrapper || ob.directory!==bootstrapLockDirectory(wrapper) ||
+    ob.inventory?.root!==ob.directory ||
+    ob.kind!=='bootstrap-owner-observation' || ob.ownerStopped!==true || ob.wrapperAbsentAtCheck!==true ||
+    ob.executionAuthorized!==false)fail('bootstrap-retire.approval');
+}
+export async function verifyBootstrapOwnerRetirement(wrapper,history){
+  wrapper=absoluteRoot(wrapper);history=absoluteRoot(history);
+  const attempt=path.basename(history).replace(/^\.wpc-bootstrap-abandoned-/,'');
+  if(history!==historyPath(wrapper,attempt))fail('bootstrap-retire.history-path');
+  await inspectDirectory(history);
+  if((await readdir(history)).sort().join(',')!=='lock,request.json')fail('bootstrap-retire.history-incomplete');
+  const request=await readRecord(path.join(history,'request.json')),v=request.value;
+  if(!equal(v,{schemaVersion:1,kind:'bootstrap-owner-retirement-request',preview:v.preview}))fail('bootstrap-retire.request');
+  validatePreview(wrapper,v.preview);if(v.preview.history!==history)fail('bootstrap-retire.history-binding');
+  const saved=await inventoryRepository(path.join(history,'lock'),{entries:4,bytes:MAX_INPUT_BYTES,depth:1});
+  const projection=inv=>inv.entries.map(e=>({path:e.path,type:e.type,dev:e.identity.dev,ino:e.identity.ino,
+    mode:e.identity.mode,sha256:e.sha256??null}));
+  const archivedOwner=await readRecord(path.join(history,'lock','owner.json'));ownerBinding(archivedOwner.value,wrapper);
+  if(!equal(projection(saved),projection(v.preview.observation.inventory)) ||
+    archivedOwner.digest!==v.preview.observation.ownerDigest)
+    fail('bootstrap-retire.history-drift');
+  if((await readRecord(request.path)).digest!==request.digest)fail('bootstrap-retire.history-drift');
+  return {status:'bootstrap-owner-attempt-archived',history,requestDigest:request.digest,
+    repositoryEffectsPerformed:false,pipelineActivated:false,wrapperStateNotVerified:true};
+}
+export async function applyBootstrapOwnerRetirement(wrapper,preview,{ioBoundary=async()=>{}}={}){
+  wrapper=absoluteRoot(wrapper);validatePreview(wrapper,preview);
+  return withRecoveryLease(wrapper,async lease=>{
+    const check=async()=>{
+      assertRecoveryLeaseHeld(lease);
+      if(!equal(await inspectBootstrapOwner(wrapper),preview.observation))fail('bootstrap-retire.stale');
+    };
+    await check();await absent(preview.history);await mkdir(preview.history,{mode:0o700});
+    const historyIdentity=id(await lstat(preview.history,{bigint:true}));
+    await ioBoundary('bootstrap-retirement-history-created',{history:preview.history});
+    await inspectDirectory(preview.history);
+    if(!equal(id(await lstat(preview.history,{bigint:true})),historyIdentity) || (await readdir(preview.history)).length)
+      fail('bootstrap-retire.history-drift');
+    const value={schemaVersion:1,kind:'bootstrap-owner-retirement-request',preview};
+    const bytes=Buffer.from(JSON.stringify(value)+'\n');if(bytes.length>MAX_INPUT_BYTES)fail('bootstrap-retire.input-size');
+    const file=path.join(preview.history,'request.json'),h=await open(file,'wx',0o600);
+    try{await h.writeFile(bytes);await h.sync();}finally{await h.close();}
+    if((await readRecord(file)).digest!==sha256(bytes))fail('bootstrap-retire.readback');
+    await ioBoundary('bootstrap-retirement-request-retained',{history:preview.history});
+    await check();await inspectDirectory(preview.history);
+    if(!equal(id(await lstat(preview.history,{bigint:true})),historyIdentity) ||
+      (await readdir(preview.history)).join(',')!=='request.json' || (await readRecord(file)).digest!==sha256(bytes))
+      fail('bootstrap-retire.history-drift');
+    // Single handoff: the original lock blocks normal writers until this rename.
+    // All history inputs already exist; no guard needs later unlocking.
+    assertRecoveryLeaseHeld(lease);await rename(preview.observation.directory,path.join(preview.history,'lock'));
+    await ioBoundary('bootstrap-retirement-lock-archived',{history:preview.history});
+    const result=await verifyBootstrapOwnerRetirement(wrapper,preview.history);
+    assertRecoveryLeaseHeld(lease);return result;
+  });
+}

package/src/operations/bundle-update.js

@@ -0,0 +1,54 @@
+import { fail } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { sha256 } from '../source/inventory.js';
+import { readConfigField, reconcileConfigFields } from './config-fields.js';
+
+// Only a member removed from a still-selected bundle may retire during update.
+// Standalone removal and removal of an entire bundle remain explicit operations.
+export function retiredBundleOwnership(previous, selection) {
+  const owners=new Set();
+  for(const [id,bundle] of Object.entries(previous?.active?.bundles??{})) {
+    if(!selection.bundles?.[id])continue;
+    for(const member of bundle.providers) if(!selection.providers.includes(member))owners.add(member);
+  }
+  return (previous?.active?.owned??[]).filter(o=>owners.has(o.owner));
+}
+export function planObservationPaths(requests, previous, selection) {
+  const retired=retiredBundleOwnership(previous,selection);
+  return [...new Set([...requests.map(r=>r.path),...retired.flatMap(o=>[o.path,...(o.backup?[o.backup]:[])])])].sort();
+}
+export function restoreRetired(entries, observations) {
+  const outputs=[];
+  const bytesAt=name=>{
+    if(!observations.has(name) || !Buffer.isBuffer(observations.get(name)))fail('bundle.retirement-missing');
+    return observations.get(name);
+  };
+  for(const name of [...new Set(entries.map(o=>o.path))].sort()) {
+    const owned=entries.filter(o=>o.path===name),before=bytesAt(name);
+    let bytes=null,fields=[],action;
+    if(owned[0].kind==='file') {
+      if(sha256(before)!==owned[0].managedHash)fail('ownership.drift');
+      if(owned[0].beforeHash!==null) {
+        bytes=bytesAt(owned[0].backup);
+        if(sha256(bytes)!==owned[0].beforeHash)fail('bundle.backup-mismatch');
+      }
+      action=bytes===null?'delete':'replace';
+    } else {
+      const requests=owned.map(o=>{
+        const request={pointer:o.pointer,present:o.beforeHash!==null,managedHash:o.managedHash};
+        if(request.present) {
+          const found=readConfigField(name,bytesAt(o.backup),o.pointer);
+          if(!found.present || contractDigest(found.value)!==o.beforeHash)fail('bundle.backup-mismatch');
+          request.value=found.value;
+        }
+        return request;
+      });
+      const result=reconcileConfigFields(name,before,requests);bytes=result.bytes;
+      fields=result.decisions.map(f=>({pointer:f.pointer,beforeHash:f.currentHash,desiredHash:f.desiredHash}));
+      action='edit-fields';
+    }
+    const beforeHash=sha256(before),desiredHash=bytes===null?null:sha256(bytes);
+    outputs.push({path:name,owner:owned[0].owner,action,beforeHash,desiredHash,fields,bytes});
+  }
+  return outputs;
+}

package/src/operations/config-fields.js

@@ -0,0 +1,24 @@
+import {parse,fail} from '../contracts/parse.js';
+import {utf8} from '../source/inventory.js';
+import {reconcileFields} from './ownership.js';
+import {readTOMLField,reconcileTOMLFields} from './toml-fields.js';
+
+// The codec is selected by a trusted exact destination, not source-provided code
+// or guessed bytes. Historical JSON field paths retain their existing format.
+export function readConfigField(name,bytes,pointer) {
+  if(['.codex/config.toml','.grok/config.toml'].includes(name))return readTOMLField(bytes,pointer);
+  if(bytes===null)return {present:false};
+  let node=parse(utf8(bytes),'json');
+  for(const part of pointer.slice(1).split('/').map(p=>p.replace(/~1/g,'/').replace(/~0/g,'~'))) {
+    if(node===null || typeof node!=='object' || Array.isArray(node))fail('ownership.ancestor');
+    if(!Object.hasOwn(node,part))return {present:false};
+    node=node[part];
+  }
+  return {present:true,value:node};
+}
+
+export function reconcileConfigFields(name,bytes,requests) {
+  if(['.codex/config.toml','.grok/config.toml'].includes(name))return reconcileTOMLFields(bytes,requests);
+  const result=reconcileFields(bytes===null?{}:parse(utf8(bytes),'json'),requests);
+  return {decisions:result.decisions,bytes:Buffer.from(JSON.stringify(result.value,null,2)+'\n')};
+}

package/src/operations/continuation-lifecycle.js

@@ -0,0 +1,77 @@
+import {prepareContinuation,validateContinuationRecord} from './reconciliation.js';
+import {applyContinuation} from './apply.js';
+import {prepareSwitchContinuation,verifySwitchContinuationApproval} from './switch-continuation.js';
+import {persistSwitchContinuationRecovery} from './switch-continuation-recovery.js';
+import {markSwitchContinuationPending} from './switch-continuation-pending.js';
+import {executeSwitchContinuationPhase,activateSwitchContinuation} from './switch-continuation-runtime.js';
+import {readRecord} from './state.js';
+import {acquireWorkspaceLock} from './lock.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','recoveryPath'],[],'continuation.input');
+  if(input.command!=='continue')fail('continuation.command');
+  requestShape(registry,['adapters','sharedAdapter'],[],'provider.interface');
+  return absoluteRoot(input.wrapper);
+}
+export async function prepareContinuationLifecycle(input,registry) {
+  const workspace=guard(input,registry);
+  if(typeof input.recoveryPath!=='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])/.test(input.recoveryPath))fail('recovery.path');
+  const record=await readRecord(resolveChild(workspace,input.recoveryPath));
+  return ['switch-recovery','switch-continuation-recovery'].includes(record.value.kind)?
+    prepareSwitchContinuation(workspace,input.recoveryPath):prepareContinuation(workspace,input.recoveryPath);
+}
+
+// Fresh exact approval, fresh journal, preserved ancestry. Native readers validate
+// pending state/lineage; the ordinary clean-history guard would reject that state.
+export async function applyContinuationLifecycle(input,registry,{report=async()=>{}}={}) {
+  const workspace=guard(input,registry,true);
+  if(typeof report!=='function')fail('continuation.reporter');
+  const result={command:'continue',workspace,status:'failed',journal:null,recovery:null,error:null,lockRelease:'not-acquired',runtime:'not-run'};
+  const emit=async event=>{try{await report(structuredClone(event));}catch{fail('continuation.report');}};
+  const 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});
+  };
+  let lock;
+  try {
+    const switching=input.prepared?.kind==='switch-continuation-preview';
+    const prepared=switching?structuredClone(input.prepared):validateContinuationRecord(input.prepared,input.approval);
+    if((switching?prepared.workspace:prepared.evidence?.workspace)!==workspace)fail('continuation.prepared-binding');
+    lock=await acquireWorkspaceLock(workspace);result.lockRelease='pending';
+    if(switching) {
+      const approval={decision:input.approval.decision,previewDigest:input.approval.preparedDigest};
+      requestShape(input.approval,['decision','preparedDigest'],[],'continuation.approval');
+      await verifySwitchContinuationApproval(lock,prepared,approval);
+      const saved=await persistSwitchContinuationRecovery(lock,prepared,approval,{onJournal,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 markSwitchContinuationPending(lock,saved.recoveryPath,saved.recoveryHash,approval);
+      for(const {phase} of prepared.remaining) {
+        await emit({kind:'phase-start',phase});
+        await executeSwitchContinuationPhase(lock,saved.recoveryPath,saved.recoveryHash,approval,phase);
+        await emit({kind:'phase-completed',phase});
+      }
+      await activateSwitchContinuation(lock,saved.recoveryPath,saved.recoveryHash,approval);result.status='ready';
+    } else {
+      const applied=await applyContinuation(lock,prepared,input.approval,{onJournal,ioBoundary:async detail=>{
+        if(detail.purpose==='recovery' && ['opened','readback'].includes(detail.phase)) {
+          result.recovery.status=detail.phase==='opened'?'created-unverified':'verified';
+          await emit({kind:'recovery-location',...result.recovery});
+        }
+      }});result.status=applied.status;
+    }
+  }catch(error){result.error=error instanceof ContractError?error.code:'continuation.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='continuation.report';}
+  return result;
+}