@6reduk/workspace-pipeline 0.1.0

package/src/operations/plan.js

@@ -0,0 +1,278 @@
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { fail, parse, ContractError } from '../contracts/parse.js';
+import { validateOperation, validateState, contractDigest, portablePath } from '../contracts/semantic.js';
+import { sha256, LIMITS, cap } from '../source/inventory.js';
+import { planLayout } from '../workspace/resolve.js';
+import { resolveChild, absoluteRoot, inspectDirectory } from '../workspace/paths.js';
+import { overlaps } from '../workspace/reserved.js';
+import { reconcileOwnership, requestShape } from './ownership.js';
+import {reconcileConfigFields} from './config-fields.js';
+import { acquire } from '../source/git.js';
+import { readState, resolveOrigin, resolveApprovedRebind, verifyPreparedSnapshot, observeTargets } from './state.js';
+import { commonEntryPath, commonEntryText, needsCommonEntry } from '../providers/common-entry.js';
+import {planObservationPaths,retiredBundleOwnership,restoreRetired} from './bundle-update.js';
+
+// Trusted CLI destination policy, not a claim about tested harness discovery.
+const roots = {shared:['AGENTS.md','CLAUDE.md'],codex:['.codex/','.agents/skills/'],
+  claude:['.claude/','CLAUDE.md','CLAUDE.local.md','.mcp.json'],kimi:['.kimi-code/'],grok:['.grok/']};
+
+export function assertRequestScope(request, providers) {
+  assertRequestShape(request);
+  const {path:name,owner,kind}=request;
+  portablePath(name);
+  if (owner==='shared' && name===commonEntryPath &&
+      (kind!=='file' || !needsCommonEntry(providers))) fail('plan.scope');
+  if (!['file','json-fields','toml-fields'].includes(kind) || !(owner==='shared' || providers.includes(owner)) ||
+      !roots[owner]?.some(root=>root.endsWith('/') ? name.startsWith(root) : name===root)) fail('plan.scope');
+  // Project MCP config is shared with user-defined servers. Own only individual
+  // named server entries, never the complete file or mcpServers parent object.
+  if(['.mcp.json','.kimi-code/mcp.json'].includes(name) && (kind!=='json-fields' || request.fields.some(field=>
+      !/^\/mcpServers\/[a-z][a-z0-9_-]{0,99}$/.test(field.pointer)))) fail('plan.scope');
+  if(name==='.grok/config.toml' && (kind!=='toml-fields' || request.fields.some(field=>
+      !/^\/mcp_servers\/[a-z][a-z0-9_-]{0,99}$/.test(field.pointer))))fail('plan.scope');
+  if(kind==='toml-fields' && !((owner==='codex' && name==='.codex/config.toml') ||
+      (owner==='grok' && name==='.grok/config.toml')))fail('plan.scope');
+  if(kind==='json-fields' && ['.codex/config.toml','.grok/config.toml'].includes(name))fail('plan.scope');
+}
+
+function assertRequestShape(request) {
+  requestShape(request, ['path','owner','kind'], ['bytes','takeover','fields'], 'plan.request');
+  if (request.kind === 'file') requestShape(request, ['path','owner','kind','bytes'], ['takeover'], 'plan.request');
+  else if (['json-fields','toml-fields'].includes(request.kind)) {
+    requestShape(request, ['path','owner','kind','fields'], [], 'plan.request');
+    if (!Array.isArray(request.fields) || !request.fields.length) fail('plan.fields');
+    for (const field of request.fields) requestShape(field, ['pointer','present'], ['value','takeover'], 'plan.fields');
+  }
+}
+
+// Source/setup/update preparation. Registry functions are trusted CLI code, never
+// loaded from the source. Temporary acquisition must remain outside workspace.
+// No harness/MCP launch, config write, trust grant or apply approval happens here.
+export async function preparePlan({wrapper,manifestPath,adapters,sharedAdapter,network=false,tempRoot=tmpdir(),rebind}) {
+  wrapper=absoluteRoot(wrapper);
+  await inspectDirectory(wrapper);
+  const temporary=(await inspectDirectory(absoluteRoot(tempRoot))).path;
+  const rel=path.relative(wrapper,temporary);
+  if(!rel || (!rel.startsWith('..'+path.sep) && rel!=='..' && !path.isAbsolute(rel))) fail('plan.preparation-location');
+  if(!adapters || typeof adapters!=='object' || Array.isArray(adapters))fail('provider.interface');
+  const statePath=resolveChild(wrapper,'.pipeline/state.json');
+  async function currentState() {
+    try{return await readState(statePath);}catch(error){if(error.code==='record.missing')return null;throw error;}
+  }
+  const before=await currentState(), previous=before?.value ?? null;
+  if(previous!==null && previous.pending!==null) fail('state.pending');
+  const options={wrapper,previous,manifestPath,command:previous?.active?'update':'setup'};
+  const rebindOptions=()=>({...options,proposal:rebind?.proposal,approval:rebind?.approval});
+  const origin=rebind ? await resolveApprovedRebind(rebindOptions()) : await resolveOrigin(options);
+  const acquired=await acquire(origin.manifest.pipeline,{manifestBase:origin.origin.base,tempRoot:temporary,network});
+  if(acquired.resolvedSource!==origin.origin.resolvedSource) fail('source-rebind-required');
+  const verified=await verifyPreparedSnapshot(acquired);
+  const layout=planLayout(verified.manifest,origin.manifest,wrapper,{adapters});
+  if(!sharedAdapter || typeof sharedAdapter.plan!=='function') fail('plan.shared-adapter');
+  const snapshot={source:structuredClone(acquired.source),commit:acquired.commit,path:'.pipeline/snapshots/'+acquired.digest.slice(7),
+    digest:acquired.digest,inventoryDigest:acquired.inventoryDigest,origin:structuredClone(origin.origin)};
+  const requests=[];
+  const context=()=>({pipeline:structuredClone(verified.manifest),workspace:structuredClone(origin.manifest),
+    layout:structuredClone(layout),snapshot:structuredClone(snapshot),
+    files:new Map([...verified.files].map(([name,bytes])=>[name,Buffer.from(bytes)]))});
+  for(const [owner,adapter] of [['shared',sharedAdapter],...layout.providers.map(id=>[id,adapters[id]])]) {
+    if(owner!=='shared') {
+      const validation=await adapter.validate(context());
+      if(validation?.valid===false) fail('provider.validation');
+    }
+    const batch=await adapter.plan(context());
+    if(!Array.isArray(batch)) fail('plan.adapter-output');
+    for(const request of batch) {
+      assertRequestShape(request);
+      if(request.owner!==owner) fail('plan.adapter-owner');
+      assertRequestScope(request,layout.providers);requests.push(request);
+    }
+    cap(requests.length,LIMITS.files,'plan.count');
+  }
+  planLayout(verified.manifest,origin.manifest,wrapper,{adapters,managedPaths:requests.map(r=>r.path)});
+  const observations=await observeTargets(wrapper,planObservationPaths(requests,previous,layout));
+  const preview=composePlan({pipeline:verified.manifest,workspace:origin.manifest,wrapper,previous,snapshot,adapters,requests,observations});
+  const after=await currentState();
+  if((after?.digest ?? null)!==(before?.digest ?? null)) fail('plan.state-drift');
+  const finalOrigin=rebind ? await resolveApprovedRebind(rebindOptions()) : await resolveOrigin(options);
+  if(contractDigest(finalOrigin)!==contractDigest(origin)) fail('plan.origin-drift');
+  const body={kind:'prepared-plan',preview,stateFileHash:before?.digest ?? null,
+    rebind:origin.rebind ?? null,preparation:{objects:acquired.preparation,snapshot:acquired.snapshotPath},runtime:'not-run'};
+  const prepared={...body,digest:contractDigest(body)};
+  assertRecoveryBudget(prepared,previous);
+  return prepared;
+}
+
+// Conservative bound for the exact inline recovery format used by S5. Fixed-size
+// hashes and false (longer than true) bound backup descriptors without reading or
+// creating backup files. No approval is granted by this sizing-only placeholder.
+export function assertRecoveryBudget(prepared,previous=null) {
+  requestShape(prepared,['kind','preview','stateFileHash','rebind','preparation','runtime','digest'],[],'plan.recovery-input');
+  requestShape(prepared.preview,['schemaVersion','plan','observations','outputs','digest'],[],'plan.recovery-input');
+  validateOperation(prepared.preview.plan,previous);
+  if(prepared.preview.plan.kind!=='plan' || !prepared.preview.plan.desired)fail('plan.recovery-input');
+  const plan=prepared.preview.plan,paths=new Set(plan.desired.owned.map(o=>o.backup).filter(p=>p!==null));
+  const hash='sha256:'+'0'.repeat(64);
+  const backups=[...paths].map(path=>({path,hash,existing:false}));
+  const pending={schemaVersion:1,workspace:plan.workspace,status:'needs-reconciliation',runtime:'not-run',
+    active:previous?.active??null,pending:contractDigest(plan),...(previous?.activation?{activation:previous.activation}:{})};
+  const activation={recovery:'.pipeline/transactions/00000000-0000-0000-0000-000000000000/recovery.json',
+    recoveryHash:hash,journalHead:{sequence:20001,hash}};
+  try {
+    for(const value of [{schemaVersion:1,prepared,approval:{decision:'approve',preparedDigest:prepared.digest},previous,backups},
+      pending,{...pending,status:'ready',active:plan.desired,pending:null,activation}])parse(JSON.stringify(value)+'\n','json');
+  }catch(error){
+    if(error instanceof ContractError && ['parse.size','parse.complexity'].includes(error.code))fail('plan.recovery-budget');
+    throw error;
+  }
+}
+
+// Pure setup/update composition. Requests must come from trusted CLI adapters,
+// never executable source-package code. Source verification and filesystem
+// observations must be coordinated by the outer planner before any apply.
+export function composePlan({pipeline, workspace, wrapper, previous = null, snapshot, adapters, requests, observations}) {
+  if (previous !== null) {
+    validateState(previous);
+    if (previous.pending !== null || previous.workspace !== wrapper) fail('plan.previous');
+    if (previous.active && previous.active.pipelineId !== pipeline.id) fail('plan.switch-required');
+  }
+  if (!Array.isArray(requests) || !Array.isArray(observations)) fail('plan.input');
+  cap(requests.length,LIMITS.files,'plan.count');
+  for (const request of requests) assertRequestShape(request);
+  const ordered = [...requests].sort((a,b)=>a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const layout = planLayout(pipeline,workspace,wrapper,{adapters,managedPaths:ordered.map(r=>r.path)});
+  const observed = new Map(), used = new Set(), owned = [], targets = [], outputs = [];
+  for (const observation of observations) {
+    portablePath(observation.path);
+    if (observed.has(observation.path)) fail('preview.duplicate');
+    observed.set(observation.path,observation.bytes);
+  }
+  for (const request of ordered) {
+    const {path: name,owner,kind} = request;
+    resolveChild(layout.wrapper,name);
+    assertRequestScope(request, layout.providers);
+    if ([...used].some(prior=>overlaps(prior,name))) fail('plan.overlap');
+    used.add(name);
+    if (!observed.has(name)) fail('preview.before');
+    const bytes = observed.get(name);
+    if (bytes!==null && !Buffer.isBuffer(bytes)) fail('preview.bytes');
+    const beforeHash = bytes===null ? null : sha256(bytes);
+    const prior = previous?.active?.owned.filter(r=>r.path.toLowerCase()===name.toLowerCase()) ?? [];
+    const entryMigration = name===commonEntryPath && owner==='shared' && kind==='file' &&
+      prior.length===1 && prior[0].path===name && prior[0].owner==='claude' && prior[0].kind==='file' &&
+      previous.active.adapterVersions.claude==='1' && layout.providers.includes('claude') &&
+      adapters.claude?.version==='2' && Buffer.isBuffer(request.bytes) &&
+      (layout.bundles || request.bytes.equals(Buffer.from(commonEntryText)));
+    if (prior.some(r=>r.path!==name || (!entryMigration && r.owner!==owner) || r.kind!==(kind==='file'?'file':'field'))) fail('plan.ownership-kind');
+    const retain = (old,pointer,currentHash,managedHash) => {
+      if (old) return {...structuredClone(old),owner,managedHash};
+      return {path:name,kind:pointer===null?'file':'field',pointer,owner,beforeHash:currentHash,managedHash,
+        backup:currentHash===null ? null : '.pipeline/backups/'+contractDigest({name,pointer,beforeHash}).slice(7)+'.bin'};
+    };
+    let result, action, fields=[];
+    if (kind==='file') {
+      if (!Buffer.isBuffer(request.bytes)) fail('plan.bytes');
+      const desiredHash=sha256(request.bytes);
+      const decision=reconcileOwnership({currentHash:beforeHash,desiredHash,managedHash:prior[0]?.managedHash ?? null,takeover:request.takeover ?? null});
+      if(decision.owned) owned.push(retain(prior[0],null,beforeHash,desiredHash));
+      action=decision.action;result=request.bytes;
+    } else {
+      if (!Array.isArray(request.fields) || !request.fields.length || request.fields.some(f=>Object.hasOwn(f,'managedHash'))) fail('plan.fields');
+      if (prior.some(p=>!request.fields.some(f=>f.pointer===p.pointer))) fail('plan.ownership-coverage');
+      const reconciled=reconcileConfigFields(name,bytes,request.fields.map(f=>({...f,managedHash:prior.find(p=>p.pointer===f.pointer)?.managedHash ?? null})));
+      for(const d of reconciled.decisions) if(d.owned) owned.push(retain(prior.find(p=>p.pointer===d.pointer),d.pointer,d.currentHash,d.desiredHash));
+      fields=reconciled.decisions.filter(d=>d.action!=='preserve').map(d=>({pointer:d.pointer,beforeHash:d.currentHash,desiredHash:d.desiredHash}));
+      action=fields.length ? (bytes===null?'create':'edit-fields') : 'preserve';
+      result=action==='preserve' ? bytes : reconciled.bytes;
+      if(action==='create') fields=[];
+    }
+    if(action!=='preserve') {
+      targets.push({id:'target-'+String(targets.length+1),path:name,owner,action,beforeHash,desiredHash:sha256(result),fields});
+      outputs.push({path:name,bytes:result});
+    }
+  }
+  // Removal/provider switch is S7. Never silently abandon existing ownership.
+  for(const restored of restoreRetired(retiredBundleOwnership(previous,layout),observed)) {
+    if([...used].some(name=>overlaps(name,restored.path)))fail('plan.overlap');
+    // Retirement cannot reach a newly selected repository destination.
+    planLayout(pipeline,workspace,wrapper,{adapters,managedPaths:[...used,restored.path]});
+    used.add(restored.path);
+    if(restored.beforeHash!==restored.desiredHash) {
+      const {bytes,...target}=restored;
+      targets.push({id:'target-'+String(targets.length+1),...target});
+      if(bytes!==null)outputs.push({path:restored.path,bytes});
+    }
+  }
+  if(previous?.active?.owned.some(r=>!used.has(r.path))) fail('plan.ownership-coverage');
+  const providers=layout.providers;
+  const bundleState=layout.bundles?{bundles:structuredClone(layout.bundles)}:{};
+  const agentsDocument=structuredClone(layout.agentsDocument);
+  const desired={id:'deployment-'+contractDigest({snapshot,layout:layout.layout,agentsDocument,providers,owned,...bundleState}).slice(7),
+    pipelineId:pipeline.id,version:pipeline.version,snapshot:structuredClone(snapshot),layout:layout.layout,
+    agentsDocument,providers,adapterVersions:Object.fromEntries(providers.map(id=>[id,adapters[id].version])),owned,...bundleState};
+  const plan={schemaVersion:1,kind:'plan',workspace:layout.wrapper,command:previous?.active?'update':'setup',
+    beforeStateHash:previous===null?null:contractDigest(previous),source:structuredClone(snapshot),desired,targets};
+  return bindPreview(plan,previous,{observations,outputs});
+}
+
+// A local preview envelope supplements the S1 operation contract with exact
+// payload bytes and observations (including unchanged targets). Not an approval,
+// path grant, snapshot verification or S5 transaction. Never publish this envelope:
+// observed/output bytes can contain user configuration secrets.
+export function bindPreview(plan, previous, { observations, outputs }) {
+  validateOperation(plan, previous);
+  if (plan.kind !== 'plan' || !Array.isArray(observations) || !Array.isArray(outputs)) fail('preview.input');
+  cap(observations.length, LIMITS.files, 'preview.count');
+  cap(outputs.length, LIMITS.files, 'preview.count');
+  const seen = new Set();
+  let total = 0;
+  const encode = (items, allowAbsent) => items.map(item => {
+    portablePath(item.path);
+    if (seen.has(item.path.toLowerCase())) fail('preview.duplicate');
+    seen.add(item.path.toLowerCase());
+    if (item.bytes === null && allowAbsent) return {path:item.path,hash:null,bytes:null};
+    if (!Buffer.isBuffer(item.bytes)) fail('preview.bytes');
+    cap(item.bytes.length, LIMITS.blob, 'preview.size');
+    total += item.bytes.length;cap(total, LIMITS.total, 'preview.total');
+    return {path:item.path,hash:sha256(item.bytes),bytes:item.bytes.toString('base64')};
+  }).sort((a,b)=>a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const observed = encode(observations, true);seen.clear();
+  const payloads = encode(outputs, false);
+  const before = new Map(observed.map(item=>[item.path,item]));
+  const after = new Map(payloads.map(item=>[item.path,item]));
+  for (const target of plan.targets) {
+    if (!before.has(target.path) || before.get(target.path).hash !== target.beforeHash) fail('preview.before');
+    if (target.desiredHash === null) {
+      if (after.has(target.path)) fail('preview.output');
+    } else if (!after.has(target.path) || after.get(target.path).hash !== target.desiredHash) fail('preview.output');
+  }
+  if (payloads.length !== plan.targets.filter(target=>target.desiredHash !== null).length) fail('preview.output');
+  const body = {schemaVersion:1,plan:structuredClone(plan),observations:observed,outputs:payloads};
+  return {...body,digest:contractDigest(body)};
+}
+
+// Reconstruct and revalidate, rather than trusting caller-provided digest strings.
+// Fresh observations must include unchanged dependencies as well as write targets.
+export function checkPreview(envelope, previous, observations) {
+  if (!envelope || Object.keys(envelope).sort().join(',') !== 'digest,observations,outputs,plan,schemaVersion' || envelope.schemaVersion !== 1) fail('preview.envelope');
+  const decode = items => {
+    if (!Array.isArray(items)) fail('preview.envelope');
+    return items.map(item=>{
+      if (!item || Object.keys(item).sort().join(',') !== 'bytes,hash,path') fail('preview.envelope');
+      if (item.bytes === null) {
+        if (item.hash !== null) fail('preview.envelope');
+        return {path:item.path,bytes:null};
+      }
+      if (typeof item.bytes !== 'string' || item.bytes.length > Math.ceil(LIMITS.blob/3)*4) fail('preview.bytes');
+      const bytes = Buffer.from(item.bytes,'base64');
+      if (bytes.toString('base64') !== item.bytes || sha256(bytes) !== item.hash) fail('preview.bytes');
+      return {path:item.path,bytes};
+    });
+  };
+  const rebound = bindPreview(envelope.plan, previous, {observations:decode(envelope.observations),outputs:decode(envelope.outputs)});
+  if (contractDigest(rebound) !== contractDigest(envelope)) fail('preview.binding');
+  const fresh = bindPreview(envelope.plan, previous, {observations,outputs:decode(envelope.outputs)});
+  if (fresh.digest !== rebound.digest) fail('preview.drift');
+  return rebound;
+}

package/src/operations/reconciliation.js

@@ -0,0 +1,112 @@
+import {inspectRecovery} from './apply.js';
+import {readState,readRecord} from './state.js';
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail,parse} from '../contracts/parse.js';
+import {requestShape} from './ownership.js';
+import {assertLockHeld} from './lock.js';
+import {bindPreview} from './plan.js';
+import {assertContinuationCapacity} from './lineage-guard.js';
+import {retiredBundleOwnership} from './bundle-update.js';
+
+export const continuationCommand=plan=>plan.command==='remove'?'remove':
+  plan.command==='update' && plan.targets.some(t=>t.desiredHash===null)?'update':'repair';
+
+// Current evidence and decisions still required, never a runnable retry/rollback.
+export async function previewReconciliation(workspace,recoveryPath) {
+  workspace=absoluteRoot(workspace);
+  if(typeof 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$/.test(recoveryPath))fail('recovery.path');
+  const stateHash=async()=>{
+    try{return (await readState(resolveChild(workspace,'.pipeline/state.json'))).digest;}
+    catch(e){if(e.code==='record.missing')return null;throw e;}
+  };
+  const before=await stateHash(),recovery=await inspectRecovery(workspace,recoveryPath);
+  if(await stateHash()!==before || (await readRecord(resolveChild(workspace,recoveryPath))).digest!==recovery.recoveryHash)
+    fail('recovery.observation-drift');
+  const body={kind:'reconciliation-preview',workspace,stateHash:before,recoveryPath,recoveryHash:recovery.recoveryHash,
+    status:recovery.status,statePhase:recovery.statePhase,diagnostics:recovery.diagnostics,targets:recovery.targets,
+    journal:recovery.journal,journalHead:recovery.journalHead,lineage:recovery.lineage,requiresDecision:recovery.status!=='applied',requiresFreshApproval:true,
+    applySupported:false,automaticActions:false,runtime:'not-run'};
+  parse(JSON.stringify(body),'json');
+  return {...body,digest:contractDigest(body)};
+}
+
+// Fresh continuation proposal only: do not resume an old writer or manufacture
+// its missing outcome. Exact desired bytes require a new readback, not rewriting.
+// Payloads and observations may contain secrets; keep this envelope local.
+export async function prepareContinuation(workspace,recoveryPath) {
+  const evidence=await previewReconciliation(workspace,recoveryPath);
+  if(!['pending','before'].includes(evidence.statePhase))fail('reconciliation.not-pending');
+  if(evidence.diagnostics.length)fail('reconciliation.conflict');
+  const record=await readRecord(resolveChild(evidence.workspace,recoveryPath));
+  if(record.digest!==evidence.recoveryHash)fail('recovery.observation-drift');
+  const previousPlan=record.value.prepared.preview,actions=[];
+  const beforeSetup=evidence.statePhase==='before';
+  if(beforeSetup && (evidence.stateHash!==null || record.value.previous!==null ||
+      record.value.prepared.kind!=='prepared-plan' || record.value.prepared.stateFileHash!==null ||
+      previousPlan.plan.command!=='setup'))fail('reconciliation.not-pending');
+  if(beforeSetup && ((await inspectRecovery(workspace,recoveryPath)).receipt!==null ||
+      evidence.targets.some(t=>t.position!=='before' || t.recorded!=='skipped')))fail('reconciliation.conflict');
+  const removal=previousPlan.plan.command==='remove';
+  const retired=new Set(retiredBundleOwnership(record.value.previous,previousPlan.plan.desired??{}).map(o=>o.path));
+  assertContinuationCapacity(evidence.lineage.length);
+  for(const target of previousPlan.plan.targets) {
+    const observed=evidence.targets.find(t=>t.id===target.id);
+    if(!observed || !['before','desired'].includes(observed.position))fail('reconciliation.conflict');
+    if(!['create','replace','edit-fields',...((removal || retired.has(target.path))?['delete','verify-absent']:[])].includes(target.action))fail('reconciliation.unsupported');
+    const output=previousPlan.outputs.find(o=>o.path===target.path);
+    if(target.desiredHash===null?!!output:!output || output.hash!==target.desiredHash)fail('reconciliation.payload');
+    actions.push({id:target.id,path:target.path,owner:target.owner,
+      action:observed.position==='desired'?'verify-readback':'write-desired',
+      recorded:observed.recorded,beforeHash:observed.observedHash,
+      desiredHash:target.desiredHash,bytes:output?.bytes??null});
+  }
+  // Include unchanged dependencies, not just the remaining writes. The fresh
+  // evidence binding prevents an unchanged target list hiding a new journal head.
+  let state=null;
+  try { state=await readState(resolveChild(evidence.workspace,'.pipeline/state.json')); }
+  catch(error) { if(!beforeSetup || error.code!=='record.missing')throw error; }
+  if((state?.digest??null)!==evidence.stateHash)fail('recovery.observation-drift');
+  const outputs=actions.filter(a=>a.bytes!==null).map(a=>({path:a.path,bytes:Buffer.from(a.bytes,'base64')}));
+  const observations=previousPlan.observations.map(o=>{
+    const action=actions.find(a=>a.path===o.path);
+    return {path:o.path,bytes:action?.action==='verify-readback'?(action.bytes===null?null:Buffer.from(action.bytes,'base64')):o.bytes===null?null:Buffer.from(o.bytes,'base64')};
+  });
+  const plan={schemaVersion:1,kind:'plan',workspace:evidence.workspace,command:continuationCommand(previousPlan.plan),
+    beforeStateHash:state===null?null:contractDigest(state.value),source:structuredClone(previousPlan.plan.source),
+    desired:structuredClone(previousPlan.plan.desired),targets:actions.map(a=>({id:a.id,path:a.path,owner:a.owner,
+      action:continuationTargetAction(a),beforeHash:a.beforeHash,desiredHash:a.desiredHash,fields:[]}))};
+  const preview=bindPreview(plan,state?.value??null,{observations,outputs});
+  const body={kind:'prepared-continuation',evidence,actions,preview,stateFileHash:evidence.stateHash,
+    dependencies:previousPlan.observations.filter(o=>!actions.some(a=>a.path===o.path)),
+    desired:structuredClone(previousPlan.plan.desired),
+    applySupported:true,requiresFreshApproval:true,automaticActions:false,runtime:'not-run'};
+  parse(JSON.stringify(body),'json');
+  if((await previewReconciliation(evidence.workspace,recoveryPath)).digest!==evidence.digest)fail('recovery.observation-drift');
+  return {...body,digest:contractDigest(body)};
+}
+
+export function continuationTargetAction(action) {
+  return action.desiredHash===null?(action.beforeHash===null?'verify-absent':'delete'):action.beforeHash===null?'create':'replace';
+}
+
+export function validateContinuationRecord(prepared,approval) {
+  requestShape(prepared,['kind','evidence','actions','preview','stateFileHash','dependencies','desired','applySupported','requiresFreshApproval','automaticActions','runtime','digest'],[],'reconciliation.prepared');
+  requestShape(approval,['decision','preparedDigest'],[],'reconciliation.approval');
+  const copy=structuredClone(parse(JSON.stringify(prepared),'json')),decision=structuredClone(approval);
+  const {digest,...body}=copy;
+  if(copy.kind!=='prepared-continuation' || copy.applySupported!==true || copy.requiresFreshApproval!==true ||
+      copy.automaticActions!==false || copy.runtime!=='not-run' || contractDigest(body)!==digest)fail('reconciliation.prepared');
+  if(decision.decision!=='approve' || decision.preparedDigest!==digest)fail('reconciliation.approval');
+  return copy;
+}
+
+export async function verifyContinuationApproval(lock,prepared,approval) {
+  const copy=validateContinuationRecord(prepared,approval);
+  await assertLockHeld(lock);
+  if(copy.evidence?.workspace!==lock.workspace)fail('reconciliation.workspace');
+  const fresh=await prepareContinuation(lock.workspace,copy.evidence.recoveryPath);
+  if(contractDigest(fresh)!==contractDigest(copy))fail('reconciliation.plan-drift');
+  await assertLockHeld(lock);
+  return fresh;
+}

package/src/operations/recovery-lease.js

@@ -0,0 +1,66 @@
+import {createServer} from 'node:net';
+import {realpath} from 'node:fs/promises';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {absoluteRoot,inspectDirectory} from '../workspace/paths.js';
+import {fail} from '../contracts/parse.js';
+
+// Local-host exclusion only. The kernel releases ownership on process death;
+// durable recovery records describe progress, never ownership of this lease.
+// No TCP listener, data protocol, filesystem socket or persistent recovery lock.
+// Unsupported platforms fail closed rather than falling back to a stale lockfile.
+const held=new WeakMap();
+async function endpoint(wrapper) {
+  wrapper=absoluteRoot(wrapper);
+  const parent=path.dirname(wrapper);
+  if(!(await inspectDirectory(parent)).exists)fail('recovery-lease.parent-missing');
+  // Existing linked/reparse wrapper roots are unsupported, just like parents.
+  // Do not give an alias a second ownership endpoint.
+  await inspectDirectory(wrapper);
+  let canonical=path.join(await realpath(parent),path.basename(wrapper));
+  if(process.platform==='win32')canonical=canonical.toLowerCase();
+  const key=createHash('sha256').update(canonical).digest('hex');
+  if(process.platform==='win32')return '\\\\.\\pipe\\wpc-recovery-'+key;
+  if(process.platform==='linux')return '\0wpc-recovery-'+key;
+  fail('recovery-lease.platform-unsupported');
+}
+
+export async function acquireRecoveryLease(wrapper) {
+  const name=await endpoint(wrapper);
+  const server=createServer(socket=>socket.destroy());
+  let failure=false,released=false;
+  server.on('error',()=>{failure=true;});
+  await new Promise((resolve,reject)=>{
+    const error=e=>{server.removeListener('listening',ready);reject(e);};
+    const ready=()=>{server.removeListener('error',error);resolve();};
+    server.once('error',error);server.once('listening',ready);
+    server.listen({path:name,exclusive:true});
+  }).catch(e=>fail(e.code==='EADDRINUSE'?'recovery-lease.busy':
+    e.code==='EACCES'?'recovery-lease.busy-or-access-denied':'recovery-lease.io'));
+  const check=()=>{if(released || failure || !server.listening)fail('recovery-lease.not-held');};
+  const lease=Object.freeze({async release(){
+    if(released)fail('recovery-lease.not-held');
+    released=true;
+    // Cleanup must run even when an asynchronous listener error invalidated check().
+    await new Promise((resolve,reject)=>server.close(e=>
+      e && e.code!=='ERR_SERVER_NOT_RUNNING'?reject(e):resolve()))
+      .catch(()=>fail('recovery-lease.release-failed-status-required'));
+    if(failure)fail('recovery-lease.lost-status-required');
+  }});
+  held.set(lease,check);return lease;
+}
+export function assertRecoveryLeaseHeld(lease) {
+  const check=lease && held.get(lease);
+  if(!check)fail('recovery-lease.capability');check();
+}
+export async function withRecoveryLease(wrapper,run) {
+  const lease=await acquireRecoveryLease(wrapper);
+  let result,runError,failed=false;
+  try{result=await run(lease);}catch(e){failed=true;runError=e;}
+  try{await lease.release();}catch(e){
+    if(failed)fail('recovery-lease.run-and-release-failed-status-required');
+    throw e;
+  }
+  if(failed)throw runError;
+  return result;
+}

package/src/operations/remove.js

@@ -0,0 +1,140 @@
+import {inspectRepair} from './repair.js';
+import {readState,observeTargets} from './state.js';
+import {resolveChild} from '../workspace/paths.js';
+import {requestShape} from './ownership.js';
+import {readConfigField,reconcileConfigFields} from './config-fields.js';
+import {bindPreview} from './plan.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {parse,fail} from '../contracts/parse.js';
+import {sha256} from '../source/inventory.js';
+import {assertLockHeld} from './lock.js';
+import {removedWithProviders} from '../providers/common-entry.js';
+
+export function selectRemovalProviders(available,requested=available) {
+  if(!Array.isArray(available) || !Array.isArray(requested) || !requested.length ||
+      new Set(requested).size!==requested.length || requested.some(id=>typeof id!=='string' || !available.includes(id)))fail('remove.providers');
+  const providers=[...requested].sort(),remaining=available.filter(id=>!providers.includes(id)).sort();
+  return {providers,remaining,owners:[...providers,...(remaining.length?[]:['shared'])]};
+}
+
+export function selectBundleRemoval(active, options={}) {
+  const all=options.providers===undefined && options.bundles===undefined;
+  const bundleIds=all?Object.keys(active.bundles??{}).sort():options.bundles??[];
+  if(!Array.isArray(bundleIds) || new Set(bundleIds).size!==bundleIds.length ||
+      bundleIds.some(id=>!Object.hasOwn(active.bundles??{},id)))fail('remove.bundles');
+  const grouped=new Set(Object.values(active.bundles??{}).flatMap(b=>b.providers));
+  const standalone=all?active.providers.filter(id=>!grouped.has(id)):options.providers??[];
+  if(!Array.isArray(standalone) || standalone.some(id=>grouped.has(id)))fail('remove.bundle-required');
+  const selection=selectRemovalProviders(active.providers,[...standalone,...bundleIds.flatMap(id=>active.bundles[id].providers)]);
+  return {...selection,bundles:[...bundleIds].sort()};
+}
+
+// Internal preparation. Replay establishes owned scope from the installed
+// package; preparation never deletes. Private byte payload.
+export async function prepareRemoval(workspace,registry,options={}) {
+  requestShape(options,[],['providers','bundles'],'remove.options');
+  const inspection=await inspectRepair(workspace,registry);
+  if(inspection.entries.some(e=>e.disposition!=='intact'))fail('remove.conflict');
+  workspace=inspection.workspace;
+  const record=await readState(resolveChild(workspace,'.pipeline/state.json'));
+  if(record.digest!==inspection.stateHash)fail('remove.observation-drift');
+  const previous=record.value,active=previous.active,selection=selectBundleRemoval(active,options);
+  const removed=active.owned.filter(o=>removedWithProviders(o,selection));
+  const retained=active.owned.filter(o=>!removedWithProviders(o,selection));
+  const observations=await observeTargets(workspace,[...new Set(active.owned.map(o=>o.path))]);
+  const current=new Map(observations.map(o=>[o.path,o.bytes])),backups=new Map(),targets=[],outputs=[];
+  const backup=async owned=>{
+    if(owned.backup===null)fail('remove.backup-missing');
+    if(!backups.has(owned.backup)) {
+      const [observation]=await observeTargets(workspace,[owned.backup]);
+      if(observation.bytes===null)fail('remove.backup-missing');
+      backups.set(owned.backup,observation.bytes);
+    }
+    return backups.get(owned.backup);
+  };
+  for(const name of [...new Set(removed.map(o=>o.path))].sort()) {
+    const owned=removed.filter(o=>o.path===name),before=current.get(name);
+    if(before===null)fail('remove.conflict');
+    let bytes=null,fields=[],action;
+    if(owned[0].kind==='file') {
+      if(sha256(before)!==owned[0].managedHash)fail('remove.conflict');
+      if(owned[0].beforeHash!==null) {
+        bytes=await backup(owned[0]);
+        if(sha256(bytes)!==owned[0].beforeHash)fail('remove.backup-mismatch');
+      }
+      action=bytes===null?'delete':'replace';
+    }else {
+      const requests=[];
+      for(const item of owned) {
+        const request={pointer:item.pointer,present:item.beforeHash!==null,managedHash:item.managedHash};
+        if(request.present) {
+          const found=readConfigField(name,await backup(item),item.pointer);
+          if(!found.present)fail('remove.backup-field');
+          request.value=found.value;
+          if(contractDigest(request.value)!==item.beforeHash)fail('remove.backup-mismatch');
+        }
+        requests.push(request);
+      }
+      const result=reconcileConfigFields(name,before,requests);
+      fields=result.decisions.map(f=>({pointer:f.pointer,beforeHash:f.currentHash,desiredHash:f.desiredHash}));
+      bytes=result.bytes;action='edit-fields';
+    }
+    const beforeHash=sha256(before),desiredHash=bytes===null?null:sha256(bytes);
+    if(beforeHash===desiredHash)continue;
+    targets.push({id:'target-'+String(targets.length+1),path:name,owner:owned[0].owner,action,beforeHash,desiredHash,fields});
+    if(bytes!==null)outputs.push({path:name,bytes});
+  }
+  let desired=null;
+  if(selection.remaining.length) {
+    desired={...structuredClone(active),providers:selection.remaining,owned:structuredClone(retained),
+      adapterVersions:Object.fromEntries(selection.remaining.map(id=>[id,active.adapterVersions[id]]))};
+    if(desired.bundles) {
+      desired.bundles=Object.fromEntries(Object.entries(desired.bundles).filter(([id])=>!selection.bundles.includes(id)));
+      if(!Object.keys(desired.bundles).length)delete desired.bundles;
+    }
+    desired.id='deployment-'+contractDigest({snapshot:desired.snapshot,layout:desired.layout,
+      ...(desired.agentsDocument===undefined?{}:{agentsDocument:desired.agentsDocument}),
+      providers:desired.providers,owned:desired.owned,...(desired.bundles?{bundles:desired.bundles}:{})}).slice(7);
+  }
+  const preview=bindPreview({schemaVersion:1,kind:'plan',command:'remove',workspace,beforeStateHash:contractDigest(previous),
+    source:structuredClone(active.snapshot),desired,targets},previous,{observations,outputs});
+  if((await inspectRepair(workspace,registry)).digest!==inspection.digest)fail('remove.observation-drift');
+  for(const fresh of await observeTargets(workspace,observations.map(o=>o.path))) {
+    const before=current.get(fresh.path);
+    if((fresh.bytes===null?null:sha256(fresh.bytes))!==(before===null?null:sha256(before)))fail('remove.observation-drift');
+  }
+  for(const [name,bytes] of backups) {
+    const [fresh]=await observeTargets(workspace,[name]);
+    if(fresh.bytes===null || sha256(fresh.bytes)!==sha256(bytes))fail('remove.observation-drift');
+  }
+  const body={kind:'prepared-removal',preview,stateFileHash:record.digest,providers:selection.providers,
+    ...(selection.bundles.length?{bundles:selection.bundles}:{}),
+    backups:[...backups].map(([path,bytes])=>({path,hash:sha256(bytes)})),
+    applySupported:true,requiresFreshApproval:true,automaticActions:false,runtime:'not-run'};
+  parse(JSON.stringify(body),'json');return {...body,digest:contractDigest(body)};
+}
+
+// Record validation is not a write grant; apply must also replay under lock.
+export function validateRemovalRecord(prepared,approval) {
+  requestShape(prepared,['kind','preview','stateFileHash','providers','backups','applySupported','requiresFreshApproval','automaticActions','runtime','digest'],['bundles'],'remove.prepared');
+  requestShape(approval,['decision','preparedDigest'],[],'remove.approval');
+  const copy=structuredClone(parse(JSON.stringify(prepared),'json')),decision=structuredClone(approval);
+  const {digest,...body}=copy;
+  if(copy.kind!=='prepared-removal' || copy.applySupported!==true || copy.requiresFreshApproval!==true ||
+      copy.automaticActions!==false || copy.runtime!=='not-run' || contractDigest(body)!==digest)fail('remove.prepared');
+  if(decision.decision!=='approve' || decision.preparedDigest!==digest)fail('remove.approval');
+  return copy;
+}
+
+export async function verifyRemovalApproval(lock,prepared,approval,registry) {
+  const copy=validateRemovalRecord(prepared,approval);
+  await assertLockHeld(lock);
+  if(copy.preview?.plan?.workspace!==lock.workspace)fail('remove.workspace');
+  const active=(await readState(resolveChild(lock.workspace,'.pipeline/state.json'))).value.active;
+  const members=new Set((copy.bundles??[]).flatMap(id=>active?.bundles?.[id]?.providers??[]));
+  const fresh=await prepareRemoval(lock.workspace,registry,{providers:copy.providers.filter(id=>!members.has(id)),
+    ...(copy.bundles?{bundles:copy.bundles}:{})});
+  if(contractDigest(fresh)!==contractDigest(copy))fail('remove.plan-drift');
+  await assertLockHeld(lock);
+  return fresh;
+}