@specific.dev/spectest 0.107.1 → 0.108.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);
 }
@@ -3969,10 +3832,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 +3847,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) {

package/dist/harness/ingress-server.js

@@ -113,9 +113,15 @@ export async function startIngressServer(options) {
                 headers.append(incoming.rawHeaders[i], incoming.rawHeaders[i + 1]);
             }
             const method = incoming.method ?? "GET";
+            // An HTTP/1 request without framing has no body. Giving it even an
+            // empty stream makes fetch invent chunked framing upstream (e.g. a
+            // bodyless DELETE then fails Fastify's content-type validation).
+            // Keep explicitly chunked bodies streaming, including empty ones.
+            const hasBody = method !== "GET" && method !== "HEAD"
+                && (headers.has("transfer-encoding") || Number(headers.get("content-length")) > 0);
             const req = new Request(new URL(incoming.url ?? "/", `http://${headers.get("host") ?? "localhost"}`), {
                 method, headers, signal: abort.signal,
-                body: method === "GET" || method === "HEAD" ? undefined : Readable.toWeb(incoming),
+                body: hasBody ? Readable.toWeb(incoming) : undefined,
                 duplex: "half",
             });
             peers.set(req, incoming.socket);

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

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { Android, AndroidApp } from "./android.js";
 export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 import { strict as nodeAssert } from "node:assert";
 export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedHeaders, WrappedBuffer, WrappedBinaryView, WrappedBytes, WrappedBlob, WrappedFile, WrappedFormData, WrappedStream, WrappedReader, WrappedBYOBReader, WrappedReadResult, WrappedResponse, Provenanced, SpectestFetch, SpectestRequestInit, Unwrap, } from "./inspect.js";
-import type { Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
+import type { Provenanced, SpectestFetch, Wrapped, Unwrap } from "./inspect.js";
 export { field } from "./inspect.js";
 export { annotate } from "./annotate.js";
 export type { Annotated, AnnotationKind, AnnotationOptions, ChatAnnotation, ChatMessageAnnotation, ChatReactionAnnotation, EmailAnnotation, } from "./annotate.js";
@@ -563,6 +563,11 @@ export interface ServiceDefinition<H extends Record<string, any> = Record<string
      * 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>;
     /**
@@ -600,13 +605,20 @@ type HelpersOf<D> = "helpers" extends keyof D ? [NonNullable<D["helpers"]>] exte
 /**
  * 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
  * typed `ctx.svc` in test bodies is `ServiceHandlesFor<S>`. */
@@ -1543,14 +1555,14 @@ export declare function defineFake<S = any, H extends Record<string, unknown> =
  * at use sites. */
 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
  * `void` side-effect helpers) pass through untouched. Mirrors `Tagged<T>` in
  * `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>>> : H[K] extends (...args: infer A) => infer R ? (...args: A) => [R] extends [void] ? void : Wrapped<Unannotated<R>> : H[K];
+    [K in keyof H]: H[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Wrapped<Unwrap<Unannotated<R>>>> : H[K] extends (...args: infer A) => infer R ? (...args: A) => [R] extends [void] ? void : Wrapped<Unwrap<Unannotated<R>>> : H[K];
 };
 /** A helper's return type as the *test* sees it. {@link annotate} boxes the
  * value in an {@link Annotated} to pick how the step renders; the daemon

package/dist/index.js

@@ -17,13 +17,9 @@ import { adoptNullishTag, readRaw, readTag } from "./inspect.js";
 // always wrapped (in every context), so the method is always there; there is no
 // `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";
 // Instrumented client primitives — drop-in replacements for Bun's native
 // clients that record each operation on the test event log and return their

package/dist/recorder.d.ts

@@ -1,5 +1,5 @@
 import type { AndroidStepDetails } from "./android-step.js";
-export type TestEvent = ExecEvent | AssertionEvent | HttpEvent | KubeEvent | BrowserEvent | DbEvent | RedisEvent | S3Event | TerminalEvent | TerminalStepEvent | WaitEvent | FakeEvent | EnvEvent | EmailEvent | StepEvent;
+export type TestEvent = ExecEvent | AssertionEvent | HttpEvent | KubeEvent | BrowserEvent | DbEvent | RedisEvent | S3Event | TerminalEvent | TerminalStepEvent | WaitEvent | FakeEvent | ServiceHelperEvent | EnvEvent | EmailEvent | StepEvent;
 interface BaseEvent {
     /** Order of *start* within the test. Reserved when an op begins (see
      *  `reserveEvent`), so an op whose nested children finish — and record —
@@ -294,6 +294,13 @@ export interface FakeEvent extends BaseEvent {
     /** Set if the helper threw. */
     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
@@ -563,6 +570,15 @@ export interface EventReservation {
     seq: number;
     tOffsetMs: number;
 }
+/** 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 declare function captureRecording(): {
+    run<T>(fn: () => T): T;
+    finish(keep: boolean): void;
+    isCurrent(): boolean;
+};
 export declare function pauseRecording(): void;
 export declare function resumeRecording(): void;
 export declare function startRecording(startedAt?: number): void;
@@ -592,6 +608,7 @@ export declare function recordS3(ev: Omit<S3Event, "seq" | "tOffsetMs" | "kind">
 export declare function recordTerminal(ev: Omit<TerminalEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordTerminalStep(ev: Omit<TerminalStepEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordFake(ev: Omit<FakeEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
+export declare function recordServiceHelper(ev: Omit<ServiceHelperEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 export declare function recordEnv(ev: Omit<EnvEvent, "seq" | "tOffsetMs" | "kind">, reservation?: EventReservation): number | undefined;
 /**
  * One block of step detail, in the dashboard's presentation vocabulary