@6reduk/workspace-pipeline 0.1.0

package/src/source/repository-budget.js

@@ -0,0 +1,18 @@
+import { fail } from '../contracts/parse.js';
+
+export const REPOSITORY_TRANSPORT_LIMITS = Object.freeze({
+  packLimit: 100 * 1024 * 1024 * 1024,
+  gitMs: 30 * 60 * 1000,
+  acquisitionMs: 2 * 60 * 60 * 1000
+});
+
+export function repositoryBudget(options = {}) {
+  const result = {};
+  for (const [key, maximum] of Object.entries(REPOSITORY_TRANSPORT_LIMITS)) {
+    const value = options[key] ?? maximum;
+    if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) fail('repository-source.' + key + '-limit');
+    result[key] = value;
+  }
+  if (result.gitMs > result.acquisitionMs) fail('repository-source.time-limits');
+  return result;
+}

package/src/source/snapshot.js

@@ -0,0 +1,37 @@
+import { mkdtemp, mkdir, writeFile, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { fail, ContractError } from '../contracts/parse.js';
+import { portablePath } from '../contracts/semantic.js';
+import { LIMITS, sha256, cap } from './inventory.js';
+
+export function checkDestination(destination, platform = process.platform) {
+  cap(platform === 'win32' ? destination.length : Buffer.byteLength(destination),
+    platform === 'win32' ? LIMITS.windowsPath : LIMITS.posixPath, 'snapshot.path-length');
+}
+// Disposable preparation only. Does not activate an installed workspace.
+// No implicit cleanup: failed preparations remain identifiable to the caller.
+export async function materialize(verified, tempRoot = tmpdir()) {
+  const parent = await realpath(tempRoot);
+  const root = await mkdtemp(path.join(parent, 'wpc-snapshot-'));
+  try {
+  const prepared = [];
+  for (const [name, bytes] of verified.files) {
+    portablePath(name);
+    if (!Buffer.isBuffer(bytes) || sha256(bytes) !== verified.fileHashes[name]) fail('snapshot.input');
+    const target = path.join(root, ...name.split('/'));
+    checkDestination(target);
+    prepared.push([target, bytes]);
+  }
+  for (const [target, bytes] of prepared) {
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, bytes, { flag: 'wx', mode: 0o600 });
+    if (sha256(await readFile(target)) !== sha256(bytes)) fail('snapshot.readback');
+  }
+  return root;
+  } catch (cause) {
+    const error = cause instanceof ContractError ? cause : new ContractError('snapshot.io');
+    error.snapshotPath = root;
+    throw error;
+  }
+}

package/src/workspace/paths.js

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { fail, ContractError } from '../contracts/parse.js';
+import { portablePath } from '../contracts/semantic.js';
+
+export function absoluteRoot(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value) || /[\u0000-\u001f\u007f]/.test(value)) fail('layout.absolute-root');
+  return path.resolve(value);
+}
+export function pathBudget(value, platform = process.platform) {
+  if ((platform === 'win32' ? value.length > 240 : Buffer.byteLength(value) > 1024)) fail('layout.path-length');
+}
+export function resolveChild(root, relative) {
+  if (relative !== '.') portablePath(relative);
+  const target = path.resolve(root, ...relative.split('/'));
+  const rel = path.relative(root, target);
+  if (rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) fail('layout.escape');
+  pathBudget(target);
+  return target;
+}
+// Read-only observation, not an atomic preflight. S5 must recheck before writes.
+// Reject links (including internal ones) rather than guessing their ownership.
+export async function inspectDirectory(value) {
+  const absolute = absoluteRoot(value), parsed = path.parse(absolute);
+  let current = parsed.root, missing = false;
+  try {
+    for (const segment of absolute.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+      if (!missing) {
+        let names;
+        try { names = await readdir(current); }
+        catch (e) {
+          // Traversal may be permitted while parent enumeration is forbidden.
+          // Only an existing exact canonical child can justify continuing.
+          if (!['EACCES', 'EPERM'].includes(e.code)) throw e;
+          const actual = await realpath(path.join(current, segment));
+          if (path.basename(actual) !== segment) fail('layout.case-alias');
+          names = [segment];
+        }
+        const matches = names.filter(n => n.toLowerCase() === segment.toLowerCase());
+        if (matches.length > 1 || (matches.length === 1 && matches[0] !== segment)) fail('layout.case-alias');
+      }
+      current = path.join(current, segment);
+      if (missing) continue;
+      let stat;
+      try { stat = await lstat(current); }
+      catch (e) { if (e.code === 'ENOENT') { missing = true; continue; } throw e; }
+      if (stat.isSymbolicLink()) fail('layout.link');
+      if (!stat.isDirectory()) fail('layout.not-directory');
+      const actual = await realpath(current);
+      if (path.resolve(actual).toLowerCase() !== path.resolve(current).toLowerCase()) fail('layout.reparse');
+    }
+    return { path: absolute, exists: !missing };
+  } catch (e) { throw e instanceof ContractError ? e : new ContractError('layout.io'); }
+}

package/src/workspace/profiles.js

@@ -0,0 +1,8 @@
+import { validateBundle } from '../contracts/semantic.js';
+
+// Pipeline is the verified manifest of the selected S2 snapshot, not a live ref.
+// No filesystem/network lookup or merging is performed at this boundary.
+export function selectProfile(pipeline, workspace, adapters) {
+  const selected = validateBundle(pipeline, workspace, adapters);
+  return structuredClone({ ...selected, profile: workspace.profile ?? null });
+}

package/src/workspace/repositories.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { fail } from '../contracts/parse.js';
+import { absoluteRoot, pathBudget } from './paths.js';
+import { planLayout } from './resolve.js';
+
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const overlaps = (a, b) => {
+  const left = a.toLowerCase(), right = b.toLowerCase();
+  const relative = path.relative(left, right);
+  const inside = relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep));
+  if (inside) return true;
+  const reverse = path.relative(right, left);
+  return reverse === '' || (!path.isAbsolute(reverse) && reverse !== '..' && !reverse.startsWith('..' + path.sep));
+};
+
+// Internal pure intent planner, NOT a saved executable preview. No filesystem,
+// Git, network, approval or installation state is inspected/changed here.
+export function planRepositoryIntents(pipeline, workspace, wrapper, choices, { command, ...layoutOptions } = {}) {
+  if (!['init', 'adopt', 'wrap'].includes(command)) fail('repositories.command');
+  if (!record(choices)) fail('repositories.choices');
+  const layout = planLayout(pipeline, workspace, wrapper, layoutOptions);
+  const ids = Object.keys(layout.repositories).sort();
+  if (Object.keys(choices).length !== ids.length || ids.some(id => !Object.hasOwn(choices, id)))
+    fail('repositories.selection');
+  const operations = [], sources = [];
+  for (const id of ids) {
+    const choice = choices[id];
+    if (!record(choice) || !['keep', 'directory', 'init', 'clone', 'move'].includes(choice.action))
+      fail('repositories.action');
+    const allowed = choice.action === 'move' ? ['action', 'from'] : ['action'];
+    if (Object.keys(choice).some(key => !allowed.includes(key))) fail('repositories.fields');
+    if (command === 'init' && choice.action === 'move') fail('repositories.move-command');
+    const target = layout.repositories[id].path;
+    const operation = { repository: id, action: choice.action, target };
+    if (choice.action === 'init') operation.initialization = { initialBranch:'main', templates:'disabled' };
+    if (choice.action === 'clone') {
+      const source = layout.layout.repositories[id].source;
+      if (!source) fail('repositories.clone-source');
+      // Local path base and ref must be resolved/frozen by the later IO preview.
+      operation.source = structuredClone(source);
+      operation.clonePolicy = {head:'detached',history:'depth-1',origin:'not-configured',templates:'disabled'};
+    }
+    if (choice.action === 'move') {
+      const from = absoluteRoot(choice.from); pathBudget(from);
+      // Do not move a wrapper ancestor, any destination or overlapping sources.
+      const relative = path.relative(from.toLowerCase(), layout.wrapper.toLowerCase());
+      if (relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep)))
+        fail('repositories.wrapper-source');
+      if (Object.values(layout.repositories).some(repo => overlaps(from, repo.path)) || sources.some(source => overlaps(from, source)))
+        fail('repositories.overlap');
+      operation.from = from; sources.push(from);
+    }
+    operations.push(operation);
+  }
+  return { command: command === 'wrap' ? 'adopt' : command, wrapper: layout.wrapper,
+    layout, operations, status: 'intent-only', filesystem: 'not-inspected', executionAuthorized: false };
+}

package/src/workspace/repository-inventory.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { constants } from 'node:fs';
+import { lstat, open, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { ContractError, fail } from '../contracts/parse.js';
+import { absoluteRoot, inspectDirectory } from './paths.js';
+
+// Separate from S2 package caps: user repositories may contain large assets.
+// A cap failure never yields a partial successful inventory.
+const defaults = Object.freeze({ entries: 200000, bytes: 100 * 1024 ** 3, depth: 128 });
+const stamp = s => [s.dev,s.ino,s.mode,s.nlink,s.size,s.mtimeNs,s.ctimeNs].map(String).join(':');
+const identity = s => ({ dev:String(s.dev), ino:String(s.ino), mode:String(s.mode), nlink:String(s.nlink),
+  size:String(s.size), mtimeNs:String(s.mtimeNs), ctimeNs:String(s.ctimeNs) });
+
+// Read-only observation, not an atomic snapshot or proof of movable Git metadata.
+// Includes ignored/untracked data and .git without invoking Git or user hooks.
+export async function inventoryRepository(directory, options = {}) {
+  if (Object.keys(options).some(key => !Object.hasOwn(defaults,key))) fail('repositories.inventory-options');
+  const limits = { ...defaults, ...options };
+  for (const key of Object.keys(defaults))
+    if (!Number.isSafeInteger(limits[key]) || limits[key] < 1 || limits[key] > defaults[key])
+      fail('repositories.inventory-limit');
+  const root = absoluteRoot(directory), entries = [];
+  let bytes = 0;
+  try {
+    if (!(await inspectDirectory(root)).exists) fail('repositories.missing');
+    const visit = async (filename, relative, depth) => {
+      if (depth > limits.depth) fail('repositories.depth');
+      if (entries.length >= limits.entries) fail('repositories.entries');
+      const before = await lstat(filename,{bigint:true});
+      if (before.isSymbolicLink()) fail('repositories.link');
+      if (before.isDirectory()) {
+        await inspectDirectory(filename);
+        const names = (await readdir(filename)).sort();
+        if (names.length > limits.entries - entries.length - 1) fail('repositories.entries');
+        entries.push({path:relative,type:'directory',identity:identity(before)});
+        for (const name of names) await visit(path.join(filename,name),relative === '.' ? name : relative+'/'+name,depth+1);
+        const after = await lstat(filename,{bigint:true});
+        if (stamp(before) !== stamp(after) || JSON.stringify(names) !== JSON.stringify((await readdir(filename)).sort()))
+          fail('repositories.drift');
+      } else if (before.isFile()) {
+        // Shared mutable bytes would invalidate preservation/independence claims.
+        if (before.nlink !== 1n) fail('repositories.hardlink');
+        if (before.size > BigInt(limits.bytes - bytes)) fail('repositories.bytes');
+        await inspectDirectory(path.dirname(filename));
+        const handle = await open(filename,constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        let total = 0;
+        const hash = createHash('sha256');
+        try {
+          if (stamp(before) !== stamp(await handle.stat({bigint:true}))) fail('repositories.drift');
+          const buffer = Buffer.alloc(64 * 1024);
+          for (;;) {
+            const {bytesRead} = await handle.read(buffer,0,buffer.length,null);
+            if (!bytesRead) break;
+            total += bytesRead;
+            if (bytes + total > limits.bytes || BigInt(total) > before.size) fail('repositories.bytes');
+            hash.update(buffer.subarray(0,bytesRead));
+          }
+          if (BigInt(total) !== before.size || stamp(before) !== stamp(await handle.stat({bigint:true})))
+            fail('repositories.drift');
+        } finally { await handle.close(); }
+        if (stamp(before) !== stamp(await lstat(filename,{bigint:true}))) fail('repositories.drift');
+        bytes += total;
+        entries.push({path:relative,type:'file',identity:identity(before),sha256:hash.digest('hex')});
+      } else fail('repositories.special-file');
+    };
+    await visit(root,'.',0);
+    // Catch changes to an earlier file while later entries were read.
+    for (const entry of entries) {
+      const current = await lstat(entry.path === '.' ? root : path.join(root,...entry.path.split('/')),{bigint:true});
+      if (current.isSymbolicLink() || JSON.stringify(identity(current)) !== JSON.stringify(entry.identity)) fail('repositories.drift');
+    }
+    return { root, entries, bytes, status:'observation-only', git:'not-verified',
+      executionAuthorized:false, digest:'sha256:'+createHash('sha256').update(JSON.stringify(entries)).digest('hex') };
+  } catch (error) { throw error instanceof ContractError ? error : new ContractError(
+    error.code==='EBUSY'?'repositories.busy':['EACCES','EPERM'].includes(error.code)?'repositories.access-denied':'repositories.inventory-io'); }
+}

package/src/workspace/repository-observation.js

@@ -0,0 +1,38 @@
+import {contractDigest} from '../contracts/semantic.js';
+import {fail} from '../contracts/parse.js';
+
+const hash=v=>typeof v==='string' && /^sha256:[a-f0-9]{64}$/.test(v);
+const exact=(v,keys)=>v && typeof v==='object' && !Array.isArray(v) &&
+  Object.keys(v).sort().join(',')===[...keys].sort().join(',');
+const identityKeys=['dev','ino','mode','nlink','size','mtimeNs','ctimeNs'];
+
+// Full observations are transient. Saved records bind every entry through the
+// exact identity digest and the separate rename-stable content projection.
+// This is an observation, not proof of execution or permission to replay it.
+export function validateInventorySummary(v) {
+  if(!exact(v,['kind','root','rootIdentity','entryCount','bytes','digest','contentDigest']) ||
+    v.kind!=='repository-inventory-summary' || typeof v.root!=='string' || !v.root ||
+    !exact(v.rootIdentity,identityKeys) || identityKeys.some(k=>typeof v.rootIdentity[k]!=='string' || !/^-?\d+$/.test(v.rootIdentity[k])) ||
+    !Number.isSafeInteger(v.entryCount) || v.entryCount<1 || v.entryCount>200000 ||
+    !Number.isSafeInteger(v.bytes) || v.bytes<0 || v.bytes>100*1024**3 ||
+    !hash(v.digest) || !hash(v.contentDigest))fail('repositories.inventory-summary');
+  return v;
+}
+export function repositoryContentDigest(inventory) {
+  if(inventory?.kind==='repository-inventory-summary')return validateInventorySummary(inventory).contentDigest;
+  return contractDigest(inventory.entries.map(e=>({path:e.path,type:e.type,mode:e.identity.mode,
+    ...(e.type==='file'?{size:e.identity.size,sha256:e.sha256}:{})})));
+}
+export function summarizeInventory(inventory) {
+  if(inventory?.kind==='repository-inventory-summary')return structuredClone(validateInventorySummary(inventory));
+  if(!Array.isArray(inventory?.entries) || inventory.entries[0]?.path!=='.' ||
+    inventory.entries[0]?.type!=='directory')fail('repositories.inventory-summary');
+  return validateInventorySummary({kind:'repository-inventory-summary',root:inventory.root,
+    rootIdentity:structuredClone(inventory.entries[0].identity),entryCount:inventory.entries.length,
+    bytes:inventory.bytes,digest:inventory.digest,contentDigest:repositoryContentDigest(inventory)});
+}
+export function summarizeTree(tree) {
+  if(!Array.isArray(tree?.entries))fail('repository-tree.summary');
+  const {entries,...body}=tree;
+  return {kind:'repository-tree-summary',...body,entryCount:entries.length};
+}

package/src/workspace/repository-preflight.js

@@ -0,0 +1,129 @@
+import path from 'node:path';
+import { lstat, readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { fail, ContractError } from '../contracts/parse.js';
+import { performance } from 'node:perf_hooks';
+import { runRepositoryGit } from '../source/git.js';
+import { repositoryBudget } from '../source/repository-budget.js';
+import { sha256 } from '../source/inventory.js';
+import { absoluteRoot, inspectDirectory } from './paths.js';
+import { inventoryRepository } from './repository-inventory.js';
+
+// Refuse occupied destinations, even empty directories. No overwrite/merge implied.
+export async function inspectRepositoryDestination(directory) {
+  const target = absoluteRoot(directory);
+  try {
+    if ((await inspectDirectory(target)).exists) fail('repositories.destination-exists');
+    let ancestor = path.dirname(target);
+    while (!(await inspectDirectory(ancestor)).exists) ancestor = path.dirname(ancestor);
+    const stat = await lstat(ancestor,{bigint:true});
+    return {target,exists:false,ancestor,ancestorIdentity:{dev:String(stat.dev),ino:String(stat.ino)},
+      executionAuthorized:false};
+  } catch (error) {
+    throw error instanceof ContractError ? error : new ContractError(error.code==='EBUSY'?'repositories.busy':
+      ['EACCES','EPERM'].includes(error.code)?'repositories.access-denied':'repositories.destination-io');
+  }
+}
+
+// Conservative local metadata screening. Passing this is NOT Git health, full
+// relocatability, lock availability or an executable preview. Unknown config blocks.
+export async function inspectRepositoryMetadata(directory, requestedBudget = {}) {
+  const budget=repositoryBudget(requestedBudget);
+  const options={...budget,deadline:requestedBudget.deadline ?? performance.now()+budget.acquisitionMs};
+  const inventory = await inventoryRepository(directory);
+  const entries = new Map(inventory.entries.map(entry=>[entry.path,entry]));
+  const blockers = [];
+  const block = code => { if (!blockers.includes(code)) blockers.push(code); };
+  if (entries.get('.git')?.type !== 'directory') block('git.embedded-directory-required');
+  for (const entry of inventory.entries) {
+    const name = entry.path.toLowerCase();
+    if (name.endsWith('/.git') && name !== '.git') block('git.nested-repository');
+    if (name === '.gitmodules' || name.endsWith('/.gitmodules') || name.startsWith('.git/modules/')) block('git.submodules');
+    if (name === '.git/commondir' || name === '.git/gitdir' || name === '.git/worktrees' || name.startsWith('.git/worktrees/')) block('git.linked-worktrees');
+    if (name === '.git/objects/info/alternates' || name === '.git/objects/info/http-alternates') block('git.external-objects');
+    if (name.startsWith('.git/') && name.endsWith('.lock')) block('git.lock-present');
+    if (name === '.git/config.worktree') block('git.worktree-config');
+    if (['.git/merge_head','.git/cherry_pick_head','.git/revert_head','.git/bisect_start',
+      '.git/rebase-merge','.git/rebase-apply','.git/sequencer'].includes(name)) block('git.operation-pending');
+    if (name.startsWith('.git/hooks/') && entry.type === 'file' && !name.endsWith('.sample')) block('git.active-hooks');
+  }
+  const config = entries.get('.git/config');
+  if (config?.type !== 'file') block('git.config-missing');
+  // Only read embedded config once shape is safe. --no-includes avoids reading
+  // arbitrary include paths. Native Git parses quoting and continuation lines.
+  if (!blockers.length) {
+    const filename = path.join(inventory.root,'.git','config');
+    const verify = async () => {
+      await inspectDirectory(path.dirname(filename));
+      const stat = await lstat(filename,{bigint:true});
+      if (!stat.isFile() || String(stat.ino)!==config.identity.ino || String(stat.dev)!==config.identity.dev || stat.nlink!==1n)
+        fail('repositories.drift');
+      if ('sha256' in config && createHash('sha256').update(await readFile(filename)).digest('hex')!==config.sha256)
+        fail('repositories.drift');
+    };
+    await verify();
+    const output = (await runRepositoryGit(inventory.root,['--git-dir='+path.dirname(filename),
+      '--work-tree='+inventory.root,'config','--file',filename,'--no-includes','--null','--list'],options)).bytes.toString('utf8');
+    await verify();
+    for (const record of output.split('\0').filter(Boolean)) {
+      const split=record.indexOf('\n'), key=(split<0?record:record.slice(0,split)).toLowerCase();
+      const value=split<0?'':record.slice(split+1);
+      if (/^core\.(repositoryformatversion|filemode|logallrefupdates|symlinks|ignorecase|autocrlf|safecrlf|eol|protectntfs|protecthfs)$/.test(key)) continue;
+      if (key==='core.bare' && value==='false') continue;
+      if (key==='extensions.objectformat' && ['sha1','sha256'].includes(value)) continue;
+      if (/^(user\.(name|email)|remote\.[^.]+\.fetch|branch\.[^.]+\.(remote|merge))$/.test(key)) continue;
+      if (/^remote\.[^.]+\.(url|pushurl)$/.test(key) && /^(https:\/\/|ssh:\/\/|[^\s/:]+@[^\s/:]+:)/.test(value)) continue;
+      block('git.config-requires-review');
+    }
+  }
+  // Config parse must not replace evidence with a later state unnoticed.
+  const after = await inventoryRepository(inventory.root);
+  if (after.digest !== inventory.digest) fail('repositories.drift');
+  return {inventory,blockers,status:blockers.length?'blocked':'metadata-screened',
+    gitHealth:'not-verified',executionAuthorized:false};
+}
+
+// Native, read-only local structure checks. Dirty state is evidence, not a
+// rejection. Still not move authorization or certification of relocated behavior.
+export async function inspectRepositoryGit(directory, requestedBudget = {}) {
+  const budget=repositoryBudget(requestedBudget);
+  const execution={...budget,deadline:requestedBudget.deadline ?? performance.now()+budget.acquisitionMs};
+  const screened = await inspectRepositoryMetadata(directory,execution);
+  if (screened.blockers.length) return screened;
+  const root = screened.inventory.root;
+  const prefix = ['--git-dir='+path.join(root,'.git'),'--work-tree='+root];
+  const git = (args, options) => runRepositoryGit(root,[...prefix,...args],{...execution,...options});
+  const text = async args => (await git(args)).bytes.toString('utf8').trim();
+  const format = await text(['rev-parse','--show-object-format=storage']);
+  if (!['sha1','sha256'].includes(format)) fail('repositories.git-format');
+  const oid = value => new RegExp('^[a-f0-9]{'+(format==='sha1'?40:64)+'}$').test(value);
+  const headResult = await git(['rev-parse','--verify','--quiet','HEAD'],{allowMissing:true});
+  let head = headResult.code === 0 ? headResult.bytes.toString('utf8').trim() : null;
+  if (head !== null && !oid(head)) fail('repositories.git-head');
+  if (head === null) {
+    // Missing HEAD is allowed only as an unborn local branch, not detached damage.
+    const branch = await text(['symbolic-ref','HEAD']);
+    if (!branch.startsWith('refs/heads/')) fail('repositories.git-head');
+    const ref = await git(['show-ref','--verify','--quiet',branch],{allowMissing:true});
+    if (ref.code !== 1) fail('repositories.git-head');
+  } else await git(['cat-file','-e',head+'^{commit}']);
+  const index = (await git(['ls-files','--stage','-z'],{outputLimit:256*1024*1024})).bytes;
+  const blockers = [];
+  for (const record of index.toString('utf8').split('\0').filter(Boolean)) {
+    const match = /^(\d{6}) ([a-f0-9]+) ([0-3])\t/.exec(record);
+    if (!match || !oid(match[2])) fail('repositories.git-index');
+    if (match[1]==='160000') blockers.push('git.submodules');
+    if (match[3]!=='0') blockers.push('git.unmerged-index');
+  }
+  // No --lost-found or other repair/write mode. Repository transport budget only.
+  await git(['fsck','--connectivity-only','--no-reflogs','--no-progress']);
+  const status = (await git(['status','--porcelain=v1','-z','--untracked-files=all','--ignore-submodules=all'],
+    {outputLimit:256*1024*1024})).bytes;
+  const after = await inventoryRepository(root);
+  if (after.digest !== screened.inventory.digest) fail('repositories.drift');
+  return {...screened,blockers:[...new Set(blockers)],status:blockers.length?'blocked':'git-inspected',
+    gitHealth:'local-connectivity-checked',head,objectFormat:format,
+    indexDigest:sha256(index),statusDigest:sha256(status),dirty:status.length!==0,
+    // Raw file names/status are intentionally not included in diagnostics.
+    executionAuthorized:false};
+}

package/src/workspace/repository-preview.js

@@ -0,0 +1,196 @@
+import path from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { fail, parse } from '../contracts/parse.js';
+import { contractDigest } from '../contracts/semantic.js';
+import { validateSource, runRepositoryGit, acquireRemoteRepository } from '../source/git.js';
+import {repositoryBudget} from '../source/repository-budget.js';
+import {performance} from 'node:perf_hooks';
+import { absoluteRoot, inspectDirectory } from './paths.js';
+import { planRepositoryIntents } from './repositories.js';
+import { inventoryRepository } from './repository-inventory.js';
+import {summarizeInventory,summarizeTree} from './repository-observation.js';
+import { inspectRepositoryGit, inspectRepositoryDestination } from './repository-preflight.js';
+import { inspectRepositoryTree } from './repository-tree.js';
+import { readRecord } from '../operations/state.js';
+
+async function manifestEvidence(workspace, options) {
+  if (!options.manifestPath) return null; // Internal domain-only callers, never execution-ready.
+  const filename=absoluteRoot(options.manifestPath), extension=path.extname(filename).toLowerCase();
+  if (!['.json','.yaml','.yml'].includes(extension)) fail('manifest.format');
+  const record=await readRecord(filename,extension==='.json'?'json':'yaml');
+  if (contractDigest(record.value)!==contractDigest(workspace)) fail('repositories.manifest-mismatch');
+  const base=path.dirname(record.path);
+  if (options.manifestBase && absoluteRoot(options.manifestBase)!==base) fail('repositories.manifest-base');
+  return {path:record.path,base,bytesDigest:record.digest};
+}
+
+// User repositories are NOT S2 pipeline packages: no pipeline manifest/8 MiB
+// blob limit or supplier code is used to resolve their commit.
+export async function bindLocalRepositorySource(source, manifestBase, options={}) {
+  const budget=repositoryBudget(options),deadline=performance.now()+budget.acquisitionMs;
+  validateSource(source);
+  if (source.subdirectory !== '.') fail('repositories.clone-subdirectory');
+  if (source.transport !== 'local') fail('repositories.local-source-required');
+  const base = absoluteRoot(manifestBase);
+  if (!(await inspectDirectory(base)).exists) fail('repositories.manifest-base');
+  const root = path.resolve(base,source.path);
+  const observed = await inspectRepositoryGit(root,budget);
+  if (observed.blockers.length) fail('repositories.clone-source-blocked');
+  const isOid = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(source.ref);
+  const refs = isOid || source.ref === 'HEAD' || source.ref.startsWith('refs/')
+    ? [source.ref] : ['refs/heads/'+source.ref,'refs/tags/'+source.ref];
+  const found = [];
+  for (const ref of refs) {
+    const result = await runRepositoryGit(root,['--git-dir='+path.join(root,'.git'),'--work-tree='+root,
+      'rev-parse','--verify','--quiet','--end-of-options',ref+'^{commit}'],{...budget,deadline,allowMissing:true});
+    if (result.code === 0) {
+      const commit = result.bytes.toString('utf8').trim();
+      if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit)) fail('repositories.clone-ref-output');
+      found.push(commit);
+    }
+  }
+  if (found.length > 1) fail('repositories.clone-ambiguous-ref');
+  if (!found.length) fail('repositories.clone-missing-ref');
+  if (isOid && found[0] !== source.ref) fail('repositories.clone-not-commit');
+  if ((await inventoryRepository(root)).digest !== observed.inventory.digest) fail('repositories.drift');
+  return { source:structuredClone(source),manifestBase:base,resolvedSource:root,commit:found[0],...budget,
+    sourceObservation:observed,checkout:'commit-only',uncommittedSourceFiles:'not-cloned' };
+}
+
+// Internal read-only candidate. No approval parser/executor may treat this as
+// authorization. Portable saved-preview schema and executable approval are pending.
+export async function prepareRepositoryPreview(pipeline, workspace, wrapper, choices, options = {}) {
+  return prepare(pipeline,workspace,wrapper,choices,options);
+}
+
+async function preparedRemoteBinding(binding, source, preparationRoot, options) {
+  if (!binding || typeof binding !== 'object' || Array.isArray(binding)) fail('repositories.saved-binding');
+  const keys=['source','resolvedSource','preparation','repo','commit','packLimit','gitMs','acquisitionMs','history','checkout','executionAuthorized','preparedInventory'];
+  const budget=repositoryBudget(options),deadline=performance.now()+budget.acquisitionMs;
+  if (Object.keys(binding).sort().join(',')!==keys.sort().join(',')) fail('repositories.saved-binding');
+  const preparation=absoluteRoot(binding.preparation), repo=absoluteRoot(binding.repo);
+  if (path.dirname(preparation)!==preparationRoot || !/^wpc-repository-[A-Za-z0-9_-]+$/.test(path.basename(preparation)) ||
+    repo!==path.join(preparation,'objects.git') || binding.resolvedSource!==source.url ||
+    contractDigest(binding.source)!==contractDigest(source) ||
+    !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(binding.commit) ||
+    Object.keys(budget).some(k=>binding[k]!==budget[k]) || binding.history!=='shallow-depth-1' ||
+    binding.checkout!=='not-performed' || binding.executionAuthorized!==false) fail('repositories.saved-binding');
+  const inventory=await inventoryRepository(repo);
+  if (contractDigest(summarizeInventory(inventory))!==contractDigest(binding.preparedInventory)) fail('repositories.preparation-drift');
+  await runRepositoryGit(repo,['cat-file','-e',binding.commit+'^{commit}'],{...budget,deadline});
+  await runRepositoryGit(repo,['fsck','--connectivity-only','--no-reflogs','--no-progress'],{...budget,deadline});
+  if ((await inventoryRepository(repo)).digest!==inventory.digest) fail('repositories.preparation-drift');
+  return structuredClone(binding);
+}
+
+async function prepare(pipeline, workspace, wrapper, choices, options, savedBindings) {
+  const manifest=await manifestEvidence(workspace,options);
+  options={...options,...(manifest?{manifestBase:manifest.base}:{})};
+  const intents = planRepositoryIntents(pipeline,workspace,wrapper,choices,options);
+  const wrapperState=await inspectDirectory(intents.wrapper);
+  const wrapperStat=wrapperState.exists?await lstat(intents.wrapper,{bigint:true}):null;
+  const wrapperObservation=wrapperStat
+    ? {action:'keep',path:intents.wrapper,identity:{dev:String(wrapperStat.dev),ino:String(wrapperStat.ino)}}
+    : {action:'create',...(await inspectRepositoryDestination(intents.wrapper))};
+  let preparationRoot;
+  if (intents.operations.some(o=>o.action==='clone' && o.source.transport==='remote')) {
+    if (!savedBindings && options.network !== true) fail('source.network-required');
+    preparationRoot = absoluteRoot(options.tempRoot);
+    if (!(await inspectDirectory(preparationRoot)).exists) fail('repository-source.temp-root');
+    const protectedRoots = [intents.wrapper,...intents.operations.filter(o=>o.from).map(o=>o.from),
+      ...intents.operations.filter(o=>o.action==='clone' && o.source.transport==='local')
+        .map(o=>path.resolve(absoluteRoot(options.manifestBase),o.source.path))];
+    for (const root of protectedRoots) {
+      const relative=path.relative(root.toLowerCase(),preparationRoot.toLowerCase());
+      if (relative==='' || (!path.isAbsolute(relative) && relative!=='..' && !relative.startsWith('..'+path.sep)))
+        fail('repository-source.preparation-location');
+    }
+  }
+  const operations = [], blockers = [];
+  if(!wrapperState.exists && wrapperObservation.ancestor!==path.dirname(intents.wrapper))
+    blockers.push({repository:null,code:'repositories.wrapper-parent-missing'});
+  for (const intent of intents.operations) {
+    const operation = {...intent};
+    if (intent.action === 'keep') operation.existing = await inspectRepositoryGit(intent.target);
+    else operation.destination = await inspectRepositoryDestination(intent.target);
+    if(operation.destination &&
+      (wrapperState.exists ? operation.destination.ancestor!==path.dirname(intent.target) : path.dirname(intent.target)!==intents.wrapper))
+      blockers.push({repository:intent.repository,code:'repositories.target-parent-missing'});
+    if (intent.action === 'move') {
+      operation.existing = await inspectRepositoryGit(intent.from);
+      if (operation.existing.inventory.entries[0].identity.dev !== operation.destination.ancestorIdentity.dev)
+        blockers.push({repository:intent.repository,code:'repositories.cross-device-not-supported'});
+    }
+    if (operation.existing)
+      for (const code of operation.existing.blockers) blockers.push({repository:intent.repository,code});
+    if (intent.action === 'clone') {
+      if (intent.source.transport==='local') operation.binding = await bindLocalRepositorySource(intent.source,options.manifestBase,options);
+      else {
+        if (savedBindings) operation.binding=await preparedRemoteBinding(savedBindings.get(intent.repository),intent.source,preparationRoot,options);
+        else {
+          const prepared = await acquireRemoteRepository(intent.source,{tempRoot:preparationRoot,network:options.network,...repositoryBudget(options)});
+          operation.binding = {...prepared,preparedInventory:await inventoryRepository(prepared.repo)};
+        }
+      }
+      operation.checkoutTree=await inspectRepositoryTree(operation.binding.repo ?? operation.binding.resolvedSource,
+        operation.binding.commit,intent.target,operation.binding);
+    }
+    operation.compensation = intent.action === 'keep' ? 'none' : 'fresh-preview-required; no automatic deletion or rollback';
+    operations.push(operation);
+  }
+  // A multi-repository scan may take time: validate every earlier observation
+  // again before returning. This is still not an atomic filesystem snapshot.
+  for (const operation of operations) {
+    const observation = operation.existing ?? operation.binding?.sourceObservation;
+    if (observation && (await inventoryRepository(observation.inventory.root)).digest !== observation.inventory.digest)
+      fail('repositories.drift');
+    if (operation.binding?.preparedInventory &&
+      (await inventoryRepository(operation.binding.repo)).digest !== operation.binding.preparedInventory.digest)
+      fail('repositories.preparation-drift');
+    if (operation.destination && contractDigest(await inspectRepositoryDestination(operation.target)) !== contractDigest(operation.destination))
+      fail('repositories.destination-drift');
+  }
+  if (contractDigest(await manifestEvidence(workspace,options))!==contractDigest(manifest)) fail('repositories.manifest-drift');
+  const finalWrapper=await inspectDirectory(intents.wrapper);
+  if(finalWrapper.exists!==wrapperState.exists)fail('repositories.wrapper-drift');
+  if(finalWrapper.exists) {
+    const stat=await lstat(intents.wrapper,{bigint:true});
+    if(String(stat.dev)!==wrapperObservation.identity.dev || String(stat.ino)!==wrapperObservation.identity.ino)
+      fail('repositories.wrapper-drift');
+  } else if(contractDigest({action:'create',...(await inspectRepositoryDestination(intents.wrapper))})!==contractDigest(wrapperObservation))
+    fail('repositories.wrapper-drift');
+  for(const op of operations) {
+    if(op.existing)op.existing.inventory=summarizeInventory(op.existing.inventory);
+    if(op.binding?.sourceObservation)op.binding.sourceObservation.inventory=summarizeInventory(op.binding.sourceObservation.inventory);
+    if(op.binding?.preparedInventory)op.binding.preparedInventory=summarizeInventory(op.binding.preparedInventory);
+    if(op.checkoutTree)op.checkoutTree=summarizeTree(op.checkoutTree);
+  }
+  const result = {kind:'repository-preview-candidate',command:intents.command,wrapper:intents.wrapper,wrapperObservation,manifest,
+    inputDigest:contractDigest({pipeline,workspace,choices}),layout:intents.layout,
+    operations,blockers,status:blockers.length?'blocked':'review-only',executionAuthorized:false};
+  return {...result,digest:contractDigest(result)};
+}
+
+// Caller supplies independently retained/approved digest and current trusted
+// inputs. A digest copied from the loaded file itself is NOT an approval.
+// Reconstructs semantics from inputs and observations, rejects extra/missing
+// fields through whole-object equality, and never reacquires remote sources.
+export async function revalidateRepositoryPreview(text, expectedDigest, pipeline, workspace, wrapper, choices, options = {}) {
+  if (!/^sha256:[a-f0-9]{64}$/.test(expectedDigest ?? '')) fail('repositories.expected-digest');
+  const saved=parse(text,'json');
+  if (!saved || typeof saved!=='object' || Array.isArray(saved)) fail('repositories.saved-preview');
+  const {digest,...body}=saved;
+  if (digest!==expectedDigest || contractDigest(body)!==expectedDigest) fail('repositories.preview-digest');
+  if (saved.kind!=='repository-preview-candidate' || saved.executionAuthorized!==false ||
+    !Array.isArray(saved.operations)) fail('repositories.saved-preview');
+  const bindings=new Map();
+  for (const operation of saved.operations) {
+    if (!operation || typeof operation!=='object' || typeof operation.repository!=='string' || bindings.has(operation.repository))
+      fail('repositories.saved-preview');
+    bindings.set(operation.repository,operation.binding);
+  }
+  const fresh=await prepare(pipeline,workspace,wrapper,choices,{...options,network:false},bindings);
+  if (contractDigest(fresh)!==contractDigest(saved)) fail('repositories.preview-drift');
+  if (fresh.blockers.length || fresh.status!=='review-only') fail('repositories.preview-blocked');
+  return fresh;
+}