effect-cf 0.32.1 → 0.34.0

package/src/ContainerNamespace.ts

@@ -6,13 +6,10 @@ import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedContainerNamespace = "Container namespace binding with getByName()";
 
-/** Named signal accepted by Cloudflare Container instances. */
 export type ContainerSignal = "SIGKILL" | "SIGINT" | "SIGTERM";
 
-/** Named or numeric signal accepted by Container `stop()`. */
 export type ContainerStopSignal = ContainerSignal | number;
 
-/** Per-instance Container startup configuration. */
 export interface ContainerStartOptions {
   readonly envVars?: Record<string, string>;
   readonly entrypoint?: Array<string>;
@@ -34,7 +31,6 @@ export interface ContainerReadinessOptions {
   readonly waitInterval?: number;
 }
 
-/** Options for starting a Container and waiting for its ports. */
 export interface ContainerStartAndWaitForPortsOptions {
   readonly startOptions?: ContainerStartOptions;
   readonly ports?: number | Array<number>;
@@ -77,7 +73,6 @@ export interface ContainerStub {
   removeDeniedHost(hostname: string): Promise<void>;
 }
 
-/** Native Container namespace binding shape. */
 export interface ContainerNamespaceResource {
   getByName(
     name: string,
@@ -85,18 +80,14 @@ export interface ContainerNamespaceResource {
   ): ContainerStub;
 }
 
-/** Exact native stub type produced by a Container namespace binding. */
 export type ContainerStubOf<Namespace extends ContainerNamespaceResource> = ReturnType<
   Namespace["getByName"]
 >;
 
-/** Container namespace binding metadata. */
 export interface ContainerNamespaceDefinition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
-/** Failure raised when invoking a named Container operation. */
 export class ContainerOperationError extends Data.TaggedError("ContainerOperationError")<{
   readonly binding: string;
   readonly instance: string;
@@ -108,7 +99,6 @@ export class ContainerOperationError extends Data.TaggedError("ContainerOperatio
   }
 }
 
-/** Effect-wrapped client for one named Container instance. */
 export interface ContainerInstanceClient<Stub extends ContainerStub = ContainerStub> {
   readonly rawUnsafe: Effect.Effect<Stub, ContainerOperationError>;
   readonly state: Effect.Effect<ContainerState, ContainerOperationError>;
@@ -140,7 +130,6 @@ export interface ContainerInstanceClient<Stub extends ContainerStub = ContainerS
   readonly removeDeniedHost: (hostname: string) => Effect.Effect<void, ContainerOperationError>;
 }
 
-/** Effect client for a Container namespace binding. */
 export interface ContainerNamespaceClient<
   Namespace extends ContainerNamespaceResource = ContainerNamespaceResource,
 > {
@@ -433,14 +422,12 @@ export const make = <Id extends string>(id: Id) => Tag<ContainerNamespaceService
 
 declare const ContainerNamespaceServiceTypeId: unique symbol;
 
-/** Nominal service marker for Container namespaces created with {@link make}. */
 export interface ContainerNamespaceService<Id extends string> {
   readonly [ContainerNamespaceServiceTypeId]: {
     readonly id: Id;
   };
 }
 
-/** Creates a typed Effect service for a Cloudflare Container namespace. */
 export const Tag =
   <Self, Namespace extends ContainerNamespaceResource = ContainerNamespaceResource>() =>
   <Id extends string>(id: Id) => {

package/src/D1.ts

@@ -10,18 +10,14 @@ const TypeId = "~effect-cf/D1" as const;
 export type TypeId = typeof TypeId;
 const expectedD1Database = "D1 database binding with prepare(), batch(), and exec()";
 
-/** Typed D1 binding definition. */
 export interface D1Definition {
-  /** Binding name as configured in `wrangler.jsonc`. */
   readonly binding: string;
 }
 
-/** Options forwarded to `@effect/sql-d1` when building a SQL client layer. */
 export type D1SqlLayerOptions = Omit<D1Client.D1ClientConfig, "db">;
 
 declare const D1ServiceTypeId: unique symbol;
 
-/** Nominal service marker for D1 services created with {@link make}. */
 export interface D1Service<Id extends string> {
   readonly [D1ServiceTypeId]: {
     readonly id: Id;
@@ -36,27 +32,9 @@ const isD1Database = <Candidate>(value: Candidate): value is Candidate & D1Datab
   Predicate.hasProperty(value, "exec") &&
   Predicate.isFunction(value.exec);
 
-/**
- * Creates a typed D1 service tag plus Effect helpers.
- */
 export const make = <Id extends string>(id: Id, definition: D1Definition) =>
   Service<D1Service<Id>>()(id, definition);
 
-/**
- * Builds a D1 service around a Cloudflare D1 database binding.
- *
- * The returned service exposes the raw `D1Database` binding and `sqlLayer(...)`
- * for providing `effect/unstable/sql` via `@effect/sql-d1`.
- *
- * @example
- * ```ts
- * class TodoDatabase extends D1.Service<TodoDatabase>()("TodoDatabase", {
- *   binding: "TODO_DB",
- * }) {}
- *
- * const SqlLive = TodoDatabase.sqlLayer();
- * ```
- */
 export const Service =
   <Self>() =>
   <Id extends string>(id: Id, definition: D1Definition) => {

package/src/DurableObject.ts

@@ -1,5 +1,5 @@
 import { DurableObject as CloudflareDurableObject } from "cloudflare:workers";
-import { Effect, Layer, type ManagedRuntime, type Scope } from "effect";
+import { Effect, Layer, type ManagedRuntime, type Scope, Tracer } from "effect";
 
 import { NativeRequest } from "./Worker";
 import { WorkerEnvironment, type WorkerEnv } from "./Environment";
@@ -8,6 +8,7 @@ import { fromWebSocket, type DurableWebSocket } from "./DurableObjectWebSocket";
 import * as Entrypoint from "./internal/Entrypoint";
 import * as Runtime from "./internal/Runtime";
 import * as Telemetry from "./internal/Telemetry";
+import type { ReceiverOptions, RpcInvocationInfo } from "./RpcTracing";
 
 const reservedMethodNames = new Set<string>([
   "constructor",
@@ -24,11 +25,21 @@ type RuntimeContext<ROut> = DurableObjectState | WorkerEnvironment | ROut;
 type HandlerContext<ROut> = RuntimeContext<ROut> | Scope.Scope;
 
 type FetchContext<ROut> = HandlerContext<ROut> | NativeRequest;
-type RunOptions = {
+/** Metadata available before an event effect or its event layer starts. */
+export interface RunOptions {
   readonly eventLayer?: boolean;
-};
+  readonly event?:
+    | "fetch"
+    | "rpc"
+    | "alarm"
+    | "webSocketMessage"
+    | "webSocketClose"
+    | "webSocketError";
+  readonly rpc?: RpcInvocationInfo;
+}
 
-const RunSymbol = Symbol.for("effect-cf/DurableObject/run");
+/** Override to instrument the whole event, then call super[RunSymbol]. */
+export const RunSymbol = Symbol.for("effect-cf/DurableObject/run");
 
 const scheduleTelemetryFlush: Effect.Effect<void, never, DurableObjectState> =
   Telemetry.scheduleTelemetryFlush((flush) =>
@@ -74,9 +85,6 @@ export type RpcHandlers<ROut, Api> = {
     : never;
 };
 
-/**
- * Options for creating a Durable Object class backed by Effect handlers.
- */
 export interface DurableObjectOptions<
   RRuntime,
   REvent = never,
@@ -113,15 +121,10 @@ export interface DurableObjectOptions<
    * does not.
    */
   readonly rpc?: Rpc;
-  /** Optional fetch handler for HTTP/WebSocket requests. */
+  /** Accept live native trace metadata. The client must also enable rpcTracing. */
+  readonly rpcTracing?: ReceiverOptions;
   readonly fetch?: Effect.Effect<Response, unknown, FetchContext<RRuntime | REvent>>;
-  /**
-   * Optional logical alarm processing effect.
-   *
-   * This runs before `alarm` and should be built with helpers such as
-   * `DurableObjectAlarm.processDue(...)` so the reusable scheduler stays inside
-   * the Durable Object's single managed runtime boundary.
-   */
+
   readonly alarms?: Effect.Effect<unknown, unknown, HandlerContext<RRuntime | REvent>>;
   /**
    * Optional raw alarm handler.
@@ -156,11 +159,14 @@ export interface DurableObjectOptions<
 export type DurableObjectClass<Rpc extends DurableObjectRpc<ROut>, ROut> = new (
   state: globalThis.DurableObjectState,
   env: WorkerEnv,
-) => CloudflareDurableObject<WorkerEnv> & DurableObjectRpcApi<Rpc, ROut>;
+) => CloudflareDurableObject<WorkerEnv> &
+  DurableObjectRpcApi<Rpc, ROut> & {
+    [RunSymbol]<A, E>(
+      effect: Effect.Effect<A, E, HandlerContext<ROut>>,
+      options?: RunOptions,
+    ): Promise<A>;
+  };
 
-/**
- * Creates a Durable Object class backed by a single managed Effect runtime.
- */
 export const make = <
   ROut,
   LayerError,
@@ -195,6 +201,8 @@ export const make = <
       runOptions: RunOptions = {},
     ): Promise<A> {
       const eventLayer = runOptions.eventLayer === false ? undefined : options.eventLayer;
+      const parent = runOptions.rpc?.parent;
+      const parentSpan = parent === undefined ? undefined : Tracer.externalSpan(parent);
 
       if (eventLayer === undefined) {
         // SAFETY: event-layer bypass is used only for initialize; otherwise an absent layer means REvent is never.
@@ -202,6 +210,8 @@ export const make = <
           this.runtime,
           // @effect-diagnostics-next-line unsafeEffectTypeAssertion:off
           effect as Effect.Effect<A, E, HandlerContext<ROut>>,
+          undefined,
+          parentSpan,
         );
       }
 
@@ -212,7 +222,7 @@ export const make = <
         REvent,
         EventLayerError,
         LayerError
-      >(this.runtime, effect, eventLayer);
+      >(this.runtime, effect, eventLayer, parentSpan);
     }
 
     fetch(request: Request): Promise<Response> {
@@ -222,7 +232,9 @@ export const make = <
         return Promise.resolve(new Response("Not Found", { status: 404 }));
       }
 
-      return this[RunSymbol](Effect.provideService(fetchHandler, NativeRequest, request));
+      return this[RunSymbol](Effect.provideService(fetchHandler, NativeRequest, request), {
+        event: "fetch",
+      });
     }
 
     alarm(alarmInfo?: globalThis.AlarmInvocationInfo): Promise<void> | void {
@@ -237,13 +249,17 @@ export const make = <
           : (logicalAlarms ?? rawAlarm);
 
       if (alarmEffect !== undefined) {
-        return this[RunSymbol](alarmEffect.pipe(Effect.onExit(() => scheduleTelemetryFlush)));
+        return this[RunSymbol](alarmEffect.pipe(Effect.onExit(() => scheduleTelemetryFlush)), {
+          event: "alarm",
+        });
       }
     }
 
     webSocketMessage(socket: WebSocket, message: string | ArrayBuffer): Promise<void> | void {
       if (options.webSocketMessage !== undefined) {
-        return this[RunSymbol](options.webSocketMessage(fromWebSocket(socket), message));
+        return this[RunSymbol](options.webSocketMessage(fromWebSocket(socket), message), {
+          event: "webSocketMessage",
+        });
       }
     }
 
@@ -256,13 +272,16 @@ export const make = <
       if (options.webSocketClose !== undefined) {
         return this[RunSymbol](
           options.webSocketClose(fromWebSocket(socket), code, reason, wasClean),
+          { event: "webSocketClose" },
         );
       }
     }
 
     webSocketError(socket: WebSocket, cause: unknown): Promise<void> | void {
       if (options.webSocketError !== undefined) {
-        return this[RunSymbol](options.webSocketError(fromWebSocket(socket), cause));
+        return this[RunSymbol](options.webSocketError(fromWebSocket(socket), cause), {
+          event: "webSocketError",
+        });
       }
     }
   }
@@ -272,8 +291,9 @@ export const make = <
     EffectDurableObject.prototype,
     options.rpc,
     reservedMethodNames,
-    (self, effect) => self[RunSymbol](effect),
+    (self, effect, rpc) => self[RunSymbol](effect, { event: "rpc", rpc }),
     () => scheduleTelemetryFlush,
+    options.rpcTracing,
   );
 
   return Entrypoint.assumeEntrypointClass<DurableObjectClass<Rpc, ROut | REvent>>(

package/src/DurableObjectAlarm.ts

@@ -34,13 +34,6 @@ const DEFAULT_PROCESS_DUE_ALARMS_FAILURE_RESCHEDULE_AFTER = "30 seconds" satisfi
 const getScheduledEventId = (input: { readonly id: string; readonly tag: string }) =>
   `effect-cf-alarm:${encodeURIComponent(input.tag)}:${encodeURIComponent(input.id)}`;
 
-/**
- * JSON-serializable alarm payload stored with each scheduled alarm.
- *
- * Payloads are intentionally opaque to `DurableObjectAlarm`. Consumers should use
- * stable `tag` values to route due alarms and then decode the payload for that
- * tag in their own domain layer.
- */
 export type AlarmPayload = S.Json;
 
 interface AlarmRow extends Record<string, SqlStorageValue> {
@@ -107,52 +100,17 @@ export type DurableObjectAlarmError =
   | StorageOperationError
   | StoredAlarmDecodeError;
 
-/**
- * Events handled by `processDueAlarms`.
- *
- * `AlarmDue` represents one durable alarm whose scheduled time is now due. The
- * `tag` is the consumer-owned routing key, while `id` is the stable alarm id
- * within that tag.
- *
- * `scheduledAt` is the logical due-after timestamp from durable storage. It is
- * not expected to match the current Durable Object alarm invocation time,
- * especially during retries. Retries re-scan durable rows with `run_at <= now`
- * and identify logical events by `{ tag, id }`.
- *
- * @example Handling events by tag
- * ```ts
- * yield* durableObjectAlarm.processDueAlarms((event) =>
- *   event.tag === "heartbeat"
- *     ? heartbeatManager.handleAlarmEvent(event).pipe(Effect.asVoid)
- *     : Effect.void
- * );
- * ```
- */
 export const DurableObjectAlarmEvent = S.TaggedUnion({
   AlarmDue: {
     id: S.NonEmptyString,
     payload: S.Json,
+    /** Persisted due time, which can differ from the invocation time during retries. */
     scheduledAt: S.DateTimeUtc,
     tag: S.NonEmptyString,
   },
 });
 export type DurableObjectAlarmEvent = typeof DurableObjectAlarmEvent.Type;
 
-/**
- * Stable reference for a scheduled alarm.
- *
- * The pair of `tag` and `id` is the durable identity. Scheduling another alarm
- * with the same pair replaces the previous alarm, and cancellation uses the
- * same pair.
- *
- * @example Cancel an alarm
- * ```ts
- * yield* durableObjectAlarm.cancelAlarm({
- *   tag: "connection-reconnect-grace",
- *   id: "reconnect-grace-check",
- * });
- * ```
- */
 export type AlarmRef<Tag extends string = string> = {
   readonly id: string;
   readonly tag: Tag;
@@ -168,38 +126,7 @@ const decodeAlarmRef = (input: AlarmRef) =>
     Effect.mapError((cause) => new InvalidAlarmRefError({ cause })),
   );
 
-/**
- * Input for scheduling or replacing an alarm.
- *
- * `runAt` is the absolute first fire time. `repeatEvery` can be any Effect
- * `Duration.Input`, including strings like `"5 seconds"`, numbers interpreted
- * as milliseconds, or `Duration` values.
- *
- * @example One-shot alarm
- * ```ts
- * const now = yield* DateTime.now;
- *
- * yield* durableObjectAlarm.scheduleAlarm({
- *   tag: "connection-reconnect-grace",
- *   id: "reconnect-grace-check",
- *   runAt: DateTime.add(now, { seconds: 15 }),
- *   payload: { reason: "socket-closed" },
- * });
- * ```
- *
- * @example Repeating alarm
- * ```ts
- * const now = yield* DateTime.now;
- *
- * yield* durableObjectAlarm.scheduleAlarm({
- *   tag: "heartbeat",
- *   id: "heartbeat-check",
- *   runAt: DateTime.add(now, { seconds: 5 }),
- *   repeatEvery: "5 seconds",
- *   payload: null,
- * });
- * ```
- */
+/** Reusing `{tag, id}` replaces an alarm. Repeats run after success, never as fixed-cadence catch-up. */
 export type ScheduleAlarmInput<Tag extends string = string> = AlarmRef<Tag> & {
   readonly payload: AlarmPayload;
   readonly repeatEvery?: Duration.Input;
@@ -237,107 +164,26 @@ export type ProcessDueAlarmsFailureAction =
     };
 
 export interface ProcessDueAlarmsOptions<OnFailureR = never, OnFailureE = never> {
-  /** Maximum due rows to load and process in one invocation. Defaults to 100. */
   readonly limit?: number;
-  /**
-   * Failure isolation mode. Defaults to `isolated` so one poison logical alarm
-   * does not block unrelated maintenance work.
-   */
+  /** `isolated` retries only the failed row; `ordered` stops before later rows. */
   readonly mode?: ProcessDueAlarmsMode;
-  /**
-   * Callback for logical handler/decode failures. Return a failure action to
-   * override the global failure behavior for this row.
-   */
   readonly onFailure?: (
     failure: ProcessDueAlarmsFailure,
   ) => Effect.Effect<ProcessDueAlarmsFailureAction | void, OnFailureE, OnFailureR>;
-  /**
-   * Delay before retrying a failed logical row in isolated mode. Defaults to 30
-   * seconds. Ignored by ordered mode unless supplied explicitly.
-   *
-   * Retrying updates only the selected occurrence, so replacements scheduled by
-   * a long-running handler are not clobbered by failure handling.
-   */
   readonly retryFailedAfter?: Duration.Input;
 }
 
-/**
- * Handler invoked for each due alarm before that alarm is acknowledged.
- *
- * If the handler fails, `DurableObjectAlarm` leaves the row due and fails the alarm
- * processing effect. Cloudflare can then retry the Durable Object alarm handler,
- * and the scheduler will find the same logical row again because `run_at` is
- * still less than or equal to the retry time.
- */
 export type ProcessDueAlarmsHandler<R = never, E = never> = (
   event: DurableObjectAlarmEvent,
 ) => Effect.Effect<void, E, R>;
 
-/**
- * Durable alarm scheduler API.
- *
- * This service only owns scheduling semantics. It does not publish, subscribe,
- * or dispatch events to consumers. Durable Object alarm handlers should pass a
- * domain handler to `processDueAlarms`; rows are acknowledged only after that
- * handler succeeds.
- *
- * This service must be the only code path that owns `storage.setAlarm()` inside
- * a Durable Object instance. Cloudflare exposes one platform alarm timestamp per
- * object, so another scheduler in the same object can clobber this service's
- * reconciled alarm timestamp.
- *
- * @example Durable Object alarm handler
- * ```ts
- * const onAlarm = Effect.gen(function* () {
- *   const durableObjectAlarm = yield* DurableObjectAlarm;
- *
- *   yield* durableObjectAlarm.processDueAlarms((event) =>
- *     Effect.gen(function* () {
- *       if (event.tag === "heartbeat") {
- *         yield* heartbeatManager.handleAlarmEvent(event);
- *         return;
- *       }
- *
- *       if (event.tag === "connection-reconnect-grace") {
- *         yield* connectionManager.expireReconnectGracePeriods();
- *       }
- *     })
- *   );
- * });
- * ```
- */
+/** Own `storage.setAlarm()` exclusively: a Durable Object has one platform alarm timestamp. */
 export type AlarmScheduler = {
-  /**
-   * Cancel a scheduled alarm by `{ tag, id }`.
-   *
-   * This is idempotent. Cancelling a missing alarm is a no-op. The underlying
-   * Durable Object alarm is reconciled afterward.
-   */
   readonly cancelAlarm: (
     input: AlarmRef,
   ) => Effect.Effect<void, InvalidAlarmRefError | StorageOperationError>;
 
-  /**
-   * Process due alarms according to `Clock.currentTimeMillis`.
-   *
-   * Each row is acknowledged only after `handle` succeeds. One-shot alarms are
-   * then deleted. Repeating alarms are rescheduled to `acknowledgedAt +
-   * repeatEvery`, which intentionally behaves as delay-after-success rather
-   * than fixed-cadence catch-up. Acknowledgements are conditional on the stored
-   * row still matching the selected occurrence, so a handler that reschedules
-   * the same `{ tag, id }` will not have its replacement clobbered by the old
-   * acknowledgement.
-   *
-   * Processing is ordered by `runAt` and stable alarm id. By default, logical
-   * handler/decode failures are isolated to the failing row: the row is retried
-   * after `retryFailedAfter`, later due rows still run, and the result reports
-   * both handled and failed rows. Use `mode: "ordered"` when a workflow
-   * intentionally requires strict head-of-line blocking.
-   *
-   * Handlers must still be idempotent: Cloudflare alarms are at-least-once, and
-   * if a handler succeeds but the acknowledgement write fails, the logical event
-   * can be delivered again.
-   */
+  /** Acknowledge after handling. Conditional writes preserve handler replacements; alarms are at-least-once. */
   readonly processDueAlarms: <R = never, E = never, OnFailureR = never, OnFailureE = never>(
     handle: ProcessDueAlarmsHandler<R, E>,
     options?: ProcessDueAlarmsOptions<OnFailureR, OnFailureE>,
@@ -347,13 +193,7 @@ export type AlarmScheduler = {
     R | OnFailureR
   >;
 
-  /**
-   * Schedule or replace an alarm by `{ tag, id }`.
-   *
-   * The durable row write and underlying platform alarm reconciliation are run
-   * in one Durable Object storage transaction, so a failed `setAlarm` rolls back
-   * the logical schedule instead of leaving a stored-but-unarmed alarm.
-   */
+  /** A failed platform setAlarm rolls back the logical schedule in the same transaction. */
   readonly scheduleAlarm: (
     input: ScheduleAlarmInput,
   ) => Effect.Effect<
@@ -578,50 +418,6 @@ export const define = <const Definitions extends AlarmDefinitions>(definitions:
     ),
 });
 
-/**
- * SQLite-backed Durable Object alarm scheduler.
- *
- * `DurableObjectAlarm` stores alarms in the current Durable Object's SQLite storage
- * and keeps the platform alarm set to the earliest pending scheduled alarm. The
- * platform alarm timestamp is only a wake-up hint; logical event identity comes
- * from persisted `{ tag, id }` rows.
- *
- * Retry safety depends on acknowledgement ordering. `processDueAlarms` runs the
- * caller's handler first and only then conditionally deletes or advances the
- * same selected row. By default, handler failures are isolated: the failed row
- * is retried after a delay, later due rows continue, and the platform alarm is
- * reconciled once at the end. Use `mode: "ordered"` for strict workflows where
- * one failed logical alarm should block later due alarms.
- *
- * Provide `DurableObjectAlarm.layer` anywhere `DurableObjectState` is available.
- *
- * @example Providing the service
- * ```ts
- * const program = Effect.gen(function* () {
- *   const durableObjectAlarm = yield* DurableObjectAlarm;
- *   const now = yield* DateTime.now;
- *
- *   yield* durableObjectAlarm.scheduleAlarm({
- *     tag: "heartbeat",
- *     id: "heartbeat-check",
- *     runAt: DateTime.add(now, { seconds: 5 }),
- *     repeatEvery: Duration.seconds(5),
- *     payload: null,
- *   });
- * }).pipe(Effect.provide(DurableObjectAlarm.layer));
- * ```
- *
- * @example Processing due alarms
- * ```ts
- * const handledEvents = yield* durableObjectAlarm.processDueAlarms((event) =>
- *   Effect.gen(function* () {
- *     if (event.tag === "heartbeat") {
- *       yield* heartbeatManager.handleAlarmEvent(event);
- *     }
- *   })
- * );
- * ```
- */
 export class DurableObjectAlarm extends Context.Service<DurableObjectAlarm, AlarmScheduler>()(
   "effect-cf/DurableObjectAlarm",
 ) {

package/src/DurableObjectDefinition.ts

@@ -7,9 +7,9 @@ import * as DurableObjectNamespace from "./DurableObjectNamespace";
 import type { DurableObjectState } from "./DurableObjectState";
 import type * as Rpc from "./Rpc";
 import * as RpcDefinition from "./RpcDefinition";
+import { recordDecodedArgs } from "./internal/RpcInvocation";
 import type { WorkerEnvironment } from "./Environment";
 
-/** Internal dynamic invocation used only before the public client contract is restored. */
 type ErasedInvoke<E> = (...args: ReadonlyArray<unknown>) => Effect.Effect<unknown, E>;
 
 export type ServiceFreeSchema = S.Codec<any, any, never, never>;
@@ -34,7 +34,6 @@ export namespace Method {
       ? [S.Schema.Type<Head>, ...ArgsFromSchemas<Tail>]
       : Array<S.Schema.Type<Args[number]>>;
 
-  /** Method schemas cross the wire through their canonical JSON codec. */
   type EncodedArgsFromSchemas<Args extends ReadonlyArray<ServiceFreeSchema>> = {
     [Index in keyof Args]: S.Json;
   };
@@ -138,6 +137,7 @@ export interface Options<
 
 export type LayerOptions = {
   readonly binding: string;
+  readonly rpcTracing?: boolean;
 };
 
 export type TagClass<
@@ -192,19 +192,6 @@ export function method(definition: {
   return RpcDefinition.method(definition);
 }
 
-/**
- * Creates a Durable Object RPC definition plus implementation/binding helpers.
- *
- * @example
- * ```ts
- * const ChatRoom = DurableObjectDefinition.make("ChatRoom", {
- *   postMessage: DurableObjectDefinition.method({
- *     args: [Schema.String],
- *     success: Schema.Void,
- *   }),
- * });
- * ```
- */
 const makeDefinition = <Id extends string, const MethodDefinitions extends Methods>(
   id: Id,
   methods: MethodDefinitions & NoReservedMethods<MethodDefinitions>,
@@ -319,7 +306,7 @@ export const Tag =
       return yield* namespace.fetch(stub, input, init);
     });
 
-    const rpc = Effect.fn("DurableObject.rpc")(function* <MethodName extends keyof ClientApi>(
+    const rpc = Effect.fnUntraced(function* <MethodName extends keyof ClientApi>(
       stub: DurableObjectNamespace.DurableObjectStubClient<ClientApi>,
       methodName: MethodName,
       ...args: ClientApi[MethodName] extends (...args: infer Args) => Promise<any> ? Args : never
@@ -333,7 +320,7 @@ export const Tag =
       return yield* invokeRpc(stub, methodName, ...args);
     });
 
-    const call = Effect.fn("DurableObject.call")(function* <MethodName extends keyof ClientApi>(
+    const call = Effect.fnUntraced(function* <MethodName extends keyof ClientApi>(
       stub: DurableObjectNamespace.DurableObjectStubClient<ClientApi>,
       methodName: MethodName,
       ...args: ClientApi[MethodName] extends (...args: infer Args) => Promise<any> ? Args : never
@@ -348,9 +335,7 @@ export const Tag =
       return yield* invokeCall(stub, methodName, ...args);
     });
 
-    const scopedCall = Effect.fn("DurableObject.scopedCall")(function* <
-      MethodName extends keyof ClientApi,
-    >(
+    const scopedCall = Effect.fnUntraced(function* <MethodName extends keyof ClientApi>(
       stub: DurableObjectNamespace.DurableObjectStubClient<ClientApi>,
       methodName: MethodName,
       ...args: ClientApi[MethodName] extends (...args: infer Args) => Promise<any> ? Args : never
@@ -425,6 +410,9 @@ const wrapHandlers = <ROut, const Self extends Definition.Any>(
     wrapped[key] = (...args: Array<unknown>) =>
       Effect.gen(function* () {
         const decodedArgs = yield* RpcDefinition.decodeArgs(definition, key, args);
+
+        yield* recordDecodedArgs(decodedArgs);
+
         const value = yield* handler(...decodedArgs);
 
         return yield* RpcDefinition.encodeSuccess(definition, key, value);