@specific.dev/spectest 0.107.2 → 0.109.0

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);
 }
@@ -3633,30 +3473,35 @@ interface ProjectSetupResult {
   durationMs: number;
 }
 
+// Captured as false in the shared template, true in a seeded interactive
+// snapshot. Repeated requests must not apply a successful seed twice.
+let interactiveSetupCompleted = false;
+
 /**
- * Run the loaded project's `setup` hook, if any. Called by the control
- * plane once between /bootstrap and the warm-template snapshot, so the
- * effects (seeded DB rows, initial pods, fixture files) are captured
- * exactly once and inherited by every later snapshot/fork.
+ * Run a project setup hook. Normal `setup` runs before the shared warm
+ * snapshot; `setupInteractive` runs only after it, in a fresh user start.
+ * Both use the same context and boot-log capture.
  *
  * Unlike test runs, this is NOT instrumented — no recorder, no event
  * timeline, no timeout from the test runner. Setup failures abort the
  * env bring-up; the control plane surfaces them as a start failure.
  */
-async function runProjectSetup(): Promise<ProjectSetupResult> {
+async function runProjectSetup(hook: "setup" | "setupInteractive" = "setup"): Promise<ProjectSetupResult> {
   // Same tee as bootstrap: a project `setup` hook's console output is
   // part of explaining the boot, not something to lose on success.
   const restoreBootLog = captureConsole(BOOT_LOG_SINK);
   try {
-    return await runProjectSetupInner();
+    return await runProjectSetupInner(hook);
   } finally {
     restoreBootLog();
   }
 }
 
-async function runProjectSetupInner(): Promise<ProjectSetupResult> {
-  const proj = requireLoaded().project;
-  if (!proj.setup) return { ran: false, durationMs: 0 };
+async function runProjectSetupInner(hook: "setup" | "setupInteractive"): Promise<ProjectSetupResult> {
+  const setup = requireLoaded().project[hook];
+  if (!setup || (hook === "setupInteractive" && interactiveSetupCompleted)) {
+    return { ran: false, durationMs: 0 };
+  }
   const start = Date.now();
   // Install the fetch wrapper for the duration of setup so `ctx.fetch` (and any
   // client routed through `globalThis.fetch`) returns a wrapped Response, same
@@ -3667,9 +3512,10 @@ async function runProjectSetupInner(): Promise<ProjectSetupResult> {
   // 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 runInstrumented(fetchScope, () => proj.setup!(ctx));
+    const ctx: ProjectSetupContext = await spectestContext();
+    await runInstrumented(fetchScope, () => setup(ctx));
+    if (hook === "setupInteractive") interactiveSetupCompleted = true;
   } finally {
     fetchScope.active = false;
     restoreFetch();
@@ -4805,10 +4651,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 +4668,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> {
@@ -6308,7 +6154,13 @@ export function harnessMethods(state: RouteState): MethodTable {
     setRecordSecrets(secrets as Record<string, string>);
   };
   return {
-    health: async () => ({ ok: true, capabilities: ["prepared-images-v1"] }),
+    health: async () => ({
+      ok: true,
+      capabilities: ["prepared-images-v1"],
+      // Optional discovery: old SDKs omit this field and are never sent the
+      // new method. Check the loaded project, including after warm restore.
+      setupInteractive: typeof loaded?.project.setupInteractive === "function",
+    }),
 
     // Live bootstrap progress, polled by the control plane during
     // `bootstrap` and streamed into the test-run row. `{}` before the
@@ -6445,6 +6297,14 @@ export function harnessMethods(state: RouteState): MethodTable {
         () => runProjectSetup(),
       ),
 
+    interactiveSetup: async () =>
+      exclusive(
+        state,
+        "inFlightProjectSetup",
+        "project-setup already in progress",
+        () => runProjectSetup("setupInteractive"),
+      ),
+
     eval: async (params) => {
       const code = requireString(params, "code");
       return exclusive(state, "inFlightTest", "a test or eval is already running", () => {

package/src/harness/protocol.ts

@@ -32,6 +32,7 @@ export type Method =
   | "loadTests"
   | "fingerprint"
   | "bootstrap"
+  | "interactiveSetup"
   | "run"
   | "eval"
   | "setRecordSecrets"
@@ -51,6 +52,7 @@ export const KNOWN_METHODS: ReadonlySet<string> = new Set<Method>([
   "loadTests",
   "fingerprint",
   "bootstrap",
+  "interactiveSetup",
   "run",
   "eval",
   "setRecordSecrets",

package/src/helper-tracking.test.ts

@@ -0,0 +1,289 @@
+import { afterEach, expect, test } from "bun:test";
+import { annotate } from "./annotate.js";
+import { expect as assertValue, type ServiceHandlesFor, type Wrapped } from "./index.js";
+import { readRaw, readTag, wrap } from "./inspect.js";
+import { trackHelpers } from "./helper-tracking.js";
+import {
+  recordHttp, recordWait, recorderEventCount, recorderMarkChildren, recorderTruncate,
+  startRecording, stopRecording,
+} from "./recorder.js";
+import { createInstrumentationScope, runInstrumented } from "./harness/instrumentation-scope.js";
+import { installFetchWrapper } from "./harness/fetch.js";
+
+function observe(subject = "Invoice") {
+  const raw = { subject, to: "owner@test", text: "Please pay" };
+  const seq = recordHttp({ method: "GET", url: "https://mail.test/latest", status: 200,
+    responseBody: JSON.stringify(raw), durationMs: 2 });
+  return wrap(raw, seq) as unknown as Wrapped<typeof raw>;
+}
+function deferred() {
+  let resolve!: () => void;
+  const promise = new Promise<void>((r) => { resolve = r; });
+  return { promise, resolve };
+}
+afterEach(() => stopRecording());
+
+for (const kind of ["fake", "service"] as const) {
+  test(`${kind} consumes the same annotation box and links assertions to one helper step`, async () => {
+    startRecording();
+    const helper = trackHelpers(kind, "mail", {
+      async latest() {
+        const value = observe();
+        await Promise.resolve();
+        recordWait({ description: "internal", attempts: 1, durationMs: 2, passed: true });
+        return annotate(value, "email");
+      },
+    });
+    const mail = await helper.latest() as unknown as Wrapped<{ subject: string }>;
+    assertValue(mail.subject).toBe("Invoice");
+    const events = stopRecording();
+    expect(events.map((e) => e.kind)).toEqual([kind, "email", "assertion"]);
+    expect(events[1]).toMatchObject({ parentSeq: events[0]!.seq, annotation: true,
+      message: { subject: "Invoice", to: ["owner@test"], text: "Please pay" } });
+    expect(events[2]).toMatchObject({ sourceSeq: events[0]!.seq, path: ["subject"] });
+    expect<unknown>(readRaw(mail)).toEqual({ subject: "Invoice", to: "owner@test", text: "Please pay" });
+    expect(events[0]).toMatchObject({ [kind === "fake" ? "fake" : "service"]: "mail",
+      member: "latest", args: [], result: readRaw(mail) });
+  });
+}
+
+test("ordinary service returns preserve value identity and operation provenance", async () => {
+  startRecording();
+  let observed: unknown;
+  const helper = trackHelpers("service", "mail", {
+    async latest() { return observed = observe(); },
+    count: () => 42,
+  });
+  const mail = await helper.latest() as Wrapped<{subject: string}>;
+  expect<unknown>(mail).toBe(observed);
+  expect(helper.count()).toBe(42);
+  assertValue(mail.subject).toBe("Invoice");
+  const events = stopRecording();
+  expect(events.map((e) => e.kind)).toEqual(["http", "assertion"]);
+  expect(events[1]).toMatchObject({ sourceSeq: events[0]!.seq, path: ["subject"] });
+});
+
+test("a helper can choose an annotated or ordinary return per call", () => {
+  startRecording();
+  const helper = trackHelpers("service", "mail", {
+    latest(render: boolean) { const value = observe(); return render ? annotate(value, "email") : value; },
+  });
+  helper.latest(false);
+  helper.latest(true);
+  expect(stopRecording().map((e) => e.kind)).toEqual(["http", "service", "email"]);
+});
+
+test("concurrent test work and sibling helpers survive an annotated return", async () => {
+  startRecording();
+  const gate = deferred();
+  const helper = trackHelpers("service", "mail", {
+    async annotated() { observe("hidden"); await gate.promise; observe("also hidden"); return annotate({subject: "shown"}, "email"); },
+    async plain() { await Promise.resolve(); return observe("sibling"); },
+  });
+  const pending = helper.annotated();
+  const outside = observe("outside");
+  const sibling = await helper.plain();
+  gate.resolve();
+  await pending;
+  assertValue(outside.subject).toBe("outside");
+  assertValue(sibling.subject).toBe("sibling");
+  const events = stopRecording();
+  expect(events.filter((e) => e.kind === "http").map((e: any) => JSON.parse(e.responseBody).subject)).toEqual(["outside", "sibling"]);
+  expect(events.filter((e) => e.kind === "service")).toHaveLength(1);
+  expect(new Set(events.map((e) => e.seq)).size).toBe(events.length);
+  const seqs = new Set(events.map((e) => e.seq));
+  for (const e of events.filter((e) => e.kind === "assertion") as any[]) expect(seqs.has(e.sourceSeq)).toBe(true);
+});
+
+test("nested annotated helpers collapse only when the outer helper annotates", async () => {
+  startRecording();
+  const inner = trackHelpers("service", "inner", { latest: () => annotate(observe(), "email") });
+  const outer = trackHelpers("service", "outer", {
+    async latest(render: boolean) { const value = await inner.latest(); return render ? annotate(value, "email") : value; },
+  });
+  await outer.latest(false);
+  await outer.latest(true);
+  const events = stopRecording();
+  expect(events.map((e) => e.kind)).toEqual(["service", "email", "service", "email"]);
+  expect(events[0]).toMatchObject({ service: "inner", member: "latest", args: [] });
+  expect(events[2]).toMatchObject({ service: "outer", member: "latest", args: [true] });
+});
+
+test("polling inside a helper cannot truncate unrelated concurrent events", async () => {
+  startRecording();
+  const gate = deferred();
+  const helper = trackHelpers("service", "mail", {
+    async latest() {
+      const start = recorderEventCount();
+      observe("discarded attempt");
+      await gate.promise;
+      recorderTruncate(start);
+      const result = observe("kept attempt");
+      const wait = recordWait({ description: "ready", attempts: 2, passed: true, durationMs: 3 })!;
+      recorderMarkChildren(start, wait);
+      return result;
+    },
+  });
+  const pending = helper.latest();
+  observe("outside");
+  gate.resolve();
+  await pending;
+  const events = stopRecording();
+  expect(events.filter((e) => e.kind === "http").map((e: any) => JSON.parse(e.responseBody).subject)).toEqual(["outside", "kept attempt"]);
+});
+
+test("an annotated service helper is one child of a poll's kept attempt", () => {
+  startRecording();
+  const helper = trackHelpers("service", "mail", { latest: () => annotate(observe(), "email") });
+  const start = recorderEventCount();
+  helper.latest();
+  recorderTruncate(start);
+  helper.latest();
+  const wait = recordWait({ description: "mail arrives", attempts: 2, passed: true, durationMs: 10 })!;
+  recorderMarkChildren(start, wait);
+  const events = stopRecording();
+  expect(events.map((e) => e.kind)).toEqual(["service", "email", "wait"]);
+  expect(events[0]!.parentSeq).toBe(wait);
+  expect(events[1]!.parentSeq).toBe(events[0]!.seq);
+});
+
+test("errors retain service diagnostics and fake error behavior", async () => {
+  for (const kind of ["fake", "service"] as const) {
+    startRecording();
+    const failure = new Error("mail unavailable");
+    const helper = trackHelpers(kind, "mail", {
+      async latest() { observe(); await Promise.resolve(); throw failure; },
+    });
+    await expect(helper.latest()).rejects.toBe(failure);
+    expect(stopRecording().map((e) => e.kind)).toEqual([kind === "fake" ? "fake" : "http"]);
+  }
+});
+
+test("live objects, callable clients, function properties and receivers survive", async () => {
+  startRecording();
+  const client = { query: () => 1 };
+  const sql = Object.assign((input: string) => observe(input), { unsafe: () => 2 });
+  const raw = { client, sql, subject: "Invoice", latest() { return annotate({subject: this.subject}, "email"); } };
+  const helper = trackHelpers("service", "mail", raw);
+  expect(helper.client).toBe(client);
+  expect(helper.sql.unsafe).toBe(sql.unsafe);
+  expect(helper.sql.unsafe()).toBe(2);
+  expect(helper.sql).toBe(helper.sql);
+  expect(helper.latest).toBe(helper.latest);
+  expect(helper.sql("query").subject.unwrap()).toBe("query");
+  expect<unknown>(readRaw(helper.latest())).toEqual({subject: "Invoice"});
+  expect<unknown>(readRaw(helper.latest.call({...raw, subject: "Other"}))).toEqual({subject: "Other"});
+});
+
+test("setup/eval unwrap annotated returns without recording", async () => {
+  const scope = createInstrumentationScope(false);
+  const helper = trackHelpers("service", "mail", { latest: () => annotate({subject: "Invoice"}, "email") });
+  const value = runInstrumented(scope, () => helper.latest());
+  expect<unknown>(readRaw(value)).toEqual({subject: "Invoice"});
+  expect(readTag(value)?.sourceSeq).toBeUndefined();
+  expect(stopRecording()).toEqual([]);
+});
+
+test("frozen helper records retain enumeration and can return chat annotations", () => {
+  startRecording();
+  const client = { query: () => 1 };
+  const helper = trackHelpers("service", "support", Object.freeze({
+    client,
+    conversation: () => annotate([{ side: "other", text: "Hello" }], "chat"),
+  }));
+  expect(Object.keys(helper)).toEqual(["client", "conversation"]);
+  expect("client" in helper).toBe(true);
+  expect(helper.client).toBe(client);
+  helper.conversation();
+  const events = stopRecording();
+  expect(events.map((e) => e.kind)).toEqual(["service", "chat"]);
+  expect(events[1]).toMatchObject({ parentSeq: events[0]!.seq, annotation: true });
+});
+
+test("timed-out helpers retain diagnostics and cannot write into the next test", async () => {
+  startRecording();
+  const gate = deferred();
+  const helper = trackHelpers("service", "mail", {
+    async latest() { observe("before timeout"); await gate.promise; observe("late"); return annotate({subject: "late"}, "email"); },
+  });
+  const pending = helper.latest();
+  expect(stopRecording().map((e) => e.kind)).toEqual(["http"]);
+  startRecording();
+  observe("next test");
+  gate.resolve();
+  await pending;
+  expect(stopRecording().map((e) => e.kind)).toEqual(["http"]);
+});
+
+test("detached work from an annotated helper stays suppressed after return", async () => {
+  startRecording();
+  const gate = deferred();
+  let detached!: Promise<unknown>;
+  const helper = trackHelpers("service", "mail", {
+    latest() { detached = gate.promise.then(() => observe("late")); return annotate({subject: "Invoice"}, "email"); },
+  });
+  helper.latest();
+  gate.resolve();
+  await detached;
+  expect(stopRecording().map((e) => e.kind)).toEqual(["service", "email"]);
+});
+
+test("stopping a test does not resurrect pending descendants of a collapsed helper", async () => {
+  startRecording();
+  const gate = deferred();
+  const inner = trackHelpers("service", "inner", {
+    async latest() { observe("hidden"); await gate.promise; return observe("also hidden"); },
+  });
+  let pending!: Promise<unknown>;
+  const outer = trackHelpers("service", "outer", {
+    latest() { pending = inner.latest(); return annotate({subject: "Invoice"}, "email"); },
+  });
+  outer.latest();
+  expect(stopRecording().map((e) => e.kind)).toEqual(["service", "email"]);
+  gate.resolve();
+  await pending;
+});
+
+for (const annotated of [false, true]) test(`real HTTP service helper preserves internal recording unless annotated (${annotated})`, async () => {
+  let requests = 0;
+  const server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch() { requests++; return Response.json({subject: "Invoice"}); } });
+  const restore = installFetchWrapper();
+  const scope = createInstrumentationScope();
+  startRecording();
+  try {
+    const helper = trackHelpers("service", "mail", {
+      async latest() {
+        const response = await fetch(`http://127.0.0.1:${server.port}/mail`);
+        const value = await response.json();
+        return annotated ? annotate(value, "email") : value;
+      },
+    });
+    await runInstrumented(scope, async () => {
+      const value = await helper.latest() as unknown as Wrapped<{subject:string}>;
+      assertValue(value.subject).toBe("Invoice");
+    });
+    expect(requests).toBe(1);
+    const events = stopRecording();
+    expect(events.map((e) => e.kind)).toEqual(annotated ? ["service", "email", "assertion"] : ["http", "assertion"]);
+    expect(events.at(-1)).toMatchObject({ sourceSeq: events[0]!.seq });
+  } finally { scope.active = false; restore(); server.stop(true); }
+});
+
+// Compile-time contract, including inferred annotated unions and generic live clients.
+function types(ctx: ServiceHandlesFor<{ mail: { image: string; helpers: () => {
+  plain(): number;
+  latest(): ReturnType<typeof annotation>;
+  maybe(): ReturnType<typeof annotation> | undefined;
+  asyncLatest(): Promise<ReturnType<typeof annotation>>;
+  generic<T>(value: T): T;
+} } }>) {
+  const plain: number = ctx.mail.plain();
+  assertValue(ctx.mail.latest().subject).toBe("Invoice");
+  const maybe: Wrapped<{subject:string}> | undefined = ctx.mail.maybe();
+  const promise: Promise<Wrapped<{subject:string}>> = ctx.mail.asyncLatest();
+  const literal: "kept" = ctx.mail.generic("kept" as const);
+  // @ts-expect-error annotated leaves remain wrapped at the caller
+  const invalid: string = ctx.mail.latest().subject;
+  return [plain, maybe, promise, literal, invalid];
+}
+function annotation() { return annotate({subject: "Invoice"}, "email"); }