0sec-cli 0.15.0 → 0.18.0

package/chunks/chunk-BFRB6HB2.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+import { createRequire as __0secCreateRequire } from "node:module";
+const require = __0secCreateRequire(import.meta.url);
+import {
+  LlmApiRuntime
+} from "./chunk-UR4ELX2Y.js";
+
+// packages/core/dist/stages/variant-candidates.js
+import { execFileSync } from "node:child_process";
+
+// packages/core/dist/stages/hunt-reachability.js
+var UNREACHABLE_PATH_PREFIXES = [
+  // ── Not built on COS (kernelctf-config.ts COS_CONFIG_STATE) ──
+  "net/kcm/",
+  // CONFIG_AF_KCM not-built — the original "kcm lesson"
+  "net/bluetooth/",
+  // CONFIG_BT not-built
+  "net/can/",
+  // CONFIG_CAN not-built
+  "fs/f2fs/",
+  // CONFIG_F2FS_FS not-built
+  // ── Exotic/unbuilt drivers (observed this session; same story, not yet
+  //    in kernelctf-config.ts's token map) ──
+  "drivers/infiniband/",
+  // RXE/infiniband — not built on COS
+  "drivers/net/wireless/",
+  // mwifiex etc. — not built on COS
+  "drivers/media/",
+  // exotic media drivers — not built on COS
+  "drivers/hid/",
+  // hidraw — not built on COS
+  "drivers/usb/gadget/",
+  // USB gadget — not built / not a zero-cap network path
+  "drivers/usb/atm/",
+  // uea/ueagle-atm — not built on COS
+  "drivers/xen/",
+  // xen paravirt — COS is not a Xen guest
+  "drivers/staging/",
+  // staging tree — not built on COS, churny/unstable
+  // ── Exotic filesystems: the trigger is mount(2), which needs
+  //    CAP_SYS_ADMIN a zero-cap kernelCTF attacker doesn't have (mirrors
+  //    kernelctf-config.ts's ext4/xfs/btrfs/ntfs3/fuse `needsCap:
+  //    CAP_SYS_ADMIN` entries); these ones aren't built on COS at all either ──
+  "fs/reiserfs/",
+  "fs/hpfs/",
+  "fs/sysv/",
+  "fs/ntfs/",
+  // legacy ntfs (distinct from the ntfs3 module)
+  "fs/jfs/"
+];
+var REACHABLE_PATH_PREFIXES = [
+  "crypto/",
+  // CONFIG_CRYPTO_USER_API_{AEAD,SKCIPHER,HASH} — AF_ALG, zero-cap
+  "net/unix/",
+  // CONFIG_UNIX — AF_UNIX, zero-cap
+  "net/core/",
+  // core socket/skb plumbing, zero-cap from any AF_* socket
+  "net/ipv4/",
+  // core IPv4, zero-cap
+  "net/ipv6/",
+  // core IPv6, zero-cap
+  // CONFIG_PACKET — kernelctf-config.ts marks needsCap CAP_NET_RAW for
+  // AF_PACKET itself; still listed reachable here (worth the finder budget).
+  "net/packet/",
+  "net/vmw_vsock/",
+  // CONFIG_VSOCKETS(+_LOOPBACK) — AF_VSOCK loopback, zero-cap
+  "net/tls/",
+  // CONFIG_TLS — kTLS, zero-cap
+  "net/xfrm/",
+  // IPsec policy/state — reachable via standard AF_INET{,6} sockets
+  "net/netlink/",
+  // AF_NETLINK core — zero-cap socket family
+  "ipc/",
+  // CONFIG_SYSVIPC — System-V IPC (msg/sem/shm), zero-cap
+  // CONFIG_EXT4_FS / CONFIG_XFS_FS — kernelctf-config.ts marks needsCap
+  // CAP_SYS_ADMIN for the *mount* trigger; still listed reachable here (core
+  // FS code is real audit surface, worth the finder budget).
+  "fs/ext4/",
+  "fs/xfs/",
+  // unprivileged_bpf_disabled is commonly runtime-off; listed reachable here
+  // rather than dropped outright (flag the caveat in the finder hint instead).
+  "kernel/bpf/",
+  "security/keys/"
+  // CONFIG_KEYS — keyrings / add_key(2), zero-cap
+];
+function hasPathSegmentPrefix(path, prefix) {
+  const idx = path.indexOf(prefix);
+  if (idx === -1)
+    return false;
+  return idx === 0 || path[idx - 1] === "/";
+}
+function classifyPathReachability(path) {
+  const norm = path.replace(/\\/g, "/");
+  for (const prefix of UNREACHABLE_PATH_PREFIXES)
+    if (hasPathSegmentPrefix(norm, prefix))
+      return "unreachable";
+  for (const prefix of REACHABLE_PATH_PREFIXES)
+    if (hasPathSegmentPrefix(norm, prefix))
+      return "reachable";
+  return "unknown";
+}
+function applyReachabilityGate(paths, opts) {
+  if (!opts.reachableOnly && !opts.reachablePrefer)
+    return { paths, unreachableCount: 0 };
+  const classified = paths.map((path) => ({ path, cls: classifyPathReachability(path) }));
+  const unreachableCount = classified.filter((c) => c.cls === "unreachable").length;
+  if (opts.reachableOnly) {
+    return { paths: classified.filter((c) => c.cls === "reachable").map((c) => c.path), unreachableCount };
+  }
+  const rank = { reachable: 0, unknown: 1, unreachable: 2 };
+  const sorted = [...classified].sort((a, b) => rank[a.cls] - rank[b.cls]).map((c) => c.path);
+  return { paths: sorted, unreachableCount };
+}
+
+// packages/core/dist/stages/variant-candidates.js
+var clip = (s, n) => s.length > n ? s.slice(0, n) + `
+...[truncated ${s.length - n} chars]` : s;
+function fixedPathsFromDiff(diff) {
+  const out = [];
+  for (const line of diff.split("\n")) {
+    const m = /^\+\+\+ b\/(.+)$/.exec(line);
+    if (m && m[1] !== "/dev/null")
+      out.push(m[1].trim());
+  }
+  return [...new Set(out)];
+}
+function grepFiles(pattern, sourceRoot, includeGlobs) {
+  const args = ["-rlE", ...includeGlobs.map((g) => `--include=${g}`), "--", pattern, "."];
+  try {
+    const out = execFileSync("grep", args, { cwd: sourceRoot, encoding: "utf8", maxBuffer: 32 * 1024 * 1024, timeout: 6e4 });
+    return out.split("\n").map((s) => s.replace(/^\.\//, "").trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function generateVariantCandidates(input) {
+  const log = input.log ?? (() => {
+  });
+  const warnings = [];
+  const maxCandidates = input.maxCandidates ?? 40;
+  const includeGlobs = input.includeGlobs ?? ["*.c", "*.h", "*.cc", "*.cpp"];
+  let diff = input.fix.diff ?? "";
+  if (!diff && input.fix.commit) {
+    try {
+      diff = execFileSync("git", ["-C", input.sourceRoot, "show", "--no-color", input.fix.commit], {
+        encoding: "utf8",
+        maxBuffer: 16 * 1024 * 1024,
+        timeout: 3e4
+      });
+    } catch (e) {
+      throw new Error(`could not read fix commit ${input.fix.commit}: ${String(e).slice(0, 160)}`);
+    }
+  }
+  if (!diff.trim())
+    throw new Error("variant hunt needs fix.diff or fix.commit");
+  const fixedPaths = fixedPathsFromDiff(diff);
+  const tool = {
+    name: "emit_variant_plan",
+    description: "Emit the variant-hunt plan derived from the fix diff.",
+    input_schema: {
+      type: "object",
+      properties: {
+        bugClass: { type: "string", description: "The bug class the fix closed, e.g. 'missing bounds check before a TLV copy'." },
+        pattern: { type: "string", description: "The exact unguarded code shape (the sink) and how the fix guarded it." },
+        grepPatterns: {
+          type: "array",
+          items: { type: "string" },
+          description: "2-6 grep ERE patterns that locate the SAME sink shape at OTHER call-sites/files (the variant sites where the fix was NOT applied). Match the sink/call, not the added guard."
+        }
+      },
+      required: ["bugClass", "pattern", "grepPatterns"]
+    }
+  };
+  const system = "You are a kernel/security VARIANT-HUNT analyst. Given a security fix diff, identify the bug class and the unguarded code SHAPE (the sink) the fix added a guard around. Then write grep EXTENDED-REGEX patterns that find the SAME bug CLASS at OTHER call-sites across the tree \u2014 where an INCOMPLETE fix or an independent instance lives.\nCRITICAL \u2014 match the CLASS, not the original site: the patched file is EXCLUDED from results, so a pattern that hardcodes the original's specific identifiers (field names like `sensf_res`, struct names like `digital_*`, the variable `resp`) will match ONLY the original and yield ZERO variants. WILDCARD the identifiers. Match the dangerous SHAPE \u2014 e.g. a length-controlled copy into a fixed buffer regardless of names: `memcpy\\([^,]+,[^,]+,[^)]*->len\\)`, or an unchecked `->len`/`->size` used as a copy/index bound. Match the sink, NOT the guard that was added.\nEmit 3-6 patterns ranging from moderately specific (the same struct-field-copy shape with wildcarded names) to general (any length-bounded memcpy/copy_from of that family). Aim for tens of hits to triage, not zero and not thousands. Call emit_variant_plan.";
+  const messages = [{ role: "user", content: [{ type: "text", text: `## Fix diff
+${clip(diff, 24e3)}` }] }];
+  const rt = new LlmApiRuntime({ type: "api", ...input.model ? { model: input.model } : {}, timeout: 24e4 });
+  let plan = null;
+  try {
+    const res = await rt.executeNative(system, messages, [tool], { onThinking() {
+    }, onDelta() {
+    }, onText() {
+    }, onUsage() {
+    } });
+    const call = (res.content ?? []).find((b) => b.type === "tool_use" && b.name === "emit_variant_plan");
+    if (call?.input)
+      plan = call.input;
+  } catch (e) {
+    throw new Error(`variant-plan LLM call failed: ${String(e).slice(0, 200)}`);
+  }
+  if (!plan || !Array.isArray(plan.grepPatterns) || plan.grepPatterns.length === 0) {
+    throw new Error("model did not emit a usable variant plan");
+  }
+  log(`[variant] bug class: ${plan.bugClass}`);
+  log(`[variant] ${plan.grepPatterns.length} grep pattern(s): ${plan.grepPatterns.join(" | ")}`);
+  const fixedSet = new Set(fixedPaths);
+  const hits = /* @__PURE__ */ new Map();
+  for (const pat of plan.grepPatterns) {
+    const files = grepFiles(pat, input.sourceRoot, includeGlobs);
+    if (files.length === 0)
+      warnings.push(`pattern matched nothing (or invalid): ${pat}`);
+    for (const f of files)
+      if (!fixedSet.has(f))
+        hits.set(f, (hits.get(f) ?? 0) + 1);
+  }
+  const ranked = [...hits.entries()].sort((a, b) => b[1] - a[1]).map(([path]) => path);
+  const gated = input.reachableOnly || input.reachablePrefer ? applyReachabilityGate(ranked, { reachableOnly: input.reachableOnly, reachablePrefer: input.reachablePrefer }) : { paths: ranked, unreachableCount: 0 };
+  if (gated.unreachableCount > 0) {
+    const verb = input.reachableOnly ? "dropped" : "deprioritized";
+    const msg = `${verb} ${gated.unreachableCount} unreachable candidate(s) (not built/zero-cap on kernelCTF COS \u2014 see hunt-reachability.ts)`;
+    warnings.push(msg);
+    log(`[variant] ${msg}`);
+  }
+  if (gated.paths.length > maxCandidates) {
+    warnings.push(`capped candidates ${gated.paths.length} -> ${maxCandidates} (raise maxCandidates to widen)`);
+  }
+  const candidates = gated.paths.slice(0, maxCandidates).map((path) => ({
+    path,
+    hint: `Variant site for: ${plan.bugClass}. Check whether ${plan.pattern} is guarded here.`
+  }));
+  log(`[variant] ${candidates.length} candidate site(s) after dedup/exclude`);
+  return {
+    brief: { bugClass: plan.bugClass, pattern: plan.pattern, fixReference: input.fix.reference ?? input.fix.commit },
+    candidates,
+    grepPatterns: plan.grepPatterns,
+    fixedPaths,
+    warnings
+  };
+}
+
+export {
+  classifyPathReachability,
+  applyReachabilityGate,
+  generateVariantCandidates
+};

package/chunks/chunk-BKZFDZ23.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+import { createRequire as __0secCreateRequire } from "node:module";
+const require = __0secCreateRequire(import.meta.url);
+import {
+  collectScopeFiles
+} from "./chunk-53G27VPS.js";
+
+// packages/core/dist/specdrift/extract.js
+var MODAL_RE = /\b(MUST(?:\s+NOT)?|SHALL(?:\s+NOT)?|SHOULD(?:\s+NOT)?|MAY|REQUIRED|OPTIONAL)\b/;
+var RANGE_RE = /\b(?:between|minimum|maximum|at least|at most|less than|greater than|[0-9]+\s*(?:-|to)\s*[0-9]+|0x[0-9a-f]+)\b/i;
+var LENGTH_RE = /\b(length|size|bytes?|octets?|bits?|payload|frame size|field)\b/i;
+var STATE_RE = /\b(state|transition|handshake|stream|session|before|after|until|when|while|once)\b/i;
+var REJECT_RE = /\b(reject(?:ed|s|ing)?|error|invalid|malformed|abort(?:ed|s|ing)?|terminate(?:d|s|ing)?|discard(?:ed|s|ing)?|fail(?:ed|s|ing)?|close(?:d|s|ing)?)\b/i;
+var ORDER_RE = /\b(before|after|first|then|prior to|followed by|precede|order)\b/i;
+var CANON_RE = /\b(canonical|normalize|normalise|case-sensitive|case-insensitive|duplicate|unique)\b/i;
+function hasNormativeSignal(text) {
+  return MODAL_RE.test(text) || REJECT_RE.test(text) || STATE_RE.test(text) && (RANGE_RE.test(text) || LENGTH_RE.test(text));
+}
+function slug(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "rule";
+}
+function splitLines(specText) {
+  const out = [];
+  let section;
+  const lines = specText.replace(/\r\n/g, "\n").split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i] ?? "";
+    const trimmed = raw.trim();
+    const mdHeading = /^#{1,6}\s+(.+)$/.exec(trimmed);
+    const numberedHeading = /^(\d+(?:\.\d+)*\.?\s+.+)$/.exec(trimmed);
+    if (mdHeading?.[1])
+      section = mdHeading[1].trim();
+    else if (numberedHeading?.[1] && trimmed.length < 120)
+      section = numberedHeading[1].trim();
+    out.push({ n: i + 1, text: raw, ...section ? { section } : {} });
+  }
+  return out;
+}
+function sentences(lines) {
+  const out = [];
+  let buf = "";
+  let start = 1;
+  let section;
+  for (const line of lines) {
+    const trimmed = line.text.trim();
+    if (!trimmed)
+      continue;
+    if (/^#{1,6}\s+/.test(trimmed) || /^(\d+(?:\.\d+)*\.?\s+.+)$/.test(trimmed))
+      continue;
+    if (!buf && !hasNormativeSignal(trimmed))
+      continue;
+    if (!buf) {
+      start = line.n;
+      section = line.section;
+    }
+    buf = buf ? `${buf} ${trimmed}` : trimmed;
+    if (/[.!?]$/.test(trimmed) || buf.length > 420) {
+      out.push({ n: start, text: buf, ...section ? { section } : {} });
+      buf = "";
+      section = void 0;
+    }
+  }
+  if (buf)
+    out.push({ n: start, text: buf, ...section ? { section } : {} });
+  return out;
+}
+function kindFor(text) {
+  if (REJECT_RE.test(text))
+    return "rejection";
+  if (STATE_RE.test(text))
+    return "state";
+  if (RANGE_RE.test(text))
+    return "range";
+  if (LENGTH_RE.test(text))
+    return "length";
+  if (ORDER_RE.test(text))
+    return "ordering";
+  if (CANON_RE.test(text))
+    return "canonicalization";
+  return "requirement";
+}
+function relevanceFor(kind, text) {
+  if (/\b(auth|encrypt|signature|certificate|key|nonce|token|permission|credential)\b/i.test(text))
+    return "high";
+  if (kind === "state" || kind === "rejection")
+    return "high";
+  if (kind === "range" || kind === "length")
+    return "medium";
+  return "low";
+}
+function subjectFor(text) {
+  const match = /(?:the|a|an)\s+([A-Za-z0-9_.-]+(?:\s+[A-Za-z0-9_.-]+){0,4})\s+(?:MUST|SHALL|SHOULD|MAY|is|required|contains|has)\b/i.exec(text);
+  return match?.[1]?.trim();
+}
+function summarize(text) {
+  return text.replace(/\s+/g, " ").slice(0, 180).replace(/[.;:,\s]+$/g, "");
+}
+function extractSpecInvariants(opts) {
+  const max = opts.maxInvariants ?? 40;
+  const warnings = [];
+  const lines = splitLines(opts.specText);
+  const candidates = sentences(lines).filter((s) => hasNormativeSignal(s.text)).slice(0, max);
+  if (candidates.length === max)
+    warnings.push(`capped invariants at ${max}; raise --max-invariants to widen extraction`);
+  if (candidates.length === 0)
+    warnings.push("no normative invariants found; spec may need OCR cleanup or LLM extraction");
+  const invariants = candidates.map((c, idx) => {
+    const kind = kindFor(c.text);
+    const summary = summarize(c.text);
+    return {
+      id: `inv-${String(idx + 1).padStart(3, "0")}-${slug(summary)}`,
+      kind,
+      summary,
+      rule: c.text,
+      ...subjectFor(c.text) ? { subject: subjectFor(c.text) } : {},
+      citations: [{ spec: opts.specName, ...c.section ? { section: c.section } : {}, lineStart: c.n, lineEnd: c.n, text: c.text }],
+      securityRelevance: relevanceFor(kind, c.text)
+    };
+  });
+  return {
+    mode: "specdrift",
+    stage: "extract",
+    spec: opts.specName,
+    invariants,
+    warnings
+  };
+}
+
+// packages/core/dist/specdrift/map.js
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "that",
+  "this",
+  "with",
+  "from",
+  "when",
+  "while",
+  "must",
+  "shall",
+  "should",
+  "not",
+  "may",
+  "been",
+  "have",
+  "has",
+  "are",
+  "is",
+  "be",
+  "for",
+  "into",
+  "whose",
+  "their",
+  "there",
+  "then",
+  "than",
+  "frame",
+  "field",
+  "message",
+  "payload",
+  "implementation",
+  "implementations"
+]);
+var KIND_HINTS = {
+  range: [/\b(?:len|length|size|limit|max|min|range|bounds?)\b/i, /[<>]=?|\bbetween\b/i],
+  length: [/\b(?:len|length|size|payload|bytes?|octets?)\b/i, /[<>]=?/],
+  ordering: [/\b(?:before|after|state|phase|order|seq|sequence)\b/i],
+  state: [/\b(?:state|phase|handshake|session|stream|open|closed|init)\b/i],
+  rejection: [/\b(?:reject|invalid|error|fail|abort|discard|close|return|throw)\b/i],
+  canonicalization: [/\b(?:canonical|normalize|normalise|lower|upper|duplicate|unique)\b/i],
+  requirement: [/\b(?:validate|check|require|assert|if|return|throw)\b/i]
+};
+var SOURCE_EXTS = /* @__PURE__ */ new Set([
+  ".c",
+  ".h",
+  ".cc",
+  ".cpp",
+  ".cxx",
+  ".hpp",
+  ".rs",
+  ".go",
+  ".java",
+  ".kt",
+  ".py",
+  ".js",
+  ".ts",
+  ".jsx",
+  ".tsx"
+]);
+function termsFor(invariant) {
+  const raw = `${invariant.subject ?? ""} ${invariant.summary} ${invariant.rule}`.toLowerCase().replace(/[`*_]/g, " ").match(/[a-z][a-z0-9-]{2,}/g) ?? [];
+  const out = [];
+  for (const term of raw) {
+    const normalized = term.replace(/-/g, "");
+    if (STOPWORDS.has(term) || STOPWORDS.has(normalized))
+      continue;
+    if (!out.includes(term))
+      out.push(term);
+    if (out.length >= 12)
+      break;
+  }
+  return out;
+}
+function snippet(lines, line) {
+  const start = Math.max(1, line - 2);
+  const end = Math.min(lines.length, line + 2);
+  const text = lines.slice(start - 1, end).map((l, idx) => `${start + idx}: ${l}`).join("\n");
+  return { lineStart: start, lineEnd: end, text };
+}
+function scoreLine(invariant, line, terms) {
+  const lowered = line.toLowerCase();
+  const matchedTerms = terms.filter((term) => lowered.includes(term));
+  let score = matchedTerms.length;
+  for (const hint of KIND_HINTS[invariant.kind])
+    if (hint.test(line))
+      score += 2;
+  if (/\b(if|switch|case|return|throw|goto|break|continue)\b/.test(line))
+    score += 1;
+  if (/^\s*(\/\/|\*|#)/.test(line))
+    score -= 2;
+  return { score, matchedTerms };
+}
+function mapInvariantsToImplementation(opts) {
+  const warnings = [];
+  const files = collectScopeFiles(opts.sourceRoot, { maxFiles: opts.maxFiles ?? 400, extensions: SOURCE_EXTS });
+  if (files.length === (opts.maxFiles ?? 400))
+    warnings.push(`source file scan capped at ${files.length}; raise --max-files to widen mapping`);
+  const candidates = [];
+  const maxPerInvariant = opts.maxCandidatesPerInvariant ?? 5;
+  for (const invariant of opts.invariants) {
+    const terms = termsFor(invariant);
+    if (terms.length === 0)
+      continue;
+    const ranked = [];
+    for (const file of files) {
+      let source;
+      try {
+        source = readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+      const lines = source.split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        const { score, matchedTerms } = scoreLine(invariant, lines[i] ?? "", terms);
+        if (score < 3 || matchedTerms.length === 0)
+          continue;
+        const snip = snippet(lines, i + 1);
+        ranked.push({
+          invariantId: invariant.id,
+          file: relative(opts.sourceRoot, file),
+          lineStart: snip.lineStart,
+          lineEnd: snip.lineEnd,
+          snippet: snip.text,
+          matchedTerms,
+          reason: `${invariant.kind} invariant terms matched implementation code`,
+          confidence: Math.min(0.95, 0.25 + score * 0.08),
+          status: "candidate",
+          rawScore: score
+        });
+      }
+    }
+    ranked.sort((a, b) => b.rawScore - a.rawScore || a.file.localeCompare(b.file) || a.lineStart - b.lineStart);
+    candidates.push(...ranked.slice(0, maxPerInvariant).map(({ rawScore: _rawScore, ...candidate }) => candidate));
+  }
+  if (opts.invariants.length > 0 && candidates.length === 0)
+    warnings.push("no implementation candidates matched extracted invariants");
+  return { candidates, warnings };
+}
+function runSpecdriftScan(opts) {
+  const extracted = extractSpecInvariants({
+    specName: opts.specName,
+    specText: opts.specText,
+    ...opts.maxInvariants ? { maxInvariants: opts.maxInvariants } : {}
+  });
+  const mapped = mapInvariantsToImplementation({
+    sourceRoot: opts.sourceRoot,
+    invariants: extracted.invariants,
+    ...opts.maxFiles ? { maxFiles: opts.maxFiles } : {},
+    ...opts.maxCandidatesPerInvariant ? { maxCandidatesPerInvariant: opts.maxCandidatesPerInvariant } : {}
+  });
+  return {
+    mode: "specdrift",
+    stage: "scan",
+    spec: opts.specName,
+    source: opts.sourceRoot,
+    invariants: extracted.invariants,
+    candidates: mapped.candidates,
+    warnings: [...extracted.warnings, ...mapped.warnings]
+  };
+}
+
+// packages/core/dist/specdrift/plan.js
+function adapterFor(invariant, candidate) {
+  const file = candidate.file.toLowerCase();
+  if (/\b(kernel|net|drivers)\b/.test(file))
+    return "kernel-repro";
+  if (invariant.kind === "state" || invariant.kind === "ordering")
+    return "stateful-transcript";
+  if (/\.(c|h|cc|cpp|cxx|rs|go)$/i.test(file) && (invariant.kind === "range" || invariant.kind === "length" || invariant.kind === "rejection"))
+    return "raw-bytes";
+  if (/\.(js|ts|py|java|kt)$/i.test(file))
+    return "unit-test";
+  return "request-response";
+}
+function questionFor(invariant, candidate) {
+  const subject = invariant.subject ? ` for ${invariant.subject}` : "";
+  if (invariant.kind === "rejection") {
+    return `Does ${candidate.file}:${candidate.lineStart} reject inputs that violate the spec rule${subject}: ${invariant.summary}?`;
+  }
+  if (invariant.kind === "state" || invariant.kind === "ordering") {
+    return `Can an input transcript reach ${candidate.file}:${candidate.lineStart} in an order/state forbidden by the spec rule${subject}: ${invariant.summary}?`;
+  }
+  if (invariant.kind === "range" || invariant.kind === "length") {
+    return `Does ${candidate.file}:${candidate.lineStart} enforce the spec bound${subject}: ${invariant.summary}?`;
+  }
+  return `Does ${candidate.file}:${candidate.lineStart} implement the spec invariant${subject}: ${invariant.summary}?`;
+}
+function planSpecdriftHypotheses(opts) {
+  const byInvariant = new Map(opts.scan.invariants.map((inv) => [inv.id, inv]));
+  const max = opts.maxHypotheses ?? 20;
+  const hypotheses = [];
+  for (const candidate of opts.scan.candidates) {
+    const invariant = byInvariant.get(candidate.invariantId);
+    if (!invariant)
+      continue;
+    const suggestedAdapter = adapterFor(invariant, candidate);
+    hypotheses.push({
+      id: `hyp-${String(hypotheses.length + 1).padStart(3, "0")}-${invariant.id.replace(/^inv-\d+-/, "").slice(0, 40)}`,
+      invariantId: invariant.id,
+      candidateFile: candidate.file,
+      candidateLineStart: candidate.lineStart,
+      candidateLineEnd: candidate.lineEnd,
+      question: questionFor(invariant, candidate),
+      suggestedAdapter,
+      rationale: `Spec invariant (${invariant.kind}, ${invariant.securityRelevance} relevance) matched ${candidate.matchedTerms.join(", ")} in candidate code. This is a hypothesis only; adapter execution or skeptic review must prove/refute behavior.`,
+      status: "hypothesis",
+      confidence: Math.min(0.9, candidate.confidence * (invariant.securityRelevance === "high" ? 1 : 0.85))
+    });
+    if (hypotheses.length >= max)
+      break;
+  }
+  return hypotheses;
+}
+function runSpecdriftPlan(opts) {
+  const scan = runSpecdriftScan(opts);
+  return {
+    ...scan,
+    stage: "plan",
+    hypotheses: planSpecdriftHypotheses({ scan, ...opts.maxHypotheses ? { maxHypotheses: opts.maxHypotheses } : {} })
+  };
+}
+
+export {
+  extractSpecInvariants,
+  mapInvariantsToImplementation,
+  runSpecdriftScan,
+  planSpecdriftHypotheses,
+  runSpecdriftPlan
+};