@specific.dev/spectest 0.79.0 → 0.79.2

package/dist/harness/raw-fetch.js

@@ -1,8 +1,8 @@
 // The real `fetch`, for SDK internals that must not go through the test
 // recorder's wrapper.
 //
-// While a test (or an eval) runs, the daemon replaces `globalThis.fetch`
-// with an instrumented one: it records an `http` event, and it hands back
+// The daemon's `globalThis.fetch` dispatcher instruments calls in the async
+// scope of a test (or setup/eval): it records an `http` event, and hands back
 // a WRAPPED response whose `ok` / `status` are provenance handles rather
 // than a boolean and a number. That is exactly right for a test's own
 // calls, and exactly wrong inside the SDK, in two ways:
@@ -17,8 +17,9 @@
 //      handed its response only after the stream it was waiting to read
 //      has already ended. A long-lived stream deadlocks.
 //
-// So SDK-internal HTTP goes through `rawFetch`. The daemon publishes the
-// original here when it installs its wrapper.
+// Fake execution is explicitly outside that scope. SDK-internal HTTP that
+// runs WITHIN a test's scope goes through `rawFetch` instead. The daemon
+// publishes the original here when it installs its wrapper.
 let original;
 /** Called by the daemon with the real `fetch`, before it installs its
  *  instrumented one. */

package/dist/index.d.ts

@@ -1405,6 +1405,9 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
      * real backing instance, `ctx.dnsName(...)` to name it). Return any
      * `Response`. Thrown errors surface as 500s. The request URL is the
      * absolute URL the client used — useful for routing on the path.
+     * Fake code uses native `fetch`: responses are ordinary `Response` objects
+     * and internal requests are not added to a running test's timeline. This
+     * also applies to state/helper factories and helper implementations.
      */
     handler: (req: Request, state: S, ctx: FakeContext) => Response | Promise<Response>;
     /**
@@ -1420,6 +1423,8 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
      * Every call is tracked in the test timeline: it records a `fake` step
      * and the return value is tagged so a later `expect(...)` on it nests
      * under that step in the UI (same provenance as `fetch`/db results).
+     * Operations inside the helper are uninstrumented, including across awaits;
+     * concurrent operations in test code continue to record normally.
      * The step renders the return value as JSON; wrap it in {@link annotate}
      * to add a richer view (an email, today) that the step's panel leads with,
      * the JSON one tab away — the test still receives the raw value, unchanged

package/dist/recorder.js

@@ -8,6 +8,7 @@
 // current recorder is `null` and the `record*` helpers are no-ops, so
 // callers can invoke them unconditionally.
 import { clearPendingNullish } from "./inspect.js";
+import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 const OUTPUT_SNIPPET_BYTES = 256 * 1024;
 class Recorder {
     events = [];
@@ -117,7 +118,7 @@ export function resumeRecording() {
     paused = Math.max(0, paused - 1);
 }
 function active() {
-    return current !== null && paused === 0;
+    return current !== null && paused === 0 && scopeAllowsRecording();
 }
 export function startRecording() {
     current = new Recorder();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.79.0",
+  "version": "0.79.2",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -95,12 +95,13 @@ import { runWrapperRules } from "./harness/wrapper-rules.js";
 import type { WrapperDiagnostic } from "./harness/wrapper-rules.js";
 import { cpus } from "node:os";
 import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath } from "./project-files.js";
+import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import {
-  isTextualContentType,
-  looksBinary,
-  omittedBody,
-  parseContentLength,
-} from "./harness/http-body.js";
+  bindInstrumentationScope,
+  createInstrumentationScope,
+  runInstrumented,
+  runUninstrumented,
+} from "./harness/instrumentation-scope.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import {
   InterceptRegistry,
@@ -169,16 +170,13 @@ import { openTerminal } from "./terminal.js";
 // `ctx.mcp(url)`. One client per call, no registry: an authenticated
 // client is passed to descendants as a test's return value.
 import { openMcp } from "./mcp.js";
-import { setRawFetch } from "./harness/raw-fetch.js";
 import { readAnnotation, type RenderAnnotation } from "./annotate.js";
 import {
   isRecording,
-  pauseRecording,
   recordEmail,
   recordEnv,
   recordExec,
   recordFake,
-  recordHttp,
   recordStep,
   recordTerminal,
   recordWait,
@@ -186,16 +184,14 @@ import {
   recorderEventCount,
   recorderMarkChildren,
   recorderTruncate,
-  resumeRecording,
   startRecording,
   stopRecording,
   truncateUtf8,
   type StepBlock,
   type TestEvent,
-  type OmittedBody,
 } from "./recorder.js";
-import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
-import type { Wrapped, WrappedResponse } from "./inspect.js";
+import { deepUnwrap, readRaw, wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
 import { generateId } from "./ids.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
@@ -2150,7 +2146,7 @@ async function startIngress(): Promise<void> {
   for (const [name, fake] of FAKES) {
     if (fake.def.state) {
       try {
-        fake.state = await fake.def.state();
+        fake.state = await runUninstrumented(() => fake.def.state!());
       } catch (err) {
         throw new Error(
           `fake ${JSON.stringify(name)} state() factory threw: ${(err as Error).message}`,
@@ -2604,7 +2600,9 @@ async function dispatchIngress(
   const upstream = async (current: Request): Promise<Response> => {
     if (route.kind === "fake") {
       try {
-        return await route.fake.def.handler(current, route.fake.state, FAKE_CTX);
+        return await runUninstrumented(() =>
+          route.fake.def.handler(current, route.fake.state, FAKE_CTX),
+        );
       } catch (err) {
         const e = err as Error;
         return new Response(
@@ -3057,7 +3055,7 @@ function registerInterceptor(
     );
   }
   const resv = reserveEvent();
-  const it = INTERCEPTORS.register(host, path, handler);
+  const it = INTERCEPTORS.register(host, path, bindInstrumentationScope(handler));
   const where = `${host}${it.path === "/" ? "" : it.path}`;
   const seq = recordStep(
     {
@@ -3288,11 +3286,11 @@ async function ensureFakeHelpers(name: string): Promise<Record<string, unknown>>
   if (!fake) throw new Error(`fake ${JSON.stringify(name)} is not loaded`);
   if (fake.trackedHelpers) return fake.trackedHelpers;
   fake.helpers = fake.def.helpers
-    ? ((await fake.def.helpers({
+    ? ((await runUninstrumented(() => fake.def.helpers!({
         name,
         state: fake.state,
         ctx: FAKE_CTX,
-      })) as Record<string, unknown>)
+      }))) as Record<string, unknown>)
     : {};
   fake.trackedHelpers = trackFakeHelpers(name, fake.helpers);
   return fake.trackedHelpers;
@@ -3386,41 +3384,24 @@ function invokeFakeHelper(
     }, resv);
   };
 
-  // A helper call is ONE step. Whatever the fake does inside it — a fetch to
-  // deliver a webhook, a call to its own API — is the fake's plumbing, not
-  // something the test did, and it would otherwise land on the timeline as
-  // an `http` step the test never made. The built-in `email()` helpers
-  // already pause around their internal polls by hand for exactly this
-  // reason (`components/email.ts`); doing it here gives every user-authored
-  // fake the same contract without having to know about it.
-  //
-  // The pause spans the helper's `await`s, so genuinely concurrent test work
-  // (`Promise.all([helper(), ctx.fetch(…)])`) loses its events too. That is
-  // the same trade `email()` has always made, and sequential test code — all
-  // of it, in practice — is unaffected.
-  pauseRecording();
+  // Record the public helper call in the caller's scope, while its body
+  // and async descendants use native fetch and emit no internal events.
   let result: unknown;
   try {
-    result = fn.apply(thisArg, args);
+    result = runUninstrumented(() => fn.apply(thisArg, args));
   } catch (err) {
-    resumeRecording();
     recordError(err);
     throw err;
   }
   if (result instanceof Promise) {
     return result.then(
-      (value) => {
-        resumeRecording();
-        return recordResult(value);
-      },
+      recordResult,
       (err) => {
-        resumeRecording();
         recordError(err);
         throw err;
       },
     );
   }
-  resumeRecording();
   return recordResult(result);
 }
 
@@ -3756,13 +3737,15 @@ async function runProjectSetupInner(): Promise<ProjectSetupResult> {
   // as in a test. No recorder is active here, so it wraps without provenance —
   // but the wrapped type stays honest at runtime (`.unwrap()` works).
   const restoreFetch = installFetchWrapper();
+  const fetchScope = createInstrumentationScope(false);
   // The full context, unscoped: every service is up by project-setup time,
   // so `ctx.svc` is the same map tests see (and shares helper instances with
   // them — a Bun.SQL pool created here is reused later).
   const ctx: ProjectSetupContext = await spectestContext();
   try {
-    await proj.setup(ctx);
+    await runInstrumented(fetchScope, () => proj.setup!(ctx));
   } finally {
+    fetchScope.active = false;
     restoreFetch();
   }
   return { ran: true, durationMs: Date.now() - start };
@@ -4753,173 +4736,6 @@ async function buildServiceHandles(cfg: EnvironmentConfig): Promise<ServiceHandl
 // Instrumentation helpers
 // ────────────────────────────────────────────────────────────────────────
 
-function describeFetchInput(input: Parameters<typeof fetch>[0]): {
-  url: string;
-  methodFromInput?: string;
-} {
-  if (typeof input === "string") return { url: input };
-  if (input instanceof URL) return { url: input.toString() };
-  // Request instance
-  const req = input as Request;
-  return { url: req.url, methodFromInput: req.method };
-}
-
-function describeRequestBody(
-  input: Parameters<typeof fetch>[0],
-  init: Parameters<typeof fetch>[1],
-): { body?: string; truncated?: boolean } {
-  // For Request objects, body has already been consumed into the request;
-  // we can't read it back without cloning, which costs. Skip unless init.body
-  // is provided directly.
-  const body = init?.body;
-  if (body === undefined || body === null) {
-    if (input instanceof Request && input.bodyUsed === false) {
-      // Don't drain the request's body here — leaving it for the actual
-      // fetch. Return a marker.
-      return { body: "[Request body not captured]", truncated: false };
-    }
-    return {};
-  }
-  if (typeof body === "string") {
-    const t = truncateUtf8(body);
-    return { body: t.value, truncated: t.truncated };
-  }
-  if (body instanceof URLSearchParams) {
-    const t = truncateUtf8(body.toString());
-    return { body: t.value, truncated: t.truncated };
-  }
-  return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
-}
-
-/**
- * Marks an error thrown by the instrumented fetch as *transport-level* —
- * the connection itself failed (refused, unresolvable, reset) before any
- * HTTP reply existed. `fetch` never rejects for an HTTP status, so every
- * rejection short of an abort is transport. `Symbol.for` so a duplicated
- * SDK module instance (the bun hardlink landmine) still recognises it.
- *
- * Why it exists: `ctx.poll` waits for convergence, and right after a fork
- * restore the guest can serve a ~10 s window where a connect or a DNS
- * lookup fails once and then heals (measured 2026-08-21: a poll's first
- * fetch hung 12 s in resolution, threw, and killed a 60 s poll on attempt
- * 1 while attempt 2 would have passed). During a poll, a dead connection
- * is just "not ready yet"; outside one it stays a hard error.
- */
-const TRANSPORT_ERROR = Symbol.for("spectest.transportError");
-
-function isTransportError(err: unknown): boolean {
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    (err as Record<symbol, unknown>)[TRANSPORT_ERROR] === true
-  );
-}
-
-/**
- * Install a fetch wrapper on `globalThis` that emits HTTP events into the
- * active recorder. Returns a restore function. Calls outside of a running
- * test still hit the original fetch (the recorder is null then; the
- * wrapper just adds a tiny amount of overhead — but we restore after each
- * test anyway, so this only matters mid-test).
- */
-function installFetchWrapper(): () => void {
-  const original = globalThis.fetch;
-  // SDK internals (the MCP client, its OAuth flow) must not see the
-  // wrapper: a wrapped `res.ok` is an object, and the wrapper reads every
-  // body to the end, which never finishes for an SSE stream.
-  setRawFetch(original);
-  const wrappedFn = async (
-    input: Parameters<typeof fetch>[0],
-    init?: Parameters<typeof fetch>[1],
-  ): Promise<Response | WrappedResponse> => {
-    const start = Date.now();
-    const resv = reserveEvent();
-    const { url, methodFromInput } = describeFetchInput(input);
-    const method = (init?.method ?? methodFromInput ?? "GET").toUpperCase();
-    const reqBody = describeRequestBody(input, init);
-    try {
-      const res = await original(input as RequestInfo, init);
-      let responseBody: string | OmittedBody | undefined;
-      let responseBodyTruncated: boolean | undefined;
-      // The reply the test gets is untouched: everything here reads a clone,
-      // and a body known to be binary is not read at all. See
-      // ./harness/http-body.ts for why a blanket `.text()` was wrong.
-      const contentType = res.headers.get("content-type");
-      const contentLength = () => parseContentLength(res.headers.get("content-length"));
-      const textual = isTextualContentType(contentType);
-      if (textual === false) {
-        responseBody = omittedBody("binary", contentType, contentLength());
-      } else {
-        try {
-          const cloned = res.clone();
-          const text = await cloned.text();
-          if (textual === undefined && looksBinary(text)) {
-            // No content type (or a multipart one), and the bytes say this
-            // was never text.
-            responseBody = omittedBody("binary", contentType, contentLength());
-          } else {
-            const t = truncateUtf8(text);
-            responseBody = t.value;
-            responseBodyTruncated = t.truncated;
-          }
-        } catch {
-          // The stream failed, or something had already consumed the body.
-          responseBody = omittedBody("unreadable", contentType, contentLength());
-        }
-      }
-      const seq = recordHttp({
-        method,
-        url,
-        requestBody: reqBody.body,
-        requestBodyTruncated: reqBody.truncated,
-        status: res.status,
-        responseBody,
-        responseBodyTruncated,
-        durationMs: Date.now() - start,
-      }, resv);
-      return wrapResponse(res, seq);
-    } catch (err) {
-      const e = err as Error;
-      recordHttp({
-        method,
-        url,
-        requestBody: reqBody.body,
-        requestBodyTruncated: reqBody.truncated,
-        durationMs: Date.now() - start,
-        error: e?.message ?? String(err),
-      }, resv);
-      // Tag transport failures for ctx.poll (see TRANSPORT_ERROR). An abort
-      // is the caller's own signal (their AbortController or their
-      // AbortSignal.timeout) — their semantics, never retried for them.
-      if (
-        typeof err === "object" &&
-        err !== null &&
-        e?.name !== "AbortError" &&
-        e?.name !== "TimeoutError"
-      ) {
-        try {
-          (err as Record<symbol, unknown>)[TRANSPORT_ERROR] = true;
-        } catch {
-          /* frozen error object — stays a hard error */
-        }
-      }
-      throw err;
-    }
-  };
-  // Preserve any provider-specific statics on `fetch` (e.g. Bun's
-  // `fetch.preconnect`) so consumers that touch them keep working.
-  const wrapped = wrappedFn as unknown as typeof fetch;
-  for (const key of Object.keys(original) as (keyof typeof original)[]) {
-    (wrapped as unknown as Record<string, unknown>)[key as string] = (
-      original as unknown as Record<string, unknown>
-    )[key as string];
-  }
-  globalThis.fetch = wrapped;
-  return () => {
-    globalThis.fetch = original;
-  };
-}
-
 /** Build the `docker exec` argv for a service command. A string command runs
  *  through `sh -lc`; an array is exact argv with no shell (the
  *  `["psql", "-f", "-"]` shape). An optional `cwd` becomes `-w <cwd>` (the
@@ -5481,6 +5297,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
 
   startRecording();
   const restoreFetch = installFetchWrapper();
+  const fetchScope = createInstrumentationScope();
 
   // Look up the parent's stored return value (if any). The parent ran in
   // an ancestor fork; its TEST_DATA entry travels with the snapshot.
@@ -5622,7 +5439,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   let outcome: { status: "passed" | "failed"; error?: RunResult["error"] };
   try {
     const value = await Promise.race([
-      Promise.resolve(testCase.run(ctx)),
+      Promise.resolve(runInstrumented(fetchScope, () => testCase.run(ctx))),
       timedOut,
     ]);
     // Stash the return value so child cases — which fork from the snapshot
@@ -5639,6 +5456,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     if (timer) clearTimeout(timer);
     RECORDING_EXEC = undefined;
     INTERCEPTORS.endScope();
+    fetchScope.active = false;
     restoreFetch();
     restoreConsole();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -6013,6 +5831,7 @@ async function evalCode(
   // Response just like in a test (no recorder here, so no provenance — but the
   // wrapped type is honest at runtime). Restored in the `finally` below.
   const restoreFetch = installFetchWrapper();
+  const fetchScope = createInstrumentationScope(false);
 
   // Same persistent acquire/detach as a test run (see runOne): the browser
   // survives the eval, so successive `spectest env eval` calls continue one
@@ -6177,7 +5996,8 @@ async function evalCode(
     await fs.mkdir(EVAL_DIR, { recursive: true });
     filePath = path.join(EVAL_DIR, `${randomUUID()}.ts`);
     await fs.writeFile(filePath, prepared.code);
-    const mod = (await import(pathToFileURL(filePath).href)) as { default?: unknown };
+    const moduleUrl = pathToFileURL(filePath).href;
+    const mod = (await runInstrumented(fetchScope, () => import(moduleUrl))) as { default?: unknown };
     outcome = { ok: true, result: safeSerialize(mod.default) };
   } catch (err) {
     const e = err as Error;
@@ -6188,6 +6008,7 @@ async function evalCode(
     };
   } finally {
     clearRecordSecrets();
+    fetchScope.active = false;
     restoreFetch();
     restoreConsole();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any