@6reduk/workspace-pipeline 0.1.0

package/src/operations/repository-bootstrap.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { mkdir,open,lstat,rename,readdir } from 'node:fs/promises';
+import { ContractError,fail } from '../contracts/parse.js';
+import { sha256 } from '../source/inventory.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { inspectDirectory } from '../workspace/paths.js';
+import { inspectRepositoryDestination } from '../workspace/repository-preflight.js';
+import { revalidateRepositoryPreview } from '../workspace/repository-preview.js';
+import { acquireBootstrapLock,assertBootstrapLockHeld } from './bootstrap-lock.js';
+import { readRecord } from './state.js';
+
+const identity=s=>({dev:String(s.dev),ino:String(s.ino)});
+async function persist(file,value) {
+  const bytes=Buffer.from(JSON.stringify(value)+'\n'),handle=await open(file,'wx',0o600);
+  try {await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+  if((await readRecord(file)).digest!==sha256(bytes))fail('repository-bootstrap.readback');
+  return sha256(bytes);
+}
+
+// Internal bootstrap phase only. Repository effects and pipeline activation are
+// separate: its original preview cannot be reused after the approved mkdir.
+// A durable external intent precedes mkdir. Any interrupted handoff retains the
+// sibling lock and records for explicit recovery, never recursive rollback.
+export async function createRepositoryWrapper({pipeline,workspace,wrapper,choices,options={},previewText,approval,
+  onLocation=async()=>{},ioBoundary=async()=>{}}) {
+  if(!approval || Object.keys(approval).sort().join(',')!=='decision,previewDigest' || approval.decision!=='approve')
+    fail('repository-bootstrap.approval');
+  const validate=()=>revalidateRepositoryPreview(previewText,approval.previewDigest,pipeline,workspace,wrapper,choices,options);
+  const preview=await validate();
+  if(!preview.manifest)fail('repository-bootstrap.manifest-required');
+  if(preview.wrapperObservation.action!=='create')fail('repository-bootstrap.wrapper-exists');
+  if(!(await inspectDirectory(path.dirname(preview.wrapper))).exists)fail('repository-bootstrap.parent-required');
+  let lock,intentStarted=false,completed=false;
+  try {
+    lock=await acquireBootstrapLock(preview.wrapper,{onLocation});
+    await validate();await assertBootstrapLockHeld(lock);
+    const intentFile=path.join(lock.directory,'intent.json');
+    intentStarted=true;
+    const intentDigest=await persist(intentFile,{schemaVersion:1,kind:'wrapper-create-intent',previewDigest:preview.digest,
+      wrapper:preview.wrapper,before:preview.wrapperObservation,compensation:'no-automatic-rollback'});
+    await ioBoundary('wrapper-intent-persisted',{directory:lock.directory});
+    await assertBootstrapLockHeld(lock);
+    if((await readRecord(intentFile)).digest!==intentDigest)fail('repository-bootstrap.intent-drift');
+    const before={action:'create',...(await inspectRepositoryDestination(preview.wrapper))};
+    if(contractDigest(before)!==contractDigest(preview.wrapperObservation))fail('repository-bootstrap.destination-drift');
+    await mkdir(preview.wrapper);
+    const created=identity(await lstat(preview.wrapper,{bigint:true}));
+    await ioBoundary('wrapper-created',{wrapper:preview.wrapper});
+    await assertBootstrapLockHeld(lock);await inspectDirectory(preview.wrapper);
+    if(contractDigest(identity(await lstat(preview.wrapper,{bigint:true})))!==contractDigest(created) ||
+      (await readdir(preview.wrapper)).length)fail('repository-bootstrap.wrapper-drift');
+    const metadata=path.join(preview.wrapper,'.pipeline');await mkdir(metadata);
+    const metadataIdentity=identity(await lstat(metadata,{bigint:true}));
+    const receipt=path.join(metadata,'repository-bootstrap.json');
+    const receiptDigest=await persist(receipt,{schemaVersion:1,kind:'wrapper-created',previewDigest:preview.digest,
+      wrapper:preview.wrapper,identity:created,metadataIdentity,intentDigest,
+      pipelineActivated:false,repositoryEffectsPerformed:false});
+    await ioBoundary('wrapper-receipt-persisted',{receipt});
+    await assertBootstrapLockHeld(lock);await inspectDirectory(metadata);
+    if(contractDigest(identity(await lstat(preview.wrapper,{bigint:true})))!==contractDigest(created) ||
+      contractDigest(identity(await lstat(metadata,{bigint:true})))!==contractDigest(metadataIdentity))
+      fail('repository-bootstrap.wrapper-drift');
+    const history=path.join(metadata,'repository-bootstrap-intent.json');
+    // Never replace even an untrusted receipt. Rename remains a cooperative,
+    // not hostile-concurrent-writer, guarantee like the surrounding lifecycle.
+    if((await readdir(metadata)).includes(path.basename(history)))fail('repository-bootstrap.history-exists');
+    if((await readRecord(intentFile)).digest!==intentDigest || (await readRecord(receipt)).digest!==receiptDigest)
+      fail('repository-bootstrap.readback');
+    await rename(intentFile,history);
+    const record=await readRecord(receipt);
+    if(record.digest!==receiptDigest || (await readRecord(history)).digest!==intentDigest)fail('repository-bootstrap.readback');
+    completed=true;
+    return {status:'wrapper-created',wrapper:preview.wrapper,receipt,requiresRepositoryPreview:true,
+      pipelineActivated:false,repositoryEffectsPerformed:false};
+  }catch(cause){
+    const error=cause instanceof ContractError?cause:new ContractError('repository-bootstrap.io');
+    if(lock)error.bootstrapDirectory=lock.directory;
+    throw error;
+  }finally{
+    if(lock && (!intentStarted || completed))await lock.release();
+  }
+}

package/src/operations/repository-clone.js

@@ -0,0 +1,63 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fail } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { performance } from 'node:perf_hooks';
+import { runGit, runRepositoryGit } from '../source/git.js';
+import { repositoryBudget } from '../source/repository-budget.js';
+import { summarizeTree } from '../workspace/repository-observation.js';
+import { inventoryRepository } from '../workspace/repository-inventory.js';
+import { inspectRepositoryGit } from '../workspace/repository-preflight.js';
+import { inspectRepositoryTree } from '../workspace/repository-tree.js';
+import { assertLockHeld } from './lock.js';
+import { assertBootstrapLockHeld } from './bootstrap-lock.js';
+
+const policy={head:'detached',history:'depth-1',origin:'not-configured',templates:'disabled'};
+export async function verifyClonedRepository(op,observed) {
+  if(contractDigest(op.clonePolicy)!==contractDigest(policy))fail('repository-clone.policy');
+  // Conservative config screening precedes native status; arbitrary local filter
+  // configuration cannot be executed just because a saved receipt says completed.
+  const git=await inspectRepositoryGit(op.target,op.binding);
+  if(git.blockers.length || git.head!==op.binding.commit || git.dirty || git.inventory.digest!==observed.digest)return false;
+  const tree=await inspectRepositoryTree(op.target,op.binding.commit,op.target,op.binding);
+  if(contractDigest(op.checkoutTree?.kind==='repository-tree-summary'?summarizeTree(tree):tree)!==contractDigest(op.checkoutTree))return false;
+  const expected=new Set(tree.entries.map(e=>e.path));
+  const actual=observed.entries.filter(e=>e.type==='file' && !e.path.startsWith('.git/'));
+  if(actual.length!==expected.size || actual.some(e=>!expected.has(e.path)))return false;
+  // No origin is silently assigned to a temporary staging directory.
+  const remotes=await runGit(op.target,['remote']);
+  return remotes.bytes.length===0;
+}
+
+// Journal intent and destination precheck belong to the caller. Local transport
+// only; no clone hardlinks/shared object database and no account/network access.
+export async function materializeRepositoryClone(op,lock,bootstrap,ioBoundary) {
+  if(contractDigest(op.clonePolicy)!==contractDigest(policy))fail('repository-clone.policy');
+  const budget=repositoryBudget(op.binding), deadline=performance.now()+budget.acquisitionMs;
+  const execute=(args,options={})=>runRepositoryGit(op.target,args,{...budget,deadline,...options});
+  const source=op.binding.repo ?? op.binding.resolvedSource;
+  const before=op.binding.preparedInventory ?? op.binding.sourceObservation.inventory;
+  const guard=async()=>{
+    await assertLockHeld(lock);await assertBootstrapLockHeld(bootstrap);
+    if((await inventoryRepository(source)).digest!==before.digest)fail('repository-clone.source-drift');
+  };
+  await guard();await mkdir(op.target);
+  await ioBoundary('clone-directory-created',{repository:op.repository});
+  await guard();
+  if((await inventoryRepository(op.target)).entries.length!==1)fail('repository-clone.target-drift');
+  await execute(['init','--template=','--object-format='+(op.binding.commit.length===64?'sha256':'sha1')]);
+  await guard();
+  await execute(['-c','protocol.allow=never','-c','protocol.file.allow=always',
+    '-c','fetch.unpackLimit=0','-c','transfer.unpackLimit=0','fetch','--depth=1','--no-tags',
+    '--no-recurse-submodules','--no-auto-maintenance','--no-write-fetch-head','--keep','--',source,op.binding.commit],
+    {objects:path.join(op.target,'.git','objects')});
+  await ioBoundary('clone-fetched',{repository:op.repository});
+  await guard();
+  const staged=await inventoryRepository(op.target);
+  if(staged.entries.some(e=>e.path!=='.' && e.path!=='.git' && !e.path.startsWith('.git/')))fail('repository-clone.target-drift');
+  // Metadata whitelist before checkout, not just after it.
+  const {inspectRepositoryMetadata}=await import('../workspace/repository-preflight.js');
+  if((await inspectRepositoryMetadata(op.target,{...budget,deadline})).blockers.length)fail('repository-clone.metadata');
+  await execute(['-c','core.autocrlf=false','-c','core.attributesFile=/dev/null','checkout','--detach',op.binding.commit]);
+  await guard();
+}

package/src/operations/repository-history.js

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import { lstat,opendir } from 'node:fs/promises';
+import { absoluteRoot,inspectDirectory } from '../workspace/paths.js';
+import { fail } from '../contracts/parse.js';
+import { bootstrapLockDirectory } from './bootstrap-lock.js';
+import { readRecord } from './state.js';
+
+// Location inventory only, not journal/evidence validation or cleanup authority.
+// No recursive enumeration and no secret-bearing record contents in the output.
+export async function listRepositoryHistory(workspace,{maxEntries=1000}={}) {
+  workspace=absoluteRoot(workspace);
+  if(!Number.isSafeInteger(maxEntries) || maxEntries<1 || maxEntries>1000)fail('repository-history.limit-option');
+  const entries=[],diagnostics=[];let count=0;
+  const issue=(error,subject)=>diagnostics.push({code:error.code??'repository-history.io',subject});
+  const consume=()=>{if(++count>maxEntries)fail('repository-history.limit');};
+  const add=async(filename,kind)=>{
+    let info;try{info=await lstat(filename);}catch(e){if(e.code==='ENOENT')return;throw e;}
+    entries.push({path:filename,kind,type:info.isSymbolicLink()?'link':info.isDirectory()?'directory':info.isFile()?'file':'other',
+      deletionEligible:false,protectionReasons:['requires-validated-retention-preview']});
+    if(info.isSymbolicLink() || (!info.isFile() && !info.isDirectory()) || (info.isFile() && info.nlink!==1))
+      fail('repository-history.unsafe-type');
+  };
+  const uuid='[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}';
+  for(const [name,pattern] of [
+    ['repository-journals',new RegExp('^'+uuid+'$')],['repository-evidence',new RegExp('^'+uuid+'$')],
+    ['repository-authorizations',new RegExp('^'+uuid+'\\.json$')],
+    ['repository-inputs',new RegExp('^'+uuid+'\\.json$')],
+    ['repository-lock-recoveries',/^[a-f0-9]{64}$/],
+    ['repository-cleanup',new RegExp('^'+uuid+'\\.json$')],
+    ['repository-completions',new RegExp('^'+uuid+'(?:\\.pending)?\\.json$')]]) {
+    const directory=path.join(workspace,'.pipeline',name);
+    try {
+      if(!(await inspectDirectory(directory)).exists)continue;
+      for await(const entry of await opendir(directory)) {
+        consume();const filename=path.join(directory,entry.name);
+        try{await add(filename,name);}catch(e){issue(e,filename);}
+        if(!pattern.test(entry.name))issue({code:'repository-history.foreign-name'},filename);
+      }
+    }catch(e){issue(e,directory);}
+  }
+  for(const name of ['repository-operation.json','repository-bootstrap.json','repository-bootstrap-intent.json',
+    'repository-bootstrap-recovery.json','repository-bootstrap-recovered-lock']) {
+    const filename=path.join(workspace,'.pipeline',name);
+    try{consume();await inspectDirectory(path.dirname(filename));await add(filename,'repository-bootstrap-record');}
+    catch(e){issue(e,filename);}
+  }
+  const bootstrap=bootstrapLockDirectory(workspace);
+  for(const filename of [bootstrap,bootstrap+'.recovery',bootstrap+'.recovery-resume']) {
+    try{consume();await inspectDirectory(path.dirname(filename));await add(filename,'repository-bootstrap-lock');}
+    catch(e){issue(e,filename);}
+  }
+  const parent=path.dirname(workspace);
+  try {
+    let scanned=0;
+    if((await inspectDirectory(parent)).exists)for await(const item of await opendir(parent)) {
+      if(++scanned>100000)fail('repository-history.parent-limit');
+      const abandoned=/^\.wpc-bootstrap-abandoned-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$(?![\s\S])/.test(item.name);
+      const resolution=new RegExp('^\\.wpc-repository-resolution-'+uuid+'$(?![\\s\\S])').test(item.name);
+      if(!abandoned && !resolution && !/^\.wpc-bootstrap-(?:history|recovery)-[a-f0-9]{64}$(?![\s\S])/.test(item.name))continue;
+      consume();
+      const directory=path.join(parent,item.name);
+      // Historical siblings may belong to another wrapper. Only an exact owner
+      // binding selects one; ambiguous/unreadable history is reported, not deleted.
+      try {
+        await inspectDirectory(directory);
+        if(resolution) {
+          const request=await readRecord(path.join(directory,'request.json'));
+          if(typeof request.value?.wrapper!=='string')fail('repository-history.owner');
+          if(request.value.wrapper===workspace)await add(directory,'repository-resolution-history');
+          continue;
+        }
+        if(abandoned) {
+          const request=await readRecord(path.join(directory,'request.json'));
+          if(typeof request.value?.preview?.wrapper!=='string')fail('repository-history.owner');
+          if(request.value.preview.wrapper===workspace)await add(directory,'repository-bootstrap-abandoned-history');
+          continue;
+        }
+        const owner=await readRecord(path.join(directory,'owner.json'));
+        const isRecovery=item.name.startsWith('.wpc-bootstrap-recovery-');
+        const binding=isRecovery?owner.value?.wrapper:owner.value?.workspace;
+        if(typeof binding!=='string')fail('repository-history.owner');
+        if(binding===workspace)await add(directory,isRecovery?'repository-bootstrap-recovery-history':'repository-bootstrap-history');
+      }catch(e){issue(e,directory);}
+    }
+  }catch(e){issue(e,parent);}
+  // Ancestor creation may have retained ownership evidence above the direct
+  // wrapper parent. Scan only names, under a shared depth/entry bound; never
+  // descend through unrelated directories or infer deletion authority.
+  try {
+    let ancestor=parent,scanned=0,depth=0;
+    for(;depth<32;depth++) {
+      if((await inspectDirectory(ancestor)).exists)for await(const item of await opendir(ancestor)) {
+        if(++scanned>100000)fail('repository-history.ancestor-limit');
+        if(!new RegExp('^\\.wpc-ancestors-'+uuid+'$(?![\\s\\S])').test(item.name))continue;
+        consume();const directory=path.join(ancestor,item.name);
+        try {
+          await inspectDirectory(directory);const request=await readRecord(path.join(directory,'request.json'));
+          if(typeof request.value?.wrapper!=='string')fail('repository-history.owner');
+          if(request.value.wrapper===workspace)await add(directory,'repository-ancestor-history');
+        }catch(e){issue(e,directory);}
+      }
+      const next=path.dirname(ancestor);if(next===ancestor)break;ancestor=next;
+    }
+    if(depth===32)fail('repository-history.ancestor-depth');
+  }catch(e){issue(e,parent);}
+  entries.sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);
+  return {workspace,entries,diagnostics,complete:diagnostics.length===0,validation:'locations-only',deletionEligible:false};
+}

package/src/operations/repository-inputs.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import {mkdir,open} from 'node:fs/promises';
+import {fail,MAX_INPUT_BYTES} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {resolveChild,inspectDirectory} from '../workspace/paths.js';
+import {readRecord} from './state.js';
+import {sha256} from '../source/inventory.js';
+
+function location(wrapper,journal) {
+  if(!/^\.pipeline\/repository-journals\/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(journal))
+    fail('repository-inputs.journal');
+  return resolveChild(wrapper,'.pipeline/repository-inputs/'+path.basename(journal)+'.json');
+}
+function validate(value,wrapper,journal,digest) {
+  if(!value || Object.keys(value).sort().join(',')!=='journal,preview,schemaVersion,wrapper' ||
+    value.schemaVersion!==1 || value.wrapper!==wrapper || value.journal!==journal)
+    fail('repository-inputs.binding');
+  const {digest:actual,...body}=value.preview??{};
+  if(actual!==digest || contractDigest(body)!==digest || body.wrapper!==wrapper ||
+    body.kind!=='repository-preview-candidate')fail('repository-inputs.preview');
+}
+// Recorded before any repository effect. This is recoverable input, not approval
+// to execute/replay: callers still inspect current state and obtain exact authority.
+export async function persistRepositoryInputs(wrapper,journal,preview) {
+  const filename=location(wrapper,journal),value={schemaVersion:1,wrapper,journal,preview};
+  validate(value,wrapper,journal,preview.digest);
+  const bytes=Buffer.from(JSON.stringify(value)+'\n');
+  if(bytes.length>MAX_INPUT_BYTES)fail('repository-inputs.size');
+  try{await mkdir(path.dirname(filename));}catch(e){if(e.code!=='EEXIST')throw e;}
+  await inspectDirectory(path.dirname(filename));
+  const handle=await open(filename,'wx',0o600);
+  try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}
+  if((await readRecord(filename)).digest!==sha256(bytes))fail('repository-inputs.readback');
+  return filename;
+}
+export async function readRepositoryInputs(wrapper,journal,previewDigest) {
+  if(!/^sha256:[a-f0-9]{64}$/.test(previewDigest??''))fail('repository-inputs.digest');
+  const record=await readRecord(location(wrapper,journal));
+  validate(record.value,wrapper,journal,previewDigest);
+  return {previewText:JSON.stringify(record.value.preview),previewDigest,path:record.path,recordDigest:record.digest};
+}

package/src/operations/repository-journal.js

@@ -0,0 +1,127 @@
+import { mkdir,open,readdir } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { fail,ContractError } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { resolveChild,inspectDirectory } from '../workspace/paths.js';
+import { sha256 } from '../source/inventory.js';
+import { readRecord } from './state.js';
+import { assertLockHeld } from './lock.js';
+
+const exact=(o,keys)=>o!==null && typeof o==='object' && !Array.isArray(o) && Object.keys(o).sort().join(',')===[...keys].sort().join(',');
+const hash=s=>typeof s==='string' && /^sha256:[a-f0-9]{64}$/.test(s);
+const file=seq=>String(seq).padStart(6,'0')+'.json';
+function bound(preview) {
+  if (!preview || preview.kind!=='repository-preview-candidate' || !hash(preview.digest) ||
+    !Array.isArray(preview.operations) || !preview.operations.length || preview.operations.length>128)fail('repository-journal.preview');
+  const {digest,...body}=preview;
+  if(contractDigest(body)!==digest)fail('repository-journal.preview');
+  const ids=new Set();
+  for(const op of preview.operations) {
+    if(!op || typeof op.repository!=='string' || ids.has(op.repository))fail('repository-journal.preview');
+    ids.add(op.repository);
+  }
+}
+function advance(state,kind,payload,preview) {
+  const op=preview.operations[state.nextIndex];
+  if(kind==='authorization') {
+    if(state.sequence!==1 || state.authorization!==null || state.pending!==null ||
+      !exact(payload,['path','digest']) || !hash(payload.digest) ||
+      !/^\.pipeline\/repository-authorizations\/[a-f0-9-]{36}\.json$/.test(payload.path))fail('repository-journal.authorization');
+    return {...state,authorization:payload};
+  }
+  if(kind==='intent') {
+    if(state.pending!==null || state.stopped || !op ||
+      !exact(payload,['repository','operationDigest']) || payload.repository!==op.repository || payload.operationDigest!==contractDigest(op))
+      fail('repository-journal.sequence');
+    return {...state,pending:state.nextIndex};
+  }
+  if(kind!=='outcome' || state.pending===null || !exact(payload,['status','evidenceDigest']) ||
+    !['completed','failed','uncertain'].includes(payload.status) ||
+    !(hash(payload.evidenceDigest) || (payload.status==='uncertain' && payload.evidenceDigest===null)))fail('repository-journal.outcome');
+  return {...state,pending:null,nextIndex:state.nextIndex+1,stopped:payload.status!=='completed',outcomes:[...state.outcomes,payload]};
+}
+const initial=()=>({sequence:0,lastHash:null,nextIndex:0,pending:null,stopped:false,outcomes:[],authorization:null});
+function result(state,preview) {
+  const terminal=state.stopped || state.nextIndex===preview.operations.length;
+  return {...state,phase:state.pending!==null?'interrupted':terminal?'terminal':'open',
+    operations:preview.operations.map((op,i)=>({repository:op.repository,
+      ...(state.outcomes[i] ?? {status:state.pending===i?'uncertain':'skipped',evidenceDigest:null})})),
+    // Outcomes are executor claims with evidence references, not self-proving PASS.
+    evidenceVerified:false};
+}
+
+export async function readRepositoryJournal(workspace,relative,preview) {
+  bound(preview);
+  if(workspace!==preview.wrapper || !/^\.pipeline\/repository-journals\/[a-f0-9-]{36}$/.test(relative))fail('repository-journal.path');
+  const directory=resolveChild(workspace,relative);
+  try {
+    await inspectDirectory(directory);const names=(await readdir(directory)).sort();
+    if(!names.length || names.length>2+2*preview.operations.length)fail('repository-journal.sequence');
+    let state=initial();
+    for(let seq=0;seq<names.length;seq++) {
+      if(names[seq]!==file(seq))fail('repository-journal.sequence');
+      const record=await readRecord(resolveChild(workspace,relative+'/'+file(seq))),event=record.value;
+      if(!exact(event,['schemaVersion','seq','previous','previewDigest','kind','payload']) || event.schemaVersion!==1 ||
+        event.seq!==seq || event.previous!==state.lastHash || event.previewDigest!==preview.digest)fail('repository-journal.binding');
+      if(seq===0) {if(event.kind!=='start' || event.payload!==null)fail('repository-journal.sequence');}
+      else {
+        if(event.kind==='authorization' && event.payload?.path!==relative.replace('/repository-journals/','/repository-authorizations/')+'.json')
+          fail('repository-journal.authorization');
+        state=advance(state,event.kind,event.payload,preview);
+      }
+      state={...state,sequence:seq+1,lastHash:record.digest};
+    }
+    return result(state,preview);
+  }catch(error){throw error instanceof ContractError?error:new ContractError('repository-journal.io');}
+}
+
+// Same intent/outcome hash-chain protocol as S5, separate namespace because
+// repository operations are not file replacement plans. No repository IO here.
+export async function createRepositoryJournal(lock,preview,{onLocation=async()=>{},ioBoundary=async()=>{}}={}) {
+  bound(preview);await assertLockHeld(lock);
+  if(preview.wrapper!==lock.workspace || preview.status!=='review-only' || preview.blockers.length)fail('repository-journal.preview');
+  preview=structuredClone(preview);
+  const relative='.pipeline/repository-journals/'+randomUUID(),directory=resolveChild(lock.workspace,relative);
+  let state=initial(),busy=false,broken=false;
+  const persist=async(kind,payload,next)=>{
+    await assertLockHeld(lock);await inspectDirectory(directory);
+    const filename=resolveChild(lock.workspace,relative+'/'+file(state.sequence));
+    const bytes=Buffer.from(JSON.stringify({schemaVersion:1,seq:state.sequence,previous:state.lastHash,previewDigest:preview.digest,kind,payload})+'\n');
+    const handle=await open(filename,'wx',0o600);
+    try {await ioBoundary('opened',{filename});await handle.writeFile(bytes);await handle.sync();await ioBoundary('synced',{filename});}
+    finally {await handle.close();}
+    const record=await readRecord(filename);if(record.digest!==sha256(bytes))fail('repository-journal.readback');
+    state={...next,sequence:state.sequence+1,lastHash:record.digest};
+  };
+  try {
+    await onLocation({directory,relative,status:'planned'});
+    const parent=resolveChild(lock.workspace,'.pipeline/repository-journals');
+    try{await mkdir(parent);}catch(e){if(e.code!=='EEXIST')throw e;}
+    await inspectDirectory(parent);await mkdir(directory);
+    await persist('start',null,state);
+    await onLocation({directory,relative,status:'initialized'});
+    async function append(kind,payload) {
+      if(busy || broken)fail('repository-journal.unavailable');busy=true;
+      try {
+        await assertLockHeld(lock);
+        const head=await readRecord(resolveChild(lock.workspace,relative+'/'+file(state.sequence-1)));
+        if(head.digest!==state.lastHash)fail('repository-journal.drift');
+        const next=advance(state,kind,payload,preview);await persist(kind,payload,next);
+        if(state.stopped || state.nextIndex===preview.operations.length) {
+          const audited=await readRepositoryJournal(lock.workspace,relative,preview);
+          if(audited.lastHash!==state.lastHash || audited.sequence!==state.sequence)fail('repository-journal.drift');
+          return audited;
+        }
+        return result(state,preview);
+      }catch(e){broken=true;throw e instanceof ContractError?e:new ContractError('repository-journal.io');}
+      finally{busy=false;}
+    }
+    return Object.freeze({relative,directory,
+      authorize:binding=>{
+        if(binding?.path!==relative.replace('/repository-journals/','/repository-authorizations/')+'.json')fail('repository-journal.authorization');
+        return append('authorization',binding);
+      },
+      intent:repository=>append('intent',{repository,operationDigest:contractDigest(preview.operations.find(op=>op.repository===repository) ?? null)}),
+      outcome:(status,evidenceDigest)=>append('outcome',{status,evidenceDigest})});
+  }catch(e){const error=e instanceof ContractError?e:new ContractError('repository-journal.io');error.repositoryJournal=relative;throw error;}
+}