@6reduk/workspace-pipeline 0.6.0 → 0.7.0

package/src/commands/desired-setup.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import {fail} from '../contracts/parse.js';
+import {parseDesiredWorkspace} from '../desired-state/source.js';
+
+const valued=new Set(['--workspace','--source','--ref','--subdirectory','--adapters','--repository','--documentation']);
+const switches=new Set(['--yes','--backup','--json','--preview']);
+export function desiredArguments(args) {
+  const values=new Map(),seen=new Set(),repositories=[];
+  for(let i=1;i<args.length;i++) {
+    const flag=args[i];
+    if(!valued.has(flag)&&!switches.has(flag))fail('cli.arguments');
+    if(seen.has(flag)&&flag!=='--repository')fail('cli.arguments');
+    seen.add(flag);
+    if(valued.has(flag)) {
+      const value=args[++i];if(!value||value.startsWith('--'))fail('cli.arguments');
+      if(flag==='--repository')repositories.push(value);else values.set(flag,value);
+    }
+  }
+  return {values,seen,repositories};
+}
+
+// User argv only; source manifests cannot execute code or choose arbitrary homes.
+export function initialDescriptor(workspace,parsed,{cwd=process.cwd()}={}) {
+  const {values,repositories}=parsed,source=values.get('--source');
+  if(!source||!values.has('--adapters'))fail('desired.setup-source-and-adapters-required');
+  const pipeline={type:'git',ref:values.get('--ref')??'HEAD',subdirectory:values.get('--subdirectory')??'.'};
+  if(/^(https|ssh):\/\//.test(source))Object.assign(pipeline,{transport:'remote',url:source});
+  else {
+    if(source.includes('://'))fail('source.url');
+    const relative=path.relative(workspace,path.resolve(cwd,source));
+    if(path.isAbsolute(relative))fail('desired.local-source-different-volume');
+    Object.assign(pipeline,{transport:'local',path:relative.split(path.sep).join('/')||'.'});
+  }
+  function pair(value) {
+    const at=value.indexOf('=');
+    if(at<1||at===value.length-1)fail('desired.layout-argument');
+    return [value.slice(0,at),value.slice(at+1)];
+  }
+  const entries=(repositories.length?repositories:['game=project']).map(pair);
+  if(new Set(entries.map(([id])=>id)).size!==entries.length)fail('desired.layout-argument');
+  const repos=Object.fromEntries(entries.map(([id,p])=>[id,{path:p,role:'code'}]));
+  if(entries.length>1&&!values.has('--documentation'))fail('desired.documentation-required');
+  const [repository,docPath]=pair(values.get('--documentation')??entries[0][0]+'=docs');
+  const descriptor={schemaVersion:2,pipeline,adapters:values.get('--adapters').split(','),
+    layout:{kind:entries.length===1?'single-repo':'multi-repo',repositories:repos,documentation:{repository,path:docPath}}};
+  return parseDesiredWorkspace(JSON.stringify(descriptor));
+}

package/src/commands/dispatch.js

@@ -1,4 +1,5 @@
 import {inspectInstallation} from '../operations/doctor.js';
+import {inspectDesiredInstallation} from '../desired-state/doctor.js';
 import {absoluteRoot} from '../workspace/paths.js';
 import {ContractError,fail} from '../contracts/parse.js';
 import {runRepositoryRecovery} from './repositories.js';
@@ -30,22 +31,32 @@ import {bindCompatibility,unwrapCompatibility,finishCompatibility,doctorCompatib
 import {parseCompat,runCompat} from './compat.js';
 
 export const help=`Workspace Pipeline CLI — development preview
+Desired-state (schema 2, executable):
+       workspace-pipeline recover-lock --workspace <absolute-directory> [--global] [--yes | --preview] [--json]
+       workspace-pipeline reset --workspace <absolute-directory> [--backup] [--yes | --preview] [--json]
+       workspace-pipeline remove --workspace <absolute-directory> [--backup] [--yes | --preview] [--json]
+       workspace-pipeline setup --workspace <existing-absolute-directory> --source <local-Git-path|https-or-ssh-URL> --adapters <comma-separated-ids> [--ref <Git-ref>] [--subdirectory <source-package-path>]
+         [--repository <id=relative-path> ...] [--documentation <id=relative-path>] [--yes | --preview] [--backup] [--json]
+       workspace-pipeline update --workspace <absolute-directory> [--yes | --preview] [--backup] [--json]
+setup defaults to game=project, documentation game=docs; multi-repo requires explicit documentation.
+No backup by default. Whole-owned adapter customizations are replaced. No project move/clone.
+Existing schema-1 and advanced lifecycle commands:
 Usage: workspace-pipeline doctor --workspace <absolute-directory> [--recovery <relative-record>] [--json]
        workspace-pipeline update --workspace <absolute-directory> [--yes | --preview] [--json]
        workspace-pipeline compat claude [recover-lock] [--apply --preview <absolute-json-file>] [--json]
        workspace-pipeline launch grok --workspace <absolute-directory> --executable <absolute-native-executable> [--inspect] [--execute]
-       workspace-pipeline <init|adopt|wrap> --workspace <absolute-directory> --choices <absolute-json-file> [--manifest <absolute-file>] [--network]
+       workspace-pipeline <init|adopt|wrap> --workspace <absolute-directory> --choices <absolute-json-file> [--manifest <absolute-file>]
        workspace-pipeline <init|adopt|wrap> --workspace <absolute-directory> --apply --preview <absolute-json-file>
-       workspace-pipeline <setup|update> --workspace <absolute-directory> [--manifest <absolute-file>] [--network]
+       workspace-pipeline <setup|update> --workspace <absolute-directory> [--manifest <absolute-file>]
        workspace-pipeline <setup|update> --workspace <absolute-directory> --apply --preview <absolute-json-file>
        workspace-pipeline rebind --workspace <absolute-directory> --manifest <absolute-file>
-       workspace-pipeline update --workspace <absolute-directory> --accept-rebind <absolute-json-file> [--network]
+       workspace-pipeline update --workspace <absolute-directory> --accept-rebind <absolute-json-file>
        workspace-pipeline reset --workspace <absolute-directory> --all [--to installed|empty]
        workspace-pipeline reset --workspace <absolute-directory> [--providers <ids>] [--bundles <ids>] [--to installed|empty]
        workspace-pipeline reset --workspace <absolute-directory> --apply --preview <absolute-json-file>
        workspace-pipeline <repair|remove> --workspace <absolute-directory> [--providers <comma-separated-ids>] [--bundles <comma-separated-ids>]
        workspace-pipeline <repair|remove> --workspace <absolute-directory> --apply --preview <absolute-json-file>
-       workspace-pipeline switch --workspace <absolute-directory> --manifest <absolute-file> [--network]
+       workspace-pipeline switch --workspace <absolute-directory> --manifest <absolute-file>
        workspace-pipeline switch --workspace <absolute-directory> --apply --preview <absolute-json-file>
        workspace-pipeline continue --workspace <absolute-directory> --recovery <relative-record>
        workspace-pipeline continue --workspace <absolute-directory> --apply --preview <absolute-json-file>
@@ -59,7 +70,7 @@ Usage: workspace-pipeline doctor --workspace <absolute-directory> [--recovery <r
        workspace-pipeline --help
 
 Migration commands (development preview):
-       workspace-pipeline migration unity preview --workspace <absolute-directory> --manifest <absolute-file> [--network]
+       workspace-pipeline migration unity preview --workspace <absolute-directory> --manifest <absolute-file>
        workspace-pipeline migration unity inspect --workspace <absolute-directory> --recovery <relative-record> --phase <deactivation|installation|recovery|closeout|compensation>
        workspace-pipeline migration unity apply --workspace <absolute-directory> --preview <absolute-file>
 Preview stages Git externally; inspect is read-only/offline. JSON can contain
@@ -85,8 +96,8 @@ Built-in workspace adapters: Codex, Claude, Kimi and Grok (configuration deliver
 Grok Claude-import suppression requires the scoped launch command, not direct grok.
 Kimi/Grok native session discovery remains separately verified; setup is not runtime certification.
 No native plugin installation, global activation, trust grant or MCP invocation.
-Preview may stage Git source outside the workspace; --network explicitly permits
-remote acquisition. Save the complete prepared JSON privately and inspect it
+Preview may stage Git source outside the workspace; selecting a remote source
+permits acquisition during preparation. Save the complete prepared JSON privately and inspect it
 before --apply --preview. It may contain configuration secrets. Apply cannot
 select a new source/manifest or download a replacement for missing staged data.
 No native plugins are installed. Source packages cannot supply executable adapters.
@@ -218,16 +229,15 @@ function parseRepositories(args) {
   const result={command:args[0]==='wrap'?'adopt':args[0]},seen=new Set();
   for(let i=1;i<args.length;i++) {
     const flag=args[i];
-    if(!['--workspace','--manifest','--choices','--apply','--preview','--network','--json'].includes(flag) || seen.has(flag))fail('cli.arguments');
+    if(!['--workspace','--manifest','--choices','--apply','--preview','--json'].includes(flag) || seen.has(flag))fail('cli.arguments');
     seen.add(flag);
     if(flag==='--json')continue;
     if(flag==='--apply'){result.apply=true;continue;}
-    if(flag==='--network'){result.network=true;continue;}
     const value=args[++i];if(value===undefined || value.startsWith('--'))fail('cli.arguments');
     result[{'--workspace':'workspace','--manifest':'manifestPath','--choices':'choicesFile','--preview':'previewFile'}[flag]]=absoluteRoot(value);
   }
   if(!result.workspace)fail('cli.workspace-required');
-  if(result.apply?(!result.previewFile || result.choicesFile || result.manifestPath || result.network):(!result.choicesFile || result.previewFile))fail('cli.arguments');
+  if(result.apply?(!result.previewFile || result.choicesFile || result.manifestPath):(!result.choicesFile || result.previewFile))fail('cli.arguments');
   return result;
 }
 
@@ -235,12 +245,11 @@ function parseLifecycle(args) {
   const result={command:args[0]},seen=new Set(),maintenance=['repair','remove'].includes(args[0]);
   for(let i=1;i<args.length;i++) {
     const flag=args[i];
-    const allowed=['--workspace','--apply','--preview','--json',...(result.command==='update'?['--accept-rebind']:[]),...(result.command==='continue'?['--recovery']:maintenance?result.command==='remove'?['--providers','--bundles']:[]:['--manifest','--network'])];
+    const allowed=['--workspace','--apply','--preview','--json',...(result.command==='update'?['--accept-rebind']:[]),...(result.command==='continue'?['--recovery']:maintenance?result.command==='remove'?['--providers','--bundles']:[]:['--manifest'])];
     if(!allowed.includes(flag) || seen.has(flag))fail('cli.arguments');
     seen.add(flag);
     if(flag==='--json')continue;
     if(flag==='--apply'){result.apply=true;continue;}
-    if(flag==='--network'){result.network=true;continue;}
     const value=args[++i];if(value===undefined || value.startsWith('--'))fail('cli.arguments');
     if(flag==='--recovery') {
       if(!/^\.pipeline\/transactions\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\/recovery\.json$(?![\s\S])/.test(value))fail('recovery.path');
@@ -260,7 +269,7 @@ function parseLifecycle(args) {
   }
   if(!result.workspace)fail('cli.workspace-required');
   if(result.rebindFile && (result.apply || result.manifestPath))fail('cli.arguments');
-    if(result.apply?(!result.previewFile || result.manifestPath || result.network || result.providers || result.bundles):result.previewFile)fail('cli.arguments');
+    if(result.apply?(!result.previewFile || result.manifestPath || result.providers || result.bundles):result.previewFile)fail('cli.arguments');
   if(result.command==='switch' && !result.apply && !result.manifestPath)fail('switch.manifest-required');
   if(result.command==='continue' && (result.apply?result.recoveryPath:!result.recoveryPath))fail('continuation.recovery-required');
   return result;
@@ -277,7 +286,7 @@ async function runLifecycle(command,registry,stdout,stderr,compatibility) {
   if(!command.apply) {
     const input={command:command.command,wrapper:command.workspace};
     if(command.manifestPath)input.manifestPath=command.manifestPath;
-    if(command.network)input.network=true;
+    if(['setup','update','switch'].includes(command.command))input.network=true;
     if(command.providers)input.providers=command.providers;
     if(command.bundles)input.bundles=command.bundles;
     if(command.recoveryPath)input.recoveryPath=command.recoveryPath;
@@ -401,7 +410,7 @@ async function runLogs(command,stdout,stderr) {
   }finally{await lock.release();}
 }
 
-export async function runCli(args,{stdout,stderr,registry=null,compatibility=null}) {
+export async function runCli(args,{stdout,stderr,registry=null,compatibility=null,desiredHostOptions={}}) {
   if(typeof stdout!=='function' || typeof stderr!=='function')fail('cli.transport');
   try {
     const command=parseCommand(args);
@@ -420,7 +429,9 @@ export async function runCli(args,{stdout,stderr,registry=null,compatibility=nul
       ['recover-bootstrap','continue-bootstrap','retire-bootstrap'].includes(command.action)?runBootstrapContinuation:runRepositoryRecovery)(command,stdout);
     if(['setup','update','repair','remove','switch','continue'].includes(command.command))return await runLifecycle(command,registry,stdout,stderr,compatibility);
     const options=command.recoveryPath===undefined?{}:{recoveryPath:command.recoveryPath};
-    const result=await doctorCompatibility(await inspectInstallation(command.workspace,options),compatibility);
+    const desired=await inspectDesiredInstallation(command.workspace,desiredHostOptions);
+    if(desired && command.recoveryPath!==undefined)fail('desired.legacy-recovery-option');
+    const result=desired??await doctorCompatibility(await inspectInstallation(command.workspace,options),compatibility);
     await stdout(JSON.stringify(result)+'\n');
     return result.ready?0:1;
   } catch(error) {

package/src/commands/init.js

@@ -74,7 +74,7 @@ export async function runRepositoryCommand(command,stdout,stderr) {
   if(!command.apply) {
     const choices=(await readRecord(command.choicesFile)).value;
     const prepared=await prepareRepositoryCommand({command:command.command,wrapper:command.workspace,
-      manifestPath:command.manifestPath,choices,network:command.network??false});
+      manifestPath:command.manifestPath,choices,network:true});
     await stdout(JSON.stringify(prepared)+'\n');return prepared.preview.status==='blocked'?1:0;
   }
   const prepared=(await readRecord(command.previewFile)).value;

package/src/commands/migration.js

@@ -18,11 +18,10 @@ const inspectors={deactivation:prepareLegacyUnityDeactivationResume,installation
 export function parseMigrationCommand(args){
  if(args[1]!=='unity'||!['preview','inspect','apply'].includes(args[2]))fail('cli.arguments');
  const result={command:'migration',action:args[2]},seen=new Set();
- const allowed=result.action==='apply'?['--workspace','--preview','--json']:result.action==='preview'?['--workspace','--manifest','--network','--json']:['--workspace','--recovery','--phase','--json'];
+ const allowed=result.action==='apply'?['--workspace','--preview','--json']:result.action==='preview'?['--workspace','--manifest','--json']:['--workspace','--recovery','--phase','--json'];
  for(let i=3;i<args.length;i++){
   const flag=args[i];if(!allowed.includes(flag)||seen.has(flag))fail('cli.arguments');seen.add(flag);
   if(flag==='--json')continue;
-  if(flag==='--network'){result.network=true;continue;}
   const value=args[++i];if(value===undefined||value.startsWith('--'))fail('cli.arguments');
   if(flag==='--workspace')result.workspace=absoluteRoot(value);
   if(flag==='--manifest')result.manifestPath=absoluteRoot(value);
@@ -41,7 +40,7 @@ export async function runMigrationCommand(command,stdout,stderr){
  if(command.action==='apply')return runMigrationApply(command,stdout,stderr);
  await stderr('Migration preview may contain private configuration bytes. Save it locally; do not publish it. Inspect before explicit apply.\n');
  const before=await readInstallerIdentity();
- const result=command.action==='preview'?await prepareLegacyUnityPreview({wrapper:command.workspace,manifestPath:command.manifestPath,network:command.network===true,
+ const result=command.action==='preview'?await prepareLegacyUnityPreview({wrapper:command.workspace,manifestPath:command.manifestPath,network:true,
   tempRoot:await mkdtemp(path.join(tmpdir(),'wpc-migration-prepare-'))}):
   await inspectors[command.phase](command.workspace,command.recoveryPath);
  const bound=await bindMigrationInstaller(result);

package/src/commands/output.js

@@ -12,6 +12,16 @@ export function formatResult(value) {
     if (value.pipeline) lines.push(`Pipeline: ${safe(value.pipeline.id)} @ ${safe(value.pipeline.version)}`,
       `Providers: ${value.pipeline.providers.map(safe).join(', ')}`);
     for (const key of ['configuration', 'transactionEvidence']) if (value[key] !== undefined) lines.push(`${key}: ${safe(value[key])}`);
+    if(value.binding) lines.push(`Git source: ${safe(value.binding.source.url??value.binding.source.path)}`,
+      `Git revision: ${safe(value.binding.commit)}`, `Source digest: ${safe(value.binding.digest)}`);
+    if(value.files) {
+      lines.push('', 'Adapter files (changes that setup/update may replace):');
+      for(const [key,label] of [['extra','Extra — removed'],['modified','Modified — overwritten'],['missing','Missing — installed'],['blocked','Unsafe — requires attention']]) {
+        const items=value.files[key]??[];lines.push(`  ${label}: ${items.length}`);
+        for(const item of items)lines.push(`    ${safe(item.path)}${item.reason?' ('+safe(item.reason)+')':''}`);
+      }
+      lines.push('Backups are off by default; use --backup when applying.');
+    }
     if(value.compatibility)lines.push(`Grok / Claude compatibility: ${safe(value.compatibility.status)}`,
       ...(value.compatibility.path?[`User config: ${safe(value.compatibility.path)}`]:[]),
       ...(value.compatibility.blockers??[]).map(b=>`  - ${safe(b)}`),

package/src/contracts/desired-state.js

@@ -0,0 +1,56 @@
+import {readFileSync} from 'node:fs';
+import Ajv2020 from 'ajv/dist/2020.js';
+import {fail, parse} from './parse.js';
+import {portablePath} from './semantic.js';
+
+const schema = JSON.parse(readFileSync(new URL('../../schemas/pipeline-v2.schema.json', import.meta.url), 'utf8'));
+const validate = new Ajv2020({strict:true, strictRequired:false, ownProperties:true}).compile(schema);
+const configPaths = ['workspace.json', '.codex/config.toml', '.claude/settings.local.json', '.mcp.json', '.grok/config.toml'];
+const overlap = (a,b) => a===b || a.startsWith(b+'/') || b.startsWith(a+'/');
+const folded = value => value.toLowerCase();
+
+// Pure compilation only: no filesystem access to source/workspace, no authority
+// to apply. Filesystem/reparse checks and config-field permissions belong to the
+// later materialization boundary. Accept serialized data, never executable objects.
+export function compileDesiredManifest(text, {selected, protectedPaths=[]}={}) {
+  const manifest = parse(text, 'json');
+  if (!validate(manifest)) fail('desired.schema');
+  if (!Array.isArray(selected) || !selected.length || new Set(selected).size!==selected.length ||
+      selected.some(id=>typeof id!=='string' || !Object.hasOwn(manifest.adapters,id))) fail('desired.selection');
+  if (!Array.isArray(protectedPaths)) fail('desired.protected-paths');
+  for (const p of protectedPaths) portablePath(p);
+  const files=[], settings=[], providers=new Set();
+  // Validate paths even in unselected adapters; reject a malformed source early.
+  // Common payload is installed once regardless of selected provider count.
+  // $shared cannot be a user adapter ID under the schema's identifier rule.
+  const deliveries=[['$shared',{providers:[],files:manifest.files??[],settings:[]}],...Object.entries(manifest.adapters)];
+  for (const [id,adapter] of deliveries) {
+    for (const file of adapter.files) {
+      portablePath(file.source); portablePath(file.target);
+      const target=folded(file.target);
+      if (['.git','.pipeline',...configPaths,...protectedPaths].some(p=>overlap(target,folded(p)))) fail('desired.scope');
+    }
+    for (const item of adapter.settings) {
+      if (!item.pointer.startsWith('/') || /~(?![01])/.test(item.pointer)) fail('desired.pointer');
+      const tokens=item.pointer.slice(1).split('/').map(p=>p.replace(/~1/g,'/').replace(/~0/g,'~'));
+      if (tokens.some(p=>!p || ['__proto__','constructor','prototype'].includes(p))) fail('desired.pointer');
+    }
+    if (id!=='$shared' && !selected.includes(id)) continue;
+    for (const provider of adapter.providers) {
+      if (providers.has(provider)) fail('desired.provider-overlap');
+      providers.add(provider);
+    }
+    files.push(...adapter.files.map(f=>({...f,adapter:id})));
+    settings.push(...adapter.settings.map(s=>({...s,adapter:id})));
+  }
+  for (let i=0;i<files.length;i++) for (let j=0;j<i;j++) {
+    if (overlap(folded(files[i].target),folded(files[j].target))) fail('desired.target-overlap');
+  }
+  for (let i=0;i<settings.length;i++) for (let j=0;j<i;j++) {
+    if (settings[i].target===settings[j].target && overlap(settings[i].pointer,settings[j].pointer)) fail('desired.field-overlap');
+  }
+  return {schemaVersion:2, pipeline:{id:manifest.id,version:manifest.version},
+    adapters:[...selected].sort(),providers:[...providers].sort(),
+    files:files.sort((a,b)=>a.target.localeCompare(b.target,'en')),
+    settings:settings.sort((a,b)=>(a.target+a.pointer).localeCompare(b.target+b.pointer,'en'))};
+}

package/src/desired-state/apply-files.js

@@ -0,0 +1,172 @@
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {lstat,readFile,mkdir,mkdtemp,writeFile,unlink,rmdir} from 'node:fs/promises';
+import {compileDesiredManifest} from '../contracts/desired-state.js';
+import {fail} from '../contracts/parse.js';
+import {inspectDirectory,pathBudget} from '../workspace/paths.js';
+import {acquireWorkspaceLock,assertLockHeld} from '../operations/lock.js';
+import {materializeDesiredFiles,inspectDesiredFiles} from './inventory.js';
+import {prepareLocalSettings,checkLocalSettings} from './local-settings.js';
+import {writeCheckedFile} from '../operations/apply.js';
+import {acquireGlobalSettings} from './global-settings.js';
+import {installationRecord,readDesiredRecords,assertDesiredTransition,beginDesiredInstall,completeDesiredInstall} from './records.js';
+import {includeRetiredTargets} from './retirement.js';
+import {bindDesiredSource} from './binding.js';
+import {observeTargets} from '../operations/state.js';
+import {prepareDesiredRemoval} from './removal.js';
+
+const digest=bytes=>'sha256:'+createHash('sha256').update(bytes).digest('hex');
+const depth=name=>name.split('/').length;
+
+// Internal engine. Legacy migration and public command authorization remain
+// separate. hostOptions (including fault-injection boundary) are trusted code.
+export async function applyDesiredFiles({workspace,manifest,selected,protectedPaths,source,binding,backup=false},hostOptions={}) {
+  if(typeof backup!=='boolean' || !Array.isArray(protectedPaths))fail('desired.apply-options');
+  const removing=hostOptions.removeExisting===true;
+  const compiled=removing?null:compileDesiredManifest(manifest,{selected,protectedPaths});
+  const delivered=removing?null:materializeDesiredFiles(compiled,source);
+  if(!removing)binding=bindDesiredSource(binding,source);
+  const lock=await acquireWorkspaceLock(workspace,{purpose:'desired-state'});
+  workspace=lock.workspace;
+  let backupDirectory=null,globalBackupDirectory=null,global=null,mutations=0;
+  try {
+    const records=await readDesiredRecords(workspace,{allowLegacyMigration:hostOptions.migrateLegacy===true});
+    if(hostOptions.expectedRecords &&
+        (hostOptions.expectedRecords.installed!==(records.installed?.hash??null) ||
+         hostOptions.expectedRecords.pending!==(records.pending?.hash??null)))fail('desired.installation-state-changed');
+    if(removing && hostOptions.removalExpected &&
+        (hostOptions.removalExpected.installed!==(records.installed?.hash??null) ||
+         hostOptions.removalExpected.pending!==(records.pending?.hash??null)))fail('desired.removal-state-changed');
+    const previousRoots=Object.values(records.installed?.value.binding?.layout.repositories??{}).map(r=>r.path);
+    const protectedDuringMigration=[...new Set([...protectedPaths,...previousRoots,...(records.legacy?.protectedPaths??[])])];
+    if(!removing)compileDesiredManifest(manifest,{selected,protectedPaths:protectedDuringMigration});
+    const removal=removing?await prepareDesiredRemoval(workspace,records,protectedDuringMigration):null;
+    if(removal?.alreadyRemoved)return {status:'removed',mutations:0,backupDirectory:null,globalSettings:'preserved'};
+    const retirement=removal??includeRetiredTargets(records.installed?.value??records.legacy?.ownership,compiled,delivered,protectedDuringMigration);
+    const desired=retirement.desired;
+    const report=await inspectDesiredFiles(workspace,desired);
+    if(!report.ready)fail('desired.unsafe-target');
+    const localOperations=retirement.settings.filter(op=>op.target!=='grok.user');
+    const settings=await prepareLocalSettings(workspace,localOperations);
+    global=await acquireGlobalSettings(retirement.settings.filter(op=>op.target==='grok.user'),{...hostOptions,workspace});
+    const next=removal?.next??installationRecord(compiled,delivered,{protectedPaths,binding,
+      globalConfigPath:compiled.settings.some(op=>op.target==='grok.user')?global?.path??null:null});
+    assertDesiredTransition(records,next);
+    const createDescriptor=!removing && hostOptions.createDescriptor===true;
+    if(createDescriptor) {
+      if(!binding)fail('desired.setup-binding-required');
+      const [entry]=await observeTargets(workspace,['workspace.json']);
+      if(entry.bytes!==null)fail('desired.setup-already-configured');
+    }
+    async function saveDescriptor() {
+      if(!createDescriptor)return;
+      const descriptor={schemaVersion:2,pipeline:binding.source,adapters:compiled.adapters,layout:binding.layout};
+      mutations++;
+      await writeCheckedFile(lock,'workspace.json',null,Buffer.from(JSON.stringify(descriptor,null,2)+'\n'));
+    }
+    const changedSettings=settings.filter(item=>item.changed);
+    const filesChanged=Boolean(report.extra.length || report.modified.length || report.missing.length);
+    if(!filesChanged && !changedSettings.length && !global?.changed) {
+      const pendingHash=createDescriptor||removing?await beginDesiredInstall(lock,records,next):records.pending?.hash??null;
+      await saveDescriptor();
+      await completeDesiredInstall(lock,records,next,pendingHash);
+      return {status:removing?'removed':mutations?'applied':'unchanged',backupDirectory:null,mutations,...(removing?{globalSettings:'preserved'}:{})};
+    }
+    const expected=new Map(desired.entries.map(e=>[e.path,e]));
+    const current=[...report.extra,
+      ...report.modified.map(e=>({path:e.path,kind:e.currentKind,hash:e.beforeHash})),
+      ...report.unchanged.map(e=>({path:e.path,kind:e.kind,hash:expected.get(e.path).hash}))];
+    function target(name) {
+      // Observed custom filenames may be Unicode, unlike source manifest paths.
+      if(typeof name!=='string' || name.split('/').some(p=>!p || p==='.' || p==='..' || p.toLowerCase()==='.git') ||
+          /[\\:\u0000-\u001f\u007f]/.test(name))fail('desired.observed-path');
+      if(!desired.scopes.some(s=>name===s.path || name.startsWith(s.path+'/')))fail('desired.scope');
+      const result=path.resolve(workspace,...name.split('/')),rel=path.relative(workspace,result);
+      if(!rel || rel==='..' || rel.startsWith('..'+path.sep) || path.isAbsolute(rel))fail('desired.scope');
+      pathBudget(result);return result;
+    }
+    async function check(entry) {
+      await assertLockHeld(lock);
+      const file=target(entry.path);
+      await inspectDirectory(path.dirname(file));
+      const stat=await lstat(file);
+      if(stat.isSymbolicLink() || (entry.kind==='file' && (!stat.isFile() || stat.nlink>1)) ||
+          (entry.kind==='directory' && !stat.isDirectory()))fail('desired.target-changed');
+      if(entry.kind==='file') {
+        const bytes=await readFile(file);
+        if(digest(bytes)!==entry.hash)fail('desired.target-changed');
+        return bytes;
+      }
+      await inspectDirectory(file);return null;
+    }
+    // Validate the complete observed set before optional backup or deletion.
+    for(const entry of current)await check(entry);
+    await checkLocalSettings(workspace,settings);
+    await global?.check();
+    const pendingHash=await beginDesiredInstall(lock,records,next);
+    await saveDescriptor();
+    await hostOptions.boundary?.('before-content');
+    if(backup) {
+      const parent=path.join(workspace,'.pipeline','backups');
+      await inspectDirectory(parent);await mkdir(parent,{recursive:true});await inspectDirectory(parent);
+      backupDirectory=await mkdtemp(path.join(parent,'desired-'));
+      for(const entry of current.sort((a,b)=>depth(a.path)-depth(b.path))) {
+        const bytes=await check(entry),destination=path.join(backupDirectory,...entry.path.split('/'));
+        await mkdir(path.dirname(destination),{recursive:true});
+        if(entry.kind==='directory')await mkdir(destination,{recursive:true});
+        else {
+          await writeFile(destination,bytes,{flag:'wx',mode:0o600});
+          if(digest(await readFile(destination))!==entry.hash)fail('desired.backup-verification');
+        }
+      }
+      // Shared configs may contain secrets: backups stay private/local and are
+      // made only on explicit request. Their contents are never put in reports.
+      const observed=await checkLocalSettings(workspace,settings);
+      for(const item of changedSettings.filter(item=>item.beforeHash!==null)) {
+        const destination=path.join(backupDirectory,...item.path.split('/'));
+        await mkdir(path.dirname(destination),{recursive:true});
+        await writeFile(destination,observed.find(o=>o.path===item.path).bytes,{flag:'wx',mode:0o600});
+        if(digest(await readFile(destination))!==item.beforeHash)fail('desired.backup-verification');
+      }
+      globalBackupDirectory=await global?.backup()??null;
+    }
+    await checkLocalSettings(workspace,settings);
+    await global?.check();
+    // Enumerated, non-recursive deletion: unexpected new directory contents make
+    // rmdir fail instead of being swept away. No old contents retained by default.
+    for(const entry of (filesChanged?current:[]).sort((a,b)=>depth(b.path)-depth(a.path))) {
+      await check(entry);
+      if(entry.kind==='directory')await rmdir(target(entry.path));
+      else await unlink(target(entry.path));
+      mutations++;
+      await hostOptions.boundary?.('after-delete');
+    }
+    for(const entry of (filesChanged?[...desired.entries]:[]).sort((a,b)=>depth(a.path)-depth(b.path))) {
+      await assertLockHeld(lock);
+      const file=target(entry.path);
+      await inspectDirectory(path.dirname(file));
+      await mkdir(path.dirname(file),{recursive:true});await inspectDirectory(path.dirname(file));
+      if(entry.kind==='directory')await mkdir(file);
+      else await writeFile(file,entry.bytes,{flag:'wx',mode:0o600});
+      mutations++;
+    }
+    for(const item of changedSettings) {
+      // Count attempted writes conservatively: an I/O failure can follow a
+      // successful rename or a partially written new file.
+      mutations++;
+      await writeCheckedFile(lock,item.path,item.beforeHash,item.bytes);
+    }
+    if(global?.changed){mutations++;await global.apply();}
+    const after=await inspectDesiredFiles(workspace,desired);
+    if(!after.ready || after.extra.length || after.modified.length || after.missing.length)fail('desired.readback');
+    const settingsAfter=await prepareLocalSettings(workspace,localOperations);
+    if(settingsAfter.some(item=>item.changed))fail('desired.config-readback');
+    await hostOptions.boundary?.('before-record');
+    await completeDesiredInstall(lock,records,next,pendingHash);
+    return {status:removing?'removed':'applied',backupDirectory,globalBackupDirectory,globalConfigPath:global?.path??null,mutations,...(removing?{globalSettings:'preserved'}:{})};
+  } catch(error) {
+    // Partial application is explicit; there is no implicit rollback promise.
+    error.desiredState={status:mutations?'partial':'not-applied',mutations,backupDirectory,globalBackupDirectory};
+    throw error;
+  } finally {try{await global?.release();}finally{await lock.release();}}
+}

package/src/desired-state/binding.js

@@ -0,0 +1,23 @@
+import {fail,parse} from '../contracts/parse.js';
+import {validateStructure} from '../contracts/validate.js';
+import {contractDigest,validateLayoutReferences} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+
+// Provenance of an acquired Git package, not a signature or a pin on project rules.
+export function validateDesiredBinding(value) {
+  const binding=parse(JSON.stringify(value),'json');
+  if(!binding || Object.keys(binding).sort().join(',')!=='commit,digest,layout,source' ||
+      !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(binding.commit) ||
+      !/^sha256:[a-f0-9]{64}$/.test(binding.digest))fail('desired.binding-invalid');
+  validateStructure('workspace',{schemaVersion:1,pipeline:binding.source,providers:['codex'],layout:binding.layout});
+  validateLayoutReferences(binding.layout);
+  return binding;
+}
+
+export function bindDesiredSource(value,source) {
+  if(value===undefined)return undefined; // Internal fixtures/older records may lack Git provenance.
+  const binding=validateDesiredBinding(value);
+  const actual=contractDigest(Object.fromEntries([...source].map(([name,bytes])=>[name,sha256(bytes)])));
+  if(actual!==binding.digest)fail('desired.binding-source-mismatch');
+  return binding;
+}

package/src/desired-state/doctor.js

@@ -0,0 +1,106 @@
+import {homedir} from 'node:os';
+import {parseTOML,getStaticTOMLValue} from 'toml-eslint-parser';
+import {parse,fail,ContractError,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {readTOMLField} from '../operations/toml-fields.js';
+import {utf8} from '../source/inventory.js';
+import {readDesiredRecords,installedPath,pendingPath} from './records.js';
+import {includeRetiredTargets} from './retirement.js';
+import {inspectDesiredFiles} from './inventory.js';
+import {parseDesiredWorkspace} from './source.js';
+import {inspectDesiredLock} from './lock-recovery.js';
+
+const paths={
+  'codex.workspace':'.codex/config.toml','claude.workspace':'.claude/settings.local.json',
+  'claude.mcp':'.mcp.json','grok.workspace':'.grok/config.toml','grok.user':'.grok/config.toml'
+};
+function field(bytes,setting) {
+  if(bytes===null)return {present:false};
+  if(bytes.length>MAX_INPUT_BYTES)fail('desired.config-size');
+  if(['codex.workspace','grok.workspace'].includes(setting.target))return readTOMLField(bytes,setting.pointer);
+  let value;
+  if(setting.target==='grok.user') {
+    try{value=getStaticTOMLValue(parseTOML(utf8(bytes),{tomlVersion:'1.0'}));}catch{fail('desired.config-syntax');}
+  } else value=parse(utf8(bytes),'json');
+  for(const part of setting.pointer.slice(1).split('/')) {
+    if(value===null || typeof value!=='object' || Array.isArray(value))fail('desired.config-ancestor');
+    if(!Object.hasOwn(value,part))return {present:false};
+    value=value[part];
+  }
+  return {present:true,value};
+}
+
+// Read-only and local: no source fetch, lock, settings change, harness or MCP.
+// null routes old-format installations to the existing doctor implementation.
+export async function inspectDesiredInstallation(workspace,{userHome=homedir(),protectedPaths=[]}={}) {
+  workspace=absoluteRoot(workspace);
+  const markers=await observeTargets(workspace,[installedPath,pendingPath]);
+  if(markers.every(item=>item.bytes===null))return null;
+  const records=await readDesiredRecords(workspace),record=(records.pending??records.installed).value;
+  if(record.intent==='removed')return {workspace,ready:false,status:'not-installed',
+    pipeline:{...record.pipeline,providers:[]},binding:record.binding??null,configuration:'not-installed',
+    diagnostics:[{code:'desired.not-installed',subject:installedPath}],globalSettings:'preserved',
+    limits:'Delivery removed; saved workspace declaration and shared user settings were preserved. No runtime checks.'};
+  const diagnostics=[];
+  const locks=[];
+  for(const global of [false,...(record.settings.some(s=>s.target==='grok.user')?[true]:[])]) {
+    const target=global?'global':'workspace';
+    try {
+      const observed=await inspectDesiredLock(workspace,{userHome,global});
+      locks.push({target,path:observed.path,status:observed.status});
+      if(observed.status!=='absent')diagnostics.push({code:'desired.'+target+'-lock-present',subject:observed.path});
+    }catch(error){
+      locks.push({target,status:'unverified'});
+      diagnostics.push({code:error instanceof ContractError?error.code:'desired.lock-read',subject:target+' lock'});
+    }
+  }
+  const protectedRoots=new Set(protectedPaths);
+  if(record.binding) {
+    for(const repo of Object.values(record.binding.layout.repositories))protectedRoots.add(repo.path);
+    try {
+      const [entry]=await observeTargets(workspace,['workspace.json']);
+      if(entry.bytes===null)diagnostics.push({code:'desired.workspace-missing',subject:'workspace.json'});
+      else {
+        const descriptor=parseDesiredWorkspace(utf8(entry.bytes));
+        for(const repo of Object.values(descriptor.layout.repositories))protectedRoots.add(repo.path);
+        if(contractDigest(descriptor.pipeline)!==contractDigest(record.binding.source) ||
+            contractDigest(descriptor.layout)!==contractDigest(record.binding.layout) ||
+            (record.adapters && contractDigest([...descriptor.adapters].sort())!==contractDigest([...record.adapters].sort())))
+          diagnostics.push({code:'desired.workspace-different',subject:'workspace.json'});
+      }
+    }catch(error){
+      diagnostics.push({code:'desired.workspace-invalid',subject:'workspace.json',
+        reason:error instanceof ContractError?error.code:'desired.workspace-read'});
+    }
+  }
+  const desired={scopes:record.scopes,entries:record.files};
+  includeRetiredTargets(record,{settings:[]},desired,[...protectedRoots]);
+  const files=await inspectDesiredFiles(workspace,desired);
+  if(records.pending)diagnostics.push({code:'desired.installation-incomplete',subject:pendingPath});
+  for(const [category,items] of Object.entries(files)) {
+    if(!['extra','modified','missing','blocked'].includes(category))continue;
+    for(const item of items)diagnostics.push({code:'desired.file-'+category,subject:item.path,...(item.reason?{reason:item.reason}:{})});
+  }
+  const cache=new Map(),settings=[];
+  for(const setting of record.settings) {
+    try {
+      if(!cache.has(setting.target)) {
+        const [observed]=await observeTargets(setting.target==='grok.user'?absoluteRoot(userHome):workspace,[paths[setting.target]]);
+        cache.set(setting.target,observed.bytes);
+      }
+      const found=field(cache.get(setting.target),setting);
+      const matches=setting.operation==='remove'?!found.present:found.present && contractDigest(found.value)===setting.valueHash;
+      settings.push({target:setting.target,pointer:setting.pointer,status:matches?'pass':'different'});
+      if(!matches)diagnostics.push({code:'desired.setting-different',subject:setting.target,pointer:setting.pointer});
+    }catch(error){
+      settings.push({target:setting.target,pointer:setting.pointer,status:'unverified'});
+      diagnostics.push({code:error instanceof ContractError?error.code:'desired.config-read',subject:setting.target,pointer:setting.pointer});
+    }
+  }
+  return {workspace,ready:diagnostics.length===0,status:records.pending?'incomplete':diagnostics.length?'drift':'ready',
+    pipeline:{...record.pipeline,providers:record.providers},binding:record.binding??null,configuration:diagnostics.length?'fail':'pass',
+    diagnostics,files,settings,locks,backupDefault:false,
+    limits:'Installed-record comparison only; no source authenticity, runtime, model-visible skills or MCP certification.'};
+}