@6reduk/workspace-pipeline 0.1.0

package/src/contracts/semantic.js

@@ -0,0 +1,240 @@
+import { posix, win32 } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { createHash } from 'node:crypto';
+import { fail } from './parse.js';
+import { validateStructure } from './validate.js';
+import { requiredCapabilities, assertAdapter } from '../providers/interface.js';
+import { resolveProviders, validateInstalledBundles } from '../providers/bundles.js';
+
+const has = (o, k) => Object.hasOwn(o, k);
+export function portablePath(value) {
+  if (typeof value !== 'string' || !value || value.length > 240 || !/^[A-Za-z0-9_. /-]+$/.test(value)) fail('path.invalid');
+  for (const part of value.split('/')) {
+    if (!part || part.length > 100 || part === '.' || part === '..' || /[. ]$/.test(part) ||
+        /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) || part.toLowerCase() === '.git') fail('path.invalid');
+  }
+  return value;
+}
+function machinePath(value) {
+  if (typeof value !== 'string' || /[\u0000-\u001f\u007f]/.test(value) ||
+      !(posix.isAbsolute(value) || win32.isAbsolute(value))) fail('state.absolute-path');
+}
+export function validateLayoutReferences(layout) {
+  for (const ref of [layout.documentation, ...Object.values(layout.projectRoots ?? {})]) {
+    if (!has(layout.repositories, ref.repository)) fail('layout.repository');
+    if (ref.path !== '.') portablePath(ref.path);
+  }
+  for (const repo of Object.values(layout.repositories)) {
+    portablePath(repo.path);
+    if (repo.source && repo.source.subdirectory !== '.') fail('source.clone-subdirectory');
+  }
+}
+export function validateInventory(inventory, { inventoryPath, manifestPath }) {
+  validateStructure('inventory', inventory);
+  portablePath(inventoryPath); portablePath(manifestPath);
+  const seen = new Set();
+  for (const name of Object.keys(inventory)) {
+    portablePath(name);
+    const key = name.toLowerCase();
+    if (key === inventoryPath.toLowerCase()) fail('inventory.self');
+    if (seen.has(key)) fail('inventory.collision');
+    seen.add(key);
+  }
+  if (!has(inventory, manifestPath)) fail('inventory.manifest');
+  // Blob contents / missing and extra physical files / digest verification belong to S2.
+  return inventory;
+}
+export function validateBundle(pipeline, workspace, adapters) {
+  validateStructure('pipeline', pipeline); validateStructure('workspace', workspace);
+  if (workspace.pipeline.subdirectory !== '.') portablePath(workspace.pipeline.subdirectory);
+  portablePath(pipeline.resources); portablePath(pipeline.inventory);
+  for (const decl of Object.values(pipeline.providers)) {
+    requiredCapabilities(decl);
+    for (const key of ['skills', 'agents', 'mcp', 'entryInstructions'])
+      if (decl[key] !== null) portablePath(decl[key]);
+  }
+  for (const profile of Object.values(pipeline.workspaceProfiles ?? {})) validateLayoutReferences(profile);
+  let layout = workspace.layout;
+  if (workspace.profile !== undefined) {
+    if (!has(pipeline.workspaceProfiles ?? {}, workspace.profile)) fail('layout.profile');
+    layout = pipeline.workspaceProfiles[workspace.profile];
+  }
+  validateLayoutReferences(layout);
+  const selection = resolveProviders(pipeline, workspace);
+  for (const bundle of Object.values(pipeline.bundles ?? {})) portablePath(bundle.entry.source);
+  for (const id of selection.providers) {
+    if (!has(pipeline.providers, id)) fail('provider.absent');
+    if (adapters) assertAdapter(adapters[id], id, pipeline.providers[id]);
+  }
+  const entry = workspace.agentsDocument ?? pipeline.agentsDocument;
+  if (entry.mode === 'source') portablePath(entry.path);
+  return { layout, agentsDocument: entry, ...selection };
+}
+export function renderEntry(text, layout) {
+  if (typeof text !== 'string' || Buffer.byteLength(text) > 2 * 1024 * 1024) fail('entry.input');
+  validateLayoutReferences(layout);
+  const output = text.replace(/\{\{([^{}]*)\}\}/g, (matchText, token, offset) => {
+    if (text[offset - 1] === '{' || text[offset + matchText.length] === '}') fail('entry.token');
+    if (token === 'documentation') {
+      const doc = layout.documentation;
+      return posix.join(layout.repositories[doc.repository].path, doc.path);
+    }
+    const match = /^repository\.([a-z][a-z0-9-]{0,62})$/.exec(token);
+    if (!match || !has(layout.repositories, match[1])) fail('entry.token');
+    return layout.repositories[match[1]].path;
+  });
+  if (output.includes('{{') || output.includes('}}')) fail('entry.token');
+  return output;
+}
+export function resolveEntryChange(current, desired, baseHash, currentHash, decision) {
+  // Pure policy decision; caller S4/S8 must compute hashes from exact bytes.
+  if (current === null) return 'create';
+  if (current === desired) return 'preserve';
+  if (decision === 'preserve') return 'preserve';
+  if (baseHash !== null && baseHash === currentHash) return 'replace';
+  if (decision === 'replace') return 'replace';
+  // Merging requires a separately reviewed desired result, never an implicit merge.
+  fail('entry.conflict');
+}
+function pointer(value) {
+  if (typeof value !== 'string' || !/^(?:\/(?:[^~/]|~[01])*)+$/.test(value)) fail('ownership.pointer');
+  for (const part of value.split('/').slice(1).map(s => s.replace(/~1/g, '/').replace(/~0/g, '~')))
+    if (['__proto__', 'constructor', 'prototype'].includes(part)) fail('ownership.pointer');
+}
+function snapshot(s) {
+  if (s.source.subdirectory !== '.') portablePath(s.source.subdirectory);
+  portablePath(s.path); machinePath(s.origin.path); machinePath(s.origin.base);
+  if (!s.path.startsWith('.pipeline/snapshots/')) fail('state.snapshot-path');
+  if (s.source.transport === 'local') machinePath(s.origin.resolvedSource);
+  else if (s.origin.resolvedSource !== s.source.url) fail('source.identity');
+}
+function ownership(records, providers) {
+  const seen = [];
+  for (const record of records) {
+    portablePath(record.path);
+    if (record.backup !== null) {
+      portablePath(record.backup);
+      if (!record.backup.startsWith('.pipeline/backups/')) fail('ownership.backup');
+    }
+    if (record.beforeHash !== null && record.backup === null) fail('ownership.backup');
+    if (record.owner !== 'shared' && !providers.includes(record.owner)) fail('ownership.owner');
+    if (record.kind === 'file' && record.pointer !== null) fail('ownership.pointer');
+    if (record.kind === 'field') pointer(record.pointer);
+    for (const previous of seen) if (previous.path.toLowerCase() === record.path.toLowerCase()) {
+      if (previous.kind === 'file' || record.kind === 'file' || previous.pointer === record.pointer ||
+          previous.pointer.startsWith(record.pointer + '/') || record.pointer.startsWith(previous.pointer + '/')) fail('ownership.overlap');
+    }
+    seen.push(record);
+  }
+}
+function deployment(d) {
+  validateInstalledBundles(d);
+  snapshot(d.snapshot); validateLayoutReferences(d.layout);
+  if (Object.keys(d.adapterVersions).sort().join(',') !== [...d.providers].sort().join(',')) fail('state.adapters');
+  ownership(d.owned, d.providers);
+}
+export function validateState(state) {
+  validateStructure('state', state); machinePath(state.workspace);
+  if (state.active) deployment(state.active);
+  if (state.status === 'ready' && (!state.active || state.pending !== null)) fail('state.ready');
+  if (state.status === 'not-installed' && (state.active !== null || state.pending !== null)) fail('state.absent');
+  if (state.status === 'needs-reconciliation' && state.pending === null) fail('state.pending');
+  if (state.status === 'drift' && state.active === null) fail('state.drift');
+  return state;
+}
+export function validateOperation(op, previous) {
+  validateStructure('operation', op);
+  const ids = new Set();
+  if (op.kind === 'plan') {
+    machinePath(op.workspace);
+    // Existing-state plans require the exact previous state, including removed
+    // providers. The desired provider set alone cannot authorize cleanup.
+    if (op.beforeStateHash !== null) {
+      if (previous == null) fail('plan.previous-required');
+      validateState(previous);
+      if (previous.workspace !== op.workspace || contractDigest(previous) !== op.beforeStateHash) fail('plan.previous');
+    } else if (previous != null) fail('plan.previous');
+    const owners = new Set(['shared', ...(previous?.active?.providers ?? []), ...(op.desired?.providers ?? [])]);
+    if (op.source) snapshot(op.source);
+    if (op.desired) {
+      deployment(op.desired);
+      if (!op.source || !isDeepStrictEqual(op.source, op.desired.snapshot)) fail('plan.source');
+    }
+    if (['setup', 'update', 'repair', 'switch'].includes(op.command) && !op.desired) fail('plan.deployment');
+    const paths = new Set();
+    for (const t of op.targets) {
+      if (!owners.has(t.owner)) fail('operation.owner');
+      if (ids.has(t.id)) fail('operation.duplicate'); ids.add(t.id);
+      portablePath(t.path);
+      if (paths.has(t.path.toLowerCase())) fail('operation.path'); paths.add(t.path.toLowerCase());
+      if (t.action === 'create' && (t.beforeHash !== null || t.desiredHash === null)) fail('operation.hash');
+      if (t.action === 'delete' && (t.beforeHash === null || t.desiredHash !== null)) fail('operation.hash');
+      const retiredBundleFile = op.command==='update' && previous?.active?.owned.some(o=>
+        o.path===t.path && o.owner===t.owner && o.kind==='file') &&
+        Object.entries(previous.active.bundles??{}).some(([id,b])=>op.desired?.bundles?.[id] &&
+          b.providers.includes(t.owner) && !op.desired.providers.includes(t.owner));
+      if (t.action === 'verify-absent' && ((op.command !== 'remove' && !retiredBundleFile) || t.beforeHash !== null || t.desiredHash !== null)) fail('operation.hash');
+      if (['replace', 'edit-fields'].includes(t.action) && (t.beforeHash === null || t.desiredHash === null)) fail('operation.hash');
+      if ((t.action === 'edit-fields') !== (t.fields.length > 0)) fail('operation.fields');
+      const fieldPointers = [];
+      for (const f of t.fields) {
+        pointer(f.pointer);
+        if (fieldPointers.some(p => p === f.pointer || p.startsWith(f.pointer + '/') || f.pointer.startsWith(p + '/'))) fail('operation.fields');
+        fieldPointers.push(f.pointer);
+      }
+    }
+  } else {
+    let stopped = false;
+    for (const r of op.operations) {
+      if (ids.has(r.operationId)) fail('operation.duplicate'); ids.add(r.operationId);
+      if (stopped && r.status !== 'skipped') fail('receipt.order');
+      if (r.status !== 'completed') stopped = true;
+      if (r.status === 'completed' && r.observedHash !== r.desiredHash) fail('receipt.readback');
+      if (r.status === 'failed' && r.observedHash !== r.beforeHash) fail('receipt.before');
+    }
+    const statuses = op.operations.map(r => r.status);
+    const expected = statuses.every(s => s === 'completed') ? 'completed' :
+      statuses.includes('uncertain') ? 'uncertain' : 'failed';
+    if (op.status !== expected) fail('receipt.status');
+  }
+  return op;
+}
+// Hash domain data, not file bytes: sorted object keys, array order retained.
+// Use only validated JSON-domain values. Source blob hashes remain exact byte hashes.
+export function contractDigest(value) {
+  const canonical = v => {
+    if (v === null || typeof v !== 'object') return JSON.stringify(v);
+    if (Array.isArray(v)) return '[' + v.map(canonical).join(',') + ']';
+    return '{' + Object.keys(v).sort().map(k => JSON.stringify(k) + ':' + canonical(v[k])).join(',') + '}';
+  };
+  return 'sha256:' + createHash('sha256').update(canonical(value), 'utf8').digest('hex');
+}
+export function validateReceiptForPlan(receipt, plan, previous) {
+  validateOperation(plan, previous); validateOperation(receipt);
+  if (plan.kind !== 'plan' || receipt.kind !== 'receipt' || receipt.planDigest !== contractDigest(plan)) fail('receipt.binding');
+  if (receipt.operations.length !== plan.targets.length) fail('receipt.coverage');
+  for (let i = 0; i < plan.targets.length; i++) {
+    const t = plan.targets[i], r = receipt.operations[i];
+    if (t.id !== r.operationId || t.beforeHash !== r.beforeHash || t.desiredHash !== r.desiredHash) fail('receipt.binding');
+  }
+  return receipt;
+}
+
+// Structural lifecycle guard only. S5 must independently prove writes/readback and
+// bind the on-disk before-state; a fabricated receipt is not execution evidence.
+export function validateTransition(previous, next, plan, receipt) {
+  if (previous !== null) validateState(previous);
+  validateState(next); validateReceiptForPlan(receipt, plan, previous);
+  if (next.workspace !== plan.workspace || (previous !== null && previous.workspace !== plan.workspace) ||
+      plan.beforeStateHash !== (previous === null ? null : contractDigest(previous))) fail('transition.before');
+  if (receipt.status === 'completed') {
+    if (!isDeepStrictEqual(next.active, plan.desired) || next.pending !== null ||
+        next.status !== (plan.desired === null ? 'not-installed' : 'ready')) fail('transition.activation');
+  } else {
+    if (next.status !== 'needs-reconciliation' || next.pending !== contractDigest(plan) ||
+        !isDeepStrictEqual(next.active, previous?.active ?? null)) fail('transition.partial');
+    if (contractDigest(next.activation??null)!==contractDigest(previous?.activation??null)) fail('transition.activation-history');
+  }
+  if (next.runtime !== 'not-run') fail('transition.runtime');
+  return next;
+}

package/src/contracts/validate.js

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { fail } from './parse.js';
+
+const names = ['common', 'pipeline', 'workspace', 'inventory', 'state', 'operation'];
+// Reviewed schemas use required inside not/oneOf and inherit types from parents.
+const ajv = new Ajv2020({ strict: true, strictTypes: false, strictRequired: false, allErrors: false,
+  ownProperties: true, coerceTypes: false, useDefaults: false, removeAdditional: false });
+for (const name of names) {
+  const schema = JSON.parse(readFileSync(new URL('../../schemas/' + name + '.schema.json', import.meta.url), 'utf8'));
+  ajv.addSchema(schema, name + '.schema.json');
+}
+// common is a reference library, not a document schema with root constraints.
+const validators = new Map(names.filter(name => name !== 'common')
+  .map(name => [name, ajv.getSchema(name + '.schema.json')]));
+export function validateStructure(kind, value) {
+  const validator = validators.get(kind);
+  if (!validator) fail('schema.kind');
+  if (!validator(value)) fail('schema.invalid');
+  return value;
+}

package/src/launch/grok.js

@@ -0,0 +1,20 @@
+// Child-process-only overlay, not a launcher or readiness check by itself.
+// Callers still validate workspace state and choose the executable.
+// This neither grants trust nor disables native plugins.
+export const GROK_CLAUDE_PIPELINE_KEYS = Object.freeze([
+  'GROK_CLAUDE_SKILLS_ENABLED', 'GROK_CLAUDE_RULES_ENABLED',
+  'GROK_CLAUDE_AGENTS_ENABLED', 'GROK_CLAUDE_MCPS_ENABLED',
+  'GROK_CLAUDE_HOOKS_ENABLED',
+]);
+export function grokEnvironment(parent, platform = process.platform) {
+  if (!parent || typeof parent !== 'object' || Array.isArray(parent)) throw new TypeError('launch.environment');
+  if (!['win32', 'linux', 'darwin'].includes(platform)) throw new TypeError('launch.platform');
+  const result = Object.create(null), owned = new Set(GROK_CLAUDE_PIPELINE_KEYS);
+  for (const [key, value] of Object.entries(parent)) {
+    // Windows spawn must not choose an inherited differently-cased spelling.
+    if (owned.has(platform === 'win32' ? key.toUpperCase() : key)) continue;
+    if (value !== undefined) result[key] = value;
+  }
+  for (const key of owned) result[key] = 'false';
+  return result;
+}

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

@@ -0,0 +1,35 @@
+import {createLegacyUnityLease,legacyUnityLeasePayload,sealLegacyUnityLease} from './legacy-unity-lease.js';
+import {verifyLegacyUnityPreview} from './legacy-unity-preview.js';
+import {acquireWorkspaceLock,assertLockHeld} from '../operations/lock.js';
+import {writeCheckedFile} from '../operations/apply.js';
+import {executeLegacyUnityDeactivation} from './legacy-unity-deactivate.js';
+import {executeLegacyUnityInstall} from './legacy-unity-install.js';
+import {finalizeLegacyUnityMigration} from './legacy-unity-finalize.js';
+
+// Persist recovery before any provider writes. Marker is written FIRST so a
+// crash saving recovery is still fail-closed for ordinary lifecycle commands.
+// No automatic rollback/unlink on error. Caller owns the returned lock lifetime.
+export async function beginLegacyUnityMigration(proposal,approval,workspace,{boundary=async()=>{}}={}){
+ const lease=await createLegacyUnityLease(proposal,approval,workspace);
+ let lock;
+ try{
+  lock=await acquireWorkspaceLock(workspace,{migrationOperation:lease});
+  await boundary('locked');
+  await verifyLegacyUnityPreview(proposal,approval,lock.workspace,lock);
+  const payload=legacyUnityLeasePayload(lease,lock.workspace);
+  await writeCheckedFile(lock,payload.markerPath,null,payload.markerBytes,undefined,
+   async phase=>boundary('marker:'+phase));
+  await writeCheckedFile(lock,payload.recoveryPath,null,payload.recoveryBytes,undefined,
+   async phase=>boundary('recovery:'+phase));
+  await sealLegacyUnityLease(lease,lock.workspace);
+  await assertLockHeld(lock);
+  return Object.freeze({lock,recoveryPath:payload.recoveryPath,recoveryHash:payload.recoveryHash,
+   status:'needs-reconciliation',providerWrites:0,runtime:'not-run',
+   deactivate:options=>executeLegacyUnityDeactivation(lock,payload,options),
+   install:options=>executeLegacyUnityInstall(lock,payload,options),
+   finalize:options=>finalizeLegacyUnityMigration(lock,payload,options)});
+ }catch(error){
+  if(lock){try{await lock.release({removeEmptyMetadata:true});}catch{error.lockRelease='failed';}}
+  throw error;
+ }
+}

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

@@ -0,0 +1,82 @@
+import {prepareLegacyUnityDeactivationResume} from './legacy-unity-deactivation-resume.js';
+import {validateLegacyUnityDeactivation} from './legacy-unity.js';
+import {readRecord,observeTargets} from '../operations/state.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {fail} from '../contracts/parse.js';
+import {createLegacyUnityCompensationLease,legacyUnityLeasePayload} from './legacy-unity-lease.js';
+import {acquireWorkspaceLock} from '../operations/lock.js';
+import {writeCheckedFile,deleteCheckedFile} from '../operations/apply.js';
+import {readdir} from 'node:fs/promises';
+
+async function noInstallation(workspace){
+ for(const path of ['.pipeline/snapshots','.pipeline/backups','.pipeline/journals','.pipeline/transactions'])
+  if((await inspectDirectory(resolveChild(workspace,path))).exists)fail('migration.compensation-installation');
+}
+export async function prepareLegacyUnityCompensation(workspace,recoveryPath){
+ const base=await prepareLegacyUnityDeactivationResume(workspace,recoveryPath);
+ if(base.status!=='needs-approval')fail('migration.compensation-conflict');
+ await noInstallation(base.workspace);
+ // A resumed attempt needs its own recovery/compensation selection, never ignore it.
+ if((await inspectDirectory(resolveChild(base.workspace,recoveryPath.replace(/recovery\.json$/,'deactivation-resumes')))).exists)fail('migration.compensation-resumed');
+ const stored=await readRecord(resolveChild(base.workspace,recoveryPath));
+ if(stored.digest!==base.recoveryHash)fail('migration.resume-drift');
+ const phase=validateLegacyUnityDeactivation(stored.value.preview.preflight.deactivation);
+ const operations=phase.targets.map(t=>{
+  const observed=base.observations.find(o=>o.path===t.path).hash;
+  return {path:t.path,action:observed===t.beforeHash?'confirm-original':'restore-original',beforeHash:observed,
+   afterHash:t.beforeHash,bytes:t.before};
+ });
+ const body={schemaVersion:1,kind:'legacy-unity-compensation-preview',workspace:base.workspace,recoveryPath,
+  recoveryHash:base.recoveryHash,markerHash:base.markerHash,base,operations,
+  removeMarker:{path:'.pipeline/migration-operation.json',beforeHash:base.markerHash},status:'needs-approval',executable:false,runtime:'not-run'};
+ return {...body,digest:contractDigest(body)};
+}
+
+export async function applyLegacyUnityCompensation(proposal,approval,workspace,{boundary=async()=>{}}={}){
+ const {lease,preview}=await createLegacyUnityCompensationLease(proposal,approval,workspace);
+ const lock=await acquireWorkspaceLock(workspace,{migrationOperation:lease});
+ try{
+  if(contractDigest(await prepareLegacyUnityCompensation(lock.workspace,preview.recoveryPath))!==contractDigest(preview))fail('migration.resume-drift');
+  const payload=legacyUnityLeasePayload(lease,lock.workspace),directory=preview.recoveryPath.replace(/recovery\.json$/,'compensation');
+  const written=[];let previous=null;
+  const append=async(kind,detail)=>{
+   for(const item of written)if((await readRecord(resolveChild(lock.workspace,item.path))).digest!==item.hash)fail('migration.journal-drift');
+   const path=directory+'/'+String(written.length).padStart(6,'0')+'.json';
+   const bytes=Buffer.from(JSON.stringify({schemaVersion:1,seq:written.length,previous,kind,detail})+'\n');
+   await writeCheckedFile(lock,path,null,bytes);previous=sha256(bytes);written.push({path,hash:previous});
+  };
+  await append('authorization',{preview,approval:{decision:'approve',previewDigest:preview.digest}});
+  const expected=new Map(preview.base.observations.map(o=>[o.path,o.hash]));
+  const check=async()=>{
+   await noInstallation(lock.workspace);
+   const originalDirectory=preview.recoveryPath.replace(/recovery\.json$/,'deactivation');
+   let names;try{names=(await readdir(resolveChild(lock.workspace,originalDirectory))).sort();}catch(e){if(e.code!=='ENOENT')throw e;names=[];}
+   if(names.join(',')!==preview.base.events.map(e=>e.path.split('/').at(-1)).join(','))fail('migration.journal-drift');
+   if((await inspectDirectory(resolveChild(lock.workspace,preview.recoveryPath.replace(/recovery\.json$/,'deactivation-resumes')))).exists)fail('migration.compensation-resumed');
+   for(const path of ['.pipeline/state.json',preview.recoveryPath.replace(/recovery\.json$/,'installation.json')])
+    if((await observeTargets(lock.workspace,[path]))[0].bytes!==null)fail('migration.compensation-installation');
+   for(const e of preview.base.events)if((await readRecord(resolveChild(lock.workspace,e.path))).digest!==e.hash)fail('migration.journal-drift');
+   for(const row of await observeTargets(lock.workspace,[...expected.keys()]))
+    if((row.bytes===null?null:sha256(row.bytes))!==expected.get(row.path))fail('migration.observation-drift');
+  };
+  for(const op of preview.operations){
+   await check();await append('intent',op);
+   try{
+    if(op.action==='restore-original')await writeCheckedFile(lock,op.path,op.beforeHash,Buffer.from(op.bytes,'base64'),undefined,boundary);
+    const [row]=await observeTargets(lock.workspace,[op.path]);
+    if(row.bytes===null||sha256(row.bytes)!==op.afterHash)fail('migration.compensation-drift');
+   }catch{
+    await append('outcome',{path:op.path,status:'uncertain'});
+    return {status:'needs-reconciliation',journal:directory,runtime:'not-run'};
+   }
+   expected.set(op.path,op.afterHash);await append('outcome',{path:op.path,status:'original-observed',hash:op.afterHash});
+  }
+  await check();await append('compensated',{recoveryHash:preview.recoveryHash});
+  await boundary('compensation-recorded');await check();
+  for(const e of written)if((await readRecord(resolveChild(lock.workspace,e.path))).digest!==e.hash)fail('migration.journal-drift');
+  await deleteCheckedFile(lock,payload.markerPath,payload.markerHash,async()=>{});
+  return {status:'legacy-restored',journal:directory,runtime:'not-run'};
+ }finally{await lock.release();}
+}

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

@@ -0,0 +1,60 @@
+import {readRecord,observeTargets} from '../operations/state.js';
+import {writeCheckedFile} from '../operations/apply.js';
+import {assertMigrationLockHeld} from '../operations/lock.js';
+import {resolveChild} from '../workspace/paths.js';
+import {validateLegacyUnityDeactivation} from './legacy-unity.js';
+import {sha256} from '../source/inventory.js';
+import {parse,fail,ContractError} from '../contracts/parse.js';
+
+// Internal first-phase executor. New activation is deliberately not performed.
+// Every attempt has an exclusive journal; replay requires a future recovery API.
+export async function executeLegacyUnityDeactivation(lock,payload,{boundary=async()=>{}}={}){
+ const guard=()=>assertMigrationLockHeld(lock,payload.recoveryPath,payload.recoveryHash);
+ await guard();
+ const stored=await readRecord(resolveChild(lock.workspace,payload.recoveryPath));
+ if(stored.digest!==payload.recoveryHash)fail('migration.recovery-drift');
+ const record=stored.value,preview=record.preview;
+ if(record.workspace!==lock.workspace||record.approval?.previewDigest!==preview.digest||record.approval?.decision!=='approve')fail('migration.recovery-binding');
+ const phase=validateLegacyUnityDeactivation(preview.preflight.deactivation);
+ const before=new Map(preview.initialObservations.map(x=>[x.path,x.hash]));
+ for(const x of preview.preflight.observations){
+  if(before.has(x.path)&&before.get(x.path)!==x.sha256)fail('migration.observation-binding');
+  before.set(x.path,x.sha256);
+ }
+ for(const row of await observeTargets(lock.workspace,[...before.keys()]))
+  if((row.bytes===null?null:sha256(row.bytes))!==before.get(row.path))fail('migration.observation-drift');
+ const directory=payload.recoveryPath.replace(/recovery\.json$/,'deactivation');
+ let seq=0,head=null,lastPath;const written=[];
+ async function append(kind,detail){
+  await guard();
+  if(lastPath&&(await readRecord(resolveChild(lock.workspace,lastPath))).digest!==head)fail('migration.journal-drift');
+  const relative=directory+'/'+String(seq).padStart(6,'0')+'.json';
+  const event={schemaVersion:1,seq,previous:head,recoveryHash:payload.recoveryHash,kind,detail};
+  const bytes=Buffer.from(JSON.stringify(parse(JSON.stringify(event),'json'))+'\n');
+  await writeCheckedFile(lock,relative,null,bytes);
+  lastPath=relative;head=sha256(bytes);written.push({path:relative,hash:head});seq++;
+ }
+ await append('start',null);
+ for(const target of phase.targets){
+  await append('intent',{path:target.path,beforeHash:target.beforeHash,afterHash:target.afterHash});
+  try{
+   await writeCheckedFile(lock,target.path,target.beforeHash,Buffer.from(target.after,'base64'),undefined,
+    async step=>boundary(step,{path:target.path}));
+  }catch(error){
+   // Error after a write is not silently promoted to successful completion.
+   let observedHash=null;
+   try{const [row]=await observeTargets(lock.workspace,[target.path]);observedHash=row.bytes===null?null:sha256(row.bytes);}catch{}
+   const status=observedHash===target.beforeHash?'failed':'uncertain';
+   await append('outcome',{path:target.path,status,observedHash});
+   return {status:'needs-reconciliation',phase:'deactivate-legacy',outcome:status,
+    journal:directory,error:error instanceof ContractError?error.code:'migration.target-io',runtime:'not-run'};
+  }
+  await append('outcome',{path:target.path,status:'completed',observedHash:target.afterHash});
+ }
+ for(const row of await observeTargets(lock.workspace,phase.targets.map(t=>t.path)))
+  if(row.bytes===null||sha256(row.bytes)!==phase.targets.find(t=>t.path===row.path).afterHash)fail('migration.phase-drift');
+ await append('phase-checked',{phase:'deactivate-legacy'});
+ for(const item of written)if((await readRecord(resolveChild(lock.workspace,item.path))).digest!==item.hash)fail('migration.journal-drift');
+ return {status:'needs-reconciliation',phase:'deactivate-legacy',outcome:'completed',journal:directory,
+  next:'install-local-delivery',runtime:'not-run'};
+}

package/src/migrations/legacy-unity-deactivation-resume-apply.js

@@ -0,0 +1,62 @@
+import {createLegacyUnityDeactivationResumeLease} from './legacy-unity-lease.js';
+import {prepareLegacyUnityDeactivationResume} from './legacy-unity-deactivation-resume.js';
+import {validateLegacyUnityDeactivation} from './legacy-unity.js';
+import {acquireWorkspaceLock} from '../operations/lock.js';
+import {readRecord,observeTargets} from '../operations/state.js';
+import {writeCheckedFile} 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 {readdir} from 'node:fs/promises';
+
+// Internal execution only; original uncertain/failed receipts are never rewritten.
+export async function applyLegacyUnityDeactivationResume(proposal,approval,workspace,{boundary=async()=>{}}={}){
+ const {lease,preview}=await createLegacyUnityDeactivationResumeLease(proposal,approval,workspace);
+ const lock=await acquireWorkspaceLock(workspace,{migrationOperation:lease});
+ try{
+  if(contractDigest(await prepareLegacyUnityDeactivationResume(lock.workspace,preview.recoveryPath))!==contractDigest(preview))fail('migration.resume-drift');
+  const record=await readRecord(resolveChild(lock.workspace,preview.recoveryPath));
+  const phase=validateLegacyUnityDeactivation(record.value.preview.preflight.deactivation);
+  const directory=preview.recoveryPath.replace(/recovery\.json$/,`deactivation-resumes/${preview.digest.slice(7)}`);
+  const written=[];let previous=null;
+  const append=async(kind,detail)=>{
+   for(const item of written)if((await readRecord(resolveChild(lock.workspace,item.path))).digest!==item.hash)fail('migration.journal-drift');
+   const path=directory+'/'+String(written.length).padStart(6,'0')+'.json';
+   const bytes=Buffer.from(JSON.stringify({schemaVersion:1,seq:written.length,previous,kind,detail})+'\n');
+   await writeCheckedFile(lock,path,null,bytes);previous=sha256(bytes);written.push({path,hash:previous});
+  };
+  await append('authorization',{preview,approval:{decision:'approve',previewDigest:preview.digest}});
+  const expected=new Map(preview.observations.map(o=>[o.path,o.hash]));
+  const check=async()=>{
+   const originalDirectory=preview.recoveryPath.replace(/recovery\.json$/,'deactivation');
+   let names;try{names=(await readdir(resolveChild(lock.workspace,originalDirectory))).sort();}catch(error){if(error.code!=='ENOENT')throw error;names=[];}
+   if(names.join(',')!==preview.events.map(e=>e.path.split('/').at(-1)).join(','))fail('migration.journal-drift');
+   for(const e of preview.events)if((await readRecord(resolveChild(lock.workspace,e.path))).digest!==e.hash)fail('migration.journal-drift');
+   for(const path of [preview.recoveryPath.replace(/recovery\.json$/,'installation.json'),'.pipeline/state.json'])
+    if((await observeTargets(lock.workspace,[path]))[0].bytes!==null)fail('migration.install-started');
+   for(const row of await observeTargets(lock.workspace,[...expected.keys()]))
+    if((row.bytes===null?null:sha256(row.bytes))!==expected.get(row.path))fail('migration.observation-drift');
+  };
+  for(const operation of preview.operations){
+   await check();await append('intent',operation);
+   try{
+    if(operation.action==='write-disabled'){
+     const target=phase.targets.find(t=>t.path===operation.path);
+     await writeCheckedFile(lock,operation.path,operation.beforeHash,Buffer.from(target.after,'base64'),undefined,boundary);
+    }
+    const [row]=await observeTargets(lock.workspace,[operation.path]);
+    if(row.bytes===null||sha256(row.bytes)!==operation.afterHash)fail('migration.phase-drift');
+   }catch{
+    const [row]=await observeTargets(lock.workspace,[operation.path]);
+    await append('outcome',{path:operation.path,status:'uncertain',observedHash:row.bytes===null?null:sha256(row.bytes)});
+    return {status:'needs-reconciliation',outcome:'uncertain',journal:directory,runtime:'not-run'};
+   }
+   expected.set(operation.path,operation.afterHash);
+   await append('outcome',{path:operation.path,status:operation.action==='write-disabled'?'written':'confirmed-observed',observedHash:operation.afterHash});
+  }
+  await check();await append('phase-observed',{phase:'deactivate-legacy',recoveryHash:preview.recoveryHash});
+  for(const e of written)if((await readRecord(resolveChild(lock.workspace,e.path))).digest!==e.hash)fail('migration.journal-drift');
+  return {status:'needs-reconciliation',outcome:'phase-observed',journal:directory,runtime:'not-run'};
+ }finally{await lock.release();}
+}

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

@@ -0,0 +1,81 @@
+import {readdir} from 'node:fs/promises';
+import {absoluteRoot,resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {readRecord,observeTargets} from '../operations/state.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256} from '../source/inventory.js';
+import {fail} from '../contracts/parse.js';
+import {validateLegacyUnityDeactivation,inspectLegacyUnityDeactivation} from './legacy-unity.js';
+
+// Read-only first-phase reconciliation. A current after hash is NOT a receipt.
+export async function prepareLegacyUnityDeactivationResume(workspace,recoveryPath){
+ workspace=absoluteRoot(workspace);
+ if(typeof recoveryPath!=='string'||!/^\.pipeline\/migrations\/[a-f0-9-]{36}\/recovery\.json$/.test(recoveryPath))fail('migration.recovery-path');
+ const recovery=await readRecord(resolveChild(workspace,recoveryPath)),r=recovery.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:recovery.digest,previewDigest:digest}))fail('migration.marker-binding');
+ // Once native installation begins this narrow route must not restore its inputs.
+ for(const path of [recoveryPath.replace(/recovery\.json$/,'installation.json'),'.pipeline/state.json']){
+  if((await observeTargets(workspace,[path]))[0].bytes!==null)fail('migration.install-started');
+ }
+ const phase=validateLegacyUnityDeactivation(p.preflight.deactivation);
+ const directory=recoveryPath.replace(/recovery\.json$/,'deactivation');
+ const exists=(await inspectDirectory(resolveChild(workspace,directory))).exists;
+ const names=exists?(await readdir(resolveChild(workspace,directory))).sort():[];
+ if(names.length>6||names.some((name,i)=>name!==String(i).padStart(6,'0')+'.json'))fail('migration.phase-evidence');
+ const events=[],intents=new Set(),completed=new Set();let previous=null,stopped=false;
+ for(let seq=0;seq<names.length;seq++){
+  if(stopped)fail('migration.phase-evidence');
+  const record=await readRecord(resolveChild(workspace,directory+'/'+names[seq]));
+  const event=record.value;let expected;
+  if(seq===0)expected={kind:'start',detail:null};
+  else if(seq===5)expected={kind:'phase-checked',detail:{phase:'deactivate-legacy'}};
+  else{
+   const t=phase.targets[Math.floor((seq-1)/2)];
+   if(seq%2){expected={kind:'intent',detail:{path:t.path,beforeHash:t.beforeHash,afterHash:t.afterHash}};intents.add(t.path);}
+   else{
+    const d=event.detail;
+    if(!d||!['completed','failed','uncertain'].includes(d.status)||
+     !(d.observedHash===null||/^sha256:[a-f0-9]{64}$/.test(d.observedHash)))fail('migration.phase-evidence');
+    if(d.status==='completed'&&d.observedHash!==t.afterHash||d.status==='failed'&&d.observedHash!==t.beforeHash)fail('migration.phase-evidence');
+    stopped=d.status!=='completed';if(!stopped)completed.add(t.path);
+    expected={kind:'outcome',detail:{path:t.path,status:d.status,observedHash:d.observedHash}};
+   }
+  }
+  if(contractDigest(event)!==contractDigest({schemaVersion:1,seq,previous,recoveryHash:recovery.digest,...expected}))fail('migration.phase-evidence');
+  previous=record.digest;events.push({path:directory+'/'+names[seq],hash:record.digest});
+ }
+ 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);
+ }
+ const rows=await observeTargets(workspace,[...expected.keys()]);
+ const classifications=inspectLegacyUnityDeactivation(phase,phase.targets.map(t=>({provider:t.provider,bytes:rows.find(r=>r.path===t.path).bytes})));
+ for(const row of rows){
+  if(phase.targets.some(t=>t.path===row.path))continue;
+  if((row.bytes===null?null:sha256(row.bytes))!==expected.get(row.path))fail('migration.observation-drift');
+ }
+ const conflicts=classifications.filter(t=>t.state==='conflict'||t.state==='after'&&!intents.has(t.path)||t.state==='before'&&completed.has(t.path));
+ const operations=conflicts.length?[]:classifications.map(t=>({path:t.path,
+  action:t.state==='before'?'write-disabled':'confirm-observed',state:t.state,
+  beforeHash:sha256(rows.find(r=>r.path===t.path).bytes),afterHash:phase.targets.find(x=>x.path===t.path).afterHash}));
+ // Recheck evidence and files, without claiming a global atomic snapshot.
+ for(const e of [{path:markerPath,hash:marker.digest},{path:recoveryPath,hash:recovery.digest},...events])
+  if((await readRecord(resolveChild(workspace,e.path))).digest!==e.hash)fail('migration.resume-drift');
+ if(exists&&(await readdir(resolveChild(workspace,directory))).sort().join(',')!==names.join(','))fail('migration.resume-drift');
+ if(!exists&&(await inspectDirectory(resolveChild(workspace,directory))).exists)fail('migration.resume-drift');
+ for(const path of [recoveryPath.replace(/recovery\.json$/,'installation.json'),'.pipeline/state.json'])
+  if((await observeTargets(workspace,[path]))[0].bytes!==null)fail('migration.resume-drift');
+ const after=await observeTargets(workspace,[...expected.keys()]);
+ const fingerprints=items=>items.map(o=>({path:o.path,hash:o.bytes===null?null:sha256(o.bytes)}));
+ if(contractDigest(fingerprints(after))!==contractDigest(fingerprints(rows)))fail('migration.resume-drift');
+ const result={schemaVersion:1,kind:'legacy-unity-deactivation-resume-preview',workspace,recoveryPath,
+  recoveryHash:recovery.digest,markerHash:marker.digest,events,observations:fingerprints(rows),classifications,conflicts,operations,
+  status:conflicts.length?'blocked':'needs-approval',executable:false,runtime:'not-run'};
+ return {...result,digest:contractDigest(result)};
+}