ruvnet-brain 4.3.21 → 4.3.25

package/scripts/oracle/source-tree.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/source-tree.mjs — the PINNED GIT TREE a C3 unit inventory is enumerated from.
+ *
+ * ADR-086 C3, per the EXTEND_FIRST Dual verdict (2026-09-14): "Enumerate the pinned Git tree and read its
+ * bound objects. A commit label on a filesystem walk is insufficient." A filesystem walk sees whatever
+ * happens to be checked out — ignored files, build output, a dirty worktree, LFS-smudged content — and
+ * cannot prove it describes the commit it is labelled with. This module reads the tree object itself.
+ *
+ * Every tracked entry gets exactly one PRIMARY entry kind, so nothing is silently skipped:
+ *   file | executable | symlink | gitlink (submodule pointer, content NOT imported) | lfs-pointer | binary
+ * Emptiness can never be inferred from what this module could not read: symlinks, gitlinks, LFS pointers
+ * and binaries are recorded explicitly, never dropped.
+ *
+ * Deterministic and model-free. The manifest carries its own sha256 over a canonical encoding, so two
+ * enumerations of the same commit are byte-identical across process boundaries.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const SOURCE_TREE_VERSION = 'oracle-source-tree/1';
+export const LFS_POINTER_PREFIX = 'version https://git-lfs.github.com/spec/v1';
+// git's own binary heuristic looks for a NUL in the first 8000 bytes; use the same boundary.
+export const BINARY_SNIFF_BYTES = 8000;
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+function git(repoDir, args, { input, maxBuffer = 1024 * 1024 * 1024 } = {}) {
+  const r = spawnSync('git', ['-C', repoDir, ...args], { input, maxBuffer });
+  if (r.error) throw new Error(`git ${args[0]} failed to start: ${r.error.message}`);
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} exited ${r.status}: ${String(r.stderr).trim().slice(0, 300)}`);
+  return r.stdout;
+}
+
+/** Resolve a commit-ish to its exact commit and root tree. Refuses anything that is not a commit. */
+export function resolveCommit({ repoDir, commit }) {
+  const commitSha = String(git(repoDir, ['rev-parse', '--verify', `${commit}^{commit}`])).trim();
+  const treeSha = String(git(repoDir, ['rev-parse', '--verify', `${commitSha}^{tree}`])).trim();
+  return { commitSha, treeSha };
+}
+
+/**
+ * Every entry in the commit's tree, recursively, from the tree OBJECT. Output format of
+ * `git ls-tree -r -l -z --full-tree`: "<mode> SP <type> SP <object> SP+ <size>\t<path>\0".
+ */
+export function listTree({ repoDir, commit }) {
+  const raw = git(repoDir, ['ls-tree', '-r', '-l', '-z', '--full-tree', commit]);
+  const entries = [];
+  for (const record of raw.toString('utf8').split('\0')) {
+    if (!record) continue;
+    const tab = record.indexOf('\t');
+    if (tab < 0) throw new Error(`unparseable ls-tree record: ${record.slice(0, 120)}`);
+    const [mode, type, objectSha, sizeField] = record.slice(0, tab).trim().split(/\s+/);
+    entries.push({
+      path: record.slice(tab + 1),
+      mode,
+      type,
+      objectSha,
+      size: sizeField === '-' ? null : Number(sizeField),
+    });
+  }
+  return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/** Read many blob objects in one `git cat-file --batch` round trip. */
+export function readBlobs({ repoDir, shas }) {
+  const unique = [...new Set(shas)];
+  const out = new Map();
+  if (!unique.length) return out;
+  const buf = git(repoDir, ['cat-file', '--batch'], { input: `${unique.join('\n')}\n` });
+  let offset = 0;
+  while (offset < buf.length) {
+    const newline = buf.indexOf(0x0a, offset);
+    const header = buf.subarray(offset, newline).toString('utf8');
+    const [sha, kind, sizeText] = header.split(' ');
+    if (kind === 'missing') throw new Error(`blob ${sha} is missing from the object store`);
+    const size = Number(sizeText);
+    const start = newline + 1;
+    out.set(sha, buf.subarray(start, start + size));
+    offset = start + size + 1; // content is followed by a single LF
+  }
+  return out;
+}
+
+/** The single primary kind of a tree entry. Content is consulted only for regular blobs. */
+export function classifyEntry(entry, bytes) {
+  if (entry.type === 'commit' || entry.mode === '160000') return 'gitlink';
+  if (entry.mode === '120000') return 'symlink';
+  if (!bytes) throw new Error(`classifyEntry(${entry.path}) needs the blob bytes`);
+  if (bytes.subarray(0, LFS_POINTER_PREFIX.length).toString('utf8') === LFS_POINTER_PREFIX) return 'lfs-pointer';
+  if (bytes.subarray(0, BINARY_SNIFF_BYTES).includes(0)) return 'binary';
+  return entry.mode === '100755' ? 'executable' : 'file';
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value === undefined ? null : value);
+}
+
+/**
+ * The snapshot manifest: one row per tracked entry, each with its exact object identity, content digest
+ * (regular blobs only) and primary kind. Returns `{ manifest, blobs }` so an enumerator can reuse the
+ * bytes it already read instead of touching the filesystem.
+ */
+export function snapshotManifest({ repoDir, commit, repo }) {
+  const { commitSha, treeSha } = resolveCommit({ repoDir, commit });
+  const entries = listTree({ repoDir, commit: commitSha });
+  const blobShas = entries.filter((e) => e.type === 'blob' && e.mode !== '120000').map((e) => e.objectSha);
+  const blobs = readBlobs({ repoDir, shas: blobShas });
+  const rows = entries.map((e) => {
+    const bytes = e.type === 'blob' && e.mode !== '120000' ? blobs.get(e.objectSha) : null;
+    const entryKind = classifyEntry(e, bytes);
+    return {
+      path: e.path,
+      mode: e.mode,
+      objectSha: e.objectSha,
+      size: e.size,
+      entryKind,
+      contentSha256: bytes ? sha256(bytes) : null,
+    };
+  });
+  const body = { version: SOURCE_TREE_VERSION, repo, commitSha, treeSha, entries: rows };
+  return { manifest: { ...body, manifestSha256: sha256(Buffer.from(canonical(body), 'utf8')) }, blobs };
+}
+
+function arg(argv, flag) { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; }
+
+export function main(argv = process.argv.slice(2)) {
+  const repoDir = arg(argv, '--repo-dir');
+  const commit = arg(argv, '--commit');
+  const repo = arg(argv, '--repo');
+  const out = arg(argv, '--out');
+  if (!repoDir || !commit || !repo) {
+    process.stderr.write('Usage: source-tree.mjs --repo-dir <git dir> --commit <sha> --repo <name> [--out <manifest.json>]\n');
+    return 64;
+  }
+  const { manifest } = snapshotManifest({ repoDir: path.resolve(repoDir), commit, repo });
+  const json = `${JSON.stringify(manifest, null, 2)}\n`;
+  if (out) fs.writeFileSync(out, json); else process.stdout.write(json);
+  const kinds = manifest.entries.reduce((acc, e) => ({ ...acc, [e.entryKind]: (acc[e.entryKind] || 0) + 1 }), {});
+  process.stderr.write(`[source-tree] ${repo}@${manifest.commitSha.slice(0, 12)} tree ${manifest.treeSha.slice(0, 12)}: ${manifest.entries.length} entries ${JSON.stringify(kinds)}\n`);
+  return 0;
+}
+
+// Entry-point guard. Compares REALPATHS on both sides: path.resolve() normalizes a path but does
+// NOT follow symlinks, while import.meta.url IS symlink-resolved by Node. Through a symlink (npm bin
+// shims, wrapper scripts, and every os.tmpdir() path on macOS) the two sides disagree, so main()
+// never runs -- and because nothing throws, the process exits 0. Pinned by
+// tests/unit/entrypoint-symlink.test.mjs.
+function isDirectInvocation() {
+  try {
+    if (!process.argv[1]) return false;
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) process.exitCode = main();

package/scripts/oracle/source-units.mjs

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/source-units.mjs — Step 14 (ADR-086, owner criterion C3) deterministic inventory.
+ *
+ * NO MODEL. Given a checked-out upstream snapshot and its exact commit, enumerate U "meaningful
+ * source units", stratify them by top-level directory × language, and select min(100, U) with a
+ * PRNG seeded from `${repo}@${commit}`. Same input → byte-identical JSON across a process boundary
+ * (tests/unit/oracle-source-units.test.mjs proves it by running the CLI twice).
+ *
+ * Every unit is bound to path + git blob SHA (sha1 over "blob <len>\0<bytes>", identical to
+ * `git hash-object`) + 1-based inclusive line span + sha256 of the unit text. A label produced later
+ * can therefore be re-checked against exact upstream bytes, and regenerated ONLY when the blob
+ * changes — the amortization Dual's C3 spec asks for.
+ *
+ * Covered: Markdown (ATX H2/H3 sections), JavaScript/TypeScript (@babel/parser AST: exported or
+ * doc-commented top-level functions, classes, interfaces, type aliases, enums, namespaces), Rust
+ * (regex: bare `pub` fn/struct/enum/trait/type/union, brace-matched), Python (regex: module-level
+ * public def/class blocks). NOT covered (inventoried as `unsupported`, counted, never silently
+ * dropped): Go, Java, C/C++, Shell, Svelte, YAML/JSON/TOML, setext Markdown headings, CommonJS
+ * `module.exports` assignments, Rust items under `#[cfg(test)]`, Rust `pub(crate)` items.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parse as babelParse } from '@babel/parser';
+
+export const RULES_VERSION = 'oracle-source-units/1';
+export const MAX_SELECTED = 100;
+export const MIN_MARKDOWN_WORDS = 40;
+export const MIN_CODE_TOKENS = 25;
+export const MAX_FILE_BYTES = 1_048_576;
+
+export const LANGUAGE_BY_EXT = Object.freeze({
+  '.md': 'markdown', '.markdown': 'markdown',
+  '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript', '.jsx': 'javascript',
+  '.ts': 'typescript', '.tsx': 'typescript', '.mts': 'typescript', '.cts': 'typescript',
+  '.rs': 'rust', '.py': 'python',
+});
+
+const VCS_IDE_DIRS = new Set(['.git', '.github', '.gitlab', '.vscode', '.idea', '.circleci', '.husky', '.devcontainer', '.svn', '.hg']);
+const DEP_BUILD_DIRS = new Set(['node_modules', 'vendor', 'vendors', 'third_party', 'third-party', 'bower_components',
+  'dist', 'build', 'out', 'target', 'coverage', '__pycache__', '.venv', 'venv', '.cache', '.next', '.turbo',
+  '.pytest_cache', '.mypy_cache', 'site-packages']);
+const TEST_DIRS = new Set(['test', 'tests', '__tests__', '__mocks__', 'fixtures', 'fixture', 'snapshots', '__snapshots__', 'e2e', 'spec']);
+const LOCKFILES = new Set(['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'Cargo.lock', 'poetry.lock', 'Pipfile.lock',
+  'bun.lockb', 'go.sum', 'composer.lock', 'Gemfile.lock', 'flake.lock', 'uv.lock']);
+const META_FILE = /^(license|licence|copying|notice|patents|changelog|changes|history|code_of_conduct|contributing|contributors|authors|security|codeowners)(\.[a-z0-9]+)?$/i;
+const GENERATED_MARKER = /@generated|code generated|do not edit|automatically generated|auto-generated/i;
+const BOILERPLATE_HEADING = /^(table of contents|contents|toc|license|licence|contributing|contributors|acknowledg(e)?ments|changelog|badges|star history|sponsors?|citation|credits)$/i;
+
+/** Path-only exclusion rules, applied to every file. Order matters: the first match names the reason. */
+export const PATH_RULES = Object.freeze([
+  ['vcs-or-ide-dir', (rel) => dirSegments(rel).some((s) => VCS_IDE_DIRS.has(s))],
+  ['dependency-or-build-dir', (rel) => dirSegments(rel).some((s) => DEP_BUILD_DIRS.has(s))],
+  ['test-dir', (rel) => dirSegments(rel).some((s) => TEST_DIRS.has(s))],
+  ['test-file', (rel) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(rel) || /(^|\/)test_[^/]*\.py$/.test(rel) || /_test\.py$/.test(rel)],
+  ['license-changelog-or-meta', (rel) => META_FILE.test(path.posix.basename(rel))],
+  ['lockfile', (rel) => LOCKFILES.has(path.posix.basename(rel)) || /\.lock$/.test(rel)],
+  ['minified-map-or-typings', (rel) => /\.min\.[cm]?js$/.test(rel) || /\.map$/.test(rel) || /\.d\.[cm]?ts$/.test(rel) || /\.snap$/.test(rel)],
+]);
+
+/** Byte rules, applied only to files in a covered language (the only ones ever read). */
+export const BYTE_RULES = Object.freeze([
+  ['oversized', (buf) => buf.length > MAX_FILE_BYTES],
+  ['binary', (buf) => buf.subarray(0, 8000).includes(0)],
+  ['generated-marker', (buf) => GENERATED_MARKER.test(buf.subarray(0, 2000).toString('utf8').split('\n').slice(0, 5).join('\n'))],
+]);
+
+function dirSegments(rel) { return rel.split('/').slice(0, -1); }
+export function sha256Hex(input) { return createHash('sha256').update(input).digest('hex'); }
+/** Exactly what `git hash-object <file>` prints. */
+export function gitBlobSha(buffer) {
+  return createHash('sha1').update(`blob ${buffer.length}\0`).update(buffer).digest('hex');
+}
+
+// ── Markdown ───────────────────────────────────────────────────────────────────────────────────
+const ATX = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+const FENCE = /^[ \t]{0,3}(```|~~~)/;
+const WORD = /[A-Za-z][A-Za-z0-9'’-]+/g;
+
+function fenceTracker() {
+  let mark = null;
+  return (line) => { // returns true when the line is a fence delimiter or inside a fence
+    const f = FENCE.exec(line);
+    if (f) {
+      if (mark === null) mark = f[1];
+      else if (line.trim().startsWith(mark)) mark = null;
+      return true;
+    }
+    return mark !== null;
+  };
+}
+
+export function countProseWords(lines) {
+  const fenced = fenceTracker();
+  let words = 0;
+  for (const raw of lines) {
+    if (fenced(raw)) continue;
+    const line = raw.trim();
+    if (!line || line.startsWith('|')) continue;
+    if (/^(!?\[[^\]]*\]\([^)]*\)\s*)+$/.test(line)) continue; // badges / bare links
+    if (/^<[^>]+>$/.test(line)) continue; // html-only line
+    const prose = line.replace(/https?:\/\/\S+/g, ' ').replace(/<[^>]+>/g, ' ');
+    words += (prose.match(WORD) || []).length;
+  }
+  return words;
+}
+
+export function extractMarkdownUnits(text) {
+  const lines = text.split('\n');
+  const fenced = fenceTracker();
+  const headings = [];
+  lines.forEach((line, i) => {
+    if (fenced(line)) return;
+    const m = ATX.exec(line);
+    if (m) headings.push({ line: i, level: m[1].length, title: m[2].trim() });
+  });
+  const units = [];
+  headings.forEach((h, idx) => {
+    if (h.level !== 2 && h.level !== 3) return;
+    if (BOILERPLATE_HEADING.test(h.title.replace(/[*_`:]/g, '').trim())) return;
+    let end = lines.length;
+    for (let j = idx + 1; j < headings.length; j++) if (headings[j].level <= 3) { end = headings[j].line; break; }
+    while (end > h.line + 1 && lines[end - 1].trim() === '') end--;
+    const words = countProseWords(lines.slice(h.line + 1, end));
+    if (words < MIN_MARKDOWN_WORDS) return;
+    units.push({ startLine: h.line + 1, endLine: end, kind: 'md-section', name: h.title });
+  });
+  return units;
+}
+
+// ── JavaScript / TypeScript ────────────────────────────────────────────────────────────────────
+const JS_KINDS = {
+  FunctionDeclaration: 'js-function', ClassDeclaration: 'js-class', TSInterfaceDeclaration: 'ts-interface',
+  TSTypeAliasDeclaration: 'ts-type', TSEnumDeclaration: 'ts-enum', TSDeclareFunction: 'ts-declare-function',
+  TSModuleDeclaration: 'ts-namespace',
+};
+const isDocComment = (c) => c.type === 'CommentBlock' && c.value.startsWith('*');
+
+function commentStartLine(node) {
+  const comments = node.leadingComments || [];
+  let start = node.loc.start.line;
+  for (let i = comments.length - 1; i >= 0; i--) {
+    if (comments[i].loc.end.line < start - 1) break;
+    start = comments[i].loc.start.line;
+  }
+  return start;
+}
+
+export function extractJsUnits(text, { typescript = false, jsx = false } = {}) {
+  let ast;
+  try {
+    ast = babelParse(text, {
+      sourceType: 'unambiguous', errorRecovery: true, attachComment: true,
+      plugins: [...(typescript ? ['typescript'] : []), ...(jsx ? ['jsx'] : []), 'decorators-legacy', 'importAttributes'],
+    });
+  } catch (error) {
+    return { error: `parse: ${error.message}`, units: [] };
+  }
+  const units = [];
+  for (const node of ast.program.body) {
+    let decl = node;
+    let exported = false;
+    if (node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration') {
+      if (!node.declaration) continue;
+      decl = node.declaration;
+      exported = true;
+    }
+    const documented = (node.leadingComments || []).some(isDocComment);
+    if (!exported && !documented) continue;
+    let kind = JS_KINDS[decl.type];
+    let name = decl.id?.name ?? 'default';
+    if (!kind && decl.type === 'VariableDeclaration') {
+      const fns = decl.declarations.filter((d) => d.init && /^(Arrow)?FunctionExpression$/.test(d.init.type));
+      if (fns.length === 0) continue;
+      kind = 'js-const-function';
+      name = fns.map((d) => d.id?.name ?? '(pattern)').join(',');
+    }
+    if (!kind) continue;
+    units.push({ startLine: commentStartLine(node), endLine: node.loc.end.line, kind, name });
+  }
+  return { units };
+}
+
+// ── Rust (regex, conservative) ─────────────────────────────────────────────────────────────────
+const RUST_ITEM = /^\s*pub\s+(?:(?:async|unsafe|const|extern\s+"[^"]*")\s+)*(fn|struct|enum|trait|type|union)\s+([A-Za-z_][A-Za-z0-9_]*)/;
+const stripRustLine = (line) => line
+  .replace(/"(?:[^"\\]|\\.)*"/g, '""').replace(/'(?:[^'\\]|\\.)'/g, "''").replace(/\/\/.*$/, '');
+
+function findRustEnd(lines, from) {
+  let depth = 0;
+  let opened = false;
+  for (let j = from; j < Math.min(lines.length, from + 3000); j++) {
+    for (const ch of stripRustLine(lines[j])) {
+      if (ch === '{') { depth++; opened = true; } else if (ch === '}') { depth--; if (opened && depth === 0) return j; } else if (ch === ';' && !opened) return j;
+    }
+  }
+  return -1;
+}
+
+export function extractRustUnits(text) {
+  const lines = text.split('\n');
+  const units = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = RUST_ITEM.exec(lines[i]);
+    if (!m) continue;
+    let start = i;
+    while (start > 0 && /^\s*(\/\/\/|#\[)/.test(lines[start - 1])) start--;
+    const end = findRustEnd(lines, i);
+    if (end < 0) continue;
+    units.push({ startLine: start + 1, endLine: end + 1, kind: `rust-${m[1]}`, name: m[2] });
+    i = end;
+  }
+  return units;
+}
+
+// ── Python (regex, conservative) ───────────────────────────────────────────────────────────────
+const PY_DEF = /^(async\s+def|def|class)\s+([A-Za-z][A-Za-z0-9_]*)/;
+
+export function extractPythonUnits(text) {
+  const lines = text.split('\n');
+  const units = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = PY_DEF.exec(lines[i]);
+    if (!m) continue;
+    let start = i;
+    while (start > 0 && /^@/.test(lines[start - 1])) start--;
+    let end = i;
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l.trim() === '') continue;
+      if (/^[\s)\]]/.test(l)) { end = j; continue; }
+      break;
+    }
+    units.push({ startLine: start + 1, endLine: end + 1, kind: m[1].startsWith('class') ? 'py-class' : 'py-function', name: m[2] });
+    i = end;
+  }
+  return units;
+}
+
+// ── Per-file extraction ────────────────────────────────────────────────────────────────────────
+const CODE_TOKEN = /[A-Za-z_$][A-Za-z0-9_$]+/g;
+export function unitText(lines, startLine, endLine) { return lines.slice(startLine - 1, endLine).join('\n'); }
+
+export function extractUnits(rel, text) {
+  const ext = path.posix.extname(rel).toLowerCase();
+  const language = LANGUAGE_BY_EXT[ext];
+  if (language === 'markdown') return { language, units: extractMarkdownUnits(text) };
+  let result;
+  if (language === 'javascript' || language === 'typescript') {
+    result = extractJsUnits(text, { typescript: language === 'typescript', jsx: ['.js', '.mjs', '.cjs', '.jsx', '.tsx'].includes(ext) });
+  } else if (language === 'rust') result = { units: extractRustUnits(text) };
+  else if (language === 'python') result = { units: extractPythonUnits(text) };
+  else return { language: null, units: [] };
+  const lines = text.split('\n');
+  const units = result.units.filter((u) => (unitText(lines, u.startLine, u.endLine).match(CODE_TOKEN) || []).length >= MIN_CODE_TOKENS);
+  return { language, units, error: result.error };
+}
+
+// ── Snapshot walk ──────────────────────────────────────────────────────────────────────────────
+export function listSnapshotFiles(dir) {
+  const out = [];
+  const walk = (abs, rel) => {
+    let entries;
+    try { entries = fs.readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) { if (e.name !== '.git') walk(path.join(abs, e.name), childRel); } else if (e.isFile()) out.push(childRel);
+    }
+  };
+  walk(dir, '');
+  return out.sort();
+}
+
+// ── Deterministic selection ────────────────────────────────────────────────────────────────────
+export function seededRandom(seed) {
+  let counter = 0;
+  return () => createHash('sha256').update(seed).update(`\n${counter++}`).digest().readUIntBE(0, 6) / 2 ** 48;
+}
+export function seededShuffle(items, rand) {
+  const a = [...items];
+  for (let i = a.length - 1; i > 0; i--) { const j = Math.floor(rand() * (i + 1)); [a[i], a[j]] = [a[j], a[i]]; }
+  return a;
+}
+/** Hamilton (largest-remainder) apportionment of `total` slots over strata sizes. */
+export function apportion(sizes, total) {
+  const keys = Object.keys(sizes).sort();
+  const U = keys.reduce((s, k) => s + sizes[k], 0);
+  if (U <= total) return Object.fromEntries(keys.map((k) => [k, sizes[k]]));
+  const quota = Object.fromEntries(keys.map((k) => [k, (sizes[k] * total) / U]));
+  const alloc = Object.fromEntries(keys.map((k) => [k, Math.floor(quota[k])]));
+  let remaining = total - keys.reduce((s, k) => s + alloc[k], 0);
+  const byFraction = keys.filter((k) => alloc[k] < sizes[k])
+    .sort((a, b) => (quota[b] - alloc[b]) - (quota[a] - alloc[a]) || (a < b ? -1 : 1));
+  for (const k of byFraction) { if (remaining <= 0) break; alloc[k]++; remaining--; }
+  return alloc;
+}
+
+export function resolveCommit(dir, explicit) {
+  if (explicit) return explicit;
+  return execFileSync('git', ['-C', dir, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+}
+
+export function buildInventory({ dir, repo, commit, maxSelected = MAX_SELECTED }) {
+  const files = listSnapshotFiles(dir);
+  const excluded = {};
+  const unsupported = {};
+  const uncoveredFiles = [];
+  const all = [];
+  let filesConsidered = 0;
+  for (const rel of files) {
+    const rule = PATH_RULES.find(([, test]) => test(rel));
+    if (rule) { excluded[rule[0]] = (excluded[rule[0]] || 0) + 1; continue; }
+    const ext = path.posix.extname(rel).toLowerCase();
+    const language = LANGUAGE_BY_EXT[ext];
+    if (!language) { const key = ext || '(none)'; unsupported[key] = (unsupported[key] || 0) + 1; continue; }
+    const buf = fs.readFileSync(path.join(dir, rel));
+    const byteRule = BYTE_RULES.find(([, test]) => test(buf));
+    if (byteRule) { excluded[byteRule[0]] = (excluded[byteRule[0]] || 0) + 1; continue; }
+    filesConsidered++;
+    const text = buf.toString('utf8');
+    const { units, error } = extractUnits(rel, text);
+    if (units.length === 0) { uncoveredFiles.push({ path: rel, reason: error ? 'parse-error' : 'no-units' }); continue; }
+    const blobSha = gitBlobSha(buf);
+    const lines = text.split('\n');
+    const topDir = rel.includes('/') ? rel.split('/')[0] : '(root)';
+    for (const u of units) {
+      const body = unitText(lines, u.startLine, u.endLine);
+      all.push({
+        unitId: sha256Hex(`${RULES_VERSION}\n${rel}\n${blobSha}\n${u.startLine}\n${u.endLine}`).slice(0, 16),
+        path: rel, blobSha, startLine: u.startLine, endLine: u.endLine, kind: u.kind, name: u.name,
+        language, stratum: `${topDir}|${language}`, bytesSha256: sha256Hex(Buffer.from(body, 'utf8')),
+        chars: body.length,
+      });
+    }
+  }
+  const sizes = {};
+  for (const u of all) sizes[u.stratum] = (sizes[u.stratum] || 0) + 1;
+  const alloc = apportion(sizes, maxSelected);
+  const seed = `${RULES_VERSION}|${repo}@${commit}`;
+  const selectedIds = new Set();
+  for (const key of Object.keys(alloc)) {
+    const pool = all.filter((u) => u.stratum === key).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : a.startLine - b.startLine));
+    for (const u of seededShuffle(pool, seededRandom(`${seed}|${key}`)).slice(0, alloc[key])) selectedIds.add(u.unitId);
+  }
+  const selected = all.filter((u) => selectedIds.has(u.unitId));
+  return {
+    schemaVersion: 1, kind: 'oracle-source-inventory', rulesVersion: RULES_VERSION, repo, commit, seed,
+    U: all.length, selectedCount: selected.length, selected,
+    strata: Object.keys(sizes).sort().map((key) => ({ key, U: sizes[key], selected: alloc[key] || 0 })),
+    coverage: {
+      filesTotal: files.length, filesExcluded: excluded, filesUnsupported: unsupported, filesConsidered,
+      filesWithUnits: filesConsidered - uncoveredFiles.length, uncoveredFilesCount: uncoveredFiles.length, uncoveredFiles,
+    },
+    rules: { minMarkdownWords: MIN_MARKDOWN_WORDS, minCodeTokens: MIN_CODE_TOKENS, maxFileBytes: MAX_FILE_BYTES, languages: [...new Set(Object.values(LANGUAGE_BY_EXT))] },
+  };
+}
+
+function arg(argv, flag) { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; }
+
+export function main(argv = process.argv.slice(2)) {
+  const dir = arg(argv, '--dir');
+  const repo = arg(argv, '--repo');
+  const out = arg(argv, '--out');
+  if (!dir || !repo) { process.stderr.write('Usage: source-units.mjs --dir <snapshot> --repo <name> [--commit <sha>] [--out <file>]\n'); return 64; }
+  const inventory = buildInventory({ dir: path.resolve(dir), repo, commit: resolveCommit(dir, arg(argv, '--commit')) });
+  const json = `${JSON.stringify(inventory, null, 2)}\n`;
+  if (out) fs.writeFileSync(out, json); else process.stdout.write(json);
+  process.stderr.write(`[source-units] ${repo}@${inventory.commit.slice(0, 10)} U=${inventory.U} selected=${inventory.selectedCount} files=${inventory.coverage.filesTotal} uncovered=${inventory.coverage.uncoveredFilesCount}\n`);
+  return 0;
+}
+
+// Entry-point guard. Compares REALPATHS on both sides: path.resolve() normalizes a path but does
+// NOT follow symlinks, while import.meta.url IS symlink-resolved by Node. Through a symlink (npm bin
+// shims, wrapper scripts, and every os.tmpdir() path on macOS) the two sides disagree, so main()
+// never runs -- and because nothing throws, the process exits 0. A silent exit 0 is indistinguishable
+// from "ran, found nothing", which is how prepareCorpusCandidate once reported SUCCESS with no
+// archive on disk. Reproduced live 2026-07-27; pinned by tests/unit/entrypoint-symlink.test.mjs.
+function isDirectInvocation() {
+  try {
+    if (!process.argv[1]) return false;
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) process.exitCode = main();

package/scripts/oracle/spike-run.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/spike-run.mjs — Step 14 feasibility-spike driver (ADR-086 C3 oracle).
+ *
+ * One repository per invocation, every stage synchronous, every artefact written OUTSIDE the
+ * checkout: inventory (source-units) → subscription-only producer (produce-questions) → deterministic
+ * validation (validate-labels) → one summary JSON the report is written from. This is the spike's
+ * human-run driver; Step 15 decides whether and how prepareCorpusCandidate consumes these modules,
+ * which is why nothing in the pipeline imports this file.
+ *
+ *   node scripts/oracle/spike-run.mjs --repo <name> --dir <snapshot> --out <dir> \
+ *     [--commit <sha>] [--batch 20] [--max-claude-calls 8] [--max-codex-calls 8] [--effort medium] [--skip-produce]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildInventory, resolveCommit } from './source-units.mjs';
+import { produceQuestions, DEFAULT_BATCH } from './produce-questions.mjs';
+import { loadBgeEmbedder, validateLabels } from './validate-labels.mjs';
+
+function arg(argv, flag) { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; }
+const writeJson = (file, value) => fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+
+export async function runSpike({ repo, dir, out, commit, batchSize = DEFAULT_BATCH, maxClaudeCalls = 8, maxCodexCalls = 8, effort = 'medium', skipProduce = false, log = () => {} }) {
+  fs.mkdirSync(out, { recursive: true });
+  const started = Date.now();
+  const inventory = buildInventory({ dir, repo, commit: resolveCommit(dir, commit) });
+  writeJson(path.join(out, 'inventory.json'), inventory);
+  log(`[spike] ${repo}@${inventory.commit.slice(0, 10)} U=${inventory.U} selected=${inventory.selectedCount}`);
+
+  const labelsFile = path.join(out, 'labels.json');
+  let labels;
+  const produceStarted = Date.now();
+  if (skipProduce && fs.existsSync(labelsFile)) {
+    labels = JSON.parse(fs.readFileSync(labelsFile, 'utf8'));
+    log('[spike] reusing existing labels.json');
+  } else {
+    labels = await produceQuestions({ inventory, snapshotDir: dir, batchSize, maxClaudeCalls, maxCodexCalls, effort, workDir: path.join(out, 'producer-work'), log });
+    writeJson(labelsFile, labels);
+  }
+  const produceMs = Date.now() - produceStarted;
+
+  const validateStarted = Date.now();
+  const embed = await loadBgeEmbedder();
+  const validation = await validateLabels({ labels, snapshotDir: dir, embed });
+  writeJson(path.join(out, 'validation.json'), validation);
+  const validateMs = Date.now() - validateStarted;
+
+  const a = validation.aggregate;
+  const calls = labels.calls;
+  const summary = {
+    repo, commit: inventory.commit, U: inventory.U, selected: inventory.selectedCount, N: 2 * inventory.selectedCount,
+    strata: inventory.strata.length, coverage: { ...inventory.coverage, uncoveredFiles: undefined },
+    producer: {
+      claude: { requestedModel: labels.producer.claude.requestedModel, calls: calls.filter((c) => c.host === 'claude').length, ok: calls.filter((c) => c.host === 'claude' && c.ok).length, modelUsage: [...new Set(calls.flatMap((c) => c.modelUsage || []))], reportedCostEstimateUsd: calls.reduce((s, c) => s + (c.reportedCostEstimateUsd || 0), 0), timeouts: calls.filter((c) => c.host === 'claude' && c.timedOut).length },
+      codex: { requestedModel: labels.producer.codex.requestedModel, calls: calls.filter((c) => c.host === 'codex').length, ok: calls.filter((c) => c.host === 'codex' && c.ok).length, timeouts: calls.filter((c) => c.host === 'codex' && c.timedOut).length, hostErrors: [...new Set(calls.flatMap((c) => c.hostErrors || []))] },
+      envAudit: labels.envAudit, skipped: a.skipped, producerErrors: a.producerErrors,
+    },
+    validation: { total: a.total, pass: a.pass, byCheck: a.byCheck, informationalE: a.informationalE, secondary: a.secondary, codex: a.codex, cosineCalibration: a.cosineCalibration },
+    wallClockMs: { produce: produceMs, validate: validateMs, total: Date.now() - started },
+    callDurationsMs: calls.map((c) => ({ host: c.host, batch: c.batchIndex, ms: c.durationMs, ok: c.ok })),
+  };
+  writeJson(path.join(out, 'summary.json'), summary);
+  log(`[spike] ${repo}: validation ${a.pass}/${a.total} pass; codex both-yes ${a.codex.bothYes}/${a.codex.withVerdicts}; ${Math.round(summary.wallClockMs.total / 1000)}s`);
+  return summary;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const repo = arg(argv, '--repo');
+  const dir = arg(argv, '--dir');
+  const out = arg(argv, '--out');
+  if (!repo || !dir || !out) { process.stderr.write('Usage: spike-run.mjs --repo <name> --dir <snapshot> --out <dir> [--commit <sha>] [--batch 20] [--max-claude-calls 8] [--max-codex-calls 8] [--effort medium] [--skip-produce]\n'); return 64; }
+  const summary = await runSpike({
+    repo, dir: path.resolve(dir), out: path.resolve(out), commit: arg(argv, '--commit'),
+    batchSize: Number(arg(argv, '--batch') || DEFAULT_BATCH), maxClaudeCalls: Number(arg(argv, '--max-claude-calls') || 8),
+    maxCodexCalls: Number(arg(argv, '--max-codex-calls') || 8), effort: arg(argv, '--effort') || 'medium',
+    skipProduce: argv.includes('--skip-produce'), log: (line) => process.stderr.write(`${line}\n`),
+  });
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+  return 0;
+}
+
+// Entry-point guard. Compares REALPATHS on both sides: path.resolve() normalizes a path but does
+// NOT follow symlinks, while import.meta.url IS symlink-resolved by Node. Through a symlink (npm bin
+// shims, wrapper scripts, and every os.tmpdir() path on macOS) the two sides disagree, so main()
+// never runs -- and because nothing throws, the process exits 0. A silent exit 0 is indistinguishable
+// from "ran, found nothing", which is how prepareCorpusCandidate once reported SUCCESS with no
+// archive on disk. Reproduced live 2026-07-27; pinned by tests/unit/entrypoint-symlink.test.mjs.
+function isDirectInvocation() {
+  try {
+    if (!process.argv[1]) return false;
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) process.exitCode = await main();