@specific.dev/spectest 0.107.2 → 0.108.0

package/dist/recorder.js

@@ -7,12 +7,18 @@
 // When no test is running (production code paths, eval, etc.) the
 // current recorder is `null` and the `record*` helpers are no-ops, so
 // callers can invoke them unconditionally.
+import { AsyncLocalStorage } from "node:async_hooks";
 import { clearPendingNullish } from "./inspect.js";
 import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 const OUTPUT_SNIPPET_BYTES = 256 * 1024;
 class Recorder {
     start;
-    events = [];
+    rootEvents = [];
+    pendingHelpers = new Set();
+    get events() {
+        const branch = recordingBranches.getStore();
+        return branch?.owner === this ? branchEvents(branch) : this.rootEvents;
+    }
     seq = 0;
     constructor(start = Date.now()) {
         this.start = start;
@@ -106,6 +112,48 @@ class Recorder {
     }
 }
 let current = null;
+const recordingBranches = new AsyncLocalStorage();
+function branchEvents(branch) {
+    return branch.state === "kept"
+        ? branch.parent ? branchEvents(branch.parent) : branch.destination
+        : branch.events;
+}
+function branchAllowsRecording(branch) {
+    return !branch || (branch.owner === current && branch.state !== "discarded" &&
+        branchAllowsRecording(branch.parent));
+}
+/** Buffer a helper's async descendants until its return chooses between the
+ * implementation's events and one annotated helper call. Seqs still come from
+ * the test recorder, so concurrent calls and linked assertions stay unique.
+ * Poll truncation/grouping inside the helper applies only to its own buffer. */
+export function captureRecording() {
+    if (!active())
+        return { run: (fn) => fn(), finish: () => { }, isCurrent: () => false };
+    const branch = {
+        owner: current, events: [], parent: recordingBranches.getStore(),
+        destination: current.drain(), state: "open",
+    };
+    current.pendingHelpers.add(branch);
+    return {
+        run: (fn) => recordingBranches.run(branch, fn),
+        isCurrent: () => branch.owner === current && active(),
+        finish(keep) {
+            if (branch.state !== "open")
+                return;
+            branch.owner.pendingHelpers.delete(branch);
+            if (keep && branchAllowsRecording(branch)) {
+                const destination = branch.parent ? branchEvents(branch.parent) : branch.destination;
+                for (const event of branch.events)
+                    destination.push(event);
+                branch.state = "kept";
+            }
+            else {
+                branch.state = "discarded";
+            }
+            branch.events.length = 0;
+        },
+    };
+}
 // Counter-based pause: `pauseRecording`/`resumeRecording` nest safely
 // (a nested `ctx.poll` inside another `ctx.poll`'s predicate stays
 // suppressed until its own resume balances out). Active record* sites
@@ -121,7 +169,7 @@ export function resumeRecording() {
     paused = Math.max(0, paused - 1);
 }
 function active() {
-    return current !== null && paused === 0 && scopeAllowsRecording();
+    return current !== null && paused === 0 && scopeAllowsRecording() && branchAllowsRecording(recordingBranches.getStore());
 }
 export function startRecording(startedAt = Date.now()) {
     current = new Recorder(startedAt);
@@ -131,6 +179,19 @@ export function stopRecording() {
     if (!current)
         return [];
     const evs = current.drain();
+    // A timeout can stop the test before a helper returns. Keep its available
+    // diagnostics, then fence detached work out of any subsequent recording.
+    for (const branch of current.pendingHelpers) {
+        if (branchAllowsRecording(branch)) {
+            for (const event of branch.events)
+                evs.push(event);
+        }
+    }
+    for (const branch of current.pendingHelpers) {
+        branch.events.length = 0;
+        branch.state = "discarded";
+    }
+    current.pendingHelpers.clear();
     current = null;
     paused = 0;
     return evs;
@@ -189,6 +250,9 @@ export function recordTerminalStep(ev, reservation) {
 export function recordFake(ev, reservation) {
     return active() ? current.push({ kind: "fake", ...ev }, reservation) : undefined;
 }
+export function recordServiceHelper(ev, reservation) {
+    return active() ? current.push({ kind: "service", ...ev }, reservation) : undefined;
+}
 export function recordEnv(ev, reservation) {
     return active() ? current.push({ kind: "env", ...ev }, reservation) : undefined;
 }
@@ -199,11 +263,7 @@ export function recordEmail(ev, reservation) {
     return active() ? current.push({ kind: "email", ...ev }, reservation) : undefined;
 }
 export function recordWait(ev, reservation) {
-    // Use `current` directly (not `active()`) so a `recordWait` at the
-    // end of a `ctx.poll` block lands even though the surrounding code
-    // just resumed from `paused`. Pushing this event is the whole point
-    // of the poll primitive.
-    return current?.push({ kind: "wait", ...ev }, reservation);
+    return active() ? current.push({ kind: "wait", ...ev }, reservation) : undefined;
 }
 /** Number of events the active recorder has accumulated. Returns 0
  *  when no recorder is active. */

package/package.json

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

package/src/annotate.ts

@@ -1,34 +1,10 @@
-// Render annotations — how a fake tells the dashboard to draw a helper's
-// return value as something richer than JSON.
-//
-// A fake helper call is recorded as a `fake` step and its return value is
-// rendered as pretty JSON, which is the right default for arbitrary data.
-// When the value *is* a domain object the timeline already draws well — an
-// email, today — the fake says so: `return annotate(msg, "email", {…})`.
-// The call is still recorded as the `fake` step it is; the annotation rides
-// *under* it as a child event (`parentSeq`, marked `annotation`) of the kind
-// that already knows how to draw this — for `"email"`, the very event the
-// built-in `email()` component's mailbox helpers record — so the dashboard
-// renders it mail-client style (header block + sandboxed HTML body) with no
-// new rendering code. It leads the step's detail panel; the raw JSON value
-// is a tab away.
-//
-// One function, keyed by kind: the kind is a key of `AnnotationOptions`, so
-// the options argument is typed against the kind that was named, and a new
-// kind is an entry in that interface (+ a case in `lower`, + an arm in
-// `daemon.ts::recordAnnotatedCall`) rather than a new export.
-//
-// The test is unaffected. `annotate` returns a box that the daemon opens at
-// the helper boundary (`daemon.ts::invokeFakeHelper`), so the caller gets
-// the raw value back, inspect-wrapped as always, and the *type* it sees is
-// still the raw value's (`WrappedHelpers` in index.ts unwraps `Annotated`).
-// Assertions keep linking to the fake step, exactly as for an unannotated
-// helper. The annotation is a rendering hint and nothing else.
-//
-// This is a fake-helper mechanism: those calls go through a tracking proxy
-// that can open the box. A *service* helper (`ctx.svc.<name>.…`) is the raw
-// record its factory returned, so an annotation there would reach the test
-// as an opaque value — don't.
+// A helper returns an annotation box to choose a richer view of its result.
+// Both fake and service helper boundaries open it, record one named helper
+// operation with an annotation child, and wrap the value for linked assertions.
+// annotate() itself does not record or attach anything to an existing operation.
+// Fake helpers always hide their implementation; service helpers opt into that
+// behavior by returning this box. Ordinary service returns keep their internal
+// recorded operations and their existing types.
 
 import { deepUnwrap } from "./inspect.js";
 import {
@@ -50,15 +26,14 @@ import {
 const ANNOTATION = Symbol.for("spectest.render-annotation");
 
 /** Phantom brand — `Annotated<T>` is nominally distinct from `T`, so the
- *  box can't be read as the value by accident inside the fake, and the
+ *  box can't be read as the value by accident inside the helper, and the
  *  helper types can recognise it and hand the *test* back a plain `T`. */
 declare const ANNOTATED: unique symbol;
 
 /**
  * A value plus a rendering hint, as returned by {@link annotate}. Return it
- * straight from a fake helper: the daemon unwraps it, so the test receives
- * the value itself and `ctx.fakes.<name>.<fn>()` is typed as if the
- * annotation weren't there.
+ * straight from a fake or service helper: the boundary opens it and the test
+ * receives the value wrapped for assertions. The box never reaches the test.
  */
 export interface Annotated<T> {
   readonly [ANNOTATED]: T;
@@ -71,7 +46,7 @@ export interface Annotated<T> {
  * another kind is a compile error at the call site.
  *
  * A new kind is an entry here, a case in `lower`, and an arm in
- * `daemon.ts::recordAnnotationChild`.
+ * `helper-tracking.ts::recordAnnotationChild`.
  */
 export interface AnnotationOptions {
   /** Draw the value as an email — one message, or a list of them for a
@@ -87,7 +62,7 @@ export type AnnotationKind = keyof AnnotationOptions;
 
 /**
  * What an annotation lowers to: the fields of the child event the daemon
- * records under the call's own `fake` one. Tagged by that event's `kind` —
+ * records under the helper call's own event. Tagged by that event's `kind` —
  * which needn't be the annotation kind's name, since an annotation names
  * what the value *is* and the event names how it's drawn.
  */
@@ -113,13 +88,13 @@ type ChatRenderAnnotation = {
 };
 
 /**
- * The email fields to render. Every one is optional — pass what the fake
- * has. Addresses take a single string or a list.
+ * The email fields to render. Every one is optional — pass what the helper
+ * observed. Addresses take a single string or a list.
  *
  * The event can also carry a date, per-row previews and attachment
- * metadata, which the built-in `email()` component fills from a really
- * captured message; a fake's mail was never sent, so those are deliberately
- * not offered here. A listing row's preview is derived from the body.
+ * metadata, which the built-in `email()` component fills from a captured
+ * message. Annotations currently cover the header/body fields below. A
+ * listing row's preview is derived from the body.
  */
 export interface EmailAnnotation {
   from?: string;
@@ -248,10 +223,12 @@ const NO_FIELDS =
   "html: value.body }).";
 
 /**
- * Say what a fake helper's return value *is*, so the timeline can draw it
+ * Say what a helper's return value *is*, so the timeline can draw it
  * as that on top of the JSON it always shows. The call stays an ordinary
- * fake step; the rendered view nests inside it. The value is returned to
- * the test unchanged (and unchanged in type).
+ * helper step; the rendered view nests inside it. Return this box from the
+ * helper: the caller receives the value wrapped for assertions. An annotated
+ * service return suppresses the helper's internal events; an ordinary service
+ * return keeps them. Calling annotate without returning the box has no effect.
  *
  * ```ts
  * helpers: ({ state }) => ({

package/src/daemon.ts

@@ -196,13 +196,11 @@ 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 { readAnnotation, type RenderAnnotation } from "./annotate.js";
+import { trackHelpers } from "./helper-tracking.js";
 import {
   isRecording,
-  recordEmail,
   recordEnv,
   recordExec,
-  recordFake,
   recordStep,
   recordTerminal,
   recordWait,
@@ -216,7 +214,7 @@ import {
   type StepBlock,
   type TestEvent,
 } from "./recorder.js";
-import { deepUnwrap, readRaw, wrap } from "./inspect.js";
+import { readRaw, wrap } from "./inspect.js";
 import type { Wrapped } from "./inspect.js";
 import { setRecordSecrets } from "./record-secrets.js";
 import { generateId } from "./ids.js";
@@ -3141,7 +3139,7 @@ const FAKE_CTX: FakeContext = {
 /** Build (or fetch from cache) the helpers record for a fake — the
  * value that ends up at `ctx.fakes.<name>`. Defaults to `{}` (a fake
  * with no `helpers` exposes nothing — tests never touch private state
- * directly). Returns a tracking proxy (see `trackFakeHelpers`) so helper
+ * directly). Returns a tracking proxy (see `trackHelpers`) so helper
  * calls land in the test timeline. */
 async function ensureFakeHelpers(name: string): Promise<Record<string, unknown>> {
   const fake = FAKES.get(name);
@@ -3154,168 +3152,10 @@ async function ensureFakeHelpers(name: string): Promise<Record<string, unknown>>
         ctx: FAKE_CTX,
       }))) as Record<string, unknown>)
     : {};
-  fake.trackedHelpers = trackFakeHelpers(name, fake.helpers);
+  fake.trackedHelpers = trackHelpers("fake", name, fake.helpers);
   return fake.trackedHelpers;
 }
 
-/** Wrap a fake's helpers so each call becomes a recorded `fake` event,
- * its arguments are `deepUnwrap`ped, and its return value is `wrap()`ped
- * for assertion provenance. Helpers
- * are functions that read/mutate the fake's private state via closure;
- * tests only ever see what those functions return. The proxy is built
- * once and shared across tests; it consults the recorder at call time,
- * so it's a transparent no-op when nothing is recording (eval / project
- * setup).
- *
- * Only own function properties are intercepted — inherited members
- * (`toString`, etc.), symbols, and any stray non-function property pass
- * straight through untouched. */
-function trackFakeHelpers(
-  fakeName: string,
-  helpers: Record<string, unknown>,
-): Record<string, unknown> {
-  return new Proxy(helpers, {
-    get(target, prop, receiver) {
-      if (typeof prop === "symbol") return Reflect.get(target, prop, receiver);
-      const desc = Object.getOwnPropertyDescriptor(target, prop);
-      if (!desc || typeof desc.value !== "function") {
-        return Reflect.get(target, prop, receiver);
-      }
-      const fn = desc.value as (...a: unknown[]) => unknown;
-      const member = String(prop);
-      return (...args: unknown[]) =>
-        invokeFakeHelper(fakeName, member, fn, target, args);
-    },
-  });
-}
-
-/** Invoke a fake helper function, recording a `fake` event and wrapping
- * the return value. Handles both sync and async helpers, and records an
- * error event (then rethrows) if the helper throws.
- *
- * Arguments are `deepUnwrap`ped on the way in, so a helper body is plain
- * user code operating on plain values: a test that feeds one helper's
- * return (or a `ctx.fetch` field) to another passes a provenance wrapper,
- * and `msg.html.matchAll(...)` inside the fake would otherwise throw a
- * `TypeError` from a stack the author can't see. Same treatment the k8s
- * client's arguments get (`components/k3s.ts::withTagging`). The types
- * still say the value is a handle — passing a wrapped value where the
- * parameter type is known is a compile error asking for `.unwrap()`; this
- * catches the case where it isn't known (an `any` off `req.json()`). */
-function invokeFakeHelper(
-  fakeName: string,
-  member: string,
-  fn: (...a: unknown[]) => unknown,
-  thisArg: unknown,
-  callArgs: unknown[],
-): unknown {
-  const t = Date.now();
-  const resv = reserveEvent();
-  const args = callArgs.map((a) => deepUnwrap(a));
-  const safeArgs = args.map((a) => safeSerialize(a));
-  const recordResult = (value: unknown): unknown => {
-    // A helper may box its return in a render annotation
-    // (`annotate(v, "email", …)`). The box never reaches the test, and it
-    // never replaces the step either: the call is recorded as the ordinary
-    // `fake` event it is, and the annotation rides *under* it as a child
-    // event (`parentSeq`), which the dashboard folds into the fake step's
-    // detail panel. So the timeline reads the same as any other helper
-    // call, with the richer view one click in.
-    const annotated = readAnnotation(value);
-    const raw = annotated ? annotated.value : value;
-    const durationMs = Date.now() - t;
-    const seq = recordFake({
-      fake: fakeName,
-      member,
-      args: safeArgs,
-      result: safeSerialize(raw),
-      durationMs,
-    }, resv);
-    if (annotated && seq !== undefined) {
-      recordAnnotationChild(fakeName, member, annotated.annotation, durationMs, seq);
-    }
-    return wrap(raw, seq);
-  };
-  const recordError = (err: unknown): void => {
-    recordFake({
-      fake: fakeName,
-      member,
-      args: safeArgs,
-      durationMs: Date.now() - t,
-      error: errMessage(err),
-    }, resv);
-  };
-
-  // 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 = runUninstrumented(() => fn.apply(thisArg, args));
-  } catch (err) {
-    recordError(err);
-    throw err;
-  }
-  if (result instanceof Promise) {
-    return result.then(
-      recordResult,
-      (err) => {
-        recordError(err);
-        throw err;
-      },
-    );
-  }
-  return recordResult(result);
-}
-
-/** Record a fake-helper call's render annotation as a child of the call's
- * own `fake` event — the same `parentSeq` grouping `ctx.poll` uses for the
- * iteration it kept, so the annotated view folds into the fake step's
- * detail panel instead of taking a timeline row of its own.
- *
- * The child is the event kind that already knows how to draw this: an
- * `email` annotation records the very event the built-in `email()`
- * component's mailbox helpers record, so it renders with no new code. It
- * carries the fake's name and member as its service/op, and the parent's
- * duration, since it describes that same call.
- *
- * Only the success path is annotated: a helper that threw returned no value
- * to annotate, so it's a plain `fake` error event. */
-function recordAnnotationChild(
-  fakeName: string,
-  member: string,
-  annotation: RenderAnnotation,
-  durationMs: number,
-  parentSeq: number,
-): void {
-  switch (annotation.kind) {
-    case "email":
-      recordEmail({
-        parentSeq,
-        annotation: true,
-        service: fakeName,
-        op: member,
-        message: annotation.message,
-        messages: annotation.messages,
-        count: annotation.count,
-        durationMs,
-      });
-      break;
-    case "chat":
-      // A chat has no event kind of its own: it describes itself in
-      // presentation terms (title + blocks), which is the seam a new step
-      // type is supposed to use. `kind` stays an opaque grouping label.
-      recordStep({
-        kind: "chat",
-        parentSeq,
-        annotation: true,
-        title: annotation.title ?? `${fakeName}.${member}`,
-        blocks: annotation.blocks,
-        durationMs,
-      });
-      break;
-  }
-}
-
 function errMessage(err: unknown): string {
   return (err as Error)?.message ?? String(err);
 }
@@ -4805,10 +4645,10 @@ async function ensureHelpers(
     try {
       HELPERS_CACHE.set(
         name,
-        await def.helpers({
+        trackHelpers("service", name, await def.helpers({
           name,
           ...(await spectestContext({ service: name, includeSelf: false })),
-        }),
+        })),
       );
     } finally {
       HELPERS_BUILDING.delete(name);
@@ -4822,8 +4662,8 @@ const HELPERS_BUILDING = new Set<string>();
 
 /**
  * Build the `svc` map for one test/eval. The value at `svc[name]` is
- * exactly the record the service's `helpers` factory returned (e.g.
- * `{ client: SqlClient }` for `postgres(...)`). Services without a
+ * a shallow helper proxy: annotated returns become named service steps;
+ * ordinary returns and live client handles pass through. Services without a
  * `helpers` factory don't appear in the map at all.
  */
 async function buildServiceHandles(cfg: EnvironmentConfig): Promise<ServiceHandles> {