hullproof 0.0.0-stage → 0.5.0

package/src/prove/recipe.ts

@@ -0,0 +1,215 @@
+// Start recipes: how to build and start an app in the sandbox, read from stack.json and the code map and from the repository itself.
+// Two recipes: a Node app on Express with a local SQLite file or an ephemeral Postgres, and (Phase 6d) a Python app on Flask with a
+// local SQLite file. Anything else, or anything that needs a hosted service, comes back as "not provable here" with the reason. A
+// recipe is never guessed.
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CodeMap, Recipe, RecipeResult, Stack } from '../types/index.ts';
+import { cmp } from '../util.ts';
+import { dummyValue, envNames } from './safety.ts';
+import { canon, sha256 } from './spec.ts';
+
+export const BASE_IMAGE = 'node:22-slim';
+export const PYTHON_IMAGE = 'python:3.12-slim';
+const HOSTED_DATA = new Set(['supabase', 'firebase-realtime-database', 'firestore', 'dynamodb', 'azure-cosmos-db', 'neon', 'planetscale', 'turso', 'aws-rds', 'google-cloud-sql', 'azure-database-mysql', 'azure-database-postgres', 'azure-sql']);
+const HOSTED_AUTH = new Set(['auth0', 'clerk', 'firebase-auth', 'supabase-auth', 'aws-cognito', 'kinde', 'workos', 'stytch', 'okta', 'microsoft-entra']);
+const LOCAL_DATA = new Set(['sqlite', 'postgres']);
+const NATIVE = ['better-sqlite3', 'sqlite3', 'bcrypt', 'sharp', 'canvas', 'argon2', 'node-sass', 'grpc', 'libsql'];
+const DB_VARS = /^(?:DATABASE_URL|DB_PATH|DATABASE_PATH|SQLITE_PATH|SQLITE_FILE|DB_FILE|DATABASE_FILE)$/;
+const HEALTH = ['/health', '/healthz', '/api/health', '/ping', '/status', '/'];
+const nice = (id: string): string => id.replace(/-/g, ' ');
+
+const no = (code: Extract<RecipeResult, { ok: false }>['code'], reason: string): RecipeResult => ({ ok: false, code, reason });
+const ids = (xs: { id: string }[]): string[] => xs.map((x) => x.id);
+
+function sourceFiles(repo: string, depth = 0, out: string[] = []): string[] {
+  if (depth > 6) return out;
+  for (const n of readdirSync(repo).sort(cmp)) {
+    if (n === 'node_modules' || n === '.git' || n === '.hullproof') continue;
+    const p = join(repo, n);
+    const st = lstatSync(p);
+    if (st.isSymbolicLink()) continue;
+    if (st.isDirectory()) sourceFiles(p, depth + 1, out);
+    else if (/\.(?:[cm]?js|ts)$/.test(n) && st.size < 1_000_000) out.push(p);
+  }
+  return out;
+}
+
+// The port the app listens on: a number in listen(), or the number after process.env.PORT. Returns null when no listen() call is found.
+export function detectPort(text: string): { port: number; fromEnv: boolean } | null {
+  const m = /\.listen\(\s*([^,)\n]+)/.exec(text);
+  if (!m) return null;
+  let expr = m[1].trim();
+  if (/^[A-Za-z_$][\w$]*$/.test(expr)) {
+    const d = new RegExp(`(?:const|let|var)\\s+${expr}\\s*=\\s*([^;\\n]+)`).exec(text);
+    if (d) expr = d[1];
+  }
+  const fromEnv = /process\.env\.PORT|process\.env\[\s*['"]PORT['"]\s*\]/.test(expr);
+  const n = /\b(\d{2,5})\b/.exec(expr.replace(/process\.env\.PORT/g, ''));
+  if (n && Number(n[1]) <= 65535) return { port: Number(n[1]), fromEnv };
+  return fromEnv ? { port: 3000, fromEnv } : null;
+}
+
+export function deriveRecipe(repo: string, stack: Stack, map: CodeMap, opts: { allowInstallScripts?: boolean } = {}): RecipeResult {
+  const hosted = [...stack.data_stores.filter((i) => HOSTED_DATA.has(i.id)), ...stack.auth.filter((i) => HOSTED_AUTH.has(i.id))];
+  if (hosted.length) return no('hosted_service', `the app uses ${hosted.map((i) => nice(i.id)).join(' and ')}, a hosted service that cannot run locally and has no local stand in in this version. It is not faked.`);
+  const otherData = stack.data_stores.filter((i) => !LOCAL_DATA.has(i.id));
+  if (otherData.length) return no('unsupported_datastore', `the app uses ${otherData.map((i) => nice(i.id)).join(' and ')}. Only a local SQLite file and an ephemeral Postgres are supported.`);
+  const fw = ids(stack.frameworks);
+  if (!fw.includes('express') && fw.includes('flask')) return deriveFlask(repo, stack, map, opts);
+  if (!fw.includes('express')) return no('unsupported_stack', `the proof sandbox has a recipe for Node on Express and for Python on Flask in this version${fw.length ? ` (found ${fw.slice(0, 4).join(', ')})` : ''}.`);
+  if (fw.includes('nextjs')) return no('unsupported_stack', 'the app also uses Next.js, which needs a production build step that this version has no recipe for.');
+  const pjPath = join(repo, 'package.json');
+  if (!existsSync(pjPath)) return no('no_package_json', 'there is no package.json at the repository root.');
+  let pj: { main?: string; scripts?: Record<string, string>; dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+  try { pj = JSON.parse(readFileSync(pjPath, 'utf8')); } catch { return no('no_package_json', 'package.json cannot be read as JSON.'); }
+  const deps = { ...(pj.dependencies ?? {}), ...(pj.devDependencies ?? {}) };
+  const notes: string[] = [];
+
+  // Build phase: a lockfile install without install scripts, or nothing at all when the repository carries its own modules.
+  const hasDeps = Object.keys(deps).length > 0;
+  const native = NATIVE.filter((n) => n in deps);
+  let install: string[] | null = null;
+  let vendored = false;
+  if (hasDeps) {
+    if (native.length && !opts.allowInstallScripts) return no('needs_install_scripts', `${native.join(', ')} needs an install script to build or download a native part, and the sandbox installs without install scripts so none can run. Pass --allow-install-scripts to let them run in the build container.`);
+    if (!existsSync(join(repo, 'package-lock.json'))) return no('no_lockfile', `there is no package-lock.json${existsSync(join(repo, 'yarn.lock')) || existsSync(join(repo, 'pnpm-lock.yaml')) ? ' (only npm lockfiles are installed in this version)' : ''}, and the sandbox installs from a lockfile only.`);
+    install = ['npm', 'ci', ...(opts.allowInstallScripts ? [] : ['--ignore-scripts']), '--no-audit', '--no-fund', '--registry=https://registry.npmjs.org/'];
+    if (opts.allowInstallScripts) notes.push('install scripts run inside the build container, which has network access to the package registry');
+  } else if (existsSync(join(repo, 'node_modules'))) { vendored = true; notes.push('the repository carries its own node_modules and has no dependencies to install, so the build phase needs no network'); }
+
+  const start = pj.scripts?.start ? 'npm start' : pj.main && existsSync(join(repo, pj.main)) ? `node ${pj.main}` : ['server.js', 'index.js', 'app.js', 'src/server.js', 'src/index.js'].find((f) => existsSync(join(repo, f))) ? `node ${['server.js', 'index.js', 'app.js', 'src/server.js', 'src/index.js'].find((f) => existsSync(join(repo, f)))}` : null;
+  if (!start) return no('no_start_command', 'there is no start script, no main file and no server.js, index.js or app.js.');
+
+  let port: { port: number; fromEnv: boolean } | null = null;
+  for (const f of sourceFiles(repo)) { port = detectPort(readFileSync(f, 'utf8')); if (port) break; }
+  if (!port) return no('port_unknown', 'no listen() call with a port was found in the source.');
+
+  const names = envNames(repo);
+  const env: Record<string, string> = {};
+  if (port.fromEnv) env.PORT = String(port.port);
+  const sqliteUsed = stack.data_stores.some((i) => i.id === 'sqlite') || sourceFiles(repo).some((f) => /node:sqlite|better-sqlite3|require\(['"]sqlite3['"]\)/.test(readFileSync(f, 'utf8')));
+  const pgUsed = stack.data_stores.some((i) => i.id === 'postgres');
+  let data: Recipe['data_store'] = { kind: 'none' };
+  if (pgUsed && !sqliteUsed) {
+    const url = names.find((n) => n === 'DATABASE_URL' || n === 'POSTGRES_URL');
+    if (!url) return no('unsupported_datastore', 'the app uses Postgres but does not read DATABASE_URL or POSTGRES_URL, so the sandbox cannot point it at its own database.');
+    const sqlIn = (d: string): string[] => (existsSync(join(repo, d)) ? readdirSync(join(repo, d)).filter((f) => f.endsWith('.sql')).sort(cmp).map((f) => `${d}/${f}`) : []);
+    const migrations = [...sqlIn('migrations'), ...sqlIn('db/migrations')];
+    const seedSql = ['seed.sql', 'db/seed.sql'].find((f) => existsSync(join(repo, f))) ?? null;
+    if (!migrations.length && !seedSql) return no('no_seed', 'the app uses Postgres and the repository has no migrations folder or seed.sql to build the schema and data from.');
+    data = { kind: 'postgres', migrations, seed_sql: seedSql };
+    env[url] = '{PGURL}';
+    notes.push('Postgres runs as a second container on an internal network with no route out');
+  } else if (sqliteUsed) {
+    const dbVars = names.filter((n) => DB_VARS.test(n));
+    if (!dbVars.length) return no('db_path_hardcoded', 'the app uses SQLite but does not read its file path from an environment variable (DATABASE_URL, DB_PATH, SQLITE_PATH and similar). The sandbox root filesystem is read only, so a path written into the code cannot be redirected to a writable place.');
+    for (const v of dbVars) env[v] = v.endsWith('_URL') ? 'file:{DATA}/app.db' : '{DATA}/app.db';
+    data = { kind: 'sqlite', env: dbVars };
+  }
+  for (const n of names) if (!(n in env) && n !== 'PORT') env[n] = dummyValue(n);
+
+  let seed: string | null = null;
+  if (pj.scripts?.seed) seed = 'npm run seed';
+  else {
+    const f = ['seed.js', 'db/seed.js', 'scripts/seed.js', 'seed.mjs'].find((x) => existsSync(join(repo, x)));
+    if (f) seed = `node ${f}`;
+    else notes.push('no seed step found; the specs rely on data the app creates itself');
+  }
+  const gets = new Set(map.entry_points.filter((e) => e.kind === 'http_route' && e.method === 'GET' && e.path).map((e) => e.path!));
+  const health = HEALTH.find((h) => gets.has(h)) ?? '/';
+  if (health === '/' && !gets.has('/')) notes.push('no health route found; the app counts as up when it answers any request with a status below 500');
+
+  return { ok: true, recipe: { schema_version: '1.0.0', stack: 'node-express', base_image: BASE_IMAGE, ...(opts.allowInstallScripts && install ? { install_scripts: true } : {}), install, vendored_modules: vendored, seed, start, port: port.port, port_from_env: port.fromEnv, health_path: health, data_store: data, env: Object.fromEntries(Object.entries(env).sort(([a], [b]) => cmp(a, b))), notes } };
+}
+
+// ---- Python on Flask (Phase 6d) ---------------------------------------------------------------------------------------------------------
+function pyFiles(repo: string, depth = 0, out: string[] = []): string[] {
+  if (depth > 6) return out;
+  for (const n of readdirSync(repo).sort(cmp)) {
+    if (['node_modules', '.git', '.hullproof', '__pycache__', '.venv', 'venv'].includes(n)) continue;
+    const p = join(repo, n);
+    const st = lstatSync(p);
+    if (st.isSymbolicLink()) continue;
+    if (st.isDirectory()) pyFiles(p, depth + 1, out);
+    else if (n.endsWith('.py') && st.size < 1_000_000) out.push(p);
+  }
+  return out;
+}
+
+// The port a Flask app listens on: app.run(port=...) with a number, or int(os.environ.get("PORT", "5000")). The flask command defaults to 5000.
+export function detectPyPort(text: string): { port: number; fromEnv: boolean } | null {
+  const run = /\.run\s*\(/.exec(text);
+  if (!run) return null;
+  // The text of the argument list, up to the bracket that closes it.
+  let depth = 1;
+  let i = run.index + run[0].length;
+  const from = i;
+  for (; i < text.length && depth > 0; i++) { if (text[i] === '(') depth++; else if (text[i] === ')') depth--; }
+  const args = text.slice(from, i - 1);
+  const at = /\bport\s*=\s*/.exec(args);
+  if (!at) return { port: 5000, fromEnv: false };
+  let d = 0;
+  let k = at.index + at[0].length;
+  const start = k;
+  for (; k < args.length; k++) { if (args[k] === '(') d++; else if (args[k] === ')') d--; else if (args[k] === ',' && d === 0) break; }
+  const expr = args.slice(start, k);
+  const fromEnv = /os\.environ|getenv/.test(expr) && /PORT/.test(expr);
+  const n = /(\d{2,5})/.exec(expr.replace(/PORT/g, ''));
+  if (n && Number(n[1]) <= 65535) return { port: Number(n[1]), fromEnv };
+  return fromEnv ? { port: 5000, fromEnv } : null;
+}
+
+function deriveFlask(repo: string, stack: Stack, map: CodeMap, opts: { allowInstallScripts?: boolean }): RecipeResult {
+  const files = pyFiles(repo);
+  const text = new Map(files.map((f) => [f, readFileSync(f, 'utf8')]));
+  const notes: string[] = [];
+  const reqPath = join(repo, 'requirements.txt');
+  if (!existsSync(reqPath)) return no('no_lockfile', 'there is no requirements.txt, and the sandbox installs from pinned requirements only (Pipfile, Poetry and uv are not read in this version).');
+  const lines = readFileSync(reqPath, 'utf8').split(/\r?\n/).map((l) => l.replace(/\s+#.*$/, '').trim()).filter((l) => l && !l.startsWith('#'));
+  const loose = lines.filter((l) => !/^[A-Za-z0-9_.\[\]-]+\s*==\s*[\w.!+*-]+(?:\s*;.*)?(?:\s+--hash=.*)?$/.test(l) && !/^--hash=/.test(l));
+  if (loose.length) return no('no_lockfile', `requirements.txt has lines that are not pinned with == (${loose.slice(0, 3).join(', ')}), and the sandbox installs from pinned requirements only.`);
+  if (lines.some((l) => /^(?:-e|git\+|https?:|\.\/|\/|--(?:index-url|extra-index-url|find-links))/.test(l))) return no('no_lockfile', 'requirements.txt points at a source other than the package index, and the sandbox installs from the index only.');
+
+  const sqlite = stack.data_stores.some((i) => i.id === 'sqlite') || [...text.values()].some((t) => /\bimport\s+(?:[\w.]+\s*,\s*)*sqlite3\b|\bfrom\s+sqlite3\b/.test(t));
+  const otherDb = lines.some((l) => /^(?:psycopg2?|psycopg|pymysql|mysqlclient|pymongo|redis|sqlalchemy|django)\b/i.test(l));
+  if (otherDb && !sqlite) return no('unsupported_datastore', 'the app uses a database package other than the built in sqlite3. Only a local SQLite file is supported for Python in this version.');
+  const names = envNames(repo);
+  const dbVars = names.filter((n) => DB_VARS.test(n));
+  if (sqlite && !dbVars.length) return no('db_path_hardcoded', 'the app uses SQLite but does not read its file path from an environment variable (DATABASE_URL, DB_PATH, SQLITE_PATH and similar). The sandbox root filesystem is read only, so a path written into the code cannot be redirected to a writable place.');
+  if (!sqlite) notes.push('no data store was found; the app starts with no database');
+
+  const appFile = files.find((f) => /\bFlask\s*\(\s*__name__/.test(text.get(f)!));
+  if (!appFile) return no('no_start_command', 'no file creates the app with Flask(__name__).');
+  const rel = (f: string): string => f.slice(repo.length + 1);
+  const runner = files.find((f) => /if\s+__name__\s*==\s*['"]__main__['"]/.test(text.get(f)!) && /\.run\s*\(/.test(text.get(f)!) && (f === appFile || /from\s+\w+\s+import|import\s+\w+/.test(text.get(f)!)));
+  let start: string;
+  let port: { port: number; fromEnv: boolean };
+  if (runner) {
+    const pt = detectPyPort(text.get(runner)!);
+    if (!pt) return no('port_unknown', 'app.run() is called but its port could not be read.');
+    port = pt;
+    start = `python ${rel(runner)}`;
+  } else {
+    const mod = rel(appFile).replace(/\.py$/, '').replace(/\//g, '.');
+    port = { port: 5000, fromEnv: false };
+    start = `python -m flask --app ${mod} run --host 127.0.0.1 --port 5000`;
+    notes.push('the app has no app.run() under __main__, so it starts with the flask command on port 5000');
+  }
+  const env: Record<string, string> = {};
+  if (port.fromEnv) env.PORT = String(port.port);
+  for (const v of dbVars) env[v] = v.endsWith('_URL') ? 'file:{DATA}/app.db' : '{DATA}/app.db';
+  for (const n of names) if (!(n in env) && n !== 'PORT') env[n] = dummyValue(n);
+  const seedFile = ['seed.py', 'db/seed.py', 'scripts/seed.py', 'init_db.py', 'db/init_db.py'].find((x) => existsSync(join(repo, x)));
+  if (!seedFile) notes.push('no seed step found; the specs rely on data the app creates itself');
+  const gets = new Set(map.entry_points.filter((e) => e.kind === 'http_route' && e.method === 'GET' && e.path).map((e) => e.path!));
+  const health = HEALTH.find((h) => gets.has(h)) ?? '/';
+  if (health === '/' && !gets.has('/')) notes.push('no health route found; the app counts as up when it answers any request with a status below 500');
+  const install = ['pip', 'install', '--no-cache-dir', ...(opts.allowInstallScripts ? [] : ['--only-binary=:all:']), '--disable-pip-version-check', '-r', 'requirements.txt'];
+  if (opts.allowInstallScripts) notes.push('a package with no wheel builds from source inside the build container, which has network access to the package index');
+  else notes.push('packages install from wheels only, so no package build script runs; a package that has no wheel makes the app not provable here');
+  notes.push('requirements are pinned by version; the sandbox does not check package hashes');
+  return { ok: true, recipe: { schema_version: '1.0.0', stack: 'python-flask', base_image: PYTHON_IMAGE, ...(opts.allowInstallScripts ? { install_scripts: true } : {}), install, vendored_modules: false, seed: seedFile ? `python ${seedFile}` : null, start, port: port.port, port_from_env: port.fromEnv, health_path: health, data_store: sqlite ? { kind: 'sqlite', env: dbVars } : { kind: 'none' }, env: Object.fromEntries(Object.entries(env).sort(([a], [b]) => cmp(a, b))), notes } };
+}
+
+export const recipeSha256 = (r: Recipe): string => sha256(canon(r));

package/src/prove/run.ts

@@ -0,0 +1,124 @@
+// The proof run: for each spec, start the app in a fresh sandbox, run the spec, tear down, three times; then build result.json from
+// the saved run files. Building the result is one pure function, used by the live run and by the replay, so a replay of the saved
+// transcripts gives the same bytes with no sandbox. Nothing here decides a verdict by itself: the verdict function is judge()
+// in executor.ts and it reads only the stored transcript.
+import type { CodeMap, NotProvable, ProveMeta, ProveResult, ProveRunSummary, ProveSpecResult, Recipe, RunOutcome, RunRecord, Spec, SpecOutcome, Stack } from '../types/index.ts';
+import { ENGINE_VERSION } from '../version.ts';
+import { cmp } from '../util.ts';
+import { judge, runRecord } from './executor.ts';
+import { deriveRecipe, recipeSha256 } from './recipe.ts';
+import { makeSandboxCopy } from './safety.ts';
+import { DEFAULT_LIMITS, type Limits, type Runner } from './runner.ts';
+import { canon, sha256, specSha256 } from './spec.ts';
+import { clearRuns, loadSpecs, readMeta, readRuns, writeMeta, writeProveResult, writeRecipe, writeRun } from './store.ts';
+
+export const RUNS_REQUIRED = 3;
+
+function verifyRun(spec: Spec, specSha: string, rr: RunRecord): ProveRunSummary {
+  const bad = (detail: string): ProveRunSummary => ({ run: rr.run, outcome: 'error', transcript_sha256: rr.transcript_sha256, detail });
+  if (rr.spec_sha256 !== specSha) return bad('the spec changed after this run, so its transcript no longer belongs to it');
+  const { transcript_sha256: _h, ...body } = rr;
+  if (sha256(canon(body)) !== rr.transcript_sha256) return bad('the stored transcript does not match its hash; it was changed after the run');
+  if (!rr.steps.length) return rr.outcome === 'error' ? { run: rr.run, outcome: 'error', transcript_sha256: rr.transcript_sha256, detail: rr.detail } : bad('a run with no steps can only be an error');
+  const j = judge(spec, rr.steps);
+  if (!j.done || !j.outcome) return bad('the stored transcript stops before the spec reaches a verdict');
+  if (j.outcome !== rr.outcome) return bad(`the stored outcome (${rr.outcome}) does not match what the transcript shows (${j.outcome})`);
+  return { run: rr.run, outcome: j.outcome, transcript_sha256: rr.transcript_sha256, detail: j.detail };
+}
+
+function combine(runs: ProveRunSummary[], required: number): { outcome: SpecOutcome; reason: string } {
+  if (runs.length < required) return { outcome: 'error', reason: `${runs.length} of ${required} runs finished, so nothing is proven` };
+  const set = new Set<RunOutcome>(runs.map((r) => r.outcome));
+  if (set.size > 1) return { outcome: 'unstable', reason: `the runs disagreed (${runs.map((r) => r.outcome).join(', ')}), so the lead stays a lead` };
+  const o = runs[0].outcome;
+  return { outcome: o, reason: o === 'proven' ? `${required} of ${required} runs: the positive control passed and the flaw showed` : runs[0].detail };
+}
+
+export function buildResult(meta: ProveMeta, specs: Spec[], dropped: { file: string; reason: string }[], runsOf: (id: string) => RunRecord[]): ProveResult {
+  const out: ProveSpecResult[] = [];
+  for (const s of specs.slice().sort((a, b) => cmp(a.spec_id, b.spec_id))) {
+    const sha = specSha256(s);
+    const base = { spec_id: s.spec_id, spec_sha256: sha, lead_key: s.lead_key, title: s.title, claim: s.claim, entry_point: s.target.entry_point, requirement_ids: s.requirement_ids, sink: { file: s.target.file, line: s.target.line } };
+    if (meta.not_provable) { out.push({ ...base, outcome: 'not_provable', reason: `not provable here (${meta.not_provable.code}): ${meta.not_provable.reason}`, runs: [] }); continue; }
+    const runs = runsOf(s.spec_id).map((r) => verifyRun(s, sha, r));
+    out.push({ ...base, ...combine(runs, meta.runs_required), runs });
+  }
+  const n = (o: SpecOutcome): number => out.filter((x) => x.outcome === o).length;
+  return {
+    schema_version: '1.0.0', engine_version: ENGINE_VERSION, commit: meta.commit, runner: meta.runner, runs_required: meta.runs_required,
+    recipe_sha256: meta.recipe_sha256, not_provable: meta.not_provable, specs: out, dropped, left_behind: meta.left_behind, copy_excluded: meta.copy_excluded,
+    counts: { specs: out.length, proven: n('proven'), not_proven: n('not_proven'), invalid: n('invalid'), unstable: n('unstable'), error: n('error'), not_provable: n('not_provable'), dropped: dropped.length },
+  };
+}
+
+export interface ProveInput {
+  repo: string; proveDir: string; commit: string | null; stack: Stack; map: CodeMap; runner: Runner;
+  runs?: number; limits?: Limits; allowInstallScripts?: boolean; log: (s: string) => void;
+}
+
+const finish = (i: ProveInput, meta: ProveMeta, specs: Spec[], dropped: { file: string; reason: string }[]): ProveResult => {
+  writeMeta(i.proveDir, meta);
+  const r = buildResult(meta, specs, dropped, (id) => readRuns(i.proveDir, id));
+  writeProveResult(i.proveDir, r);
+  return r;
+};
+
+export async function runProve(i: ProveInput): Promise<ProveResult> {
+  const limits = i.limits ?? DEFAULT_LIMITS;
+  const required = i.runs ?? RUNS_REQUIRED;
+  const { specs, dropped } = loadSpecs(i.proveDir);
+  clearRuns(i.proveDir);
+  const meta: ProveMeta = { schema_version: '1.0.0', commit: i.commit, runner: i.runner.name, runs_required: required, recipe_sha256: null, not_provable: null, left_behind: 0, copy_excluded: [] };
+  const stop = (np: NotProvable): ProveResult => finish(i, { ...meta, not_provable: np }, specs, dropped);
+  if (!specs.length) { i.log('hullproof prove: no valid specs to run'); return finish(i, meta, specs, dropped); }
+
+  const rec = deriveRecipe(i.repo, i.stack, i.map, { allowInstallScripts: i.allowInstallScripts });
+  if (!rec.ok) return stop({ code: rec.code, reason: rec.reason });
+  const recipe: Recipe = rec.recipe;
+  meta.recipe_sha256 = recipeSha256(recipe);
+  writeRecipe(i.proveDir, recipe);
+  const av = await i.runner.available();
+  if (!av.ok) return stop({ code: 'no_runtime', reason: av.reason });
+  const copy = makeSandboxCopy(i.repo, { keepNodeModules: recipe.vendored_modules });
+  if ('error' in copy) return stop({ code: 'too_large', reason: copy.error });
+  meta.copy_excluded = copy.excluded;
+  let notProvable: NotProvable | null = null;
+  let leftBehind = 0;
+  try {
+    i.log(`hullproof prove: ${i.runner.name}, ${copy.files} files copied, ${copy.excluded.length} left out, preparing the image`);
+    const prep = await i.runner.prepare({ recipe, copyDir: copy.dir, sourceDir: i.repo, limits });
+    if (!prep.ok) { notProvable = { code: prep.code, reason: prep.reason }; }
+    else {
+      try {
+        outer: for (const spec of specs) {
+          const sha = specSha256(spec);
+          for (let run = 1; run <= required; run++) {
+            const st = await prep.prepared.start();
+            if (!st.ok) { notProvable = { code: st.code, reason: st.reason }; break outer; }
+            try {
+              const r = await st.instance.runSpec(spec);
+              const body = r.ok ? { outcome: r.outcome, detail: r.detail, steps: r.steps } : { outcome: 'error' as const, detail: r.reason, steps: [] };
+              writeRun(i.proveDir, runRecord(spec, sha, run, body));
+              i.log(`hullproof prove: ${spec.spec_id} run ${run}/${required}: ${body.outcome}`);
+            } finally { leftBehind += (await st.instance.stop()).left_behind.length; }
+          }
+        }
+      } finally {
+        const t = await prep.prepared.dispose();
+        leftBehind += t.left_behind.length;
+        if (t.left_behind.length) i.log(`hullproof prove: WARNING: left behind after teardown: ${t.left_behind.join(', ')}`);
+      }
+    }
+  } finally { copy.cleanup(); }
+  return finish(i, { ...meta, not_provable: notProvable, left_behind: leftBehind }, specs, dropped);
+}
+
+// Rebuilds result.json from the saved specs and run files. No sandbox, no app, no model.
+export function replayProve(proveDir: string): ProveResult | string {
+  const meta = readMeta(proveDir);
+  if (!meta) return `no saved proof run in ${proveDir}`;
+  const { specs, dropped } = loadSpecs(proveDir);
+  const r = buildResult(meta, specs, dropped, (id) => readRuns(proveDir, id));
+  writeProveResult(proveDir, r);
+  return r;
+}

package/src/prove/runner.ts

@@ -0,0 +1,28 @@
+// The runner interface of the proof sandbox. One backend is a container runtime (container.ts). The other, a plain local process
+// (local.ts), is labelled unsafe and exists only for the engine's own fixtures. The prove step knows only this interface.
+import type { NotProvableCode, Recipe, Spec, StepRecord } from '../types/index.ts';
+import type { RunOutcome } from '../types/prove.ts';
+
+export interface Limits { memory: string; cpus: string; pids: number; instanceMs: number; execMs: number; healthMs: number }
+export const DEFAULT_LIMITS: Limits = { memory: '512m', cpus: '1', pids: 128, instanceMs: 180_000, execMs: 60_000, healthMs: 30_000 };
+
+export interface Exec { code: number | null; stdout: string; stderr: string; timedOut: boolean }
+export interface Teardown { left_behind: string[] }
+export type SpecRun = { ok: true; outcome: RunOutcome; detail: string; steps: StepRecord[] } | { ok: false; reason: string };
+
+export interface Instance {
+  readonly baseUrl: string;
+  exec(cmd: string[], o?: { input?: string; timeoutMs?: number }): Promise<Exec>;   // inside the sandbox, with the same limits as the app
+  runSpec(spec: Spec): Promise<SpecRun>;                                              // the step executor, inside the sandbox
+  stop(): Promise<Teardown>;
+}
+export type StartResult = { ok: true; instance: Instance } | { ok: false; code: NotProvableCode; reason: string };
+export interface Prepared { start(): Promise<StartResult>; dispose(): Promise<Teardown> }
+export type PrepareResult = { ok: true; prepared: Prepared } | { ok: false; code: NotProvableCode; reason: string };
+
+export interface PrepareRequest { recipe: Recipe; copyDir: string; sourceDir: string; limits: Limits }
+export interface Runner {
+  readonly name: string;
+  available(): Promise<{ ok: true } | { ok: false; reason: string }>;
+  prepare(r: PrepareRequest): Promise<PrepareResult>;
+}

package/src/prove/safety.ts

@@ -0,0 +1,98 @@
+// The safety rules of the proof sandbox that do not depend on a container runtime: the typed confirmation, the loopback only
+// target rule, the copy of the repository without secrets, and the dummy environment. Design: docs/PHASE-4-DESIGN.md, safety rules 1 to 3.
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, copyFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { loopbackBase } from './executor.ts';
+
+export const CONFIRM_PHRASE = 'I own this app and approve running it';
+
+// Rule 1: an explicit flag and the exact typed phrase. Nothing else counts: no environment variable, no default, no CI setting.
+export function checkConfirmation(allowRun: boolean, typed: string | null): { ok: true } | { ok: false; reason: string } {
+  if (!allowRun) return { ok: false, reason: 'hullproof prove runs the app, so it needs --allow-run' };
+  if (typed === null) return { ok: false, reason: `hullproof prove needs the owner's typed confirmation: type "${CONFIRM_PHRASE}"` };
+  if (typed.trim() !== CONFIRM_PHRASE) return { ok: false, reason: `the confirmation does not match. Type exactly: ${CONFIRM_PHRASE}` };
+  return { ok: true };
+}
+
+// Rule 2: the only address a request may go to is the sandbox's own loopback on the recipe's port.
+export function assertSandboxTarget(url: string, port: number): void {
+  const u = loopbackBase(url);
+  if (Number(u.port) !== port) throw new Error(`refused: ${u.origin} is not the sandbox app port ${port}`);
+}
+
+// Rule 3: names that never go into the copy. Environment files, keys, credentials, tool folders, git history.
+const SECRET_FILE = /^(?:\.env(?:\..*)?|\.npmrc|\.netrc|\.pypirc|\.git-credentials|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|credentials(?:\..*)?|.*\.(?:pem|key|p12|pfx|jks|keystore|kdbx)|service-account.*\.json|.*secrets?\.(?:json|ya?ml|toml))$/i;
+const SKIP_DIR = new Set(['.git', '.hullproof', '.DS_Store', '.next', '.cache', 'coverage']);
+export const isSecretFile = (name: string): boolean => SECRET_FILE.test(name);
+const MAX_FILE = 10 * 1024 * 1024;
+const MAX_TOTAL = 200 * 1024 * 1024;
+
+export interface SandboxCopy { dir: string; files: number; excluded: string[]; cleanup(): void }
+
+// Copies the repository to a fresh temporary folder, leaving out secrets and (unless the repository vendors its modules) node_modules.
+// Symbolic links are never followed or copied. Returns what was left out so the report can say so.
+export function makeSandboxCopy(repo: string, o: { keepNodeModules: boolean }): SandboxCopy | { error: string } {
+  const root = realpathSync(repo);
+  const dir = mkdtempSync(join(tmpdir(), 'hp-prove-'));
+  const excluded: string[] = [];
+  let files = 0;
+  let total = 0;
+  const walk = (from: string): string | null => {
+    for (const name of readdirSync(from).sort()) {
+      const p = join(from, name);
+      const rel = relative(root, p).split(sep).join('/');
+      const st = lstatSync(p);
+      if (st.isSymbolicLink()) { excluded.push(`${rel} (symbolic link)`); continue; }
+      if (st.isDirectory()) {
+        if (SKIP_DIR.has(name)) continue;
+        if (name === 'node_modules' && !o.keepNodeModules) { excluded.push(`${rel}/ (dependencies are installed in the build phase)`); continue; }
+        mkdirSync(join(dir, rel), { recursive: true });
+        const e = walk(p);
+        if (e) return e;
+        continue;
+      }
+      if (!st.isFile()) continue;
+      if (isSecretFile(name)) { excluded.push(`${rel} (secret file)`); continue; }
+      if (st.size > MAX_FILE) { excluded.push(`${rel} (over 10 MB)`); continue; }
+      total += st.size;
+      if (total > MAX_TOTAL) return 'the repository is over 200 MB, which is too large to copy into a sandbox';
+      mkdirSync(join(dir, rel, '..'), { recursive: true });
+      copyFileSync(p, join(dir, rel));
+      files++;
+    }
+    return null;
+  };
+  const err = walk(root);
+  if (err) { rmSync(dir, { recursive: true, force: true }); return { error: err }; }
+  return { dir, files, excluded: excluded.sort(), cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+// The environment variable names the repository reads: process.env.NAME and process.env['NAME'] in source files, and the names
+// (not the values) in .env.example. A real .env file is never opened.
+const SRC = /\.(?:[cm]?[jt]sx?)$/;
+const PY_SRC = /\.py$/;
+export function envNames(repo: string): string[] {
+  const names = new Set<string>();
+  const walk = (d: string, depth: number): void => {
+    if (depth > 8) return;
+    for (const n of readdirSync(d)) {
+      if (n === 'node_modules' || n === '.git' || n === '.hullproof' || n === '.next' || n === '__pycache__' || n === '.venv' || n === 'venv') continue;
+      const p = join(d, n);
+      const st = lstatSync(p);
+      if (st.isSymbolicLink()) continue;
+      if (st.isDirectory()) walk(p, depth + 1);
+      else if (st.isFile() && st.size < 1_000_000) {
+        if (SRC.test(n)) for (const m of readFileSync(p, 'utf8').matchAll(/process\.env(?:\.([A-Z][A-Z0-9_]*)|\[\s*['"]([A-Z][A-Z0-9_]*)['"]\s*\])/g)) names.add(m[1] ?? m[2]);
+        else if (PY_SRC.test(n)) for (const m of readFileSync(p, 'utf8').matchAll(/os\.(?:environ(?:\.get)?\s*[[(]\s*|getenv\s*\(\s*)['"]([A-Z][A-Z0-9_]*)['"]/g)) names.add(m[1]);
+        else if (n === '.env.example') for (const l of readFileSync(p, 'utf8').split(/\r?\n/)) { const m = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/.exec(l); if (m) names.add(m[1]); }
+      }
+    }
+  };
+  if (existsSync(repo)) walk(repo, 0);
+  return [...names].sort();
+}
+
+// A fixed dummy value per name, so two runs get the same environment. It looks like what it stands for and opens nothing.
+export const dummyValue = (name: string): string => `dummy-${name.toLowerCase().replace(/_/g, '-')}-${createHash('sha256').update(name).digest('hex').slice(0, 8)}`;