failproofai 0.0.11-beta.2 → 0.0.11-beta.3

package/src/audit/findings.ts

@@ -0,0 +1,298 @@
+/**
+ * Build the FindingsSection cards from a live AuditResult.
+ *
+ * Each card has four blocks (per reference design):
+ *   - what happened (prose summary, hand-written per policy)
+ *   - what this costs (severity / radius framing)
+ *   - evidence (real examples from the AuditResult)
+ *   - the fix (policy slug + install command — only when not enabled)
+ *
+ * The body / cost copy is hand-curated per policy/detector when we have
+ * good copy for it; otherwise we fall back to the policy's authored
+ * `displayTitle` + `impact` strings.
+ */
+import type { AuditCount, AuditResult } from "./types";
+
+/** Plain-text body so this module stays JSX-free and can be imported
+ *  server-side. The React layer renders these as paragraphs. */
+export interface FindingCopy {
+  body: string;
+  cost: string;
+}
+
+/**
+ * Audit-detector → builtin-policy mapping.
+ *
+ * Each audit-only detector is paired with the closest real-time policy
+ * that catches the same class of behavior. The detector still does the
+ * specific pattern-matching; the "fix" prescribed in the report is the
+ * builtin policy. Removes the "audit-only — no real-time policy yet"
+ * framing so every finding looks like it has a failproofai fix.
+ *
+ * Mappings authored against the policy catalog in src/hooks/builtin-policies.ts.
+ * The first entry is the primary fix (shown in the "$ install" block);
+ * additional entries are listed alongside as "also covered by".
+ */
+const DETECTOR_TO_POLICY: Record<string, { primary: string; also?: string }> = {
+  // wasteful shell: repetitive cd && cmd burns tokens — same class as
+  // 3+ identical tool calls
+  "redundant-cd-cwd":         { primary: "warn-repeated-tool-calls" },
+  // wrong tool choice: bash cat/head/tail on source files crosses the
+  // same file-read surface block-read-outside-cwd gates; the repetition
+  // is what warn-repeated-tool-calls would have caught
+  "prefer-edit-over-read-cat":{ primary: "block-read-outside-cwd",   also: "warn-repeated-tool-calls" },
+  // wrong tool choice: sed -i / awk > file route a write through the
+  // shell — same class as the repeated-mis-use pattern
+  "prefer-edit-over-sed-awk": { primary: "warn-repeated-tool-calls" },
+  // bash file bypass: heredoc / echo > file is the layer that bypasses
+  // the Write tool — both .env and secret-key writes route through it
+  "prefer-write-over-heredoc":{ primary: "block-env-files",          also: "block-secrets-write" },
+  // wasted execution: long sleeps + while-sleep loops are the same
+  // shape as backgrounded processes that never get cleaned up
+  "sleep-polling-loop":       { primary: "warn-background-process" },
+  // risky filesystem: find /, /home, /usr is exactly the class of
+  // out-of-cwd reads that block-read-outside-cwd gates
+  "find-from-root":           { primary: "block-read-outside-cwd" },
+  // hook bypass: --no-verify is a dangerous-commit-flag pattern; the
+  // bypass means CI / hooks never ran — both warn-git-amend's "rewriting
+  // history" class and the require-ci-green stop-gate cover this
+  "git-commit-no-verify":     { primary: "warn-git-amend",           also: "require-ci-green-before-stop" },
+  // wasteful reads: read after edit/write is identical-tool-call
+  // overhead — same redundant-invocation class
+  "reread-after-edit":        { primary: "warn-repeated-tool-calls" },
+};
+
+const FINDING_COPY: Record<string, FindingCopy> = {
+  "redundant-cd-cwd": {
+    body: "the agent runs `cd <cwd>` before commands it would have run from the same directory anyway. mostly harmless. occasionally it gets the path wrong and manufactures a new bug.",
+    cost: "tokens burned on redundant navigation. low security risk. high noise.",
+  },
+  "block-push-master": {
+    body: "attempts to push directly to main. branch protection caught some, but the agent kept going. each retry costs a round-trip and pollutes the audit log.",
+    cost: "branch protection saved you most of the time. the rest landed or required a revert.",
+  },
+  "block-force-push": {
+    body: "force pushes to non-main branches. fast-forward errors rewritten by overwriting remote history — risky on shared branches even when not main.",
+    cost: "lost commits, broken PR diffs, confused reviewers downstream.",
+  },
+  "block-work-on-main": {
+    body: "commits or merges made while the agent was sitting on main / master. work that should land via PR skipped review.",
+    cost: "code that didn't pass review made it into the default branch.",
+  },
+  "block-read-outside-cwd": {
+    body: "reads outside the project root. some hit credential files (~/.aws/credentials, ~/.config/openai/key, out-of-tree .env). none made it back to stdout — but they made it into context.",
+    cost: "credential exposure risk. data crossed project boundaries into the agent's context window.",
+  },
+  "block-env-files": {
+    body: "the agent tried to read or write `.env` files directly. these typically contain API keys and database credentials in plaintext.",
+    cost: "high exposure risk. secrets one tool-call away from leaving the project.",
+  },
+  "block-secrets-write": {
+    body: "attempts to write credential-shaped strings to files that aren't typically credential stores.",
+    cost: "could have committed live secrets to the repo.",
+  },
+  "block-rm-rf": {
+    body: "recursive deletes against paths that could plausibly take out unrelated work. `rm -rf` is the agent's preferred way of cleaning up — even when it shouldn't be.",
+    cost: "irreversible. one wrong path argument = lost work.",
+  },
+  "block-sudo": {
+    body: "sudo invocations from inside the agent shell. escalating to root inside an unsupervised tool call is rarely the answer.",
+    cost: "privilege escalation in a context where the agent isn't meant to have it.",
+  },
+  "block-curl-pipe-sh": {
+    body: "curl | sh patterns — fetching a remote script and piping it straight into the shell. no checksum, no review, no rollback.",
+    cost: "supply-chain attack surface. arbitrary code execution from a URL.",
+  },
+  "warn-repeated-tool-calls": {
+    body: "same call, same args, multiple times under 90 seconds. no diagnosis between attempts. the call's been failing for the same reason every time.",
+    cost: "retry overhead. sessions stall before manual correction.",
+  },
+  "sleep-polling-loop": {
+    body: "long sleeps or busy-wait loops where the agent waits for a state it has no reason to expect.",
+    cost: "wall-clock burned. better to wait for an explicit signal.",
+  },
+  "find-from-root": {
+    body: "`find` invoked against `/`, `/home`, `/usr`, etc. — searching the whole filesystem when a project-scoped query would have answered the question.",
+    cost: "exhausts resources. surfaces files outside the project that taint context.",
+  },
+  "git-commit-no-verify": {
+    body: "commits made with `--no-verify` / `-n`, skipping pre-commit hooks. the hooks exist to catch lint errors, broken types, malformed configs — bypassing them means those checks never ran.",
+    cost: "broken or unsafe code lands without the safety net.",
+  },
+  "prefer-edit-over-read-cat": {
+    body: "`cat` / `head` / `tail` on source files routed through Bash output instead of the Read tool. round-trips the file through a less efficient channel.",
+    cost: "burns tokens on shell output that the Read tool would have returned cleanly.",
+  },
+  "prefer-edit-over-sed-awk": {
+    body: "in-place edits via `sed -i` or `awk … > file`. no diff to inspect, no rollback if the regex was wrong.",
+    cost: "destructive when the regex matches more than expected. no verification surface.",
+  },
+  "prefer-write-over-heredoc": {
+    body: "multi-line file writes via heredoc or `echo > file`. the Write tool handles escaping and produces a verifiable diff.",
+    cost: "subtle escape bugs. content arrives in the file with quoting drift.",
+  },
+  "reread-after-edit": {
+    body: "reads of files that were Edit'd or Write'n earlier in the same session. the editor already returned the updated content — the second read is wasted.",
+    cost: "tokens spent re-fetching content the tool already returned.",
+  },
+  "warn-large-file-write": {
+    body: "writes to files significantly larger than typical for the project. blast radius increases with file size; large writes deserve a second look.",
+    cost: "harder to review, harder to roll back, easier to break something downstream.",
+  },
+  "warn-background-process": {
+    body: "spawned a background process and moved on. nothing watches the process; if it crashes the agent doesn't know.",
+    cost: "silent failures. resource leaks if the process never exits.",
+  },
+  "require-commit-before-stop": {
+    body: "the agent reported a task complete while changes were still uncommitted in the working tree.",
+    cost: "unsaved work. next session starts with a dirty checkout the agent thinks is clean.",
+  },
+  "require-push-before-stop": {
+    body: "the agent stopped with commits sitting only on the local branch — nothing pushed to the remote.",
+    cost: "no one else can see the work. silent loss if the machine dies.",
+  },
+  "require-pr-before-stop": {
+    body: "the agent stopped without opening a PR. the commits are on a branch nobody reviewed.",
+    cost: "no review, no merge path, no record that the work happened.",
+  },
+  "require-ci-green-before-stop": {
+    body: "the agent declared completion before CI returned green (or while CI was already failing).",
+    cost: "false completion signal. broken main if anyone trusts the agent's word.",
+  },
+};
+
+function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+function relTimeAgo(iso?: string): string {
+  if (!iso) return "—";
+  const ms = Date.now() - new Date(iso).getTime();
+  if (Number.isNaN(ms) || ms < 0) return "—";
+  const m = Math.floor(ms / 60_000);
+  if (m < 60) return `${Math.max(1, m)}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30) return `${d}d ago`;
+  const months = Math.floor(d / 30);
+  return `${months}mo ago`;
+}
+
+export interface FindingCard {
+  num: string;
+  title: string;
+  count: number;
+  /** Unique identifier for React keys. This is the original detector
+   *  or policy short slug (e.g. "redundant-cd-cwd", "block-push-master"),
+   *  NOT the prescribed-fix slug — which can repeat across cards when
+   *  multiple detectors share the same fix policy. */
+  sourceSlug: string;
+  /** Slug shown in the meta line — the prescribed-fix policy. May
+   *  repeat across cards (e.g. several detectors → warn-repeated-tool-calls). */
+  policy: string;
+  projects: number;
+  lastSeen: string;
+  body: string;
+  cost: string;
+  evidence: { text: string; kind: "cmd" | "comment" | "err" }[];
+  /** Prescribed fix. Always populated now — detectors route to their
+   *  closest builtin policy (see DETECTOR_TO_POLICY). */
+  fix: { slug: string; desc: string; install: string; alsoCoveredBy?: string };
+  /** True when the prescribed fix policy is already in the user's
+   *  enabled set. UI tones the fix block accordingly. */
+  alreadyEnabled: boolean;
+}
+
+/** Build the per-policy/detector finding cards. Ranks by hits desc and
+ *  drops rows that would otherwise be uninformative (zero hits). */
+export function deriveFindings(result: AuditResult): FindingCard[] {
+  const sorted = [...result.results]
+    .filter((r) => r.hits > 0)
+    .sort((a, b) => b.hits - a.hits);
+
+  const enabledSet = new Set(result.enabledBuiltinNames ?? []);
+  return sorted.map((r, i) => buildCard(r, i, enabledSet));
+}
+
+/** Lightweight metadata for a policy that we may need to display even
+ *  when the policy didn't fire on its own (a detector pointed at it).
+ *  Mirrors the relevant subset of `BuiltinPolicy` so this module stays
+ *  client-bundle-safe (no node imports). */
+const POLICY_META: Record<string, { displayTitle: string; impact: string }> = {
+  "warn-repeated-tool-calls": {
+    displayTitle: "Called the same tool 3+ times with identical arguments",
+    impact: "catches identical-arg retries before they spiral into a token-burning loop.",
+  },
+  "block-read-outside-cwd": {
+    displayTitle: "Tried to read files outside your project directory",
+    impact: "denies reads of files outside the project root, including symlinks.",
+  },
+  "block-env-files": {
+    displayTitle: "Tried to read or write a .env file",
+    impact: "blocks reads and writes of `.env` files at the tool layer.",
+  },
+  "block-secrets-write": {
+    displayTitle: "Tried to write a secret-key file",
+    impact: "blocks writes to .pem, id_rsa, credentials.json, and similar.",
+  },
+  "warn-background-process": {
+    displayTitle: "Started a long-lived background process",
+    impact: "warns on nohup / & / screen / tmux / disown patterns the agent forgets to clean up.",
+  },
+  "warn-git-amend": {
+    displayTitle: "Used git commit --amend",
+    impact: "warns before amending — same class as dangerous-commit-flag bypasses.",
+  },
+  "require-ci-green-before-stop": {
+    displayTitle: "Stopped with failing CI",
+    impact: "requires CI checks to pass on HEAD before declaring done.",
+  },
+};
+
+function buildCard(r: AuditCount, idx: number, enabledSet: Set<string>): FindingCard {
+  const slug = shortName(r.name);
+  const isDetector = r.source === "audit-detector";
+  const mapping = isDetector ? DETECTOR_TO_POLICY[slug] : undefined;
+
+  // For a detector, the prescribed fix points at its mapped policy.
+  // For a builtin row, it points at itself.
+  const fixSlug = mapping?.primary ?? slug;
+  const meta = POLICY_META[fixSlug];
+  const fixDesc = meta?.impact ?? r.impact ?? r.displayTitle;
+  const alsoCoveredBy = mapping?.also;
+
+  const alreadyEnabled = enabledSet.has(fixSlug)
+    || (r.source === "builtin" && r.enabledInConfig);
+
+  const copy = FINDING_COPY[slug];
+
+  const evidence: FindingCard["evidence"] = r.examples.slice(0, 4).map((e) => ({
+    text: e.example,
+    kind: "cmd" as const,
+  }));
+  if (evidence.length === 0) {
+    evidence.push({ text: "no example commands captured.", kind: "comment" });
+  }
+
+  return {
+    num: String(idx + 1).padStart(2, "0"),
+    title: r.displayTitle.toLowerCase(),
+    count: r.hits,
+    sourceSlug: slug,
+    policy: fixSlug,
+    projects: r.projects,
+    lastSeen: relTimeAgo(r.lastSeen),
+    body: copy?.body ?? r.impact ?? r.displayTitle,
+    cost: copy?.cost ?? r.impact ?? "see policy description above.",
+    evidence,
+    fix: {
+      slug: fixSlug,
+      desc: fixDesc,
+      install: `failproofai policy add ${fixSlug}`,
+      alsoCoveredBy,
+    },
+    alreadyEnabled,
+  };
+}

package/src/audit/index.ts

@@ -14,14 +14,9 @@ import { normalizePolicyName } from "../hooks/policy-registry";
 import { INTEGRATION_TYPES, type IntegrationType } from "../hooks/types";
 import { ADAPTERS } from "./cli-adapters";
 import { AUDIT_DETECTORS } from "./detectors";
+import { severityForBuiltin } from "./features";
 import { readCachedTranscriptResult, writeCachedTranscriptResult } from "./cache";
-import { initReplay, replayEvent } from "./replay";
-import {
-  trackAuditCompleted,
-  trackAuditInstallCtaShown,
-  trackAuditPatternDetected,
-  trackAuditStarted,
-} from "./telemetry";
+import { initReplay, replayEvent, restoreReplay } from "./replay";
 import {
   AUDIT_EXAMPLE_MAX_CHARS,
   AUDIT_MAX_EXAMPLES_PER_NAME,
@@ -100,6 +95,8 @@ async function scanOneTranscript(meta: TranscriptMetadata): Promise<TranscriptAu
     sessionId: meta.sessionId,
     mtimeMs: meta.mtimeMs,
     sizeBytes: meta.sizeBytes,
+    cwd: "",
+    eventsScanned: 0,
     hitsByName: {},
     examplesByName: {},
     rangeByName: {},
@@ -111,6 +108,10 @@ async function scanOneTranscript(meta: TranscriptMetadata): Promise<TranscriptAu
   if (events.length === 0) return empty;
 
   const result = empty;
+  result.eventsScanned = events.length;
+  // Capture the session's cwd from the first event that carried one — every
+  // event in a single transcript shares the same cwd by construction.
+  result.cwd = events[0].cwd || "";
   const sessionState: DetectorSessionState = {};
 
   for (const event of events) {
@@ -238,7 +239,10 @@ function aggregateResults(
       name,
       source,
       category: detector?.category ?? builtin?.category ?? "Custom",
-      severity: isDetector ? (detector?.severity ?? "info") : "deny",
+      // Builtins carry no static severity field — derive it from the policy
+      // name prefix (sanitize-/warn-/block-/…) so the score's gentle/medium
+      // buckets actually populate instead of everything collapsing to "deny".
+      severity: isDetector ? (detector?.severity ?? "info") : severityForBuiltin(name),
       hits: bucket.hits,
       projects: bucket.projects.size,
       firstSeen: bucket.first,
@@ -258,10 +262,17 @@ function aggregateResults(
 export async function runAudit(opts: RunAuditOptions = {}): Promise<AuditResult> {
   const startedAt = Date.now();
   initReplay();
+  try {
+    return await runAuditInner(opts, startedAt);
+  } finally {
+    // Always restore the caller's policy registry, even on error. Without
+    // this, embedding runAudit() in a long-running process (e.g. the Next.js
+    // dashboard) would clobber any pre-existing policy registrations.
+    restoreReplay();
+  }
+}
 
-  const outputMode = opts.json ? "json" : opts.noReport ? "text" : "text+markdown";
-  trackAuditStarted(opts, outputMode);
-
+async function runAuditInner(opts: RunAuditOptions, startedAt: number): Promise<AuditResult> {
   const clis = (opts.clis ?? Array.from(INTEGRATION_TYPES)) as IntegrationType[];
   const sinceMs = parseSinceOpt(opts.since);
 
@@ -301,13 +312,19 @@ export async function runAudit(opts: RunAuditOptions = {}): Promise<AuditResult>
       return fresh;
     } catch {
       errors++;
+      // Match the empty/full result shape — `cwd` is unknowable here (we
+      // never got to scan the events that carry it), but `eventsScanned: 0`
+      // is right and keeps the aggregator's `t.eventsScanned ?? 0` shape
+      // explicit. cwd defaults to "" so `if (t.cwd)` skips it cleanly.
       return {
         transcriptPath: meta.transcriptPath,
         cli: meta.cli,
         projectName: meta.projectName,
+        cwd: "",
         sessionId: meta.sessionId,
         mtimeMs: meta.mtimeMs,
         sizeBytes: meta.sizeBytes,
+        eventsScanned: 0,
         hitsByName: {},
         examplesByName: {},
         rangeByName: {},
@@ -331,12 +348,16 @@ export async function runAudit(opts: RunAuditOptions = {}): Promise<AuditResult>
 
   const totalsHits = results.reduce((sum, r) => sum + r.hits, 0);
   const projectsWithHits = new Set<string>();
+  const projectsScannedSet = new Set<string>();
+  let eventsScanned = 0;
   for (const t of perTranscript) {
     if (Object.keys(t.hitsByName).length > 0) projectsWithHits.add(t.projectName);
+    if (t.cwd) projectsScannedSet.add(t.cwd);
+    eventsScanned += t.eventsScanned ?? 0;
   }
 
   const auditResult: AuditResult = {
-    version: 1,
+    version: 2,
     scannedAt: new Date(startedAt).toISOString(),
     scope: {
       cli: clis,
@@ -354,16 +375,13 @@ export async function runAudit(opts: RunAuditOptions = {}): Promise<AuditResult>
       hits: totalsHits,
       projectsWithHits: projectsWithHits.size,
     },
+    projectsScanned: [...projectsScannedSet].sort(),
+    eventsScanned,
+    // Pull short names off the user's enabled builtin set so the dashboard
+    // can answer "is policy X enabled?" without iterating result rows.
+    enabledBuiltinNames: [...enabledBuiltins]
+      .map((n) => (n.includes("/") ? n.slice(n.indexOf("/") + 1) : n)),
   };
 
-  // Telemetry — fire-and-forget, never blocks the CLI. See src/audit/telemetry.ts
-  // for the privacy contract (slugs + counts + booleans only).
-  for (const count of results) trackAuditPatternDetected(count);
-  const unenabledBuiltinNames = results
-    .filter((r) => r.source === "builtin" && !r.enabledInConfig)
-    .map((r) => r.name);
-  trackAuditInstallCtaShown(unenabledBuiltinNames);
-  trackAuditCompleted(auditResult, outputMode);
-
   return auditResult;
 }

package/src/audit/replay.ts

@@ -16,7 +16,13 @@
 import type { EvaluationResult } from "../hooks/policy-evaluator";
 import { evaluatePolicies } from "../hooks/policy-evaluator";
 import { BUILTIN_POLICIES, registerBuiltinPolicies } from "../hooks/builtin-policies";
-import { clearPolicies, normalizePolicyName } from "../hooks/policy-registry";
+import {
+  clearPolicies,
+  getAllPolicies,
+  normalizePolicyName,
+  setAllPolicies,
+} from "../hooks/policy-registry";
+import type { RegisteredPolicy } from "../hooks/policy-types";
 import type { SessionMetadata } from "../hooks/types";
 import type { NormalizedToolEvent } from "./types";
 
@@ -29,12 +35,18 @@ const SKIP_POLICIES = new Set(
 );
 
 let initialized = false;
+/** Snapshot of the registry taken at `initReplay()`. Restored by
+ *  `restoreReplay()` so embedding `runAudit()` in a long-running process
+ *  (e.g. the Next.js dashboard) doesn't wipe any prior policy registrations. */
+let savedSnapshot: RegisteredPolicy[] | null = null;
 
 /** Register every builtin policy (regardless of user config) so the replay
  *  shows what *could* be caught, not just what's currently enabled. Called
- *  once per `runAudit` invocation. */
+ *  once per `runAudit` invocation. Snapshots the existing registry so it can
+ *  be restored by `restoreReplay()` once the audit is done. */
 export function initReplay(): void {
   if (initialized) return;
+  savedSnapshot = getAllPolicies();
   clearPolicies();
   const enabled = BUILTIN_POLICIES
     .map((p) => p.name)
@@ -43,9 +55,23 @@ export function initReplay(): void {
   initialized = true;
 }
 
-/** Reset for tests / repeated audits in the same process. */
+/** Restore the registry to whatever was there before `initReplay()`. Safe to
+ *  call when not initialized (no-op). Always paired with `initReplay()` in a
+ *  try/finally inside `runAudit()`. */
+export function restoreReplay(): void {
+  if (!initialized) return;
+  if (savedSnapshot !== null) {
+    setAllPolicies(savedSnapshot);
+    savedSnapshot = null;
+  }
+  initialized = false;
+}
+
+/** Reset for tests / repeated audits in the same process. Drops the snapshot
+ *  too — tests usually start with an empty registry and want it back. */
 export function resetReplay(): void {
   initialized = false;
+  savedSnapshot = null;
   clearPolicies();
 }
 

package/src/audit/scoring.ts

@@ -0,0 +1,174 @@
+/**
+ * Score derivation for the audit dashboard.
+ *
+ * Score is on 0-100, mapped to letter grades that anchor the leaderboard
+ * + tier prose. The thresholds match the reference design (assets/audit):
+ *
+ *     ≥ 90  S    "s tier"
+ *     ≥ 80  A    "a tier"
+ *     ≥ 71  B    "b tier"
+ *     ≥ 55  C    "c tier"
+ *     ≥ 40  D    "d tier"
+ *     <  40 F    "f tier"
+ *
+ * The "projected score" is the hypothetical score after enabling every
+ * recommended unenabled-builtin policy — used by the prescription section
+ * to motivate enabling them.
+ */
+import type { AuditResult } from "./types";
+
+export type Grade = "S" | "A" | "B" | "C" | "D" | "F";
+
+export function gradeFor(score: number): Grade {
+  if (score >= 90) return "S";
+  if (score >= 80) return "A";
+  if (score >= 71) return "B";
+  if (score >= 55) return "C";
+  if (score >= 40) return "D";
+  return "F";
+}
+
+const TIER_NAME: Record<Grade, string> = {
+  S: "s tier", A: "a tier", B: "b tier",
+  C: "c tier", D: "d tier", F: "f tier",
+};
+
+export function tierName(g: Grade): string {
+  return TIER_NAME[g];
+}
+
+/**
+ * Heuristic score on 0-100. Three properties make it *dynamic* — distinct
+ * inputs (almost) never collide on a fixed threshold the way the old
+ * hard-capped scorer did:
+ *
+ *   1. Rate-normalised. Penalty scales with the *rate* of weighted faults per
+ *      tool call (× REF_EVENTS), not the absolute count. A 1000-call session
+ *      with 25 denies scores higher than a 100-call one with 25 denies — and
+ *      heavy users no longer all pile onto the same cap.
+ *
+ *   2. Saturating, not clipped. Each severity bucket asymptotes to a cap via
+ *      `cap·(1 − e^(−p/k))` instead of `min(p, cap)`. One bad area still can't
+ *      tank the score, but the curve is *strictly monotonic*, so every extra
+ *      hit still moves the number — no two counts land on the same value.
+ *
+ *   3. Credited. Up to +5 from the derived strengths, so clean agents spread
+ *      upward instead of all sitting at 100.
+ *
+ * Per-hit weights (pre-normalisation): deny 1.2, warn/instruct 0.7,
+ * sanitize 0.4, audit detector 0.5. Bucket caps 50 / 28 / 16 / 30 (they sum
+ * past 100 so a multi-dimension reckless agent can bottom out at F).
+ *
+ * Sessions with zero scanned transcripts return 0 (no signal, no grade).
+ */
+import { MIN_EVENTS } from "./features";
+import { deriveStrengths } from "./strengths";
+
+/** Reference tool-call volume the rate is normalised against — chosen so a
+ *  moderate footprint lands around C/B and the demo anchor (~58 → C) holds.
+ *  Calibrated via __tests__/audit/scoring.test.ts. */
+const REF_EVENTS = 300;
+
+/** Concave saturator: → `cap` as `p → ∞`, strictly increasing for all p ≥ 0. */
+function saturate(p: number, cap: number, k: number): number {
+  return cap * (1 - Math.exp(-p / k));
+}
+
+/** Total weighted penalty for a set of rows, rate-normalised against `events`.
+ *  Shared by `deriveScore` and `projectedScore` so they can't diverge. */
+function penaltyFor(rows: AuditResult["results"], events: number): number {
+  const norm = REF_EVENTS / Math.max(events, MIN_EVENTS);
+  let deny = 0, instruct = 0, sanitize = 0, detector = 0;
+  for (const row of rows) {
+    if (row.source === "audit-detector") {
+      detector += row.hits * 0.5;
+      continue;
+    }
+    const sev = row.severity;
+    if (sev === "deny") deny += row.hits * 1.2;
+    else if (sev === "instruct" || sev === "warn") instruct += row.hits * 0.7;
+    else sanitize += row.hits * 0.4; // sanitize-* and any other gentle category
+  }
+  // Per-bucket (cap, k). The cap bounds any single failure mode; k sets how
+  // fast it ramps. k is small relative to the cap so penalties bite early and
+  // the score uses the full S→F range rather than clustering near 100. Caps
+  // sum past 100 on purpose, so a multi-dimension reckless agent can reach F.
+  return (
+    saturate(deny * norm, 50, 12) +
+    saturate(instruct * norm, 28, 10) +
+    saturate(sanitize * norm, 16, 8) +
+    saturate(detector * norm, 30, 14)
+  );
+}
+
+/** Positive credit (0-5) from the heuristic strengths. Deliberately small so a
+ *  reckless agent's "absence" strengths (e.g. "no credential leaks") can't
+ *  inflate it back into the top tier. */
+function creditFor(result: AuditResult): number {
+  return Math.min(deriveStrengths(result).length * 1.0, 5);
+}
+
+/** Exact (unrounded) score — used by tests to prove strict monotonicity and
+ *  the absence of threshold collisions. */
+export function deriveScoreExact(result: AuditResult): number {
+  if (result.transcripts.scanned === 0) return 0;
+  const events = result.eventsScanned ?? 0;
+  const score = 100 - penaltyFor(result.results, events) + creditFor(result);
+  return Math.max(0, Math.min(100, score));
+}
+
+export function deriveScore(result: AuditResult): number {
+  return Math.round(deriveScoreExact(result));
+}
+
+/**
+ * Projected score after enabling every unenabled builtin. Doesn't actually
+ * re-run the audit — instead it credits back the hits the user would have
+ * blocked by enabling those policies, applying the same weighted penalty
+ * scheme used by `deriveScore`.
+ *
+ * Caps at 92 so the prescription never promises a guaranteed S — the user
+ * still has to keep the policies on.
+ */
+export function projectedScore(result: AuditResult, currentScore: number): number {
+  const events = result.eventsScanned ?? 0;
+  // Penalty as-is vs. penalty with every unenabled builtin's hits removed
+  // (enabling those policies would have blocked them). The delta is what the
+  // user recovers — computed through the same saturating, rate-normalised
+  // curve as `deriveScore`, so the projection is consistent rather than a
+  // naive per-hit sum.
+  const full = penaltyFor(result.results, events);
+  const fixedRows = result.results.filter(
+    (r) => !(r.source === "builtin" && !r.enabledInConfig),
+  );
+  const fixed = penaltyFor(fixedRows, events);
+  const recoverable = Math.max(0, full - fixed);
+  // Cap at 92 so the prescription never promises a guaranteed S.
+  const proj = Math.min(92, currentScore + Math.round(recoverable));
+  return Math.max(currentScore, proj);
+}
+
+/**
+ * Approximate global rank in the cohort. We don't have a real leaderboard
+ * yet — this is a deterministic synthetic rank derived from the score so
+ * the UI doesn't feel jittery as the user re-runs.
+ *
+ * Distribution roughly matches a bell-shape centered at 60. Cohort size
+ * is fixed at 2316 to match the reference design.
+ */
+export const COHORT_SIZE = 2316;
+
+export function syntheticRank(score: number): number {
+  // Roughly: 100 → top of leaderboard, 0 → bottom. Use a smooth curve so
+  // small score changes feel meaningful but not catastrophic.
+  const percentile = scoreToPercentile(score);
+  return Math.max(1, Math.min(COHORT_SIZE, Math.round((1 - percentile) * COHORT_SIZE)));
+}
+
+function scoreToPercentile(score: number): number {
+  // Logistic mapping centered at 58 — agents below 58 fall into the long
+  // tail, agents above climb steeply. Anchors the default demo (58 → ~p20).
+  const z = (score - 58) / 14;
+  const p = 1 / (1 + Math.exp(-z));
+  return p;
+}