optbrew 0.0.0-stage → 0.1.1

package/lib/install.mjs

@@ -0,0 +1,158 @@
+import { cp, lstat, mkdir, open, readFile, realpath, rename, rm, symlink } from 'node:fs/promises';
+import path from 'node:path';
+import { isDistributedBundlePath, verifyBundle } from '../skills/optbrew/scripts/core/bundle.mjs';
+import { readInstallRecord, writeInstallRecord } from './records.mjs';
+import { resolveTargets, scopePaths } from './paths.mjs';
+
+async function statOrNull(name) {
+  try { return await lstat(name); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function rejectLinkedAncestors(scopeRoot, destination) {
+  const relative = path.relative(scopeRoot, destination);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`outside scope: ${destination}`);
+  let current = scopeRoot;
+  if ((await statOrNull(current))?.isSymbolicLink()) throw new Error(`scope root is a link: ${current}`);
+  for (const part of relative.split(path.sep).slice(0, -1)) {
+    current = path.join(current, part);
+    if ((await statOrNull(current))?.isSymbolicLink()) throw new Error(`junction/link ancestor outside trusted scope: ${current}`);
+  }
+}
+
+async function verifiedManifest(bundleRoot) {
+  if ((await lstat(bundleRoot)).isSymbolicLink()) throw new Error(`bundle root is a link: ${bundleRoot}`);
+  const manifest = JSON.parse(await readFile(path.join(bundleRoot, 'bundle-manifest.json'), 'utf8'));
+  const verification = await verifyBundle({ bundleRoot, manifest });
+  if (verification.status !== 'valid') throw new Error(`bundle integrity failed: ${verification.errors.map(e => `${e.path}:${e.code}`).join(', ')}`);
+  return { manifest, verification };
+}
+
+async function targetOwned(target, record, managedBundle) {
+  const existing = await statOrNull(target.path);
+  const saved = record?.targets.find(item => item.agent === target.agent && item.path === target.path);
+  if (!existing) {
+    if (saved) throw new Error(`registered target missing: ${target.path}`);
+    return false;
+  }
+  if (!saved || saved.managed_target !== managedBundle) throw new Error(`unmanaged optbrew target exists: ${target.path}`);
+  if (saved.strategy === 'link') {
+    if (!existing.isSymbolicLink() || await realpath(target.path) !== await realpath(managedBundle)) throw new Error(`registered link changed: ${target.path}`);
+  } else if (saved.strategy === 'copy') {
+    if (!existing.isDirectory() || existing.isSymbolicLink()) throw new Error(`registered copy changed: ${target.path}`);
+    const check = await verifiedManifest(target.path);
+    if (check.manifest.bundle_hash !== record.bundle_hash) throw new Error(`registered copy changed: ${target.path}`);
+  } else throw new Error(`invalid recorded strategy: ${saved.strategy}`);
+  return true;
+}
+
+/** Initial install and additive target registration; version changes belong to update. */
+export async function install({ bundleRoot, agents, scope, home, projectRoot, dryRun = false, strategy = 'link' }) {
+  if (!['link', 'copy'].includes(strategy)) throw new TypeError('strategy must be link or copy');
+  const { scopeRoot, managedRoot } = scopePaths({ scope, home, projectRoot });
+  const targets = resolveTargets({ agents, scope, home, projectRoot }).map(t => ({ ...t, strategy }));
+  const source = await verifiedManifest(bundleRoot);
+  for (const target of targets) await rejectLinkedAncestors(scopeRoot, target.path);
+  await rejectLinkedAncestors(scopeRoot, path.join(managedRoot, 'bundle'));
+
+  async function inspect() {
+    if (await statOrNull(path.join(managedRoot, 'transaction.json'))) {
+      // Single-quoted literals: neither PowerShell nor a POSIX shell expands $ or backticks inside them.
+      const powershell = `'${managedRoot.replaceAll("'", "''")}'`, posix = `'${managedRoot.replaceAll("'", "'\\''")}'`;
+      throw new Error(`recovery_required: interrupted transaction; run optbrew update before install. PowerShell: optbrew update --record-root ${powershell}; POSIX shell: optbrew update --record-root ${posix}`);
+    }
+    const record = await readInstallRecord(managedRoot);
+    if (record) {
+      if (record.managed_root !== managedRoot || record.scope_id !== `${scope}:${scopeRoot}`) throw new Error('install record scope mismatch');
+      if (record.bundle_hash !== source.manifest.bundle_hash || record.release_version !== source.manifest.release_version) throw new Error('existing release differs; use optbrew update');
+      const managed = await verifiedManifest(path.join(managedRoot, 'bundle'));
+      if (managed.manifest.bundle_hash !== record.bundle_hash) throw new Error('managed bundle differs from record');
+      for (const saved of record.targets) {
+        const canonical = resolveTargets({ agents: [saved.agent], scope, home, projectRoot })[0];
+        if (saved.path !== canonical.path || saved.managed_target !== canonical.managed_target) throw new Error('install record target path mismatch');
+        await rejectLinkedAncestors(scopeRoot, saved.path);
+        await targetOwned(saved, record, path.join(managedRoot, 'bundle'));
+      }
+    } else if (await statOrNull(path.join(managedRoot, 'bundle'))) throw new Error('unmanaged bundle exists');
+    for (const target of targets) await targetOwned(target, record, path.join(managedRoot, 'bundle'));
+    return record;
+  }
+
+  const before = await inspect();
+  const pending = targets.filter(t => !before?.targets.some(saved => saved.agent === t.agent));
+  const decision = { strategy, targets, pending: pending.map(t => t.path), release_version: source.manifest.release_version };
+  if (dryRun) return { status: 'dry_run', dry_run: true, record: null, changed_paths: [], decision, verification: source.verification };
+
+  await mkdir(managedRoot, { recursive: true });
+  const lockPath = path.join(managedRoot, 'install.lock');
+  let lock;
+  try { lock = await open(lockPath, 'wx'); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error('scope install lock already held'); throw error; }
+  const changed = [];
+  try {
+    const record = await inspect();
+    const toAdd = targets.filter(t => !record?.targets.some(saved => saved.agent === t.agent));
+    const managedBundle = path.join(managedRoot, 'bundle');
+    let next = record;
+    if (!record) {
+      const staging = path.join(managedRoot, `bundle.${process.pid}.${Date.now()}.tmp`);
+      try {
+        await cp(bundleRoot, staging, { recursive: true, errorOnExist: true, force: false, dereference: false,
+          filter: sourcePath => isDistributedBundlePath(path.relative(bundleRoot, sourcePath)) });
+        const copied = await verifiedManifest(staging);
+        if (copied.manifest.bundle_hash !== source.manifest.bundle_hash) throw new Error('staged bundle changed');
+        await rename(staging, managedBundle);
+        changed.push(managedBundle);
+      } finally { await rm(staging, { recursive: true, force: true }); }
+      next = {
+        schema_version: '1.0.0', scope_id: `${scope}:${scopeRoot}`, release_version: source.manifest.release_version,
+        bundle_hash: source.manifest.bundle_hash, source: path.resolve(bundleRoot), managed_root: managedRoot,
+        targets: [], file_hashes: Object.fromEntries(source.manifest.files.map(f => [f.path, f.sha256])),
+        previous_releases: [], transaction: { state: 'pending' }, source_ref: 'bundle-manifest.json',
+      };
+      try { await writeInstallRecord(managedRoot, next); }
+      catch (error) {
+        // Only remove the bundle this invocation created, if no record took ownership of it.
+        if (!(await readInstallRecord(managedRoot)) &&
+            (await verifiedManifest(managedBundle)).manifest.bundle_hash === source.manifest.bundle_hash) {
+          await rm(managedBundle, { recursive: true, force: true });
+        }
+        throw error;
+      }
+    }
+    for (const target of toAdd) {
+      await rejectLinkedAncestors(scopeRoot, target.path);
+      if (await statOrNull(target.path)) throw new Error(`unmanaged optbrew target exists: ${target.path}`);
+      await mkdir(path.dirname(target.path), { recursive: true });
+      if (strategy === 'link') {
+        try { await symlink(managedBundle, target.path, process.platform === 'win32' ? 'junction' : 'dir'); }
+        catch (error) { throw new Error(`link unavailable for ${target.path}; retry explicitly with --strategy copy (${error.message})`); }
+      } else {
+        const staging = `${target.path}.${process.pid}.${Date.now()}.tmp`;
+        try {
+          await cp(managedBundle, staging, { recursive: true, errorOnExist: true, force: false });
+          await verifiedManifest(staging);
+          await rename(staging, target.path);
+        } finally { await rm(staging, { recursive: true, force: true }); }
+      }
+      changed.push(target.path);
+      next.targets = [...next.targets, target];
+      next.transaction = { state: 'pending' };
+      try { await writeInstallRecord(managedRoot, next); }
+      catch (error) {
+        // A write failure leaves the previous record intact. Undo only this newly created target.
+        const current = await statOrNull(target.path);
+        if (current?.isSymbolicLink() && await realpath(target.path) === await realpath(managedBundle)) await rm(target.path);
+        else if (current?.isDirectory() && !current.isSymbolicLink() &&
+                 (await verifiedManifest(target.path)).manifest.bundle_hash === source.manifest.bundle_hash) {
+          await rm(target.path, { recursive: true });
+        }
+        throw error;
+      }
+    }
+    if (next.transaction.state !== 'committed') {
+      next.transaction = { state: 'committed' };
+      await writeInstallRecord(managedRoot, next);
+    }
+    return { status: changed.length ? 'installed' : 'unchanged', dry_run: false, record: next, changed_paths: changed, decision, verification: source.verification };
+  } finally { await lock.close(); await rm(lockPath, { force: true }); }
+}

package/lib/paths.mjs

@@ -0,0 +1,30 @@
+import os from 'node:os';
+import path from 'node:path';
+
+const locations = {
+  codex: ['.agents/skills/optbrew', '.agents/skills/optbrew'],
+  'claude-code': ['.claude/skills/optbrew', '.claude/skills/optbrew'],
+  cursor: ['.cursor/skills/optbrew', '.cursor/skills/optbrew'],
+  opencode: ['.config/opencode/skills/optbrew', '.opencode/skills/optbrew'],
+  pi: ['.pi/agent/skills/optbrew', '.pi/skills/optbrew'],
+};
+
+export const supportedAgents = Object.keys(locations);
+
+export function scopePaths({ scope, home = os.homedir(), projectRoot }) {
+  if (scope !== 'user' && scope !== 'project') throw new TypeError('scope must be user or project');
+  if (scope === 'project' && !projectRoot) throw new TypeError('project scope requires --project');
+  const scopeRoot = path.resolve(scope === 'user' ? home : projectRoot);
+  return { scopeRoot, managedRoot: path.join(scopeRoot, scope === 'user' ? '.optbrew/installs/user' : '.optbrew/install') };
+}
+
+/** Fixed host paths confirmed against current host documentation. */
+export function resolveTargets({ agents, scope, home, projectRoot }) {
+  const { scopeRoot, managedRoot } = scopePaths({ scope, home, projectRoot });
+  if (!Array.isArray(agents) || !agents.length) throw new TypeError('at least one agent required');
+  if (new Set(agents).size !== agents.length) throw new TypeError('duplicate agent');
+  return agents.map(agent => {
+    if (!locations[agent]) throw new TypeError(`unknown agent: ${agent}`);
+    return { agent, path: path.join(scopeRoot, locations[agent][scope === 'user' ? 0 : 1]), strategy: 'link', managed_target: path.join(managedRoot, 'bundle') };
+  });
+}

package/lib/records.mjs

@@ -0,0 +1,44 @@
+import { mkdir, readFile, open, rename, rm, lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export function validateInstallRecord(record) {
+  if (record?.schema_version !== '1.0.0') throw new Error('migration_required: unsupported install record schema; use a compatible optbrew release');
+  if (!Array.isArray(record.targets) || !/^[a-f0-9]{64}$/.test(record.bundle_hash) ||
+      typeof record.managed_root !== 'string' || typeof record.scope_id !== 'string' ||
+      typeof record.release_version !== 'string' || !record.file_hashes || typeof record.file_hashes !== 'object' ||
+      !Array.isArray(record.previous_releases) || !['pending', 'committed'].includes(record.transaction?.state)) throw new Error('invalid install record');
+  if (Object.entries(record.file_hashes).some(([name, hash]) => path.isAbsolute(name) || name.split(/[\\/]/).includes('..') || !/^[a-f0-9]{64}$/.test(hash))) throw new Error('invalid install record file hashes');
+  return record;
+}
+
+/** Flush bytes before atomic replacement; callers hold the scope lock. */
+export async function writeDurableJson(file, value) {
+  const temp = `${file}.${randomUUID()}.tmp`;
+  try {
+    const handle = await open(temp, 'wx');
+    try { await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`); await handle.sync(); }
+    finally { await handle.close(); }
+    await rename(temp, file);
+    // Windows cannot open directories for fsync. File flush + rename remains atomic there.
+    if (process.platform !== 'win32') {
+      const directory = await open(path.dirname(file), 'r');
+      try { await directory.sync(); } finally { await directory.close(); }
+    }
+  } finally { await rm(temp, { force: true }); }
+}
+
+export async function readInstallRecord(scopeRoot) {
+  const file = path.join(scopeRoot, 'install-record.json');
+  try {
+    if ((await lstat(file)).isSymbolicLink()) throw new Error('install record is a link');
+    const record = JSON.parse(await readFile(file, 'utf8'));
+    return validateInstallRecord(record);
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+export async function writeInstallRecord(scopeRoot, record) {
+  await mkdir(scopeRoot, { recursive: true });
+  const file = path.join(scopeRoot, 'install-record.json');
+  await writeDurableJson(file, record);
+}

package/lib/transaction.mjs

@@ -0,0 +1,205 @@
+import { cp, lstat, mkdir, open, readFile, readlink, realpath, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { createBundleManifest, isDistributedBundlePath, verifyBundle } from '../skills/optbrew/scripts/core/bundle.mjs';
+import { readInstallRecord, validateInstallRecord, writeDurableJson, writeInstallRecord } from './records.mjs';
+import { resolveTargets, scopePaths } from './paths.mjs';
+
+export async function statOrNull(file) {
+  try { return await lstat(file); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+/** Check the resolved absolute parent immediately before every managed rename. */
+export async function assertManagedPath(scopeRoot, destination) {
+  scopeRoot = path.resolve(scopeRoot);
+  destination = path.resolve(destination);
+  const relative = path.relative(scopeRoot, destination);
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`outside managed scope: ${destination}`);
+  let current = path.parse(scopeRoot).root;
+  for (const part of path.relative(current, path.dirname(destination)).split(path.sep)) {
+    current = path.join(current, part);
+    const stat = await statOrNull(current);
+    if (stat?.isSymbolicLink()) throw new Error(`linked ancestor: ${current}`);
+    if (stat && !stat.isDirectory()) throw new Error(`invalid ancestor: ${current}`);
+    if (stat && path.resolve(await realpath(current)).toLowerCase() !== current.toLowerCase()) throw new Error(`resolved path changed: ${current}`);
+  }
+}
+
+export async function validateScope(recordRoot, record) {
+  validateInstallRecord(record);
+  const match = /^(user|project):(.+)$/.exec(record.scope_id);
+  if (!match) throw new Error('invalid record scope');
+  const [, scope, scopeRoot] = match;
+  const options = { scope, home: scopeRoot, projectRoot: scopeRoot };
+  if (scopePaths(options).managedRoot !== recordRoot || record.managed_root !== recordRoot) throw new Error('install record scope mismatch');
+  await assertManagedPath(scopeRoot, path.join(recordRoot, 'install-record.json'));
+  const agents = record.targets.map(t => t.agent);
+  if (new Set(agents).size !== agents.length) throw new Error('duplicate record target');
+  for (const target of record.targets) {
+    const expected = resolveTargets({ ...options, agents: [target.agent] })[0];
+    if (target.path !== expected.path || target.managed_target !== expected.managed_target || !['copy', 'link'].includes(target.strategy)) throw new Error('install record target ownership mismatch');
+    await assertManagedPath(scopeRoot, target.path);
+  }
+  return scopeRoot;
+}
+
+export async function verifiedBundle(bundleRoot) {
+  if (!(await lstat(bundleRoot)).isDirectory() || (await lstat(bundleRoot)).isSymbolicLink()) throw new Error('bundle ownership: expected real directory');
+  if ((await lstat(path.join(bundleRoot, 'bundle-manifest.json'))).isSymbolicLink()) throw new Error('manifest is a link');
+  const manifest = JSON.parse(await readFile(path.join(bundleRoot, 'bundle-manifest.json'), 'utf8'));
+  if (manifest.schema_version !== '1.0.0') throw new Error('migration_required: unsupported bundle manifest schema');
+  const verification = await verifyBundle({ bundleRoot, manifest });
+  if (verification.status !== 'valid') throw new Error(`bundle integrity failed: ${JSON.stringify(verification.errors)}`);
+  const lock = JSON.parse(await readFile(path.join(bundleRoot, 'source-lock.json'), 'utf8'));
+  if (lock.schema_version !== '1.0.0' || !Array.isArray(lock.files) || !Array.isArray(lock.modules)) throw new Error('invalid source-lock');
+  const hashes = new Map(manifest.files.map(f => [f.path, f.sha256]));
+  const seen = new Set();
+  for (const file of lock.files) {
+    const name = file.package_path?.startsWith('skills/optbrew/') ? file.package_path.slice('skills/optbrew/'.length) : null;
+    if (!name || seen.has(name) || (isDistributedBundlePath(name) && hashes.get(name) !== file.distributed_sha256))
+      throw new Error('source-lock hash/mapping mismatch');
+    seen.add(name);
+  }
+  return { manifest, verification };
+}
+
+export async function copyBundle(source, destination) {
+  await cp(source, destination, { recursive: true, force: false, errorOnExist: true, dereference: false,
+    filter: file => isDistributedBundlePath(path.relative(source, file)) });
+  return verifiedBundle(destination);
+}
+
+/** Fingerprint bytes, including the manifest, to recognize pre/post rename states. */
+export async function fingerprint(file) {
+  const stat = await statOrNull(file);
+  if (!stat) return null;
+  if (stat.isSymbolicLink()) return `link:${await readlink(file)}`;
+  if (!stat.isDirectory()) throw new Error(`unexpected managed path type: ${file}`);
+  const manifest = await createBundleManifest({ bundleRoot: file, releaseVersion: '0.0.0' });
+  const meta = await readFile(path.join(file, 'bundle-manifest.json'));
+  return createHash('sha256').update(manifest.bundle_hash).update(meta).digest('hex');
+}
+
+export async function withScopeLock(recordRoot, action, { recover = false } = {}) {
+  const file = path.join(recordRoot, 'install.lock');
+  let handle;
+  try { handle = await open(file, 'wx'); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    if (!recover || (await lstat(file)).isSymbolicLink()) throw new Error('scope install lock already held');
+    // Serialize stale-owner reclamation so two recoverers cannot remove a new live lock.
+    const reclaimPath = path.join(recordRoot, 'recovery.lock');
+    const reclaim = await open(reclaimPath, 'wx');
+    try {
+      let owner;
+      try { owner = JSON.parse(await readFile(file, 'utf8')); } catch { throw new Error('recovery_required: unknown lock owner'); }
+      if (!Number.isInteger(owner.pid) || owner.pid < 1 || !owner.token) throw new Error('recovery_required: unknown lock owner');
+      try { process.kill(owner.pid, 0); throw new Error('scope install lock already held'); }
+      catch (e) { if (e.code !== 'ESRCH') throw e; }
+      await rm(file);
+      handle = await open(file, 'wx');
+    } finally { await reclaim.close(); await rm(reclaimPath); }
+  }
+  const token = randomUUID();
+  try {
+    await handle.writeFile(JSON.stringify({ pid: process.pid, token })); await handle.sync();
+    return await action();
+  } finally {
+    await handle.close();
+    const owner = JSON.parse(await readFile(file, 'utf8'));
+    if (owner.token === token) await rm(file);
+  }
+}
+
+export function operationPaths(destination, id) {
+  return { path: destination, staging: `${destination}.optbrew-${id}.stage`, previous: path.join(path.dirname(destination), `_백업_원본_optbrew-${id}-${path.basename(destination)}`) };
+}
+
+export async function managedRename(scopeRoot, from, to) {
+  await assertManagedPath(scopeRoot, from);
+  await assertManagedPath(scopeRoot, to);
+  if (await statOrNull(to)) throw new Error(`rename destination exists: ${to}`);
+  await rename(from, to);
+}
+
+export async function readJournal(recordRoot) {
+  const file = path.join(recordRoot, 'transaction.json');
+  if (!(await statOrNull(file))) return null;
+  if ((await lstat(file)).isSymbolicLink()) throw new Error('journal is a link');
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+export async function finishJournal(recordRoot, journal, state) {
+  journal.state = state;
+  await writeDurableJson(path.join(recordRoot, 'transaction.json'), journal);
+  const directory = path.join(recordRoot, 'transactions', journal.id);
+  await mkdir(directory, { recursive: true });
+  await managedRename(await validateScope(recordRoot, journal.before), path.join(recordRoot, 'transaction.json'), path.join(directory, 'receipt.json'));
+}
+
+async function recoverLocked(recordRoot) {
+  const journal = await readJournal(recordRoot);
+  if (!journal) return { status: 'clean', restored_version: null, unresolved_paths: [], evidence_ref: null };
+  const evidence_ref = path.join(recordRoot, 'transaction.json');
+  try {
+    if (journal.schema_version !== '1.0.0' || !/^[a-f0-9-]{36}$/.test(journal.id) || !Array.isArray(journal.operations)) throw new Error('invalid journal');
+    const scopeRoot = await validateScope(recordRoot, journal.before);
+    await validateScope(recordRoot, journal.after);
+    const expected = [path.join(recordRoot, 'bundle'), ...journal.before.targets.filter(t => t.strategy === 'copy').map(t => t.path)];
+    if (journal.operations.length !== expected.length || journal.after.scope_id !== journal.before.scope_id || JSON.stringify(journal.after.targets) !== JSON.stringify(journal.before.targets)) throw new Error('journal target mismatch');
+    for (const [i, op] of journal.operations.entries()) {
+      const canonical = operationPaths(expected[i], journal.id);
+      if (Object.keys(canonical).some(k => canonical[k] !== op[k])) throw new Error('journal path ownership mismatch');
+      for (const p of Object.values(canonical)) await assertManagedPath(scopeRoot, p);
+      const current = await fingerprint(op.path), old = await fingerprint(op.previous), staged = await fingerprint(op.staging);
+      if (old !== null && old !== op.before_hash || staged !== null && staged !== op.after_hash ||
+          current !== null && current !== op.before_hash && current !== op.after_hash ||
+          old === null && current !== op.before_hash) throw new Error(`unresolved managed path: ${op.path}`);
+    }
+    const currentRecord = await readInstallRecord(recordRoot);
+    if (JSON.stringify(currentRecord) !== JSON.stringify(journal.before) && JSON.stringify(currentRecord) !== JSON.stringify(journal.after)) throw new Error('install record changed during transaction');
+    const snapshot = path.join(recordRoot, 'releases', journal.id, 'bundle');
+    await assertManagedPath(scopeRoot, snapshot);
+    const verified = await verifiedBundle(snapshot);
+    if (verified.manifest.bundle_hash !== journal.before.bundle_hash || verified.manifest.release_version !== journal.before.release_version) throw new Error('previous snapshot changed');
+    for (const target of journal.before.targets.filter(t => t.strategy === 'link')) {
+      if (!(await statOrNull(target.path))?.isSymbolicLink() || path.resolve(path.dirname(target.path), await readlink(target.path)) !== path.join(recordRoot, 'bundle')) throw new Error(`link ownership changed: ${target.path}`);
+    }
+    if (journal.state === 'committed') {
+      if (JSON.stringify(currentRecord) !== JSON.stringify(journal.after)) throw new Error('committed record mismatch');
+      for (const op of journal.operations) if (await fingerprint(op.path) !== op.after_hash) throw new Error('committed readback mismatch');
+      await finishJournal(recordRoot, journal, 'committed');
+      return { status: 'committed', restored_version: journal.after.release_version, unresolved_paths: [], evidence_ref };
+    }
+    for (const op of [...journal.operations].reverse()) {
+      if (await statOrNull(op.previous)) {
+        if (await statOrNull(op.path)) {
+          if (await statOrNull(op.staging)) throw new Error(`staging conflict: ${op.path}`);
+          await managedRename(scopeRoot, op.path, op.staging);
+        }
+        await managedRename(scopeRoot, op.previous, op.path);
+      }
+      if (await fingerprint(op.path) !== op.before_hash) throw new Error(`restore readback failed: ${op.path}`);
+    }
+    await writeInstallRecord(recordRoot, journal.before);
+    for (const op of journal.operations) {
+      const restored = await verifiedBundle(op.path);
+      if (restored.manifest.bundle_hash !== journal.before.bundle_hash || restored.manifest.release_version !== journal.before.release_version) throw new Error(`restored local edits require review: ${op.path}`);
+    }
+    await finishJournal(recordRoot, journal, 'recovered');
+    return { status: 'recovered', restored_version: journal.before.release_version, unresolved_paths: [], evidence_ref: path.join(recordRoot, 'transactions', journal.id, 'receipt.json') };
+  } catch (error) {
+    return { status: 'recovery_required', restored_version: null, unresolved_paths: [error.message], evidence_ref };
+  }
+}
+
+/** Never replace unknown paths, edited recovery material, or an active process's lock. */
+export async function recoverTransaction(recordRoot) {
+  recordRoot = path.resolve(recordRoot);
+  try {
+    const record = await readInstallRecord(recordRoot);
+    if (!record) throw new Error('install record missing');
+    await validateScope(recordRoot, record);
+    return await withScopeLock(recordRoot, () => recoverLocked(recordRoot), { recover: true });
+  } catch (error) { return { status: 'recovery_required', restored_version: null, unresolved_paths: [error.message], evidence_ref: path.join(recordRoot, 'transaction.json') }; }
+}

package/lib/update.mjs

@@ -0,0 +1,181 @@
+import { lstat, mkdir, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { createBundleManifest } from '../skills/optbrew/scripts/core/bundle.mjs';
+import { readInstallRecord, writeDurableJson, writeInstallRecord } from './records.mjs';
+import { assertManagedPath, copyBundle, fingerprint, finishJournal, managedRename, operationPaths,
+  readJournal, recoverTransaction, statOrNull, validateScope, verifiedBundle, withScopeLock } from './transaction.mjs';
+
+const versionPattern = /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/;
+function compareVersions(a, b) {
+  const parse = v => v.split('+')[0].split('-');
+  const [aBase, ...aPre] = parse(a), [bBase, ...bPre] = parse(b);
+  const x = aBase.split('.').map(Number), y = bBase.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return Math.sign(x[i] - y[i]);
+  if (!aPre.length || !bPre.length) return Math.sign(bPre.length - aPre.length);
+  const ap = aPre.join('-').split('.'), bp = bPre.join('-').split('.');
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    if (ap[i] === bp[i]) continue;
+    if (ap[i] === undefined || bp[i] === undefined) return ap[i] === undefined ? -1 : 1;
+    const an = /^\d+$/.test(ap[i]), bn = /^\d+$/.test(bp[i]);
+    if (an && bn) return Math.sign(Number(ap[i]) - Number(bp[i]));
+    if (an !== bn) return an ? -1 : 1;
+    return ap[i] < bp[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Registry metadata only. An explicitly confirmed package name is required. */
+export async function checkUpdates({ packageName, currentVersion, registryTransport }) {
+  if (!versionPattern.test(currentVersion)) throw new TypeError('invalid current version');
+  if (!packageName) return { current_version: currentVersion, latest_version: null, status: 'local_only', source_ref: 'bundled release; registry package unconfirmed' };
+  if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(packageName)) throw new TypeError('invalid registry package name');
+  const source_ref = `https://registry.npmjs.org/${encodeURIComponent(packageName)}`;
+  const transport = registryTransport ?? (async () => {
+    const response = await fetch(source_ref, { signal: AbortSignal.timeout(10000), redirect: 'error', headers: { accept: 'application/json' } });
+    if (!response.ok) throw new Error(`registry HTTP ${response.status}`);
+    return response.json();
+  });
+  const metadata = await transport(packageName);
+  const latest = metadata?.['dist-tags']?.latest;
+  if (!versionPattern.test(latest)) throw new Error('registry latest version missing or invalid');
+  return { current_version: currentVersion, latest_version: latest, status: compareVersions(latest, currentVersion) > 0 ? 'update_available' : 'current', source_ref };
+}
+
+function matchesRecord(manifest, record) {
+  return manifest.bundle_hash === record.bundle_hash && manifest.release_version === record.release_version &&
+    JSON.stringify(Object.fromEntries(manifest.files.map(f => [f.path, f.sha256]))) === JSON.stringify(record.file_hashes);
+}
+
+async function inspect(recordRoot, record, localChanges) {
+  const scopeRoot = await validateScope(recordRoot, record);
+  if (record.transaction.state !== 'committed') throw new Error('recovery_required: pending initial install; finish optbrew install first');
+  const conflicts = [];
+  const bundle = path.join(recordRoot, 'bundle');
+  for (const target of [{ path: bundle, strategy: 'copy' }, ...record.targets]) {
+    await assertManagedPath(scopeRoot, target.path);
+    const stat = await statOrNull(target.path);
+    if (target.strategy === 'link') {
+      if (!stat?.isSymbolicLink() || await realpath(target.path) !== await realpath(bundle)) throw new Error(`link ownership changed: ${target.path}`);
+      continue;
+    }
+    if (!stat?.isDirectory() || stat.isSymbolicLink()) throw new Error(`copy ownership changed: ${target.path}`);
+    // Hash the current bytes against the recorded allowlist, never trust a rewritten manifest.
+    const actual = await createBundleManifest({ bundleRoot: target.path, releaseVersion: record.release_version });
+    const manifestPath = path.join(target.path, 'bundle-manifest.json');
+    if ((await lstat(manifestPath)).isSymbolicLink()) throw new Error('manifest ownership changed');
+    const saved = JSON.parse(await readFile(manifestPath, 'utf8'));
+    if (!matchesRecord(actual, record) || !matchesRecord(saved, record)) conflicts.push({ path: target.path, reason: 'recorded file hashes or manifest changed' });
+  }
+  if (conflicts.length && localChanges === 'abort') throw new Error(`local changes: ${conflicts.map(c => c.path).join(', ')}; use --local-changes backup-and-replace to preserve and replace`);
+  return { scopeRoot, conflicts };
+}
+
+async function compatible(previous, next) {
+  // No migration is shipped. Changes to the persisted schema or evaluation contract require one.
+  const contractFiles = ['references/schemas/contract.schema.json', 'references/check-registry.json',
+    'references/profiles.json', 'references/scoring.md', 'references/measurement.md', 'scripts/core/score.mjs',
+    'scripts/core/weights.mjs', 'scripts/core/protocol.mjs', 'scripts/core/contracts.mjs',
+    'scripts/core/compare.mjs', 'scripts/core/metrics.mjs', 'scripts/core/bootstrap.mjs'];
+  for (const name of contractFiles) {
+    const old = previous.files.find(f => f.path === name)?.sha256;
+    const current = next.files.find(f => f.path === name)?.sha256;
+    if (old !== current) throw new Error(`migration_required: ${name} changed; use a release with an explicit migration before updating this scope`);
+  }
+  for (const field of ['evaluation_version', 'protocol_version']) {
+    if (previous[field] !== next[field]) throw new Error(`migration_required: ${field} changed or became unknown`);
+  }
+}
+
+async function applyRelease({ bundleRoot, recordRoot, localChanges, faultHook, kind, expectedSnapshot }) {
+  if (!['abort', 'backup-and-replace'].includes(localChanges)) throw new TypeError('localChanges must be abort or backup-and-replace');
+  recordRoot = path.resolve(recordRoot);
+  const original = await readInstallRecord(recordRoot);
+  if (!original) throw new Error('install record missing');
+  await validateScope(recordRoot, original);
+  if (await readJournal(recordRoot)) {
+    const recovery = await recoverTransaction(recordRoot);
+    return { status: recovery.status === 'recovery_required' ? 'recovery_required' : 'recovered', record: await readInstallRecord(recordRoot), changed_paths: [], decision: { recovery, instruction: 'rerun the requested update after recovery' }, verification: null };
+  }
+  return withScopeLock(recordRoot, async () => {
+    // A different writer may have left a journal between preflight and lock acquisition.
+    if (await readJournal(recordRoot)) throw new Error('recovery_required: transaction appeared; rerun update or rollback to recover');
+    const before = await readInstallRecord(recordRoot);
+    const { scopeRoot, conflicts } = await inspect(recordRoot, before, localChanges);
+    const source = await verifiedBundle(bundleRoot);
+    if (expectedSnapshot && (source.manifest.bundle_hash !== expectedSnapshot.bundle_hash || source.manifest.release_version !== expectedSnapshot.release_version)) throw new Error('rollback snapshot identity mismatch');
+    if (source.manifest.release_version === before.release_version && source.manifest.bundle_hash !== before.bundle_hash) throw new Error('release version reused with different bundle');
+    if (kind === 'update' && compareVersions(source.manifest.release_version, before.release_version) < 0) throw new Error('older bundle requires rollback');
+    if (source.manifest.bundle_hash === before.bundle_hash && source.manifest.release_version === before.release_version && !conflicts.length) return { status: 'unchanged', record: before, changed_paths: [], decision: {}, verification: source.verification };
+    const managed = path.join(recordRoot, 'bundle');
+    let previousRoot = managed;
+    if (conflicts.some(c => c.path === managed)) previousRoot = before.source;
+    const previous = await verifiedBundle(previousRoot);
+    if (!matchesRecord(previous.manifest, before)) throw new Error('previous verified bundle unavailable; preserve edits and recover original release first');
+    await compatible(previous.manifest, source.manifest);
+    const id = randomUUID();
+    const snapshotRoot = path.join(recordRoot, 'releases', id, 'bundle');
+    await assertManagedPath(scopeRoot, snapshotRoot);
+    await mkdir(path.dirname(snapshotRoot), { recursive: true });
+    const snapshot = await copyBundle(previousRoot, snapshotRoot);
+    if (!matchesRecord(snapshot.manifest, before)) throw new Error('previous snapshot integrity failed');
+    const operations = [];
+    for (const destination of [managed, ...before.targets.filter(t => t.strategy === 'copy').map(t => t.path)]) {
+      const op = operationPaths(destination, id);
+      await assertManagedPath(scopeRoot, op.staging);
+      if (await statOrNull(op.previous) || await statOrNull(op.staging)) throw new Error('transaction staging already exists');
+      const staged = await copyBundle(bundleRoot, op.staging);
+      if (JSON.stringify(staged.manifest) !== JSON.stringify(source.manifest)) throw new Error('staged bundle identity changed');
+      operations.push({ ...op, before_hash: await fingerprint(destination), after_hash: await fingerprint(op.staging) });
+    }
+    const decision = { local_changes: localChanges, conflicts, backups: operations.map(op => ({ path: op.path, backup: op.previous })) };
+    const after = { ...before, release_version: source.manifest.release_version, bundle_hash: source.manifest.bundle_hash,
+      source: path.resolve(bundleRoot), file_hashes: Object.fromEntries(source.manifest.files.map(f => [f.path, f.sha256])),
+      previous_releases: [...before.previous_releases, { release_version: before.release_version, bundle_hash: before.bundle_hash, bundle_root: snapshotRoot }],
+      transaction: { state: 'committed', id, kind, conflicts, backups: decision.backups } };
+    const journal = { schema_version: '1.0.0', id, state: 'prepared', before, after, operations };
+    await writeDurableJson(path.join(recordRoot, 'transaction.json'), journal);
+    try {
+      await faultHook?.('after_staging');
+      // Reinspect after staging so edits made while preparing cannot be silently overwritten.
+      await inspect(recordRoot, before, localChanges);
+      for (const [index, op] of operations.entries()) {
+        if (await fingerprint(op.path) !== op.before_hash || await fingerprint(op.staging) !== op.after_hash) throw new Error('local changes during transaction preparation');
+        await managedRename(scopeRoot, op.path, op.previous);
+        if (await fingerprint(op.previous) !== op.before_hash) throw new Error('backup readback failed');
+        await managedRename(scopeRoot, op.staging, op.path);
+        if (await fingerprint(op.path) !== op.after_hash) throw new Error('target readback failed');
+        if (index === 1 || (index === 0 && operations.length === 1)) await faultHook?.('after_first_target');
+      }
+      await faultHook?.('before_record_replace');
+      await inspect(recordRoot, after, 'abort');
+      if (JSON.stringify(await readInstallRecord(recordRoot)) !== JSON.stringify(before)) throw new Error('install record changed during transaction');
+      await writeInstallRecord(recordRoot, after);
+      if (JSON.stringify(await readInstallRecord(recordRoot)) !== JSON.stringify(after)) throw new Error('record readback failed');
+      await inspect(recordRoot, after, 'abort');
+      await finishJournal(recordRoot, journal, 'committed');
+      return { status: kind === 'rollback' ? 'rolled_back' : 'updated', record: after, changed_paths: [managed, ...after.targets.map(t => t.path)], decision, verification: source.verification };
+    } catch (error) {
+      return { status: 'recovery_required', record: await readInstallRecord(recordRoot), changed_paths: [], decision: { ...decision, error: error.message, recovery: 'rerun update or call recoverTransaction(recordRoot)', journal: path.join(recordRoot, 'transaction.json') }, verification: null };
+    }
+  }, { recover: true });
+}
+
+/** Apply this running, locally verified release; obtaining npm packages is the caller's job. */
+export async function update({ bundleRoot, recordRoot, localChanges = 'abort', faultHook }) {
+  return applyRelease({ bundleRoot, recordRoot, localChanges, faultHook, kind: 'update' });
+}
+
+export async function rollback({ recordRoot, releaseVersion, faultHook }) {
+  recordRoot = path.resolve(recordRoot);
+  const record = await readInstallRecord(recordRoot);
+  if (!record) throw new Error('install record missing');
+  const scopeRoot = await validateScope(recordRoot, record);
+  if (await readJournal(recordRoot)) return applyRelease({ recordRoot, localChanges: 'abort', faultHook, kind: 'rollback' });
+  const snapshot = [...record.previous_releases].reverse().find(r => r.release_version === releaseVersion);
+  if (!snapshot) throw new Error('verified previous release not found');
+  const relative = path.relative(path.join(recordRoot, 'releases'), snapshot.bundle_root);
+  if (!/^[a-f0-9-]{36}[\\/]bundle$/.test(relative)) throw new Error('rollback snapshot outside managed releases');
+  await assertManagedPath(scopeRoot, snapshot.bundle_root);
+  return applyRelease({ bundleRoot: snapshot.bundle_root, recordRoot, localChanges: 'abort', faultHook, kind: 'rollback', expectedSnapshot: snapshot });
+}