@6reduk/workspace-pipeline 0.5.0 → 0.7.0

package/src/commands/desired-remove.js

@@ -0,0 +1,48 @@
+import {ContractError,fail} from '../contracts/parse.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {readDesiredRecords,installedPath,pendingPath} from '../desired-state/records.js';
+import {prepareDesiredRemoval} from '../desired-state/removal.js';
+import {inspectDesiredFiles} from '../desired-state/inventory.js';
+import {prepareLocalSettings} from '../desired-state/local-settings.js';
+import {applyDesiredFiles} from '../desired-state/apply-files.js';
+import {desiredArguments} from './desired-setup.js';
+import {safeTerminalText as safe} from './output.js';
+
+export async function tryDesiredRemove(args,options,{isTTY=false,confirm,display,hostOptions={}}={}) {
+  if(args[0]!=='remove')return null;
+  const at=args.indexOf('--workspace');if(at<0||!args[at+1])return null;
+  try {
+    const workspace=absoluteRoot(args[at+1]);
+    const markers=await observeTargets(workspace,[installedPath,pendingPath]);
+    if(markers.every(m=>m.bytes===null))return null;
+    const {seen}=desiredArguments(args);
+    if([...seen].some(f=>!['--workspace','--preview','--yes','--json','--backup'].includes(f)))fail('cli.arguments');
+    const dry=seen.has('--preview'),yes=seen.has('--yes');
+    if(dry&&yes)fail('cli.arguments');
+    if(!dry&&!yes&&(!isTTY||!confirm))fail('cli.confirmation-required');
+    const records=await readDesiredRecords(workspace),prepared=await prepareDesiredRemoval(workspace,records);
+    if(prepared.alreadyRemoved){await options.stdout(JSON.stringify({workspace,status:'removed',applied:false,globalSettings:'preserved'})+'\n');return 0;}
+    const files=await inspectDesiredFiles(workspace,prepared.desired);
+    const local=await prepareLocalSettings(workspace,prepared.settings);
+    const summary={command:'remove',workspace,status:'preview',applied:false,files,
+      localSettings:local.map(s=>({path:s.path,changed:s.changed})),backup:seen.has('--backup'),globalSettings:'preserved',
+      preserved:['workspace.json','project repositories','.pipeline journals and backups']};
+    if(dry){await options.stdout(JSON.stringify(summary)+'\n');return files.ready?0:1;}
+    const lines=['Workspace Pipeline — remove',`Workspace: ${safe(workspace)}`,`Backup: ${summary.backup?'enabled':'OFF'}`,
+      'Remove all recorded adapter files, including custom files inside owned directories.',
+      'Preserve repositories, workspace.json, journals/backups and shared global settings.'];
+    for(const item of files.extra)lines.push(`  remove: ${safe(item.path)}`);
+    for(const item of files.blocked)lines.push(`  blocked: ${safe(item.path)}`);
+    for(const item of summary.localSettings)lines.push(`  settings: ${safe(item.path)} (${item.changed?'remove owned fields':'unchanged'})`);
+    if(display)await display(lines.join('\n')+'\n');else await options.stderr(lines.join('\n')+'\n');
+    if(!files.ready)fail('desired.unsafe-target');
+    if(!yes&&await confirm()!==true){await options.stdout(JSON.stringify({status:'cancelled',applied:false})+'\n');return 0;}
+    const result=await applyDesiredFiles({workspace,protectedPaths:prepared.protectedPaths,backup:summary.backup},
+      {...hostOptions,removeExisting:true,removalExpected:{installed:records.installed?.hash??null,pending:records.pending?.hash??null}});
+    await options.stdout(JSON.stringify({...result,workspace,preserved:summary.preserved})+'\n');return 0;
+  }catch(error){
+    await options.stderr(JSON.stringify({error:error instanceof ContractError?error.code:'cli.desired-remove-io',
+      ...(error.desiredState?{application:error.desiredState}:{})})+'\n');return 2;
+  }
+}

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,21 +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>
@@ -58,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
@@ -84,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.
@@ -217,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;
 }
 
@@ -234,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');
@@ -259,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;
@@ -276,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;
@@ -400,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);
@@ -419,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/interactive-update.js

@@ -0,0 +1,59 @@
+import {mkdtemp,writeFile,unlink,rmdir} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+import {runCli,parseCommand} from './dispatch.js';
+import {safeTerminalText as safe} from './output.js';
+
+export function updateSummary(saved){
+  const p=saved.kind==='prepared-with-claude-compatibility'?saved.workspace:saved;
+  const plan=p.preview.plan;
+  const lines=['Workspace Pipeline — update',`Workspace: ${safe(plan.workspace)}`,
+    `Pipeline: ${safe(plan.desired.pipelineId)} @ ${safe(plan.desired.version)}`,
+    `Providers: ${plan.desired.providers.map(safe).join(', ')}`,`Changes: ${plan.targets.length}`];
+  for(const t of plan.targets)lines.push(`  ${safe(t.action)}  ${safe(t.path)}`);
+  const c=saved.compatibility;
+  if(c){lines.push(`Grok global compatibility: ${safe(c.status)}`);
+    if(c.path)lines.push(`  Config: ${safe(c.path)}`);
+    for(const k of c.changes??[])lines.push(`  compat.claude.${safe(k)} = true`);
+    for(const b of c.blockers??[])lines.push(`  BLOCKED: ${safe(b)}`);
+    if(c.warning)lines.push(safe(c.warning));
+  }
+  lines.push('No automatic reset. Apply rechecks files and approval before writing.');
+  return lines.join('\n')+'\n';
+}
+
+// Human-facing entry only. runCli remains the deterministic preview/apply API.
+export async function runInteractiveUpdate(args,options,{isTTY=false,confirm,display,execute=runCli}={}){
+  if(args[0]!=='update'||args.includes('--apply'))return execute(args,options);
+  const yes=args.includes('--yes'),dry=args.includes('--preview');
+  const clean=args.filter(x=>x!=='--yes'&&x!=='--preview');
+  if(args.filter(x=>x==='--yes').length>1||args.filter(x=>x==='--preview').length>1||(yes&&dry)){
+    await options.stdout(JSON.stringify({error:'cli.arguments'})+'\n');return 2;
+  }
+  // --json alone retains the existing machine preview contract; it never authorizes writes.
+  if(dry||(args.includes('--json')&&!yes))return execute(clean,options);
+  try{parseCommand(clean);}catch{return execute(clean,options);}
+  if(!yes&&(!isTTY||!confirm)){
+    await options.stdout(JSON.stringify({error:'cli.confirmation-required',next:'Use an interactive terminal, --yes to apply, or --preview --json for a saved plan.'})+'\n');return 2;
+  }
+  let raw='';
+  const code=await execute(clean,{...options,stdout:async text=>{raw+=text;}});
+  if(code!==0){if(raw)await options.stdout(raw);return code;}
+  const saved=JSON.parse(raw);
+  await display(updateSummary(saved));
+  if(saved.compatibility?.status==='blocked'){
+    await options.stdout(JSON.stringify({status:'blocked',error:'grok-compat.blocked'})+'\n');return 1;
+  }
+  if(!yes&&await confirm()!==true){await options.stdout(JSON.stringify({status:'cancelled',applied:false})+'\n');return 0;}
+  // Feed the exact approved bytes through the same public saved-preview verifier.
+  const dir=await mkdtemp(path.join(tmpdir(),'wpc-approved-update-'));
+  const file=path.join(dir,'preview.json');
+  try{
+    await writeFile(file,raw,{flag:'wx',mode:0o600});
+    const command=parseCommand(clean);
+    return await execute(['update','--workspace',command.workspace,'--apply','--preview',file],options);
+  }finally{
+    // Only our one named temporary file, never a recursive workspace cleanup.
+    await unlink(file).catch(()=>{});await rmdir(dir).catch(()=>{});
+  }
+}

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

@@ -1,6 +1,7 @@
 // Presentation boundary only: internal command results and saved JSON contracts
 // remain unchanged. Never infer success from the shape of a rendered result.
-const safe = value => String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+export const safeTerminalText = value => String(value).replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+const safe = safeTerminalText;
 const privateKey = /bytes|base64|content|secret|token|password/i;
 
 export function formatResult(value) {
@@ -11,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;
+}