@6reduk/workspace-pipeline 0.6.0 → 0.7.0

package/src/desired-state/global-settings.js

@@ -0,0 +1,74 @@
+import path from 'node:path';
+import {homedir,hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+import {mkdir,mkdtemp,writeFile,readFile,readdir,unlink,rmdir,open,rename} from 'node:fs/promises';
+import {fail} from '../contracts/parse.js';
+import {absoluteRoot,inspectDirectory} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {sha256} from '../source/inventory.js';
+import {compileDesiredSettings} from './settings.js';
+
+// userHome is a trusted host/test dependency, never a source manifest field.
+// Cooperative profile lock serializes installations from different workspaces.
+export async function acquireGlobalSettings(operations,{userHome=homedir(),workspace}={}) {
+  if(!operations.length)return null;
+  if(operations.some(op=>op.target!=='grok.user'))fail('desired.global-target');
+  // Validate scope/value declarations before creating profile metadata.
+  compileDesiredSettings('grok.user',null,operations);
+  const root=absoluteRoot(userHome);
+  if(!(await inspectDirectory(root)).exists)fail('desired.profile-missing');
+  const directory=path.join(root,'.grok'),lockDirectory=path.join(directory,'.wpc-config-lock');
+  await inspectDirectory(directory);await mkdir(directory,{recursive:true});await inspectDirectory(directory);
+  try{await mkdir(lockDirectory);}catch(e){if(e.code==='EEXIST')fail('desired.profile-busy');throw e;}
+  const token=randomUUID(),owner=Buffer.from(JSON.stringify({schemaVersion:1,token,pid:process.pid,host:hostname(),
+    createdAt:new Date().toISOString(),workspace:workspace===undefined?null:absoluteRoot(workspace),purpose:'desired-global-settings'})+'\n'),ownerPath=path.join(lockDirectory,'owner');
+  await writeFile(ownerPath,owner,{flag:'wx',mode:0o600});
+  let released=false;
+  async function held() {
+    if(released)fail('desired.profile-lock-released');
+    await inspectDirectory(lockDirectory);
+    const [observed]=await observeTargets(root,['.grok/.wpc-config-lock/owner']);
+    if(observed.bytes===null || !observed.bytes.equals(owner))fail('desired.profile-lock-changed');
+  }
+  async function release() {
+    await held();
+    const names=await readdir(lockDirectory);
+    if(names.length!==1 || names[0]!=='owner')fail('desired.profile-lock-changed');
+    await unlink(ownerPath);await rmdir(lockDirectory);released=true;
+  }
+  try {
+    const relative='.grok/config.toml',filename=path.join(directory,'config.toml');
+    const [initial]=await observeTargets(root,[relative]);
+    const edited=compileDesiredSettings('grok.user',initial.bytes,operations);
+    const beforeHash=initial.bytes===null?null:sha256(initial.bytes);
+    let backupDirectory=null;
+    async function check() {
+      await held();const [current]=await observeTargets(root,[relative]);
+      if((current.bytes===null?null:sha256(current.bytes))!==beforeHash)fail('desired.global-config-changed');
+      return current.bytes;
+    }
+    return {
+      path:filename,changed:edited.changed,release,check,
+      async backup() {
+        const bytes=await check();
+        if(!edited.changed || bytes===null)return null;
+        const parent=path.join(directory,'workspace-pipeline-backups');
+        await inspectDirectory(parent);await mkdir(parent,{recursive:true});await inspectDirectory(parent);
+        backupDirectory=await mkdtemp(path.join(parent,'desired-'));
+        const destination=path.join(backupDirectory,'config.toml');
+        await writeFile(destination,bytes,{flag:'wx',mode:0o600});
+        if(sha256(await readFile(destination))!==beforeHash)fail('desired.backup-verification');
+        return backupDirectory;
+      },
+      async apply() {
+        await check();if(!edited.changed)return;
+        const staging=beforeHash===null?filename:path.join(directory,'config.toml.wpc-'+token+'.tmp');
+        const handle=await open(staging,'wx',0o600);
+        try{await handle.writeFile(edited.bytes);await handle.sync();}finally{await handle.close();}
+        if(beforeHash!==null){await check();await rename(staging,filename);}
+        const [after]=await observeTargets(root,[relative]);
+        if(after.bytes===null || !after.bytes.equals(edited.bytes))fail('desired.global-readback');
+      }
+    };
+  } catch(error){await release();throw error;}
+}

package/src/desired-state/inventory.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {lstat,readdir,readFile} from 'node:fs/promises';
+import {fail} from '../contracts/parse.js';
+import {portablePath} from '../contracts/semantic.js';
+import {absoluteRoot,inspectDirectory,resolveChild} from '../workspace/paths.js';
+
+const hash=bytes=>'sha256:'+createHash('sha256').update(bytes).digest('hex');
+const order=(a,b)=>a.path<b.path?-1:a.path>b.path?1:0;
+const maxFiles=10000,maxBytes=64*1024*1024;
+
+// Compiled manifest and authenticated source map are supplied by the caller.
+// This function performs no writes and copies source buffers before returning.
+export function materializeDesiredFiles(compiled,source) {
+  if(!compiled || compiled.schemaVersion!==2 || !Array.isArray(compiled.files) || !(source instanceof Map))fail('desired.input');
+  const entries=new Map(),aliases=new Map();let bytes=0;
+  function add(name,kind,content) {
+    portablePath(name);
+    const key=name.toLowerCase(),old=entries.get(name);
+    if(aliases.has(key) && aliases.get(key)!==name)fail('desired.case-alias');
+    if(old){if(kind==='directory' && old.kind===kind)return;fail('desired.materialized-overlap');}
+    aliases.set(key,name);const entry={path:name,kind};
+    if(kind==='file') {
+      if(!Buffer.isBuffer(content))fail('desired.source-bytes');
+      bytes+=content.length;if(bytes>maxBytes)fail('desired.byte-limit');
+      entry.bytes=Buffer.from(content);entry.hash=hash(entry.bytes);
+    }
+    entries.set(name,entry);if(entries.size>maxFiles)fail('desired.file-limit');
+  }
+  for(const mapping of compiled.files) {
+    portablePath(mapping.source);portablePath(mapping.target);
+    if(mapping.kind==='file') {
+      if(!source.has(mapping.source))fail('desired.source-missing');
+      add(mapping.target,'file',source.get(mapping.source));
+    } else if(mapping.kind==='directory') {
+      add(mapping.target,'directory');let found=false;
+      for(const [name,content] of source) {
+        portablePath(name);if(!name.startsWith(mapping.source+'/'))continue;
+        found=true;const suffix=name.slice(mapping.source.length+1),parts=suffix.split('/');
+        for(let i=1;i<parts.length;i++)add(mapping.target+'/'+parts.slice(0,i).join('/'),'directory');
+        add(mapping.target+'/'+suffix,'file',content);
+      }
+      // Git has no empty directory entries: a missing source must not become
+      // an empty desired tree that deletes all installed contents.
+      if(!found)fail('desired.source-missing');
+    } else fail('desired.kind');
+  }
+  return {scopes:compiled.files.map(({target,kind})=>({path:target,kind})),entries:[...entries.values()].sort(order)};
+}
+
+// Read-only observation, not a lease or write authorization. Apply must hold
+// its lock and recheck safety. Only declared file scopes are traversed.
+export async function inspectDesiredFiles(workspace,desired) {
+  workspace=absoluteRoot(workspace);
+  if(!(await inspectDirectory(workspace)).exists)fail('desired.workspace-missing');
+  const actual=new Map(),blocked=[];let totalBytes=0,count=0;
+  async function visit(relative,absolute,depth=0) {
+    if(++count>maxFiles || depth>64)fail('desired.file-limit');
+    let stat;
+    try{stat=await lstat(absolute);}catch(error){if(error.code==='ENOENT')return;throw error;}
+    if(stat.isSymbolicLink()){blocked.push({path:relative,reason:'link'});return;}
+    if(stat.isDirectory()) {
+      await inspectDirectory(absolute);actual.set(relative,{path:relative,kind:'directory'});
+      const names=await readdir(absolute),seen=new Set();
+      for(const name of names.sort()) {
+        const child=relative+'/'+name,key=name.toLowerCase();
+        if(seen.has(key)){blocked.push({path:child,reason:'case-alias'});continue;}
+        seen.add(key);
+        if(key==='.git'){blocked.push({path:child,reason:'nested-repository'});continue;}
+        await visit(child,path.join(absolute,name),depth+1);
+      }
+    } else if(stat.isFile()) {
+      if(stat.nlink>1){blocked.push({path:relative,reason:'hardlink'});return;}
+      totalBytes+=stat.size;if(totalBytes>maxBytes)fail('desired.byte-limit');
+      const bytes=await readFile(absolute);
+      if(bytes.length!==stat.size)fail('desired.observation-changed');
+      actual.set(relative,{path:relative,kind:'file',hash:hash(bytes)});
+    } else blocked.push({path:relative,reason:'special-file'});
+  }
+  for(const scope of desired.scopes) {
+    const absolute=resolveChild(workspace,scope.path),parent=await inspectDirectory(path.dirname(absolute));
+    if(!parent.exists)continue;
+    const matches=(await readdir(parent.path)).filter(n=>n.toLowerCase()===path.basename(absolute).toLowerCase());
+    if(matches.length>1 || (matches.length===1 && matches[0]!==path.basename(absolute))) {
+      blocked.push({path:scope.path,reason:'case-alias'});continue;
+    }
+    await visit(scope.path,absolute);
+  }
+  const expected=new Map(desired.entries.map(e=>[e.path,e]));
+  const extra=[],modified=[],missing=[],unchanged=[];
+  for(const [name,want] of expected) {
+    const have=actual.get(name);
+    if(!have){missing.push({path:name,kind:want.kind});continue;}
+    if(have.kind!==want.kind || (want.kind==='file' && have.hash!==want.hash))
+      modified.push({path:name,kind:want.kind,currentKind:have.kind,beforeHash:have.hash??null,desiredHash:want.hash??null});
+    else unchanged.push({path:name,kind:want.kind});
+  }
+  for(const [name,have] of actual)if(!expected.has(name))extra.push(have);
+  return {extra:extra.sort(order),modified:modified.sort(order),missing:missing.sort(order),
+    unchanged:unchanged.sort(order),blocked:blocked.sort(order),ready:blocked.length===0,
+    backupDefault:false,scope:'declared-file-targets-only'};
+}

package/src/desired-state/legacy-state.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import {parse,fail} from '../contracts/parse.js';
+import {validateState} from '../contracts/semantic.js';
+import {sha256,utf8} from '../source/inventory.js';
+import {observeTargets} from '../operations/state.js';
+import {writeCheckedFile,deleteCheckedFile} from '../operations/apply.js';
+
+const configTargets={'.codex/config.toml':'codex.workspace','.claude/settings.local.json':'claude.workspace',
+  '.mcp.json':'claude.mcp','.grok/config.toml':'grok.workspace'};
+
+export function decodeLegacyState(workspace,bytes) {
+  const value=parse(utf8(bytes),'json');validateState(value);
+  if(path.resolve(value.workspace)!==path.resolve(workspace))fail('desired.legacy-workspace');
+  if(value.pending!==null || !value.active || !['ready','drift','conflict'].includes(value.status))fail('desired.legacy-unfinished');
+  const scopes=[],settings=[];
+  for(const owned of value.active.owned) {
+    if(owned.kind==='file')scopes.push({path:owned.path,kind:'file'});
+    else {
+      const target=configTargets[owned.path];
+      if(!target)fail('desired.legacy-field-target');
+      settings.push({target,pointer:owned.pointer,operation:'set',valueHash:owned.managedHash});
+    }
+  }
+  return {value,bytes,hash:sha256(bytes),protectedPaths:Object.values(value.active.layout.repositories).map(repo=>repo.path),
+    ownership:{pipeline:{id:value.active.pipelineId,version:value.active.version},scopes,settings}};
+}
+
+export async function retireLegacyState(lock,legacy) {
+  if(!legacy)return;
+  const history='.pipeline/history/state-v1-'+legacy.hash.slice(7)+'.json';
+  const [existing]=await observeTargets(lock.workspace,[history]);
+  if(existing.bytes===null)await writeCheckedFile(lock,history,null,legacy.bytes);
+  else if(sha256(existing.bytes)!==legacy.hash)fail('desired.legacy-history-conflict');
+  // Preserve the pre-existing operational record as history, not a backup of
+  // overwritten adapter files. Original journals/snapshots are not rewritten.
+  await deleteCheckedFile(lock,'.pipeline/state.json',legacy.hash,async()=>{});
+}

package/src/desired-state/local-settings.js

@@ -0,0 +1,40 @@
+import {fail} from '../contracts/parse.js';
+import {observeTargets} from '../operations/state.js';
+import {sha256} from '../source/inventory.js';
+import {compileDesiredSettings} from './settings.js';
+
+const destinations=Object.freeze({
+  'codex.workspace':'.codex/config.toml',
+  'claude.workspace':'.claude/settings.local.json',
+  'claude.mcp':'.mcp.json',
+  'grok.workspace':'.grok/config.toml'
+});
+
+// Read and compile every configuration before any adapter file is deleted.
+// Global configuration is intentionally not resolved through workspace paths.
+export async function prepareLocalSettings(workspace,settings) {
+  const groups=new Map();
+  for(const operation of settings) {
+    if(!Object.hasOwn(destinations,operation.target))fail('desired.global-settings-not-integrated');
+    if(!groups.has(operation.target))groups.set(operation.target,[]);
+    groups.get(operation.target).push(operation);
+  }
+  const observations=await observeTargets(workspace,[...groups.keys()].map(key=>destinations[key]));
+  const result=[];
+  for(const [target,operations] of groups) {
+    const relative=destinations[target],before=observations.find(o=>o.path===relative).bytes;
+    const edited=compileDesiredSettings(target,before,operations);
+    result.push({path:relative,beforeHash:before===null?null:sha256(before),
+      bytes:edited.bytes,afterHash:sha256(edited.bytes),changed:edited.changed});
+  }
+  return result;
+}
+
+export async function checkLocalSettings(workspace,prepared) {
+  const observed=await observeTargets(workspace,prepared.map(item=>item.path));
+  for(const item of prepared) {
+    const current=observed.find(o=>o.path===item.path);
+    if((current.bytes===null?null:sha256(current.bytes))!==item.beforeHash)fail('desired.config-changed');
+  }
+  return observed;
+}

package/src/desired-state/lock-recovery.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import {homedir,hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+import {readdir,rename,unlink,rmdir} from 'node:fs/promises';
+import {fail,parse} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {absoluteRoot,inspectDirectory} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {assertNoRepositoryPending} from '../operations/repository-pending.js';
+import {withRecoveryLease,assertRecoveryLeaseHeld} from '../operations/recovery-lease.js';
+import {sha256,utf8} from '../source/inventory.js';
+import {readDesiredRecords} from './records.js';
+
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+function liveness(owner) {
+  if(owner.host!==hostname())return 'unknown-host';
+  try{process.kill(owner.pid,0);return 'live-or-reused-pid';}
+  catch(e){return e.code==='ESRCH'?'local-pid-absent':'unknown';}
+}
+function location(workspace,{global=false,userHome=homedir()}={}) {
+  if(typeof global!=='boolean')fail('desired.recovery-options');
+  const root=global?absoluteRoot(userHome):workspace;
+  return {root,relative:global?'.grok/.wpc-config-lock':'.pipeline/lock',
+    filename:global?'owner':'owner.json',purpose:global?'desired-global-settings':'desired-state'};
+}
+async function ownerAt(loc,relative,workspace) {
+  const directory=path.join(loc.root,...relative.split('/'));
+  if(!(await inspectDirectory(directory)).exists)return null;
+  const names=await readdir(directory);
+  if(names.length!==1||names[0]!==loc.filename)fail('desired.recovery-foreign-entry');
+  const [observed]=await observeTargets(loc.root,[relative+'/'+loc.filename]);
+  if(observed.bytes===null)fail('desired.recovery-owner-missing');
+  const owner=parse(utf8(observed.bytes),'json');
+  if(!owner || Object.keys(owner).sort().join(',')!=='createdAt,host,pid,purpose,schemaVersion,token,workspace' ||
+      owner.schemaVersion!==1||owner.purpose!==loc.purpose||owner.workspace!==workspace||!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('desired.recovery-owner-invalid');
+  return {owner,hash:sha256(observed.bytes),liveness:liveness(owner)};
+}
+
+// Read-only: age alone never authorizes release, and signal 0 does not kill.
+export async function inspectDesiredLock(workspace,options={}) {
+  workspace=absoluteRoot(workspace);const loc=location(workspace,options);
+  await assertNoRepositoryPending(workspace);
+  const records=await readDesiredRecords(workspace);
+  const state={installed:records.installed?.hash??null,pending:records.pending?.hash??null};
+  const lock=await ownerAt(loc,loc.relative,workspace);
+  const result={workspace,global:options.global===true,path:path.join(loc.root,...loc.relative.split('/')),state,
+    status:lock===null?'absent':lock.liveness==='local-pid-absent'?'stopped-owner-observed':'owner-unconfirmed',lock};
+  return {...result,digest:contractDigest(result)};
+}
+
+// The existing OS lease serializes recoverers, without another stale lockfile.
+// Rename the exact stale directory atomically; never delete/reuse its old path
+// after rename, since a fresh cooperative writer may immediately acquire it.
+export async function recoverDesiredLock(workspace,expected,options={}) {
+  workspace=absoluteRoot(workspace);const loc=location(workspace,options);
+  return withRecoveryLease(loc.root,async lease=>{
+    let current=await inspectDesiredLock(workspace,options);
+    if(current.digest!==expected.digest)fail('desired.recovery-observation-changed');
+    if(current.status==='absent')return {status:'no-lock',workspace,global:options.global===true};
+    if(current.status!=='stopped-owner-observed')fail('desired.recovery-owner-unconfirmed');
+    current=await inspectDesiredLock(workspace,options);
+    if(current.digest!==expected.digest)fail('desired.recovery-observation-changed');
+    assertRecoveryLeaseHeld(lease);
+    const relative=loc.relative+'-retiring-'+randomUUID(),temporary=path.join(loc.root,...relative.split('/'));
+    await rename(current.path,temporary);
+    try {
+      const saved=await ownerAt(loc,relative,workspace);
+      if(!saved || saved.hash!==current.lock.hash)fail('desired.recovery-retired-mismatch');
+      assertRecoveryLeaseHeld(lease);
+      await unlink(path.join(temporary,loc.filename));
+      await rmdir(temporary); // Never recursively remove unexpected children.
+    }catch(error){error.recovery={lockReleased:true,residualPath:temporary};throw error;}
+    return {status:'lock-retired',workspace,global:options.global===true,
+      next:'Inspect doctor, then explicitly retry reset or remove; operation records and configuration were not changed.'};
+  });
+}

package/src/desired-state/records.js

@@ -0,0 +1,75 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import {fail,parse} from '../contracts/parse.js';
+import {contractDigest,portablePath} from '../contracts/semantic.js';
+import {observeTargets} from '../operations/state.js';
+import {writeCheckedFile,deleteCheckedFile} from '../operations/apply.js';
+import {sha256,utf8} from '../source/inventory.js';
+import {decodeLegacyState,retireLegacyState} from './legacy-state.js';
+import {validateDesiredBinding} from './binding.js';
+
+export const installedPath='.pipeline/desired-install.json';
+export const pendingPath='.pipeline/desired-pending.json';
+const hash={type:'string',pattern:'^sha256:[a-f0-9]{64}$'};
+const validate=new Ajv2020({strict:true}).compile({type:'object',additionalProperties:false,
+  required:['schemaVersion','operationHash','pipeline','providers','scopes','files','settings'],properties:{
+    schemaVersion:{const:1},operationHash:hash,binding:{type:'object'},
+    intent:{enum:['remove','removed']},
+    adapters:{type:'array',minItems:1,uniqueItems:true,items:{type:'string',pattern:'^[a-z][a-z0-9-]{0,62}$'}},
+    pipeline:{type:'object',additionalProperties:false,required:['id','version'],properties:{id:{type:'string'},version:{type:'string'}}},
+    providers:{type:'array',uniqueItems:true,items:{enum:['codex','claude','grok','kimi']}},
+    scopes:{type:'array',maxItems:10000,items:{type:'object',additionalProperties:false,required:['path','kind'],properties:{path:{type:'string'},kind:{enum:['file','directory']}}}},
+    files:{type:'array',maxItems:10000,items:{type:'object',additionalProperties:false,required:['path','kind','hash'],properties:{path:{type:'string'},kind:{enum:['file','directory']},hash:{anyOf:[hash,{type:'null'}]}}}},
+    settings:{type:'array',maxItems:1000,items:{type:'object',additionalProperties:false,required:['target','pointer','operation','valueHash'],properties:{target:{type:'string'},pointer:{type:'string'},operation:{enum:['set','remove']},valueHash:{anyOf:[hash,{type:'null'}]}}}}
+  }});
+
+// Only desired identities/digests, never old contents or secret setting values.
+export function installationRecord(compiled,desired,{protectedPaths,globalConfigPath,binding}) {
+  const files=desired.entries.map(e=>({path:e.path,kind:e.kind,hash:e.hash??null}));
+  const provenance=binding===undefined?{}:{binding:validateDesiredBinding(binding)};
+  return {schemaVersion:1,operationHash:contractDigest({compiled,files,protectedPaths,globalConfigPath,...provenance}),...provenance,
+    pipeline:compiled.pipeline,adapters:compiled.adapters,providers:compiled.providers,scopes:desired.scopes,files,
+    settings:compiled.settings.map(s=>({target:s.target,pointer:s.pointer,operation:s.operation,
+      valueHash:s.operation==='set'?contractDigest(s.value):null}))};
+}
+
+export async function readDesiredRecords(workspace,{allowLegacyMigration=false}={}) {
+  const observations=await observeTargets(workspace,[installedPath,pendingPath,'.pipeline/state.json']);
+  // Migration is explicit; never silently abandon the old lifecycle state.
+  const legacyBytes=observations.find(o=>o.path==='.pipeline/state.json').bytes;
+  if(legacyBytes!==null && !allowLegacyMigration)fail('desired.legacy-migration-required');
+  const result={legacy:legacyBytes===null?null:decodeLegacyState(workspace,legacyBytes)};
+  for(const [key,name] of [['installed',installedPath],['pending',pendingPath]]) {
+    const bytes=observations.find(o=>o.path===name).bytes;
+    if(bytes===null){result[key]=null;continue;}
+    const value=parse(utf8(bytes),'json');
+    if(!validate(value))fail('desired.record-invalid');
+    if(value.intent==='removed' && (key==='pending'||value.scopes.length||value.files.length||value.settings.length||value.providers.length))fail('desired.record-invalid');
+    if(value.intent==='remove' && (key==='installed'||value.files.length||value.settings.some(s=>s.operation!=='remove'||s.target==='grok.user')))fail('desired.record-invalid');
+    if(value.binding!==undefined)validateDesiredBinding(value.binding);
+    for(const e of [...value.scopes,...value.files])portablePath(e.path);
+    result[key]={value,hash:sha256(bytes)};
+  }
+  return result;
+}
+
+export function assertDesiredTransition(records,next) {
+  if(records.pending?.value.intent==='remove' && next.intent!=='remove')fail('desired.finish-remove-before-update');
+  if(records.pending && records.pending.value.operationHash!==next.operationHash)fail('desired.retry-same-source-required');
+  const previous=records.installed?.value??records.legacy?.ownership;
+  if(!previous || previous.intent==='removed')return;
+  if(previous.pipeline.id!==next.pipeline.id)fail('desired.pipeline-switch-not-integrated');
+}
+
+const encode=record=>Buffer.from(JSON.stringify(record,null,2)+'\n');
+export async function beginDesiredInstall(lock,records,next) {
+  if(records.pending)return records.pending.hash;
+  return writeCheckedFile(lock,pendingPath,null,encode(next));
+}
+export async function completeDesiredInstall(lock,records,next,pendingHash) {
+  const completed=next.intent==='remove'?{...next,intent:'removed',scopes:[],files:[],settings:[],providers:[]}:next;
+  const bytes=encode(completed);
+  if(records.installed?.hash!==sha256(bytes))
+    await writeCheckedFile(lock,installedPath,records.installed?.hash??null,bytes);
+  await retireLegacyState(lock,records.legacy);
+  if(pendingHash)await deleteCheckedFile(lock,pendingPath,pendingHash,async()=>{});
+}

package/src/desired-state/removal.js

@@ -0,0 +1,32 @@
+import {fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {observeTargets} from '../operations/state.js';
+import {utf8} from '../source/inventory.js';
+import {parseDesiredWorkspace} from './source.js';
+import {includeRetiredTargets} from './retirement.js';
+
+// Offline full-delivery removal. Historical ownership never grants deletion of
+// repositories. User-wide compatibility remains shared, not workspace-owned.
+export async function prepareDesiredRemoval(workspace,records,protectedPaths=[]) {
+  if(records.pending && records.pending.value.intent!=='remove')fail('desired.finish-install-before-remove');
+  const previous=(records.pending??records.installed)?.value;
+  if(!previous)fail('desired.not-installed');
+  if(previous.intent==='removed')return {alreadyRemoved:true};
+  if(!previous.binding)fail('desired.removal-binding-required');
+  const protectedRoots=new Set(protectedPaths);
+  for(const repo of Object.values(previous.binding.layout.repositories))protectedRoots.add(repo.path);
+  const [entry]=await observeTargets(workspace,['workspace.json']);
+  if(entry.bytes!==null) {
+    const descriptor=parseDesiredWorkspace(utf8(entry.bytes));
+    for(const repo of Object.values(descriptor.layout.repositories))protectedRoots.add(repo.path);
+  }
+  const desired={scopes:[],entries:[]};
+  const retired=includeRetiredTargets(previous,{settings:[]},desired,[...protectedRoots]);
+  const settings=records.pending?previous.settings.map(s=>({target:s.target,pointer:s.pointer,operation:'remove'})):
+    retired.settings.filter(s=>s.target!=='grok.user');
+  const next=records.pending?.value??{...previous,intent:'remove',files:[],
+    settings:settings.map(s=>({...s,valueHash:null})),
+    operationHash:contractDigest({intent:'remove',previous,preserveGlobalSettings:true})};
+  return {alreadyRemoved:false,next,desired:retired.desired,settings,
+    protectedPaths:[...protectedRoots]};
+}

package/src/desired-state/reset.js

@@ -0,0 +1,27 @@
+import {fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {readDesiredRecords} from './records.js';
+import {parseDesiredWorkspace,prepareDesiredWorkspace} from './source.js';
+
+// Reset is restoration of the recorded Git package, not a fetch of today's ref.
+// The source remains declarative: updates keep using its original branch/ref.
+export async function prepareDesiredReset(workspace,text,options={}) {
+  const descriptor=parseDesiredWorkspace(text),records=await readDesiredRecords(workspace);
+  if(records.pending?.value.intent==='remove')fail('desired.finish-remove-before-reset');
+  const record=(records.pending??records.installed)?.value;
+  if(!record?.binding || !record.adapters)fail('desired.reset-binding-required');
+  if(contractDigest(descriptor.pipeline)!==contractDigest(record.binding.source) ||
+      contractDigest(descriptor.layout)!==contractDigest(record.binding.layout) ||
+      contractDigest([...descriptor.adapters].sort())!==contractDigest([...record.adapters].sort()))
+    fail('desired.reset-workspace-different');
+  const pinned={...descriptor,pipeline:{...record.binding.source,ref:record.binding.commit}};
+  const prepared=await prepareDesiredWorkspace(workspace,JSON.stringify(pinned),options);
+  if(prepared.provenance.commit!==record.binding.commit || prepared.provenance.digest!==record.binding.digest)
+    fail('desired.reset-source-mismatch');
+  prepared.input.binding=record.binding;
+  prepared.provenance={source:record.binding.source,commit:record.binding.commit,digest:record.binding.digest};
+  prepared.descriptor=descriptor;
+  prepared.reset={mode:records.pending?'pending-installation':'installed',commit:record.binding.commit};
+  prepared.expectedRecords={installed:records.installed?.hash??null,pending:records.pending?.hash??null};
+  return prepared;
+}

package/src/desired-state/retirement.js

@@ -0,0 +1,37 @@
+import {compileDesiredManifest} from '../contracts/desired-state.js';
+import {compileDesiredSettings} from './settings.js';
+import {fail} from '../contracts/parse.js';
+
+const contains=(parent,child)=>parent===child || child.startsWith(parent+'/');
+
+// Revalidate stored ownership through today's scope policy. A historical record
+// is not a bypass for repository exclusions or config-field permissions.
+export function includeRetiredTargets(previous,compiled,desired,protectedPaths) {
+  if(!previous)return {desired,settings:compiled.settings};
+  const priorSettings=previous.settings.map(s=>({target:s.target,pointer:s.pointer,operation:'remove'}));
+  compileDesiredManifest(JSON.stringify({schemaVersion:2,id:'retirement-check',version:'0.0.0',adapters:{prior:{
+    providers:['codex'],files:previous.scopes.map(s=>({source:'unused',target:s.path,kind:s.kind})),settings:priorSettings
+  }}}),{selected:['prior'],protectedPaths});
+  for(const op of priorSettings)compileDesiredSettings(op.target,null,[op]);
+  const settings=[...compiled.settings,...priorSettings.filter(old=>
+    previous.settings.find(s=>s.target===old.target && s.pointer===old.pointer).operation==='set' &&
+    !compiled.settings.some(s=>s.target===old.target && s.pointer===old.pointer))];
+  const all=[...previous.scopes,...desired.scopes];
+  // Different spellings of intersecting scopes cannot be resolved portably.
+  for(const a of all)for(const b of all) {
+    if(contains(a.path.toLowerCase(),b.path.toLowerCase()) && !contains(a.path,b.path))fail('desired.retirement-case-alias');
+  }
+  const unique=[...new Map(all.map(s=>[s.path,s])).values()];
+  const scopes=unique.filter(s=>!unique.some(parent=>parent.path!==s.path && contains(parent.path,s.path)));
+  const entries=new Map(desired.entries.map(e=>[e.path,e]));
+  // A narrowed former directory still needs structural parents while deleting
+  // its obsolete siblings. Those parents are not new ownership grants.
+  for(const entry of desired.entries) {
+    const parts=entry.path.split('/');
+    for(let i=1;i<parts.length;i++) {
+      const name=parts.slice(0,i).join('/');
+      if(scopes.some(s=>contains(s.path,name)) && !entries.has(name))entries.set(name,{path:name,kind:'directory'});
+    }
+  }
+  return {desired:{scopes,entries:[...entries.values()]},settings};
+}

package/src/desired-state/settings.js

@@ -0,0 +1,125 @@
+import {isDeepStrictEqual} from 'node:util';
+import {parseTOML,getStaticTOMLValue} from 'toml-eslint-parser';
+import {fail,parse,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {utf8} from '../source/inventory.js';
+import {readTOMLField,reconcileTOMLFields,AGENT_CONTROL_KEYS} from '../operations/toml-fields.js';
+
+const compat=['skills','rules','agents','mcps','hooks'];
+const named=/^\/(agents|mcp_servers|mcpServers)\/[a-z][a-z0-9_-]{0,99}$/;
+const object=v=>v!==null && typeof v==='object' && !Array.isArray(v);
+
+// Named configuration destinations, never source-provided absolute filenames.
+// No I/O. This module cannot change auth, models, trust, permissions or hooks.
+export function compileDesiredSettings(target,bytes,operations) {
+  if(bytes!==null && (!Buffer.isBuffer(bytes)||bytes.length>MAX_INPUT_BYTES))fail('desired.config-input');
+  if(!Array.isArray(operations)||!operations.length||operations.length>1000)fail('desired.config-operations');
+  const checked=parse(JSON.stringify(operations),'json');
+  const pointers=[];
+  for(const op of checked) {
+    if(op.target!==target || !['set','remove'].includes(op.operation) ||
+        Object.keys(op).some(k=>!['adapter','target','pointer','operation','value'].includes(k)) ||
+        (op.operation==='set')!==Object.hasOwn(op,'value'))fail('desired.config-operation');
+    const p=op.pointer;
+    if(typeof p!=='string')fail('desired.config-scope');
+    let allowed=false;
+    if(target==='codex.workspace')allowed=named.test(p) && /^\/(agents|mcp_servers)\//.test(p) && !AGENT_CONTROL_KEYS.includes(p.split('/')[2]);
+    if(target==='grok.workspace')allowed=named.test(p) && p.startsWith('/mcp_servers/');
+    if(target==='claude.mcp')allowed=named.test(p) && p.startsWith('/mcpServers/');
+    if(target==='claude.workspace')allowed=p==='/enabledMcpjsonServers';
+    if(target==='grok.user')allowed=compat.some(k=>p==='/compat/claude/'+k);
+    if(!allowed || p.split('/').some(k=>['__proto__','prototype','constructor'].includes(k)))fail('desired.config-scope');
+    if(pointers.some(q=>p===q || p.startsWith(q+'/') || q.startsWith(p+'/')))fail('desired.field-overlap');
+    pointers.push(p);
+    if(op.operation==='set') {
+      if(target==='grok.user' && typeof op.value!=='boolean')fail('desired.config-value');
+      if(target==='claude.workspace' && (!Array.isArray(op.value)||op.value.some(v=>typeof v!=='string')||new Set(op.value).size!==op.value.length))fail('desired.config-value');
+      if(named.test(p) && !object(op.value))fail('desired.config-value');
+    }
+  }
+  if(target==='grok.user')return compatSettings(bytes,checked);
+  if(['codex.workspace','grok.workspace'].includes(target)) {
+    const requests=checked.map(op=>{
+      const current=readTOMLField(bytes,op.pointer);
+      return {pointer:op.pointer,present:op.operation==='set',...(op.operation==='set'?{value:op.value}:{}),
+        managedHash:current.present?contractDigest(current.value):null};
+    });
+    // The old codec is reused only as a syntax-preserving editor. The observed
+    // value is deliberately replaceable; its backup/conflict decisions are not
+    // part of the new installation policy and are not returned.
+    const result=reconcileTOMLFields(bytes,requests);
+    return {bytes:result.bytes,changed:!result.bytes.equals(bytes??Buffer.alloc(0))};
+  }
+  const current=bytes===null?{}:parse(utf8(bytes),'json');
+  if(!object(current))fail('desired.config-shape');
+  const result=structuredClone(current);
+  for(const op of checked) {
+    const parts=op.pointer.slice(1).split('/');let parent=result;
+    for(const key of parts.slice(0,-1)) {
+      if(!Object.hasOwn(parent,key)) {
+        if(op.operation==='remove'){parent=null;break;}
+        parent[key]={};
+      }
+      if(!object(parent[key]))fail('desired.config-ancestor');
+      parent=parent[key];
+    }
+    if(parent!==null) {
+      if(op.operation==='remove')delete parent[parts.at(-1)];
+      else parent[parts.at(-1)]=op.value;
+    }
+  }
+  if(JSON.stringify(result)===JSON.stringify(current))return {bytes:bytes??Buffer.from('{}\n'),changed:false};
+  return {bytes:Buffer.from(JSON.stringify(result,null,2)+'\n'),changed:true};
+}
+
+function compatSettings(bytes,operations) {
+  const text=bytes===null?'':utf8(bytes);
+  let ast,value;try{ast=parseTOML(text,{tomlVersion:'1.0'});value=getStaticTOMLValue(ast);}catch{fail('desired.config-syntax');}
+  if(value.compat!==undefined && !object(value.compat))fail('desired.config-ancestor');
+  if(value.compat?.claude!==undefined && !object(value.compat.claude))fail('desired.config-ancestor');
+  const expected=structuredClone(value),edits=[],seen=new Set(),nl=text.includes('\r\n')?'\r\n':'\n';
+  const changes=operations.filter(op=>{
+    const k=op.pointer.split('/').at(-1),exists=Object.hasOwn(value.compat?.claude??{},k);
+    if(op.operation==='remove'){if(exists)delete expected.compat.claude[k];return exists;}
+    expected.compat??={};expected.compat.claude??={};expected.compat.claude[k]=op.value;
+    return !exists || value.compat.claude[k]!==op.value;
+  });
+  if(!changes.length)return {bytes:bytes??Buffer.alloc(0),changed:false};
+  function pair(node,base) {
+    const keys=[...base,...node.key.keys.map(k=>k.name??k.value)];
+    for(const op of changes) {
+      const wanted=op.pointer.slice(1).split('/');
+      if(keys.length<wanted.length && keys.every((k,i)=>k===wanted[i]))fail('desired.config-inline-ancestor');
+      if(keys.length===wanted.length && keys.every((k,i)=>k===wanted[i])) {
+        seen.add(op.pointer);
+        edits.push(op.operation==='remove'?[...node.range,'']:[...node.value.range,String(op.value)]);
+      }
+    }
+  }
+  let table=null,parentTable=null;
+  for(const node of ast.body[0].body) {
+    if(node.type==='TOMLKeyValue')pair(node,[]);
+    else if(node.type==='TOMLTable') {
+      if(node.resolvedKey.join('.')==='compat.claude')table=node;
+      if(node.resolvedKey.length===1 && node.resolvedKey[0]==='compat')parentTable=node;
+      for(const child of node.body)pair(child,node.resolvedKey);
+    }
+  }
+  const additions=changes.filter(op=>op.operation==='set'&&!seen.has(op.pointer));
+  if(additions.length) {
+    const selected=table??parentTable;
+    if(selected) {
+      if(selected.kind!=='standard')fail('desired.config-ancestor');
+      const end=text.indexOf('\n',selected.key.range[1]),pos=end<0?text.length:end+1;
+      edits.push([pos,pos,(end<0?nl:'')+additions.map(op=>(table?'':'claude.')+
+        op.pointer.split('/').at(-1)+' = '+String(op.value)+nl).join('')]);
+    } else edits.push([0,0,additions.map(op=>op.pointer.slice(1).split('/').join('.')+' = '+String(op.value)+nl).join('')]);
+  }
+  let output=text;
+  for(const [start,end,replacement] of edits.sort((a,b)=>b[0]-a[0]))output=output.slice(0,start)+replacement+output.slice(end);
+  let after;try{after=getStaticTOMLValue(parseTOML(output,{tomlVersion:'1.0'}));}catch{fail('desired.config-postcondition');}
+  function normalize(v){if(v.compat?.claude && !Object.keys(v.compat.claude).length)delete v.compat.claude;if(v.compat && !Object.keys(v.compat).length)delete v.compat;return v;}
+  if(!isDeepStrictEqual(normalize(after),normalize(expected)))fail('desired.config-postcondition');
+  const bom=bytes?.subarray(0,3).equals(Buffer.from([0xef,0xbb,0xbf]));
+  return {bytes:Buffer.from((bom?'\uFEFF':'')+output),changed:true};
+}