@gaganref/confect-server 10.3.1-fork.4 → 10.3.1-fork.41

package/src/QueryStreamCursor.ts

@@ -1,12 +1,12 @@
 import * as Array from "effect/Array";
 import * as Effect from "effect/Effect";
-import * as QueryStreamKey from "./QueryStreamKey";
+import * as QueryStreamKey from "./QueryStreamKey.js";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as Match from "effect/Match";
 import * as Schema from "effect/Schema";
 import * as SchemaGetter from "effect/SchemaGetter";
-import * as QueryStreamKeyLayout from "./QueryStreamKeyLayout";
-import * as QueryStreamKeyValues from "./QueryStreamKeyValues";
+import * as QueryStreamKeyLayout from "./QueryStreamKeyLayout.js";
+import * as QueryStreamKeyValues from "./QueryStreamKeyValues.js";
 
 // Serialized labels are a cursor boundary representation. They include every
 // runtime position but do not preserve implicitness.

package/src/QueryStreamIndexPrefix.ts

@@ -1,8 +1,8 @@
 import * as Array from "effect/Array";
 import * as Data from "effect/Data";
 import * as Result from "effect/Result";
-import type * as QueryStreamKey from "./QueryStreamKey";
-import type * as QueryStreamKeyValues from "./QueryStreamKeyValues";
+import type * as QueryStreamKey from "./QueryStreamKey.js";
+import type * as QueryStreamKeyValues from "./QueryStreamKeyValues.js";
 
 const TypeId = "~@confect/server/QueryStreamIndexPrefix";
 

package/src/QueryStreamIndexRange.ts

@@ -11,10 +11,10 @@ import * as Match from "effect/Match";
 import * as Option from "effect/Option";
 import * as Result from "effect/Result";
 import type * as Types from "effect/Types";
-import * as QueryStreamIndexPrefix from "./QueryStreamIndexPrefix";
-import * as QueryStreamKeyBounds from "./QueryStreamKeyBounds";
-import * as QueryStreamKeyValues from "./QueryStreamKeyValues";
-import type * as QueryStreamOrderDirection from "./QueryStreamOrderDirection";
+import * as QueryStreamIndexPrefix from "./QueryStreamIndexPrefix.js";
+import * as QueryStreamKeyBounds from "./QueryStreamKeyBounds.js";
+import * as QueryStreamKeyValues from "./QueryStreamKeyValues.js";
+import type * as QueryStreamOrderDirection from "./QueryStreamOrderDirection.js";
 
 type Head<FieldPaths extends ReadonlyArray<string>> =
   FieldPaths extends readonly [infer H extends string, ...ReadonlyArray<string>]

package/src/QueryStreamKey.ts

@@ -1,8 +1,8 @@
 import * as Data from "effect/Data";
 import * as Predicate from "effect/Predicate";
 import * as Result from "effect/Result";
-import * as QueryStreamKeyLayout from "./QueryStreamKeyLayout";
-import type * as QueryStreamKeyValues from "./QueryStreamKeyValues";
+import * as QueryStreamKeyLayout from "./QueryStreamKeyLayout.js";
+import type * as QueryStreamKeyValues from "./QueryStreamKeyValues.js";
 
 const TypeId = "~@confect/server/QueryStreamKey";
 

package/src/QueryStreamKeyBounds.ts

@@ -3,9 +3,9 @@ import * as Data from "effect/Data";
 import * as Option from "effect/Option";
 import * as Order from "effect/Order";
 import * as Result from "effect/Result";
-import * as QueryStreamKey from "./QueryStreamKey";
-import * as QueryStreamKeyLayout from "./QueryStreamKeyLayout";
-import * as QueryStreamKeyValues from "./QueryStreamKeyValues";
+import * as QueryStreamKey from "./QueryStreamKey.js";
+import * as QueryStreamKeyLayout from "./QueryStreamKeyLayout.js";
+import * as QueryStreamKeyValues from "./QueryStreamKeyValues.js";
 
 // A bound's key may be a *prefix* of the full key: bounding by `["a"]` means
 // bounding by the whole family of keys that start with `"a"`. To compare

package/src/QueryStreamKeyLayout.ts

@@ -6,7 +6,7 @@ import * as Option from "effect/Option";
 import * as Result from "effect/Result";
 import type * as Types from "effect/Types";
 
-import * as QueryStreamKeyLabels from "./QueryStreamKeyLabels";
+import * as QueryStreamKeyLabels from "./QueryStreamKeyLabels.js";
 
 /**
  * One runtime position of a stream key. Explicit IDs and their aliases are

package/src/QueryStreamKeyValues.ts

@@ -12,7 +12,7 @@ import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as SchemaGetter from "effect/SchemaGetter";
 import * as SchemaIssue from "effect/SchemaIssue";
-import type * as QueryStreamOrderDirection from "./QueryStreamOrderDirection";
+import type * as QueryStreamOrderDirection from "./QueryStreamOrderDirection.js";
 
 const UNDEFINED_SENTINEL = { $undefined: true } as const;
 const KeyValue = Schema.Json.pipe(

package/src/QueryStreamPagination.ts

@@ -4,8 +4,8 @@ import * as Match from "effect/Match";
 import * as Option from "effect/Option";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
-import type * as QueryStreamKey from "./QueryStreamKey";
-import * as QueryStreamKeyValues from "./QueryStreamKeyValues";
+import type * as QueryStreamKey from "./QueryStreamKey.js";
+import * as QueryStreamKeyValues from "./QueryStreamKeyValues.js";
 
 const PageSize = Schema.Natural.pipe(
   Schema.brand("~@confect/server/QueryStreamPagination/PageSize"),

package/src/QueryStreamReadBudget.ts

@@ -22,8 +22,9 @@ export interface QueryStreamReadBudget {
   readonly getReadCounts: Effect.Effect<ReadCounts>;
   /**
    * Returns a stream that records reads against this budget and stops
-   * requesting further batches once exhausted. Apply directly to the document
-   * source before buffering, filtering, or combining its output.
+   * requesting further batches once exhausted, except for one limit-boundary
+   * lookahead to detect completion. Apply directly to the document source
+   * before buffering, filtering, or combining its output.
    */
   readonly accountFor: (
     encodedDocuments: Stream.Stream<unknown>,
@@ -133,10 +134,22 @@ export const make = Effect.fnUntraced(function* (
         SynchronizedRef.modifyEffect(stateRef, (state) =>
           Effect.gen(function* () {
             if (isExhausted(state, limits)) {
-              return Tuple.make(
-                Option.none(),
-                State.Stopped(readCounts(state)),
-              );
+              const canProbeEnd =
+                State.$is("Active")(state) &&
+                !Option.exists(
+                  limits.maximumRowsRead,
+                  (limit) => state.rowsRead > limit,
+                ) &&
+                !Option.exists(
+                  limits.maximumBytesRead,
+                  (limit) => state.bytesRead > limit,
+                );
+              // Iterators expose completion only through a pull. Count a
+              // lookahead row, but never publish it beyond either limit.
+              const counts = canProbeEnd
+                ? record(state, yield* pull)
+                : readCounts(state);
+              return Tuple.make(Option.none(), State.Stopped(counts));
             }
             const documents = yield* pull;
             return Tuple.make(

package/src/RegisteredConvexFunction.ts

@@ -24,27 +24,27 @@ import * as Layer from "effect/Layer";
 import * as Match from "effect/Match";
 import * as Schema from "effect/Schema";
 import * as EffectScheduler from "effect/Scheduler";
-import * as Auth from "./Auth";
-import * as ConvexConfigProvider from "./ConvexConfigProvider";
-import * as DatabaseReader from "./DatabaseReader";
-import type * as DatabaseSchema from "./DatabaseSchema";
-import * as DatabaseWriter from "./DatabaseWriter";
-import type * as DataModel from "./DataModel";
-import * as ExecutionMetadata from "./ExecutionMetadata";
-import * as RequestMetadata from "./RequestMetadata";
-import * as TransactionMetadata from "./TransactionMetadata";
-import * as MutationCtx from "./MutationCtx";
-import * as MutationRunner from "./MutationRunner";
-import * as MutationTransactionContext from "./MutationTransactionContext";
-import * as QueryCtx from "./QueryCtx";
-import * as QueryRunner from "./QueryRunner";
-import * as QueryTransactionContext from "./QueryTransactionContext";
-import * as RegisteredFunction from "./RegisteredFunction";
-import type * as FunctionRegistryItem from "./FunctionRegistryItem";
-import type * as ResolvedMiddleware from "./ResolvedMiddleware";
-import * as Scheduler from "./Scheduler";
-import { StorageWriter } from "./StorageWriter";
-import type * as Handler from "./Handler";
+import * as Auth from "./Auth.js";
+import * as ConvexConfigProvider from "./ConvexConfigProvider.js";
+import * as DatabaseReader from "./DatabaseReader.js";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import * as DatabaseWriter from "./DatabaseWriter.js";
+import type * as DataModel from "./DataModel.js";
+import * as ExecutionMetadata from "./ExecutionMetadata.js";
+import * as RequestMetadata from "./RequestMetadata.js";
+import * as TransactionMetadata from "./TransactionMetadata.js";
+import * as MutationCtx from "./MutationCtx.js";
+import * as MutationRunner from "./MutationRunner.js";
+import * as MutationTransactionContext from "./MutationTransactionContext.js";
+import * as QueryCtx from "./QueryCtx.js";
+import * as QueryRunner from "./QueryRunner.js";
+import * as QueryTransactionContext from "./QueryTransactionContext.js";
+import * as RegisteredFunction from "./RegisteredFunction.js";
+import type * as FunctionRegistryItem from "./FunctionRegistryItem.js";
+import type * as ResolvedMiddleware from "./ResolvedMiddleware.js";
+import * as Scheduler from "./Scheduler.js";
+import { StorageWriter } from "./StorageWriter.js";
+import type * as Handler from "./Handler.js";
 
 export type Definition = Data.TaggedEnum<{
   PublicQuery: ReturnType<typeof queryFunction>;
@@ -61,12 +61,14 @@ export const prepare = (
   databaseSchema: DatabaseSchema.AnyWithProps,
   item: FunctionRegistryItem.ConfectFunctionRegistryItem,
   resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware> = [],
+  observability?: Layer.Layer<never>,
 ) =>
   Match.value(item.functionType).pipe(
     Match.when("query", () => {
       const definition = queryFunction({
         databaseSchema,
         name: item.name,
+        observability,
         functionVisibility: item.functionVisibility,
         args: item.args,
         returns: item.returns,
@@ -84,6 +86,7 @@ export const prepare = (
       const definition = mutationFunction({
         databaseSchema,
         name: item.name,
+        observability,
         functionVisibility: item.functionVisibility,
         args: item.args,
         returns: item.returns,
@@ -100,6 +103,7 @@ export const prepare = (
     Match.when("action", () => {
       const definition = convexActionFunction(databaseSchema, {
         name: item.name,
+        observability,
         functionVisibility: item.functionVisibility,
         args: item.args,
         returns: item.returns,
@@ -188,6 +192,7 @@ const queryFunction = <
   error,
   handler,
   resolvedMiddlewares,
+  observability,
 }: {
   databaseSchema: DatabaseSchema_;
   name: string;
@@ -199,6 +204,7 @@ const queryFunction = <
     a: Args,
   ) => Effect.Effect<Returns, E, Handler.QueryServices<DatabaseSchema_>>;
   resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+  observability?: Layer.Layer<never> | undefined;
 }) => ({
   args: compileArgsSchema(args, databaseSchema.target.scope),
   returns: compileReturnsSchema(returns, databaseSchema.target.scope),
@@ -258,6 +264,9 @@ const queryFunction = <
         RegisteredFunction.combineErrorSchemas(error, resolvedMiddlewares),
         {
           scheduler: new EffectScheduler.MixedScheduler("sync"),
+          invocation: Effect.promise(() => ctx.meta.getFunctionMetadata()),
+          clock: observability === undefined ? undefined : queryClock,
+          observability,
         },
       ),
     ),
@@ -274,6 +283,7 @@ export const mutationLayer = <Schema extends DatabaseSchema.AnyWithProps>(
     RequestMetadata.layer(ctx.meta),
     TransactionMetadata.layer(ctx.meta),
     Auth.layerForTarget<Schema["target"]>(schema.target, ctx.auth),
+    Auth.mutationLayer(ctx.auth),
     Scheduler.layer<DatabaseSchema.Scope<Schema>>(
       ctx.scheduler,
       schema.target.scope,
@@ -313,6 +323,7 @@ const mutationFunction = <
   error,
   handler,
   resolvedMiddlewares,
+  observability,
 }: {
   databaseSchema: DatabaseSchema_;
   name: string;
@@ -324,6 +335,7 @@ const mutationFunction = <
     a: Args,
   ) => Effect.Effect<Returns, E, MutationServices<DatabaseSchema_>>;
   resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+  observability?: Layer.Layer<never> | undefined;
 }) => ({
   args: compileArgsSchema(args, databaseSchema.target.scope),
   returns: compileReturnsSchema(returns, databaseSchema.target.scope),
@@ -360,6 +372,8 @@ const mutationFunction = <
         RegisteredFunction.combineErrorSchemas(error, resolvedMiddlewares),
         {
           scheduler: new EffectScheduler.MixedScheduler("sync"),
+          invocation: Effect.promise(() => ctx.meta.getFunctionMetadata()),
+          observability,
         },
       ),
     ),
@@ -382,6 +396,7 @@ const convexActionFunction = <
     error,
     handler,
     resolvedMiddlewares,
+    observability,
   }: {
     name: string;
     functionVisibility: FunctionVisibility;
@@ -396,6 +411,7 @@ const convexActionFunction = <
       RegisteredFunction.ActionServices<DatabaseSchema_>
     >;
     resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+    observability?: Layer.Layer<never> | undefined;
   },
 ) =>
   RegisteredFunction.actionFunctionBase({
@@ -407,6 +423,7 @@ const convexActionFunction = <
     error,
     handler,
     resolvedMiddlewares,
+    observability,
     createLayer: (ctx) =>
       Layer.mergeAll(
         RegisteredFunction.actionLayer(schema, ctx),

package/src/RegisteredFunction.ts

@@ -1,3 +1,5 @@
+import * as ActionCallSpec from "@confect/core/ActionCall";
+import * as ActionCall from "./ActionCall.js";
 import type { FunctionSpec, RuntimeAndFunctionType } from "@confect/core";
 import * as IdScope from "@confect/core/IdScope";
 import type * as FunctionProvenance from "@confect/core/FunctionProvenance";
@@ -9,6 +11,7 @@ import {
 import {
   type DefaultFunctionArgs,
   type FunctionVisibility,
+  type FunctionMetadata,
   type GenericActionCtx,
   type GenericDataModel,
   type StorageReader as ConvexStorageReader,
@@ -19,30 +22,41 @@ import {
 import type { Value } from "convex/values";
 import { ConvexError } from "convex/values";
 import { pipe } from "effect/Function";
+import * as Clock from "effect/Clock";
+import * as Cause from "effect/Cause";
 import * as Console from "effect/Console";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
 import * as Result from "effect/Result";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
 import type * as EffectScheduler from "effect/Scheduler";
-import * as ActionCtx from "./ActionCtx";
-import * as ActionRunner from "./ActionRunner";
-import * as Auth from "./Auth";
-import * as ConvexLogger from "./ConvexLogger";
-import type * as DatabaseSchema from "./DatabaseSchema";
-import type * as DataModel from "./DataModel";
-import * as ExecutionMetadata from "./ExecutionMetadata";
-import * as RequestMetadata from "./RequestMetadata";
-import * as MutationRunner from "./MutationRunner";
-import * as QueryRunner from "./QueryRunner";
-import type * as ResolvedMiddleware from "./ResolvedMiddleware";
-import * as Scheduler from "./Scheduler";
-import * as Storage from "./Storage";
-import * as StorageActionWriter from "./StorageActionWriter";
-import type * as StorageReader from "./StorageReader";
-import * as StorageWriter from "./StorageWriter";
-import * as VectorSearch from "./VectorSearch";
-import type * as Handler from "./Handler";
+import * as ActionCtx from "./ActionCtx.js";
+import * as ActionRunner from "./ActionRunner.js";
+import * as Auth from "./Auth.js";
+import * as ConvexLogger from "./ConvexLogger.js";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import type * as DataModel from "./DataModel.js";
+import * as ExecutionMetadata from "./ExecutionMetadata.js";
+import * as RequestMetadata from "./RequestMetadata.js";
+import * as MutationRunner from "./MutationRunner.js";
+import * as QueryRunner from "./QueryRunner.js";
+import type * as ResolvedMiddleware from "./ResolvedMiddleware.js";
+import * as Scheduler from "./Scheduler.js";
+import * as Storage from "./Storage.js";
+import * as StorageActionWriter from "./StorageActionWriter.js";
+import type * as StorageReader from "./StorageReader.js";
+import * as StorageWriter from "./StorageWriter.js";
+import * as Tracer from "effect/Tracer";
+import * as ObservabilityRuntime from "./internal/observability.js";
+import * as VectorSearch from "./VectorSearch.js";
+import type * as Handler from "./Handler.js";
+
+export const Observability = Context.Reference<Layer.Layer<never> | undefined>(
+  "@confect/server/Observability",
+  { defaultValue: () => undefined },
+);
 
 export type Any =
   | RegisteredQuery<FunctionVisibility, DefaultFunctionArgs, any>
@@ -183,67 +197,144 @@ export const combineErrorSchemas = (
 };
 
 /**
- * Run the `Effect` as a `Promise`. The error schema acts as an allowlist of
- * failures that may be surfaced to the client as a `ConvexError`:
+ * Run the `Effect` as a `Promise`. Inspect the complete `Exit` before encoding
+ * a declared error so a typed failure cannot hide a defect.
  *
- * - With a schema: typed errors are schema-encoded and wrapped in a
- *   `ConvexError`, then thrown so Convex surfaces the data to the client.
- *   `Effect.either` escapes the failure channel before `runPromise` so the
- *   thrown `ConvexError` retains its `Symbol.for("ConvexError")` identity
- *   instead of being wrapped in Effect's `FiberFailure`.
- * - Without a schema: every failure is converted to a defect via `Effect.orDie`,
- *   so nothing—not even a `ConvexError` the handler placed in its error
- *   channel—reaches the client as a `ConvexError`. The fiber dies and
- *   `runPromise` rejects with a generic failure.
+ * Any `Die` reason takes the defect path. Without a `Die`, the first `Fail` in
+ * cause order is schema-encoded and thrown as a `ConvexError` outside the
+ * Effect runtime so Convex surfaces its data to the client. Other failures and
+ * interruptions alongside that `Fail` are ignored. Without an error schema, the
+ * selected failure is treated as a defect.
  *
- * Either way, a `ConvexError` _defect_—thrown imperatively rather than placed
- * in the error channel, e.g. the pagination protocol's `InvalidCursor` signal
- * from `QueryStream.paginate`—is rethrown bare so it retains its identity and
- * Convex serializes its `data` to the client, matching how a thrown
- * `ConvexError` behaves in a plain Convex handler.
+ * A lone `ConvexError` defect or a selected undeclared `ConvexError` failure is
+ * rethrown bare so it keeps Convex's meaning. Pagination and Workpool rely on
+ * its data for their control signals. Other causes with a `Die`, interrupt-only
+ * or empty causes, and error-encoding failures reject with a plain `Error`
+ * whose message renders the complete cause and whose `cause` holds it for
+ * server diagnostics.
  *
  * A `scheduler` in `runOptions` must be passed here as a run option rather than
  * provided via `Effect.provideService` inside `effect`: the run option lands in
  * the fiber's root context, while a service provided within `effect` pops
- * before the `orDie`/`catch`/`result` wrappers this function adds. The fiber's
- * op counter survives context pops, so a cooperative yield can fire inside
- * those wrappers—only a root-context scheduler covers them.
+ * before the exit/encoding wrappers this function adds. The fiber's op counter
+ * survives context pops, so a cooperative yield can fire inside those wrappers.
+ * Only a root-context scheduler covers them.
  */
 export const runHandlerPromise =
   (
     errorSchema: Schema.Codec<any, any> | undefined,
     runOptions?: {
       readonly scheduler?: EffectScheduler.Scheduler | undefined;
+      readonly clock?: Clock.Clock | undefined;
+      readonly invocation?: Effect.Effect<FunctionMetadata> | undefined;
+      readonly observability?: Layer.Layer<never> | undefined;
     },
   ) =>
   <A, E>(effect: Effect.Effect<A, E>): Promise<A> => {
-    // A `ConvexError` defect escapes into the (escaped) failure channel so
-    // the `throw` below rethrows it with its identity intact.
-    const rethrowConvexErrorDefects = Effect.catchDefect(
-      (defect: unknown): Effect.Effect<never, ConvexError<any>> =>
-        defect instanceof ConvexError
-          ? Effect.fail(defect)
-          : Effect.die(defect),
+    const { observability, invocation, clock } = runOptions ?? {};
+    let encodedError: Exit.Exit<any, any> | undefined;
+    let undeclared: { readonly error: unknown } | undefined;
+    const observed = Effect.tapCause(effect, (cause) =>
+      Effect.gen(function* () {
+        const reason =
+          cause.reasons.find(Cause.isDieReason) ??
+          cause.reasons.find(Cause.isFailReason);
+        if (reason?._tag === "Fail" && errorSchema !== undefined) {
+          encodedError = yield* Effect.exit(
+            Schema.encodeEffect(errorSchema)(reason.error),
+          );
+          // An encoding failure is a defect, even when it dies with a ConvexError.
+          if (Exit.isFailure(encodedError)) {
+            const encoding = encodedError.cause;
+            return yield* Cause.squash(encoding) instanceof ConvexError
+              ? Effect.die(
+                  new Error(Cause.pretty(encoding), { cause: encoding }),
+                )
+              : Effect.orDie(encodedError);
+          }
+        }
+        // With no error schema a failure is a defect, so the root span ends as one.
+        if (
+          reason?._tag === "Fail" &&
+          errorSchema === undefined &&
+          !(reason.error instanceof ConvexError)
+        ) {
+          undeclared = { error: reason.error };
+          return yield* Effect.die(reason.error);
+        }
+      }),
     );
-
-    const withConvexError =
-      errorSchema === undefined
-        ? Effect.orDie(effect)
-        : effect.pipe(
-            Effect.catch((typedError) =>
-              pipe(
-                Schema.encodeEffect(errorSchema)(typedError),
-                Effect.catchTag("SchemaError", Effect.die),
-                Effect.andThen((encodedError) =>
-                  Effect.fail(new ConvexError(encodedError)),
+    const withConvexError: Effect.Effect<Result.Result<A, ConvexError<any>>> =
+      Effect.gen(function* () {
+        const exit = yield* Effect.exit(
+          observability === undefined || invocation === undefined
+            ? effect
+            : Effect.flatMap(invocation, ({ name, type, componentPath }) =>
+                Effect.useSpan(
+                  name,
+                  {
+                    root: true,
+                    attributes: { kind: type, componentPath },
+                  },
+                  (span) =>
+                    Effect.provideService(observed, Tracer.ParentSpan, span),
                 ),
               ),
-            ),
+        );
+        if (Exit.isSuccess(exit)) {
+          return Result.succeed(exit.value);
+        }
+        if (undeclared !== undefined)
+          return yield* Effect.die(undeclared.error);
+
+        const cause =
+          encodedError !== undefined && Exit.isFailure(encodedError)
+            ? encodedError.cause
+            : exit.cause;
+        const reason =
+          cause.reasons.find(Cause.isDieReason) ??
+          cause.reasons.find(Cause.isFailReason);
+        if (
+          encodedError === undefined &&
+          reason?._tag === "Die" &&
+          cause.reasons.length === 1 &&
+          reason.defect instanceof ConvexError
+        ) {
+          return Result.fail(reason.defect);
+        }
+
+        if (reason?._tag === "Fail") {
+          if (errorSchema === undefined) {
+            if (reason.error instanceof ConvexError) {
+              return Result.fail(reason.error);
+            }
+            return yield* Effect.die(reason.error);
+          }
+          const encoded =
+            encodedError ??
+            (yield* Effect.exit(
+              Schema.encodeEffect(errorSchema)(reason.error),
+            ));
+          if (Exit.isSuccess(encoded)) {
+            return Result.fail(new ConvexError(encoded.value));
+          }
+          return yield* Effect.die(
+            new Error(Cause.pretty(encoded.cause), { cause: encoded.cause }),
           );
+        }
+        return yield* Effect.die(new Error(Cause.pretty(cause), { cause }));
+      });
     return Effect.runPromise(
-      Effect.result(rethrowConvexErrorDefects(withConvexError)).pipe(
-        Effect.provide(ConvexLogger.layer),
+      withConvexError.pipe(
+        Effect.provide(
+          observability === undefined
+            ? ConvexLogger.layer
+            : ObservabilityRuntime.memoized(observability),
+        ),
         Effect.provideService(Console.Console, globalThis.console),
+        clock === undefined
+          ? (self) => self
+          : Effect.provideService(Clock.Clock, clock),
       ),
       runOptions,
     ).then(
@@ -274,6 +365,7 @@ export const actionFunctionBase = <
   resolvedMiddlewares = [],
   createLayer,
   scope = IdScope.app,
+  observability,
 }: {
   name: string;
   functionVisibility: FunctionVisibility;
@@ -286,6 +378,7 @@ export const actionFunctionBase = <
     ctx: GenericActionCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
   ) => Layer.Layer<R>;
   scope?: IdScope.IdScope;
+  observability?: Layer.Layer<never> | undefined;
 }) => ({
   args: compileArgsSchema(args, scope),
   returns: compileReturnsSchema(returns, scope),
@@ -299,6 +392,12 @@ export const actionFunctionBase = <
         Schema.decodeUnknownEffect(args),
         Effect.catchTag("SchemaError", Effect.die),
       );
+      const restricted = resolvedMiddlewares.some(
+        ({ middlewareSpec }) =>
+          middlewareSpec.key === ActionCallSpec.Middleware.key,
+      )
+        ? restrict(ctx)
+        : undefined;
       // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context -- Middleware errors are intentionally erased here and validated by runHandlerPromise against the combined error schema below.
       const decodedReturns = yield* applyMiddleware(
         handler(decodedArgs),
@@ -309,13 +408,19 @@ export const actionFunctionBase = <
           functionVisibility,
           args: decodedArgs,
         },
-      ).pipe(Effect.provide(createLayer(ctx)));
+      ).pipe(Effect.provide(createLayer(restricted?.ctx ?? ctx)));
+      if (restricted !== undefined) yield* restricted.check;
       return yield* pipe(
         decodedReturns,
         Schema.encodeEffect(returns),
         Effect.catchTag("SchemaError", Effect.die),
       );
-    }).pipe(runHandlerPromise(combineErrorSchemas(error, resolvedMiddlewares))),
+    }).pipe(
+      runHandlerPromise(combineErrorSchemas(error, resolvedMiddlewares), {
+        invocation: Effect.promise(() => ctx.meta.getFunctionMetadata()),
+        observability,
+      }),
+    ),
 });
 
 export type ActionServices<
@@ -389,3 +494,47 @@ export const storageLayer = <Scope extends IdScope.IdScope>(
   Storage.layer(reader) as Layer.Layer<
     Storage.Storage | StorageReader.ForScope<Scope>
   >;
+
+/**
+ * Shares one dispatch budget across the entire middleware chain.
+ */
+const restrict = <Model extends GenericDataModel>(
+  ctx: GenericActionCtx<Model>,
+) => {
+  let dispatched = false;
+  const claim = () => {
+    if (dispatched) throw new ActionCall.ActionCallAlreadyUsed();
+    dispatched = true;
+  };
+  const restricted: GenericActionCtx<Model> = {
+    ...ctx,
+    scheduler: {
+      runAfter: () => {
+        throw new ActionCall.SchedulingNotAllowed();
+      },
+      runAt: () => {
+        throw new ActionCall.SchedulingNotAllowed();
+      },
+      cancel: () => {
+        throw new ActionCall.SchedulingNotAllowed();
+      },
+    },
+    runQuery: (...args) => {
+      claim();
+      return ctx.runQuery(...args);
+    },
+    runMutation: (...args) => {
+      claim();
+      return ctx.runMutation(...args);
+    },
+    runAction: () => {
+      throw new ActionCall.NestedActionNotAllowed();
+    },
+  };
+  return {
+    ctx: restricted,
+    check: Effect.suspend(() =>
+      dispatched ? Effect.void : Effect.die(new ActionCall.ActionCallNotUsed()),
+    ),
+  };
+};