@specific.dev/spectest 0.67.0 → 0.68.0

package/dist/daemon.js

@@ -39,6 +39,7 @@ import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
+import { runWrapperRules } from "./harness/wrapper-rules.js";
 import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
@@ -4133,7 +4134,16 @@ async function pollCall(description, fn, opts) {
         lastIterStartIdx = recorderEventCount();
         try {
             const v = await fn();
-            if (v !== null && v !== undefined && v !== false) {
+            // Decide on the RAW value. A predicate that hands back a wrapped leaf
+            // (`rows[0].written` off an instrumented query) returns a `Carrier`,
+            // and a carrier around `false` is an object — truthy, and `!== false`.
+            // Without this a poll accepted a condition that was never met and the
+            // test ran on against stale data, which is worse than a timeout: there
+            // is no failure to read (reported 2026-08-30, run_0cjtx0dbzjs5yq6vwefkk,
+            // where `written: false` passed the wait on attempt 1 in 3 ms).
+            // `value` keeps the WRAPPED form so the return still carries provenance.
+            const ready = readRaw(v);
+            if (ready !== null && ready !== undefined && ready !== false) {
                 value = v;
                 success = true;
                 break;
@@ -5061,7 +5071,11 @@ async function evalCode(code, secrets) {
 // its own `typescript` in spectest/package.json wins. A project tsconfig.json
 // wins over the generated one the same way.
 // ────────────────────────────────────────────────────────────────────────
-const TYPECHECK_DIR = "/opt/spectest/typecheck";
+/** Where the baked compiler lives. Overridable so the typecheck — and the
+ *  blocking rules, which always use THIS copy rather than the project's own —
+ *  can be driven outside a VM (same convention as
+ *  `SPECTEST_COVERAGE_TOOLS_DIR`). */
+const TYPECHECK_DIR = process.env.SPECTEST_TYPECHECK_DIR ?? "/opt/spectest/typecheck";
 /** Cap on errors shipped in the report; `totalErrors` carries the true count. */
 const TYPECHECK_ERROR_CAP = 50;
 let TYPECHECK = null;
@@ -5176,7 +5190,17 @@ async function runTypecheck() {
         return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: "typecheck timed out" };
     }
     const { errors, total, suppressed } = parseTscOutput(res.stdout + res.stderr);
-    if (errors.length === 0) {
+    const wrapper = await runWrapperRulesReport(config);
+    const strip = ({ file, line, column, code, message }) => ({
+        file,
+        line,
+        column,
+        code,
+        message,
+    });
+    const blocking = wrapper.filter((d) => d.blocking).map(strip);
+    const advisory = wrapper.filter((d) => !d.blocking).map(strip);
+    if (errors.length === 0 && wrapper.length === 0) {
         // Exit 0 → clean. Non-zero with no *user-file* diagnostics is either
         // all-suppressed (still ok from the user's perspective) or a compiler
         // crash (config not found, OOM) — surface the latter.
@@ -5189,7 +5213,51 @@ async function runTypecheck() {
         }
         return { status: "ok", errors: [], totalErrors: 0, durationMs };
     }
-    return { status: "errors", errors, totalErrors: total, durationMs };
+    // The wrapper findings ride the same list the CLI and the dashboard already
+    // render; `blocking` is a second view of the ones that also fail the run, so
+    // nothing has to learn a new shape to show them. Blocking leads, because
+    // `errors` is capped and the entries that stopped the run must never be the
+    // ones the cap drops.
+    const all = [...blocking, ...advisory, ...errors];
+    return {
+        status: "errors",
+        errors: all.slice(0, TYPECHECK_ERROR_CAP),
+        totalErrors: total + wrapper.length,
+        durationMs,
+        ...(blocking.length > 0 ? { blocking } : {}),
+    };
+}
+/**
+ * The blocking rules, run against the BAKED compiler whatever the project
+ * pins. Best-effort in every direction: an install that predates the API, a
+ * config the rules cannot open, or a throw from `typescript/unstable/*` all
+ * yield no findings, so a run proceeds exactly as it does today. Only a
+ * definite finding can stop one.
+ */
+async function runWrapperRulesReport(config) {
+    const typescriptDir = path.join(TYPECHECK_DIR, "node_modules", "typescript");
+    if (!existsSync(path.join(typescriptDir, "dist", "api", "async", "api.js")))
+        return [];
+    try {
+        const run = await runWrapperRules({
+            typescriptDir,
+            configFile: config,
+            appDir: APP_DIR,
+            readFile: (f) => fs.readFile(f, "utf8"),
+            relative: path.relative,
+            join: path.join,
+            dirname: path.dirname,
+        });
+        if (run.status !== "ok") {
+            console.warn(`[typecheck] wrapper rules ${run.status}: ${run.detail ?? "no detail"}`);
+            return [];
+        }
+        return run.diagnostics;
+    }
+    catch (err) {
+        console.warn(`[typecheck] wrapper rules threw: ${err?.message ?? err}`);
+        return [];
+    }
 }
 /** Run `job` under a mutual-exclusion slot, refusing if one is held. */
 async function exclusive(state, slot, busy, job) {

package/dist/harness/wrapper-rules.d.ts

@@ -0,0 +1,149 @@
+/** A finding, shaped like the `TypecheckError` the report already carries. */
+export interface WrapperDiagnostic {
+    /** Path relative to the app dir, matching the advisory diagnostics. */
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    message: string;
+    /**
+     * Whether this finding may fail the run. Only a rule that is true of the
+     * RUN, not merely of the declared types, may block — see the header and the
+     * note on {@link CODE_TRUTHY}.
+     */
+    blocking: boolean;
+}
+/**
+ * A condition on a wrapped value — always true. **Blocking**, but on different
+ * grounds from {@link CODE_EQUALITY}, and the difference is worth knowing.
+ *
+ * This rule is NOT a proof. Two things can hide a runtime nullish from the
+ * compiler: a row generic that overstates a column
+ * (`client<{ names: string }>` over a `string_agg` that returns NULL) and
+ * TypeScript's deliberately unsound array indexing (`rows[0]` is typed
+ * non-optional even when the array is empty). A nullish leaf comes back RAW
+ * from `wrapChild`, so in those shapes `if (rows[0]?.names)` really does tell
+ * present from absent, and "always true" is false about it — measured against
+ * a real suite on 2026-08-30 (`journal-note.ts:200`).
+ *
+ * It blocks anyway, as a CONVENTION rather than a verdict: *unwrap before
+ * branching on a wrapped value*, the same discipline the docs already teach
+ * for `===`. What makes that acceptable is that the fix is safe in every case
+ * — `?.unwrap()` short-circuits, so it never throws and never changes code
+ * that was already correct; it only removes the accident. And the accident is
+ * the worst failure this SDK has: a `ctx.poll` predicate that collapses a
+ * wrapped `false` to `true` passes on attempt 1, the suite runs on against
+ * data that never arrived, and neither the compiler nor the runtime says a
+ * word (reported 2026-08-30).
+ *
+ * The line this does not cross: a rule may demand more of the user's own code,
+ * but it may never fail a run over OUR stale types (the patched global
+ * `fetch`) or over the compiler's own bad inference (TS2367 across a
+ * callback). Those cost the user a fix they cannot make.
+ */
+export declare const CODE_TRUTHY = "SPECTEST2001";
+/**
+ * `===`/`!==` between a wrapped value and a plain one — always false/true.
+ * **Blocking.** Sound even when a row generic understates nullability: if the
+ * leaf is a carrier the comparison is false because an object never equals a
+ * primitive, and if it is raw nullish it is false because nullish does not
+ * equal the literal either. A nullish literal on the other side is excluded —
+ * see {@link equalityIsConstant}.
+ */
+export declare const CODE_EQUALITY = "SPECTEST2002";
+/**
+ * Split a printed type on its TOP-LEVEL `|`, leaving nested unions alone
+ * (`Carrier<A | B> | undefined` → [`Carrier<A | B>`, `undefined`]). Depth is
+ * tracked across every bracket kind because a printed type can hold object
+ * literals (`{ a: 1 | 2 }`), tuples and parenthesised function types.
+ */
+export declare function splitUnion(text: string): string[];
+/** One union member that is the primitive carrier. Object/array/response
+ *  wrappers are deliberately NOT included: they are objects whether or not we
+ *  wrap them, so a condition on one is not made constant by the wrapper. */
+export declare function isCarrierMember(member: string): boolean;
+export type TypeVerdict = 
+/** Every member is a carrier and none is nullish — constant at runtime. */
+"carrier"
+/** A carrier that may also be absent — a real presence test, leave alone. */
+ | "nullable-carrier"
+/** Not a wrapper. */
+ | "plain";
+/**
+ * Classify a printed type for the rules. `unknown`/`any`/an error type read as
+ * `plain`: the checker could not say what the value is, and a rule that blocks
+ * a run must not guess.
+ */
+export declare function classifyType(text: string | undefined): TypeVerdict;
+/** Source text that denotes a nullish literal. */
+export declare function isNullishLiteral(exprText: string): boolean;
+/**
+ * Verdict for a strict `===`/`!==`. Blocking only when exactly one side is a
+ * definite carrier: two carriers compare object identity, which is a different
+ * mistake and not one this rule can prove constant.
+ *
+ * A comparison against a NULLISH LITERAL is never constant, whatever the type
+ * says. `wrapChild` hands a `null`/`undefined` leaf back RAW, so
+ * `row.setting === null` is the correct way to ask whether a column is null —
+ * and it answers correctly in both directions. The declared type cannot show
+ * this, because a row generic is the caller's own assertion
+ * (`client<{ setting: unknown }>`) and routinely understates nullability.
+ * Found in a real suite on 2026-08-30 (`document-export-settings.ts:64`),
+ * where flagging it would have blocked a passing test.
+ */
+export declare function equalityIsConstant(left: string | undefined, right: string | undefined, leftExpr?: string, rightExpr?: string): boolean;
+/**
+ * The real start of a node. A TypeScript node's `pos` is the end of the
+ * PREVIOUS node, so it includes the leading whitespace and comments; `tsc`
+ * reports the first meaningful character. Without this every column is a few
+ * places to the left and a finding above a comment points at the comment.
+ */
+export declare function startOfNode(text: string, pos: number): number;
+/** 1-indexed line/column for a character offset, matching `tsc` output. */
+export declare function lineColumnAt(text: string, pos: number): {
+    line: number;
+    column: number;
+};
+/** Trim a source snippet for a message: one line, bounded. */
+export declare function snippet(text: string, pos: number, end: number): string;
+export declare function truthyMessage(expr: string, typeText: string): string;
+export declare function equalityMessage(expr: string, typeText: string, negated: boolean): string;
+/** Minimal shape of the bits of the TS 7 API this uses. */
+interface TsNode {
+    kind: number;
+    pos: number;
+    end: number;
+    [k: string]: unknown;
+}
+export interface WrapperRuleRun {
+    status: "ok" | "skipped" | "failed";
+    diagnostics: WrapperDiagnostic[];
+    detail?: string;
+    durationMs: number;
+}
+/** Candidate positions, and what each one means if the operand is a carrier. */
+interface Candidate {
+    node: TsNode;
+    kind: "truthy" | "equality";
+    /** For an equality, the other side, whose type decides with this one. */
+    other?: TsNode;
+    negated?: boolean;
+}
+/**
+ * Collect the positions worth asking about in one file. Kept separate from the
+ * checker so the walk can be reasoned about (and extended) on its own.
+ */
+export declare function collectCandidates(statements: readonly TsNode[], kindName: (n: TsNode) => string, walk: (n: TsNode, visit: (c: TsNode) => void) => void): Candidate[];
+export declare function runWrapperRules(opts: {
+    /** Directory of the baked `typescript` package. */
+    typescriptDir: string;
+    /** Absolute path of the tsconfig to open. */
+    configFile: string;
+    /** Only files under here produce diagnostics. */
+    appDir: string;
+    readFile: (p: string) => Promise<string>;
+    relative: (from: string, to: string) => string;
+    join: (...parts: string[]) => string;
+    dirname: (p: string) => string;
+}): Promise<WrapperRuleRun>;
+export {};

package/dist/harness/wrapper-rules.js

@@ -0,0 +1,422 @@
+// Blocking typecheck rules: control flow that a provenance wrapper makes
+// constant.
+//
+// `sdk/src/inspect.ts` returns every primitive leaf of a recorded op as a
+// `Carrier` — an object holding the value, with coercion sinks so template
+// interpolation, arithmetic, `==` and `JSON.stringify` all behave. Two things
+// a carrier cannot rescue, because JavaScript exposes no hook for either:
+//
+//   if (row.written)      // an object is ALWAYS truthy, even around `false`
+//   measured.rows === 2   // an object is NEVER === a primitive
+//
+// Both are constant, and both are silent. The first is the more expensive: a
+// `ctx.poll` predicate that collapses a wrapped `false` to `true` reports
+// success on attempt 1 and the suite runs on against data that never arrived
+// (reported 2026-08-30). `tsc` catches the second as TS2367 and says nothing
+// about the first — a truthiness test on an object type is legal TypeScript.
+//
+// WHY THESE MAY BLOCK A RUN WHEN `tsc`'s OWN DIAGNOSTICS MAY NOT
+// ---------------------------------------------------------------
+// The typecheck report is advisory because a `tsc` verdict is about the
+// DECLARED TYPES, and those can disagree with the program that actually runs,
+// in both directions:
+//
+//   - the types go stale: the global `fetch` is patched at runtime to record
+//     but keeps its raw `Response` type, so correct code is flagged;
+//   - narrowing is unsound: TypeScript does not reset a narrowed `let` across
+//     a callback, so `phase === "end"` after `[1,2].forEach(() => phase = "end")`
+//     is reported as having no overlap when at runtime it matches.
+//
+// The second is why TS2367 cannot gate a run even though it is exactly the
+// diagnostic that would have caught the reported bug.
+//
+// These rules ask a different question — *is this value a `Carrier`* — which
+// is a fact about the runtime representation, not an inference. Wrapping is
+// unconditional (see inspect.ts), so a value typed `Carrier<T>` IS an object
+// when the line executes. Narrowing cannot turn a carrier into a number, so
+// there is no unsoundness to inherit.
+//
+// {@link CODE_EQUALITY} is true of the run outright. {@link CODE_TRUTHY} is a
+// convention on top of it — read its note for why that still earns a gate, and
+// for the line neither rule crosses.
+//
+// SOUNDNESS CONDITIONS, both load-bearing:
+//
+//   1. `strictNullChecks` must be on. With it off, an optional leaf
+//      (`row.opt?: Carrier<string>`) reports as `Carrier<string>` rather than
+//      `Carrier<string> | undefined`, and `if (row.opt)` — a legitimate
+//      presence test, since `wrapChild` returns nullish RAW — would be flagged
+//      as a bug. The driver refuses to run rather than guess.
+//   2. A union carrying `null`/`undefined` is never flagged, for the same
+//      reason: that condition distinguishes present from absent and is correct.
+//
+// The type is identified from its printed form rather than from its symbol:
+// one round trip instead of several, and the whole decision stays a pure
+// function over a string, which is what the tests below drive. A user type
+// that happens to be called `Carrier<T>` would also be flagged — and would
+// also be an object at runtime, so the finding stays true.
+/**
+ * A condition on a wrapped value — always true. **Blocking**, but on different
+ * grounds from {@link CODE_EQUALITY}, and the difference is worth knowing.
+ *
+ * This rule is NOT a proof. Two things can hide a runtime nullish from the
+ * compiler: a row generic that overstates a column
+ * (`client<{ names: string }>` over a `string_agg` that returns NULL) and
+ * TypeScript's deliberately unsound array indexing (`rows[0]` is typed
+ * non-optional even when the array is empty). A nullish leaf comes back RAW
+ * from `wrapChild`, so in those shapes `if (rows[0]?.names)` really does tell
+ * present from absent, and "always true" is false about it — measured against
+ * a real suite on 2026-08-30 (`journal-note.ts:200`).
+ *
+ * It blocks anyway, as a CONVENTION rather than a verdict: *unwrap before
+ * branching on a wrapped value*, the same discipline the docs already teach
+ * for `===`. What makes that acceptable is that the fix is safe in every case
+ * — `?.unwrap()` short-circuits, so it never throws and never changes code
+ * that was already correct; it only removes the accident. And the accident is
+ * the worst failure this SDK has: a `ctx.poll` predicate that collapses a
+ * wrapped `false` to `true` passes on attempt 1, the suite runs on against
+ * data that never arrived, and neither the compiler nor the runtime says a
+ * word (reported 2026-08-30).
+ *
+ * The line this does not cross: a rule may demand more of the user's own code,
+ * but it may never fail a run over OUR stale types (the patched global
+ * `fetch`) or over the compiler's own bad inference (TS2367 across a
+ * callback). Those cost the user a fix they cannot make.
+ */
+export const CODE_TRUTHY = "SPECTEST2001";
+/**
+ * `===`/`!==` between a wrapped value and a plain one — always false/true.
+ * **Blocking.** Sound even when a row generic understates nullability: if the
+ * leaf is a carrier the comparison is false because an object never equals a
+ * primitive, and if it is raw nullish it is false because nullish does not
+ * equal the literal either. A nullish literal on the other side is excluded —
+ * see {@link equalityIsConstant}.
+ */
+export const CODE_EQUALITY = "SPECTEST2002";
+/**
+ * Split a printed type on its TOP-LEVEL `|`, leaving nested unions alone
+ * (`Carrier<A | B> | undefined` → [`Carrier<A | B>`, `undefined`]). Depth is
+ * tracked across every bracket kind because a printed type can hold object
+ * literals (`{ a: 1 | 2 }`), tuples and parenthesised function types.
+ */
+export function splitUnion(text) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        const c = text[i];
+        if (c === "<" || c === "(" || c === "[" || c === "{")
+            depth += 1;
+        else if (c === ">" || c === ")" || c === "]" || c === "}")
+            depth -= 1;
+        else if (c === "|" && depth === 0) {
+            parts.push(text.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    parts.push(text.slice(start).trim());
+    return parts.filter((p) => p.length > 0);
+}
+/** One union member that is the primitive carrier. Object/array/response
+ *  wrappers are deliberately NOT included: they are objects whether or not we
+ *  wrap them, so a condition on one is not made constant by the wrapper. */
+export function isCarrierMember(member) {
+    return /^Carrier<[\s\S]*>$/.test(member.trim());
+}
+/**
+ * Classify a printed type for the rules. `unknown`/`any`/an error type read as
+ * `plain`: the checker could not say what the value is, and a rule that blocks
+ * a run must not guess.
+ */
+export function classifyType(text) {
+    if (!text)
+        return "plain";
+    const members = splitUnion(text);
+    const nullish = members.filter((m) => m === "null" || m === "undefined");
+    const rest = members.filter((m) => m !== "null" && m !== "undefined");
+    if (rest.length === 0)
+        return "plain";
+    // A union mixing a carrier with a non-nullish plain type is not a shape the
+    // SDK produces. Blocking a run needs certainty, so an unrecognised shape
+    // reads as plain rather than as a finding.
+    if (!rest.every((m) => isCarrierMember(m)))
+        return "plain";
+    return nullish.length > 0 ? "nullable-carrier" : "carrier";
+}
+/** Source text that denotes a nullish literal. */
+export function isNullishLiteral(exprText) {
+    const t = exprText.trim();
+    return t === "null" || t === "undefined" || /^void\s+0$/.test(t);
+}
+/**
+ * Verdict for a strict `===`/`!==`. Blocking only when exactly one side is a
+ * definite carrier: two carriers compare object identity, which is a different
+ * mistake and not one this rule can prove constant.
+ *
+ * A comparison against a NULLISH LITERAL is never constant, whatever the type
+ * says. `wrapChild` hands a `null`/`undefined` leaf back RAW, so
+ * `row.setting === null` is the correct way to ask whether a column is null —
+ * and it answers correctly in both directions. The declared type cannot show
+ * this, because a row generic is the caller's own assertion
+ * (`client<{ setting: unknown }>`) and routinely understates nullability.
+ * Found in a real suite on 2026-08-30 (`document-export-settings.ts:64`),
+ * where flagging it would have blocked a passing test.
+ */
+export function equalityIsConstant(left, right, leftExpr = "", rightExpr = "") {
+    if (isNullishLiteral(leftExpr) || isNullishLiteral(rightExpr))
+        return false;
+    const l = classifyType(left);
+    const r = classifyType(right);
+    return (l === "carrier") !== (r === "carrier");
+}
+/**
+ * The real start of a node. A TypeScript node's `pos` is the end of the
+ * PREVIOUS node, so it includes the leading whitespace and comments; `tsc`
+ * reports the first meaningful character. Without this every column is a few
+ * places to the left and a finding above a comment points at the comment.
+ */
+export function startOfNode(text, pos) {
+    let i = Math.max(0, Math.min(pos, text.length));
+    while (i < text.length) {
+        const c = text[i];
+        if (c === " " || c === "\t" || c === "\r" || c === "\n") {
+            i += 1;
+        }
+        else if (c === "/" && text[i + 1] === "/") {
+            const nl = text.indexOf("\n", i);
+            i = nl === -1 ? text.length : nl + 1;
+        }
+        else if (c === "/" && text[i + 1] === "*") {
+            const close = text.indexOf("*/", i + 2);
+            i = close === -1 ? text.length : close + 2;
+        }
+        else {
+            break;
+        }
+    }
+    return i;
+}
+/** 1-indexed line/column for a character offset, matching `tsc` output. */
+export function lineColumnAt(text, pos) {
+    const clamped = Math.max(0, Math.min(pos, text.length));
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < clamped; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            line += 1;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: clamped - lineStart + 1 };
+}
+/** Trim a source snippet for a message: one line, bounded. */
+export function snippet(text, pos, end) {
+    const raw = text.slice(Math.max(0, pos), Math.max(0, end)).trim();
+    const oneLine = raw.split("\n")[0]?.trim() ?? "";
+    return oneLine.length > 60 ? `${oneLine.slice(0, 57)}…` : oneLine;
+}
+export function truthyMessage(expr, typeText) {
+    const subject = expr ? `\`${expr}\`` : "This value";
+    return (`${subject} is \`${typeText}\` — a provenance wrapper, which is an object at ` +
+        `runtime, so this condition is always true. A wrapped \`false\`, \`0\` or ` +
+        `\`""\` reads as truthy. Call \`.unwrap()\` before testing it.`);
+}
+export function equalityMessage(expr, typeText, negated) {
+    const subject = expr ? `\`${expr}\`` : "This value";
+    const verdict = negated ? "always true" : "always false";
+    return (`${subject} is \`${typeText}\` — a provenance wrapper, which is an object at ` +
+        `runtime and can never be strictly equal to a plain value, so this ` +
+        `comparison is ${verdict}. Call \`.unwrap()\` first, or assert with ` +
+        `\`expect(...)\`, which unwraps for you.`);
+}
+/** `TypeFlags.Object | TypeFlags.Union` — the only shapes a carrier can wear.
+ *  Filtering on the flags the batch call already returned keeps the printed
+ *  name (one round trip each) off every ordinary `boolean` condition. */
+const OBJECT_OR_UNION = (1 << 19) | (1 << 20);
+const SYNTAX = {
+    If: "IfStatement",
+    While: "WhileStatement",
+    DoWhile: "DoStatement",
+    For: "ForStatement",
+    Conditional: "ConditionalExpression",
+    Prefix: "PrefixUnaryExpression",
+    Binary: "BinaryExpression",
+};
+/**
+ * Collect the positions worth asking about in one file. Kept separate from the
+ * checker so the walk can be reasoned about (and extended) on its own.
+ */
+export function collectCandidates(statements, kindName, walk) {
+    const all = [];
+    const push = (n) => {
+        all.push(n);
+        walk(n, push);
+    };
+    for (const s of statements)
+        push(s);
+    const out = [];
+    for (const n of all) {
+        const k = kindName(n);
+        if (k === SYNTAX.If || k === SYNTAX.While || k === SYNTAX.DoWhile) {
+            const e = n.expression;
+            if (e)
+                out.push({ node: e, kind: "truthy" });
+        }
+        else if (k === SYNTAX.For || k === SYNTAX.Conditional) {
+            const e = n.condition;
+            if (e)
+                out.push({ node: e, kind: "truthy" });
+        }
+        else if (k === SYNTAX.Prefix) {
+            // `!x` — TypeScript's own always-truthy check misses this shape, which
+            // is why the rule cannot lean on TS2774.
+            if (kindName({ kind: n.operator }) === "ExclamationToken") {
+                const e = n.operand;
+                if (e)
+                    out.push({ node: e, kind: "truthy" });
+            }
+        }
+        else if (k === SYNTAX.Binary) {
+            const op = kindName({ kind: n.operatorToken?.kind });
+            const left = n.left;
+            const right = n.right;
+            if (!left || !right)
+                continue;
+            if (op === "AmpersandAmpersandToken" || op === "BarBarToken") {
+                out.push({ node: left, kind: "truthy" });
+            }
+            else if (op === "EqualsEqualsEqualsToken") {
+                out.push({ node: left, kind: "equality", other: right, negated: false });
+            }
+            else if (op === "ExclamationEqualsEqualsToken") {
+                out.push({ node: left, kind: "equality", other: right, negated: true });
+            }
+        }
+    }
+    return out;
+}
+export async function runWrapperRules(opts) {
+    const started = Date.now();
+    const done = (r) => ({
+        ...r,
+        durationMs: Date.now() - started,
+    });
+    let api;
+    try {
+        const base = opts.join(opts.typescriptDir, "dist");
+        const apiMod = (await import(opts.join(base, "api", "async", "api.js")));
+        const utils = (await import(opts.join(base, "ast", "utils.js")));
+        const visitor = (await import(opts.join(base, "ast", "visitor.js")));
+        const inst = new apiMod.API({ cwd: opts.dirname(opts.configFile) });
+        api = inst;
+        const snapshot = await inst.updateSnapshot({ openProjects: [opts.configFile] });
+        const project = (await snapshot.getProjects())[0];
+        if (!project)
+            return done({ status: "failed", diagnostics: [], detail: "no project" });
+        // Soundness condition 1 — see the header. Without strictNullChecks an
+        // optional carrier loses its `| undefined` and every presence test in the
+        // suite becomes a finding, so refuse rather than guess.
+        // `compilerOptions` is the file's raw options, not the resolved ones, so
+        // the `strict` family has to be folded by hand: an explicit
+        // `strictNullChecks` wins, otherwise `strict` supplies it.
+        const strictNullChecks = project.compilerOptions.strictNullChecks ??
+            project.compilerOptions.strict ??
+            false;
+        if (strictNullChecks !== true) {
+            return done({
+                status: "skipped",
+                diagnostics: [],
+                detail: "strictNullChecks is off; a wrapped optional cannot be told from a wrapped value",
+            });
+        }
+        const kindName = (n) => typeof n?.kind === "number" ? utils.formatSyntaxKind(n.kind) : "";
+        const walk = (n, visit) => {
+            try {
+                visitor.visitEachChild(n, (c) => {
+                    visit(c);
+                    return c;
+                }, undefined);
+            }
+            catch {
+                /* a node shape the walker cannot descend — its children are skipped */
+            }
+        };
+        const names = await project.program.getSourceFileNames();
+        const files = names.filter((f) => f.startsWith(`${opts.appDir}/`) && !f.includes("/node_modules/") && !f.endsWith(".d.ts"));
+        const diagnostics = [];
+        for (const file of files) {
+            const sf = await project.program.getSourceFile(file);
+            if (!sf)
+                continue;
+            const candidates = collectCandidates(sf.statements, kindName, walk);
+            if (candidates.length === 0)
+                continue;
+            // One batched checker call per file, then a printed name only for the
+            // types that could be a wrapper at all.
+            const nodes = candidates.flatMap((c) => (c.other ? [c.node, c.other] : [c.node]));
+            const types = await project.checker.getTypeAtLocation(nodes);
+            const printed = new Map();
+            for (let i = 0; i < nodes.length; i += 1) {
+                const t = types[i];
+                if (t && (t.flags & OBJECT_OR_UNION) !== 0) {
+                    printed.set(i, await project.checker.typeToString(t));
+                }
+            }
+            const text = await opts.readFile(file);
+            const rel = opts.relative(opts.appDir, file);
+            let idx = 0;
+            for (const c of candidates) {
+                const leftText = printed.get(idx);
+                idx += 1;
+                const rightText = c.other ? printed.get(idx) : undefined;
+                if (c.other)
+                    idx += 1;
+                const start = startOfNode(text, c.node.pos);
+                const where = lineColumnAt(text, start);
+                const expr = snippet(text, start, c.node.end);
+                if (c.kind === "truthy") {
+                    if (classifyType(leftText) !== "carrier")
+                        continue;
+                    diagnostics.push({
+                        file: rel,
+                        ...where,
+                        code: CODE_TRUTHY,
+                        message: truthyMessage(expr, leftText),
+                        blocking: true,
+                    });
+                    continue;
+                }
+                const otherStart = startOfNode(text, c.other.pos);
+                const otherExpr = snippet(text, otherStart, c.other.end);
+                if (!equalityIsConstant(leftText, rightText, expr, otherExpr))
+                    continue;
+                const carrierIsLeft = classifyType(leftText) === "carrier";
+                const node = carrierIsLeft ? c.node : c.other;
+                const at = carrierIsLeft ? start : otherStart;
+                diagnostics.push({
+                    file: rel,
+                    ...lineColumnAt(text, at),
+                    code: CODE_EQUALITY,
+                    message: equalityMessage(snippet(text, at, node.end), (carrierIsLeft ? leftText : rightText), c.negated === true),
+                    blocking: true,
+                });
+            }
+        }
+        return done({ status: "ok", diagnostics });
+    }
+    catch (err) {
+        return done({
+            status: "failed",
+            diagnostics: [],
+            detail: err?.message ?? String(err),
+        });
+    }
+    finally {
+        try {
+            api?.close();
+        }
+        catch {
+            /* the session is already gone */
+        }
+    }
+}