@6reduk/workspace-pipeline 0.1.0

package/src/operations/switch-preflight.js

@@ -0,0 +1,73 @@
+import path from 'node:path';
+import {validateSwitchRecord} from './switch-records.js';
+import {assertLockHeld} from './lock.js';
+import {prepareRemoval} from './remove.js';
+import {readState,observeTargets,resolveOrigin,verifyPreparedSnapshot} from './state.js';
+import {absoluteRoot,inspectDirectory,resolveChild} from '../workspace/paths.js';
+import {planLayout} from '../workspace/resolve.js';
+import {composePlan,assertRequestScope} from './plan.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail} from '../contracts/parse.js';
+import {sha256,cap,LIMITS} from '../source/inventory.js';
+
+// Read-only locked preflight. No Git/network, persistence, provider writes or
+// activation. A future executor must repeat relevant checks at write boundaries.
+export async function verifySwitchApproval(lock,prepared,approval,registry,previous) {
+  const bound=validateSwitchRecord(prepared,approval,previous),copy=bound.prepared;
+  await assertLockHeld(lock);
+  if(copy.preview.workspace!==lock.workspace)fail('switch-preflight.workspace');
+  const workspace=lock.workspace,plan=copy.preview.phases[1].preview.plan;
+  const snapshot={snapshotPath:copy.preparation.snapshot,manifest:{id:plan.desired.pipelineId,version:plan.desired.version},
+    digest:plan.source.digest,inventoryDigest:plan.source.inventoryDigest};
+  const options={wrapper:workspace,previous:null,manifestPath:plan.source.origin.path,command:'setup'};
+  const nested=r=>!r || (!path.isAbsolute(r) && r!=='..' && !r.startsWith('..'+path.sep));
+  async function verify() {
+    await assertLockHeld(lock);
+    for(const candidate of Object.values(copy.preparation)) {
+      const root=absoluteRoot(candidate);
+      if(nested(path.relative(workspace,root)) || nested(path.relative(root,workspace)))fail('switch-preflight.preparation-location');
+      if(!(await inspectDirectory(root)).exists)fail('switch-preflight.preparation-missing');
+    }
+    const record=await readState(resolveChild(workspace,'.pipeline/state.json'));
+    if(record.digest!==copy.stateFileHash || contractDigest(record.value)!==contractDigest(bound.previous))fail('switch-preflight.state-drift');
+    // Full old-package replay also verifies installed snapshot and backup bytes.
+    if(contractDigest(await prepareRemoval(workspace,registry))!==contractDigest(copy.removal))fail('switch-preflight.removal-drift');
+    const origin=await resolveOrigin(options);
+    if(contractDigest(origin.origin)!==contractDigest(plan.source.origin) ||
+        contractDigest(origin.manifest.pipeline)!==contractDigest(plan.source.source))fail('switch-preflight.origin-drift');
+    const verified=await verifyPreparedSnapshot(snapshot);
+    const observations=await observeTargets(workspace,copy.preview.observations.map(o=>o.path));
+    for(const o of observations) {
+      const expected=copy.preview.observations.find(v=>v.path===o.path);
+      if((o.bytes===null?null:sha256(o.bytes))!==expected.hash || (o.bytes===null?null:o.bytes.toString('base64'))!==expected.bytes)fail('switch-preflight.observation-drift');
+    }
+    if((await readState(resolveChild(workspace,'.pipeline/state.json'))).digest!==copy.stateFileHash)fail('switch-preflight.state-drift');
+    await assertLockHeld(lock);
+    return {origin,verified};
+  }
+  const {origin,verified}=await verify(),{adapters,sharedAdapter}=registry;
+  const layout=planLayout(verified.manifest,origin.manifest,workspace,{adapters});
+  const context=()=>({pipeline:structuredClone(verified.manifest),workspace:structuredClone(origin.manifest),layout:structuredClone(layout),snapshot:structuredClone(plan.source),
+    files:new Map([...verified.files].map(([name,bytes])=>[name,Buffer.from(bytes)]))});
+  const requests=[];
+  for(const [owner,adapter] of [['shared',sharedAdapter],...layout.providers.map(id=>[id,adapters[id]])]) {
+    if(owner!=='shared' && (await adapter.validate(context()))?.valid===false)fail('provider.validation');
+    const batch=await adapter.plan(context());
+    if(!Array.isArray(batch))fail('plan.adapter-output');
+    cap(requests.length+batch.length,LIMITS.files,'plan.count');
+    for(const request of batch) {
+      assertRequestScope(request,layout.providers);
+      if(request.owner!==owner)fail('plan.adapter-owner');
+      requests.push(request.kind==='file'?{...request,bytes:Buffer.isBuffer(request.bytes)?Buffer.from(request.bytes):request.bytes}:structuredClone(request));
+    }
+  }
+  const incoming=copy.preview.phases[1].preview;
+  const observations=incoming.observations.map(o=>({path:o.path,bytes:o.bytes===null?null:Buffer.from(o.bytes,'base64')}));
+  const rendered=composePlan({pipeline:verified.manifest,workspace:origin.manifest,wrapper:workspace,previous:null,
+    snapshot:plan.source,adapters,requests,observations});
+  if(contractDigest(rendered)!==contractDigest(incoming) || requests.length!==observations.length ||
+      observations.some(o=>!requests.some(r=>r.path===o.path)))fail('switch-preflight.adapter-drift');
+  // Async adapters may have changed dependencies: repeat the observations.
+  await verify();
+  return {...bound,snapshot,applySupported:false,runtime:'not-run'};
+}

package/src/operations/switch-prepare.js

@@ -0,0 +1,75 @@
+import path from 'node:path';
+import {tmpdir} from 'node:os';
+import {prepareRemoval} from './remove.js';
+import {composeSwitchPreview} from './switch.js';
+import {composePlan,assertRequestScope} from './plan.js';
+import {readState,resolveOrigin,verifyPreparedSnapshot,observeTargets} from './state.js';
+import {absoluteRoot,inspectDirectory,resolveChild} from '../workspace/paths.js';
+import {planLayout} from '../workspace/resolve.js';
+import {acquire} from '../source/git.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {fail,parse} from '../contracts/parse.js';
+import {requestShape} from './ownership.js';
+import {cap,LIMITS} from '../source/inventory.js';
+
+// Staging only: never calls an executor or writes workspace/provider files.
+// Registry is trusted CLI code; the Git package supplies data, not executable code.
+export async function prepareSwitch({wrapper,manifestPath,network=false,tempRoot=tmpdir()},registry) {
+  requestShape(registry,['adapters','sharedAdapter'],[],'provider.interface');
+  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(typeof manifestPath!=='string' || !manifestPath.length)fail('switch.manifest-required');
+  const removal=await prepareRemoval(wrapper,registry);
+  const statePath=resolveChild(wrapper,'.pipeline/state.json'),record=await readState(statePath);
+  if(record.digest!==removal.stateFileHash)fail('switch.state-drift');
+  const options={wrapper,previous:null,manifestPath,command:'setup'};
+  const origin=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 {adapters,sharedAdapter}=registry;
+  const layout=planLayout(verified.manifest,origin.manifest,wrapper,{adapters});
+  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 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)]))});
+  const requests=[];
+  for(const [owner,adapter] of [['shared',sharedAdapter],...layout.providers.map(id=>[id,adapters[id]])]) {
+    if(owner!=='shared' && (await adapter.validate(context()))?.valid===false)fail('provider.validation');
+    const batch=await adapter.plan(context());
+    if(!Array.isArray(batch))fail('plan.adapter-output');
+    cap(requests.length+batch.length,LIMITS.files,'plan.count');
+    for(const request of batch) {
+      assertRequestScope(request,layout.providers);
+      if(request.owner!==owner)fail('plan.adapter-owner');
+      // Detach buffers/fields from asynchronous adapter-owned values.
+      requests.push(request.kind==='file'?{...request,bytes:Buffer.isBuffer(request.bytes)?Buffer.from(request.bytes):request.bytes}:structuredClone(request));
+    }
+  }
+  planLayout(verified.manifest,origin.manifest,wrapper,{adapters,managedPaths:requests.map(r=>r.path)});
+  const observations=await observeTargets(wrapper,requests.map(r=>r.path));
+  const removed=new Set(removal.preview.plan.targets.map(t=>t.path));
+  const restored=new Map(removal.preview.outputs.map(o=>[o.path,Buffer.from(o.bytes,'base64')]));
+  const projected=observations.map(o=>({path:o.path,bytes:removed.has(o.path)?restored.get(o.path)??null:o.bytes}));
+  const replacement=composePlan({pipeline:verified.manifest,workspace:origin.manifest,wrapper,
+    previous:null,snapshot,adapters,requests,observations:projected});
+  const preview=composeSwitchPreview({previous:record.value,removal:removal.preview,replacement});
+  // Recheck after all asynchronous adapter work. This is not an atomic read or
+  // fresh apply approval; a future locked executor must repeat its preflight.
+  if((await prepareRemoval(wrapper,registry)).digest!==removal.digest)fail('switch.removal-drift');
+  if(contractDigest(await resolveOrigin(options))!==contractDigest(origin))fail('plan.origin-drift');
+  await verifyPreparedSnapshot(acquired);
+  const after=await observeTargets(wrapper,observations.map(o=>o.path));
+  if(contractDigest(after)!==contractDigest(observations))fail('switch.observation-drift');
+  if((await readState(statePath)).digest!==record.digest)fail('switch.state-drift');
+  const body={kind:'prepared-switch',preview,removal,stateFileHash:record.digest,
+    preparation:{objects:acquired.preparation,snapshot:acquired.snapshotPath},
+    sourceVerification:'verified-at-preparation',applySupported:false,requiresFreshApproval:true,runtime:'not-run'};
+  const copy=parse(JSON.stringify(body),'json');
+  return {...copy,digest:contractDigest(copy)};
+}

package/src/operations/switch-records.js

@@ -0,0 +1,60 @@
+import {parse,fail} from '../contracts/parse.js';
+import {requestShape} from './ownership.js';
+import {contractDigest,validateState,portablePath} from '../contracts/semantic.js';
+import {composeSwitchPreview} from './switch.js';
+import {absoluteRoot} from '../workspace/paths.js';
+
+const hash=value=>typeof value==='string' && /^sha256:[a-f0-9]{64}(?![\s\S])/.test(value);
+const detach=value=>parse(JSON.stringify(value),'json');
+
+// Structural binding only: never a substitute for locked replay/source checks.
+export function validateSwitchRecord(prepared,approval,previous) {
+  const copy=detach(prepared),decision=detach(approval),state=detach(previous);
+  requestShape(copy,['kind','preview','removal','stateFileHash','preparation','sourceVerification','applySupported','requiresFreshApproval','runtime','digest'],[],'switch-record.prepared');
+  requestShape(decision,['decision','preparedDigest'],[],'switch-record.approval');
+  validateState(state);
+  if(state.status!=='ready' || !state.active || state.pending!==null)fail('switch-record.previous');
+  const {digest,...body}=copy;
+  if(copy.kind!=='prepared-switch' || copy.sourceVerification!=='verified-at-preparation' || copy.applySupported!==false ||
+      copy.requiresFreshApproval!==true || copy.runtime!=='not-run' || !hash(copy.stateFileHash) || contractDigest(body)!==digest)fail('switch-record.prepared');
+  if(decision.decision!=='approve' || decision.preparedDigest!==digest)fail('switch-record.approval');
+  requestShape(copy.preparation,['objects','snapshot'],[],'switch-record.preparation');
+  absoluteRoot(copy.preparation.objects);absoluteRoot(copy.preparation.snapshot);
+  const r=copy.removal;
+  requestShape(r,['kind','preview','stateFileHash','providers','backups','applySupported','requiresFreshApproval','automaticActions','runtime','digest'],['bundles'],'switch-record.removal');
+  const {digest:rd,...rb}=r;
+  if(r.kind!=='prepared-removal' || r.applySupported!==true || r.requiresFreshApproval!==true || r.automaticActions!==false ||
+      r.runtime!=='not-run' || r.stateFileHash!==copy.stateFileHash || contractDigest(rb)!==rd ||
+      !Array.isArray(r.providers) || contractDigest(r.providers)!==contractDigest([...state.active.providers].sort()))fail('switch-record.removal');
+  if(!Array.isArray(r.backups))fail('switch-record.backups');
+  const expected=new Set(state.active.owned.map(o=>o.backup).filter(v=>v!==null)),seen=new Set();
+  for(const b of r.backups) {
+    requestShape(b,['path','hash'],[],'switch-record.backups');portablePath(b.path);
+    if(!expected.has(b.path) || seen.has(b.path) || !hash(b.hash))fail('switch-record.backups');
+    seen.add(b.path);
+  }
+  if(seen.size!==expected.size)fail('switch-record.backups');
+  if(!Array.isArray(copy.preview?.phases) || copy.preview.phases.length!==2)fail('switch-record.phases');
+  const fresh=composeSwitchPreview({previous:state,removal:r.preview,replacement:copy.preview.phases[1].preview});
+  if(contractDigest(fresh)!==contractDigest(copy.preview))fail('switch-record.phases');
+  return {prepared:copy,approval:decision,previous:state};
+}
+
+export function createSwitchRecoveryRecord({prepared,approval,previous,journal}) {
+  const bound=validateSwitchRecord(prepared,approval,previous);
+  if(typeof journal!=='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(journal))fail('switch-record.journal');
+  // Both sources are required for recovery; the new snapshot must be durably
+  // installed and verified before a future executor writes provider targets.
+  const body={schemaVersion:1,kind:'switch-recovery',...bound,journal,
+    snapshots:{old:bound.previous.active.snapshot,new:bound.prepared.preview.phases[1].preview.plan.source},
+    activationSupported:false,runtime:'not-run'};
+  return detach({...body,digest:contractDigest(body)});
+}
+
+export function validateSwitchRecoveryRecord(record) {
+  const copy=detach(record);
+  requestShape(copy,['schemaVersion','kind','prepared','approval','previous','journal','snapshots','activationSupported','runtime','digest'],[],'switch-record.recovery');
+  const fresh=createSwitchRecoveryRecord(copy);
+  if(contractDigest(copy)!==contractDigest(fresh))fail('switch-record.recovery');
+  return fresh;
+}

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

@@ -0,0 +1,74 @@
+import {mkdir,open} from 'node:fs/promises';
+import {verifySwitchApproval} from './switch-preflight.js';
+import {createSwitchRecoveryRecord,validateSwitchRecoveryRecord} from './switch-records.js';
+import {createSwitchJournal,readSwitchJournal} from './switch-journal-store.js';
+import {copySnapshot,saveBackup} from './backup.js';
+import {incomingSwitchBackups} from './switch-backups.js';
+import {assertLockHeld} from './lock.js';
+import {readRecord,observeTargets,verifyPreparedSnapshot,verifyInstalledSnapshot} from './state.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {sha256} from '../source/inventory.js';
+import {fail,ContractError} from '../contracts/parse.js';
+
+// Read-only structural/durable evidence inspection, not current-target recovery
+// or permission to continue. Generic history integration is still pending.
+export async function readSwitchRecovery(workspace,relative) {
+  const match=typeof relative==='string' && /^\.pipeline\/transactions\/([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})\/recovery.json(?![\s\S])/.exec(relative);
+  if(!match)fail('switch-recovery.path');
+  const stored=await readRecord(resolveChild(workspace,relative)),record=validateSwitchRecoveryRecord(stored.value);
+  if(record.previous.workspace!==workspace || record.journal!=='.pipeline/journals/'+match[1])fail('switch-recovery.binding');
+  await verifyInstalledSnapshot(record.previous);
+  for(const backup of [...record.prepared.removal.backups,...incomingSwitchBackups(record.prepared.preview.phases[1].preview)]) {
+    const [observation]=await observeTargets(workspace,[backup.path]);
+    if(observation.bytes===null || sha256(observation.bytes)!==backup.hash)fail('switch-recovery.backup');
+  }
+  const desired=record.prepared.preview.phases[1].preview.plan.desired;
+  await verifyPreparedSnapshot({snapshotPath:resolveChild(workspace,record.snapshots.new.path),
+    manifest:{id:desired.pipelineId,version:desired.version},digest:record.snapshots.new.digest,inventoryDigest:record.snapshots.new.inventoryDigest});
+  const journal=await readSwitchJournal(workspace,record.journal,record.prepared.preview,record.previous);
+  if((await readRecord(resolveChild(workspace,relative))).digest!==stored.digest)fail('switch-recovery.drift');
+  return {record,fileHash:stored.digest,journal,applySupported:false,runtime:'not-run'};
+}
+
+// Persist prerequisites only. Never changes active/pending state or target files.
+// Orphan/partial metadata is retained on failure, never retried or cleaned here.
+export async function persistSwitchRecovery(lock,prepared,approval,registry,previous,{boundary=async()=>{},onJournal=async()=>{}}={}) {
+  const checked=await verifySwitchApproval(lock,prepared,approval,registry,previous);
+  const args={prepared:checked.prepared,approval:checked.approval,previous:checked.previous};
+  // Bound serialization before any additional metadata write.
+  createSwitchRecoveryRecord({...args,journal:'.pipeline/journals/00000000-0000-0000-0000-000000000000'});
+  const backups=incomingSwitchBackups(args.prepared.preview.phases[1].preview);
+  // Check all existing collisions before saving any new backup. Old backups are
+  // immutable; a shared path with different bytes is a blocker, not an overwrite.
+  for(const backup of backups) {
+    const [current]=await observeTargets(lock.workspace,[backup.path]);
+    if(current.bytes!==null && sha256(current.bytes)!==backup.hash)fail('switch-recovery.backup-conflict');
+  }
+  await copySnapshot(lock,checked.snapshot);
+  await boundary('snapshot');
+  await verifySwitchApproval(lock,args.prepared,args.approval,registry,args.previous);
+  for(const backup of backups)await saveBackup(lock,backup.path,backup.bytes,backup.hash);
+  await boundary('backups');
+  await verifySwitchApproval(lock,args.prepared,args.approval,registry,args.previous);
+  const journal=await createSwitchJournal(lock,args.prepared.preview,args.previous,{onLocation:onJournal});
+  const uuid=journal.relative.split('/').at(-1),relative='.pipeline/transactions/'+uuid+'/recovery.json';
+  const record=createSwitchRecoveryRecord({...args,journal:journal.relative});
+  const bytes=Buffer.from(JSON.stringify(record)+'\n');
+  try {
+    await assertLockHeld(lock);
+    const parent=resolveChild(lock.workspace,'.pipeline/transactions'),directory=resolveChild(lock.workspace,'.pipeline/transactions/'+uuid);
+    try{await mkdir(parent);}catch(error){if(error.code!=='EEXIST')throw error;}
+    await inspectDirectory(parent);await mkdir(directory);await inspectDirectory(directory);
+    const handle=await open(resolveChild(lock.workspace,relative),'wx',0o600);
+    try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+    await boundary('recovery-written',{path:relative});
+    if((await readRecord(resolveChild(lock.workspace,relative))).digest!==sha256(bytes))fail('switch-recovery.readback');
+    await verifySwitchApproval(lock,args.prepared,args.approval,registry,args.previous);
+    const evidence=await readSwitchRecovery(lock.workspace,relative);
+    if(evidence.journal.sequence!==1 || evidence.journal.status!=='open')fail('switch-recovery.journal');
+    await assertLockHeld(lock);
+    // No mutable journal writer is returned: no provider operation is authorized.
+    return {recoveryPath:relative,recoveryHash:evidence.fileHash,journalPath:journal.relative,
+      snapshotPath:record.snapshots.new.path,applySupported:false,runtime:'not-run'};
+  }catch(error){throw error instanceof ContractError?error:new ContractError('switch-recovery.io');}
+}

package/src/operations/switch.js

@@ -0,0 +1,52 @@
+import {checkPreview} from './plan.js';
+import {contractDigest,validateState} from '../contracts/semantic.js';
+import {requestShape} from './ownership.js';
+import {fail,parse} from '../contracts/parse.js';
+
+const decode=items=>items.map(o=>({path:o.path,bytes:o.bytes===null?null:Buffer.from(o.bytes,'base64')}));
+
+// Pure phase composition, NOT a source verifier, write grant or executable plan.
+// The caller must stage/verify the incoming Git package and replay both registries
+// before obtaining an approval for any future switch executor.
+export function composeSwitchPreview({previous,removal,replacement}) {
+  validateState(previous);
+  if(previous.status!=='ready' || !previous.active || previous.pending!==null)fail('switch.previous');
+  requestShape(removal,['schemaVersion','plan','observations','outputs','digest'],[],'switch.preview');
+  requestShape(replacement,['schemaVersion','plan','observations','outputs','digest'],[],'switch.preview');
+  const old=checkPreview(removal,previous,decode(removal.observations));
+  const incoming=checkPreview(replacement,null,decode(replacement.observations));
+  if(old.plan.command!=='remove' || old.plan.desired!==null || old.plan.workspace!==previous.workspace ||
+      contractDigest(old.plan.source)!==contractDigest(previous.active.snapshot))fail('switch.removal');
+  if(incoming.plan.command!=='setup' || incoming.plan.workspace!==previous.workspace || !incoming.plan.desired)fail('switch.replacement');
+  if(incoming.plan.desired.pipelineId===previous.active.pipelineId)fail('switch.same-pipeline');
+  if(incoming.plan.source.digest===previous.active.snapshot.digest)fail('switch.source-identity');
+  if(contractDigest(incoming.plan.desired.layout)!==contractDigest(previous.active.layout))fail('switch.layout-change');
+
+  const initial=new Map(old.observations.map(o=>[o.path,o]));
+  const removed=new Map(old.plan.targets.map(t=>[t.path,t.desiredHash]));
+  const restored=new Map(old.outputs.map(o=>[o.path,o]));
+  for(const observation of incoming.observations) {
+    if([...initial.keys()].some(name=>name!==observation.path && name.toLowerCase()===observation.path.toLowerCase()))fail('switch.path-alias');
+    if(initial.has(observation.path)) {
+      const expected=removed.has(observation.path)?removed.get(observation.path):initial.get(observation.path).hash;
+      if(observation.hash!==expected)fail('switch.projected-before');
+      const expectedBytes=removed.has(observation.path)?restored.get(observation.path)?.bytes??null:initial.get(observation.path).bytes;
+      if(observation.bytes!==expectedBytes)fail('switch.projected-before');
+    }else initial.set(observation.path,observation);
+  }
+  // All old managed scope must have been observed even when the incoming package
+  // no longer mentions it; its removal must never depend on new adapter coverage.
+  if(previous.active.owned.some(o=>!old.observations.some(v=>v.path===o.path)))fail('switch.old-coverage');
+  const final=new Map(initial);
+  for(const phase of [old,incoming]) {
+    const outputs=new Map(phase.outputs.map(o=>[o.path,o]));
+    for(const t of phase.plan.targets)final.set(t.path,outputs.get(t.path)??{path:t.path,hash:null,bytes:null});
+  }
+  const body={kind:'switch-phase-preview',workspace:previous.workspace,beforeStateHash:contractDigest(previous),
+    fromPipeline:previous.active.pipelineId,toPipeline:incoming.plan.desired.pipelineId,
+    phases:[{name:'remove-old',preview:old},{name:'install-new',preview:incoming}],
+    observations:[...initial.values()].sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0),
+    results:[...final.values()].sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0),
+    applySupported:false,requiresFreshApproval:true,sourceVerification:'not-verified',runtime:'not-run'};
+  const copy=parse(JSON.stringify(body),'json');return {...copy,digest:contractDigest(copy)};
+}

package/src/operations/toml-fields.js

@@ -0,0 +1,133 @@
+import {parseTOML, getStaticTOMLValue} from 'toml-eslint-parser';
+import {isDeepStrictEqual} from 'node:util';
+import {fail, MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {utf8} from '../source/inventory.js';
+import {reconcileFields,requestShape} from './ownership.js';
+
+// Only complete named Codex agent/MCP entries. No model, permission, auth or
+// trust setting may be addressed through this editor. No I/O or authorization.
+function parts(pointer) {
+  if(typeof pointer!=='string' || !/^\/(agents|mcp_servers)\/[a-z][a-z0-9_-]{0,99}$/.test(pointer))fail('toml.scope');
+  const result=pointer.slice(1).split('/');
+  if(['__proto__','prototype','constructor'].includes(result[1]))fail('toml.scope');
+  if(result[0]==='agents' && ['enabled','max_threads','max_depth','max_concurrent_threads_per_session',
+    'default_subagent_model','default_subagent_reasoning_effort','job_max_runtime_seconds','interrupt_message'].includes(result[1]))fail('toml.scope');
+  return result;
+}
+const prefix=(a,b)=>a.length<=b.length && a.every((x,i)=>x===b[i]);
+const keys=key=>key.keys.map(k=>k.type==='TOMLBare'?k.name:k.value);
+
+function document(bytes) {
+  if(bytes!==null && !Buffer.isBuffer(bytes))fail('toml.input');
+  if(bytes!==null && bytes.length>MAX_INPUT_BYTES)fail('toml.size');
+  const text=bytes===null?'':utf8(bytes);
+  let ast;try{ast=parseTOML(text,{tomlVersion:'1.0'});}catch{fail('toml.syntax');}
+  let count=0;
+  function inspect(node,depth=0) {
+    if(++count>50000 || depth>64)fail('toml.complexity');
+    if(node.type==='TOMLKey' && keys(node).some(k=>['__proto__','prototype','constructor'].includes(k)))fail('toml.key');
+    // Deliberately omit parent/tokens/comments, which contain cycles or duplicate nodes.
+    for(const key of ['body','key','value','elements','keys']) {
+      const value=node[key];
+      for(const child of Array.isArray(value)?value:[value])if(child && typeof child==='object' && typeof child.type==='string')inspect(child,depth+1);
+    }
+  }
+  inspect(ast);
+  let value;try{value=getStaticTOMLValue(ast);}catch{fail('toml.syntax');}
+  return {text,ast,value};
+}
+
+function selected(value,pointer) {
+  const [root,name]=parts(pointer);
+  if(!Object.hasOwn(value,root))return {present:false};
+  const parent=value[root];
+  if(parent===null || typeof parent!=='object' || Array.isArray(parent) || parent instanceof Date)fail('toml.ancestor');
+  if(!Object.hasOwn(parent,name))return {present:false};
+  const entry=parent[name];
+  if(entry===null || typeof entry!=='object' || Array.isArray(entry) || entry instanceof Date)fail('toml.entry');
+  // Reuse the JSON-domain validator without admitting dates/NaN/unsafe integers
+  // into owned hashes. Foreign TOML values are never serialized or normalized.
+  const checked=reconcileFields({},[{pointer,present:true,value:entry}]);
+  return {present:true,value:checked.value[root][name]};
+}
+
+export function readTOMLField(bytes,pointer) {
+  return selected(document(bytes).value,pointer);
+}
+
+function literal(value) {
+  if(typeof value==='string')return JSON.stringify(value).replace(/\u007f/g,'\\u007f');
+  if(typeof value==='boolean' || (typeof value==='number' && Number.isFinite(value) && (!Number.isInteger(value)||Number.isSafeInteger(value))))return String(value);
+  if(Array.isArray(value))return '['+value.map(literal).join(', ')+']';
+  if(value && typeof value==='object')return '{ '+Object.keys(value).sort().map(k=>JSON.stringify(k)+' = '+literal(value[k])).join(', ')+' }';
+  fail('toml.value'); // TOML has no null; no coercion to string/empty value.
+}
+
+// Select source spans by parsed semantic keys, never regex matching source text.
+// Inline ancestor tables cannot be split without editing foreign bytes: refuse.
+function deletionRanges(ast,target) {
+  const ranges=[];
+  const visitPair=(node,base)=>{
+    const key=[...base,...keys(node.key)];
+    if(prefix(target,key))ranges.push(node.range);
+    else if(prefix(key,target))fail('toml.inline-ancestor');
+  };
+  for(const node of ast.body[0].body) {
+    if(node.type==='TOMLKeyValue')visitPair(node,[]);
+    else if(node.type==='TOMLTable') {
+      const key=node.resolvedKey;
+      if(key.some(k=>typeof k!=='string') && prefix(key.filter(k=>typeof k==='string'),target))fail('toml.array-ancestor');
+      if(prefix(target,key)) {
+        if(node.kind!=='standard')fail('toml.array-ancestor');
+        const end=ast.tokens.find(t=>t.range[0]>=node.key.range[1] && t.value===']');
+        if(!end)fail('toml.syntax');
+        ranges.push([node.range[0],end.range[1]]);
+        for(const pair of node.body)ranges.push(pair.range);
+      }else for(const pair of node.body)visitPair(pair,key);
+    }
+  }
+  return ranges;
+}
+
+function normalizeEmptyRoots(value) {
+  for(const root of ['agents','mcp_servers'])if(value[root] && !Array.isArray(value[root]) && Object.keys(value[root]).length===0)delete value[root];
+  return value;
+}
+
+export function reconcileTOMLFields(bytes,requests) {
+  const before=document(bytes),projected=Object.create(null);
+  if(!Array.isArray(requests) || !requests.length || requests.length>1000)fail('toml.requests');
+  for(const request of requests) {
+    requestShape(request,['pointer','present'],['value','managedHash','takeover'],'toml.requests');
+    const [root,name]=parts(request?.pointer),found=selected(before.value,request.pointer);
+    if(found.present){projected[root]??=Object.create(null);projected[root][name]=found.value;}
+  }
+  const reconciled=reconcileFields(projected,requests),ranges=[],additions=[],expected=structuredClone(before.value);
+  const newline=before.text.includes('\r\n')?'\r\n':'\n';
+  for(const decision of reconciled.decisions) {
+    if(decision.action==='preserve')continue;
+    const target=parts(decision.pointer),[root,name]=target;
+    ranges.push(...deletionRanges(before.ast,target));
+    const found=selected(reconciled.value,decision.pointer);
+    if(found.present) {
+      expected[root]??={};expected[root][name]=JSON.parse(JSON.stringify(found.value));
+      additions.push('['+target.map(k=>JSON.stringify(k)).join('.')+']'+newline+
+        Object.keys(found.value).sort().map(k=>JSON.stringify(k)+' = '+literal(found.value[k])+newline).join(''));
+    }else if(expected[root])delete expected[root][name];
+  }
+  let result=before.text;
+  // Consume only the immediate line ending of an owned statement. Never trim
+  // whitespace/comments or blank lines outside its AST range.
+  const ordered=ranges.map(([start,end])=>[start,end+(before.text.startsWith('\r\n',end)?2:before.text[end]==='\n'?1:0)]).sort((a,b)=>b[0]-a[0]);
+  for(let i=0;i<ordered.length;i++) {
+    const [start,end]=ordered[i];
+    if(i && end>ordered[i-1][0])fail('toml.overlap');
+    result=result.slice(0,start)+result.slice(end);
+  }
+  if(additions.length)result+=(result && !result.endsWith('\n')?newline:'')+additions.join('');
+  const output=Buffer.from(result),after=document(output);
+  // Compare full semantics, including foreign Date/NaN/Infinity values. Only
+  // empty implicit root tables may disappear after their last owned child.
+  if(!isDeepStrictEqual(normalizeEmptyRoots(after.value),normalizeEmptyRoots(expected)))fail('toml.postcondition');
+  return {bytes:output,decisions:reconciled.decisions};
+}

package/src/providers/bundles.js

@@ -0,0 +1,42 @@
+import { fail } from '../contracts/parse.js';
+
+// Declarative membership only. Native formats and destination roots stay in
+// trusted compiled adapters; packages cannot provide executable adapters.
+export function resolveProviders(pipeline, workspace) {
+  const assigned = new Set();
+  for (const bundle of Object.values(pipeline.bundles ?? {})) {
+    for (const id of bundle.providers) {
+      if (!Object.hasOwn(pipeline.providers, id)) fail('bundle.provider-absent');
+      if (assigned.has(id)) fail('bundle.overlap');
+      assigned.add(id);
+    }
+  }
+  const providers = new Set(workspace.providers ?? []), bundles = {};
+  for (const key of workspace.bundles ?? []) {
+    const bundle = Object.hasOwn(pipeline.bundles??{},key) ? pipeline.bundles[key] : undefined;
+    if (!bundle) fail('bundle.absent');
+    for (const id of bundle.providers) {
+      if (providers.has(id)) fail('bundle.selection-overlap');
+      providers.add(id);
+    }
+    bundles[key] = structuredClone(bundle);
+  }
+  // A selected standalone member of a declared bundle would create a second
+  // lifecycle for the same entry. Old sources without bundles still work.
+  if ((workspace.providers ?? []).some(id => assigned.has(id))) fail('bundle.select-bundle');
+  return { providers: [...providers].sort(), ...(Object.keys(bundles).length ? { bundles } : {}) };
+}
+
+export function installedSelection(active) {
+  const members = new Set(Object.values(active.bundles ?? {}).flatMap(b => b.providers));
+  return { providers: active.providers.filter(id => !members.has(id)),
+    ...(active.bundles ? { bundles: Object.keys(active.bundles).sort() } : {}) };
+}
+
+export function validateInstalledBundles(active) {
+  const seen = new Set();
+  for (const bundle of Object.values(active.bundles ?? {})) for (const id of bundle.providers) {
+    if (seen.has(id) || !active.providers.includes(id)) fail('bundle.state-membership');
+    seen.add(id);
+  }
+}

package/src/providers/common-entry.js

@@ -0,0 +1,16 @@
+// Trusted delivery policy, not source-package instructions or runtime isolation.
+export const commonEntryPath = 'CLAUDE.md';
+export const commonEntryText = '@AGENTS.md\n\nRead [AGENTS.md](AGENTS.md) before acting.\nFollow only the provider instructions for your current harness.\nThis shared entry grants no approval and does not enable another provider.\n';
+export const needsCommonEntry = providers => providers.some(id => id === 'claude' || id === 'grok');
+
+// Replay old installed bytes for doctor/repair/remove. Fresh plans always use
+// the current format. Adapter versions are installer metadata, not task gates.
+export const legacyEntryReplay = context => context.installedAdapterVersions !== undefined &&
+  ['claude', 'grok'].filter(id => context.workspace.providers.includes(id))
+    .every(id => context.installedAdapterVersions[id] === '1');
+
+export function removedWithProviders(owned, selection) {
+  if (owned.owner === 'shared' && owned.path === commonEntryPath)
+    return !needsCommonEntry(selection.remaining);
+  return selection.owners.includes(owned.owner);
+}

package/src/providers/grok.js

@@ -0,0 +1,26 @@
+import { fail, MAX_INPUT_BYTES } from '../contracts/parse.js';
+import { sourceText } from './source.js';
+import { skills, agents, mcp } from './native.js';
+
+// Direct component rendering only. Compatibility isolation requires the separate
+// launch path; installing these files does not certify an ordinary `grok` launch.
+const capabilities = Object.freeze(['skills', 'agents', 'mcp', 'entry-instructions']);
+function render(context) {
+  const declaration = context.pipeline.providers.grok;
+  if (!declaration || declaration.requires.some(value => !capabilities.includes(value))) fail('provider.unsupported');
+  const requests = [];
+  if (declaration.skills !== null) requests.push(...skills(context, 'grok', declaration.skills));
+  if (declaration.agents !== null) requests.push(...agents(context, 'grok', declaration.agents).requests);
+  if (declaration.mcp !== null) requests.push({ owner: 'grok', path: '.grok/config.toml',
+    kind: 'toml-fields', fields: mcp(context, 'grok', declaration.mcp) });
+  // The common AGENTS.md owner supplies the provider instruction link.
+  if (declaration.entryInstructions !== null) {
+    const value = sourceText(context, declaration.entryInstructions);
+    if (!value.trim() || value.includes('\0') || Buffer.byteLength(value) > MAX_INPUT_BYTES) fail('provider.format');
+  }
+  return requests;
+}
+export const grokAdapter = Object.freeze({ id: 'grok', version: '2', capabilities,
+  async validate(context) { render(context); return { valid: true, runtime: 'not-run' }; },
+  async plan(context) { return render(context); },
+});

package/src/providers/interface.js

@@ -0,0 +1,25 @@
+import { fail } from '../contracts/parse.js';
+
+export const CAPABILITIES = Object.freeze(['skills', 'agents', 'mcp', 'entry-instructions', 'compatibility-isolation']);
+export const COMPONENTS = Object.freeze({ skills: 'skills', agents: 'agents', mcp: 'mcp', entryInstructions: 'entry-instructions' });
+export function requiredCapabilities(declaration) {
+  const required = new Set(declaration.requires);
+  let components = 0;
+  for (const [field, capability] of Object.entries(COMPONENTS)) {
+    if (declaration[field] !== null) { required.add(capability); components++; }
+    else if (required.has(capability)) fail('provider.required-null');
+  }
+  if (components === 0) fail('provider.empty');
+  return [...required].sort();
+}
+// Trusted CLI adapters only. Never dynamically import code from a pipeline package.
+export function assertAdapter(adapter, id, declaration) {
+  if (!adapter || adapter.id !== id || typeof adapter.version !== 'string' || !adapter.version ||
+      !Array.isArray(adapter.capabilities) ||
+      adapter.capabilities.some(c => !CAPABILITIES.includes(c)) ||
+      new Set(adapter.capabilities).size !== adapter.capabilities.length ||
+      typeof adapter.validate !== 'function' || typeof adapter.plan !== 'function') fail('provider.interface');
+  for (const c of requiredCapabilities(declaration))
+    if (!adapter.capabilities.includes(c)) fail('provider.unsupported');
+  return adapter;
+}

package/src/providers/kimi.js

@@ -0,0 +1,26 @@
+import { fail, MAX_INPUT_BYTES } from '../contracts/parse.js';
+import { sourceText } from './source.js';
+import { skills, agents, mcp } from './native.js';
+
+// Direct, workspace-local delivery. No plugin installation, mutable cache,
+// account settings, trust grants or harness invocation.
+const capabilities = Object.freeze(['skills', 'agents', 'mcp', 'entry-instructions']);
+function render(context) {
+  const declaration = context.pipeline.providers.kimi;
+  if (!declaration || declaration.requires.some(value => !capabilities.includes(value))) fail('provider.unsupported');
+  const requests = [];
+  if (declaration.skills !== null) requests.push(...skills(context, 'kimi', declaration.skills));
+  if (declaration.agents !== null) requests.push(...agents(context, 'kimi', declaration.agents).requests);
+  if (declaration.mcp !== null) requests.push({ owner: 'kimi', path: '.kimi-code/mcp.json',
+    kind: 'json-fields', fields: mcp(context, 'kimi', declaration.mcp) });
+  // Shared adapter owns AGENTS.md and its provider entry link.
+  if (declaration.entryInstructions !== null) {
+    const value = sourceText(context, declaration.entryInstructions);
+    if (!value.trim() || value.includes('\0') || Buffer.byteLength(value) > MAX_INPUT_BYTES) fail('provider.format');
+  }
+  return requests;
+}
+export const kimiAdapter = Object.freeze({ id: 'kimi', version: '1', capabilities,
+  async validate(context) { render(context); return { valid: true, runtime: 'not-run' }; },
+  async plan(context) { return render(context); },
+});