@specific.dev/spectest 0.107.2 → 0.109.0

package/src/helper-tracking.ts

@@ -0,0 +1,162 @@
+import { readAnnotation } from "./annotate.js";
+import type { RenderAnnotation } from "./annotate.js";
+import { deepUnwrap, wrap } from "./inspect.js";
+import { runUninstrumented } from "./harness/instrumentation-scope.js";
+import {
+  captureRecording, recordEmail, recordFake, recordServiceHelper, recordStep, reserveEvent, safeSerialize,
+  type EventReservation,
+} from "./recorder.js";
+
+type HelperKind = "fake" | "service";
+
+/** Both helper namespaces consume the same annotation box. Only direct own
+ * function properties are intercepted: live clients, getters and inherited
+ * methods pass through; callable clients retain their properties. Service functions without annotations
+ * retain their original results, types and underlying recorded operations. */
+export function trackHelpers<H extends Record<string, unknown>>(kind: HelperKind, name: string, helpers: H): H {
+  const methods = new Map<string, { original: Function; tracked: Function }>();
+  // A separate, extensible target also supports frozen helper records: a proxy
+  // over the original cannot substitute a non-writable function property.
+  const proxy: H = new Proxy(Object.create(Object.getPrototypeOf(helpers)), {
+    get(_target, prop) {
+      if (typeof prop !== "string") return Reflect.get(helpers, prop, helpers);
+      const descriptor = Object.getOwnPropertyDescriptor(helpers, prop);
+      if (!descriptor || typeof descriptor.value !== "function") return Reflect.get(helpers, prop, helpers);
+      const fn = descriptor.value as (...args: unknown[]) => unknown;
+      const cached = methods.get(prop);
+      if (cached?.original === fn) return cached.tracked;
+      // A callable handle (e.g. tagged-template SQL) can also have methods.
+      // Proxy its call rather than replacing it with a bare arrow function.
+      const tracked = new Proxy(fn, {
+        apply(original, thisArg, args) {
+          return invokeHelper(kind, name, prop, original,
+            kind === "fake" || thisArg === proxy ? helpers : thisArg, args);
+        },
+      });
+      methods.set(prop, { original: fn, tracked });
+      return tracked;
+    },
+    has: (_target, prop) => Reflect.has(helpers, prop),
+    ownKeys: () => Reflect.ownKeys(helpers),
+    getOwnPropertyDescriptor(_target, prop) {
+      const descriptor = Object.getOwnPropertyDescriptor(helpers, prop);
+      return descriptor && { ...descriptor, configurable: true };
+    },
+    set: (_target, prop, value) => Reflect.set(helpers, prop, value, helpers),
+    deleteProperty: (_target, prop) => Reflect.deleteProperty(helpers, prop),
+    // Virtual properties must remain configurable on this view.
+    defineProperty: (_target, prop, descriptor) => descriptor.configurable === true &&
+      Reflect.defineProperty(helpers, prop, descriptor),
+    preventExtensions: () => false,
+  });
+  return proxy;
+}
+
+function invokeHelper(
+  kind: HelperKind, name: string, member: string,
+  fn: (...args: unknown[]) => unknown, receiver: unknown, callArgs: unknown[],
+): unknown {
+  const start = Date.now();
+  const reservation = reserveEvent();
+  const recording = captureRecording();
+  // Fake bodies have always received raw args. Services keep their existing
+  // input contract: they may intentionally accept wrapped values or clients.
+  const args = kind === "fake" ? callArgs.map((arg) => deepUnwrap(arg)) : callArgs;
+  const safeArgs = kind === "fake" ? args.map((arg) => safeSerialize(arg)) : undefined;
+  const finish = (value: unknown): unknown => {
+    const annotated = readAnnotation(value);
+    if (kind === "service" && !annotated) {
+      recording.finish(true);
+      return value;
+    }
+    recording.finish(false);
+    const raw = deepUnwrap(annotated ? annotated.value : value);
+    const durationMs = Date.now() - start;
+    const seq = recording.isCurrent()
+      ? recordHelper(kind, name, member,
+        safeArgs ?? args.map((arg) => safeSerialize(deepUnwrap(arg))), raw, durationMs, reservation)
+      : undefined;
+    if (annotated && seq !== undefined) {
+      recordAnnotationChild(name, member, annotated.annotation, durationMs, seq);
+    }
+    return wrap(raw, seq);
+  };
+  const fail = (error: unknown): never => {
+    // There was no annotated return to replace the implementation. Preserve
+    // service failures' underlying diagnostics; fake internals stay hidden.
+    recording.finish(kind === "service");
+    if (kind === "fake" && recording.isCurrent()) {
+      recordFake({ fake: name, member, args: safeArgs!, durationMs: Date.now() - start,
+        error: error instanceof Error ? error.message : String(error) }, reservation);
+    }
+    throw error;
+  };
+  let result: unknown;
+  try {
+    result = recording.run(() => kind === "fake"
+      ? runUninstrumented(() => fn.apply(receiver, args))
+      : fn.apply(receiver, args));
+  } catch (error) {
+    return fail(error);
+  }
+  return result instanceof Promise ? result.then(finish, fail) : finish(result);
+}
+
+function recordHelper(
+  kind: HelperKind, name: string, member: string, args: unknown[], result: unknown,
+  durationMs: number, reservation: EventReservation | undefined,
+): number | undefined {
+  if (kind === "fake") {
+    return recordFake({ fake: name, member, args, result: safeSerialize(result), durationMs }, reservation);
+  }
+  return recordServiceHelper({ service: name, member, args, result: safeSerialize(result), durationMs }, reservation);
+}
+
+/** Record a helper call's render annotation as a child of the call's
+ * own event — the same `parentSeq` grouping `ctx.poll` uses for the
+ * iteration it kept, so the annotated view folds into the helper 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 helper'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. */
+function recordAnnotationChild(
+  name: string,
+  member: string,
+  annotation: RenderAnnotation,
+  durationMs: number,
+  parentSeq: number,
+): void {
+  switch (annotation.kind) {
+    case "email":
+      recordEmail({
+        parentSeq,
+        annotation: true,
+        service: name,
+        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 ?? `${name}.${member}`,
+        blocks: annotation.blocks,
+        durationMs,
+      });
+      break;
+  }
+}

package/src/index.ts

@@ -36,7 +36,7 @@ export type {
   SpectestRequestInit,
   Unwrap,
 } from "./inspect.js";
-import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
+import type { OpTag, Provenanced, SpectestFetch, Wrapped, Unwrap } from "./inspect.js";
 
 // `field` — a provenance-preserving, null-safe selector: a `null`/`undefined`
 // leaf read off a wrapped op result is raw and untagged, so an `expect(...)` on
@@ -49,13 +49,9 @@ import type { OpTag, Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
 // `unwrap(x)` free function. See the `.unwrap()` discipline section of `spectest docs`.
 export { field } from "./inspect.js";
 
-// Render annotations for fake helpers: a helper returns
-// `annotate(value, "email", { … })` or `annotate(value, "chat", { … })`
-// when its value is one of those, and the fake step it records gains a
-// nested event drawing it — an email mail-client style, a conversation as
-// bubbles — which the step's panel leads with, tabbing to the raw JSON
-// value. The kind picks the options' type, and the test still gets the raw
-// value, with the raw value's type — see `annotate.ts`.
+// Fake and service helpers return annotate(value, kind) to render their own
+// result as email/chat. Their boundary opens the box and links assertions to
+// the helper step. Annotated service returns suppress internal operation events.
 export { annotate } from "./annotate.js";
 export type {
   Annotated,
@@ -768,6 +764,11 @@ export interface ServiceDefinition<
    * user chose in the services map and matches the in-VM DNS name; the
    * rest of the {@link ServiceHelpersContext} (exec, projectRoot) lets a
    * component reach into its containers without daemon internals.
+   *
+   * Direct helper functions may return `annotate(value, "email" | "chat")`.
+   * That call becomes one named service step, its internal events are hidden,
+   * and the caller receives `Wrapped<T>` linked to the helper. Ordinary returns
+   * retain their existing value/type and underlying operation events.
    */
   helpers?: (args: ServiceHelpersContext) => H | Promise<H>;
   /**
@@ -816,13 +817,26 @@ type HelpersOf<D> = "helpers" extends keyof D
 /**
  * Per-service handles derived from a concrete services map. Only
  * services that ship a `helpers` factory appear here; `ctx.svc.<name>`
- * is exactly the record the factory returned (e.g. `{ client: SqlClient }`
- * for `postgres(...)`). Services without helpers don't show up at all,
+ * preserves the factory's live handles and ordinary function results. A
+ * function returning `annotate(value, kind)` instead returns a wrapped value
+ * linked to one named service-helper step. Services without helpers don't show up,
  * so plain `services: { api: { image: ... } }` adds no noise.
  */
 export type ServiceHandlesFor<S extends ServicesMap> = {
-  [K in keyof S as HelpersOf<S[K]> extends never ? never : K]: HelpersOf<S[K]>;
+  [K in keyof S as HelpersOf<S[K]> extends never ? never : K]: ServiceHelpers<HelpersOf<S[K]>>;
+};
+
+/** Only annotated returns change type. Keeping other function types verbatim
+ * preserves generics, overloads, and callable clients with attached methods. */
+type ServiceHelpers<H> = {
+  [K in keyof H]: H[K] extends (...args: infer A) => infer R
+    ? Extract<Awaited<R>, Annotated<unknown>> extends never
+      ? H[K]
+      : (...args: A) => R extends Promise<infer V>
+        ? Promise<ServiceHelperResult<V>> : ServiceHelperResult<R>
+    : H[K];
 };
+type ServiceHelperResult<R> = R extends Annotated<infer V> ? Wrapped<Unwrap<V>> : R;
 
 /** Loose, runtime-friendly shape of `ctx.svc` for code that doesn't
  * know the concrete services map (the daemon, generic helpers). The
@@ -2265,7 +2279,7 @@ export function defineFake<
 export type FakesMap = Record<string, FakeDefinition<any, any>>;
 
 /** Rewrite a helpers record so each function's result is inspect-wrapped
- * ({@link Wrapped}) — mirroring the runtime, where `trackFakeHelpers` wraps
+ * ({@link Wrapped}) — mirroring the runtime, where `trackHelpers` wraps
  * every helper return value for assertion provenance. Without this the raw
  * return type (e.g. `Charge[]`) reaches `expect`, which the `Provenanced`
  * gate rejects. Handles sync and async helpers; non-function members (and
@@ -2273,9 +2287,9 @@ export type FakesMap = Record<string, FakeDefinition<any, any>>;
  * `components/k3s.ts`, extended to cover synchronous returns. */
 type WrappedHelpers<H> = {
   [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R>
-    ? (...args: A) => Promise<Wrapped<Unannotated<R>>>
+    ? (...args: A) => Promise<Wrapped<Unwrap<Unannotated<R>>>>
     : H[K] extends (...args: infer A) => infer R
-      ? (...args: A) => [R] extends [void] ? void : Wrapped<Unannotated<R>>
+      ? (...args: A) => [R] extends [void] ? void : Wrapped<Unwrap<Unannotated<R>>>
       : H[K];
 };
 
@@ -2363,18 +2377,26 @@ export interface Project<
    * appear in the timeline.
    */
   setup?: ProjectSetupFn<S, F>;
+  /**
+   * Prepare a new interactive environment, after normal setup and the shared
+   * warm-template snapshot. Runs on both cold starts and warm restores from
+   * the dashboard or `spectest env start`, before the environment is ready.
+   * Never runs for tests, snapshot forks, or resuming a stopped environment.
+   * Uses the same context as `setup`; throw to fail the start.
+   */
+  setupInteractive?: ProjectSetupFn<S, F>;
   tests?: TestSuite<S, F>;
 }
 
 /**
- * Context handed to the project-level `setup` hook: the full
+ * Context handed to the project-level `setup` and `setupInteractive` hooks: the full
  * {@link SpectestContext}, minus only what a timeline gives a test
  * (testName, parent, browser/mobile/terminal). Everything a test can do
  * to the environment — exec, fetch, `svc`/`fakes` helpers, `poll`,
  * `dnsName`, `certificate`, `startService`, and project-file access via
- * `projectRoot`/`readProjectFile` — is available here too, and whatever it
- * produces is captured into the warm-template snapshot, so every test
- * inherits it without re-running.
+ * `projectRoot`/`readProjectFile` — is available here too. Normal `setup`
+ * state is captured into the shared warm template; `setupInteractive`
+ * state belongs only to the new interactive environment.
  */
 export interface ProjectSetupContext<
   S extends ServicesMap = ServicesMap,
@@ -2423,6 +2445,8 @@ export interface ProjectOpts<
 > {
   /** Optional project-level setup. See `Project.setup`. */
   setup?: ProjectSetupFn<S, F>;
+  /** Optional interactive-only setup. See `Project.setupInteractive`. */
+  setupInteractive?: ProjectSetupFn<S, F>;
   /** Test cases for this project's suite. */
   tests?: TestCase<unknown, S, F>[];
 }
@@ -2487,7 +2511,7 @@ export interface DefinedEnvironment<
   ): TestGroup<P, S, F>;
   /** Bundle this environment with a test suite into the project default
    * export. Pass tests as a plain array for the common case, or an
-   * options bag to attach project-level `setup`. (Fakes are declared on
+   * options bag to attach `setup` or `setupInteractive`. (Fakes are declared on
    * `defineEnvironment`, not here.) */
   project(tests?: TestCase<unknown, S, F>[]): Project<S, F>;
   project(opts: ProjectOpts<S, F>): Project<S, F>;
@@ -2639,6 +2663,7 @@ export function defineEnvironment<
       : (arg ?? {});
     const proj: Project<S, F> = { environment: config };
     if (opts.setup) proj.setup = opts.setup;
+    if (opts.setupInteractive) proj.setupInteractive = opts.setupInteractive;
     if (fakes) proj.fakes = fakes;
     if (opts.tests && opts.tests.length > 0) {
       // Explicit suite (single-file / legacy layout): the tests are listed

package/src/interactive-setup.test.ts

@@ -0,0 +1,89 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// The daemon owns globals and snapshot-resident state. Use a fresh process,
+// just as each freshly built environment has its own harness.
+for (const withHook of [false, true]) {
+  test(`interactive setup: ${withHook ? "context, failure, exclusion and one-shot state" : "optional hook"}`, async () => {
+    const root = await mkdtemp(join(tmpdir(), "spectest-interactive-setup-"));
+    try {
+      await mkdir(join(root, "spectest"));
+      await mkdir(join(root, "bin"));
+      await writeFile(join(root, "bin/docker"), '#!/bin/sh\nprintf "%s\\n" "$*"\n', { mode: 0o755 });
+      const entry = join(root, "spectest/index.ts");
+      await writeFile(entry, `
+        import { defineEnvironment } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
+        export const calls = [];
+        const env = defineEnvironment({ name: "seed", services: {
+          app: { image: { type: "registry", reference: "busybox" },
+            helpers: () => ({ label: "typed helper" }) },
+        }});
+        export default env.project({
+          setup: () => { calls.push("baseline"); },
+          ${withHook ? `setupInteractive: async (ctx) => {
+            calls.push("interactive");
+            console.log("seeding demo data");
+            await globalThis.seedGate;
+            if (globalThis.failSeed) throw new Error("seed rejected");
+            const response = await ctx.fetch("data:application/json,%7B%22ok%22%3Atrue%7D");
+            if (response.status.unwrap() !== 200) throw new Error("fetch not wrapped");
+            if (ctx.svc.app.label !== "typed helper") throw new Error("missing helpers");
+            if ("browser" in ctx || "testName" in ctx) throw new Error("test context leaked");
+            const result = await ctx.exec("app", ["seed", "demo"]);
+            if (typeof result.exitCode !== "number" || !result.stdout.includes("seed demo")) {
+              throw new Error("exec result not plain: " + JSON.stringify(result));
+            }
+          },` : ""}
+        });
+      `);
+      const script = `
+        import { strict as assert } from "node:assert";
+        import { METHODS } from ${JSON.stringify(new URL("./daemon.ts", import.meta.url).href)};
+        import { calls } from ${JSON.stringify(entry)};
+        const nativeFetch = globalThis.fetch;
+        await METHODS.load({});
+        assert.equal((await METHODS.health({})).setupInteractive, ${withHook});
+        await METHODS.projectSetup({});
+        assert.deepEqual(calls, ["baseline"]);
+        ${withHook ? `
+          let release;
+          globalThis.seedGate = new Promise(r => { release = r; });
+          globalThis.failSeed = true;
+          const failed = METHODS.interactiveSetup({});
+          await assert.rejects(METHODS.interactiveSetup({}), /already in progress/);
+          await assert.rejects(METHODS.projectSetup({}), /already in progress/);
+          release();
+          await assert.rejects(failed, /seed rejected/);
+          assert.equal(globalThis.fetch, nativeFetch);
+          globalThis.failSeed = false;
+          assert.equal((await METHODS.interactiveSetup({})).ran, true);
+          assert.deepEqual(calls, ["baseline", "interactive", "interactive"]);
+          // A repeated request (or a resumed seeded snapshot) cannot reseed.
+          assert.equal((await METHODS.interactiveSetup({})).ran, false);
+          assert.deepEqual(calls, ["baseline", "interactive", "interactive"]);
+          const logs = await METHODS.envLogs({});
+          assert.ok(logs.bootLog.includes("seeding demo data"));
+        ` : `
+          assert.equal((await METHODS.interactiveSetup({})).ran, false);
+          assert.deepEqual(calls, ["baseline"]);
+        `}
+        assert.equal(globalThis.fetch, nativeFetch);
+        // envLogs' subprocess timeout keeps a timer alive after it returns;
+        // this fixture tests hook behavior, not daemon process lifetime.
+        process.exit(0);
+      `;
+      const child = Bun.spawn([process.execPath, "--eval", script], {
+        env: { ...process.env, SPECTEST_APP_DIR: root, PATH: `${root}/bin:${process.env.PATH}` },
+        stdout: "pipe", stderr: "pipe",
+      });
+      const [code, stdout, stderr] = await Promise.all([
+        child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+      ]);
+      expect(code, stdout + stderr).toBe(0);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }, 20_000);
+}

package/src/recorder.ts

@@ -8,6 +8,7 @@
 // current recorder is `null` and the `record*` helpers are no-ops, so
 // callers can invoke them unconditionally.
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { AndroidStepDetails } from "./android-step.js";
 import { clearPendingNullish } from "./inspect.js";
 import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
@@ -27,6 +28,7 @@ export type TestEvent =
   | TerminalStepEvent
   | WaitEvent
   | FakeEvent
+  | ServiceHelperEvent
   | EnvEvent
   | EmailEvent
   // Open `kind`, so it goes last: narrowing the union by a literal kind
@@ -339,6 +341,14 @@ export interface FakeEvent extends BaseEvent {
   error?: string;
 }
 
+/** An annotated service helper has the same call/return shape as a fake.
+ * Only helpers returning an annotation emit this event. */
+export interface ServiceHelperEvent extends Omit<FakeEvent, "kind" | "fake"> {
+  kind: "service";
+  /** Service name — the key in `ctx.svc`. */
+  service: string;
+}
+
 /**
  * One captured email, as embedded on an {@link EmailEvent}. The HTML and
  * text bodies ride along (truncated to the output cap) so the dashboard
@@ -631,7 +641,12 @@ export interface EventReservation {
 }
 
 class Recorder {
-  private events: TestEvent[] = [];
+  private rootEvents: TestEvent[] = [];
+  readonly pendingHelpers = new Set<RecordingBranch>();
+  private get events(): TestEvent[] {
+    const branch = recordingBranches.getStore();
+    return branch?.owner === this ? branchEvents(branch) : this.rootEvents;
+  }
   private seq = 0;
   constructor(private readonly start = Date.now()) {}
 
@@ -733,6 +748,60 @@ class Recorder {
 
 let current: Recorder | null = null;
 
+interface RecordingBranch {
+  owner: Recorder;
+  events: TestEvent[];
+  parent: RecordingBranch | undefined;
+  destination: TestEvent[];
+  state: "open" | "kept" | "discarded";
+}
+
+const recordingBranches = new AsyncLocalStorage<RecordingBranch>();
+
+function branchEvents(branch: RecordingBranch): TestEvent[] {
+  return branch.state === "kept"
+    ? branch.parent ? branchEvents(branch.parent) : branch.destination
+    : branch.events;
+}
+
+function branchAllowsRecording(branch: RecordingBranch | undefined): boolean {
+  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(): {
+  run<T>(fn: () => T): T;
+  finish(keep: boolean): void;
+  isCurrent(): boolean;
+} {
+  if (!active()) return { run: (fn) => fn(), finish: () => {}, isCurrent: () => false };
+  const branch: RecordingBranch = {
+    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
@@ -751,7 +820,7 @@ export function resumeRecording(): void {
 }
 
 function active(): boolean {
-  return current !== null && paused === 0 && scopeAllowsRecording();
+  return current !== null && paused === 0 && scopeAllowsRecording() && branchAllowsRecording(recordingBranches.getStore());
 }
 
 export function startRecording(startedAt = Date.now()): void {
@@ -762,6 +831,18 @@ export function startRecording(startedAt = Date.now()): void {
 export function stopRecording(): TestEvent[] {
   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;
@@ -862,6 +943,13 @@ export function recordFake(
   return active() ? current!.push({ kind: "fake", ...ev }, reservation) : undefined;
 }
 
+export function recordServiceHelper(
+  ev: Omit<ServiceHelperEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "service", ...ev }, reservation) : undefined;
+}
+
 export function recordEnv(
   ev: Omit<EnvEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,
@@ -992,11 +1080,7 @@ export function recordWait(
   ev: Omit<WaitEvent, "seq" | "tOffsetMs" | "kind">,
   reservation?: EventReservation,
 ): number | undefined {
-  // 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