@specific.dev/spectest 0.107.1 → 0.108.0

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"); }

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];
 };