ruvnet-brain 4.3.26 → 4.3.27

package/scripts/gist-receipts.mjs

@@ -33,6 +33,7 @@ import { fileURLToPath } from 'node:url';
 import { canonicalJson, digest, validateGistAggregateReceipt } from './coverage-integrity.mjs';
 import { promoteArtifactSet } from '../kb/incremental-refresh.mjs';
 import { writeRvfGeneration } from './rvf-generation.mjs';
+import { fetchGistGitSnapshot } from './gist-git-transport.mjs';
 
 const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const TEXT_EXT = new Set(['.md', '.markdown', '.txt', '.rst']);
@@ -45,6 +46,7 @@ const HEX_GIST = /^[a-f0-9]{20,64}$/;
 const OWNER_RE = /^[A-Za-z0-9-]{1,39}$/;
 const compareCanonicalText = (left, right) => String(left) < String(right) ? -1
   : String(left) > String(right) ? 1 : 0;
+const VERIFIED_CAPTURE_SETS = new WeakMap();
 
 function validDate(value) {
   return typeof value === 'string' && Number.isFinite(Date.parse(value));
@@ -122,38 +124,67 @@ const RATE_LIMIT_RE = /rate limit/i;
 const NOT_FOUND_RE = /\bnot found\b|HTTP 404/i;
 const FORBIDDEN_INTEGRATION_RE = /resource not accessible by integration/i;
 const TRANSIENT_RE = /timeout|timed out|TLS handshake|ECONNRESET|ECONNREFUSED|EAI_AGAIN|temporary failure|HTTP 5\d\d|HTTP 429|socket hang up/i;
+const MAX_RATE_LIMIT_WAIT_MS = 15 * 60 * 1000;
+
+function retryDelay(error, attempt, retryDelayMs) {
+  if (error?.code !== 'GIST_RATE_LIMITED') return retryDelayMs * attempt;
+  const retryAfter = Number(error.headers?.['retry-after']);
+  const resetAt = Number(error.headers?.['x-ratelimit-reset']);
+  const requested = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000
+    : Number.isFinite(resetAt) && resetAt > 0 ? Math.max(0, resetAt * 1000 - Date.now()) : retryDelayMs * attempt;
+  return requested > MAX_RATE_LIMIT_WAIT_MS ? null : Math.max(retryDelayMs * attempt, requested);
+}
 
 export class GistFetchError extends Error {
-  constructor(message, { code, gistId, status, retryable = false } = {}) {
+  constructor(message, { code, gistId, status, headers = {}, retryable = false } = {}) {
     super(message);
     this.name = 'GistFetchError';
     this.code = code;
     this.gistId = gistId;
     if (status !== undefined) this.status = status;
+    if (headers && Object.keys(headers).length) this.headers = headers;
     this.retryable = retryable;
   }
 }
 
-function classifyGistFetchFailure(stderr, gistId) {
+function classifyGistFetchFailure(stderr, gistId, { status, headers = {} } = {}) {
   const message = String(stderr || '').trim();
-  if (NOT_FOUND_RE.test(message)) {
-    return new GistFetchError(`gist ${gistId} was moved or deleted: ${message}`,
-      { code: 'GIST_NOT_FOUND', gistId, retryable: false });
+  const responseStatus = status ?? (Number(message.match(/\bHTTP\s+(\d{3})\b/i)?.[1]) || undefined);
+  const safeHeaders = Object.fromEntries(['x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after', 'x-ratelimit-resource', 'x-github-request-id']
+    .flatMap((key) => headers[key] == null ? [] : [[key, String(headers[key])]]));
+  const responseDetail = [responseStatus ? `HTTP ${responseStatus}` : '', Object.keys(safeHeaders).length
+    ? `headers=${JSON.stringify(safeHeaders)}` : '', message].filter(Boolean).join('; ');
+  if (responseStatus === 404 || (!responseStatus && NOT_FOUND_RE.test(message))) {
+    return new GistFetchError(`gist ${gistId} was moved or deleted: ${responseDetail}`,
+      { code: 'GIST_NOT_FOUND', gistId, status: responseStatus, headers: safeHeaders, retryable: false });
   }
-  if (FORBIDDEN_INTEGRATION_RE.test(message)) {
-    return new GistFetchError(`gist ${gistId} fetch rejected -- token lacks gist scope: ${message}`,
-      { code: 'GIST_FORBIDDEN', gistId, retryable: false });
+  if (RATE_LIMIT_RE.test(message) || (responseStatus === 403 && headers['x-ratelimit-remaining'] === '0')
+    || (responseStatus === 429 && Boolean(headers['retry-after']))) {
+    return new GistFetchError(`gist ${gistId} fetch rate-limited: ${responseDetail}`,
+      { code: 'GIST_RATE_LIMITED', gistId, status: responseStatus, headers: safeHeaders, retryable: true });
   }
-  if (RATE_LIMIT_RE.test(message)) {
-    return new GistFetchError(`gist ${gistId} fetch rate-limited: ${message}`,
-      { code: 'GIST_RATE_LIMITED', gistId, retryable: true });
+  if (responseStatus === 403 && (FORBIDDEN_INTEGRATION_RE.test(message) || !headers['x-ratelimit-remaining'])) {
+    return new GistFetchError(`gist ${gistId} fetch rejected (HTTP 403): ${responseDetail}`,
+      { code: 'GIST_FORBIDDEN', gistId, status: responseStatus, headers: safeHeaders, retryable: false });
   }
-  if (TRANSIENT_RE.test(message)) {
-    return new GistFetchError(`gist ${gistId} fetch failed transiently: ${message}`,
-      { code: 'GIST_TRANSIENT_FAILURE', gistId, retryable: true });
+  if (TRANSIENT_RE.test(message) || (responseStatus >= 500 && responseStatus < 600) || responseStatus === 429) {
+    return new GistFetchError(`gist ${gistId} fetch failed transiently: ${responseDetail}`,
+      { code: 'GIST_TRANSIENT_FAILURE', gistId, status: responseStatus, headers: safeHeaders, retryable: true });
   }
-  return new GistFetchError(`gist ${gistId} fetch failed: ${message}`,
-    { code: 'GIST_FETCH_FAILED', gistId, retryable: false });
+  return new GistFetchError(`gist ${gistId} fetch failed: ${responseDetail}`,
+    { code: 'GIST_FETCH_FAILED', gistId, status: responseStatus, headers: safeHeaders, retryable: false });
+}
+
+function parseGhResponse(output) {
+  const text = String(output || '');
+  const match = text.match(/^HTTP\/\S+\s+(\d+)\r?\n([\s\S]*?)\r?\n\r?\n([\s\S]*)$/m);
+  if (!match) return { status: undefined, headers: {}, body: text };
+  const headers = {};
+  for (const line of match[2].split(/\r?\n/)) {
+    const split = line.indexOf(':');
+    if (split > 0) headers[line.slice(0, split).trim().toLowerCase()] = line.slice(split + 1).trim();
+  }
+  return { status: Number(match[1]), headers, body: match[3] };
 }
 
 function defaultSleep(ms) {
@@ -172,11 +203,14 @@ export async function defaultFetchGist(id, { spawn = spawnSync, retries = 3, ret
   const attempts = Math.max(1, retries);
   let lastError;
   for (let attempt = 1; attempt <= attempts; attempt++) {
-    const result = spawn('gh', ['api', `gists/${id}`], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
-    if (result.status === 0) return JSON.parse(result.stdout);
-    lastError = classifyGistFetchFailure(result.stderr, id);
+    const result = spawn('gh', ['api', '--include', `gists/${id}`], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    const response = parseGhResponse(result.stdout);
+    if (result.status === 0) return JSON.parse(response.body);
+    lastError = classifyGistFetchFailure(`${result.stderr || ''}\n${response.body || ''}`, id, response);
     if (!lastError.retryable || attempt === attempts) throw lastError;
-    await sleep(retryDelayMs * attempt);
+    const delay = retryDelay(lastError, attempt, retryDelayMs);
+    if (delay === null) throw lastError;
+    await sleep(delay);
     if (signal?.aborted) throw abortError(signal);
   }
   throw lastError;
@@ -185,17 +219,34 @@ export async function defaultFetchGist(id, { spawn = spawnSync, retries = 3, ret
 // The unauthenticated fallback used ONLY for the specific 403 "no gist scope" rejection. Mirrors
 // source-coverage.mjs's listGistsUnauthenticated: same env var, same accept header, same
 // unauthenticated-quota reasoning. `fetchImpl` is a test seam (default: global fetch).
-async function fetchPublicGistDetail(id, { fetchImpl = globalThis.fetch, signal } = {}) {
+async function fetchPublicGistDetail(id, { fetchImpl = globalThis.fetch, retries = 3, retryDelayMs = 300,
+  sleep = defaultSleep, signal } = {}) {
   const apiBase = process.env.RUVNET_GISTS_API || 'https://api.github.com';
-  const response = await fetchImpl(`${apiBase}/gists/${id}`, {
-    headers: { accept: 'application/vnd.github+json', 'user-agent': 'ruvnet-brain-gist-receipts' },
-    signal,
-  });
-  if (!response.ok) {
-    throw new GistFetchError(`gist ${id} public detail fetch failed: HTTP ${response.status}`,
-      { code: 'GIST_FETCH_FAILED', gistId: id, status: response.status, retryable: false });
+  const attempts = Math.max(1, retries);
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const response = await fetchImpl(`${apiBase}/gists/${id}`, {
+      headers: { accept: 'application/vnd.github+json', 'user-agent': 'ruvnet-brain-gist-receipts' },
+      signal,
+    });
+    if (response.ok) return response.json();
+    const headers = {};
+    for (const key of ['x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after', 'x-ratelimit-resource', 'x-github-request-id']) {
+      const value = response.headers?.get?.(key);
+      if (value != null) headers[key] = value;
+    }
+    const body = await response.json?.().catch?.(() => null);
+    const classified = classifyGistFetchFailure(`public detail fetch failed: HTTP ${response.status} ${body?.message || ''}`, id,
+      { status: response.status, headers });
+    const error = new GistFetchError(`gist ${id} public detail fetch failed: ${classified.message}`,
+      { code: classified.code, gistId: id, status: response.status, headers: classified.headers,
+        retryable: classified.retryable });
+    if (!error.retryable || attempt === attempts) throw error;
+    const delay = retryDelay(error, attempt, retryDelayMs);
+    if (delay === null) throw error;
+    await sleep(delay);
+    if (signal?.aborted) throw abortError(signal);
   }
-  return response.json();
+  throw new Error(`gist ${id} public detail retries exhausted`);
 }
 
 // The transport `captureGistSources` uses by default for per-gist DETAIL. Wraps `defaultFetchGist`
@@ -229,9 +280,18 @@ export async function defaultFetchRaw(file, { fetchImpl = globalThis.fetch, retr
         headers: { 'user-agent': 'ruvnet-brain-gist-receipts' }, signal,
       });
       if (response.ok) return Buffer.from(await response.arrayBuffer());
-      const transient = response.status === 429 || (response.status >= 500 && response.status < 600);
-      lastError = new GistFetchError(`raw gist fetch failed: HTTP ${response.status}`,
-        { code: transient ? 'GIST_RAW_TRANSIENT_FAILURE' : 'GIST_RAW_FETCH_FAILED', status: response.status, retryable: transient });
+      const headers = {};
+      for (const key of ['x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after', 'x-ratelimit-resource', 'x-github-request-id']) {
+        const value = response.headers?.get?.(key);
+        if (value != null) headers[key] = value;
+      }
+      const rateLimited = response.status === 403 && (headers['x-ratelimit-remaining'] === '0'
+        || RATE_LIMIT_RE.test(response.statusText || '')) || response.status === 429;
+      const transient = rateLimited || (response.status >= 500 && response.status < 600);
+      lastError = new GistFetchError(`raw gist fetch failed: HTTP ${response.status}; headers=${JSON.stringify(
+        Object.fromEntries(Object.entries(headers).filter(([key]) => ['x-ratelimit-remaining', 'x-ratelimit-reset', 'retry-after', 'x-ratelimit-resource', 'x-github-request-id'].includes(key))))}`,
+      { code: rateLimited ? 'GIST_RATE_LIMITED' : transient ? 'GIST_RAW_TRANSIENT_FAILURE' : 'GIST_RAW_FETCH_FAILED',
+        status: response.status, headers, retryable: transient });
       if (!transient) throw lastError;
     } catch (error) {
       if (error instanceof GistFetchError) { lastError = error; if (!error.retryable) throw error; }
@@ -243,7 +303,9 @@ export async function defaultFetchRaw(file, { fetchImpl = globalThis.fetch, retr
       }
     }
     if (attempt === attempts) throw lastError;
-    await sleep(retryDelayMs * attempt);
+    const delay = retryDelay(lastError, attempt, retryDelayMs);
+    if (delay === null) throw lastError;
+    await sleep(delay);
     if (signal?.aborted) throw abortError(signal);
   }
   throw lastError;
@@ -340,18 +402,49 @@ function reusableCachedGist(cached, stub) {
   return 'reuse';
 }
 
-export async function captureGistSources({ observation, cache = null, fetchDetail = defaultFetchDetail,
-  fetchRaw = defaultFetchRaw, signal, now = () => new Date().toISOString() } = {}) {
+export async function captureGistSources({ observation, cache = null, fetchDetail = null,
+  fetchRaw = defaultFetchRaw, fetchGitSnapshot = fetchGistGitSnapshot, signal,
+  now = () => new Date().toISOString() } = {}) {
   const stubs = observation?.gists?.rows;
   if (!Array.isArray(stubs) || stubs.some(({ id }) => !HEX_GIST.test(String(id || '')))
     || new Set(stubs.map(({ id }) => id)).size !== stubs.length) {
     throw new Error('source observation has missing or duplicate gist ids');
   }
+  const observedRowsSha256 = digest({ owner: observation.owner, observedAt: observation.observedAt, rows: stubs });
   const gists = {};
   const reused = [];
   const fetched = [];
   for (const stub of [...stubs].sort((a, b) => String(a.id).localeCompare(String(b.id)))) {
     if (signal?.aborted) throw abortError(signal);
+    if (!fetchDetail) {
+      // The production/no-key route never spends one REST detail request per gist and never trusts
+      // a body-free cache or timestamps as content identity. A full bare clone gives one immutable
+      // Git commit/tree; every observed raw_url's blob identity must match its HEAD file bytes.
+      const snapshot = await fetchGitSnapshot({ owner: observation.owner, stub, signal });
+      const files = [];
+      for (const source of snapshot.files) {
+        const filename = source.filename;
+        if (!TEXT_EXT.has(path.extname(filename).toLowerCase())) {
+          files.push({ filename, included: false, reason: 'non-text policy exclusion', size: source.size,
+            sourceGit: { ...source.sourceGit, captureMethod: 'public-bare-git-v1', revisionKind: 'git-commit',
+              observedAt: observation.observedAt, observedRowsSha256,
+              sourceObservationSha256: observation.observationSha256 } });
+          continue;
+        }
+        let text;
+        try { text = new TextDecoder('utf-8', { fatal: true }).decode(source.body); }
+        catch { throw new Error(`gist ${stub.id}/${filename} is not valid UTF-8 text`); }
+        files.push({ filename, included: true, sha256: sha256(source.body), bytes: source.size,
+          body: text, sourceGit: { ...source.sourceGit, captureMethod: 'public-bare-git-v1', revisionKind: 'git-commit',
+            observedAt: observation.observedAt, observedRowsSha256,
+            sourceObservationSha256: observation.observationSha256 } });
+      }
+      if (files.length !== snapshot.treeFileCount) throw new Error(`gist ${stub.id} Git inventory changed during capture`);
+      gists[stub.id] = { gistId: stub.id, versionSha: snapshot.headSha, updatedAt: stub.updated_at,
+        ingestedAt: now(), complete: true, files };
+      fetched.push(stub.id);
+      continue;
+    }
     const cached = cache?.gists?.[stub.id];
     const verdict = cached ? reusableCachedGist(cached, stub) : 'miss';
     if (verdict === 'tampered') {
@@ -386,14 +479,31 @@ export async function captureGistSources({ observation, cache = null, fetchDetai
       complete: files.length === Object.keys(full.files || {}).length, files };
     fetched.push(stub.id);
   }
-  return {
+  const captured = {
     owner: observation.owner,
+    observedRowsSha256,
     observedAt: observation.observedAt,
     sourceObservationSha256: observation.observationSha256,
     generatedAt: now(),
     gists,
     reuseEvidence: { reused, fetched },
   };
+  VERIFIED_CAPTURE_SETS.set(captured, {
+    fingerprint: digest(captured),
+    owner: observation.owner,
+    observedRowsSha256,
+    sourceObservationSha256: observation.observationSha256,
+  });
+  return captured;
+}
+
+function isCurrentVerifiedCapture(captured, observation) {
+  const proof = captured && typeof captured === 'object' ? VERIFIED_CAPTURE_SETS.get(captured) : null;
+  return Boolean(proof && proof.owner === observation?.owner
+    && proof.observedRowsSha256 === digest({ owner: observation?.owner,
+      observedAt: observation?.observedAt, rows: observation?.gists?.rows })
+    && proof.sourceObservationSha256 === observation?.observationSha256
+    && proof.fingerprint === digest(captured));
 }
 
 // ── stage 2: render ──────────────────────────────────────────────────────────────────────────────
@@ -462,6 +572,25 @@ export function validateGistReceipt({ receipt, observation = null, passagesFile,
     if (!validDate(row?.updatedAt) || !validDate(row?.ingestedAt)) {
       throw new Error(`gist ${gistId} has an invalid updatedAt/ingestedAt timestamp`);
     }
+    const sourceProofs = (row?.files || []).map((file) => file?.sourceGit).filter(Boolean);
+    if (sourceProofs.length && sourceProofs.length !== row.files.length) {
+      throw new Error(`gist ${gistId} mixes Git-bound and unbound file evidence`);
+    }
+    if (sourceProofs.length && sourceProofs.some((proof) => !HEX40.test(String(proof.headSha || ''))
+      || !HEX40.test(String(proof.treeSha || '')) || !HEX40.test(String(proof.blobSha || ''))
+      || proof.captureMethod !== 'public-bare-git-v1' || proof.revisionKind !== 'git-commit'
+      || !validDate(proof.observedAt) || proof.sourceObservationSha256 !== receipt.sourceObservationSha256
+      || !HEX64.test(String(proof.observedRowsSha256 || ''))
+      || !Number.isSafeInteger(proof.treeFileCount) || proof.treeFileCount !== row.files.length
+      || proof.observedTruncated !== false || proof.observedFileCount !== proof.treeFileCount
+      || proof.headSha !== row.versionSha || proof.observed !== true
+      || !HEX40.test(String(proof.observedRawRevisionSha || ''))
+      || !['blob', 'commit'].includes(proof.observedRawRevisionKind)
+      || proof.observedRawBlobSha !== proof.blobSha
+      || sourceProofs.some((other) => other.treeSha !== proof.treeSha || other.headSha !== proof.headSha
+        || other.observedRowsSha256 !== proof.observedRowsSha256))) {
+      throw new Error(`gist ${gistId} has an incomplete Git snapshot proof`);
+    }
     for (const file of row?.files || []) {
       if (!validateFilename(file?.filename)) throw new Error(`gist ${gistId} has an unsafe or missing filename`);
     }
@@ -517,8 +646,9 @@ export async function buildGistAggregate({ observation, cache = null, outDir, ro
       sourceMetadata: null, files: [], sourceReceipt: null, reuseEvidence: { reused: [], fetched: [] } };
   }
 
-  const captured = await captureGistSources({
-    observation, cache, fetchDetail: transport.fetchDetail, fetchRaw: transport.fetchRaw, signal, now,
+  const captured = isCurrentVerifiedCapture(cache, observation) ? cache : await captureGistSources({
+    observation, cache, fetchDetail: transport.fetchDetail, fetchRaw: transport.fetchRaw,
+    fetchGitSnapshot: transport.fetchGitSnapshot, signal, now,
   });
   const { passageBytes, metadata, gistRecords } = renderGistPassages({ captured, generatedAt: captured.generatedAt });
   const includedFileCount = Object.values(captured.gists)

package/scripts/ingest-gists.mjs

@@ -194,10 +194,13 @@ async function main() {
   }
 
   const observedAt = new Date().toISOString();
-  const rows = gists.map((g) => ({ id: g.id, updated_at: g.updated_at, files: g.files }));
+  const rows = gists.map((g) => ({ id: g.id, updated_at: g.updated_at, html_url: g.html_url,
+    truncated: g.truncated, files: g.files }));
   const observation = {
     owner: OWNER, observedAt,
-    observationSha256: digest({ owner: OWNER, rows: rows.map(({ id, updated_at }) => ({ id, updated_at })) }),
+    // Bind the exact listed file inventory and its truncation indicator. A timestamp-only digest
+    // could otherwise reuse a capture after the API changes a file's pinned raw blob or completeness.
+    observationSha256: digest({ owner: OWNER, rows }),
     gists: { rows },
   };
   const now = () => observedAt;

package/scripts/installed-brain-health.mjs

@@ -0,0 +1,99 @@
+// ADR-089: describe installed identities without confusing a validator pin with search-engine proof.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { readInstalledRuntime, isCorpusReleaseTag } from '../kb/corpus-release-identity.mjs';
+import { cmpVersion } from './stack-sync.mjs';
+import { isRuntimeFile } from './approved-runtime.mjs';
+
+const SEARCH_FILES = ['forge-mcp-all.mjs', 'forge-ask-all.mjs', 'forge-rerank.mjs', 'card-lane.mjs'];
+// Keep the doctor probe answerable and bounded. A health probe must exercise a real indexed
+// source/citation path; it must not turn an unclear broad question into an all-corpus rerank.
+export const DOCTOR_SMOKE_QUERY = 'What package name is declared in the RuvNet Brain KB package manifest?';
+export function doctorSmokeArgs(cacheDir) {
+  return ['forge-ask-all.mjs', '--dir', cacheDir, '--q', DOCTOR_SMOKE_QUERY,
+    '--repos', 'ruvnet-brain', '--k', '3', '--pool', '8', '--bounded'];
+}
+const version = value => typeof value === 'string' && /^v?\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(value)
+  ? value.replace(/^v/, '') : null;
+
+export function inspectInstalledBrain(kbDir, packageVersion) {
+  const result = { healthy: false, packageVersion, searchVersion: null, corpusTag: null,
+    validatorVersion: null, searchFiles: {}, issues: [] };
+  let source;
+  try { source = JSON.parse(fs.readFileSync(path.join(kbDir, 'SOURCE.json'), 'utf8')); }
+  catch { result.issues.push('SOURCE.json is missing or unreadable'); }
+  result.searchVersion = version(source?.brainVersion) || version(source?.releaseTag);
+  result.corpusTag = isCorpusReleaseTag(source?.corpusReleaseTag) ? source.corpusReleaseTag : null;
+  if (!result.searchVersion) result.issues.push('the search engine version is unverified');
+  if (version(source?.brainVersion) && version(source?.releaseTag)
+    && version(source.brainVersion) !== version(source.releaseTag)) {
+    result.issues.push('SOURCE.json runtime version and release tag disagree');
+  }
+  const pin = readInstalledRuntime(kbDir);
+  result.validatorVersion = pin.brainVersion;
+  if (!pin.ok) result.issues.push(pin.reason);
+  if (pin.ok && result.searchVersion && version(pin.brainVersion) !== result.searchVersion) {
+    result.issues.push(`validator runtime ${pin.brainVersion} and search engine ${result.searchVersion} differ`);
+  }
+  const expected = version(packageVersion);
+  if (expected && result.searchVersion && cmpVersion(result.searchVersion, expected) < 0) {
+    result.issues.push(`search engine ${result.searchVersion} is behind package ${packageVersion}`);
+  }
+  for (const file of SEARCH_FILES) {
+    try {
+      const bytes = fs.readFileSync(path.join(kbDir, file));
+      result.searchFiles[file] = { bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') };
+      if (!bytes.length) result.issues.push(`search executable ${file} is empty`);
+    } catch { result.issues.push(`search executable ${file} is missing`); }
+  }
+  // The installed archive manifest lets doctor detect code drift even if SOURCE's version stayed
+  // unchanged. This is a consistency check, not independent authentication of a local manifest.
+  try {
+    const archive = JSON.parse(fs.readFileSync(path.join(kbDir, 'ARCHIVE-MANIFEST.json'), 'utf8'));
+    if (archive.kind !== 'ruvnet-brain-archive-manifest' || !Array.isArray(archive.files)) {
+      throw new Error('invalid archive manifest shape');
+    }
+    if (version(archive.version) !== result.searchVersion) {
+      result.issues.push('archive manifest and search engine versions differ');
+    }
+    const runtimeFiles = new Set([...SEARCH_FILES, ...archive.files.filter(row => isRuntimeFile(row?.path)).map(row => row.path)]);
+    for (const file of runtimeFiles) {
+      if (typeof file !== 'string' || path.isAbsolute(file) || file.includes('\\')
+        || file.split('/').some(part => !part || part === '.' || part === '..')) {
+        result.issues.push('archive manifest contains an unsafe runtime path');
+        continue;
+      }
+      const rows = archive.files.filter(row => row?.path === file);
+      let actual = result.searchFiles[file];
+      if (!actual) {
+        try {
+          const bytes = fs.readFileSync(path.join(kbDir, file));
+          actual = { bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') };
+          result.searchFiles[file] = actual;
+        } catch { result.issues.push(`runtime file ${file} is missing`); }
+      }
+      if (rows.length !== 1 || !/^[a-f0-9]{64}$/.test(rows[0]?.sha256 || '')
+        || !Number.isSafeInteger(rows[0]?.bytes) || rows[0].bytes < 0) {
+        result.issues.push(`archive manifest has no unique valid identity for ${file}`);
+      } else if (actual && (actual.sha256 !== rows[0].sha256 || actual.bytes !== rows[0].bytes)) {
+        result.issues.push(`search executable ${file} differs from the installed archive manifest`);
+      }
+    }
+  } catch (error) {
+    result.issues.push(`installed archive manifest is missing or unreadable: ${error.message}`);
+  }
+  // These hashes and the local manifest are NOT independent release approval receipts.
+  result.healthy = result.issues.length === 0;
+  return result;
+}
+
+export function classifySmokeEvidence(verification, answer) {
+  if (!verification?.grounded) return { usable: false, reason: verification?.reason || 'citation-not-verified' };
+  const weak = /EVIDENCE:\s*(?:INSUFFICIENT_EVIDENCE|THIN)\b/i.test(answer);
+  if (weak) return { usable: false, reason: 'retrieval-evidence-insufficient' };
+  if (/BUILT\/SHIPPED CLAIM:\s*NOT PROVEN/i.test(answer)) {
+    return { usable: false, reason: 'required-implementation-unproven' };
+  }
+  return { usable: true, reason: null };
+}

package/scripts/public-inputs.mjs

@@ -36,6 +36,7 @@ import { fileURLToPath } from 'node:url';
 import { digest, fileIdentity } from './coverage-integrity.mjs';
 import { isPrivate, loadPrivateFence, loadPrivateSlugs, shouldFenceL2 } from './private-fence.mjs';
 import { promoteArtifactSet } from '../kb/incremental-refresh.mjs';
+import { isCapabilityOnly } from '../kb/capability-only.mjs';
 
 const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HEX40 = /^[a-f0-9]{40}$/;
@@ -299,7 +300,7 @@ export function materializePublicInputs({ builderRoot = DEFAULT_ROOT, policy = {
   try {
     for (const repo of allRepos) {
       const src = path.join(kb, `${repo}-primer.md`);
-      if (isPrivate(privateSet, repo)) {
+      if (isPrivate(privateSet, repo) || isCapabilityOnly(repo)) {
         excluded.primers.push({ repo, ...excludedIdentity(src) });
         continue;
       }

package/scripts/public-verification-inputs.mjs

@@ -113,6 +113,18 @@ function exactNamedFile(root, name, label) {
   return trustedFile(path.join(root, name), label);
 }
 
+function validHistoricalGenerationLedger(ledger, names) {
+  const legacy = ledger?.schemaVersion === 1;
+  const runtime = ledger?.schemaVersion === 2
+    && ledger?.kind === 'ruvnet-brain-runtime-generation-ledger'
+    && HEX40.test(String(ledger?.sourceSnapshot || ''));
+  return (legacy || runtime)
+    && typeof ledger?.brainVersion === 'string' && Boolean(ledger.brainVersion)
+    && typeof ledger?.releaseTag === 'string' && Boolean(ledger.releaseTag)
+    && names.length > 0
+    && new Set(names.map((name) => name.toLowerCase())).size === names.length;
+}
+
 function validateCandidate({ root, bundleFile, packageFile }) {
   const coverageFile = trustedFile(path.join(root, 'COVERAGE.json'), 'candidate release coverage');
   const coverageBytes = fs.readFileSync(coverageFile);
@@ -176,9 +188,7 @@ function retrospectiveBaselineFromTree({ extractedRoot, bundleFile, expectedTag,
   const root = path.dirname(ledgerFile);
   const { value: ledger } = readJson(ledgerFile, 'historical baseline generation ledger');
   const names = Object.keys(ledger?.stores || {}).sort();
-  if (ledger.schemaVersion !== 1 || typeof ledger.brainVersion !== 'string' || !ledger.brainVersion
-    || typeof ledger.releaseTag !== 'string' || !ledger.releaseTag || !names.length
-    || new Set(names.map((name) => name.toLowerCase())).size !== names.length) {
+  if (!validHistoricalGenerationLedger(ledger, names)) {
     fail('historical baseline generation ledger is malformed');
   }
   const archive = namedIdentity(bundleFile);
@@ -245,9 +255,7 @@ function observedBaselineFromTree({ extractedRoot, bundleFile, expectedTag, expe
   const root = path.dirname(ledgerFile);
   const { value: ledger } = readJson(ledgerFile, 'historical baseline generation ledger');
   const ledgerNames = Object.keys(ledger?.stores || {}).sort();
-  if (ledger.schemaVersion !== 1 || typeof ledger.brainVersion !== 'string' || !ledger.brainVersion
-    || typeof ledger.releaseTag !== 'string' || !ledger.releaseTag || !ledgerNames.length
-    || new Set(ledgerNames.map((name) => name.toLowerCase())).size !== ledgerNames.length) {
+  if (!validHistoricalGenerationLedger(ledger, ledgerNames)) {
     fail('historical baseline generation ledger is malformed');
   }
   const archive = namedIdentity(bundleFile);

package/scripts/refresh-capability-only-store.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Rebuild ruOS's release store from the curated capability summary, never from repository source.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { buildCorpus } from '../kb/forge-corpus.mjs';
+import { loadRvf } from '../kb/resolve-deps.mjs';
+import { CAPABILITY_RETIRED_SUFFIXES, isCapabilityOnly } from '../kb/capability-only.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const NAME = 'cognitum-ruos';
+const MODEL = 'Xenova/bge-base-en-v1.5';
+const DIMENSIONS = 768;
+
+function writeJson(file, value) {
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function prepareCapabilityOnlyInputs(assetsDir) {
+  const dir = path.resolve(assetsDir);
+  if (!fs.statSync(dir).isDirectory()) throw new Error(`assets directory is invalid: ${dir}`);
+  const corpus = buildCorpus({ repo: dir, name: NAME });
+  if (corpus.chunks.length !== 1 || corpus.chunks[0].path !== 'CAPABILITIES.md'
+    || corpus.chunks[0].kind !== 'doc') {
+    throw new Error('curated ruOS source must produce exactly one CAPABILITIES.md document');
+  }
+
+  for (const suffix of CAPABILITY_RETIRED_SUFFIXES) fs.rmSync(path.join(dir, `${NAME}${suffix}`), { force: true });
+  for (const file of fs.readdirSync(dir)) {
+    if (file.startsWith(`${NAME}.big.vecs.`) || file.startsWith(`${NAME}.big.progress.`)) {
+      fs.rmSync(path.join(dir, file), { force: true });
+    }
+  }
+  const chunk = corpus.chunks[0];
+  writeJsonLines(path.join(dir, `${NAME}.passages.jsonl`), [{
+    id: chunk.id, text: chunk.text, path: chunk.path, title: chunk.title,
+  }]);
+  writeJson(path.join(dir, `${NAME}.meta.json`), {
+    model: MODEL, dimensions: DIMENSIONS, metric: 'cosine', generated: new Date().toISOString(),
+    entries: { [chunk.id]: { path: chunk.path, kind: chunk.kind, title: chunk.title, chunk: '1/1', preview: chunk.preview } },
+  });
+  return { dir, sourceText: chunk.text, id: chunk.id };
+}
+
+// Historical v4.3.26 Brain self-store embedded the implementation primer. Remove those
+// vectors from the copied seed and bind the rewritten bytes before packaging.
+export async function pruneCapabilityOnlySelfStore(assetsDir, { RvfDatabase = null } = {}) {
+  const dir = path.resolve(assetsDir);
+  const passagesFile = path.join(dir, 'ruvnet-brain.passages.jsonl');
+  const metaFile = path.join(dir, 'ruvnet-brain.meta.json');
+  const rvfFile = path.join(dir, 'ruvnet-brain.big.rvf');
+  const ledgerFile = path.join(dir, 'RVF-GENERATIONS.json');
+  const rows = fs.readFileSync(passagesFile, 'utf8').trim().split('\n').filter(Boolean).map(JSON.parse);
+  const removed = rows.filter(row => /(?:^|\/)cognitum-ruos-primer\.md$/i.test(row.path || ''));
+  if (!removed.length) return { removed: 0 };
+  if (!RvfDatabase) ({ mod: { RvfDatabase } } = loadRvf());
+  const db = await RvfDatabase.open(rvfFile);
+  try {
+    await db.delete(removed.map(row => row.id));
+    await db.compact();
+  } finally { await db.close(); }
+  const kept = rows.filter(row => !removed.some(item => item.id === row.id));
+  writeJsonLines(passagesFile, kept);
+  const meta = JSON.parse(fs.readFileSync(metaFile, 'utf8'));
+  const removedIds = new Set(removed.map(row => row.id));
+  for (const row of removed) {
+    const entry = meta.entries?.[row.path];
+    if (!entry) continue;
+    entry.chunkIds = (entry.chunkIds || []).filter(id => !removedIds.has(id));
+    if (!entry.chunkIds.length) delete meta.entries[row.path];
+  }
+  writeJson(metaFile, meta);
+  const ledger = JSON.parse(fs.readFileSync(ledgerFile, 'utf8'));
+  const bytes = fs.readFileSync(rvfFile);
+  ledger.stores['ruvnet-brain'] = {
+    ...ledger.stores['ruvnet-brain'],
+    sha256: crypto.createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length,
+    builtUtc: new Date().toISOString(),
+  };
+  writeJson(ledgerFile, ledger);
+  return { removed: removed.length };
+}
+
+function writeJsonLines(file, rows) {
+  fs.writeFileSync(file, `${rows.map((row) => JSON.stringify(row)).join('\n')}\n`);
+}
+
+export function bindCapabilityOnlyGeneration(assetsDir, { builtUtc = new Date().toISOString() } = {}) {
+  const dir = path.resolve(assetsDir);
+  const rvfFile = path.join(dir, `${NAME}.big.rvf`);
+  const metaFile = path.join(dir, `${NAME}.meta.json`);
+  const ledgerFile = path.join(dir, 'RVF-GENERATIONS.json');
+  const embedFile = path.join(dir, `${NAME}.big.rvf.embed.json`);
+  const rvf = fs.readFileSync(rvfFile);
+  const embed = JSON.parse(fs.readFileSync(embedFile, 'utf8'));
+  const meta = JSON.parse(fs.readFileSync(metaFile, 'utf8'));
+  if (embed.model !== MODEL || embed.dimensions !== DIMENSIONS || Object.keys(meta.entries || {}).length !== 1) {
+    throw new Error('rebuilt ruOS store does not match the 768-dim, one-summary contract');
+  }
+  const ledger = JSON.parse(fs.readFileSync(ledgerFile, 'utf8'));
+  if (!ledger || ![1, 2].includes(ledger.schemaVersion) || typeof ledger.stores !== 'object' || !ledger.stores) {
+    throw new Error('seed runtime generation ledger is malformed');
+  }
+  const previous = ledger.stores[NAME] || {};
+  ledger.stores[NAME] = {
+    file: `${NAME}.big.rvf`,
+    sha256: crypto.createHash('sha256').update(rvf).digest('hex'),
+    bytes: rvf.length,
+    model: MODEL,
+    dimensions: DIMENSIONS,
+    sourceCommit: previous.sourceCommit ?? null,
+    builtUtc,
+  };
+  writeJson(ledgerFile, ledger);
+  return ledger.stores[NAME];
+}
+
+export async function refreshCapabilityOnlyStore(assetsDir) {
+  const { dir } = prepareCapabilityOnlyInputs(assetsDir);
+  const selfStore = await pruneCapabilityOnlySelfStore(dir);
+  const script = path.join(ROOT, 'kb/forge-big.mjs');
+  const result = spawnSync(process.execPath, [script, 'both', '--dir', dir, '--name', NAME], {
+    cwd: ROOT, encoding: 'utf8', stdio: 'inherit', env: process.env,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`ruOS capability-only RVF build exited ${result.status}`);
+  return { ...bindCapabilityOnlyGeneration(dir), selfStore };
+}
+
+async function main(argv) {
+  const index = argv.indexOf('--assets');
+  const assetsDir = index >= 0 ? argv[index + 1] : null;
+  if (!assetsDir) throw new Error('Usage: refresh-capability-only-store.mjs --assets <seed-kb-directory>');
+  if (!isCapabilityOnly(NAME)) throw new Error('configured store is not capability-only');
+  const result = await refreshCapabilityOnlyStore(assetsDir);
+  console.log(JSON.stringify({ store: NAME, ...result }));
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  try { await main(process.argv.slice(2)); } catch (error) { console.error(`[capability-store] ${error.message}`); process.exitCode = 1; }
+}