@bigsteele/the-prospect 0.2.0 → 0.3.0

package/dist/detect/types.d.ts

@@ -10,6 +10,8 @@
  */
 /** One declared dependency and every place it was actually seen. */
 export interface DepFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     name: string;
     version: string;
     /** Which manifest declared it, repository-relative. */
@@ -53,14 +55,27 @@ export interface VendorFact {
 }
 /** Two or more services doing the same category of work. */
 export interface OverlapFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     category: VendorCategory;
     services: string[];
     call_sites: number;
+    /** What each service was seen doing inside the category, when the code says. */
+    roles?: Record<string, string[]>;
+    /**
+     * Set when the code shows the services doing DIFFERENT jobs inside one
+     * category - Stripe processing on a merchant's own account beside Square
+     * billing the platform, Gemini writing text beside Replicate making images.
+     * A category is not a job. Listed, never deducted; the text is the reason.
+     */
+    distinct?: string;
     on_record?: OnRecord;
 }
 export type RailCategory = "pdf" | "rate-limiting" | "email-templating" | "auth-session" | "queue-scheduler" | "search" | "payments-logic" | "webhook-plumbing" | "parsing-ocr";
 /** A subsystem built by hand where the market sells a rail. */
 export interface HandrolledFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     rail: RailCategory;
     files: string[];
     loc: number;
@@ -76,6 +91,8 @@ export interface HandrolledFact {
 }
 /** A cluster of near-identical code living in more than one file. */
 export interface DuplicateFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     files: string[];
     /** Lines in the repeated block, after normalization. */
     lines: number;
@@ -95,15 +112,25 @@ export interface DuplicateFact {
 }
 /** A runtime file no entrypoint reaches. */
 export interface DeadFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     file: string;
     loc: number;
     /** Why the detector believes nothing reaches it. */
     note: string;
+    /**
+     * A UI-kit scaffold component (shadcn's `components.json` beside it) that no
+     * file imports. Never bundled, so it does not ship; still read and searched.
+     * Listed at a quarter of the weight.
+     */
+    scaffold?: boolean;
     on_record?: OnRecord;
     touches?: string;
 }
 /** A call whose cost multiplies: per request, per row, or on a clock. */
 export interface CostFact {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     file: string;
     shape: "per-request" | "per-row" | "per-schedule";
     /** What is being called - a vendor host or an SDK call name. */
@@ -130,6 +157,8 @@ export interface NorthStar {
 }
 /** A shape in the migrations worth a human minute. Never a verdict. */
 export interface DatabaseFinding {
+    /** Stable id, so a verdict can name this finding: see verdicts.ts. */
+    id?: string;
     kind: "table_without_rls" | "rls_not_forced" | "definer_without_check" | "policy_reaches_anon";
     /** The table, function or policy, schema-qualified where it has one. */
     subject: string;
@@ -145,5 +174,9 @@ export interface DatabaseReading {
     tables: number;
     policies: number;
     definer_functions: number;
+    /** Definer functions whose EXECUTE the migrations revoke from public, anon or authenticated. */
+    definer_execute_revoked: number;
+    /** A guard function the repository carries to check definer grants at runtime, when one is named. */
+    guard?: string;
     findings: DatabaseFinding[];
 }

package/dist/detect/vendors.js

@@ -53,6 +53,43 @@ const KNOWN = [
     { service: "Cal.com", category: "calendar", hosts: /api\.cal\.com$/, env: /^CAL_/ },
     { service: "Calendly", category: "calendar", hosts: /api\.calendly\.com$/, env: /^CALENDLY_/ },
 ];
+const ROLES = {
+    payments: [
+        {
+            role: "processes on a merchant's own account (Connect or OAuth markers)",
+            merchant: true,
+            re: /\/v1\/accounts\b|stripe[-_]account|on_behalf_of|transfer_data|application_fee|oauth2\/(token|authorize|revoke)|refresh_token|merchant_id|connected_account/i,
+        },
+        {
+            role: "bills the platform's own account (subscriptions, its own checkout)",
+            re: /\bsubscriptions?\b|\/v1\/checkout\/sessions|\/v2\/(checkout|subscriptions|invoices)|\binvoices?\b|price_id|\bplan_id\b/i,
+        },
+    ],
+    ai: [
+        { role: "writes text", re: /generateContent|chat\/completions|\/v1\/messages\b|messages\.create|\/completions\b|\bembeddings\b|responses\.create/i },
+        { role: "makes images", re: /\/predictions\b|images\.(generate|edit)|\/images\/generations|\bimagen\b|nano-banana|stable-diffusion|\bsdxl\b|\bflux[-/]|dall-e/i },
+        { role: "makes speech or audio", re: /text-to-speech|\/v1\/audio\/|speech\.create|audio\.transcriptions/i },
+    ],
+};
+/**
+ * A role belongs to a vendor only when it sits ON that vendor's call: the line
+ * that names the vendor, or the few lines under it that finish the same call.
+ * "Nearest vendor within forty lines" credited Gemini with making images because
+ * a `predictions:` type field sat thirty lines from its URL.
+ */
+const ROLE_REACH = 30; // lines under the vendor's line; the role regexes are endpoint-shaped, so this reach stays safe
+/** Every KNOWN service a single line names, by host, env var or import. */
+function vendorsOnLine(line, only) {
+    const out = [];
+    const host = /https?:\/\/([a-z0-9][a-z0-9.-]+\.[a-z]{2,})/i.exec(line)?.[1]?.toLowerCase();
+    const env = /([A-Z][A-Z0-9_]{2,})/.exec(line)?.[1];
+    const spec = /["']((?:npm:)?@?[a-z0-9][a-z0-9._/-]*)["']/i.exec(line)?.[1]?.replace(/^npm:/, "");
+    for (const k of only) {
+        if ((host && k.hosts?.test(host)) || (env && k.env?.test(env)) || (spec && k.sdks?.test(spec)))
+            out.push(k);
+    }
+    return out;
+}
 /** Hosts that are content, not services: fonts, CDNs of the app's own assets, social links. */
 const NOISE_HOST = /(^|\.)(esm\.sh|cdn\.jsdelivr\.net|unpkg\.com|fonts\.(googleapis|gstatic)\.com|githubusercontent\.com|github\.com|linkedin\.com|x\.com|twitter\.com|instagram\.com|facebook\.com|youtube\.com|tiktok\.com|schema\.org|w3\.org|localhost)$/i;
 export async function detectVendors(repo) {
@@ -118,11 +155,67 @@ export async function detectVendors(repo) {
     for (const [category, list] of byCategory) {
         if (category === "other" || list.length < 2)
             continue;
-        overlaps.push({
+        const o = {
             category,
             services: list.map((v) => v.service),
             call_sites: list.reduce((t, v) => t + v.call_sites, 0),
-        });
+        };
+        const roleTable = ROLES[category];
+        if (roleTable) {
+            // Roles, read from the lines near each vendor's own markers.
+            const known = list.map((v) => KNOWN.find((k) => k.service === v.service));
+            const roles = new Map(); // service -> role -> where
+            const evidenceFiles = new Set(list.flatMap((v) => v.evidence.map((e) => e.file)));
+            for (const f of evidenceFiles) {
+                const text = await repo.read(f);
+                if (!text)
+                    continue;
+                const lines = text.split("\n");
+                const marks = [];
+                lines.forEach((line, i) => {
+                    for (const k of vendorsOnLine(line, known))
+                        marks.push({ at: i, k });
+                });
+                if (!marks.length)
+                    continue;
+                lines.forEach((line, i) => {
+                    for (const r of roleTable) {
+                        if (!r.re.test(line))
+                            continue;
+                        let best = null;
+                        for (const m of marks) {
+                            const d = i - m.at; // the vendor line itself, or lines under it
+                            if (d >= 0 && d <= ROLE_REACH && (!best || d < best.d))
+                                best = { d, k: m.k };
+                        }
+                        if (!best)
+                            continue;
+                        const mine = roles.get(best.k.service) ?? new Map();
+                        if (!mine.has(r.role))
+                            mine.set(r.role, `${f}:${i + 1}`);
+                        roles.set(best.k.service, mine);
+                    }
+                });
+            }
+            if (roles.size)
+                o.roles = Object.fromEntries([...roles].map(([s, m]) => [s, [...m.keys()]]));
+            const merchantRole = roleTable.find((r) => r.merchant);
+            const merchants = merchantRole ? o.services.filter((s) => roles.get(s)?.has(merchantRole.role)) : [];
+            if (merchants.length) {
+                const where = merchants.map((s) => `${s} (${roles.get(s).get(merchantRole.role)})`).join(" and ");
+                o.distinct = `${where} ${merchants.length > 1 ? "carry" : "carries"} Connect or OAuth markers: charging on a merchant's own account. A second processor beside that is a merchant's choice of where their sales land, not the platform paying twice.`;
+            }
+            else if (o.services.every((s) => roles.get(s)?.size)) {
+                const sets = o.services.map((s) => new Set(roles.get(s).keys()));
+                const disjoint = sets.every((a, i) => sets.every((b, j) => i === j || ![...a].some((r) => b.has(r))));
+                if (disjoint) {
+                    o.distinct =
+                        o.services.map((s) => `${s} ${[...roles.get(s).entries()].map(([r, w]) => `${r} (${w})`).join(" and ")}`).join("; ") +
+                            ". One category, two jobs.";
+                }
+            }
+        }
+        overlaps.push(o);
     }
     const unrecognised = [...unknownHosts.entries()]
         .map(([host, set]) => ({ host, files: [...set].slice(0, 5) }))

package/dist/index.d.ts

@@ -6,6 +6,8 @@ import { type ProspectScore } from "./score.js";
 import type { CostFact, DeadFact, DepFact, DatabaseReading, DuplicateFact, Fingerprint, HandrolledFact, NorthStar, OverlapFact, VendorFact } from "./detect/types.js";
 export { toMarkdown, secretShaped } from "./report.js";
 export { checkReport } from "./check.js";
+export { checkVerdicts, rescore, showMath, findingIds } from "./verdicts.js";
+export type { Verdicts, VerdictRecord, EvidenceEntry, Verdict } from "./verdicts.js";
 export type { ProspectScore } from "./score.js";
 export interface Prospect {
     format: "bigsteele-prospect/1";
@@ -43,5 +45,5 @@ export interface Prospect {
         entrypoints: number;
     };
 }
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.3.0";
 export declare function runProspect(root: string): Promise<Prospect>;

package/dist/index.js

@@ -36,7 +36,8 @@ import { Decisions, touches } from "./decisions.js";
 import { scoreProspect } from "./score.js";
 export { toMarkdown, secretShaped } from "./report.js";
 export { checkReport } from "./check.js";
-export const VERSION = "0.2.0";
+export { checkVerdicts, rescore, showMath, findingIds } from "./verdicts.js";
+export const VERSION = "0.3.0";
 export async function runProspect(root) {
     const repo = await openRepo(root);
     const runtime = runtimeCode(repo.files);
@@ -94,6 +95,28 @@ export async function runProspect(root) {
         d.on_record = record.explains(frag(d.file)) ?? undefined;
         d.touches = touches(d.file, few);
     }
+    // EVERY FINDING GETS A NAME (0.3). The protocol has to rule on each one -
+    // confirmed, refuted, on record, unknown - and a verdict needs something to
+    // point at. Ids are stable across runs of the same repository.
+    for (const d of deps)
+        if (d.no_reference_found)
+            d.id = `dep:${d.name}`;
+    for (const o of vendorsReading.overlaps)
+        o.id = `overlap:${o.category}`;
+    for (const o of stack.overlaps)
+        o.id = `overlap:${o.category}`;
+    for (const h of handrolled)
+        h.id = `hand:${h.rail}`;
+    for (const c of stack.consolidations)
+        c.id = `cut:${c.candidate}`;
+    duplicates.forEach((d, i) => { if (!d.deliberate && !d.parallel)
+        d.id = `dup:${i + 1}:${d.files[0] ?? ""}`; });
+    for (const d of deadReading.dead)
+        d.id = `dead:${d.file}`;
+    for (const c of costs)
+        c.id = `cost:${c.file}:${c.line.split(":")[0]}`;
+    for (const f of database.findings)
+        f.id = `db:${f.kind}:${f.subject}`;
     // Last, and after every detector, so the ledger describes the run that just
     // happened rather than a plan for one.
     const coverage = await coverageOf(repo);

package/dist/report.js

@@ -17,13 +17,17 @@ export function toMarkdown(p) {
     const accidental = p.duplicates.filter((d) => !d.deliberate);
     const highHand = p.handrolled.filter((h) => h.confidence === "high");
     const cuts = p.stack.consolidations;
+    // A category is not a job: pairs the code shows doing different work are
+    // listed under their own heading and never counted as paid twice.
+    const paidTwice = p.overlaps.filter((o) => !o.distinct);
+    const twoJobs = p.overlaps.filter((o) => o.distinct);
     L.push(`# The Prospect: ${p.app}`, "");
     // The headline is an argument, not a metric.
     const claims = [];
     if (noRef.length)
         claims.push(`**${noRef.length} of ${p.totals.runtime_deps}** dependencies show no reference anywhere`);
-    if (p.overlaps.length)
-        claims.push(`**${p.overlaps.length}** job${p.overlaps.length > 1 ? "s are" : " is"} paid for twice`);
+    if (paidTwice.length)
+        claims.push(`**${paidTwice.length}** job${paidTwice.length > 1 ? "s are" : " is"} paid for twice`);
     if (highHand.length)
         claims.push(`**${highHand.length}** subsystem${highHand.length > 1 ? "s" : ""} built by hand where the market sells a rail`);
     if (cuts.length)
@@ -51,7 +55,7 @@ export function toMarkdown(p) {
             retest: "install, build and run the test suite with it gone",
         });
     }
-    for (const o of p.overlaps.filter((x) => !x.on_record)) {
+    for (const o of paidTwice.filter((x) => !x.on_record)) {
         actions.push({
             what: `${prose(o.services)} both do ${label(o.category)} work`,
             touches: "one bill and one failure surface per vendor",
@@ -91,7 +95,7 @@ export function toMarkdown(p) {
     const onRecord = [];
     for (const d of noRef.filter((x) => x.on_record))
         onRecord.push({ what: `\`${d.name}\` shows no reference`, where: `${d.on_record.file}:${d.on_record.line} - ${d.on_record.excerpt}` });
-    for (const o of p.overlaps.filter((x) => x.on_record))
+    for (const o of paidTwice.filter((x) => x.on_record))
         onRecord.push({ what: `${prose(o.services)} both do ${label(o.category)} work`, where: `${o.on_record.file}:${o.on_record.line} - ${o.on_record.excerpt}` });
     for (const c of cuts.filter((x) => x.on_record))
         onRecord.push({ what: `${c.candidate} beside ${c.keep}`, where: `${c.on_record.file}:${c.on_record.line} - ${c.on_record.excerpt}` });
@@ -121,6 +125,16 @@ export function toMarkdown(p) {
             L.push(`${parallels.length} parallel adapter block(s), ${total} lines in total, at the same relative path under sibling adapter directories. A generated file cannot import from the generator, so these duplicate by design; the one question is whether the generator could render them from a single partial.`, "");
         }
     }
+    // TWO VENDORS, TWO JOBS. A category shared is not a bill doubled; the code
+    // showed each doing different work. Listed so the reader sees the pair was
+    // weighed, charged nothing, and asked to be written down once.
+    if (twoJobs.length) {
+        L.push(`## Two vendors, two jobs`, "");
+        L.push(`Same category, different work by the look of the code. Not charged. A line in DECISIONS.md naming both keeps the next scan from asking.`, "");
+        for (const o of twoJobs)
+            L.push(`- **${label(o.category)}**: ${o.services.join(" + ")}. ${o.distinct}${o.on_record ? ` On record: ${o.on_record.file}:${o.on_record.line}.` : ""}`);
+        L.push("");
+    }
     // UNKNOWN. What the scan could not settle, stated rather than scored.
     const unknowns = [];
     if (p.north_star.confidence !== "high")
@@ -196,7 +210,10 @@ export function toMarkdown(p) {
     if (db.files > 0) {
         L.push(`### The database`, "");
         L.push(`${db.files} migration file(s): ${db.tables} table(s), ${db.policies} policy/policies, ` +
-            `${db.definer_functions} function(s) running as definer. ` +
+            `${db.definer_functions} function(s) running as definer` +
+            (db.definer_execute_revoked ? `, ${db.definer_execute_revoked} of them with EXECUTE revoked from public, anon or authenticated in the migrations` : "") +
+            `. ` +
+            (db.guard ? `The repository carries \`${db.guard}\`, which checks the live grants; this scan reads only what the migrations state. ` : "") +
             (db.findings.length === 0
                 ? `Nothing below stood out.`
                 : `${db.findings.length} shape(s) worth a minute.`), "");
@@ -233,9 +250,9 @@ export function toMarkdown(p) {
         L.push("");
         L.push(`A package can earn its keep without an import (a CLI run from a script, a plugin loaded by name at runtime). This table is the list to answer for, not a kill list.`, "");
     }
-    if (p.overlaps.length) {
+    if (paidTwice.length) {
         L.push(`### Jobs paid for twice`, "");
-        for (const o of p.overlaps) {
+        for (const o of paidTwice) {
             L.push(`- **${label(o.category)}**: ${o.services.join(" + ")} (${o.call_sites} call sites). One category of work, ${o.services.length} vendors, ${o.services.length} invoices, ${o.services.length} places a key can leak.`);
         }
         L.push("");
@@ -278,9 +295,11 @@ export function toMarkdown(p) {
     }
     if (p.dead.length) {
         L.push(`### Files no entrypoint reaches`, "");
-        L.push(`From ${p.totals.entrypoints} entrypoints, the import walk never arrived at these. A file loaded by a path built at runtime can still be alive - this is the list to answer for.`, "");
+        const scaffold = p.dead.filter((d) => d.scaffold).length;
+        L.push(`From ${p.totals.entrypoints} entrypoints, the import walk never arrived at these, and no reached file names them by path. A file loaded by a path built at runtime can still be alive - this is the list to answer for.` +
+            (scaffold ? ` ${scaffold} are UI-kit scaffold components (a components.json sits beside them) that no file imports: never bundled, only read and searched, and weighed a quarter.` : ""), "");
         for (const d of p.dead.slice(0, 20))
-            L.push(`- \`${d.file}\` (${d.loc} lines)`);
+            L.push(`- \`${d.file}\` (${d.loc} lines${d.scaffold ? ", scaffold" : ""})`);
         if (p.dead.length > 20)
             L.push(`- …and ${p.dead.length - 20} more in the JSON`);
         L.push("");

package/dist/score.js

@@ -51,16 +51,20 @@ export function scoreProspect(input) {
     const noRef = runtimeDeps.filter((d) => d.no_reference_found && !d.on_record);
     // Unreferenced runtime dependencies: up to 20.
     ding("dependencies with no reference found", Math.min(20, noRef.length * 2), noRef.length ? `${noRef.length} of ${runtimeDeps.length} runtime dependencies` : "");
-    // Files no entrypoint reaches: up to 20, by share of runtime files.
+    // Files no entrypoint reaches: up to 20, by share of runtime files. A UI-kit
+    // scaffold component nothing imports is never bundled, so it weighs a quarter.
     const dead = input.dead.filter((d) => !d.on_record);
-    const deadShare = input.runtime_files > 0 ? dead.length / input.runtime_files : 0;
-    ding("files no entrypoint reaches", Math.min(20, Math.round(deadShare * 100)), dead.length ? `${dead.length} files (${Math.round(deadShare * 100)} in 100)` : "");
+    const scaffold = dead.filter((d) => d.scaffold).length;
+    const deadWeight = dead.length - scaffold + scaffold / 4;
+    const deadShare = input.runtime_files > 0 ? deadWeight / input.runtime_files : 0;
+    ding("files no entrypoint reaches", Math.min(20, Math.round(deadShare * 100)), dead.length ? `${dead.length} files (${Math.round(deadShare * 100)} in 100${scaffold ? `; ${scaffold} are scaffold components, weighed a quarter` : ""})` : "");
     // Accidental duplicate clusters: up to 20. Deliberate copies cost nothing.
     const accidental = input.duplicates.filter((d) => !d.deliberate && !d.parallel && !d.on_record);
     const dupLines = accidental.reduce((t, d) => t + d.lines * (d.files.length - 1), 0);
     ding("duplicated blocks not marked deliberate", Math.min(20, Math.round(dupLines / 40)), accidental.length ? `${accidental.length} clusters, ${dupLines} repeated lines` : "");
-    // Vendor overlap: up to 20. Two vendors in one category is a doubled bill.
-    const overlaps = input.overlaps.filter((o) => !o.on_record);
+    // Vendor overlap: up to 20. Two vendors doing ONE JOB is a doubled bill; two
+    // vendors the code shows doing different jobs inside a category is not (0.2.1).
+    const overlaps = input.overlaps.filter((o) => !o.on_record && !o.distinct);
     ding("two or more vendors doing one job", Math.min(20, overlaps.length * 7), overlaps.length ? overlaps.map((o) => `${o.category}: ${o.services.join(" + ")}`).join("; ") : "");
     // Hand-rolled where a rail exists: up to 12, high-confidence only.
     const high = input.handrolled.filter((h) => h.confidence === "high" && !h.on_record);

package/dist/verdicts.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The verdicts: what the agent decided about every Step 0 finding, and the
+ * score recomputed from those decisions.
+ *
+ * Step 0 is a deterministic scan, and a deterministic scan is a hypothesis
+ * machine: it reads shapes and prints them. The protocol's first job is to
+ * take every finding to the code and rule on it, one of four ways -
+ * CONFIRMED with evidence, REFUTED with the reason the shape lied, ON_RECORD
+ * with the line that decided it, or UNKNOWN with what would settle it. A
+ * finding no verdict covers is a finding nobody checked, and the gate says so.
+ *
+ * The score then follows the verdicts, not the scan: a refuted finding costs
+ * nothing, a recorded one costs nothing, and the math is printed so the number
+ * can be argued with rather than trusted. Same rule as The Big Sean's
+ * validator: if this and the agent disagree, believe this and fix the file.
+ *
+ * PURE MODULE: no filesystem, no process. The CLI feeds it parsed JSON.
+ */
+import type { Prospect } from "./index.js";
+import { type ProspectScore } from "./score.js";
+export type Verdict = "CONFIRMED" | "REFUTED" | "ON_RECORD" | "UNKNOWN";
+export interface VerdictRecord {
+    /** The finding's id from the scan JSON: dep:zod, overlap:ai, hand:search, dead:src/x.ts, cost:file:line, db:kind:subject, cut:Vercel, dup:1:file */
+    id: string;
+    verdict: Verdict;
+    /** Evidence ids (EV-nn) from the register. Required for CONFIRMED and REFUTED. */
+    evidence?: string[];
+    /** Why - the shape that lied, the record that decided, or what would settle it. */
+    reason?: string;
+    /** For ON_RECORD: the decision line, file:line. */
+    record?: string;
+}
+export interface EvidenceEntry {
+    id: string;
+    /** What was done: the file read, the command run, the page loaded. */
+    what: string;
+    /** Where: file:line, a sanitised command, or a URL. */
+    where: string;
+    /** What was observed, in one line. Secrets and personal data never. */
+    observed: string;
+}
+export interface Verdicts {
+    format: "bigsteele-prospect-verdicts/1";
+    /** The scan these verdicts rule on. */
+    scan?: string;
+    commit?: string;
+    findings: VerdictRecord[];
+    evidence: EvidenceEntry[];
+}
+/** Every finding id the scan carries, in the order the report prints them. */
+export declare function findingIds(p: Prospect): string[];
+export interface VerdictCheck {
+    ok: boolean;
+    problems: string[];
+    counts: Record<Verdict, number> & {
+        total: number;
+        unruled: number;
+    };
+}
+/**
+ * Validate the verdicts against the scan they claim to rule on. Every scan
+ * finding needs a verdict; every CONFIRMED and REFUTED needs evidence that
+ * exists in the register; every UNKNOWN needs a reason; every ON_RECORD needs
+ * the line. A report text may be passed so that cited evidence is also
+ * required to appear in the report.
+ */
+export declare function checkVerdicts(p: Prospect, v: Verdicts, reportMd?: string): VerdictCheck;
+export interface Rescore {
+    before: ProspectScore;
+    after: ProspectScore;
+    dropped: {
+        refuted: string[];
+        on_record: string[];
+    };
+    unknown: string[];
+}
+/** The score with refuted and recorded findings removed. UNKNOWN still counts: unproven is not innocent. */
+export declare function rescore(p: Prospect, v: Verdicts): Rescore;
+/** The math, printed. Nothing on the page is typed by hand. */
+export declare function showMath(p: Prospect, v: Verdicts, r: Rescore, c: VerdictCheck): string;

package/dist/verdicts.js

@@ -0,0 +1,144 @@
+import { scoreProspect } from "./score.js";
+const VERDICTS = new Set(["CONFIRMED", "REFUTED", "ON_RECORD", "UNKNOWN"]);
+/** Every finding id the scan carries, in the order the report prints them. */
+export function findingIds(p) {
+    const ids = [];
+    for (const d of p.deps)
+        if (d.id)
+            ids.push(d.id);
+    for (const o of p.overlaps)
+        if (o.id)
+            ids.push(o.id);
+    for (const h of p.handrolled)
+        if (h.id)
+            ids.push(h.id);
+    for (const c of p.stack.consolidations)
+        if (c.id)
+            ids.push(c.id);
+    for (const d of p.duplicates)
+        if (d.id)
+            ids.push(d.id);
+    for (const d of p.dead)
+        if (d.id)
+            ids.push(d.id);
+    for (const c of p.cost_surfaces)
+        if (c.id)
+            ids.push(c.id);
+    for (const f of p.database.findings)
+        if (f.id)
+            ids.push(f.id);
+    return ids;
+}
+/**
+ * Validate the verdicts against the scan they claim to rule on. Every scan
+ * finding needs a verdict; every CONFIRMED and REFUTED needs evidence that
+ * exists in the register; every UNKNOWN needs a reason; every ON_RECORD needs
+ * the line. A report text may be passed so that cited evidence is also
+ * required to appear in the report.
+ */
+export function checkVerdicts(p, v, reportMd) {
+    const problems = [];
+    const counts = { CONFIRMED: 0, REFUTED: 0, ON_RECORD: 0, UNKNOWN: 0, total: 0, unruled: 0 };
+    if (v.format !== "bigsteele-prospect-verdicts/1")
+        problems.push(`format is "${String(v.format)}", expected "bigsteele-prospect-verdicts/1"`);
+    const evidence = new Map((v.evidence ?? []).map((e) => [e.id, e]));
+    for (const e of v.evidence ?? []) {
+        if (!/^EV-\d+$/.test(e.id))
+            problems.push(`evidence "${e.id}" is not named EV-<n>`);
+        if (!e.where || !e.observed)
+            problems.push(`evidence ${e.id} lacks where or observed`);
+    }
+    const byId = new Map();
+    for (const r of v.findings ?? []) {
+        if (byId.has(r.id))
+            problems.push(`finding ${r.id} has two verdicts`);
+        byId.set(r.id, r);
+    }
+    const ids = findingIds(p);
+    const known = new Set(ids);
+    for (const r of v.findings ?? []) {
+        if (!known.has(r.id))
+            problems.push(`verdict on "${r.id}", which the scan did not report`);
+    }
+    for (const id of ids) {
+        const r = byId.get(id);
+        counts.total++;
+        if (!r) {
+            counts.unruled++;
+            problems.push(`no verdict on ${id}: a finding nobody checked`);
+            continue;
+        }
+        if (!VERDICTS.has(r.verdict)) {
+            problems.push(`${id}: verdict "${String(r.verdict)}" is not CONFIRMED, REFUTED, ON_RECORD or UNKNOWN`);
+            continue;
+        }
+        counts[r.verdict]++;
+        if (r.verdict === "CONFIRMED" || r.verdict === "REFUTED") {
+            if (!r.evidence?.length)
+                problems.push(`${id}: ${r.verdict} with no evidence entry`);
+            for (const ev of r.evidence ?? []) {
+                if (!evidence.has(ev))
+                    problems.push(`${id}: cites ${ev}, which is not in the register`);
+                else if (reportMd && !reportMd.includes(ev))
+                    problems.push(`${id}: cites ${ev}, which the report never shows`);
+            }
+        }
+        if (r.verdict === "REFUTED" && !r.reason)
+            problems.push(`${id}: REFUTED without saying what shape lied`);
+        if (r.verdict === "UNKNOWN" && !r.reason)
+            problems.push(`${id}: UNKNOWN without saying what would settle it`);
+        if (r.verdict === "ON_RECORD" && !r.record)
+            problems.push(`${id}: ON_RECORD without the deciding line`);
+    }
+    return { ok: problems.length === 0, problems, counts };
+}
+/** The score with refuted and recorded findings removed. UNKNOWN still counts: unproven is not innocent. */
+export function rescore(p, v) {
+    const verdictOf = new Map((v.findings ?? []).map((r) => [r.id, r.verdict]));
+    const keep = (id) => !id || !(verdictOf.get(id) === "REFUTED" || verdictOf.get(id) === "ON_RECORD");
+    const refuted = [...verdictOf].filter(([, x]) => x === "REFUTED").map(([id]) => id);
+    const onRecord = [...verdictOf].filter(([, x]) => x === "ON_RECORD").map(([id]) => id);
+    const unknown = [...verdictOf].filter(([, x]) => x === "UNKNOWN").map(([id]) => id);
+    const deps = p.deps.map((d) => (keep(d.id) ? d : { ...d, no_reference_found: false }));
+    const unusedPaid = deps.find((d) => !d.dev && d.no_reference_found && /^(openai|stripe|twilio|resend|@sendgrid\/|@anthropic-ai\/|@clerk\/|algoliasearch|cloudinary)/.test(d.name))?.name ?? null;
+    const after = scoreProspect({
+        not_asked: p.score.not_asked,
+        deps,
+        overlaps: p.overlaps.filter((o) => keep(o.id)),
+        consolidations: p.stack.consolidations.filter((c) => keep(c.id)),
+        handrolled: p.handrolled.filter((h) => keep(h.id)),
+        duplicates: p.duplicates.filter((d) => keep(d.id)),
+        dead: p.dead.filter((d) => keep(d.id)),
+        costs: p.cost_surfaces.filter((c) => keep(c.id)),
+        runtime_files: p.totals.runtime_files,
+        unused_paid_service: unusedPaid,
+    });
+    return { before: p.score, after, dropped: { refuted, on_record: onRecord }, unknown };
+}
+/** The math, printed. Nothing on the page is typed by hand. */
+export function showMath(p, v, r, c) {
+    const L = [];
+    L.push(`THE PROSPECT - recomputed from ${v.scan ?? "the scan"}${v.commit ? ` at ${v.commit}` : ""}`);
+    L.push(`findings: ${c.counts.total}  CONFIRMED ${c.counts.CONFIRMED}  REFUTED ${c.counts.REFUTED}  ON_RECORD ${c.counts.ON_RECORD}  UNKNOWN ${c.counts.UNKNOWN}  unruled ${c.counts.unruled}`);
+    L.push(`evidence entries: ${(v.evidence ?? []).length}`);
+    L.push("");
+    L.push(`Step 0 score   ${String(r.before.total).padStart(3)}/100 (${r.before.grade})  Level ${r.before.level.n} ${r.before.level.name}`);
+    L.push(`After verdicts ${String(r.after.total).padStart(3)}/100 (${r.after.grade})  Level ${r.after.level.n} ${r.after.level.name}`);
+    L.push("");
+    L.push("Deductions after verdicts:");
+    if (!r.after.deductions.length)
+        L.push("  none");
+    for (const d of r.after.deductions)
+        L.push(`  ${String(d.points).padStart(4)}  ${d.what}  (${d.evidence})`);
+    for (const f of r.after.floors)
+        L.push(`  floor: ${f}`);
+    if (r.dropped.refuted.length)
+        L.push("", `Refuted, cost nothing: ${r.dropped.refuted.join(", ")}`);
+    if (r.dropped.on_record.length)
+        L.push(`On record, cost nothing: ${r.dropped.on_record.join(", ")}`);
+    if (r.unknown.length)
+        L.push(`Still unknown, still charged: ${r.unknown.join(", ")}`);
+    L.push("");
+    L.push(c.ok ? "verdicts: complete" : `verdicts: ${c.problems.length} problem(s) - the number above is not final until they are fixed`);
+    return L.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigsteele/the-prospect",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A prospector's read of your codebase and your market. Digs the ground you own: every dependency that does no work, every vendor you pay twice, every subsystem you built by hand where a rail now exists. Then surveys the territory: what your industry ships by API that your code still does the hard way. Every suggestion stands on three legs - a fact read from your code, a fact researched from your market with a source and a date, and the thing your product exists to do. Standalone: one npx, no other scan required.",
   "type": "module",
   "license": "UNLICENSED",