@6reduk/workspace-pipeline 0.1.0

package/src/operations/doctor.js

@@ -0,0 +1,214 @@
+import {readConfigField} from './config-fields.js';
+import { absoluteRoot, resolveChild, inspectDirectory } from '../workspace/paths.js';
+import { inspectRepositoryPending } from './repository-pending.js';
+import { readRecord, readState, observeTargets, verifyInstalledSnapshot } from './state.js';
+import { ContractError, fail } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { sha256 } from '../source/inventory.js';
+import { inspectRecovery } from './apply.js';
+import { requestShape } from './ownership.js';
+import { inspectHistory } from './history.js';
+import {inspectPendingSwitch} from './switch-inspect.js';
+import {inspectActivatedSwitch} from './switch-activate.js';
+import {inspectSwitchContinuation} from './switch-continuation-runtime.js';
+
+async function inspectDoctorRecovery(workspace,relative,options={}) {
+  const record=await readRecord(resolveChild(workspace,relative));
+  if(record.value?.kind==='switch-continuation-recovery') {
+    const state=await readState(resolveChild(workspace,'.pipeline/state.json')),pending=state.value.pending!==null;
+    const checked=await inspectSwitchContinuation(workspace,relative,{active:!pending});
+    if(checked.recoveryHash!==record.digest)fail('doctor.observation-drift');
+    return {status:checked.status,statePhase:pending?'pending':'active',journal:record.value.journal,
+      recoveryHash:record.digest,comparisonScope:'switch-exact-projection',fieldProjections:[],
+      diagnostics:pending?['doctor.switch-pending',...(checked.conflicts.length?['doctor.switch-target-drift']:[])]:[]};
+  }
+  if(record.value?.kind!=='switch-recovery')return inspectRecovery(workspace,relative,options);
+  const state=await readState(resolveChild(workspace,'.pipeline/state.json'));
+  const pending=state.value.pending!==null;
+  const checked=pending?await inspectPendingSwitch(workspace,relative):await inspectActivatedSwitch(workspace,relative);
+  if(checked.recoveryHash!==record.digest)fail('doctor.observation-drift');
+  return {status:checked.status,statePhase:pending?'pending':'active',journal:record.value.journal,
+    recoveryHash:record.digest,comparisonScope:'switch-exact-projection',fieldProjections:[],
+    diagnostics:pending?['doctor.switch-pending',...(checked.conflicts.length?['doctor.switch-target-drift']:[])]:[]};
+}
+
+// Configuration readiness only: never runtime, acceptance, cleanup eligibility
+// or authority to repair. Active transactions are matched by content binding,
+// never timestamps. Repeated no-op applications can corroborate the same state;
+// all matching records are checked, not hidden behind one explicit selection.
+export async function inspectInstallation(workspace, options = {}) {
+  requestShape(options,[],['recoveryPath'],'doctor.options');
+  if (Object.hasOwn(options,'recoveryPath') && (typeof options.recoveryPath!=='string' ||
+      !/^\.pipeline\/transactions\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\/recovery\.json$/.test(options.recoveryPath))) fail('recovery.path');
+  workspace = absoluteRoot(workspace);
+  const diagnostics = [], targets = [];
+  const result = {workspace, status:'incomplete', configuration:'not-verified',
+    diagnostics, targets, transactionEvidence:'not-verified', runtime:'not-run',
+    automaticActions:false, ready:false,fieldProjections:[]};
+  const issue = (error, subject) => diagnostics.push({code:error instanceof ContractError ? error.code : 'doctor.io',subject});
+  let selectedPath=options.recoveryPath;
+  const inspectSelectedRecovery = async () => {
+    if (selectedPath===undefined) return;
+    try {
+      const recovery=await inspectDoctorRecovery(workspace,selectedPath,{fieldOwnershipOnly:true});
+      for(const path of recovery.fieldProjections)result.fieldProjections.push({recovery:selectedPath,path});
+      result.recovery={path:selectedPath,status:recovery.status,statePhase:recovery.statePhase,
+        journal:recovery.journal,hash:recovery.recoveryHash,comparisonScope:recovery.comparisonScope,fieldProjections:recovery.fieldProjections};
+      result.transactionEvidence=recovery.status==='applied'?'pass':'fail';
+      for (const code of recovery.diagnostics) diagnostics.push({code,subject:selectedPath});
+      if (recovery.status!=='applied') diagnostics.push({code:'doctor.transaction-not-applied',subject:selectedPath});
+    } catch (error) {
+      result.transactionEvidence='fail';issue(error,'selected-recovery');
+    }
+  };
+  let record;
+  try {
+    const repositories=await inspectRepositoryPending(workspace);
+    if(repositories.blocked){
+      diagnostics.push(...repositories.blockers);
+      if(repositories.blockers.some(b=>b.code==='migration.pending'))result.status='needs-reconciliation';
+      return result;
+    }
+    if (!(await inspectDirectory(workspace)).exists) {
+      diagnostics.push({code:'doctor.workspace-missing',subject:workspace});return result;
+    }
+    result.history=await inspectHistory(workspace);
+    diagnostics.push(...result.history.diagnostics);
+    if ((await inspectDirectory(resolveChild(workspace,'.pipeline/lock'))).exists)
+      diagnostics.push({code:'doctor.lock-present',subject:'.pipeline/lock'});
+    record = await readState(resolveChild(workspace,'.pipeline/state.json'));
+  } catch (error) {
+    issue(error,'.pipeline/state.json');
+    if (error.code==='record.missing' && diagnostics.length===1 &&
+        !(await inspectDirectory(resolveChild(workspace,'.pipeline'))).exists) result.status='not-installed';
+    return result;
+  }
+  const state = record.value;
+  if (absoluteRoot(state.workspace) !== workspace) {
+    diagnostics.push({code:'doctor.workspace-binding',subject:'.pipeline/state.json'});return result;
+  }
+  result.recordedStatus = state.status;
+  if (state.pending !== null) {
+    result.status='needs-reconciliation';
+    diagnostics.push({code:'doctor.pending',subject:'.pipeline/state.json'});
+    if(selectedPath===undefined) {
+      const matches=result.history.entries.filter(e=>['switch','switch-continuation'].includes(e.kind) && e.pendingDigest===state.pending);
+      if(matches.length===1)selectedPath=matches[0].recovery;
+      else if(matches.length>1)diagnostics.push({code:'doctor.switch-pending-binding',subject:'history'});
+    }
+    await inspectSelectedRecovery();return result;
+  }
+  const matchingTransactions=()=>{
+    if(!state.activation)return result.history.entries.filter(item=>item.status==='journal-completed' && item.desiredHash===contractDigest(state.active));
+    const anchor=state.activation,item=result.history.entries.find(e=>e.recovery===anchor.recovery);
+    if(!item || item.status!=='journal-completed' || item.recoveryHash!==anchor.recoveryHash ||
+        item.journalHash!==anchor.journalHead.hash || item.journalSequence!==anchor.journalHead.sequence ||
+        item.desiredHash!==contractDigest(state.active)) {
+      diagnostics.push({code:'doctor.activation-binding',subject:'.pipeline/state.json'});return [];
+    }
+    if(selectedPath!==undefined && selectedPath!==anchor.recovery)
+      diagnostics.push({code:'doctor.activation-selection',subject:selectedPath});
+    return [item];
+  };
+  if (!state.active) {
+    const matches=matchingTransactions();
+    result.matchingTransactions=matches.map(item=>item.recovery);
+    // Absence of an active deployment alone is not proof of completed removal.
+    // Check every matching transaction, never choose one by timestamp or allow
+    // explicit selection to hide another invalid matching record.
+    if(result.history.entries.length && !matches.length)
+      diagnostics.push({code:'doctor.transaction-missing',subject:'history'});
+    if(selectedPath===undefined && matches.length)selectedPath=matches[0].recovery;
+    await inspectSelectedRecovery();
+    for(const match of matches)if(match.recovery!==selectedPath) {
+      try {
+        const checked=await inspectDoctorRecovery(workspace,match.recovery);
+        if(checked.status!=='applied')diagnostics.push({code:'doctor.transaction-not-applied',subject:match.recovery});
+        for(const code of checked.diagnostics)diagnostics.push({code,subject:match.recovery});
+      }catch(error){issue(error,match.recovery);}
+    }
+    try {
+      if(contractDigest(await inspectHistory(workspace))!==contractDigest(result.history))
+        diagnostics.push({code:'doctor.observation-drift',subject:'history'});
+      if((await readState(resolveChild(workspace,'.pipeline/state.json'))).digest!==record.digest)
+        diagnostics.push({code:'doctor.observation-drift',subject:'.pipeline/state.json'});
+      if((await inspectDirectory(resolveChild(workspace,'.pipeline/lock'))).exists &&
+          !diagnostics.some(d=>d.code==='doctor.lock-present'))
+        diagnostics.push({code:'doctor.lock-present',subject:'.pipeline/lock'});
+    }catch(error){issue(error,'readback');}
+    const verified=state.status==='not-installed' && diagnostics.length===0 && result.history.complete &&
+      (!result.history.entries.length || result.transactionEvidence==='pass');
+    result.status=verified?'not-installed':'needs-reconciliation';
+    result.configuration=verified?'not-installed':'fail';
+    if(diagnostics.length && selectedPath!==undefined)result.transactionEvidence='fail';
+    // ready remains false: successful removal is not an installed pipeline.
+    return result;
+  }
+  const matches=matchingTransactions();
+  if (matches.length===0) diagnostics.push({code:'doctor.transaction-missing',subject:'history'});
+  else if (selectedPath===undefined) selectedPath=matches[0].recovery;
+  result.matchingTransactions=matches.map(item=>item.recovery);
+  result.pipeline = {id:state.active.pipelineId,version:state.active.version,providers:[...state.active.providers]};
+  if(state.active.bundles) result.pipeline.bundles=Object.entries(state.active.bundles).map(([id,b])=>({id,
+    suppliedProviders:[...b.providers],installedProviders:b.providers.filter(p=>state.active.providers.includes(p)),
+    entry:b.entry.target,runtime:'not-run'}));
+  try { await verifyInstalledSnapshot(state); }
+  catch (error) { issue(error,'snapshot'); }
+  const names = [...new Set(state.active.owned.map(item=>item.path))];
+  let observations;
+  try { observations = await observeTargets(workspace,names); }
+  catch (error) { issue(error,'targets');return result; }
+  const bytes = new Map(observations.map(item=>[item.path,item.bytes]));
+  for (const owned of state.active.owned) {
+    let actual = null;
+    try {
+      const value = bytes.get(owned.path);
+      if (value !== null && owned.kind === 'file') actual=sha256(value);
+      if (value !== null && owned.kind === 'field') {
+        const field=readConfigField(owned.path,value,owned.pointer);
+        if (field.present) actual=contractDigest(field.value);
+      }
+      if (actual!==owned.managedHash) diagnostics.push({code:'doctor.owned-drift',subject:owned.path,pointer:owned.pointer});
+    } catch (error) {issue(error,owned.path);}
+    targets.push({path:owned.path,pointer:owned.pointer,expectedHash:owned.managedHash,observedHash:actual});
+  }
+  // Bind the selected historical record to the current active deployment, not
+  // merely a valid old journal. inspectRecovery validates that relationship.
+  result.configuration=diagnostics.length?'fail':'pass';
+  await inspectSelectedRecovery();
+  for(const match of matches) if(match.recovery!==selectedPath) {
+    try {
+      const checked=await inspectDoctorRecovery(workspace,match.recovery,{fieldOwnershipOnly:true});
+      for(const path of checked.fieldProjections)result.fieldProjections.push({recovery:match.recovery,path});
+      if(checked.status!=='applied') {
+        result.transactionEvidence='fail';
+        diagnostics.push({code:'doctor.transaction-not-applied',subject:match.recovery});
+      }
+      for(const code of checked.diagnostics) diagnostics.push({code,subject:match.recovery});
+    }catch(error){result.transactionEvidence='fail';issue(error,match.recovery);}
+  }
+  try {
+    const finalHistory=await inspectHistory(workspace);
+    if (contractDigest(finalHistory)!==contractDigest(result.history))
+      diagnostics.push({code:'doctor.observation-drift',subject:'history'});
+    if ((await inspectDirectory(resolveChild(workspace,'.pipeline/lock'))).exists &&
+        !diagnostics.some(d=>d.code==='doctor.lock-present'))
+      diagnostics.push({code:'doctor.lock-present',subject:'.pipeline/lock'});
+    if ((await readState(resolveChild(workspace,'.pipeline/state.json'))).digest!==record.digest)
+      diagnostics.push({code:'doctor.observation-drift',subject:'.pipeline/state.json'});
+    for (const item of await observeTargets(workspace,names)) {
+      const before=bytes.get(item.path);
+      if ((before===null?null:sha256(before))!==(item.bytes===null?null:sha256(item.bytes)))
+        diagnostics.push({code:'doctor.observation-drift',subject:item.path});
+    }
+  } catch (error) {issue(error,'readback');}
+  if (diagnostics.some(d=>d.code==='doctor.observation-drift' || d.subject==='readback'))
+    result.transactionEvidence=selectedPath===undefined?'not-verified':'fail';
+  if (!result.history.complete || result.history.diagnostics.length)
+    result.transactionEvidence='fail';
+  if (state.status!=='ready') diagnostics.push({code:'doctor.state-not-ready',subject:'.pipeline/state.json'});
+  result.configuration=diagnostics.length?'fail':'pass';
+  result.ready=diagnostics.length===0 && result.history.complete && result.transactionEvidence==='pass';
+  result.status=result.ready?'ready':diagnostics.some(d=>d.code==='doctor.owned-drift')?'drift':'needs-reconciliation';
+  return result;
+}

package/src/operations/history.js

@@ -0,0 +1,170 @@
+import {opendir} from 'node:fs/promises';
+import {absoluteRoot,resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {readRecord} from './state.js';
+import {readJournal} from './journal.js';
+import {ContractError,fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {inspectRecovery} from './apply.js';
+import {readSwitchRecovery} from './switch-recovery-store.js';
+import {readSwitchContinuationRecovery} from './switch-continuation-recovery.js';
+import {inspectMigrationPending} from './migration-pending.js';
+
+const idPattern=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const maxEntries=1000;
+async function list(workspace,relative) {
+  const directory=resolveChild(workspace,relative),names=[];
+  if (!(await inspectDirectory(directory)).exists) return names;
+  for await (const entry of await opendir(directory)) {
+    if (names.length>=maxEntries) fail('history.limit');
+    // Inspect exact children rather than following directory entry links.
+    if (!idPattern.test(entry.name)) fail('history.entry-name');
+    await inspectDirectory(resolveChild(workspace,relative+'/'+entry.name));
+    names.push(entry.name);
+  }
+  return names.sort();
+}
+
+// Read-only metadata inventory. A terminal journal is NOT proof of activation,
+// approval, backup validity or current target bytes. All entries remain protected
+// from cleanup until a separate dependency-aware retention scanner certifies them.
+export async function inspectHistory(workspace) {
+  workspace=absoluteRoot(workspace);
+  const entries=[],diagnostics=[],continuations=[],switchContinuations=[];
+  const records=new Map(),predecessors=new Map();
+  const result={workspace,entries,diagnostics,complete:false,automaticActions:false};
+  const issue=(e,subject)=>diagnostics.push({code:e instanceof ContractError?e.code:'history.io',subject});
+  let journals,transactions;
+  try {
+    if (!(await inspectDirectory(workspace)).exists) fail('history.workspace-missing');
+    const migration=await inspectMigrationPending(workspace);
+    if(migration.blocked){diagnostics.push(...migration.blockers);return result;}
+    journals=await list(workspace,'.pipeline/journals');
+    transactions=await list(workspace,'.pipeline/transactions');
+  } catch(e) {issue(e,'inventory');return result;}
+  const js=new Set(journals),ts=new Set(transactions);
+  for (const id of [...new Set([...journals,...transactions])].sort()) {
+    const item={id,journal:js.has(id)?'.pipeline/journals/'+id:null,
+      recovery:ts.has(id)?'.pipeline/transactions/'+id+'/recovery.json':null,
+      status:'unknown',protected:true};
+    entries.push(item);
+    if (!item.journal || !item.recovery) {
+      item.status='orphan';diagnostics.push({code:'history.orphan',subject:id});continue;
+    }
+    try {
+      const filename=resolveChild(workspace,item.recovery),record=await readRecord(filename);
+      records.set(item.recovery,record.value);
+      if(record.value?.kind==='switch-continuation-recovery') {
+        const checked=await readSwitchContinuationRecovery(workspace,item.recovery),journal=checked.journal;
+        const parent=checked.root;
+        if(checked.fileHash!==record.digest)fail('history.observation-drift');
+        records.set(item.recovery,{...record.value,previous:parent.record.previous});
+        item.kind='switch-continuation';item.pendingDigest=checked.record.digest;
+        item.status=journal.status==='completed'?'journal-completed':journal.status==='uncertain'?'uncertain':journal.status==='failed'?'failed':'open';
+        item.recoveryHash=record.digest;item.journalHash=journal.lastFileHash;item.journalSequence=journal.sequence;
+        item.desiredHash=contractDigest(parent.record.prepared.preview.phases[1].preview.plan.desired);
+        switchContinuations.push(item);
+        if(item.status!=='journal-completed')diagnostics.push({code:'history.unfinished',subject:id});
+        continue;
+      }
+      if(record.value?.kind==='switch-recovery') {
+        const checked=await readSwitchRecovery(workspace,item.recovery),journal=checked.journal;
+        if(checked.fileHash!==record.digest)fail('history.observation-drift');
+        item.kind='switch';item.pendingDigest=checked.record.digest;
+        item.status=journal.status==='completed'?'journal-completed':journal.status==='uncertain'?'uncertain':journal.status==='failed'?'failed':'open';
+        item.recoveryHash=record.digest;item.journalHash=journal.lastFileHash;item.journalSequence=journal.sequence;
+        item.desiredHash=contractDigest(checked.record.prepared.preview.phases[1].preview.plan.desired);
+        if(item.status!=='journal-completed')diagnostics.push({code:'history.unfinished',subject:id});
+        continue;
+      }
+      const plan=record.value?.prepared?.preview?.plan,previous=record.value?.previous;
+      const journal=await readJournal(workspace,item.journal,plan,previous);
+      item.status=journal.receipt?.status==='completed'?'journal-completed':
+        journal.phase==='interrupted'?'uncertain':journal.phase==='terminal'?'failed':'open';
+      item.recoveryHash=record.digest;item.journalHash=journal.lastHash;item.journalSequence=journal.sequence;
+      item.desiredHash=contractDigest(plan.desired);
+      if(record.value?.prepared?.kind==='prepared-continuation')continuations.push(item);
+      if (item.status!=='journal-completed') diagnostics.push({code:'history.unfinished',subject:id});
+      if ((await readRecord(filename)).digest!==record.digest) fail('history.observation-drift');
+    } catch(e) {item.status='unknown';issue(e,id);}
+  }
+  // Completed history is checked as historical evidence, not against today's
+  // target bytes. Validate explicit predecessor bindings before using any anchor
+  // to distinguish repeated equal deployments or removal cycles.
+  const byPath=new Map(entries.map(e=>[e.recovery,e]));
+  for(const item of entries) {
+    try {
+      if(item.status==='journal-completed' && !continuations.includes(item)) {
+        if(['switch','switch-continuation'].includes(item.kind)) {
+          const evidence=await (item.kind==='switch'?readSwitchRecovery:readSwitchContinuationRecovery)(workspace,item.recovery);
+          if(evidence.fileHash!==item.recoveryHash || evidence.journal.lastFileHash!==item.journalHash ||
+              evidence.journal.sequence!==item.journalSequence)fail('history.observation-drift');
+        }else {
+        const evidence=await inspectRecovery(workspace,item.recovery,{evidenceOnly:true});
+        if(evidence.recoveryHash!==item.recoveryHash || evidence.journalHead.hash!==item.journalHash ||
+            evidence.journalHead.sequence!==item.journalSequence)fail('history.observation-drift');
+        }
+      }
+      const previous=records.get(item.recovery)?.previous,anchor=previous?.activation;
+      if(anchor) {
+        const parent=byPath.get(anchor.recovery);
+        if(!parent || parent.status!=='journal-completed' || parent.recoveryHash!==anchor.recoveryHash ||
+            parent.journalHash!==anchor.journalHead.hash || parent.journalSequence!==anchor.journalHead.sequence ||
+            parent.desiredHash!==contractDigest(previous.active))fail('history.activation-binding');
+        predecessors.set(item.recovery,anchor.recovery);
+      }
+    }catch(e){issue(e,item.id);}
+  }
+  // Linear graph walk; identical deployment hashes do not define graph edges.
+  const done=new Set();
+  for(const start of predecessors.keys()) {
+    const visiting=new Set();let current=start;
+    while(current && !done.has(current)) {
+      if(visiting.has(current)){diagnostics.push({code:'history.activation-cycle',subject:start});break;}
+      visiting.add(current);current=predecessors.get(current);
+    }
+    for(const name of visiting)done.add(name);
+  }
+  // Keep original status and hashes; only an independently validated completed
+  // continuation can resolve its exact predecessor's unfinished diagnostic.
+  // This proves readbacks, not activation or current target bytes.
+  for(const item of continuations)if(item.status==='journal-completed') {
+    try {
+      const evidence=await inspectRecovery(workspace,item.recovery,{evidenceOnly:true});
+      if(evidence.recoveryHash!==item.recoveryHash)fail('history.observation-drift');
+      const ancestors=evidence.lineage.map(link=>({link,old:entries.find(e=>e.recovery===link.recovery)}));
+      for(const {link,old} of ancestors)if(!old || old.recoveryHash!==link.recoveryHash || old.journalHash!==link.journalHead.hash ||
+          !['open','uncertain','failed','journal-completed'].includes(old.status))fail('history.continuation-binding');
+      for(const {old} of ancestors) {
+      old.resolvedBy=[...(old.resolvedBy??[]),item.recovery].sort();
+      old.resolution='continued';
+      }
+      item.resolves=evidence.resolves.recovery;
+      item.resolvesChain=ancestors.map(({old})=>old.recovery);
+    }catch(e){issue(e,item.id);}
+  }
+  for(const item of switchContinuations)if(item.status==='journal-completed') {
+    try {
+      const evidence=await readSwitchContinuationRecovery(workspace,item.recovery),p=evidence.record.preview;
+      if(evidence.fileHash!==item.recoveryHash || evidence.journal.lastFileHash!==item.journalHash ||
+          evidence.journal.sequence!==item.journalSequence)fail('history.continuation-binding');
+      const ancestors=evidence.ancestors.map(link=>({link,old:byPath.get(link.relative)}));
+      for(const {link,old} of ancestors)if(!old || !['switch','switch-continuation'].includes(old.kind) || !['uncertain','open','journal-completed'].includes(old.status) ||
+          old.recoveryHash!==link.fileHash || old.journalHash!==link.journal.lastFileHash ||
+          old.journalSequence!==link.journal.sequence)fail('history.continuation-binding');
+      for(const {old} of ancestors) {
+        old.resolvedBy=[...(old.resolvedBy??[]),item.recovery].sort();old.resolution='continued';
+      }
+      item.resolves=p.recoveryPath;item.resolvesChain=ancestors.map(({link})=>link.relative);
+    }catch(e){issue(e,item.id);}
+  }
+  for(let i=diagnostics.length-1;i>=0;i--)if(diagnostics[i].code==='history.unfinished' &&
+      entries.some(e=>e.id===diagnostics[i].subject && e.resolution==='continued'))diagnostics.splice(i,1);
+  try {
+    for(const item of entries)if(item.recoveryHash &&
+        (await readRecord(resolveChild(workspace,item.recovery))).digest!==item.recoveryHash)fail('history.observation-drift');
+    if (JSON.stringify(journals)!==JSON.stringify(await list(workspace,'.pipeline/journals')) ||
+        JSON.stringify(transactions)!==JSON.stringify(await list(workspace,'.pipeline/transactions'))) fail('history.observation-drift');
+    result.complete=true;
+  } catch(e) {issue(e,'readback');}
+  return result;
+}

package/src/operations/installer-identity.js

@@ -0,0 +1,49 @@
+import {readdir,lstat,readFile} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {sha256} from '../source/inventory.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {parse,fail} from '../contracts/parse.js';
+
+const installedRoot=fileURLToPath(new URL('../../',import.meta.url));
+// Root override is a trusted test seam, never an argv/source-package option.
+export async function readInstallerIdentity(root=installedRoot){
+ root=path.resolve(root);const files=[];let total=0;
+ const walk=async(relative,depth=0)=>{
+  if(depth>32||files.length>=2048)fail('installer.inventory-limit');
+  const filename=path.join(root,relative),before=await lstat(filename);
+  if(before.isSymbolicLink())fail('installer.inventory-link');
+  if(before.isDirectory()){
+   const names=(await readdir(filename)).sort();if(names.length>2048)fail('installer.inventory-limit');
+   for(const name of names)await walk(relative+'/'+name,depth+1);
+  }else{
+   if(!before.isFile()||before.size>2*1024*1024||total+before.size>64*1024*1024)fail('installer.inventory-limit');
+   const bytes=await readFile(filename),after=await lstat(filename);
+   if(!after.isFile()||after.isSymbolicLink()||before.ino!==after.ino||before.dev!==after.dev||
+    before.mtimeMs!==after.mtimeMs||before.size!==after.size||bytes.length!==before.size)fail('installer.inventory-drift');
+   total+=bytes.length;files.push({path:relative,hash:sha256(bytes)});
+  }
+ };
+ await walk('package.json');await walk('src');await walk('schemas');
+ const packageBytes=await readFile(path.join(root,'package.json'));
+ if(sha256(packageBytes)!==files.find(f=>f.path==='package.json').hash)fail('installer.inventory-drift');
+ const manifest=parse(packageBytes.toString('utf8'),'json');
+ if(typeof manifest.name!=='string'||typeof manifest.version!=='string')fail('installer.package');
+ const body={schemaVersion:1,kind:'installer-payload-identity',name:manifest.name,version:manifest.version,
+  files:files.sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0)};
+ return {...body,digest:contractDigest(body)};
+}
+
+export async function bindMigrationInstaller(preview,root=installedRoot){
+ const installer=await readInstallerIdentity(root);
+ const body={schemaVersion:1,kind:'installer-bound-migration-preview',installer,preview};
+ const record={...body,digest:contractDigest(body)};
+ // Enforce saved-record reader bounds before emitting an unusable preview.
+ parse(JSON.stringify(record),'json');return record;
+}
+export async function verifyMigrationInstaller(record,root=installedRoot){
+ const copy=parse(JSON.stringify(record),'json'),{digest,...body}=copy;
+ if(copy.kind!=='installer-bound-migration-preview'||copy.schemaVersion!==1||contractDigest(body)!==digest)fail('installer.preview-binding');
+ if(contractDigest(await readInstallerIdentity(root))!==contractDigest(copy.installer))fail('installer.changed');
+ return copy.preview;
+}

package/src/operations/journal.js

@@ -0,0 +1,142 @@
+import { mkdir, open, readdir } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { fail, ContractError } from '../contracts/parse.js';
+import { validateOperation, validateReceiptForPlan, contractDigest } from '../contracts/semantic.js';
+import { resolveChild, inspectDirectory } from '../workspace/paths.js';
+import { readRecord } from './state.js';
+import { assertLockHeld } from './lock.js';
+import { sha256 } from '../source/inventory.js';
+
+const nameFor = seq => String(seq).padStart(6, '0') + '.json';
+const exact = (record, keys) => record !== null && typeof record === 'object' &&
+  Object.keys(record).sort().join(',') === [...keys].sort().join(',');
+
+function assertOutcome(target,payload) {
+  if(!exact(payload,['status','observedHash']) || !['completed','failed','uncertain'].includes(payload.status))fail('journal.sequence');
+  if((payload.status==='completed' && payload.observedHash!==target.desiredHash) ||
+      (payload.status==='failed' && payload.observedHash!==target.beforeHash) ||
+      (payload.observedHash!==null && !/^sha256:[a-f0-9]{64}$/.test(payload.observedHash)))fail('journal.outcome');
+}
+
+function receipt(plan, previous, outcomes, pending) {
+  if (pending !== null) outcomes = [...outcomes, {status:'uncertain',observedHash:null}];
+  const operations = plan.targets.map((target, i) => ({operationId:target.id,
+    beforeHash:target.beforeHash,desiredHash:target.desiredHash,
+    ...(outcomes[i] ?? {status:'skipped',observedHash:null})}));
+  const status = operations.every(op=>op.status==='completed') ? 'completed' :
+    operations.some(op=>op.status==='uncertain') ? 'uncertain' : 'failed';
+  return validateReceiptForPlan({schemaVersion:1,kind:'receipt',planDigest:contractDigest(plan),status,operations},plan,previous);
+}
+
+// Read-only interpretation of persisted evidence. No rollback, continuation or
+// ready-state activation. An intent without outcome is uncertain, not failed.
+export async function readJournal(workspace, relative, plan, previous) {
+  validateOperation(plan,previous);
+  if(plan.kind!=='plan')fail('journal.plan');
+  if (plan.workspace !== workspace || !/^\.pipeline\/journals\/[a-f0-9-]{36}$/.test(relative)) fail('journal.path');
+  const directory = resolveChild(workspace,relative);
+  try {
+    await inspectDirectory(directory);
+    const names = (await readdir(directory)).sort();
+    if (!names.length || names.length > 1+2*plan.targets.length) fail('journal.sequence');
+    let chain=null, pending=null, stopped=false; const outcomes=[],planDigest=contractDigest(plan);
+    for (let seq=0;seq<names.length;seq++) {
+      if(names[seq]!==nameFor(seq)) fail('journal.sequence');
+      const record=await readRecord(resolveChild(workspace,relative+'/'+names[seq]));
+      const event=record.value;
+      if(!exact(event,['schemaVersion','seq','previous','planDigest','kind','payload']) || event.schemaVersion!==1 ||
+          event.seq!==seq || event.previous!==chain || event.planDigest!==planDigest) fail('journal.binding');
+      if(seq===0) {
+        if(event.kind!=='start' || event.payload!==null)fail('journal.sequence');
+      } else if(event.kind==='intent') {
+        if(pending!==null || outcomes.length>=plan.targets.length || stopped ||
+          !exact(event.payload,['operationId']) || event.payload.operationId!==plan.targets[outcomes.length].id) fail('journal.sequence');
+        pending=outcomes.length;
+      } else if(event.kind==='outcome') {
+        if(pending===null)fail('journal.sequence');
+        assertOutcome(plan.targets[pending],event.payload);
+        outcomes.push(event.payload);pending=null;stopped=event.payload.status!=='completed';
+      } else fail('journal.sequence');
+      chain=record.digest;
+    }
+    const terminal=outcomes.length===plan.targets.length || stopped;
+    return {sequence:names.length,lastHash:chain,nextIndex:outcomes.length,pending,
+      phase:pending!==null?'interrupted':terminal?'terminal':'open',
+      receipt:terminal || pending!==null ? receipt(plan,previous,outcomes,pending) : null};
+  } catch(error) {throw error instanceof ContractError ? error : new ContractError('journal.io');}
+}
+
+export async function createJournal(lock, plan, previous=null, {ioBoundary=async()=>{},onLocation=async()=>{}}={}) {
+  validateOperation(plan,previous);
+  if(plan.kind!=='plan')fail('journal.plan');
+  await assertLockHeld(lock);
+  if(plan.workspace!==lock.workspace) fail('journal.workspace');
+  plan=structuredClone(plan);previous=structuredClone(previous);
+  const relative='.pipeline/journals/'+randomUUID();
+  const parent=resolveChild(lock.workspace,'.pipeline/journals'), directory=resolveChild(lock.workspace,relative);
+  const planDigest=contractDigest(plan),metrics={headReads:0,recordReadbacks:0,fullAudits:0};
+  async function persist(event) {
+    await assertLockHeld(lock);await inspectDirectory(directory);
+    const filename=resolveChild(lock.workspace,relative+'/'+nameFor(event.seq));
+    const detail={path:relative+'/'+nameFor(event.seq),stagedPath:relative+'/'+nameFor(event.seq)};
+    const bytes=Buffer.from(JSON.stringify(event)+'\n'),handle=await open(filename,'wx',0o600);
+    try {
+      await ioBoundary('opened',detail);
+      await handle.writeFile(bytes);await ioBoundary('written',detail);
+      await handle.sync();await ioBoundary('synced',detail);
+    }
+    finally {await handle.close();}
+    const record=await readRecord(filename);metrics.recordReadbacks++;
+    if(record.digest!==sha256(bytes))fail('journal.readback');
+    await ioBoundary('readback',detail);
+    return record.digest;
+  }
+  async function audit(){metrics.fullAudits++;return readJournal(lock.workspace,relative,plan,previous);}
+  try {
+    await onLocation({relative,directory,status:'planned'});
+    try {await mkdir(parent);}catch(error){if(error.code!=='EEXIST')throw error;}
+    await inspectDirectory(parent);await mkdir(directory);
+    await onLocation({relative,directory,status:'created'});
+    await persist({schemaVersion:1,seq:0,previous:null,planDigest,kind:'start',payload:null});
+    let state=await audit(), busy=false, broken=false;
+    await onLocation({relative,directory,status:'initialized'});
+    async function append(kind,payload) {
+      if(busy || broken)fail('journal.unavailable');
+      busy=true;
+      try {
+        await assertLockHeld(lock);
+        // Constant-size append verification. Older history is fully audited on
+        // terminal outcome and by readJournal (including apply's activation gate).
+        // A changed historical prefix may be detected at that later gate, not at
+        // the next append. This is not protection against hostile OS access.
+        const head=await readRecord(resolveChild(lock.workspace,relative+'/'+nameFor(state.sequence-1)));metrics.headReads++;
+        if(head.digest!==state.lastHash)fail('journal.drift');
+        const current=state;
+        if(kind==='intent') {
+          if(current.phase!=='open' || payload.operationId!==plan.targets[current.nextIndex]?.id)fail('journal.sequence');
+        } else {
+          if(current.pending===null)fail('journal.sequence');
+          assertOutcome(plan.targets[current.pending],payload);
+        }
+        const lastHash=await persist({schemaVersion:1,seq:state.sequence,previous:state.lastHash,planDigest,kind,payload});
+        const nextIndex=state.nextIndex+(kind==='outcome'?1:0),pending=kind==='intent'?state.nextIndex:null;
+        const terminal=nextIndex===plan.targets.length || (kind==='outcome' && payload.status!=='completed');
+        state={sequence:state.sequence+1,lastHash,nextIndex,pending,phase:pending!==null?'interrupted':terminal?'terminal':'open',receipt:null};
+        if(terminal) {
+          const verified=await audit();
+          if(verified.sequence!==state.sequence || verified.lastHash!==state.lastHash || verified.nextIndex!==state.nextIndex ||
+              verified.pending!==state.pending || verified.phase!==state.phase)fail('journal.drift');
+          state=verified;
+        }
+        // Nonterminal append results are compact observations, not receipts.
+        // Recovery reconstructs uncertainty using the full read-only reader.
+        return structuredClone(state);
+      }catch(error){broken=true;throw error instanceof ContractError?error:new ContractError('journal.io');}
+      finally{busy=false;}
+    }
+    return Object.freeze({relative,directory,
+      metrics:()=>({...metrics}),
+      intent: operationId=>append('intent',{operationId}),
+      outcome: (status,observedHash)=>append('outcome',{status,observedHash})});
+  }catch(error){throw error instanceof ContractError?error:new ContractError('journal.io');}
+}