ruvnet-brain 4.0.6 → 4.0.7

package/scripts/release-transaction-provider.mjs

@@ -0,0 +1,236 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { RECEIPT_PREFIX, TERMINAL_STATES } from './release-transaction.mjs';
+
+const REPO = 'stuinfla/ruvnet-brain';
+const PACKAGE = 'ruvnet-brain';
+
+const command = (name, args, options = {}) => execFileSync(name, args, {
+  encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...options,
+}).trim();
+const json = (name, args, options) => JSON.parse(command(name, args, options));
+const maybe = (callback, fallback = null) => {
+  try { return callback(); } catch { return fallback; }
+};
+
+const tagSha = (tag, root) => {
+  const rows = command('git', ['ls-remote', 'origin', `refs/tags/${tag}`, `refs/tags/${tag}^{}`], { cwd: root })
+    .split('\n').filter(Boolean).map((line) => line.split(/\s+/));
+  return rows.find(([, ref]) => ref?.endsWith('^{}'))?.[0] || rows[0]?.[0] || '';
+};
+
+const assetBytes = (asset) => {
+  const result = spawnSync('gh', ['api', asset.url, '-H', 'Accept: application/octet-stream'], {
+    encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error || result.status !== 0) throw new Error(`cannot download transaction asset ${asset.name}`);
+  return Buffer.from(result.stdout);
+};
+const assetReceipt = (asset) => JSON.parse(assetBytes(asset).toString('utf8'));
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+
+export function liveReleaseProvider({
+  root = process.cwd(), candidateReceipt = null, publicationReceipt = null,
+} = {}) {
+  let releases = [];
+  let activeDraft = null;
+  const refresh = () => {
+    releases = json('gh', ['api', `repos/${REPO}/releases?per_page=100`]);
+    return releases;
+  };
+  const releaseById = (id) => json('gh', ['api', `repos/${REPO}/releases/${id}`]);
+  const receiptsFor = (release) => (release?.assets || [])
+    .filter(({ name }) => name.startsWith(RECEIPT_PREFIX) && name.endsWith('.json'))
+    .map(assetReceipt);
+  const materializeRemoteAssets = (draft, identity) => {
+    const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-release-staged-'));
+    try {
+      const release = releaseById(draft.id);
+      const required = [
+        ['bundlePath', 'ruvnet-brain.zip'],
+        ['bundleSignaturePath', 'ruvnet-brain.zip.sig'],
+        ['bundleDigestPath', 'ruvnet-brain.zip.sha256'],
+      ];
+      const assets = {};
+      for (const [key, name] of required) {
+        const remote = release.assets?.find((asset) => asset.name === name);
+        if (!remote) throw new Error(`staged GitHub asset missing: ${name}`);
+        const file = path.join(temp, name);
+        fs.writeFileSync(file, assetBytes(remote), { flag: 'wx', mode: 0o600 });
+        assets[key] = file;
+      }
+      if (sha256(fs.readFileSync(assets.bundlePath)) !== identity.bundleSha256) {
+        throw new Error('staged GitHub bundle digest does not match transaction identity');
+      }
+      const packed = json('npm', [
+        'pack', `${PACKAGE}@candidate-v${identity.version}`, '--json', '--pack-destination', temp,
+      ]);
+      if (!Array.isArray(packed) || packed.length !== 1 || !packed[0].filename) {
+        throw new Error('npm candidate pack did not return exactly one artifact');
+      }
+      assets.packagePath = path.join(temp, packed[0].filename);
+      const integrity = `sha512-${crypto.createHash('sha512').update(fs.readFileSync(assets.packagePath)).digest('base64')}`;
+      if (integrity !== identity.packageIntegrity) throw new Error('staged npm package integrity mismatch');
+      return { assets, cleanup: () => fs.rmSync(temp, { recursive: true, force: true }) };
+    } catch (error) {
+      fs.rmSync(temp, { recursive: true, force: true });
+      throw error;
+    }
+  };
+
+  return {
+    async discover(identity) {
+      const all = refresh();
+      const matchingDrafts = all.filter((release) => release.tag_name === identity.tag
+        && release.target_commitish === identity.candidateSha).map((release) => ({
+        id: release.id, tag: release.tag_name, sha: release.target_commitish, draft: release.draft,
+      }));
+      activeDraft = matchingDrafts[0] || null;
+      const receipts = matchingDrafts.length === 1 ? receiptsFor(releaseById(matchingDrafts[0].id)) : [];
+      const latestByTransaction = new Map();
+      for (const receipt of all.flatMap((release) => receiptsFor(release))) {
+        const prior = latestByTransaction.get(receipt.transactionId);
+        if (!prior || receipt.sequence > prior.sequence) latestByTransaction.set(receipt.transactionId, receipt);
+      }
+      const pending = [...latestByTransaction.values()]
+        .filter((receipt) => !TERMINAL_STATES.has(receipt.state));
+      const npmLatest = maybe(() => command('npm', ['view', `${PACKAGE}@latest`, 'version']), null);
+      const githubLatest = maybe(() => json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name, null);
+      return { matchingDrafts, receipts, pending, prior: { npmLatest, githubLatest } };
+    },
+
+    async createDraft(identity) {
+      const release = json('gh', [
+        'api', '-X', 'POST', `repos/${REPO}/releases`,
+        '-f', `tag_name=${identity.tag}`, '-f', `target_commitish=${identity.candidateSha}`,
+        '-f', `name=${identity.tag} staged candidate`, '-F', 'draft=true', '-F', 'prerelease=false',
+      ]);
+      activeDraft = { id: release.id, tag: release.tag_name, sha: release.target_commitish };
+      return activeDraft;
+    },
+
+    async appendReceipt(draft, receipt, name) {
+      const anchor = draft || activeDraft;
+      if (!anchor) throw new Error('no draft anchor for transaction receipt');
+      const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-release-receipt-'));
+      const file = path.join(temp, name);
+      try {
+        fs.writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+        command('gh', ['release', 'upload', anchor.tag, file, '--repo', REPO]);
+      } finally {
+        fs.rmSync(temp, { recursive: true, force: true });
+      }
+    },
+
+    async readReceipt(draft, sequence) {
+      const name = `${RECEIPT_PREFIX}${String(sequence).padStart(4, '0')}.json`;
+      const release = releaseById((draft || activeDraft).id);
+      const asset = release.assets?.find((item) => item.name === name);
+      if (!asset) throw new Error(`remote receipt ${name} is missing after upload`);
+      return assetReceipt(asset);
+    },
+
+    async uploadAssets(draft, assets) {
+      const paths = [assets.bundlePath, assets.bundleSignaturePath, assets.bundleDigestPath, assets.packagePath];
+      for (const file of paths) {
+        const release = releaseById(draft.id);
+        const existing = release.assets?.find(({ name }) => name === path.basename(file));
+        if (existing) {
+          if (sha256(assetBytes(existing)) !== sha256(fs.readFileSync(file))) {
+            throw new Error(`refusing to replace staged asset with different bytes: ${existing.name}`);
+          }
+          continue;
+        }
+        command('gh', ['release', 'upload', draft.tag, file, '--repo', REPO]);
+      }
+    },
+
+    async materializeStagedAssets(draft, identity) {
+      return materializeRemoteAssets(draft, identity);
+    },
+
+    async stageNpm(identity, packagePath) {
+      const existing = maybe(() => command('npm', ['view', `${PACKAGE}@${identity.version}`, 'dist.integrity']), null);
+      if (existing) return;
+      command('npm', ['publish', packagePath, '--tag', `candidate-v${identity.version}`]);
+    },
+
+    async observeNpmCandidate(identity) {
+      const metadata = json('npm', ['view', `${PACKAGE}@candidate-v${identity.version}`, '--json']);
+      return { version: metadata.version, integrity: metadata.dist?.integrity, tag: `candidate-v${identity.version}` };
+    },
+
+    async publishDraftNonLatest(draft) {
+      command('gh', ['api', '-X', 'PATCH', `repos/${REPO}/releases/${draft.id}`, '-F', 'draft=false', '-f', 'make_latest=false']);
+    },
+
+    async observeGithub(identity) {
+      const release = json('gh', ['api', `repos/${REPO}/releases/tags/${identity.tag}`]);
+      const latest = maybe(() => json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name, null);
+      return { tag: release.tag_name, sha: tagSha(identity.tag, root), latest: latest === identity.tag };
+    },
+
+    async promoteNpm(identity) {
+      command('npm', ['dist-tag', 'add', `${PACKAGE}@${identity.version}`, 'latest']);
+    },
+    async observeNpmLatest() {
+      return { version: command('npm', ['view', `${PACKAGE}@latest`, 'version']) };
+    },
+    async makeGithubLatest(draft) {
+      command('gh', ['api', '-X', 'PATCH', `repos/${REPO}/releases/${draft.id}`, '-f', 'make_latest=true']);
+    },
+    async observeGithubLatest() {
+      return { tag: json('gh', ['api', `repos/${REPO}/releases/latest`]).tag_name };
+    },
+    async restoreNpmLatest(prior, expected) {
+      const current = command('npm', ['view', `${PACKAGE}@latest`, 'version']);
+      if (current !== expected) throw new Error(`refusing compensation: npm latest is ${current}, expected ${expected}`);
+      command('npm', ['dist-tag', 'add', `${PACKAGE}@${prior}`, 'latest']);
+    },
+    async finalize(identity, receipt, hostVerifier) {
+      const staged = materializeRemoteAssets(activeDraft, identity);
+      let hosts;
+      try {
+        hosts = await hostVerifier.verify({ source: 'final', identity, assets: staged.assets });
+      } finally {
+        staged.cleanup();
+      }
+      if (hosts.verdict !== 'PASS') return { verdict: 'FAIL', hosts };
+      if (!candidateReceipt || !publicationReceipt) {
+        throw new Error('final convergence requires candidate and publication receipt paths');
+      }
+      if (!fs.existsSync(path.resolve(root, publicationReceipt))) {
+        const publication = spawnSync(process.execPath, [
+          'scripts/publication-receipt.mjs', '--candidate', candidateReceipt, '--out', publicationReceipt,
+        ], { cwd: root, encoding: 'utf8', timeout: 1_200_000 });
+        if (publication.error || publication.status !== 0) {
+          return { verdict: 'FAIL', hosts, publicationError: String(publication.stderr || publication.error?.message) };
+        }
+      }
+      const seal = spawnSync(process.execPath, [
+        'scripts/release-proof.mjs', '--candidate', candidateReceipt, '--publication', publicationReceipt,
+      ], { cwd: root, encoding: 'utf8', timeout: 300_000 });
+      if (seal.error || seal.status !== 0) {
+        return { verdict: 'FAIL', hosts, sealError: String(seal.stderr || seal.error?.message) };
+      }
+      const channels = spawnSync(process.execPath, ['scripts/verify-channels.mjs'], {
+        cwd: root, encoding: 'utf8', timeout: 600_000,
+      });
+      if (channels.error || channels.status !== 0) {
+        return { verdict: 'FAIL', hosts, channelError: String(channels.stderr || channels.error?.message) };
+      }
+      const probe = spawnSync(process.execPath, ['scripts/published-surface-probe.mjs', '--json'], {
+        cwd: root, encoding: 'utf8', timeout: 600_000,
+      });
+      let observed = null;
+      try { observed = JSON.parse(probe.stdout || ''); } catch {}
+      return {
+        verdict: probe.status === 0 && observed?.verdict === 'PASS' ? 'PASS' : 'FAIL',
+        hosts, surface: observed, publicationReceipt, previousReceiptDigest: receipt.receiptDigest,
+      };
+    },
+  };
+}

package/scripts/release-transaction.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto';
+
+export const RECEIPT_PREFIX = 'release-transaction-';
+export const TERMINAL_STATES = new Set(['channels-converged', 'aborted']);
+
+const canonical = (value) => {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+};
+
+export const receiptPayload = (receipt) => {
+  const { signature: _signature, receiptDigest: _digest, ...payload } = receipt;
+  return canonical(payload);
+};
+
+export const digestReceipt = (receipt) => crypto.createHash('sha256')
+  .update(receiptPayload(receipt)).digest('hex');
+
+export const transactionIdFor = (identity) => crypto.createHash('sha256').update(canonical({
+  repository: identity.repository,
+  package: identity.package,
+  version: identity.version,
+  tag: identity.tag,
+  candidateSha: identity.candidateSha,
+  packageIntegrity: identity.packageIntegrity,
+  bundleSha256: identity.bundleSha256,
+})).digest('hex');
+
+export function signReceipt(receipt, privateKey) {
+  const unsigned = { ...receipt, receiptDigest: digestReceipt(receipt) };
+  return {
+    ...unsigned,
+    signature: crypto.sign(null, Buffer.from(canonical(unsigned)), privateKey).toString('base64'),
+  };
+}
+
+export function verifyReceipt(receipt, publicKey) {
+  if (!receipt || receipt.schemaVersion !== 1 || !/^[a-f0-9]{64}$/.test(receipt.transactionId || '')) {
+    throw new Error('invalid release transaction receipt');
+  }
+  const { signature, receiptDigest, ...unsigned } = receipt;
+  if (digestReceipt(unsigned) !== receiptDigest) throw new Error('release receipt digest mismatch');
+  if (!crypto.verify(null, Buffer.from(canonical({ ...unsigned, receiptDigest })), publicKey, Buffer.from(signature || '', 'base64'))) {
+    throw new Error('release receipt signature mismatch');
+  }
+  return receipt;
+}
+
+export function validateReceiptChain(receipts, identity, publicKey) {
+  const expectedId = transactionIdFor(identity);
+  const sorted = [...receipts].sort((a, b) => a.sequence - b.sequence);
+  let previous = null;
+  for (let index = 0; index < sorted.length; index += 1) {
+    const receipt = verifyReceipt(sorted[index], publicKey);
+    if (receipt.transactionId !== expectedId || canonical(receipt.identity) !== canonical(identity)) {
+      throw new Error('release receipt identity conflict');
+    }
+    if (receipt.sequence !== index) throw new Error('release receipt sequence gap or replay');
+    if ((receipt.previousReceiptDigest || null) !== (previous?.receiptDigest || null)) {
+      throw new Error('release receipt chain conflict');
+    }
+    previous = receipt;
+  }
+  return sorted;
+}
+
+const stateReceipt = ({ identity, prior, state, fence, observation = {}, privateKey }) => signReceipt({
+  schemaVersion: 1,
+  transactionId: transactionIdFor(identity),
+  sequence: prior ? prior.sequence + 1 : 0,
+  previousReceiptDigest: prior?.receiptDigest || null,
+  state,
+  fence,
+  identity,
+  observation,
+  createdAt: new Date().toISOString(),
+}, privateKey);
+
+const exact = (actual, expected, label) => {
+  if (actual !== expected) throw new Error(`${label} mismatch: ${actual ?? '(missing)'} != ${expected}`);
+};
+
+export async function runReleaseTransaction({ identity, assets, adapter, privateKey, publicKey, hostVerifier }) {
+  const expectedId = transactionIdFor(identity);
+  const discovered = await adapter.discover(identity);
+  const competing = discovered.pending?.filter((item) => item.transactionId !== expectedId) || [];
+  if (competing.length) throw new Error(`pending release ${competing[0].transactionId} blocks ${expectedId}`);
+  if ((discovered.matchingDrafts || []).length > 1) throw new Error('duplicate matching drafts require reconciliation');
+
+  let chain = validateReceiptChain(discovered.receipts || [], identity, publicKey);
+  let current = chain.at(-1) || null;
+  const fence = current?.fence || discovered.fence || crypto.randomUUID();
+  const draft = discovered.matchingDrafts?.[0] || await adapter.createDraft(identity, fence);
+  const completed = new Set(chain.map(({ state }) => state));
+  const append = async (state, observation = {}) => {
+    const receipt = stateReceipt({ identity, prior: current, state, fence, observation, privateKey });
+    await adapter.appendReceipt(draft, receipt, `${RECEIPT_PREFIX}${String(receipt.sequence).padStart(4, '0')}.json`);
+    const observed = await adapter.readReceipt(draft, receipt.sequence);
+    verifyReceipt(observed, publicKey);
+    exact(observed.receiptDigest, receipt.receiptDigest, 'remote receipt');
+    current = receipt;
+    completed.add(state);
+    return receipt;
+  };
+  const intend = async (state, observation = {}) => {
+    if (!completed.has(state)) await append(state, observation);
+  };
+
+  if (!current) await append('remote-prepared', { draftId: draft.id, prior: discovered.prior });
+  if (TERMINAL_STATES.has(current.state)) return current;
+  if (current.fence !== fence) throw new Error('stale release transaction fence');
+
+  if (!completed.has('local-hosts-verified')) {
+    await intend('asset-upload-intent');
+    await adapter.uploadAssets(draft, assets, identity);
+    await intend('host-verification-intent', { source: 'sealed-local-assets' });
+    const localHosts = await hostVerifier.verify({ source: 'local', identity, assets });
+    if (localHosts.verdict !== 'PASS') throw new Error('local staged host verification failed');
+    await append('local-hosts-verified', { hosts: localHosts });
+  }
+
+  if (!completed.has('npm-candidate-staged')) {
+    await intend('npm-stage-intent');
+    await adapter.stageNpm(identity, assets.packagePath);
+    const stagedNpm = await adapter.observeNpmCandidate(identity);
+    exact(stagedNpm.version, identity.version, 'npm candidate version');
+    exact(stagedNpm.integrity, identity.packageIntegrity, 'npm candidate integrity');
+    await append('npm-candidate-staged', { npm: stagedNpm });
+  }
+
+  if (!completed.has('prepared')) {
+    await intend('remote-host-verification-intent');
+    const staged = await adapter.materializeStagedAssets(draft, identity);
+    try {
+      const remoteHosts = await hostVerifier.verify({ source: 'staged', identity, assets: staged.assets, draft });
+      if (remoteHosts.verdict !== 'PASS') throw new Error('remote staged host verification failed');
+      await append('prepared', { hosts: remoteHosts });
+    } finally {
+      staged.cleanup();
+    }
+  }
+
+  if (!completed.has('github-promoted-nonlatest')) {
+    await intend('github-promote-intent');
+    await adapter.publishDraftNonLatest(draft, identity);
+    const github = await adapter.observeGithub(identity);
+    exact(github.sha, identity.candidateSha, 'GitHub candidate SHA');
+    if (github.latest) throw new Error('GitHub candidate advanced latest before npm convergence');
+    await append('github-promoted-nonlatest', { github });
+  }
+
+  if (!completed.has('npm-promoted')) {
+    await intend('npm-promote-intent');
+    try {
+      await adapter.promoteNpm(identity);
+    } catch (error) {
+      throw new Error(`npm promotion pending for ${identity.version}: ${error.message}`);
+    }
+    const npmLatest = await adapter.observeNpmLatest();
+    exact(npmLatest.version, identity.version, 'npm latest');
+    await append('npm-promoted', { npm: npmLatest });
+  }
+
+  // A failed GitHub-latest promotion is compensated back to A. The historical npm-promoted
+  // receipt remains true, but is no longer the current external state, so a clean-runner retry
+  // must explicitly re-promote B before it may retry GitHub.
+  if (current.state === 'compensated') {
+    await append('npm-repromote-intent');
+    await adapter.promoteNpm(identity);
+    const npmLatest = await adapter.observeNpmLatest();
+    exact(npmLatest.version, identity.version, 'npm latest after compensation retry');
+    await append('npm-repromoted', { npm: npmLatest });
+  }
+
+  if (!completed.has('defaults-promoted')) {
+    await intend('github-latest-intent');
+    try {
+      await adapter.makeGithubLatest(draft, identity);
+    } catch (error) {
+      const observed = await adapter.observeNpmLatest();
+      if (observed.version !== identity.version) throw new Error('npm latest changed during compensation');
+      await intend('compensation-intent', { restore: discovered.prior?.npmLatest });
+      await adapter.restoreNpmLatest(discovered.prior?.npmLatest, identity.version);
+      exact((await adapter.observeNpmLatest()).version, discovered.prior?.npmLatest, 'npm compensation');
+      await append('compensated', { reason: error.message });
+      throw new Error(`GitHub latest promotion failed; npm compensated: ${error.message}`);
+    }
+    const githubLatest = await adapter.observeGithubLatest();
+    exact(githubLatest.tag, identity.tag, 'GitHub latest');
+    await append('defaults-promoted', { github: githubLatest });
+  }
+
+  await intend('finalize-intent');
+  const final = await adapter.finalize(identity, current, hostVerifier);
+  if (final.verdict !== 'PASS') throw new Error('final release convergence failed');
+  return append('channels-converged', final);
+}
+
+export async function abortReleaseTransaction({ identity, receipts, reason, authorized, adapter, privateKey, publicKey }) {
+  if (!authorized) throw new Error('release abort requires explicit human authorization');
+  const chain = validateReceiptChain(receipts, identity, publicKey);
+  const current = chain.at(-1);
+  if (!current || TERMINAL_STATES.has(current.state)) throw new Error('release transaction is not abortable');
+  const receipt = stateReceipt({
+    identity, prior: current, state: 'aborted', fence: current.fence,
+    observation: { reason, authorized: true }, privateKey,
+  });
+  await adapter.appendReceipt(null, receipt, `${RECEIPT_PREFIX}${String(receipt.sequence).padStart(4, '0')}.json`);
+  return receipt;
+}