@6reduk/workspace-pipeline 0.1.0

package/src/migrations/legacy-unity-finalize.js

@@ -0,0 +1,88 @@
+import {assertMigrationLockHeld} from '../operations/lock.js';
+import {readRecord,readState,observeTargets} from '../operations/state.js';
+import {inspectRecovery,writeCheckedFile,deleteCheckedFile} from '../operations/apply.js';
+import {resolveChild} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {fail} from '../contracts/parse.js';
+import {verifyLegacyUnityDeactivationJournal} from './legacy-unity-install.js';
+
+// Read-only installed-phase verification. This never issues a write capability.
+export async function inspectInstalledLegacyUnityMigration(workspace,payload){
+  const stored=await readRecord(resolveChild(workspace,payload.recoveryPath));
+  if(stored.digest!==payload.recoveryHash)fail('migration.recovery-drift');
+  const preview=stored.value.preview;
+  const phase=await verifyLegacyUnityDeactivationJournal(workspace,payload.recoveryPath,payload.recoveryHash,preview);
+  const locator=await readRecord(resolveChild(workspace,payload.recoveryPath.replace(/recovery\.json$/,'installation.json')));
+  const native=await readRecord(resolveChild(workspace,locator.value.recoveryPath));
+  const body={kind:'prepared-plan',preview:preview.setup,stateFileHash:null,rebind:null,
+   preparation:{objects:preview.preflight.supply.objectsPath,snapshot:preview.preflight.supply.snapshotPath},runtime:'not-run'};
+  const digest=contractDigest(body);
+  if(contractDigest(native.value.prepared)!==contractDigest({...body,digest}) || native.value.previous!==null ||
+   contractDigest(native.value.approval)!==contractDigest({decision:'approve',preparedDigest:digest}))fail('migration.install-binding');
+  let selectedPath=locator.value.recoveryPath,selected=native,continuationHash=null;
+  const continuationPath=payload.recoveryPath.replace(/recovery\.json$/,'installation-continuation.json');
+  if((await observeTargets(workspace,[continuationPath]))[0].bytes!==null){
+   const pointer=await readRecord(resolveChild(workspace,continuationPath));
+   const authorizationPath=payload.recoveryPath.replace(/recovery\.json$/,'installation-continuation-authorization.json');
+   const authorization=await readRecord(resolveChild(workspace,authorizationPath)),a=authorization.value,p=a.preview;
+   if(!p||a.kind!=='legacy-unity-install-recovery-authorization'||a.schemaVersion!==1)fail('migration.continuation-binding');
+   const {digest:approvedDigest,...approvedBody}=p;
+   if(contractDigest(approvedBody)!==approvedDigest||contractDigest(a.approval)!==contractDigest({decision:'approve',previewDigest:approvedDigest})||
+    p.workspace!==workspace||p.recoveryPath!==payload.recoveryPath||p.recoveryHash!==payload.recoveryHash||p.locatorHash!==locator.digest||
+    contractDigest(p.phase)!==contractDigest(phase)||p.continuation?.evidence?.recoveryPath!==locator.value.recoveryPath||
+    p.continuation.evidence.recoveryHash!==native.digest)fail('migration.continuation-binding');
+   selectedPath=pointer.value.recoveryPath;
+   if(typeof selectedPath!=='string'||!/^\.pipeline\/transactions\/[a-f0-9-]{36}\/recovery\.json$/.test(selectedPath))fail('migration.continuation-binding');
+   const expectedPointer={schemaVersion:1,kind:'legacy-unity-install-continuation',migrationRecoveryHash:payload.recoveryHash,
+    authorizationPath,authorizationHash:authorization.digest,preparedDigest:p.continuation.digest,recoveryPath:selectedPath,
+    journal:selectedPath.replace('/transactions/','/journals/').replace('/recovery.json','')};
+   if(contractDigest(pointer.value)!==contractDigest(expectedPointer))fail('migration.continuation-binding');
+   selected=await readRecord(resolveChild(workspace,selectedPath));
+   if(contractDigest(selected.value.prepared)!==contractDigest(p.continuation)||
+    contractDigest(selected.value.approval)!==contractDigest({decision:'approve',preparedDigest:p.continuation.digest}))fail('migration.continuation-binding');
+   continuationHash=pointer.digest;
+  }
+  const checked=await inspectRecovery(workspace,selectedPath);
+  const expected={schemaVersion:1,kind:'legacy-unity-installation',migrationRecoveryHash:payload.recoveryHash,
+   preparedDigest:digest,deactivation:preview.preflight.deactivation.digest,
+   journal:locator.value.recoveryPath.replace('/transactions/','/journals/').replace('/recovery.json',''),recoveryPath:locator.value.recoveryPath};
+  if(contractDigest(locator.value)!==contractDigest(expected) || checked.recoveryHash!==selected.digest)fail('migration.install-binding');
+  if(continuationHash&&(checked.lineage.length!==1||checked.lineage[0].recovery!==locator.value.recoveryPath||checked.lineage[0].recoveryHash!==native.digest))fail('migration.continuation-binding');
+  if(checked.status!=='applied'||checked.statePhase!=='active'||checked.diagnostics.length)fail('migration.install-incomplete');
+  const state=await readState(resolveChild(workspace,'.pipeline/state.json'));
+  if(contractDigest(state.value.activation)!==contractDigest({recovery:selectedPath,
+   recoveryHash:selected.digest,journalHead:checked.journalHead}))fail('migration.activation-binding');
+  // Native exact target verification covers final configs (including opt-outs).
+  // Legacy binding markers are not native targets and must also remain unchanged.
+  const markers=preview.preflight.observations.filter(o=>o.path.startsWith('.unity-sdd/'));
+  for(const row of await observeTargets(workspace,markers.map(o=>o.path))){
+   const expected=markers.find(o=>o.path===row.path);
+   if(row.bytes===null||sha256(row.bytes)!==expected.sha256)fail('migration.legacy-marker-drift');
+  }
+  return {migrationRecoveryHash:stored.digest,installationLocatorHash:locator.digest,
+   deactivationHead:phase.head,stateHash:state.digest,nativeRecoveryHash:selected.digest,native:checked,
+   ...(continuationHash?{continuationHash,originalNativeRecoveryHash:native.digest}:{})};
+}
+
+// Internal same-process closeout. Restart authorization/recovery is separate.
+export async function finalizeLegacyUnityMigration(lock,payload,{boundary=async()=>{}}={}){
+ const check=async()=>{
+  await assertMigrationLockHeld(lock,payload.recoveryPath,payload.recoveryHash);
+  return inspectInstalledLegacyUnityMigration(lock.workspace,payload);
+ };
+ const verified=await check();
+ const completionPath=payload.recoveryPath.replace(/recovery\.json$/,'completion.json');
+ const bytes=Buffer.from(JSON.stringify({schemaVersion:1,kind:'legacy-unity-completion',
+  workspace:lock.workspace,...verified,runtime:'not-run'})+'\n');
+ await writeCheckedFile(lock,completionPath,null,bytes);
+ await boundary('completion-recorded');
+ if(contractDigest(await check())!==contractDigest(verified))fail('migration.completion-drift');
+ if((await readRecord(resolveChild(lock.workspace,completionPath))).digest!==sha256(bytes))fail('migration.completion-drift');
+ await deleteCheckedFile(lock,payload.markerPath,payload.markerHash,async phase=>{
+  if(phase==='before-delete')await boundary('before-marker-removal');
+ });
+ // Marker removal deliberately invalidates the sealed migration capability.
+ // Caller can release it, but cannot perform further migration writes.
+ return {status:'completed',completionPath,completionHash:sha256(bytes),runtime:'not-run'};
+}

package/src/migrations/legacy-unity-install-recovery.js

@@ -0,0 +1,76 @@
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {readRecord,observeTargets} from '../operations/state.js';
+import {prepareContinuation} from '../operations/reconciliation.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {fail} from '../contracts/parse.js';
+import {verifyLegacyUnityDeactivationJournal} from './legacy-unity-install.js';
+import {createLegacyUnityInstallRecoveryLease} from './legacy-unity-lease.js';
+import {acquireWorkspaceLock} from '../operations/lock.js';
+import {applyContinuation,writeCheckedFile} from '../operations/apply.js';
+
+// Read-only wrapper around the existing native continuation planner. No retry,
+// outcome rewriting, migration lease, native write or source acquisition.
+export async function prepareLegacyUnityInstallRecovery(workspace,recoveryPath){
+ workspace=absoluteRoot(workspace);
+ if(typeof recoveryPath!=='string'||!/^\.pipeline\/migrations\/[a-f0-9-]{36}\/recovery\.json$/.test(recoveryPath))fail('migration.recovery-path');
+ if((await observeTargets(workspace,[recoveryPath.replace(/recovery\.json$/,'installation-continuation.json')]))[0].bytes!==null)fail('migration.continuation-started');
+ const original=await readRecord(resolveChild(workspace,recoveryPath)),r=original.value,p=r.preview;
+ if(r.schemaVersion!==1||r.kind!=='legacy-unity-recovery'||r.workspace!==workspace||p?.workspace!==workspace||
+  recoveryPath!==`.pipeline/migrations/${r.id}/recovery.json`)fail('migration.recovery-binding');
+ const {digest,...body}=p;
+ if(contractDigest(body)!==digest||contractDigest(r.approval)!==contractDigest({decision:'approve',previewDigest:digest}))fail('migration.preview-binding');
+ const markerPath='.pipeline/migration-operation.json',marker=await readRecord(resolveChild(workspace,markerPath));
+ if(contractDigest(marker.value)!==contractDigest({schemaVersion:1,kind:'legacy-unity-pending',workspace,recoveryPath,
+  recoveryHash:original.digest,previewDigest:digest}))fail('migration.marker-binding');
+ const phase=await verifyLegacyUnityDeactivationJournal(workspace,recoveryPath,original.digest,p);
+ const locatorPath=recoveryPath.replace(/recovery\.json$/,'installation.json'),locator=await readRecord(resolveChild(workspace,locatorPath));
+ const nativePath=locator.value.recoveryPath;
+ if(typeof nativePath!=='string'||!/^\.pipeline\/transactions\/[a-f0-9-]{36}\/recovery\.json$/.test(nativePath))fail('migration.install-binding');
+ const native=await readRecord(resolveChild(workspace,nativePath));
+ const preparedBody={kind:'prepared-plan',preview:p.setup,stateFileHash:null,rebind:null,
+  preparation:{objects:p.preflight.supply.objectsPath,snapshot:p.preflight.supply.snapshotPath},runtime:'not-run'};
+ const preparedDigest=contractDigest(preparedBody);
+ if(contractDigest(native.value.prepared)!==contractDigest({...preparedBody,digest:preparedDigest})||native.value.previous!==null||
+  contractDigest(native.value.approval)!==contractDigest({decision:'approve',preparedDigest}))fail('migration.install-binding');
+ const continuation=await prepareContinuation(workspace,nativePath);
+ if(continuation.evidence.recoveryHash!==native.digest||contractDigest(locator.value)!==contractDigest({schemaVersion:1,
+  kind:'legacy-unity-installation',migrationRecoveryHash:original.digest,preparedDigest,deactivation:p.preflight.deactivation.digest,
+  journal:continuation.evidence.journal,recoveryPath:nativePath}))fail('migration.install-binding');
+ // These legacy markers are outside native ownership and continuation checks.
+ const bindings=p.preflight.observations.filter(o=>o.path.startsWith('.unity-sdd/'));
+ for(const row of await observeTargets(workspace,bindings.map(o=>o.path)))
+  if(row.bytes===null||sha256(row.bytes)!==bindings.find(o=>o.path===row.path).sha256)fail('migration.legacy-marker-drift');
+ for(const record of [{path:recoveryPath,hash:original.digest},{path:markerPath,hash:marker.digest},
+  {path:locatorPath,hash:locator.digest},{path:nativePath,hash:native.digest}])
+  if((await readRecord(resolveChild(workspace,record.path))).digest!==record.hash)fail('migration.resume-drift');
+ if(contractDigest(await verifyLegacyUnityDeactivationJournal(workspace,recoveryPath,original.digest,p))!==contractDigest(phase)||
+  (await prepareContinuation(workspace,nativePath)).digest!==continuation.digest)fail('migration.resume-drift');
+ const result={schemaVersion:1,kind:'legacy-unity-install-recovery-preview',workspace,recoveryPath,recoveryHash:original.digest,
+  markerHash:marker.digest,locatorHash:locator.digest,phase,continuation,status:'needs-approval',executable:false,runtime:'not-run'};
+ return {...result,digest:contractDigest(result)};
+}
+
+export async function applyLegacyUnityInstallRecovery(proposal,approval,workspace,options={}){
+ const {lease,preview}=await createLegacyUnityInstallRecoveryLease(proposal,approval,workspace);
+ const lock=await acquireWorkspaceLock(workspace,{migrationOperation:lease});
+ try{
+  if(contractDigest(await prepareLegacyUnityInstallRecovery(lock.workspace,preview.recoveryPath))!==contractDigest(preview))fail('migration.resume-drift');
+  const authorizationPath=preview.recoveryPath.replace(/recovery\.json$/,'installation-continuation-authorization.json');
+  const bytes=Buffer.from(JSON.stringify({schemaVersion:1,kind:'legacy-unity-install-recovery-authorization',preview,
+   approval:{decision:'approve',previewDigest:preview.digest}})+'\n');
+  await writeCheckedFile(lock,authorizationPath,null,bytes);
+  const locatorPath=preview.recoveryPath.replace(/recovery\.json$/,'installation-continuation.json');
+  const result=await applyContinuation(lock,preview.continuation,{decision:'approve',preparedDigest:preview.continuation.digest},{
+   ...options,onJournal:async location=>{
+    if(location.status!=='planned')return;
+    const recoveryPath=`.pipeline/transactions/${location.relative.split('/').at(-1)}/recovery.json`;
+    await writeCheckedFile(lock,locatorPath,null,Buffer.from(JSON.stringify({schemaVersion:1,kind:'legacy-unity-install-continuation',
+     migrationRecoveryHash:preview.recoveryHash,authorizationPath,authorizationHash:sha256(bytes),
+     preparedDigest:preview.continuation.digest,recoveryPath,journal:location.relative})+'\n'));
+   }
+  });
+  if((await readRecord(resolveChild(lock.workspace,authorizationPath))).digest!==sha256(bytes))fail('migration.authorization-drift');
+  return {status:'needs-reconciliation',installationStatus:result.status,recoveryPath:result.recoveryPath,authorizationPath,runtime:'not-run'};
+ }finally{await lock.release();}
+}

package/src/migrations/legacy-unity-install-resume.js

@@ -0,0 +1,60 @@
+import {randomUUID} from 'node:crypto';
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {readRecord,observeTargets,verifyPreparedSnapshot} from '../operations/state.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {fail} from '../contracts/parse.js';
+import {verifyLegacyUnityDeactivationJournal,executeLegacyUnityInstall} from './legacy-unity-install.js';
+import {createLegacyUnityInstallResumeLease,legacyUnityLeasePayload} from './legacy-unity-lease.js';
+import {acquireWorkspaceLock} from '../operations/lock.js';
+import {writeCheckedFile} from '../operations/apply.js';
+
+export async function prepareLegacyUnityInstallResume(workspace,recoveryPath){
+ workspace=absoluteRoot(workspace);
+ if(typeof recoveryPath!=='string'||!/^\.pipeline\/migrations\/[a-f0-9-]{36}\/recovery\.json$/.test(recoveryPath))fail('migration.recovery-path');
+ const record=await readRecord(resolveChild(workspace,recoveryPath)),r=record.value,p=r.preview;
+ if(r.schemaVersion!==1||r.kind!=='legacy-unity-recovery'||r.workspace!==workspace||p?.workspace!==workspace||
+  recoveryPath!==`.pipeline/migrations/${r.id}/recovery.json`)fail('migration.recovery-binding');
+ const {digest,...body}=p;
+ if(contractDigest(body)!==digest||contractDigest(r.approval)!==contractDigest({decision:'approve',previewDigest:digest}))fail('migration.preview-binding');
+ const markerPath='.pipeline/migration-operation.json',marker=await readRecord(resolveChild(workspace,markerPath));
+ if(contractDigest(marker.value)!==contractDigest({schemaVersion:1,kind:'legacy-unity-pending',workspace,recoveryPath,recoveryHash:record.digest,previewDigest:digest}))fail('migration.marker-binding');
+ const absent=[recoveryPath.replace(/recovery\.json$/,'installation.json'),'.pipeline/state.json'];
+ for(const o of await observeTargets(workspace,absent))if(o.bytes!==null)fail('migration.install-started');
+ const phase=await verifyLegacyUnityDeactivationJournal(workspace,recoveryPath,record.digest,p);
+ const expected=new Map(p.initialObservations.map(o=>[o.path,o.hash]));
+ for(const o of p.preflight.observations){
+  if(expected.has(o.path)&&expected.get(o.path)!==o.sha256)fail('migration.observation-binding');
+  expected.set(o.path,o.sha256);
+ }
+ for(const t of p.preflight.deactivation.targets)expected.set(t.path,t.afterHash);
+ const observe=async()=>{
+  const rows=await observeTargets(workspace,[...expected.keys()]);
+  const hashes=rows.map(o=>({path:o.path,hash:o.bytes===null?null:sha256(o.bytes)}));
+  if(hashes.some(o=>o.hash!==expected.get(o.path)))fail('migration.observation-drift');
+  return hashes;
+ };
+ const observations=await observe(),s=p.preflight.supply;
+ await verifyPreparedSnapshot({snapshotPath:s.snapshotPath,manifest:{id:'unity-sdd',version:s.version},digest:s.digest,inventoryDigest:s.inventoryDigest});
+ if(contractDigest(await observe())!==contractDigest(observations)||
+  contractDigest(await verifyLegacyUnityDeactivationJournal(workspace,recoveryPath,record.digest,p))!==contractDigest(phase)||
+  (await readRecord(resolveChild(workspace,recoveryPath))).digest!==record.digest||
+  (await readRecord(resolveChild(workspace,markerPath))).digest!==marker.digest)fail('migration.resume-drift');
+ for(const o of await observeTargets(workspace,absent))if(o.bytes!==null)fail('migration.install-started');
+ const result={schemaVersion:1,kind:'legacy-unity-install-resume-preview',workspace,recoveryPath,
+  recoveryHash:record.digest,markerHash:marker.digest,phase,observations,setup:p.setup,status:'needs-approval',executable:false,runtime:'not-run'};
+ return {...result,digest:contractDigest(result)};
+}
+
+export async function applyLegacyUnityInstallResume(proposal,approval,workspace,options={}){
+ const {lease,preview}=await createLegacyUnityInstallResumeLease(proposal,approval,workspace);
+ const lock=await acquireWorkspaceLock(workspace,{migrationOperation:lease});
+ try{
+  if(contractDigest(await prepareLegacyUnityInstallResume(lock.workspace,preview.recoveryPath))!==contractDigest(preview))fail('migration.resume-drift');
+  const authorizationPath=preview.recoveryPath.replace(/recovery\.json$/,`install-authorizations/${randomUUID()}.json`);
+  await writeCheckedFile(lock,authorizationPath,null,Buffer.from(JSON.stringify({schemaVersion:1,kind:'legacy-unity-install-authorization',
+   preview,approval:{decision:'approve',previewDigest:preview.digest}})+'\n'));
+  const result=await executeLegacyUnityInstall(lock,legacyUnityLeasePayload(lease,lock.workspace),options);
+  return {...result,authorizationPath};
+ }finally{await lock.release();}
+}

package/src/migrations/legacy-unity-install.js

@@ -0,0 +1,88 @@
+import {readdir} from 'node:fs/promises';
+import {readRecord,observeTargets} from '../operations/state.js';
+import {assertMigrationLockHeld} from '../operations/lock.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {applyPrepared,writeCheckedFile} from '../operations/apply.js';
+import {assertRecoveryBudget} from '../operations/plan.js';
+import {providerRegistry} from '../providers/registry.js';
+import {validateLegacyUnityDeactivation} from './legacy-unity.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {parse,fail} from '../contracts/parse.js';
+import {verifyLegacyUnityResumedEvidence} from './legacy-unity-resumed-evidence.js';
+
+// Require complete first-phase evidence, not merely disabled settings.
+export async function verifyLegacyUnityDeactivationJournal(workspace,recoveryPath,recoveryHash,preview){
+ const resumed=await verifyLegacyUnityResumedEvidence(workspace,recoveryPath,recoveryHash,preview);
+ if(resumed)return resumed;
+ const phase=validateLegacyUnityDeactivation(preview.preflight.deactivation);
+ const directory=recoveryPath.replace(/recovery\.json$/,'deactivation');
+ await inspectDirectory(resolveChild(workspace,directory));
+ const names=(await readdir(resolveChild(workspace,directory))).sort();
+ if(names.join(',')!=='000000.json,000001.json,000002.json,000003.json,000004.json,000005.json')fail('migration.phase-incomplete');
+ const expected=[{kind:'start',detail:null}];
+ for(const t of phase.targets)expected.push(
+  {kind:'intent',detail:{path:t.path,beforeHash:t.beforeHash,afterHash:t.afterHash}},
+  {kind:'outcome',detail:{path:t.path,status:'completed',observedHash:t.afterHash}});
+ expected.push({kind:'phase-checked',detail:{phase:'deactivate-legacy'}});
+ let previous=null;
+ for(let seq=0;seq<expected.length;seq++){
+  const actual=await readRecord(resolveChild(workspace,directory+'/'+names[seq]));
+  const event={schemaVersion:1,seq,previous,recoveryHash,...expected[seq]};
+  if(contractDigest(actual.value)!==contractDigest(event))fail('migration.phase-evidence');
+  previous=actual.digest;
+ }
+ return {directory,head:previous};
+}
+
+// Trusted compiled adapters remain authoritative. The only extra requests are
+// exact takeover bindings for the two entry files in the approved migration.
+function migrationRegistry(preview){
+ const decorate=adapter=>({...adapter,async plan(context){
+  const requests=await adapter.plan(context);
+  return requests.map(request=>{
+   const entry=preview.entries.find(e=>e.path===request.path);
+   if(!entry)return request;
+   if(request.kind!=='file'||sha256(request.bytes)!==entry.desiredHash)fail('migration.entry-drift');
+   return {...request,takeover:{beforeHash:entry.beforeHash,desiredHash:entry.desiredHash}};
+  });
+ }});
+ return {sharedAdapter:decorate(providerRegistry.sharedAdapter),adapters:Object.fromEntries(
+  Object.entries(providerRegistry.adapters).map(([id,adapter])=>[id,decorate(adapter)]))};
+}
+
+// Second phase delegates target writes/backups/state to native apply. Marker
+// remains afterwards; a separate validated finalization must remove it.
+export async function executeLegacyUnityInstall(lock,payload,options={}){
+ await assertMigrationLockHeld(lock,payload.recoveryPath,payload.recoveryHash);
+ const stored=await readRecord(resolveChild(lock.workspace,payload.recoveryPath));
+ if(stored.digest!==payload.recoveryHash)fail('migration.recovery-drift');
+ const preview=stored.value.preview;
+ await verifyLegacyUnityDeactivationJournal(lock.workspace,payload.recoveryPath,payload.recoveryHash,preview);
+ for(const row of await observeTargets(lock.workspace,preview.preflight.deactivation.targets.map(t=>t.path))){
+  const t=preview.preflight.deactivation.targets.find(t=>t.path===row.path);
+  if(row.bytes===null||sha256(row.bytes)!==t.afterHash)fail('migration.phase-drift');
+ }
+ const body={kind:'prepared-plan',preview:preview.setup,stateFileHash:null,rebind:null,
+  preparation:{objects:preview.preflight.supply.objectsPath,snapshot:preview.preflight.supply.snapshotPath},runtime:'not-run'};
+ const prepared={...body,digest:contractDigest(body)};
+ assertRecoveryBudget(prepared,null);
+ // This subordinate approval is derived only from the already authenticated
+ // full migration approval. It is not a new claim of a human decision.
+ const approval={decision:'approve',preparedDigest:prepared.digest};
+ const locatorPath=payload.recoveryPath.replace(/recovery\.json$/,'installation.json');
+ const [existing]=await observeTargets(lock.workspace,[locatorPath]);
+ if(existing.bytes!==null)fail('migration.install-already-started');
+ const applied=await applyPrepared(lock,prepared,approval,migrationRegistry(preview),null,{
+  ...options,onJournal:async location=>{
+   if(location.status!=='planned')return;
+   const runId=location.relative.split('/').at(-1);
+   const locator={schemaVersion:1,kind:'legacy-unity-installation',migrationRecoveryHash:payload.recoveryHash,
+    preparedDigest:prepared.digest,deactivation:preview.preflight.deactivation.digest,
+    journal:location.relative,recoveryPath:`.pipeline/transactions/${runId}/recovery.json`};
+   await writeCheckedFile(lock,locatorPath,null,Buffer.from(JSON.stringify(parse(JSON.stringify(locator),'json'))+'\n'));
+  }
+ });
+ return {status:'needs-reconciliation',phase:'install-local-delivery',installationStatus:applied.status,
+  recoveryPath:applied.recoveryPath,journal:applied.journal,runtime:'not-run'};
+}

package/src/migrations/legacy-unity-lease.js

@@ -0,0 +1,136 @@
+import {randomUUID} from 'node:crypto';
+import {verifyLegacyUnityPreview} from './legacy-unity-preview.js';
+import {absoluteRoot,resolveChild} from '../workspace/paths.js';
+import {readRecord,observeTargets} from '../operations/state.js';
+import {parse,fail} from '../contracts/parse.js';
+import {sha256} from '../source/inventory.js';
+import {contractDigest} from '../contracts/semantic.js';
+
+const leases=new WeakMap();
+const encode=value=>Buffer.from(JSON.stringify(parse(JSON.stringify(value),'json'))+'\n');
+const markerPath='.pipeline/migration-operation.json';
+
+// Fresh closeout approval can recreate only a verified persisted migration lease.
+export async function createLegacyUnityCloseoutLease(proposal,approval,workspace){
+ const {prepareLegacyUnityCloseoutResume}=await import('./legacy-unity-resume.js');
+ workspace=absoluteRoot(workspace);
+ const detached=parse(JSON.stringify(proposal),'json');
+ if(contractDigestApproval(approval)!==detached.digest)fail('migration.resume-approval');
+ const actual=await prepareLegacyUnityCloseoutResume(workspace,detached.recoveryPath);
+ if(contractDigest(actual)!==contractDigest(detached))fail('migration.resume-drift');
+ const recovery=await readRecord(resolveChild(workspace,actual.recoveryPath));
+ const [marker]=await observeTargets(workspace,[markerPath]);
+ if(recovery.digest!==actual.observations.recovery||marker.bytes===null||sha256(marker.bytes)!==actual.observations.marker)fail('migration.resume-drift');
+ const lease=Object.freeze({workspace});
+ leases.set(lease,{workspace,recoveryPath:actual.recoveryPath,recoveryBytes:encode(recovery.value),
+  recoveryHash:recovery.digest,markerBytes:Buffer.from(marker.bytes),markerHash:sha256(marker.bytes),sealed:true});
+ return {lease,preview:actual};
+}
+function contractDigestApproval(value){
+ if(!value||value.decision!=='approve'||typeof value.previewDigest!=='string'||Object.keys(value).sort().join(',')!=='decision,previewDigest')fail('migration.resume-approval');
+ return value.previewDigest;
+}
+
+export async function createLegacyUnityCompensationLease(proposal,approval,workspace){
+ const {prepareLegacyUnityCompensation}=await import('./legacy-unity-compensate.js');
+ workspace=absoluteRoot(workspace);const detached=parse(JSON.stringify(proposal),'json');
+ if(contractDigestApproval(approval)!==detached.digest)fail('migration.resume-approval');
+ const actual=await prepareLegacyUnityCompensation(workspace,detached.recoveryPath);
+ if(contractDigest(actual)!==contractDigest(detached))fail('migration.resume-drift');
+ const recovery=await readRecord(resolveChild(workspace,actual.recoveryPath));
+ const [marker]=await observeTargets(workspace,[markerPath]);
+ if(recovery.digest!==actual.recoveryHash||marker.bytes===null||sha256(marker.bytes)!==actual.markerHash)fail('migration.resume-drift');
+ const lease=Object.freeze({workspace});
+ leases.set(lease,{workspace,recoveryPath:actual.recoveryPath,recoveryBytes:encode(recovery.value),recoveryHash:recovery.digest,
+  markerBytes:Buffer.from(marker.bytes),markerHash:sha256(marker.bytes),sealed:true});
+ return {lease,preview:actual};
+}
+
+export async function createLegacyUnityInstallRecoveryLease(proposal,approval,workspace){
+ const {prepareLegacyUnityInstallRecovery}=await import('./legacy-unity-install-recovery.js');
+ workspace=absoluteRoot(workspace);const detached=parse(JSON.stringify(proposal),'json');
+ if(contractDigestApproval(approval)!==detached.digest)fail('migration.resume-approval');
+ const actual=await prepareLegacyUnityInstallRecovery(workspace,detached.recoveryPath);
+ if(contractDigest(actual)!==contractDigest(detached))fail('migration.resume-drift');
+ const recovery=await readRecord(resolveChild(workspace,actual.recoveryPath));
+ const [marker]=await observeTargets(workspace,[markerPath]);
+ if(recovery.digest!==actual.recoveryHash||marker.bytes===null||sha256(marker.bytes)!==actual.markerHash)fail('migration.resume-drift');
+ const lease=Object.freeze({workspace});
+ leases.set(lease,{workspace,recoveryPath:actual.recoveryPath,recoveryBytes:encode(recovery.value),recoveryHash:recovery.digest,
+  markerBytes:Buffer.from(marker.bytes),markerHash:sha256(marker.bytes),sealed:true});
+ return {lease,preview:actual};
+}
+
+export async function createLegacyUnityInstallResumeLease(proposal,approval,workspace){
+ const {prepareLegacyUnityInstallResume}=await import('./legacy-unity-install-resume.js');
+ workspace=absoluteRoot(workspace);
+ const detached=parse(JSON.stringify(proposal),'json');
+ if(contractDigestApproval(approval)!==detached.digest)fail('migration.resume-approval');
+ const actual=await prepareLegacyUnityInstallResume(workspace,detached.recoveryPath);
+ if(contractDigest(actual)!==contractDigest(detached))fail('migration.resume-drift');
+ const recovery=await readRecord(resolveChild(workspace,actual.recoveryPath));
+ const [marker]=await observeTargets(workspace,[markerPath]);
+ if(recovery.digest!==actual.recoveryHash||marker.bytes===null||sha256(marker.bytes)!==actual.markerHash)fail('migration.resume-drift');
+ const lease=Object.freeze({workspace});
+ leases.set(lease,{workspace,recoveryPath:actual.recoveryPath,recoveryBytes:encode(recovery.value),recoveryHash:recovery.digest,
+  markerBytes:Buffer.from(marker.bytes),markerHash:sha256(marker.bytes),sealed:true});
+ return {lease,preview:actual};
+}
+
+export async function createLegacyUnityDeactivationResumeLease(proposal,approval,workspace){
+ const {prepareLegacyUnityDeactivationResume}=await import('./legacy-unity-deactivation-resume.js');
+ workspace=absoluteRoot(workspace);
+ const detached=parse(JSON.stringify(proposal),'json');
+ if(contractDigestApproval(approval)!==detached.digest)fail('migration.resume-approval');
+ const actual=await prepareLegacyUnityDeactivationResume(workspace,detached.recoveryPath);
+ if(actual.status!=='needs-approval'||contractDigest(actual)!==contractDigest(detached))fail('migration.resume-drift');
+ const recovery=await readRecord(resolveChild(workspace,actual.recoveryPath));
+ const [marker]=await observeTargets(workspace,[markerPath]);
+ if(recovery.digest!==actual.recoveryHash||marker.bytes===null||sha256(marker.bytes)!==actual.markerHash)fail('migration.resume-drift');
+ const lease=Object.freeze({workspace});
+ leases.set(lease,{workspace,recoveryPath:actual.recoveryPath,recoveryBytes:encode(recovery.value),recoveryHash:recovery.digest,
+  markerBytes:Buffer.from(marker.bytes),markerHash:sha256(marker.bytes),sealed:true});
+ return {lease,preview:actual};
+}
+
+// Process-local capability, issued only after trusted reconstruction and explicit
+// complete-preview approval. Serialized objects cannot recreate this capability.
+export async function createLegacyUnityLease(proposal,approval,workspace){
+ workspace=absoluteRoot(workspace);
+ const preview=await verifyLegacyUnityPreview(proposal,approval,workspace);
+ const id=randomUUID(),recoveryPath=`.pipeline/migrations/${id}/recovery.json`;
+ const record={schemaVersion:1,kind:'legacy-unity-recovery',id,workspace,preview,
+  approval:{decision:'approve',previewDigest:preview.digest}};
+ const recoveryBytes=encode(record),recoveryHash=sha256(recoveryBytes);
+ const marker={schemaVersion:1,kind:'legacy-unity-pending',workspace,recoveryPath,recoveryHash,previewDigest:preview.digest};
+ const markerBytes=encode(marker),markerHash=sha256(markerBytes);
+ const lease=Object.freeze({workspace});
+ leases.set(lease,{workspace,recoveryPath,recoveryBytes,recoveryHash,markerBytes,markerHash,sealed:false});
+ return lease;
+}
+function selected(lease,workspace){
+ const value=lease&&leases.get(lease);
+ if(!value||value.workspace!==absoluteRoot(workspace))fail('migration.lease');
+ return value;
+}
+export async function assertLegacyUnityLease(lease,workspace){
+ const value=selected(lease,workspace);
+ const [marker]=await observeTargets(workspace,[markerPath]);
+ if(marker.bytes===null){if(value.sealed)fail('migration.marker-missing');return;}
+ if(sha256(marker.bytes)!==value.markerHash)fail('migration.marker-drift');
+ if(value.sealed&&(await readRecord(resolveChild(workspace,value.recoveryPath))).digest!==value.recoveryHash)fail('migration.recovery-drift');
+}
+// Internal persistence payload, not another source of approval. Copies prevent
+// callers mutating the private capability's expected hashes or bytes.
+export function legacyUnityLeasePayload(lease,workspace){
+ const value=selected(lease,workspace);
+ return {markerPath,markerBytes:Buffer.from(value.markerBytes),markerHash:value.markerHash,
+  recoveryPath:value.recoveryPath,recoveryBytes:Buffer.from(value.recoveryBytes),recoveryHash:value.recoveryHash};
+}
+export async function sealLegacyUnityLease(lease,workspace){
+ const value=selected(lease,workspace);
+ const [marker]=await observeTargets(workspace,[markerPath]);
+ if(marker.bytes===null||sha256(marker.bytes)!==value.markerHash)fail('migration.marker-drift');
+ if((await readRecord(resolveChild(workspace,value.recoveryPath))).digest!==value.recoveryHash)fail('migration.recovery-drift');
+ value.sealed=true;
+}

package/src/migrations/legacy-unity-preflight.js

@@ -0,0 +1,67 @@
+// Read-only wrapper observation. Acquisition writes only to external temp storage.
+// No approval, target writes, lock acquisition or native harness invocation.
+import path from 'node:path';
+import {tmpdir} from 'node:os';
+import {readdir} from 'node:fs/promises';
+import {assertLockHeld} from '../operations/lock.js';
+import {fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {absoluteRoot,inspectDirectory} from '../workspace/paths.js';
+import {observeTargets,verifyPreparedSnapshot} from '../operations/state.js';
+import {acquire} from '../source/git.js';
+import {sha256} from '../source/inventory.js';
+import {prepareLegacyUnityDeactivation} from './legacy-unity.js';
+
+const targets=['.codex/config.toml','.claude/settings.local.json','AGENTS.md','CLAUDE.md',
+ '.unity-sdd/workspace.json','.unity-sdd/claude.json'];
+const nested=(parent,child)=>{const r=path.relative(parent,child);return !r||(!path.isAbsolute(r)&&r!=='..'&&!r.startsWith('..'+path.sep));};
+async function observe(wrapper,lock){
+ if(!(await inspectDirectory(wrapper)).exists)fail('migration.wrapper-missing');
+ // Existing managed metadata requires reconciliation, not a second bootstrap.
+ if((await inspectDirectory(path.join(wrapper,'.pipeline'))).exists){
+  if(!lock||lock.workspace!==wrapper)fail('migration.already-managed');
+  await assertLockHeld(lock);
+  const names=await readdir(path.join(wrapper,'.pipeline'));
+  if(names.length!==1||names[0]!=='lock')fail('migration.already-managed');
+ }
+ const rows=await observeTargets(wrapper,targets);
+ if(rows.some(r=>r.bytes===null))fail('migration.legacy-missing');
+ // Native observation order is sorted; callers must not depend on input order.
+ return targets.map(name=>rows.find(row=>row.path===name));
+}
+const fingerprints=rows=>rows.map(r=>({path:r.path,sha256:sha256(r.bytes)}));
+export async function prepareLegacyUnityPreflight({wrapper,source,manifestBase,tempRoot=tmpdir(),network=false}){
+ wrapper=absoluteRoot(wrapper);tempRoot=absoluteRoot(tempRoot);
+ if(nested(wrapper,tempRoot)||nested(tempRoot,wrapper))fail('migration.preparation-location');
+ const before=await observe(wrapper);
+ const deactivation=prepareLegacyUnityDeactivation([
+  {provider:'codex',bytes:before[0].bytes},{provider:'claude',bytes:before[1].bytes}]);
+ const acquired=await acquire(source,{manifestBase,tempRoot,network});
+ const verified=await verifyPreparedSnapshot(acquired);
+ if(verified.manifest.id!=='unity-sdd'||!verified.manifest.providers.codex||!verified.manifest.providers.claude)fail('migration.supply');
+ const after=await observe(wrapper);
+ if(contractDigest(fingerprints(before))!==contractDigest(fingerprints(after)))fail('migration.observation-drift');
+ const body={schemaVersion:1,kind:'legacy-unity-preflight',workspace:wrapper,
+  observations:fingerprints(before),deactivation,
+  supply:{source:acquired.source,commit:acquired.commit,version:verified.manifest.version,digest:acquired.digest,inventoryDigest:acquired.inventoryDigest,
+   snapshotPath:acquired.snapshotPath,objectsPath:acquired.preparation},runtime:'not-run'};
+ return {...body,digest:contractDigest(body)};
+}
+
+// Recheck observed wrapper and staged package without contacting Git/network.
+// Digest equality is integrity, not authorization or proof of an earlier check.
+export async function recheckLegacyUnityPreflight(record,wrapper,lock){
+ const {digest,...body}=record;
+ if(record.kind!=='legacy-unity-preflight'||contractDigest(body)!==digest||record.workspace!==absoluteRoot(wrapper))fail('migration.preflight-binding');
+ const rows=await observe(wrapper,lock);
+ if(contractDigest(fingerprints(rows))!==contractDigest(record.observations))fail('migration.observation-drift');
+ for(const candidate of [record.supply.snapshotPath,record.supply.objectsPath]){
+  const root=absoluteRoot(candidate);
+  if(nested(wrapper,root)||nested(root,wrapper))fail('migration.preparation-location');
+  if(!(await inspectDirectory(root)).exists)fail('migration.preparation-missing');
+ }
+ const expected=prepareLegacyUnityDeactivation([{provider:'codex',bytes:rows[0].bytes},{provider:'claude',bytes:rows[1].bytes}]);
+ if(contractDigest(expected)!==contractDigest(record.deactivation))fail('migration.preflight-binding');
+ const verified=await verifyPreparedSnapshot({...record.supply,manifest:{id:'unity-sdd',version:record.supply.version}});
+ return {observed:true,pipeline:verified.manifest.id,runtime:'not-run',authorized:false};
+}

package/src/migrations/legacy-unity-preview.js

@@ -0,0 +1,91 @@
+// Full rendered proposal only: never pass setup directly to generic apply.
+// It observes the virtual post-deactivation configuration, not current bytes.
+import {fail,parse} from '../contracts/parse.js';
+import {requestShape} from '../operations/ownership.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {planLayout} from '../workspace/resolve.js';
+import {resolveOrigin,observeTargets,verifyPreparedSnapshot} from '../operations/state.js';
+import {composePlan,assertRequestScope} from '../operations/plan.js';
+import {providerRegistry} from '../providers/registry.js';
+import {prepareLegacyUnityPreflight,recheckLegacyUnityPreflight} from './legacy-unity-preflight.js';
+
+export async function prepareLegacyUnityPreview({wrapper,manifestPath,tempRoot,network=false}){
+ wrapper=absoluteRoot(wrapper);
+ const origin=await resolveOrigin({wrapper,manifestPath,command:'setup'});
+ if(origin.manifest.bundles || [...(origin.manifest.providers??[])].sort().join(',')!=='claude,codex')fail('migration.providers');
+ const preflight=await prepareLegacyUnityPreflight({wrapper,source:origin.manifest.pipeline,manifestBase:origin.origin.base,tempRoot,network});
+ return renderLegacyUnityPreview(wrapper,origin,preflight);
+}
+
+async function renderLegacyUnityPreview(wrapper,origin,preflight,lock){
+ const manifestPath=origin.origin.path;
+ const verified=await verifyPreparedSnapshot({...preflight.supply,manifest:{id:'unity-sdd',version:preflight.supply.version}});
+ const {adapters,sharedAdapter}=providerRegistry;
+ const layout=planLayout(verified.manifest,origin.manifest,wrapper,{adapters});
+ const snapshot={source:structuredClone(preflight.supply.source),commit:preflight.supply.commit,
+  path:'.pipeline/snapshots/'+preflight.supply.digest.slice(7),digest:preflight.supply.digest,
+  inventoryDigest:preflight.supply.inventoryDigest,origin:structuredClone(origin.origin)};
+ const context=()=>({pipeline:structuredClone(verified.manifest),workspace:structuredClone(origin.manifest),
+  layout:structuredClone(layout),snapshot:structuredClone(snapshot),files:new Map([...verified.files].map(([p,b])=>[p,Buffer.from(b)]))});
+ const requests=[];
+ for(const [owner,adapter] of [['shared',sharedAdapter],['codex',adapters.codex],['claude',adapters.claude]]){
+  if(owner!=='shared'&&(await adapter.validate(context()))?.valid===false)fail('provider.validation');
+  for(const request of await adapter.plan(context())){
+   if(request.owner!==owner)fail('plan.adapter-owner');
+   assertRequestScope(request,origin.manifest.providers);requests.push(request);
+  }
+ }
+ const observed=await observeTargets(wrapper,requests.map(r=>r.path));
+ const entries=[];
+ for(const request of requests){
+  if(!['AGENTS.md','CLAUDE.md'].includes(request.path))continue;
+  const before=observed.find(r=>r.path===request.path)?.bytes;
+  if(!Buffer.isBuffer(before)||request.kind!=='file')fail('migration.entry');
+  request.takeover={beforeHash:sha256(before),desiredHash:sha256(request.bytes)};
+  // Exact original entry content retained in the private approval proposal.
+  entries.push({path:request.path,before:before.toString('base64'),after:request.bytes.toString('base64'),...request.takeover});
+ }
+ if(entries.length!==2)fail('migration.entry');
+ const projected=observed.map(item=>{
+  const change=preflight.deactivation.targets.find(t=>t.path===item.path);
+  if(!change)return item;
+  if(item.bytes===null||sha256(item.bytes)!==change.beforeHash)fail('migration.observation-drift');
+  return {path:item.path,bytes:Buffer.from(change.after,'base64')};
+ });
+ const setup=composePlan({pipeline:verified.manifest,workspace:origin.manifest,wrapper,snapshot,
+  adapters,requests,observations:projected});
+ // All output dependencies, not just the legacy six, must still be unchanged.
+ const fresh=await observeTargets(wrapper,requests.map(r=>r.path));
+ const hashes=items=>items.map(x=>({path:x.path,hash:x.bytes===null?null:sha256(x.bytes)}));
+ if(contractDigest(hashes(fresh))!==contractDigest(hashes(observed)))fail('migration.observation-drift');
+ await recheckLegacyUnityPreflight(preflight,wrapper,lock);
+ if(contractDigest(await resolveOrigin({wrapper,manifestPath,command:'setup'}))!==contractDigest(origin))fail('migration.origin-drift');
+ const body={schemaVersion:1,kind:'legacy-unity-preview',workspace:wrapper,preflight,
+  origin:origin.origin,entries,initialObservations:hashes(observed),setup,
+  phases:['deactivate-legacy','install-local-delivery'],runtime:'not-run'};
+ return {...body,digest:contractDigest(body)};
+}
+
+// Genuine approval is supplied by the caller. It binds the complete proposal,
+// not its embedded setup phase. Re-render trusted adapters without acquiring Git.
+// Read-only, no lock or write capability returned; execution must recheck again.
+export async function verifyLegacyUnityPreview(proposal,approval,wrapper,lock){
+ requestShape(approval,['decision','previewDigest'],[],'migration.approval');
+ requestShape(proposal,['schemaVersion','kind','workspace','preflight','origin','entries','initialObservations','setup','phases','runtime','digest'],[],'migration.preview');
+ if(approval.decision!=='approve'||approval.previewDigest!==proposal.digest)fail('migration.approval');
+ // Limit serializable proposal complexity and detach before asynchronous reads.
+ const copy=parse(JSON.stringify(proposal),'json');
+ const {digest,...body}=copy;
+ wrapper=absoluteRoot(wrapper);
+ if(copy.workspace!==wrapper||copy.schemaVersion!==1||copy.kind!=='legacy-unity-preview'||contractDigest(body)!==digest)fail('migration.preview-binding');
+ const origin=await resolveOrigin({wrapper,manifestPath:copy.origin.path,command:'setup'});
+ if(origin.manifest.bundles || [...(origin.manifest.providers??[])].sort().join(',')!=='claude,codex'||
+  contractDigest(origin.origin)!==contractDigest(copy.origin)||
+  contractDigest(origin.manifest.pipeline)!==contractDigest(copy.preflight.supply.source))fail('migration.origin-drift');
+ await recheckLegacyUnityPreflight(copy.preflight,wrapper,lock);
+ const rebuilt=await renderLegacyUnityPreview(wrapper,origin,copy.preflight,lock);
+ if(contractDigest(rebuilt)!==contractDigest(copy))fail('migration.render-drift');
+ return rebuilt;
+}