@clear-capabilities/agentic-security-scanner 0.153.2 → 0.155.0

package/src/language/nix-closure.js

@@ -0,0 +1,331 @@
+// Resolved derivation and closure inventory (NIX-008).
+//
+// Reads EXPLICITLY SUPPLIED, target-specific exports produced by supported Nix tools; it never runs nix,
+// never discovers an executable and never touches the filesystem (this module imports no fs): store-looking
+// paths are only strings to be validated and related to each other.
+//
+// Supported schemas (all documented in docs/guides/nix.md):
+//   nix-path-info-json       `nix path-info --json --recursive <installable>`: the object form (keys are store
+//                            paths, Nix >= 2.19) and the older array form ([{path, references, deriver, ...}])
+//   nix-derivation-show-json `nix derivation show --recursive <installable>`: object keyed by .drv path with
+//                            outputs, inputSrcs, inputDrvs, env; also the wrapped {derivations, version} form
+//                            whose inputs live under inputs.drvs / inputs.srcs and whose paths omit /nix/store/
+//   nix-store-query-text     `nix-store --query --requisites <path>`: one store path per line (OUTPUT-ONLY
+//                            identity: no deriver, hash or version, so it can never support an exact claim)
+//
+// Two different graphs come out and are never conflated: the RUNTIME closure (references of the target's
+// output paths) and the BUILD graph (inputDrvs of its derivation). A node's scopes say which it is in.
+// An exact claim is made only when every condition holds; each failed condition is a disclosure.
+
+import { createHash, createVerify } from 'node:crypto';
+
+export const NIX_CLOSURE_VERSION = 'nix-closure/1';
+export const CLOSURE_BUDGETS = Object.freeze({ maxBytes: 64 * 1024 * 1024, maxNodes: 200_000, maxEdges: 1_000_000, maxEnvBytes: 1 << 20, maxExports: 16 });
+const SUPPORTED_TOOLS = new Set(['nix', 'nix-store']);
+const SCHEMA_COMMANDS = {
+  'nix-path-info-json': /^nix(?:\s+--\S+)*\s+path-info\b.*--json\b|^nix(?:\s+--\S+)*\s+path-info\b.*--recursive\b/,
+  'nix-derivation-show-json': /^nix(?:\s+--\S+)*\s+(?:derivation\s+show|show-derivation)\b/,
+  'nix-store-query-text': /^nix-store\b.*(?:--query|-q)\b.*(?:--requisites|-R|--references|--tree)\b|^nix-store\s+-qR\b/,
+};
+const STORE = '/nix/store/';
+const BASE32 = '0123456789abcdfghijklmnpqrsvwxyz';
+const STORE_PATH = new RegExp(`^/nix/store/([${BASE32}]{32})-([^/\\x00\\s]+)$`);
+const OUTPUT_SUFFIX = /-(?:dev|bin|lib|out|man|doc|info|devdoc|debug|static|dist|fakeroot|headers|include|terminfo)$/;
+const ROLE_OF_ENV = [
+  ['nativeCheckInputs', 'test'], ['checkInputs', 'test'], ['installCheckInputs', 'test'],
+  ['nativeBuildInputs', 'build'], ['depsBuildBuild', 'build'], ['depsBuildTarget', 'build'], ['depsBuildBuildPropagated', 'build'], ['propagatedNativeBuildInputs', 'build'],
+  ['buildInputs', 'build+runtime'], ['propagatedBuildInputs', 'build+runtime'], ['depsHostHost', 'build+runtime'], ['depsTargetTarget', 'build+runtime'], ['depsHostHostPropagated', 'build+runtime'],
+];
+
+/** Validate and split a store path. Returns null for anything that is not exactly /nix/store/<hash>-<name>. */
+export function parseStorePath(p) {
+  if (typeof p !== 'string' || p.length > 1024) return null;
+  const m = STORE_PATH.exec(p);
+  if (!m || m[2] === '.' || m[2] === '..' || m[2].includes('..')) return null;
+  return { path: p, hash: m[1], name: m[2] };
+}
+const normalizePath = (p) => (typeof p === 'string' && /^[0-9a-df-np-sv-z]{32}-/.test(p) ? STORE + p : p);
+
+/** Heuristic only: nixpkgs naming is pname-version where the version starts at the first "-<digit>". */
+export function inferNameVersion(name, drvEnv) {
+  if (drvEnv && typeof drvEnv.pname === 'string' && typeof drvEnv.version === 'string') return { pname: drvEnv.pname, version: drvEnv.version, authority: 'derivation-env' };
+  if (drvEnv && typeof drvEnv.name === 'string') { const m = /^(.+?)-(\d.*)$/.exec(drvEnv.name); if (m) return { pname: m[1], version: m[2], authority: 'derivation-env' }; }
+  const base = String(name || '').replace(/\.drv$/, '').replace(OUTPUT_SUFFIX, '');
+  const m = /^(.+?)-(\d.*)$/.exec(base);
+  return m ? { pname: m[1], version: m[2], authority: 'inferred-from-store-path' } : { pname: base || null, version: null, authority: 'inferred-from-store-path' };
+}
+
+export function detectSchema(parsed, text) {
+  if (typeof text === 'string' && parsed === undefined) {
+    const lines = text.split(/\r?\n/).filter(Boolean);
+    return lines.length && lines.every((l) => l.startsWith('/')) ? 'nix-store-query-text' : null;
+  }
+  if (Array.isArray(parsed)) return parsed.every((x) => x && typeof x === 'object' && typeof x.path === 'string') ? 'nix-path-info-json' : null;
+  if (parsed && typeof parsed === 'object') {
+    if (parsed.derivations && typeof parsed.derivations === 'object') return 'nix-derivation-show-json';
+    const ks = Object.keys(parsed);
+    if (!ks.length) return null;
+    if (ks.every((k) => /\.drv$/.test(k))) return 'nix-derivation-show-json';
+    if (ks.every((k) => /^(?:\/nix\/store\/)?[0-9a-df-np-sv-z]{32}-/.test(k))) return 'nix-path-info-json';
+  }
+  return null;
+}
+
+const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+
+/**
+ * @param {{exports: Array<{schema?:string, text?:string, data?:any, provenance?:object, signature?:string}>,
+ *          expected?: {system?:string, installable?:string, revision?:object, flakeLockSha256?:string, maxAgeDays?:number, inputsChangedAtMs?:number, roots?:string[], requireSigned?:boolean, publicKeyPem?:string},
+ *          now?: number, budgets?: object}} opts
+ */
+export function importNixClosure(opts = {}) {
+  const b = { ...CLOSURE_BUDGETS, ...(opts.budgets || {}) };
+  const now = opts.now ?? Date.now();
+  const expected = opts.expected || {};
+  const dis = []; const diag = [];
+  const add = (kind, detail, extra = {}) => dis.push({ kind, detail, ...extra });
+  const out = { version: NIX_CLOSURE_VERSION, status: 'ok', nodes: [], edges: [], disclosures: dis, diagnostics: diag, claims: null, provenance: [], roots: [], coverage: {} };
+  const exps = (opts.exports || []).slice(0, b.maxExports);
+  if ((opts.exports || []).length > b.maxExports) add('truncated', `only the first ${b.maxExports} exports were read`);
+  if (!exps.length) { add('no-export', 'no export was supplied: nothing about the closure is known'); out.status = 'empty'; out.claims = claims(false, false, dis); return out; }
+
+  // ── parse each export ──
+  const pathInfo = new Map();    // path -> {references[], deriver, narHash, narSize, valid}
+  const drvs = new Map();        // drv path -> entry
+  const queryPaths = new Set();
+  const provenance = [];
+  let truncated = false; let malformed = 0;
+
+  for (const [idx, ex] of exps.entries()) {
+    const label = `export[${idx}]`;
+    let parsed; let text = typeof ex.text === 'string' ? ex.text : null;
+    if (text !== null && text.length > b.maxBytes) { add('truncated', `${label} is ${text.length} bytes (limit ${b.maxBytes}); not read`); truncated = true; continue; }
+    if (ex.data !== undefined) parsed = ex.data;
+    else if (text !== null) { try { parsed = JSON.parse(text); } catch { parsed = undefined; } }
+    let schema = ex.schema || detectSchema(parsed, text);
+    if (!schema || !(schema in SCHEMA_COMMANDS)) { diag.push({ export: label, kind: 'unsupported-schema', detail: ex.schema ? `schema ${ex.schema} is not supported` : 'could not recognise the export format' }); malformed++; continue; }
+    const prov = assessProvenance(ex, schema, expected, now, label, add);
+    provenance.push({ export: label, schema, ...prov.summary });
+    if (schema === 'nix-store-query-text') {
+      const lines = String(text !== null ? text : '').split(/\r?\n/).filter(Boolean);
+      for (const l of lines) { const sp = parseStorePath(l.trim()); if (!sp) { diag.push({ export: label, kind: 'invalid-store-path', detail: `not a store path: ${l.slice(0, 80)}` }); malformed++; continue; } if (queryPaths.size < b.maxNodes) queryPaths.add(sp.path); else truncated = true; }
+      continue;
+    }
+    if (schema === 'nix-path-info-json') {
+      const entries = Array.isArray(parsed) ? parsed.map((e) => [e && e.path, e]) : Object.entries(parsed || {});
+      for (const [p, e] of entries) {
+        const sp = parseStorePath(normalizePath(p));
+        if (!sp) { diag.push({ export: label, kind: 'invalid-store-path', detail: `not a store path: ${String(p).slice(0, 80)}` }); malformed++; continue; }
+        if (e === null) { pathInfo.set(sp.path, { references: null, valid: false }); continue; }       // invalid path in the store
+        if (!e || typeof e !== 'object') { diag.push({ export: label, kind: 'malformed-entry', detail: sp.path }); malformed++; continue; }
+        if (pathInfo.size >= b.maxNodes) { truncated = true; break; }
+        const refs = Array.isArray(e.references) ? e.references.map((r) => parseStorePath(normalizePath(r))).filter(Boolean).map((r) => r.path) : null;
+        if (Array.isArray(e.references) && refs.length !== e.references.length) { diag.push({ export: label, kind: 'invalid-store-path', detail: `${sp.path} has reference(s) that are not store paths` }); malformed++; }
+        pathInfo.set(sp.path, { references: refs, deriver: typeof e.deriver === 'string' && e.deriver ? normalizePath(e.deriver) : null, narHash: typeof e.narHash === 'string' ? e.narHash : null, narSize: Number.isFinite(e.narSize) ? e.narSize : null, valid: e.valid !== false, signatures: Array.isArray(e.signatures) ? e.signatures.length : 0 });
+      }
+      continue;
+    }
+    // derivation show
+    const wrapped = parsed && parsed.derivations && typeof parsed.derivations === 'object';
+    const table = wrapped ? parsed.derivations : parsed;
+    for (const [dp0, e] of Object.entries(table || {})) {
+      const dp = normalizePath(dp0);
+      const sp = parseStorePath(dp);
+      if (!sp || !/\.drv$/.test(sp.name)) { diag.push({ export: label, kind: 'invalid-store-path', detail: `not a derivation path: ${String(dp0).slice(0, 80)}` }); malformed++; continue; }
+      if (!e || typeof e !== 'object') { diag.push({ export: label, kind: 'malformed-entry', detail: sp.path }); malformed++; continue; }
+      if (drvs.size >= b.maxNodes) { truncated = true; break; }
+      const outputs = {};
+      if (e.outputs && typeof e.outputs === 'object') for (const [n, o] of Object.entries(e.outputs)) { const p = o && o.path ? parseStorePath(normalizePath(o.path)) : null; outputs[n] = p ? p.path : null; }
+      const inputDrvs = {};
+      const rawIn = wrapped && e.inputs ? (e.inputs.drvs || {}) : (e.inputDrvs || {});
+      for (const [k, v] of Object.entries(rawIn)) { const p = parseStorePath(normalizePath(k)); if (!p) { diag.push({ export: label, kind: 'invalid-store-path', detail: `inputDrv key in ${sp.name}` }); malformed++; continue; } inputDrvs[p.path] = Array.isArray(v) ? v : (v && Array.isArray(v.outputs) ? v.outputs : []); }
+      const rawSrcs = wrapped && e.inputs ? (e.inputs.srcs || []) : (e.inputSrcs || []);
+      const inputSrcs = (Array.isArray(rawSrcs) ? rawSrcs : []).map((s) => parseStorePath(normalizePath(s))).filter(Boolean).map((s) => s.path);
+      let env = e.env && typeof e.env === 'object' ? e.env : null;
+      if (env && JSON.stringify(env).length > b.maxEnvBytes) { env = null; diag.push({ export: label, kind: 'env-too-large', detail: sp.name }); }
+      drvs.set(sp.path, { outputs, inputDrvs, inputSrcs, system: typeof e.system === 'string' ? e.system : null, builder: typeof e.builder === 'string' ? e.builder : null, env });
+    }
+  }
+  out.provenance = provenance;
+  if (truncated) { add('truncated', `an export exceeded the node budget (${b.maxNodes}) or size limit; the inventory is partial`); }
+  if (malformed) add('malformed', `${malformed} entr${malformed === 1 ? 'y' : 'ies'} could not be used (see diagnostics)`);
+
+  // ── node table ──
+  const nodes = new Map();
+  const node = (id, kind) => { if (!nodes.has(id)) { const sp = parseStorePath(id); nodes.set(id, { id, kind, hash: sp ? sp.hash : null, storeName: sp ? sp.name : null, scopes: new Set(), outputs: [], system: null, identity: null, pname: null, version: null, versionAuthority: null, deriver: null, narHash: null, patches: [], sources: [], missing: [], roles: new Set(), group: null }); } return nodes.get(id); };
+  const outputOwner = new Map();   // output path -> {drv, outputName}
+  for (const [dp, d] of drvs) { for (const [n, p] of Object.entries(d.outputs)) if (p) outputOwner.set(p, { drv: dp, output: n }); }
+  const edges = [];
+  const edgeKeys = new Set();
+  const addEdge = (from, to, kind, role) => { const k = `${from}\u0000${to}\u0000${kind}`; if (edgeKeys.has(k)) return; if (edges.length >= b.maxEdges) { truncated = true; return; } edgeKeys.add(k); edges.push({ from, to, kind, ...(role ? { role } : {}) }); };
+
+  for (const [p, info] of pathInfo) {
+    const n = node(p, 'output');
+    n.narHash = info.narHash || null; n.deriver = info.deriver || null;
+    if (info.references === null && info.valid !== false) n.missing.push('references');
+    if (!info.narHash) n.missing.push('narHash');
+    if (!info.deriver) n.missing.push('deriver');
+    if (info.references) for (const r of info.references) if (r !== p) addEdge(p, r, 'reference', null);
+  }
+  for (const p of queryPaths) { const n = node(p, 'output'); n.queryOnly = !pathInfo.has(p); }
+  for (const [dp, d] of drvs) {
+    const n = node(dp, 'derivation');
+    n.system = d.system; n.outputs = Object.entries(d.outputs).map(([name, path]) => ({ name, path })); n.sources = d.inputSrcs;
+    const nv = inferNameVersion(n.storeName, d.env);
+    n.pname = nv.pname; n.version = nv.version; n.versionAuthority = nv.authority; n.identity = d.env ? 'derivation-env' : 'drv-path-only';
+    if (!d.env) n.missing.push('env');
+    if (d.env && typeof d.env.patches === 'string') n.patches = d.env.patches.split(/\s+/).filter(Boolean).map((x) => { const sp = parseStorePath(x); return sp ? { path: sp.path, name: sp.name } : null; }).filter(Boolean).map((x) => ({ path: x.path, name: x.name || x.path }));
+    if (d.env && typeof d.env.urls === 'string') n.upstreamUrls = d.env.urls.split(/\s+/).filter(Boolean).slice(0, 8);
+    if (d.env && typeof d.env.rev === 'string') n.upstreamRev = d.env.rev;
+    // role of each input derivation, from the environment lists that name its output paths
+    const rolesFor = (outPaths) => {
+      const roles = new Set();
+      if (!d.env) return roles;
+      for (const [key, role] of ROLE_OF_ENV) { const v = d.env[key]; if (typeof v !== 'string') continue; const set = new Set(v.split(/\s+/)); if (outPaths.some((p) => set.has(p))) roles.add(role); }
+      return roles;
+    };
+    for (const [ip, outs] of Object.entries(d.inputDrvs)) {
+      const callee = drvs.get(ip);
+      const outPaths = callee ? Object.values(callee.outputs).filter(Boolean) : [];
+      const roles = rolesFor(outPaths);
+      const role = roles.size ? [...roles].sort().join('|') : 'build';
+      node(ip, 'derivation');
+      addEdge(dp, ip, 'input-drv', role);
+      const e = edges.find((x) => x.from === dp && x.to === ip && x.kind === 'input-drv'); if (e) e.outputsUsed = outs;
+    }
+    for (const s of d.inputSrcs) { const sn = node(s, 'source'); addEdge(dp, s, 'input-src', 'source'); sn.scopes.add('source'); }
+    // link derivation <-> outputs
+    for (const [name, op] of Object.entries(d.outputs)) if (op) { const on = node(op, 'output'); on.deriver = on.deriver || dp; on.outputName = name; addEdge(op, dp, 'deriver', null); }
+  }
+  for (const n of nodes.values()) {
+    if (n.kind === 'output') {
+      const owner = outputOwner.get(n.id) || (n.deriver && drvs.has(n.deriver) ? { drv: n.deriver } : null);
+      const d = owner ? drvs.get(owner.drv) : null;
+      if (d) { const nv = inferNameVersion(n.storeName, d.env); n.pname = nv.pname; n.version = nv.version; n.versionAuthority = nv.authority; n.identity = d.env ? 'derivation-env' : 'drv-path-only'; n.system = d.system; n.outputName = owner.output || n.outputName; n.patches = (nodes.get(owner.drv) || {}).patches || []; n.upstreamUrls = (nodes.get(owner.drv) || {}).upstreamUrls; n.upstreamRev = (nodes.get(owner.drv) || {}).upstreamRev; }
+      else { const nv = inferNameVersion(n.storeName, null); n.pname = nv.pname; n.version = nv.version; n.versionAuthority = 'inferred-from-store-path'; n.identity = 'output-only'; }
+    }
+  }
+
+  // ── roots and scopes ──
+  let roots = (expected.roots || []).map((r) => parseStorePath(r)).filter(Boolean).map((r) => r.path);
+  const fromExpected = roots.length > 0;
+  if (!roots.length && pathInfo.size) {
+    const referenced = new Set();
+    for (const [p, info] of pathInfo) for (const r of info.references || []) if (r !== p) referenced.add(r);
+    roots = [...pathInfo.keys()].filter((p) => !referenced.has(p));
+  }
+  if (!roots.length && queryPaths.size === 1) roots = [...queryPaths];
+  const rootDrvs = [];
+  for (const r of roots) { const n = nodes.get(r); if (n && n.deriver && drvs.has(n.deriver)) rootDrvs.push(n.deriver); }
+  if (roots.length > 1 && !fromExpected) add('ambiguous-root', `${roots.length} paths are not referenced by any other: the target cannot be identified without expected.roots`);
+  if (!roots.length) add('no-root', 'no root path could be determined: scopes are not assigned');
+  out.roots = roots;
+  // runtime closure
+  const runtime = new Set(); const rq = [...roots.filter((r) => nodes.has(r))];
+  for (const r of rq) runtime.add(r);
+  while (rq.length) { const u = rq.shift(); for (const e of edges) if (e.from === u && e.kind === 'reference' && !runtime.has(e.to)) { runtime.add(e.to); rq.push(e.to); } }
+  for (const id of runtime) nodes.get(id).scopes.add('runtime');
+  // build graph (from the root derivations)
+  const buildSeen = new Map(); const bq = [];
+  for (const rd of rootDrvs) { buildSeen.set(rd, new Set(['target'])); bq.push(rd); }
+  while (bq.length) {
+    const u = bq.shift();
+    for (const e of edges) if (e.from === u && e.kind === 'input-drv') {
+      const roles = new Set(String(e.role || 'build').split('|'));
+      const cur = buildSeen.get(e.to) || new Set();
+      const before = cur.size;
+      for (const r of roles) cur.add(r);
+      // roles propagate: a build-only tool's own inputs are build inputs of the target
+      if (!buildSeen.has(e.to) || cur.size !== before) { buildSeen.set(e.to, cur); bq.push(e.to); }
+    }
+  }
+  for (const [id, roles] of buildSeen) {
+    const n = nodes.get(id); if (!n) continue;
+    n.scopes.add('build');
+    if ([...roles].every((r) => r === 'test' || r === 'target')) { if (roles.has('test')) n.scopes.add('test'); }
+    for (const r of roles) if (r !== 'target') n.roles.add(r);
+  }
+  // output nodes inherit the build/test scope of their derivation when they were not found in the runtime closure
+  for (const n of nodes.values()) if (n.kind === 'output') { const owner = outputOwner.get(n.id); if (owner && buildSeen.has(owner.drv)) { const roles = buildSeen.get(owner.drv); n.scopes.add('build'); if (!n.scopes.has('runtime')) for (const r of roles) if (r !== 'target') n.roles.add(r); if ([...roles].every((r) => r === 'test' || r === 'target') && roles.has('test')) n.scopes.add('test'); } }
+
+  // same-name different-build groups
+  // distinct BUILDS: outputs of one derivation (out, dev, ...) are one build; different derivations are different builds
+  const groups = new Map();
+  for (const n of nodes.values()) if (n.kind === 'output' && n.pname) { const k = `${n.pname}@${n.version || '?'}`; if (!groups.has(k)) groups.set(k, new Set()); groups.get(k).add((outputOwner.get(n.id) || {}).drv || n.deriver || n.hash); }
+  for (const n of nodes.values()) if (n.kind === 'output' && n.pname) { const k = `${n.pname}@${n.version || '?'}`; const g = groups.get(k); n.group = k; n.sameNameDifferentBuild = g.size > 1; }
+
+  // dangling references / inputDrvs make a graph open
+  let openRuntime = false; let openBuild = false;
+  for (const [p, info] of pathInfo) for (const r of info.references || []) if (!pathInfo.has(r) && r !== p) { openRuntime = true; }
+  for (const d of drvs.values()) for (const ip of Object.keys(d.inputDrvs)) if (!drvs.has(ip)) openBuild = true;
+  if (pathInfo.size && openRuntime) add('open-closure', 'some references point at paths that are not in the export: the runtime closure is not closed');
+  if (drvs.size && openBuild) add('open-build-graph', 'some inputDrvs are not described in the export: the build graph is not closed');
+  for (const n of nodes.values()) if (n.kind === 'output' && n.identity === 'output-only') { if (!dis.some((x) => x.kind === 'output-only-identity')) add('output-only-identity', 'some components are known only by their store path: name and version are inferred from the path, not authoritative', { count: 0 }); dis.find((x) => x.kind === 'output-only-identity').count++; }
+  const missingMeta = [...nodes.values()].filter((n) => n.missing.length && n.kind !== 'source');
+  if (missingMeta.length) add('missing-metadata', `${missingMeta.length} node(s) lack metadata (${[...new Set(missingMeta.flatMap((n) => n.missing))].join(', ')})`, { count: missingMeta.length });
+
+  for (const n of nodes.values()) {
+    out.nodes.push({ id: n.id, kind: n.kind, componentClass: n.kind === 'source' ? 'source-dependency' : 'resolved-package', hash: n.hash, storeName: n.storeName, pname: n.pname, version: n.version, versionAuthority: n.versionAuthority, identity: n.identity, outputName: n.outputName || null, outputs: n.outputs, system: n.system, scopes: [...n.scopes].sort(), roles: [...n.roles].sort(), deriver: n.deriver, narHash: n.narHash, patches: n.patches, upstream: n.upstreamUrls || n.upstreamRev ? { urls: n.upstreamUrls || [], rev: n.upstreamRev || null } : null, sameNameDifferentBuild: !!n.sameNameDifferentBuild, group: n.group, missing: n.missing });
+  }
+  out.nodes.sort((a, b) => a.id.localeCompare(b.id));
+  out.edges = edges.sort((a, b) => `${a.from}${a.to}${a.kind}`.localeCompare(`${b.from}${b.to}${b.kind}`));
+  out.coverage = { outputs: out.nodes.filter((n) => n.kind === 'output').length, derivations: out.nodes.filter((n) => n.kind === 'derivation').length, sources: out.nodes.filter((n) => n.kind === 'source').length, edges: out.edges.length, runtimeClosure: runtime.size, buildGraph: buildSeen.size };
+  if (truncated) out.status = 'partial';
+  else if (malformed) out.status = 'partial';
+
+  // ── claims ──
+  const blocking = (kinds) => dis.some((d) => kinds.includes(d.kind));
+  const common = ['foreign-target', 'foreign-revision', 'stale-export', 'unverified-provenance', 'truncated', 'malformed', 'ambiguous-root', 'no-root', 'invalid-signature', 'unsigned'];
+  const exactRuntime = pathInfo.size > 0 && !openRuntime && !blocking([...common, 'output-only-identity']) && [...nodes.values()].filter((n) => n.kind === 'output' && runtime.has(n.id)).every((n) => !n.missing.includes('references'));
+  const exactBuild = drvs.size > 0 && !openBuild && !blocking(common) && [...nodes.values()].filter((n) => n.kind === 'derivation').every((n) => !n.missing.includes('env'));
+  out.claims = claims(exactBuild, exactRuntime, dis);
+  return out;
+}
+
+function claims(exactBuildGraph, exactRuntimeClosure, dis) {
+  return {
+    exactBuildGraph, exactRuntimeClosure, exactInventory: exactBuildGraph && exactRuntimeClosure,
+    completeness: exactBuildGraph || exactRuntimeClosure ? 'complete-for-supplied-target' : 'not-claimed',
+    reasons: dis.filter((d) => !['no-export'].includes(d.kind)).map((d) => d.kind),
+  };
+}
+
+function assessProvenance(ex, schema, expected, now, label, add) {
+  const p = ex.provenance && typeof ex.provenance === 'object' ? ex.provenance : null;
+  const summary = { level: 'none', tool: null, command: null, target: null };
+  if (!p) { add('unverified-provenance', `${label}: no provenance envelope (tool, command, target, flake.lock hash): the export cannot be tied to a target`); return { summary }; }
+  summary.tool = p.tool || null; summary.command = p.command || null; summary.target = p.target || null; summary.toolVersion = p.toolVersion || null; summary.generatedAt = p.generatedAt || null;
+  let level = 'declared';
+  if (!SUPPORTED_TOOLS.has(p.tool)) { add('unverified-provenance', `${label}: tool ${p.tool || '(none)'} is not a supported source for ${schema}`); level = 'none'; }
+  else if (typeof p.command !== 'string' || !SCHEMA_COMMANDS[schema].test(p.command)) { add('unverified-provenance', `${label}: the recorded command does not produce ${schema}`); level = 'none'; }
+  else if (!p.target || typeof p.target !== 'object' || !p.target.system) { add('unverified-provenance', `${label}: provenance names no target system`); level = 'none'; }
+  if (level !== 'none') {
+    const t = p.target || {};
+    if (expected.system && t.system !== expected.system) add('foreign-target', `${label}: export is for system ${t.system}, expected ${expected.system}`);
+    if (expected.installable && t.installable !== expected.installable) add('foreign-target', `${label}: export is for ${t.installable || '(unnamed)'}, expected ${expected.installable}`);
+    for (const [k, v] of Object.entries(expected.revision || {})) { const got = (p.revision || {})[k]; if (got !== v) add('foreign-revision', `${label}: ${k} revision ${got || '(none)'} differs from the expected ${v}`); }
+    if (expected.flakeLockSha256 && p.flakeLockSha256 !== expected.flakeLockSha256) add('stale-export', `${label}: made against a different flake.lock (${String(p.flakeLockSha256 || 'none').slice(0, 12)} vs ${expected.flakeLockSha256.slice(0, 12)})`);
+    const at = Date.parse(p.generatedAt);
+    if (!Number.isFinite(at)) add('stale-export', `${label}: no usable generation time`);
+    else {
+      const maxMs = (expected.maxAgeDays ?? 30) * 86400000;
+      if (now - at > maxMs) add('stale-export', `${label}: generated ${Math.round((now - at) / 86400000)} days ago (limit ${expected.maxAgeDays ?? 30})`);
+      if (Number.isFinite(expected.inputsChangedAtMs) && expected.inputsChangedAtMs > at) add('stale-export', `${label}: the flake inputs changed after this export was generated`);
+    }
+  }
+  // optional attestation
+  if (ex.signature) {
+    try {
+      const body = JSON.stringify({ schema: ex.schema ?? schema, provenance: p, data: ex.data !== undefined ? ex.data : null, text: ex.text !== undefined ? ex.text : null });
+      const v = createVerify('sha256'); v.update(body);
+      if (expected.publicKeyPem && v.verify(expected.publicKeyPem, Buffer.from(ex.signature, 'base64'))) { if (level !== 'none') level = 'signed'; }
+      else add('invalid-signature', `${label}: the signature does not verify`);
+    } catch (e) { add('invalid-signature', `${label}: signature check failed (${e.message})`); }
+  } else if (expected.requireSigned) add('unsigned', `${label}: a signed export is required`);
+  summary.level = level;
+  return { summary };
+}
+
+/** Canonical body that a producer signs (exported so tests and producers agree on it). */
+export function signedBody(ex) { return JSON.stringify({ schema: ex.schema, provenance: ex.provenance, data: ex.data !== undefined ? ex.data : null, text: ex.text !== undefined ? ex.text : null }); }
+export { sha256 as _sha256 };

package/src/language/nix-eval-isolation.js

@@ -0,0 +1,274 @@
+// Isolated, opt-in Nix evaluation (NIX-011).
+//
+// Ordinary scanning NEVER evaluates customer Nix: nothing imports this module on the default path. An
+// operator who explicitly asks for evaluation gets it only inside an OS sandbox whose isolation this module
+// has just proved with a probe, and only through an evaluator whose required safety flags were
+// feature-detected. The order is fixed and every step before the last is "before project code runs":
+//
+//   1. detectSandbox      which backend exists on this host (macOS sandbox-exec, Linux bubblewrap), or none
+//   2. probeSandbox       run a probe INSIDE the sandbox that tries to read outside the allowlist, write
+//                         outside it, reach the network, reach a daemon socket, spawn a process and see a
+//                         credential variable; the sandbox is accepted only if every attempt is refused
+//   3. detectEvaluator    run `--version` / `eval --help` and require every safety flag to exist
+//   4. runIsolatedEval    run the target-scoped evaluation with a clean environment, a read-only allowlist,
+//                         a wall-clock deadline, an output cap and a memory ceiling; kill the whole process group
+//
+// Anything that fails earlier returns `unsupported` or `blocked` with `projectCodeEvaluated:false`; the
+// static findings of the scan are never touched (`staticFindingsRetained:true`) and the result says how to
+// import a supplied export instead. Flags are NOT the boundary: the filesystem/network/process boundary is
+// the sandbox, and the probe tests it independently of any flag. Nix's own build sandbox and restricted
+// evaluation are additional controls, not substitutes. Nothing here runs `nixos-rebuild`, activates a
+// configuration, builds anything or edits a host setting.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { createServer as netServer } from 'node:net';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, realpathSync } from 'node:fs';
+import { tmpdir, platform as osPlatform } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const NIX_EVAL_VERSION = 'nix-eval-isolation/1';
+export const DEFAULT_LIMITS = Object.freeze({ deadlineMs: 20_000, maxOutputBytes: 1 << 20, maxRssMb: 512, killGraceMs: 1500, probeDeadlineMs: 15_000 });
+/** Flags the evaluator must support; a missing one means `unsupported`, never "run without it". */
+export const REQUIRED_EVAL_FLAGS = Object.freeze(['--offline', '--no-update-lock-file', '--no-write-lock-file', '--pure-eval', '--json', '--option']);
+/** `--option name value` settings that are always passed. */
+export const SAFETY_OPTIONS = Object.freeze({
+  'allow-import-from-derivation': 'false',
+  'allow-unsafe-native-code-during-evaluation': 'false',
+  'accept-flake-config': 'false',
+  'restrict-eval': 'true',
+  'allowed-uris': '',
+  'substituters': '',
+  'max-jobs': '0',
+});
+const CLEAN_PATH = '/usr/bin:/bin';
+const ATTR_RE = /^[A-Za-z0-9_][A-Za-z0-9_.+'-]*(?:\.(?:[A-Za-z0-9_][A-Za-z0-9_+'-]*|"[A-Za-z0-9_.+-]+"))*$/;
+
+// ── 1. sandbox backend ───────────────────────────────────────────────────────
+const which = (bin) => { const r = spawnSync('/usr/bin/which', [bin], { encoding: 'utf8', timeout: 5000 }); return r.status === 0 ? r.stdout.trim() : null; };
+
+export function detectSandbox(opts = {}) {
+  const plat = opts.platform || osPlatform();
+  const find = opts.which || which;
+  if (opts.forceBackend === 'none') return { available: false, backend: 'none', platform: plat, reason: 'isolation disabled by the caller' };
+  if (plat === 'darwin') {
+    const p = find('sandbox-exec');
+    return p ? { available: true, backend: 'sandbox-exec', path: p, platform: plat, reason: null } : { available: false, backend: 'none', platform: plat, reason: 'sandbox-exec is not installed' };
+  }
+  if (plat === 'linux') {
+    const p = find('bwrap');
+    return p ? { available: true, backend: 'bwrap', path: p, platform: plat, reason: null } : { available: false, backend: 'none', platform: plat, reason: 'bubblewrap (bwrap) is not installed: no tested unprivileged filesystem/network namespace is available' };
+  }
+  return { available: false, backend: 'none', platform: plat, reason: `no sandbox backend is implemented for ${plat}` };
+}
+
+const sbq = (s) => `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+
+/**
+ * The sandboxed command for a backend. Reads are an ALLOWLIST (the listed roots, system library paths and the
+ * evaluator); writes are an allowlist of one scratch directory; network and process creation are denied.
+ * @param {{backend:string, path?:string}} sb
+ * @param {{execFile:string, args:string[], readOnly:string[], readFiles?:string[], writable:string[], cwd:string}} spec
+ */
+export function sandboxCommand(sb, spec) {
+  const ro = [...new Set(spec.readOnly.map(real))];
+  const files = [...new Set((spec.readFiles || []).map(real))];
+  const rw = [...new Set(spec.writable.map(real))];
+  const exec = real(spec.execFile);
+  if (sb.backend === 'sandbox-exec') {
+    const profile = [
+      '(version 1)', '(allow default)', '(deny network*)',
+      '(deny file-write*)', `(allow file-write* ${rw.map((p) => `(subpath ${sbq(p)})`).join(' ')} (subpath "/dev"))`,
+      '(deny file-read-data (subpath "/"))',
+      `(allow file-read-data (literal "/") ${[spec.cwd, ...rw].map((p) => `(literal ${sbq(real(p))})`).join(' ')} (subpath "/usr") (subpath "/System") (subpath "/Library") (subpath "/private/var/db") (subpath "/dev") (subpath "/nix/store") ${ro.map((p) => `(subpath ${sbq(p)})`).join(' ')} ${files.map((p) => `(literal ${sbq(p)})`).join(' ')} ${rw.map((p) => `(subpath ${sbq(p)})`).join(' ')})`,
+      '(deny process-exec*)', `(allow process-exec (literal ${sbq(exec)}) (subpath "/nix/store"))`,
+    ].join('\n');
+    return { file: sb.path, args: ['-p', profile, exec, ...spec.args], profile };
+  }
+  if (sb.backend === 'bwrap') {
+    const a = ['--unshare-all', '--die-with-parent', '--new-session', '--clearenv', '--proc', '/proc', '--dev', '/dev', '--tmpfs', '/tmp'];
+    for (const p of ['/usr', '/lib', '/lib64', '/bin', '/etc/ssl', '/nix/store']) a.push('--ro-bind-try', p, p);
+    for (const p of ro) a.push('--ro-bind', p, p);
+    for (const p of files) a.push('--ro-bind', p, p);
+    for (const p of rw) a.push('--bind', p, p);
+    a.push('--chdir', spec.cwd, exec, ...spec.args);
+    return { file: sb.path, args: a, profile: null };
+  }
+  return null;
+}
+
+// ── process supervisor ───────────────────────────────────────────────────────
+function rssOfGroup(pgid) {
+  const r = spawnSync('/bin/ps', ['-o', 'rss=', '-g', String(pgid)], { encoding: 'utf8', timeout: 2000 });
+  if (r.status !== 0) return 0;
+  return r.stdout.split('\n').map((x) => parseInt(x, 10)).filter(Number.isFinite).reduce((a, b) => a + b, 0) / 1024;
+}
+function killGroup(pid, sig) { try { process.kill(-pid, sig); } catch { try { process.kill(pid, sig); } catch { /* gone */ } } }
+
+/** Run a command to completion under a deadline, an output cap and a memory ceiling. Never throws. */
+export function supervise(file, args, { env, cwd, deadlineMs, maxOutputBytes, maxRssMb, killGraceMs = 1500 }) {
+  return new Promise((resolveP) => {
+    const t0 = Date.now();
+    let child;
+    try { child = spawn(file, args, { env, cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] }); }
+    catch (e) { return resolveP({ status: 'failed', reason: `could not start: ${e.message}`, stdout: '', stderr: '', exitCode: null, signal: null, ms: 0 }); }
+    let out = ''; let err = ''; let bytes = 0; let state = null; let done = false;
+    const finish = (extra = {}) => { if (done) return; done = true; clearInterval(poll); clearTimeout(dl); resolveP({ stdout: out, stderr: err.slice(0, 4000), ms: Date.now() - t0, ...extra }); };
+    const stop = (why) => { if (state) return; state = why; killGroup(child.pid, 'SIGTERM'); setTimeout(() => killGroup(child.pid, 'SIGKILL'), killGraceMs).unref(); };
+    child.stdout.on('data', (d) => { bytes += d.length; if (bytes > maxOutputBytes) { stop('output-limit'); return; } out += d.toString('utf8'); });
+    child.stderr.on('data', (d) => { if (err.length < 8000) err += d.toString('utf8'); });
+    const dl = setTimeout(() => stop('timed-out'), deadlineMs);
+    const poll = setInterval(() => { if (!state && maxRssMb && rssOfGroup(child.pid) > maxRssMb) stop('resource-limit'); }, 250);
+    child.on('error', (e) => finish({ status: 'failed', reason: e.message, exitCode: null, signal: null }));
+    child.on('close', (code, signal) => {
+      killGroup(child.pid, 'SIGKILL');                                          // reap any descendants
+      finish({ status: state || (code === 0 ? 'ok' : 'failed'), exitCode: code, signal, reason: state ? `${state}${state === 'timed-out' ? ` after ${deadlineMs} ms` : ''}` : (code === 0 ? null : `exit ${code}`) });
+    });
+  });
+}
+
+const cleanEnv = (work, extra = {}) => ({ PATH: CLEAN_PATH, HOME: work, TMPDIR: work, LANG: 'C', LC_ALL: 'C', ...extra });
+
+// ── 2. probe ─────────────────────────────────────────────────────────────────
+const PROBE_SOURCE = `
+const fs=require('fs'),net=require('net'),cp=require('child_process');
+const [allowedFile,outsideFile,outsideWrite,okWrite,port,sock]=process.argv.slice(2);
+const r={};const t=(k,f)=>{try{r[k]=f()}catch(e){r[k]='refused:'+(e.code||'error')}};
+t('readAllowed',()=>fs.readFileSync(allowedFile,'utf8').trim());
+t('readOutside',()=>{fs.readFileSync(outsideFile,'utf8');return 'READ'});
+t('readHostFile',()=>{fs.readFileSync('/etc/hosts','utf8');return 'READ'});
+t('writeOutside',()=>{fs.writeFileSync(outsideWrite,'x');return 'WROTE'});
+t('writeScratch',()=>{fs.writeFileSync(okWrite,'x');return 'wrote'});
+t('spawn',()=>{cp.execFileSync('/bin/echo',['x']);return 'SPAWNED'});
+t('credentialEnv',()=>process.env.PROBE_CREDENTIAL||'absent');
+let pending=2;const fin=()=>{if(--pending===0){console.log(JSON.stringify(r));process.exit(0)}};
+const tcp=net.connect(Number(port),'127.0.0.1');tcp.on('connect',()=>{r.network='CONNECTED';tcp.destroy();fin()});tcp.on('error',(e)=>{r.network='refused:'+e.code;fin()});
+const un=net.connect(sock);un.on('connect',()=>{r.daemonSocket='CONNECTED';un.destroy();fin()});un.on('error',(e)=>{r.daemonSocket='refused:'+e.code;fin()});
+setTimeout(()=>{r.timeout=true;console.log(JSON.stringify(r));process.exit(0)},8000);
+`;
+
+/**
+ * Prove the isolation of a backend with real attempts, independent of any evaluator flag. The result is
+ * `verified` only if the one permitted read worked, the scratch write worked and every other attempt was refused.
+ */
+export async function probeSandbox(sb, opts = {}) {
+  if (!sb || !sb.available) return { verified: false, backend: sb ? sb.backend : 'none', reason: (sb && sb.reason) || 'no sandbox', attempts: {} };
+  const limits = { ...DEFAULT_LIMITS, ...(opts.limits || {}) };
+  const base = mkdtempSync(join(tmpdir(), 'nix-eval-probe-'));
+  const allowed = join(base, 'ro'); const scratch = join(base, 'rw'); const outside = join(base, 'outside');
+  for (const d of [allowed, scratch, outside]) mkdirSync(d);
+  writeFileSync(join(allowed, 'a.txt'), 'allowed'); writeFileSync(join(outside, 'secret.txt'), 'secret');
+  const script = join(base, 'probe.cjs'); writeFileSync(script, PROBE_SOURCE);
+  const sockPath = join(base, 'daemon.sock');
+  let connections = 0;
+  const tcp = netServer((s) => { connections++; s.destroy(); });
+  const uds = netServer((s) => { connections++; s.destroy(); });
+  await new Promise((r) => tcp.listen(0, '127.0.0.1', r));
+  await new Promise((r) => uds.listen(sockPath, r));
+  const port = tcp.address().port;
+  try {
+    const exe = opts.nodePath || process.execPath;
+    const cmd = sandboxCommand(sb, { execFile: exe, args: [script, join(allowed, 'a.txt'), join(outside, 'secret.txt'), join(outside, 'w.txt'), join(scratch, 'w.txt'), String(port), sockPath], readOnly: [allowed, dirname(dirname(real(exe)))], readFiles: [script], writable: [scratch], cwd: scratch });
+    const r = await supervise(cmd.file, cmd.args, { env: cleanEnv(scratch), cwd: scratch, deadlineMs: limits.probeDeadlineMs, maxOutputBytes: 64 * 1024, maxRssMb: limits.maxRssMb, killGraceMs: limits.killGraceMs });
+    let attempts = null;
+    try { attempts = JSON.parse(r.stdout.trim()); } catch { /* unparseable: not verified */ }
+    if (!attempts) return { verified: false, backend: sb.backend, reason: `the probe did not complete inside the sandbox (${r.reason || r.stderr.slice(0, 120) || 'no output'})`, attempts: {} };
+    const insufficient = [];
+    if (attempts.readAllowed !== 'allowed') insufficient.push('the allowlisted read failed: the sandbox is unusable');
+    if (attempts.writeScratch !== 'wrote') insufficient.push('the scratch write failed: the sandbox is unusable');
+    if (attempts.readOutside === 'READ') insufficient.push('a file outside the allowlist could be read');
+    if (attempts.readHostFile === 'READ') insufficient.push('a host file (/etc/hosts) could be read');
+    if (attempts.writeOutside === 'WROTE') insufficient.push('a file outside the scratch directory could be written');
+    if (attempts.network === 'CONNECTED') insufficient.push('a network connection succeeded');
+    if (attempts.daemonSocket === 'CONNECTED') insufficient.push('a unix daemon socket could be reached');
+    if (attempts.spawn === 'SPAWNED') insufficient.push('a native process could be spawned');
+    if (attempts.credentialEnv && attempts.credentialEnv !== 'absent') insufficient.push('a credential environment variable was visible');
+    if (attempts.timeout) insufficient.push('the probe timed out');
+    return { verified: insufficient.length === 0 && connections === 0, backend: sb.backend, reason: insufficient.length ? insufficient.join('; ') : (connections ? 'the probe listeners saw a connection' : null), attempts, listenerConnections: connections, insufficient };
+  } finally { tcp.close(); uds.close(); rmSync(base, { recursive: true, force: true }); }
+}
+
+// ── 3. evaluator feature detection ───────────────────────────────────────────
+/** @param {{file:string, prefixArgs?:string[]}} nix  the evaluator command (a stand-in in tests) */
+export async function detectEvaluator(nix, sb, ctx) {
+  const run = async (args) => {
+    const cmd = sandboxCommand(sb, { execFile: nix.file, args: [...(nix.prefixArgs || []), ...args], readOnly: ctx.readOnly, readFiles: [...(ctx.readFiles || []), ...(nix.prefixArgs || []).filter((a) => !a.startsWith('-'))], writable: [ctx.work], cwd: ctx.work });
+    return supervise(cmd.file, cmd.args, { env: cleanEnv(ctx.work), cwd: ctx.work, deadlineMs: 10_000, maxOutputBytes: 64 * 1024, maxRssMb: ctx.limits.maxRssMb, killGraceMs: ctx.limits.killGraceMs });
+  };
+  const v = await run(['--version']);
+  const ver = (/(\d+\.\d+(?:\.\d+)?)/.exec(v.stdout) || [])[1] || null;
+  if (v.status !== 'ok' || !ver) return { ok: false, reason: `the evaluator did not report a version (${v.reason || 'no output'})`, version: null, missing: REQUIRED_EVAL_FLAGS.slice() };
+  const h = await run(['eval', '--help']);
+  const text = `${h.stdout}\n${h.stderr}`;
+  const missing = REQUIRED_EVAL_FLAGS.filter((f) => !text.includes(f));
+  return { ok: missing.length === 0, version: ver, missing, reason: missing.length ? `the evaluator lacks required safety flag(s): ${missing.join(', ')}` : null };
+}
+
+// ── target selection and argv ────────────────────────────────────────────────
+/** A flake output attribute, validated. Anything outside a plain attribute path is refused. */
+export function selectTarget({ root, attribute, system = null } = {}) {
+  if (typeof root !== 'string' || !root.startsWith('/')) return { ok: false, reason: 'the project root must be an absolute path' };
+  if (typeof attribute !== 'string' || !ATTR_RE.test(attribute) || attribute.length > 200) return { ok: false, reason: `"${String(attribute).slice(0, 40)}" is not a plain flake attribute path` };
+  if (/\.\./.test(attribute)) return { ok: false, reason: 'attribute paths may not contain ..' };
+  return { ok: true, installable: `path:${root}#${attribute}`, root, attribute, system };
+}
+export function buildEvalArgs(target) {
+  const opts = Object.entries(SAFETY_OPTIONS).flatMap(([k, v]) => ['--option', k, v]);
+  return ['eval', '--offline', '--no-update-lock-file', '--no-write-lock-file', '--pure-eval', '--json', ...opts, target.installable];
+}
+
+// ── 4. run ───────────────────────────────────────────────────────────────────
+export const IMPORT_FALLBACK = Object.freeze({
+  summary: 'Evaluation did not run or did not finish. Static findings are unaffected. To supply the data yourself, generate an export on a trusted machine and pass it in:',
+  steps: ['nix path-info --json --recursive <installable>  >  pathinfo.json', 'nix derivation show --recursive <installable>  >  drvshow.json', 'Provide both with a provenance envelope (tool, command, target system and installable, flake.lock sha256, generation time); see docs/guides/nix.md'],
+  schemas: ['nix-path-info-json', 'nix-derivation-show-json', 'nix-store-query-text'],
+});
+
+/**
+ * @param {{nix:{file:string,prefixArgs?:string[]}, root:string, attribute:string, system?:string, limits?:object,
+ *          sandbox?:object, extraReadOnly?:string[], probe?:Function, env?:object}} o
+ * @returns {Promise<{status:'ok'|'unsupported'|'blocked'|'timed-out'|'output-limit'|'resource-limit'|'failed', projectCodeEvaluated:boolean, ...}>}
+ */
+export async function runIsolatedEval(o) {
+  const limits = { ...DEFAULT_LIMITS, ...(o.limits || {}) };
+  const keep = { staticFindingsRetained: true, fallback: IMPORT_FALLBACK, evaluation: 'opt-in' };
+  const stopBefore = (status, reason, extra = {}) => ({ status, reason, projectCodeEvaluated: false, ...keep, ...extra });
+  const target = selectTarget({ root: o.root, attribute: o.attribute, system: o.system });
+  if (!target.ok) return stopBefore('blocked', target.reason);
+  const sb = o.sandbox || detectSandbox();
+  if (!sb.available) return stopBefore('unsupported', `no isolation is available (${sb.reason}); the project's Nix code was NOT evaluated`, { sandbox: sb });
+  const probe = await (o.probe || probeSandbox)(sb, { limits });
+  if (!probe.verified) return stopBefore('blocked', `the sandbox did not prove its isolation, so the project's Nix code was NOT evaluated: ${probe.reason}`, { sandbox: sb, probe });
+  const work = mkdtempSync(join(tmpdir(), 'nix-eval-work-'));
+  try {
+    const root = real(o.root);
+    const nixFiles = [nix_file(o.nix), ...(o.nix.prefixArgs || []).filter((a) => a && !a.startsWith('-')).map(real)];
+    const ctx = { work: real(work), readOnly: [root, dirname(dirname(real(o.nix.file))), ...(o.extraReadOnly || [])], readFiles: nixFiles, limits };
+    const feat = await detectEvaluator(o.nix, sb, ctx);
+    if (!feat.ok) return stopBefore('unsupported', `${feat.reason}; the project's Nix code was NOT evaluated`, { sandbox: sb, probe: { verified: true }, evaluator: feat });
+    const args = [...(o.nix.prefixArgs || []), ...buildEvalArgs(target)];
+    const cmd = sandboxCommand(sb, { execFile: o.nix.file, args, readOnly: ctx.readOnly, readFiles: nixFiles, writable: [ctx.work], cwd: ctx.work });
+    const r = await supervise(cmd.file, cmd.args, { env: cleanEnv(ctx.work, o.env || {}), cwd: ctx.work, deadlineMs: limits.deadlineMs, maxOutputBytes: limits.maxOutputBytes, maxRssMb: limits.maxRssMb, killGraceMs: limits.killGraceMs });
+    const base = { ...keep, projectCodeEvaluated: true, sandbox: { backend: sb.backend }, evaluator: { version: feat.version }, ms: r.ms, target: { attribute: target.attribute, system: target.system, installable: target.installable } };
+    if (r.status !== 'ok') return { ...base, status: r.status === 'failed' ? 'failed' : r.status, reason: r.reason || r.stderr.slice(0, 200) };
+    let data;
+    try { data = JSON.parse(r.stdout); } catch { return { ...base, status: 'failed', reason: 'the evaluator output was not JSON' }; }
+    const digest = createHash('sha256').update(r.stdout).digest('hex');
+    return { ...base, status: 'ok', reason: null, export: { schema: 'nix-eval-attrs-json', provenance: { tool: 'nix', toolVersion: feat.version, command: `nix ${buildEvalArgs(target).join(' ')}`, target: { system: target.system, installable: target.installable, attribute: target.attribute }, generatedAt: new Date().toISOString(), isolation: sb.backend, outputSha256: digest }, data }, outputSha256: digest };
+  } finally { rmSync(work, { recursive: true, force: true }); }
+}
+const nix_file = (n) => real(n.file);
+
+/** Evaluation health is its OWN state: it never replaces, empties or downgrades the static scan. */
+export function mergeEvaluationHealth(scanHealth, result) {
+  const h = scanHealth && typeof scanHealth === 'object' ? { ...scanHealth } : {};
+  const requested = !!result;
+  h.evaluation = requested
+    ? { requested: true, status: result.status, ran: result.projectCodeEvaluated === true, reason: result.reason || null, ms: result.ms ?? null, fallback: result.status === 'ok' ? null : result.fallback || IMPORT_FALLBACK }
+    : { requested: false, status: 'not-requested', ran: false, reason: 'evaluation is opt-in; the scan is static', fallback: null };
+  h.staticFindingsRetained = true;
+  return h;
+}
+
+export { cleanEnv as _cleanEnv, which as _which };