@specific.dev/spectest 0.66.0 → 0.68.0

package/dist/browser.js

@@ -34,6 +34,7 @@ import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
+import { capturePageStructure } from "./page-snapshot.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { attachBrowserCoverage, browserCoverageActive, harvestBrowserCoverage, } from "./browser-coverage.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
@@ -1122,6 +1123,37 @@ function buildBackend(holder, recorder, buildOpts) {
     // when rrweb's load-deferred full snapshot is most likely to be
     // missing from the chunk we're about to drain (see `drainExpr`).
     let lastDrainUrl = null;
+    // Failed steps that captured their page. Bounded per session per case: a
+    // test that catches its own locator errors in a loop must not pay for a
+    // capture on each one, and three pages is already more than a reader will
+    // open. `ctx.poll` needs no bookkeeping here — it truncates the events of
+    // every superseded attempt, and each capture rides its own event.
+    let pageCaptures = 0;
+    const PAGE_CAPTURE_LIMIT = 3;
+    /** The page behind a failed step, for its event (see page-snapshot.ts).
+     *  Best-effort and quiet: this runs while an error is already on its way
+     *  up, and must never become the failure the author sees. */
+    async function failedPageStructure(action, error) {
+        // No recorder means nothing is recording this op (an eval, a library
+        // caller), so there is no event for the capture to ride out on.
+        if (!recorder || recordingEnded || viewClosed)
+            return undefined;
+        if (pageCaptures >= PAGE_CAPTURE_LIMIT)
+            return undefined;
+        pageCaptures += 1;
+        try {
+            return await capturePageStructure(holder.page, {
+                session: recorder.sessionName ?? "",
+                // A desktop view has no device preset; a phone-emulated one does.
+                kind: holder.device ? "mobile" : "browser",
+                action,
+                error,
+            });
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Session provenance stamped on every recorded op: which replay player
      *  the step belongs to, which named browser it acted on, and where in
      *  the player to seek (`endT`, in rrweb's clock). */
@@ -1203,12 +1235,17 @@ function buildBackend(holder, recorder, buildOpts) {
         catch (err) {
             const e = err;
             const endT = Date.now();
+            const error = e?.message ?? String(err);
+            // Captured after the clock stops, so the diagnostic is not billed to
+            // the step, and before the event is recorded, so it rides it.
+            const pageStructure = await failedPageStructure(action, error);
             recordBrowser({
                 action,
                 ...fields,
                 ...sessionFields(endT),
                 durationMs: endT - t,
-                error: e?.message ?? String(err),
+                error,
+                ...(pageStructure ? { pageStructure } : {}),
             }, resv);
             // Still try to drain — the failure itself may have produced
             // useful rrweb events (mutations from a half-loaded page, etc.).
@@ -1536,12 +1573,16 @@ function buildBackend(holder, recorder, buildOpts) {
             // where the matcher started polling, since that's what `tOffsetMs` means
             // everywhere else (the ops that reserve up front stamp their start).
             const endT = Date.now();
+            // A matcher that ran out of budget is the other half of a failed
+            // browser step, and the page it settled on is the same evidence.
+            const pageStructure = error ? await failedPageStructure(action, error) : undefined;
             const seq = recordBrowser({
                 action,
                 ...fields,
                 ...sessionFields(endT),
                 durationMs: waitedMs,
                 ...(error ? { error } : {}),
+                ...(pageStructure ? { pageStructure } : {}),
             }, reserveBackdated(waitedMs));
             // Drain the rrweb the page buffered while the matcher waited into this
             // step's chunk, so `settledTarget` has bounds to seek into.

package/dist/components/supabase.d.ts

@@ -33,20 +33,6 @@ export interface SupabaseOptions {
     storage?: boolean;
     /** Include Realtime (`<name>-realtime`). Default `true`. */
     realtime?: boolean;
-    /**
-     * Edge functions. `isolation` picks how they run on the edge runtime:
-     * `"shared"` (default) loads every function into **one** isolate, so a
-     * shared module graph (`_shared/`, npm packages) is loaded once rather than
-     * once per function — measured on a 51-function project as 230 MB against
-     * 3.6 GB. Hosted Supabase runs one isolate per function, and the one thing
-     * that differs is module-level state: a singleton in `_shared` is one
-     * object for all functions here, one per function there. `"per-function"`
-     * runs it the hosted way. Either way the runtime, the request each
-     * function sees and the per-function `verify_jwt` are the same.
-     */
-    functions?: {
-        isolation?: "shared" | "per-function";
-    };
     /**
      * Also serve the gateway over **HTTPS** at `https://<hostname>` via the
      * daemon's CA-trusted TLS reverse proxy (in addition to the plain

package/dist/components/supabase.js

@@ -698,9 +698,6 @@ async function validJwt(token: string): Promise<boolean> {
   }
 }
 
-/** How the functions run: every function in one isolate (the default), or
- *  one isolate per function as hosted Supabase does — see sharedWorker. */
-const ISOLATION = Deno.env.get("FUNCTIONS_ISOLATION") === "per-function" ? "per-function" : "shared";
 /** Where the generated entry of the shared isolate lives — outside the repo
  *  mount, which is read-only and the user's checkout, and NOT under /tmp:
  *  the runtime gives its workers an in-memory /tmp, so a file the main
@@ -780,7 +777,8 @@ async function stdServerUrls(dir: string, out: Set<string>): Promise<void> {
 // what differs from hosted Supabase is that module-level state is one
 // object for every function rather than one per function.
 //
-// It stands in only where it can be exact. A function with its own
+// There is deliberately no opt-out: it stands in wherever it can be exact,
+// and where it cannot the per-function isolates are used. A function with its own
 // deno.json / import map (per-function resolution the one config cannot
 // express), a functions/deno.jsonc (comments; not merged) or a config that
 // names an importMap keep the per-function isolates, and so does a shared
@@ -929,7 +927,6 @@ async function writeShared(names: string[]): Promise<string | null> {
 /** The shared isolate (pooled by the runtime under SHARED_DIR), or null when
  *  the functions run one isolate each — decided once, with the reason logged. */
 async function sharedWorker(): Promise<any | null> {
-  if (ISOLATION !== "shared") return null;
   if (!sharedSpec) {
     sharedSpec = (async () => {
       const names = await functionNames();
@@ -1729,9 +1726,6 @@ export function supabase(opts = {}) {
                         JWT_SECRET: jwtSecret,
                         // Where the router looks for `<name>/`, inside the repo mount.
                         FUNCTIONS_DIR: fnServePath,
-                        // One isolate for all functions (default) or one each — see the
-                        // `functions` option and the router's shared-isolate notes.
-                        FUNCTIONS_ISOLATION: opts.functions?.isolation ?? "shared",
                         // The default a function inherits when the config says nothing:
                         // reject an unauthenticated call, as hosted Supabase does.
                         VERIFY_JWT: "true",

package/dist/daemon.js

@@ -39,10 +39,11 @@ 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";
-import { InterceptRegistry, runChain, } from "./harness/intercept.js";
+import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, certEntries, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
@@ -2301,35 +2302,61 @@ function ingressClaimsHostname(hostname) {
     }
     return false;
 }
-/** Record one request an interceptor saw, nested under its `intercept` step. */
+/** Record one request an interceptor saw, nested under its `intercept` step.
+ *
+ * A forced 503 is the step doing exactly what its description says, so it is
+ * **not** marked failed — reddening the outcome the test asked for trains the
+ * reader to ignore the colour. Only a handler that threw is marked, because
+ * that 500 is a bug in the middleware rather than the outage it stands for. */
 function recordInterceptedRequest(it, rec, durationMs) {
     const parentSeq = INTERCEPT_STEP_SEQ.get(it.id);
     if (parentSeq === undefined || !isRecording())
         return;
-    const by = rec.answeredBy === "handler"
-        ? "answered by the interceptor"
-        : rec.answeredBy === "modified"
-            ? "upstream answer replaced by the interceptor"
-            : "passed through to the upstream";
+    const by = rec.threw
+        ? "the interceptor threw — 500 from spectest, not from your handler"
+        : rec.answeredBy === "handler"
+            ? "answered by the interceptor"
+            : rec.answeredBy === "modified"
+                ? "upstream answer replaced by the interceptor"
+                : "passed through to the upstream";
     recordStep({
         kind: "intercept-request",
         parentSeq,
         title: `${rec.method} ${rec.path} → ${rec.status}`,
-        status: rec.status >= 500 && rec.answeredBy !== "upstream" ? "failed" : "passed",
+        status: rec.threw ? "failed" : "passed",
+        // Method, path and status are already the title; the one thing the row
+        // cannot say for itself is who produced that status.
         blocks: [
-            {
-                type: "kv",
-                rows: [
-                    { label: "Host", value: it.hostname },
-                    { label: "Request", value: `${rec.method} ${rec.path}` },
-                    { label: "Status", value: String(rec.status) },
-                    { label: "Answered", value: by },
-                ],
-            },
+            { type: "kv", rows: [{ label: "Answered", value: by, error: rec.threw === true }] },
         ],
         durationMs,
     });
 }
+/** The handler's own source, which is what the interceptor actually does.
+ *
+ * Free and impossible to let rot: Bun runs the project's TypeScript
+ * directly, so `toString()` is the text the author wrote. It is the step's
+ * body, under the description — a mechanism the reader can check against
+ * the intent the description claims. A handler long enough to be a wall of
+ * code folds into a disclosure instead of pushing the requests off screen.
+ */
+function handlerBlocks(handler) {
+    let src;
+    try {
+        src = String(handler);
+    }
+    catch {
+        return [];
+    }
+    const code = { type: "code", lang: "ts", label: "Handler", code: src };
+    return src.split("\n").length > HANDLER_FOLD_LINES
+        ? [{ type: "details", summary: "Handler", blocks: [code] }]
+        : [code];
+}
+/** Past this many lines the handler source is folded away. Chosen so the
+ *  shapes this feature is for — a one-line forced status, a short
+ *  fail-twice-then-pass — always show, and only a real program hides. */
+const HANDLER_FOLD_LINES = 15;
 /**
  * Put middleware in front of a hostname the ingress serves — the
  * implementation behind `ctx.intercept`.
@@ -2338,15 +2365,19 @@ function recordInterceptedRequest(it, rec, durationMs) {
  * the daemon (DNS does not point here), so the interceptor could only be
  * silent — and silence is the failure mode this whole layer is designed
  * against. The message names the two ways to get a route.
+ *
+ * The `description` is required because it is the step's whole title in the
+ * timeline and in the CLI's failure detail: it is what tells a reader why
+ * the UI under test went to its error state. The handler source says how;
+ * only the author can say what it means.
  */
-function registerInterceptor(hostname, pathOrHandler, maybeHandler) {
-    const path = typeof pathOrHandler === "string" ? pathOrHandler : undefined;
-    const handler = typeof pathOrHandler === "function" ? pathOrHandler : maybeHandler;
-    if (typeof hostname !== "string" || hostname.length === 0) {
-        throw new Error("ctx.intercept: a hostname is required");
-    }
-    const host = hostname.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-    if (!handler) {
+function registerInterceptor(target, description, handler) {
+    const { hostname: host, path } = parseTarget(target);
+    if (typeof description !== "string" || description.trim() === "") {
+        throw new Error(`ctx.intercept(${JSON.stringify(target)}): a description is required — what the ` +
+            `environment now does, as the timeline reads it, e.g. "the sync endpoint returns 503".`);
+    }
+    if (typeof handler !== "function") {
         throw new Error("ctx.intercept: a handler (req, next) => Response is required");
     }
     if (!ingressClaimsHostname(host)) {
@@ -2357,19 +2388,41 @@ function registerInterceptor(hostname, pathOrHandler, maybeHandler) {
     }
     const resv = reserveEvent();
     const it = INTERCEPTORS.register(host, path, handler);
+    const where = `${host}${it.path === "/" ? "" : it.path}`;
     const seq = recordStep({
         kind: "intercept",
-        title: `intercept ${host}${it.path === "/" ? "" : it.path}`,
+        // The description alone. The pill already says INTERCEPT, and the
+        // target is in the panel — a row that repeats both spends its width
+        // on what the reader can already see and none of it on the one thing
+        // only the author knows.
+        title: description.trim(),
         blocks: [
+            ...handlerBlocks(handler),
             {
-                type: "kv",
-                rows: [
-                    { label: "Host", value: host },
-                    { label: "Path", value: it.path === "/" ? "/ (every path)" : `${it.path} and below` },
+                // The target IS the summary line, so the closed disclosure still
+                // says where the interceptor sits — a generic "Target" label
+                // would spend the one visible line saying nothing.
+                type: "details",
+                summary: where,
+                blocks: [
+                    {
+                        type: "kv",
+                        rows: [
+                            {
+                                label: "Matches",
+                                value: it.path === "/" ? "every path on this host" : `${it.path} and below`,
+                            },
+                            {
+                                label: "Until",
+                                value: it.scope === undefined ? "remove()" : "the end of this test",
+                            },
+                        ],
+                    },
                 ],
             },
         ],
-        durationMs: 0,
+        // No duration: this is a marker for the moment the interceptor went
+        // up, and "(0 ms)" reads as a step that did nothing.
     }, resv);
     if (seq !== undefined)
         INTERCEPT_STEP_SEQ.set(it.id, seq);
@@ -4081,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;
@@ -5009,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;
@@ -5124,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.
@@ -5137,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/intercept.d.ts

@@ -48,6 +48,12 @@ export interface InterceptedRequest {
      *  upstream via `next()` untouched (`upstream`), or the upstream's answer
      *  replaced by the interceptor after `next()` (`modified`). */
     answeredBy: "handler" | "upstream" | "modified";
+    /** The handler threw (or returned something that is not a `Response`), so
+     *  the 500 below is a bug in the test's own middleware rather than the
+     *  outage it was asked to produce. The distinction cannot be recovered
+     *  from the status: a deliberate 500 and a crashed handler are the same
+     *  number, and only this tells the timeline which one to mark as wrong. */
+    threw?: boolean;
 }
 export interface Interceptor {
     id: number;
@@ -61,6 +67,22 @@ export interface Interceptor {
     calls: number;
     requests: InterceptedRequest[];
 }
+/**
+ * Split an intercept target — `app.test`, `app.test/api/sync`,
+ * `*.example.com/v1` — into the hostname and the mount path.
+ *
+ * The path rides the target rather than a second argument because that is
+ * what it is: part of what the interceptor claims, not a separate knob. It
+ * also keeps the signature down to one string, so the description that
+ * follows can never be mistaken for a path.
+ *
+ * A scheme is tolerated (`https://app.test/api`) since that is how the same
+ * address is written everywhere else.
+ */
+export declare function parseTarget(target: string): {
+    hostname: string;
+    path: string;
+};
 /** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
  *  never `/apix`. `/` matches everything. Query strings do not take part. */
 export declare function pathMounts(mount: string, pathname: string): boolean;

package/dist/harness/intercept.js

@@ -33,6 +33,34 @@
  * plain `Request`/`Response` objects.
  */
 import { isWildcard, wildcardSuffix } from "./hostmatch";
+/**
+ * Split an intercept target — `app.test`, `app.test/api/sync`,
+ * `*.example.com/v1` — into the hostname and the mount path.
+ *
+ * The path rides the target rather than a second argument because that is
+ * what it is: part of what the interceptor claims, not a separate knob. It
+ * also keeps the signature down to one string, so the description that
+ * follows can never be mistaken for a path.
+ *
+ * A scheme is tolerated (`https://app.test/api`) since that is how the same
+ * address is written everywhere else.
+ */
+export function parseTarget(target) {
+    if (typeof target !== "string" || target.trim() === "") {
+        throw new Error("intercept: a target hostname is required, e.g. \"app.test\" or \"app.test/api\"");
+    }
+    const bare = target.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+    const slash = bare.indexOf("/");
+    const hostname = slash === -1 ? bare : bare.slice(0, slash);
+    const rest = slash === -1 ? undefined : bare.slice(slash);
+    if (hostname === "") {
+        throw new Error(`intercept: target ${JSON.stringify(target)} names no hostname — write it as "app.test/api", not "/api"`);
+    }
+    if (hostname.includes("?") || hostname.includes("#")) {
+        throw new Error(`intercept: target ${JSON.stringify(target)} cannot carry a query or fragment`);
+    }
+    return { hostname, path: normalizeMount(rest) };
+}
 /** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
  *  never `/apix`. `/` matches everything. Query strings do not take part. */
 export function pathMounts(mount, pathname) {
@@ -159,6 +187,7 @@ export async function runChain(chain, req, upstream, observe) {
             res = new Response(`spectest-daemon: interceptor for ${it.hostname} threw: ${e?.message ?? String(err)}\n`, { status: 500, headers: { "content-type": "text/plain" } });
             record.answeredBy = "handler";
             record.status = 500;
+            record.threw = true;
             it.calls++;
             it.requests.push(record);
             observe?.(it, record, Date.now() - started);

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 {};