cursedbelt-server 4.8.0 → 4.11.0

package/dist/server/bench/cpuClock.d.ts

@@ -40,6 +40,10 @@ export interface CpuClock {
  * That is why {@link runCpuBench} drives its cases SERIALLY — a serial driver is what
  * makes this proxy sound enough to gate on. Mounted in production it is advisory: useful
  * for ranking routes, not for a billing claim.
+ *
+ * Where the runtime has no such reading, this returns {@link unavailableCpuClock} — a
+ * clock, never a throw. {@link probeProcessCpuUsage} is what decides, and it decides by
+ * CALLING.
  */
 export declare function processCpuClock(): CpuClock;
 /**

package/dist/server/bench/cpuClock.js

@@ -26,11 +26,15 @@
  * That is why {@link runCpuBench} drives its cases SERIALLY — a serial driver is what
  * makes this proxy sound enough to gate on. Mounted in production it is advisory: useful
  * for ranking routes, not for a billing claim.
+ *
+ * Where the runtime has no such reading, this returns {@link unavailableCpuClock} — a
+ * clock, never a throw. {@link probeProcessCpuUsage} is what decides, and it decides by
+ * CALLING.
  */
 export function processCpuClock() {
-    const usable = typeof process !== 'undefined' && typeof process.cpuUsage === 'function';
-    if (!usable)
-        return unavailableCpuClock('process.cpuUsage (absent)');
+    const probe = probeProcessCpuUsage();
+    if (!probe.ok)
+        return unavailableCpuClock(`process.cpuUsage (${probe.why})`);
     return {
         source: 'process.cpuUsage',
         proxy: true,
@@ -44,6 +48,56 @@ export function processCpuClock() {
         },
     };
 }
+/**
+ * 🔴 **Is `process.cpuUsage()` a clock here? Answered by CALLING it, never by `typeof`.**
+ *
+ * Measured 2026-09-19 on the first real deploy of a Worker mounting `cpuBudget()`: under
+ * `nodejs_compat`, workerd's strategy for the parts of `node:process` it does not implement
+ * is to PROVIDE the method and throw when it is called —
+ *
+ * ```
+ * Error [ERR_METHOD_NOT_IMPLEMENTED]: The process.cpuUsage method is not implemented
+ *     at process.cpuUsage (node-internal:public_process:235:11)
+ * ```
+ *
+ * — so `typeof process.cpuUsage === 'function'` answers *yes* about the one runtime the
+ * probe exists to answer *no* about. The clock that came back threw on first use, and
+ * because `cpuBudget()` is mounted FIRST by design, the throw landed in front of the whole
+ * app: every path 500, with 843 green tests behind it, because `bun test` runs where the
+ * method works.
+ *
+ * This is a capability CLASS, not one method: `nodejs_compat` stubs a great deal of
+ * `node:process`, `node:os` and `node:v8` the same way. `src/nodeBuiltinsAreProbedByCalling.spec.ts`
+ * is the check that keeps a `typeof` gate from coming back anywhere in this library.
+ *
+ * Both call shapes are exercised, because the span uses both and only one of them is
+ * probed by the first: `cpuUsage()` for the baseline and `cpuUsage(before)` for the delta.
+ * That costs two calls at wiring time — the same trade {@link workerCpuClock} argues for on
+ * the other side, and the alternative is a gate that reads zero for ever.
+ */
+function probeProcessCpuUsage() {
+    // Present-but-throwing and absent are both unavailable; the distinction only LABELS the
+    // clock, and is never the decision — which is why this line may carry the excuse that
+    // `src/nodeBuiltinsAreProbedByCalling.spec.ts` refuses everywhere else.
+    // probe-by-calling:ignore — label only; the call below is what decides.
+    const present = typeof process !== 'undefined' && typeof process.cpuUsage === 'function';
+    let reading;
+    try {
+        // A bare `process` that does not exist throws a ReferenceError in here, which is the
+        // same answer as a method that throws: not a clock.
+        const before = process.cpuUsage();
+        const delta = process.cpuUsage(before);
+        reading = before.user + before.system + delta.user + delta.system;
+    }
+    catch {
+        return { ok: false, why: present ? 'throws' : 'absent' };
+    }
+    // A stub that returns something non-numeric is no more usable than one that throws, and
+    // would otherwise reach the recorder as a confident 0.00 for every route.
+    if (!Number.isFinite(reading))
+        return { ok: false, why: 'non-numeric' };
+    return { ok: true };
+}
 /**
  * A clock over a CPU-ms reader the runtime supplies. `proxy: false` — this is the real
  * quantity Cloudflare bills, so a report built on it may be quoted as one.

package/dist/server/bench/runBench.d.ts

@@ -31,6 +31,33 @@ export interface BenchCase {
      * that never ran — a green budget over a broken route.
      */
     expectStatus?: number | number[] | ((status: number) => boolean);
+    /**
+     * Called before EVERY iteration of this case — warm-up included. For a **destructive**
+     * route, rebuild the fixture here; without it the second call measures an empty database.
+     *
+     * 🔴 This is the hook a destructive route cannot be benched without. `runCpuBench` fires a
+     * case `warmup + iterations` times against ONE app instance, which is exactly right for a
+     * read and a lie for a purge: the first call runs against a populated library and the next
+     * twenty-nine against an empty one, so the p99 is a small number for the wrong reason and
+     * the budget it satisfies means nothing. `expectStatus` cannot catch it either — the second
+     * call legitimately answers 200 with `{ deleted: 0 }`.
+     *
+     * It is **per case**, not run-wide, so the cheap read cases pay nothing for it — neither
+     * the rebuild nor the accounting {@link runCpuBench} does around it.
+     *
+     * 🔴 **Its cost is not measured, and that is checked rather than assumed.** The recorder is
+     * written through by the `cpuBudget()` middleware inside `app.fetch`, so a hook that runs
+     * outside that call is already excluded by ordering — but ordering is an accident, and a
+     * fixture rebuild that cost 200 ms and got attributed to the route would make this feature
+     * a worse lie than the hole it closes. So {@link runCpuBench} refuses a hook that drives
+     * the app under bench (see the error it throws), and `cpuBudget.spec.ts` proves a hook that
+     * burns real CPU leaves the route's number alone.
+     *
+     * `iteration` is 0-based and monotonic across the WHOLE case, warm-up first: warm-up gets
+     * `0 … warmup-1` and the measured pass continues from `warmup`. A hook that seeds ids from
+     * it therefore never collides between the two passes.
+     */
+    beforeEach?: (c: BenchCase, iteration: number) => void | Promise<void>;
 }
 export interface RunCpuBenchOpts {
     /** Anything with Hono's `fetch` shape. */

package/dist/server/bench/runBench.js

@@ -25,6 +25,39 @@ function statusAllowed(c, status) {
 function describe(c) {
     return `${(c.method ?? 'GET').toUpperCase()} ${c.path}`;
 }
+/**
+ * Every request the recorder has attributed to any route so far. `samples` counts what was
+ * SEEN rather than what the reservoir retained, so this only ever goes up within a phase.
+ */
+function totalSamples(recorder) {
+    let n = 0;
+    for (const r of recorder.report().routes)
+        n += r.samples;
+    return n;
+}
+/**
+ * Run a case's {@link BenchCase.beforeEach}, and prove it stayed out of the histogram.
+ *
+ * 🔴 The obvious way to rebuild a fixture is to drive the app that already has the routes —
+ * `POST /api/upload` thirty times to re-seed a library. Those requests go through
+ * `cpuBudget()` like any other, so the rebuild lands in the report as real samples on real
+ * routes, and the destructive route this hook exists to measure honestly is now benched
+ * beside rows nobody asked for. Refusing it here is cheap and only costs a case that has a
+ * hook at all.
+ */
+async function prepare(opts, c, iteration) {
+    if (!c.beforeEach)
+        return;
+    const before = totalSamples(opts.recorder);
+    await c.beforeEach(c, iteration);
+    const after = totalSamples(opts.recorder);
+    if (after !== before) {
+        throw new Error(`cpu-bench: ${describe(c)}'s beforeEach drove ${after - before} request(s) through the ` +
+            'app under bench, so the fixture rebuild is now IN the measurement it exists to keep ' +
+            'out of it. Rebuild the fixture directly — against the database, the store, the ' +
+            'seed helper — never through app.fetch.');
+    }
+}
 async function fire(opts, c) {
     const method = (c.method ?? c.init?.method ?? 'GET').toUpperCase();
     const req = new Request(`${opts.origin ?? BENCH_ORIGIN}${c.path}`, { ...c.init, method });
@@ -46,16 +79,23 @@ export async function runCpuBench(opts) {
     const warmup = opts.warmup ?? 5;
     if (!(iterations > 0))
         throw new Error('runCpuBench: iterations must be > 0');
+    // `beforeEach` runs over the warm-up too, deliberately. Warm-up exists to reach a handler's
+    // steady state, and a destructive route warmed against the empty database it emptied warms
+    // the wrong branch — the loop the p99 is about never runs.
     for (const c of opts.cases) {
-        for (let i = 0; i < warmup; i += 1)
+        for (let i = 0; i < warmup; i += 1) {
+            await prepare(opts, c, i);
             await fire(opts, c);
+        }
     }
     // 🔴 Everything above was warm-up. Discard it — measuring it is the bug this guards.
     opts.recorder.reset();
     for (const c of opts.cases) {
         const n = c.iterations ?? iterations;
-        for (let i = 0; i < n; i += 1)
+        for (let i = 0; i < n; i += 1) {
+            await prepare(opts, c, warmup + i);
             await fire(opts, c);
+        }
     }
     return opts.recorder.report();
 }

package/dist/server/d1/index.d.ts

@@ -15,7 +15,7 @@
  * ```
  */
 export { type BackupPoint, createTimeTravelBackup, type DatabaseBackup, type TimeTravelOpts, } from './backup';
-export { type InvocationD1, perInvocation } from './invocation';
+export { createPendingWrites, type InvocationD1, type PendingWrites, perInvocation, type WriteCollector } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';
 export { createRemoteD1, type D1BindingLike, type D1BindingMeta, type D1BindingResult, type D1BindingStatement, } from './remote';

package/dist/server/d1/index.js

@@ -33,7 +33,7 @@ export { createTimeTravelBackup, } from './backup';
 // that does not use the query builder — which per `../db/kysely.ts`'s own header is most
 // of them, since business tables stay on raw statements. Measured 2026-09-18 against the
 // published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
-export { perInvocation } from './invocation';
+export { createPendingWrites, perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';
 export { createRemoteD1, } from './remote';

package/dist/server/d1/invocation.d.ts

@@ -39,6 +39,14 @@
  * It wraps either driver, because it sits ABOVE the seam and only counts. That is what
  * makes the local gate able to prove a production-only limit: wrap a local database in a
  * test, run the loop, and the laptop fails exactly where the Worker would.
+ *
+ * ## The other thing that is true for the span of one request: {@link createPendingWrites}
+ *
+ * A Worker port's synchronous stores answer from a snapshot and queue their durable writes
+ * as promises, which the entry point awaits BEFORE the response leaves. That collector has
+ * the same lifetime as the budget above — one per invocation, constructed by the caller in
+ * the same breath — so it lives in the same file. See its own header for why it was moved
+ * here on 2026-09-19.
  */
 import { type D1LikeDatabase } from './types';
 /**
@@ -70,3 +78,67 @@ export interface InvocationD1 extends D1LikeDatabase {
 export declare function perInvocation(db: D1LikeDatabase, opts?: {
     max?: number;
 }): InvocationD1;
+/**
+ * Where a durable write goes on its way out of one invocation.
+ *
+ * Deliberately two members, and the narrower `add`-only half is what a STORE takes. A store
+ * that also held `settle` could end the request's writes from inside the request, which is
+ * the entry point's job and nobody else's. `cursedauth/d1-stores` declares exactly this
+ * two-method shape under its own name (`WriteCollector`) because that package sits UNDER
+ * this one and may not import it — structural typing means an object made here satisfies it
+ * verbatim, with no dependency edge in either direction.
+ */
+export interface WriteCollector {
+    add(promise: Promise<unknown>): void;
+}
+/** A write that must land before the response is returned. See {@link createPendingWrites}. */
+export interface PendingWrites extends WriteCollector {
+    /** Await every collected write. Called BEFORE the response is returned, never after. */
+    settle(): Promise<void>;
+}
+/**
+ * Collect the durable writes of ONE invocation, to be awaited before the response leaves.
+ *
+ * ## Why this is the Worker-write primitive and not a convenience
+ *
+ * A ported app's synchronous stores cannot await — their signatures are somebody else's
+ * published contract — so the shape every port lands on is: one read fills a snapshot, every
+ * sync call answers from it, and every mutation both updates the snapshot and pushes its
+ * statement's promise in here. The entry point then does the awaiting:
+ *
+ * ```ts
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const db     = perInvocation(createRemoteD1(env.DB));
+ *     const writes = createPendingWrites();
+ *     const res    = await app.fetch(req, { db, writes });
+ *     await writes.settle();          // 🔴 BEFORE the response, never after
+ *     return res;
+ *   },
+ * };
+ * ```
+ *
+ * 🔴 **`settle()` before the response, never `ctx.waitUntil`.** A Worker isolate is per-colo
+ * and short-lived; a write acknowledged by a 200 and then dropped means "sign out" reported
+ * success and left the credential live — a failure invisible to any single-process test and
+ * indistinguishable, to the person, from the feature being broken.
+ *
+ * 🔴 **`Promise.all`, not `allSettled`.** A failed durable write must not be reported as a
+ * success. It surfaces as a 500 from the entry point, which is the honest answer to "did my
+ * sign-out take". `allSettled` here would convert every lost write into a silent 200 — the
+ * same outcome as not collecting them at all, reached by a road that looks careful.
+ *
+ * ## Why it lives here
+ *
+ * It was written three times before it was published once — `apps/patterns/worker/stores.ts`,
+ * `apps/collections/worker/stores.ts` and `libs/cursedauth/src/d1Stores.ts`, byte-identical
+ * but for a comment, with six more ports queued behind them. It is a D1-INVOCATION primitive
+ * rather than an auth one, so it belongs beside {@link perInvocation}: both are constructed
+ * per request, both describe what is true for the span of one, and neither knows anything
+ * about who is signed in.
+ *
+ * Ordering is NOT what this gives you. Everything added is already in flight, so two writes
+ * that must land in order go in one `batch()`, never in two `add`s — a DELETE that must
+ * precede its INSERT will otherwise race and trip a unique index.
+ */
+export declare function createPendingWrites(): PendingWrites;

package/dist/server/d1/invocation.js

@@ -39,6 +39,14 @@
  * It wraps either driver, because it sits ABOVE the seam and only counts. That is what
  * makes the local gate able to prove a production-only limit: wrap a local database in a
  * test, run the loop, and the laptop fails exactly where the Worker would.
+ *
+ * ## The other thing that is true for the span of one request: {@link createPendingWrites}
+ *
+ * A Worker port's synchronous stores answer from a snapshot and queue their durable writes
+ * as promises, which the entry point awaits BEFORE the response leaves. That collector has
+ * the same lifetime as the budget above — one per invocation, constructed by the caller in
+ * the same breath — so it lives in the same file. See its own header for why it was moved
+ * here on 2026-09-19.
  */
 import { LIMITS } from './limits';
 import { D1LimitError } from './types';
@@ -164,3 +172,60 @@ export function perInvocation(db, opts = {}) {
         },
     };
 }
+/**
+ * Collect the durable writes of ONE invocation, to be awaited before the response leaves.
+ *
+ * ## Why this is the Worker-write primitive and not a convenience
+ *
+ * A ported app's synchronous stores cannot await — their signatures are somebody else's
+ * published contract — so the shape every port lands on is: one read fills a snapshot, every
+ * sync call answers from it, and every mutation both updates the snapshot and pushes its
+ * statement's promise in here. The entry point then does the awaiting:
+ *
+ * ```ts
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const db     = perInvocation(createRemoteD1(env.DB));
+ *     const writes = createPendingWrites();
+ *     const res    = await app.fetch(req, { db, writes });
+ *     await writes.settle();          // 🔴 BEFORE the response, never after
+ *     return res;
+ *   },
+ * };
+ * ```
+ *
+ * 🔴 **`settle()` before the response, never `ctx.waitUntil`.** A Worker isolate is per-colo
+ * and short-lived; a write acknowledged by a 200 and then dropped means "sign out" reported
+ * success and left the credential live — a failure invisible to any single-process test and
+ * indistinguishable, to the person, from the feature being broken.
+ *
+ * 🔴 **`Promise.all`, not `allSettled`.** A failed durable write must not be reported as a
+ * success. It surfaces as a 500 from the entry point, which is the honest answer to "did my
+ * sign-out take". `allSettled` here would convert every lost write into a silent 200 — the
+ * same outcome as not collecting them at all, reached by a road that looks careful.
+ *
+ * ## Why it lives here
+ *
+ * It was written three times before it was published once — `apps/patterns/worker/stores.ts`,
+ * `apps/collections/worker/stores.ts` and `libs/cursedauth/src/d1Stores.ts`, byte-identical
+ * but for a comment, with six more ports queued behind them. It is a D1-INVOCATION primitive
+ * rather than an auth one, so it belongs beside {@link perInvocation}: both are constructed
+ * per request, both describe what is true for the span of one, and neither knows anything
+ * about who is signed in.
+ *
+ * Ordering is NOT what this gives you. Everything added is already in flight, so two writes
+ * that must land in order go in one `batch()`, never in two `add`s — a DELETE that must
+ * precede its INSERT will otherwise race and trip a unique index.
+ */
+export function createPendingWrites() {
+    const pending = [];
+    return {
+        add: (promise) => void pending.push(promise),
+        async settle() {
+            // `all`, not `allSettled`: a failed durable write must not be reported as a
+            // success. It surfaces as a 500 from the entry point, which is the honest answer
+            // to "did my sign-out take".
+            await Promise.all(pending);
+        },
+    };
+}

package/dist/server/storage/files/chunkedUpload.d.ts

@@ -35,7 +35,7 @@ export interface ChunkedUploadService {
 /**
  * Mint the direct-to-backend PUT URL for one chunk. The app supplies this so the module stays
  * backend-agnostic. For binary-server: `${base}/upload-chunk/${app}/${key}?token=` with a token
- * carrying { k, uid, sid, ci, tc }.
+ * carrying { k, uid, sid, ci, tc, sz }.
  */
 export type MintChunkUpload = (args: {
     key: string;
@@ -43,6 +43,17 @@ export type MintChunkUpload = (args: {
     ci: number;
     tc: number;
     owner: string;
+    /**
+     * The SOURCE byte length this session was opened with — pass it straight into the token's `sz`
+     * claim (`FileTokenClaims.sz`), which is the only end-to-end integrity check the upload path
+     * has: binary-server compares it to the assembled object and answers 422 instead of indexing a
+     * short one.
+     *
+     * 🔴 `undefined` when the caller could not state a positive length, and then the claim must be
+     * OMITTED rather than sent as `0` — a declared zero refuses every assemble. That is the same
+     * posture the claim itself has: optional, so that declaring it could never take an upload down.
+     */
+    sz?: number;
 }) => Promise<string>;
 export declare function createChunkedUploadService(cfg: {
     catalogue: FileCatalogue;

package/dist/server/storage/files/chunkedUpload.js

@@ -39,7 +39,12 @@ export function createChunkedUploadService(cfg) {
                 tags: req.tags,
                 createdAt: now(),
             });
-            const chunkUploadUrls = await Promise.all(Array.from({ length: chunkCount }, (_, ci) => cfg.mintChunkUpload({ key, sid, ci, tc: chunkCount, owner })));
+            // 🔴 The source length rides along, because `chunkCount` above is derived from it and a
+            // count is not a length: a session that splits the file wrongly stores whatever it sent,
+            // faithfully, with a 201. Omitted rather than zeroed when the caller stated no positive
+            // size — `sz: 0` would refuse every assemble. See `MintChunkUpload.sz`.
+            const declaredSize = Number.isFinite(req.size) && req.size > 0 ? req.size : undefined;
+            const chunkUploadUrls = await Promise.all(Array.from({ length: chunkCount }, (_, ci) => cfg.mintChunkUpload({ key, sid, ci, tc: chunkCount, owner, sz: declaredSize })));
             return { fileId, sid, key, chunkSize, chunkCount, chunkUploadUrls };
         },
         async complete(sid, confirmed) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.8.0",
+	"version": "4.11.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

package/src/nodeBuiltinsAreProbedByCalling.spec.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from 'bun:test';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * 🔴 **No `typeof x === 'function'` gate in front of a Node built-in. Probe by CALLING.**
+ *
+ * Measured 2026-09-19, the first real deploy of a cursedbelt app onto Workers:
+ * `https://collections.curtwphillips.workers.dev/healthz` answered `500` on **every path**,
+ * with 843 green tests behind it. One line did it — `bench/cpuClock.ts`:
+ *
+ * ```ts
+ * const usable = typeof process !== 'undefined' && typeof process.cpuUsage === 'function';
+ * ```
+ *
+ * Under `nodejs_compat`, workerd's strategy for the parts of `node:process` it does not
+ * implement is to PROVIDE the method and throw when it is called:
+ *
+ * ```
+ * Error [ERR_METHOD_NOT_IMPLEMENTED]: The process.cpuUsage method is not implemented
+ *     at process.cpuUsage (node-internal:public_process:235:11)
+ *     at Object.start (index.js:2772:30)     <- cpuBudget's middleware
+ * ```
+ *
+ * So the availability probe answered *yes* about the one runtime it exists to answer *no*
+ * about, and because `cpuBudget()` is mounted first by design, the throw landed in front of
+ * the whole app.
+ *
+ * 🔴 **That is a capability CLASS, not one method.** `nodejs_compat` stubs a great deal of
+ * `node:process`, `node:os` and `node:v8` the same way, and five apps have a "move to a
+ * Worker" task queued behind this library. `cpuClock.ts` is fixed; this is what stops the
+ * shape coming back somewhere else, where the next deploy would find it instead of a test.
+ *
+ * ## What it measures
+ *
+ * For every non-spec source file: blank the comments and string/template literals, work out
+ * which identifiers name a Node built-in (the `process` global, plus every binding imported
+ * from a `node:*` module, static or dynamic), and red on `typeof <that>.… === 'function'` in
+ * either direction and either operand order.
+ *
+ * `typeof x === 'undefined'` is deliberately NOT flagged: "is there a `process` at all" is a
+ * question a stub cannot lie about, and it is the guard that stops a bare reference throwing
+ * a `ReferenceError` before any `try` can catch it. What is forbidden is concluding a method
+ * WORKS because it EXISTS.
+ *
+ * ## The excuse, and why there is one
+ *
+ * A line carrying `probe-by-calling:ignore` (on it, or on the line above) is allowed — for
+ * the one honest use left: labelling. `cpuClock.ts` decides by calling and then uses a
+ * presence check only to say `(absent)` or `(throws)` in the clock's source string. Excuse
+ * the LINE, never delete the rule.
+ *
+ * ## Verified failing before it was trusted, 2026-09-19
+ *
+ * Four probes, each written to a scratch `src/server/bench/probe.agent.ts`, run, and deleted:
+ *
+ *   · the pre-fix line itself, `typeof process !== 'undefined' && typeof process.cpuUsage
+ *     === 'function'` → **red**, `1 pass, 1 fail`, naming
+ *     `server/bench/probe.agent.ts:1 — typeof process.cpuUsage === 'function'`
+ *   · the same line under a `probe-by-calling:ignore` comment → green — the excuse working
+ *   · `typeof process !== 'undefined'` alone → green — the carve-out working
+ *   · `import { homedir } from 'node:os'` + `typeof homedir === 'function'` → **red**, naming
+ *     line 2. That is the import-tracking half, which the `process` global never exercises.
+ *
+ * 🔴 The first probe is why there was a rewrite rather than a lucky green: run against the
+ * scanner's first draft it PASSED, because that draft blanked string literals along with
+ * comments and the pattern it hunts for ends in the literal `'function'`. A check whose
+ * first probe is green is a check nobody has seen work — see {@link stripComments}.
+ */
+
+const SRC = fileURLToPath(new URL('.', import.meta.url));
+
+/** `typeof A.b.c === 'function'`, and the three other ways to write it. */
+const TYPEOF_FUNCTION =
+  /typeof\s+([A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)\s*[!=]==?\s*['"]function['"]|['"]function['"]\s*[!=]==?\s*typeof\s+([A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)/g;
+
+/** The one global that is a Node built-in without being imported. */
+const GLOBAL_NODE_BUILTINS = new Set(['process']);
+
+const IGNORE_MARKER = 'probe-by-calling:ignore';
+
+/**
+ * Blank COMMENTS, preserving line structure and every string literal, so a scanner is not
+ * fooled by prose.
+ *
+ * 🔴 Both halves of that are load-bearing, and each was found by a probe rather than by
+ * reasoning. Comments must go: this package is comment-dense and `cpuClock.ts`'s own header
+ * QUOTES the forbidden line as the bug it fixed, so a comment-blind scan reds on the fix.
+ * Strings must STAY: the pattern this looks for ends in `'function'`, which IS a string
+ * literal — blanking literals made the check silently unable to match anything at all, and
+ * a probe file carrying the exact pre-fix line passed. Strings are still TRACKED (never
+ * blanked) so that a `//` inside one — `'https://…'` — cannot be read as a comment.
+ */
+function stripComments(source: string): string {
+  let out = '';
+  let i = 0;
+  while (i < source.length) {
+    const c = source[i];
+    const next = source[i + 1];
+    if (c === '/' && next === '/') {
+      while (i < source.length && source[i] !== '\n') {
+        out += ' ';
+        i += 1;
+      }
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      while (i < source.length && !(source[i] === '*' && source[i + 1] === '/')) {
+        out += source[i] === '\n' ? '\n' : ' ';
+        i += 1;
+      }
+      out += '  ';
+      i += 2;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') {
+      const quote = c;
+      out += c;
+      i += 1;
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === '\\') {
+          out += source[i];
+          i += 1;
+          if (i < source.length) {
+            out += source[i];
+            i += 1;
+          }
+          continue;
+        }
+        out += source[i];
+        i += 1;
+      }
+      out += source[i] ?? '';
+      i += 1;
+      continue;
+    }
+    out += c;
+    i += 1;
+  }
+  return out;
+}
+
+/** Every local name in this file that refers to something out of a `node:*` module. */
+function nodeBuiltinRoots(code: string): Set<string> {
+  const roots = new Set(GLOBAL_NODE_BUILTINS);
+  // `import x, { a, b as c } from 'node:os'` / `import * as os from 'node:os'`
+  // and `const { homedir } = await import('node:os')`.
+  const statics = /import\s+([\s\S]*?)\s+from\s+['"]node:[^'"]+['"]/g;
+  const dynamics =
+    /(?:const|let|var)\s+(\{[^}]*\}|[A-Za-z_$][\w$]*)\s*=\s*await\s+import\s*\(\s*['"]node:/g;
+  // 🔴 Read from the RAW source, not the stripped copy: the module specifier is a string
+  // literal, so stripping blanks the very `'node:os'` this has to match. A binding named
+  // only inside a comment widens the rule by one identifier, which is the safe direction.
+  for (const m of code.matchAll(statics)) collectBindings(m[1] ?? '', roots);
+  for (const m of code.matchAll(dynamics)) collectBindings(m[1] ?? '', roots);
+  return roots;
+}
+
+/** Pull the local names out of an import clause: `x, { a, b as c }`, `* as ns`, `{ a }`. */
+function collectBindings(clause: string, into: Set<string>): void {
+  for (const part of clause.replace(/[{}]/g, ',').split(',')) {
+    const token = part.trim();
+    if (!token || token === 'type') continue;
+    const aliased = token.match(/\bas\s+([A-Za-z_$][\w$]*)$/);
+    const name = aliased ? aliased[1] : token.replace(/^type\s+/, '');
+    if (/^[A-Za-z_$][\w$]*$/.test(name)) into.add(name);
+  }
+}
+
+function sourceFiles(dir: string, found: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = `${dir}${entry}`;
+    if (statSync(full).isDirectory()) {
+      sourceFiles(`${full}/`, found);
+      continue;
+    }
+    // Specs are excluded: a test may legitimately assert about a probe, and a `typeof`
+    // gate in one cannot 500 a deployed app.
+    if (entry.endsWith('.ts') && !entry.endsWith('.spec.ts')) found.push(full);
+  }
+  return found;
+}
+
+interface Violation {
+  file: string;
+  line: number;
+  text: string;
+}
+
+function scan(): Violation[] {
+  const violations: Violation[] = [];
+  for (const file of sourceFiles(SRC)) {
+    const raw = readFileSync(file, 'utf8');
+    const rawLines = raw.split('\n');
+    const code = stripComments(raw);
+    const roots = nodeBuiltinRoots(raw);
+    code.split('\n').forEach((line, index) => {
+      for (const m of line.matchAll(TYPEOF_FUNCTION)) {
+        const subject = (m[1] ?? m[2] ?? '').replace(/\s+/g, '');
+        const root = subject.split('.')[0];
+        if (!roots.has(root)) continue;
+        const here = rawLines[index] ?? '';
+        const above = rawLines[index - 1] ?? '';
+        if (here.includes(IGNORE_MARKER) || above.includes(IGNORE_MARKER)) continue;
+        violations.push({
+          file: file.slice(SRC.length),
+          line: index + 1,
+          text: `typeof ${subject} === 'function'`,
+        });
+      }
+    });
+  }
+  return violations;
+}
+
+describe('Node built-ins are probed by CALLING, never by typeof', () => {
+  it('has a real tree to scan — otherwise every assertion below passes vacuously', () => {
+    const files = sourceFiles(SRC);
+    expect(files.length).toBeGreaterThan(100);
+    // The scanner must actually resolve `node:*` imports, or the import half is dead.
+    const withOsImport = files.find((f) => f.endsWith('server/sqlite/export.ts'));
+    expect(withOsImport).toBeTruthy();
+    expect(nodeBuiltinRoots(readFileSync(withOsImport as string, 'utf8')).has('tmpdir')).toBe(true);
+  });
+
+  it('finds no typeof gate in front of a Node built-in anywhere in src', () => {
+    const violations = scan();
+    const message = violations.map((v) => `  ${v.file}:${v.line} — ${v.text}`).join('\n');
+    expect(
+      violations.length === 0 ? '' : `\n${message}\n\nProbe by calling, inside a try.\n`,
+    ).toBe('');
+  });
+});