@specific.dev/spectest 0.107.2 → 0.109.0

package/README.md

@@ -273,3 +273,26 @@ origin allowlists and cookie relationships. Different subdomains are still
 different origins; a synthetic response must still supply the intended CORS
 headers. Permissive mode is a convenience override and should not be used to
 verify application CORS restrictions.
+
+## Annotated service helpers (0.108.0)
+
+Service helpers support the same `return annotate(value, "email" | "chat", options?)`
+contract as fake helpers. The SDK opens the annotation box, records one named
+service call, and returns a wrapped value whose assertions link to that call.
+The annotated call's internal operations are suppressed; concurrent work is
+unaffected. Ordinary helper returns retain their values and underlying events.
+
+```ts
+helpers: ({ fetch }) => ({
+  async latest() {
+    const response = await fetch("http://mail:8080/messages/latest");
+    const mail = (await response.json<{ subject: string; text: string }>()).unwrap();
+    return annotate(mail, "email");
+  },
+})
+```
+
+The classic viewer shows `mail.latest()` with Email/JSON tabs; JSON contains
+helper arguments and the returned value. The SPA retains its nested presentation.
+`annotate` always returns a box for the helper boundary; it does not attach views
+to arbitrary recorded results. See `spectest docs /services` for a complete example.

package/dist/annotate.d.ts

@@ -1,13 +1,12 @@
 import { type EmailEventMessage, type EmailEventSummary, type StepBlock } from "./recorder.js";
 /** 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;
@@ -19,7 +18,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
@@ -33,7 +32,7 @@ export interface AnnotationOptions {
 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.
  */
@@ -56,13 +55,13 @@ type ChatRenderAnnotation = {
     blocks: StepBlock[];
 };
 /**
- * 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;
@@ -175,10 +174,12 @@ export interface ChatReactionAnnotation {
     new?: boolean;
 }
 /**
- * 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/dist/annotate.js

@@ -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 { truncateUtf8, } from "./recorder.js";
 /**
@@ -48,10 +24,12 @@ const NO_FIELDS = 'annotate(value, "email"): nothing to render — no email fiel
     'annotate(value, "email", { to: value.recipient, subject: value.title, ' +
     "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/dist/daemon.js

@@ -73,9 +73,9 @@ 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 } from "./annotate.js";
-import { isRecording, recordEmail, recordEnv, recordExec, recordFake, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
-import { deepUnwrap, readRaw, wrap } from "./inspect.js";
+import { trackHelpers } from "./helper-tracking.js";
+import { isRecording, recordEnv, recordExec, recordStep, recordTerminal, recordWait, reserveEvent, recorderEventCount, recorderMarkChildren, recorderTruncate, startRecording, stopRecording, truncateUtf8, } from "./recorder.js";
+import { readRaw, wrap } from "./inspect.js";
 import { setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 function namedServices(cfg) {
@@ -2623,7 +2623,7 @@ const FAKE_CTX = {
 /** 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) {
     const fake = FAKES.get(name);
@@ -2638,146 +2638,9 @@ async function ensureFakeHelpers(name) {
             ctx: FAKE_CTX,
         })))
         : {};
-    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, helpers) {
-    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;
-            const member = String(prop);
-            return (...args) => 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, member, fn, thisArg, callArgs) {
-    const t = Date.now();
-    const resv = reserveEvent();
-    const args = callArgs.map((a) => deepUnwrap(a));
-    const safeArgs = args.map((a) => safeSerialize(a));
-    const recordResult = (value) => {
-        // 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) => {
-        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;
-    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, member, annotation, durationMs, parentSeq) {
-    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) {
     return err?.message ?? String(err);
 }
@@ -3062,31 +2925,34 @@ async function bootstrapInner(prepared, identity) {
     logBootstrapTimings(result);
     return result;
 }
+// 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() {
+async function runProjectSetup(hook = "setup") {
     // 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() {
-    const proj = requireLoaded().project;
-    if (!proj.setup)
+async function runProjectSetupInner(hook) {
+    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
@@ -3097,9 +2963,11 @@ async function runProjectSetupInner() {
     // 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 = await spectestContext();
     try {
-        await runInstrumented(fetchScope, () => proj.setup(ctx));
+        const ctx = await spectestContext();
+        await runInstrumented(fetchScope, () => setup(ctx));
+        if (hook === "setupInteractive")
+            interactiveSetupCompleted = true;
     }
     finally {
         fetchScope.active = false;
@@ -3969,10 +3837,10 @@ async function ensureHelpers(name, def) {
         }
         HELPERS_BUILDING.add(name);
         try {
-            HELPERS_CACHE.set(name, await def.helpers({
+            HELPERS_CACHE.set(name, trackHelpers("service", name, await def.helpers({
                 name,
                 ...(await spectestContext({ service: name, includeSelf: false })),
-            }));
+            })));
         }
         finally {
             HELPERS_BUILDING.delete(name);
@@ -3984,8 +3852,8 @@ async function ensureHelpers(name, def) {
 const HELPERS_BUILDING = new Set();
 /**
  * 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) {
@@ -5268,7 +5136,13 @@ export function harnessMethods(state) {
         setRecordSecrets(secrets);
     };
     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
         // first bootstrap of this harness process.
@@ -5385,6 +5259,7 @@ export function harnessMethods(state) {
             return { ok: true, timings: await bootstrap(prepared) };
         }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => 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/dist/harness/protocol.d.ts

@@ -23,7 +23,7 @@
 /** Protocol version this build speaks. Must match `PROTOCOL_VERSION` in protocol.rs. */
 export declare const PROTOCOL_VERSION = 1;
 /** Methods either side can send. */
-export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "run" | "eval" | "setRecordSecrets" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
+export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "interactiveSetup" | "run" | "eval" | "setRecordSecrets" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
 /** Methods this build knows how to dispatch. A method outside this set still
  *  *parses* — it is answered with an error, never dropped. */
 export declare const KNOWN_METHODS: ReadonlySet<string>;

package/dist/harness/protocol.js

@@ -30,6 +30,7 @@ export const KNOWN_METHODS = new Set([
     "loadTests",
     "fingerprint",
     "bootstrap",
+    "interactiveSetup",
     "run",
     "eval",
     "setRecordSecrets",

package/dist/helper-tracking.d.ts

@@ -0,0 +1,7 @@
+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 declare function trackHelpers<H extends Record<string, unknown>>(kind: HelperKind, name: string, helpers: H): H;
+export {};

package/dist/helper-tracking.js

@@ -0,0 +1,142 @@
+import { readAnnotation } from "./annotate.js";
+import { deepUnwrap, wrap } from "./inspect.js";
+import { runUninstrumented } from "./harness/instrumentation-scope.js";
+import { captureRecording, recordEmail, recordFake, recordServiceHelper, recordStep, reserveEvent, safeSerialize, } from "./recorder.js";
+/** 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(kind, name, helpers) {
+    const methods = new Map();
+    // A separate, extensible target also supports frozen helper records: a proxy
+    // over the original cannot substitute a non-writable function property.
+    const proxy = 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;
+            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, name, member, fn, receiver, callArgs) {
+    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) => {
+        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) => {
+        // 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;
+    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, name, member, args, result, durationMs, reservation) {
+    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, member, annotation, durationMs, parentSeq) {
+    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;
+    }
+}