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

package/src/GroupImpl.ts

@@ -1,17 +1,18 @@
 import type * as GroupSpec from "@confect/core/GroupSpec";
 import type * as MiddlewareSpec from "@confect/core/MiddlewareSpec";
-import * as Registry from "./Registry";
-import * as RegistryItems from "./RegistryItems";
+import * as Registry from "./Registry.js";
+import * as RegistryItems from "./RegistryItems.js";
 import * as Array from "effect/Array";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Data from "effect/Data";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Predicate from "effect/Predicate";
 import * as Ref from "effect/Ref";
-import type * as DatabaseSchema from "./DatabaseSchema";
-import type * as FunctionImpl from "./FunctionImpl";
-import type * as MiddlewareImpl from "./MiddlewareImpl";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import type * as FunctionImpl from "./FunctionImpl.js";
+import type * as MiddlewareImpl from "./MiddlewareImpl.js";
 
 export const TypeId = "~@confect/server/GroupImpl";
 export type TypeId = typeof TypeId;
@@ -111,10 +112,20 @@ export const make = <
     FunctionImpl.FromGroupSpec<Group> | MiddlewareImpl.FromGroupSpec<Group>
   >;
 
-const findUnfinalizedGroupImpl = <S>(
-  context: Context.Context<S>,
-): Option.Option<AnyUnfinalized> =>
-  Array.findFirst(context.mapUnsafe.values(), isUnfinalizedGroupImpl);
+const findGroupImpl = <S>(context: Context.Context<S>): Option.Option<Any> =>
+  Array.findFirst(context.mapUnsafe.values(), isGroupImpl);
+
+export class MissingRequiredMiddlewareError extends Data.TaggedError(
+  "MissingRequiredMiddlewareError",
+)<{
+  readonly missing: ReadonlyArray<RegistryItems.MissingMiddleware>;
+}> {
+  override get message(): string {
+    return `GroupImpl.finalize: ${this.missing.map(({ functionName, middlewareKey }) => `${functionName} requires middleware "${middlewareKey}"`).join("\n")}`;
+  }
+}
+
+type Finalizable = Layer.Layer<AnyUnfinalized> | Layer.Layer<AnyFinalized>;
 
 /**
  * Mark a `GroupImpl` layer as fully implemented. The parameter type defaults
@@ -127,20 +138,52 @@ const findUnfinalizedGroupImpl = <S>(
  * registered into this group's scope are snapshotted onto the produced service
  * value's `registeredFunctionNames` field, so consumers can verify impl
  * completeness against a `GroupSpec`'s expected functions without having to
- * inspect the `Registry` themselves.
+ * inspect the `Registry` themselves. Pass `{ required }` to check every
+ * registered function's middleware at layer build, including internal
+ * functions. This form also accepts a finalized layer so generated registration
+ * can enforce the backend declaration without changing authored impls. Pass
+ * `groupPath` to qualify uncovered function names in the diagnostic.
  */
-export const finalize = (
+export function finalize(options: {
+  readonly groupPath?: string;
+  readonly required: ReadonlyArray<
+    Pick<MiddlewareSpec.AnyMiddlewareSpec, "key">
+  >;
+}): (group: Finalizable) => Layer.Layer<GroupImpl<"Finalized">>;
+export function finalize(
   group: Layer.Layer<GroupImpl<"Unfinalized">>,
+): Layer.Layer<GroupImpl<"Finalized">>;
+export function finalize(
+  input:
+    | Finalizable
+    | {
+        readonly groupPath?: string;
+        readonly required: ReadonlyArray<
+          Pick<MiddlewareSpec.AnyMiddlewareSpec, "key">
+        >;
+      },
+):
+  | Layer.Layer<GroupImpl<"Finalized">>
+  | ((group: Finalizable) => Layer.Layer<GroupImpl<"Finalized">>) {
+  return "required" in input
+    ? (group) => finalizeWith(group, input.required, input.groupPath)
+    : finalizeWith(input, []);
+}
+
+const finalizeWith = (
+  group: Layer.Layer<never>,
+  required: ReadonlyArray<Pick<MiddlewareSpec.AnyMiddlewareSpec, "key">>,
+  groupPath = "",
 ): Layer.Layer<GroupImpl<"Finalized">> =>
   Layer.flatMap(group, (context): Layer.Layer<GroupImpl<"Finalized">> =>
-    findUnfinalizedGroupImpl(context).pipe(
+    findGroupImpl(context).pipe(
       Option.match({
         onNone: () =>
           Layer.effect(
             GroupImpl<"Finalized">({ finalizationStatus: "Finalized" }),
             Effect.die(
               new Error(
-                "GroupImpl.finalize: no Unfinalized GroupImpl service was found in the layer's context.",
+                "GroupImpl.finalize: no GroupImpl service was found in the layer's context.",
               ),
             ),
           ),
@@ -150,6 +193,16 @@ export const finalize = (
             Effect.gen(function* () {
               const registry = yield* Registry.Registry;
               const items = yield* Ref.get(registry);
+              const missing = RegistryItems.missingRequired(
+                items,
+                required,
+                groupPath,
+              );
+              if (missing.length > 0) {
+                return yield* Effect.die(
+                  new MissingRequiredMiddlewareError({ missing }),
+                );
+              }
               return {
                 [TypeId]: TypeId,
                 finalizationStatus: "Finalized" as const,

package/src/GroupRegistry.ts

@@ -1,17 +1,21 @@
+import * as RegisteredFunction from "./RegisteredFunction.js";
 import * as Effect from "effect/Effect";
 import type * as Layer from "effect/Layer";
 import * as Ref from "effect/Ref";
-import * as Registry from "./Registry";
-import type * as RegistryItems from "./RegistryItems";
-import type * as GroupImpl from "./GroupImpl";
-import * as MiddlewareRegistryItem from "./MiddlewareRegistryItem";
+import * as Registry from "./Registry.js";
+import type * as RegistryItems from "./RegistryItems.js";
+import type * as GroupImpl from "./GroupImpl.js";
+import * as MiddlewareRegistryItem from "./MiddlewareRegistryItem.js";
 
 export const make = (
   groupLayer: Layer.Layer<GroupImpl.GroupImpl<"Finalized">>,
 ) => {
-  const registryItems = Effect.gen(function* () {
+  const { registryItems, observability } = Effect.gen(function* () {
     const registry = yield* Registry.Registry;
-    return yield* Ref.get(registry);
+    return {
+      registryItems: yield* Ref.get(registry),
+      observability: yield* RegisteredFunction.Observability,
+    };
   }).pipe(
     Effect.provide(groupLayer),
     Effect.provideService(
@@ -21,7 +25,7 @@ export const make = (
     Effect.runSync,
   );
 
-  return partitionRegistryItems(registryItems);
+  return { ...partitionRegistryItems(registryItems), observability };
 };
 
 const partitionRegistryItems = (registryItems: RegistryItems.RegistryItems) => {

package/src/Handler.ts

@@ -1,30 +1,31 @@
+import type { ActionCall } from "@confect/core/ActionCall";
 import type { FunctionSpec, RuntimeAndFunctionType } from "@confect/core";
 import type * as FunctionProvenance from "@confect/core/FunctionProvenance";
 import type * as NodeServices from "@effect/platform-node/NodeServices";
 import type { Effect } from "effect";
-import type * as ActionCtx from "./ActionCtx";
-import type * as ActionRunner from "./ActionRunner";
-import type * as Auth from "./Auth";
-import type * as DatabaseReader from "./DatabaseReader";
-import type * as DatabaseSchema from "./DatabaseSchema";
-import type * as DatabaseWriter from "./DatabaseWriter";
-import type * as DataModel from "./DataModel";
-import type { ExecutionMetadata } from "./ExecutionMetadata";
-import type { RequestMetadata } from "./RequestMetadata";
-import type { TransactionMetadata } from "./TransactionMetadata";
-import type * as MutationCtx from "./MutationCtx";
-import type * as MutationRunner from "./MutationRunner";
-import type { MutationTransactionContext } from "./MutationTransactionContext";
-import type * as QueryCtx from "./QueryCtx";
-import type * as QueryRunner from "./QueryRunner";
-import type { QueryTransactionContext } from "./QueryTransactionContext";
-import type * as RegisteredFunction from "./RegisteredFunction";
-import type * as Scheduler from "./Scheduler";
-import type { Storage } from "./Storage";
-import type * as StorageActionWriter from "./StorageActionWriter";
-import type * as StorageReader from "./StorageReader";
-import type * as StorageWriter from "./StorageWriter";
-import type * as VectorSearch from "./VectorSearch";
+import type * as ActionCtx from "./ActionCtx.js";
+import type * as ActionRunner from "./ActionRunner.js";
+import type * as Auth from "./Auth.js";
+import type * as DatabaseReader from "./DatabaseReader.js";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import type * as DatabaseWriter from "./DatabaseWriter.js";
+import type * as DataModel from "./DataModel.js";
+import type { ExecutionMetadata } from "./ExecutionMetadata.js";
+import type { RequestMetadata } from "./RequestMetadata.js";
+import type { TransactionMetadata } from "./TransactionMetadata.js";
+import type * as MutationCtx from "./MutationCtx.js";
+import type * as MutationRunner from "./MutationRunner.js";
+import type { MutationTransactionContext } from "./MutationTransactionContext.js";
+import type * as QueryCtx from "./QueryCtx.js";
+import type * as QueryRunner from "./QueryRunner.js";
+import type { QueryTransactionContext } from "./QueryTransactionContext.js";
+import type * as RegisteredFunction from "./RegisteredFunction.js";
+import type * as Scheduler from "./Scheduler.js";
+import type { Storage } from "./Storage.js";
+import type * as StorageActionWriter from "./StorageActionWriter.js";
+import type * as StorageReader from "./StorageReader.js";
+import type * as StorageWriter from "./StorageWriter.js";
+import type * as VectorSearch from "./VectorSearch.js";
 
 export type Handler<
   DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
@@ -94,6 +95,7 @@ export type MutationServices<
 > =
   | DatabaseReader.DatabaseReader<DatabaseSchema_>
   | DatabaseWriter.DatabaseWriter<DatabaseSchema_>
+  | Auth.MutationAuth
   | (DatabaseSchema_["target"]["kind"] extends "component" ? never : Auth.Auth)
   | Scheduler.ForScope<DatabaseSchema.Scope<DatabaseSchema_>>
   | StorageReader.ForScope<DatabaseSchema.Scope<DatabaseSchema_>>
@@ -114,9 +116,7 @@ export type MutationServices<
 /**
  * Shared by both action runtimes.
  */
-export type ActionServices<
-  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
-> =
+type RawActionServices<DatabaseSchema_ extends DatabaseSchema.AnyWithProps> =
   | Scheduler.ForScope<DatabaseSchema.Scope<DatabaseSchema_>>
   | (DatabaseSchema_["target"]["kind"] extends "component" ? never : Auth.Auth)
   | StorageReader.ForScope<DatabaseSchema.Scope<DatabaseSchema_>>
@@ -134,6 +134,22 @@ export type ActionServices<
       DatabaseSchema.Scope<DatabaseSchema_>
     >;
 
+export type ActionServices<S extends DatabaseSchema.AnyWithProps, R = never> = [
+  Extract<R, ActionCall>,
+] extends [never]
+  ? RawActionServices<S>
+  : Exclude<
+      RawActionServices<S>,
+      | Scheduler.ForScope<DatabaseSchema.Scope<S>>
+      | QueryRunner.QueryRunner
+      | MutationRunner.MutationRunner
+      | ActionRunner.ActionRunner
+      | ActionCtx.ActionCtx<
+          DataModel.ToConvex<DataModel.FromSchema<S>>,
+          DatabaseSchema.Scope<S>
+        >
+    >;
+
 export type ConfectProvenanceQuery<
   DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
   FunctionSpec_ extends
@@ -153,7 +169,7 @@ export type ConvexRuntimeAction<
   FunctionSpec_ extends
     FunctionSpec.AnyWithPropsWithFunctionType<RuntimeAndFunctionType.AnyAction>,
   R = never,
-> = Base<FunctionSpec_, ActionServices<DatabaseSchema_> | R>;
+> = Base<FunctionSpec_, ActionServices<DatabaseSchema_, R> | R>;
 
 export type NodeRuntimeAction<
   DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
@@ -162,7 +178,7 @@ export type NodeRuntimeAction<
   R = never,
 > = Base<
   FunctionSpec_,
-  ActionServices<DatabaseSchema_> | NodeServices.NodeServices | R
+  ActionServices<DatabaseSchema_, R> | NodeServices.NodeServices | R
 >;
 
 type Base<FunctionSpec_ extends FunctionSpec.AnyWithProps, R> = (

package/src/HttpRouter.ts

@@ -24,24 +24,27 @@ import type * as HttpApiGroup from "effect/http-api/HttpApiGroup";
 import type * as Etag from "effect/http/Etag";
 import type * as HttpPlatform from "effect/http/HttpPlatform";
 import * as HttpRouter from "effect/http/HttpRouter";
+import * as HttpMiddleware from "effect/http/HttpMiddleware";
+import type * as HttpServerRequest from "effect/http/HttpServerRequest";
 import * as HttpServer from "effect/http/HttpServer";
-import type * as ActionRunner from "./ActionRunner";
-import type * as Auth from "./Auth";
-import type { ExecutionMetadata } from "./ExecutionMetadata";
-import type { RequestMetadata } from "./RequestMetadata";
-import type * as DatabaseSchema from "./DatabaseSchema";
-import type * as DataModel from "./DataModel";
-import type * as Handler from "./Handler";
-import * as ConvexConfigProvider from "./ConvexConfigProvider";
-import * as ConvexLogger from "./ConvexLogger";
-import type * as MutationRunner from "./MutationRunner";
-import type * as QueryRunner from "./QueryRunner";
-import * as RegisteredFunction from "./RegisteredFunction";
-import type * as Scheduler from "./Scheduler";
-import type { Storage } from "./Storage";
-import type { StorageActionWriter } from "./StorageActionWriter";
-import type { StorageReader } from "./StorageReader";
-import type { StorageWriter } from "./StorageWriter";
+import type * as ActionRunner from "./ActionRunner.js";
+import type * as Auth from "./Auth.js";
+import type { ExecutionMetadata } from "./ExecutionMetadata.js";
+import type { RequestMetadata } from "./RequestMetadata.js";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import type * as DataModel from "./DataModel.js";
+import type * as Handler from "./Handler.js";
+import * as ConvexConfigProvider from "./ConvexConfigProvider.js";
+import * as ObservabilityRuntime from "./internal/observability.js";
+import * as ConvexLogger from "./ConvexLogger.js";
+import type * as MutationRunner from "./MutationRunner.js";
+import type * as QueryRunner from "./QueryRunner.js";
+import * as RegisteredFunction from "./RegisteredFunction.js";
+import type * as Scheduler from "./Scheduler.js";
+import type { Storage } from "./Storage.js";
+import type { StorageActionWriter } from "./StorageActionWriter.js";
+import type { StorageReader } from "./StorageReader.js";
+import type { StorageWriter } from "./StorageWriter.js";
 
 /**
  * The Confect services available to HTTP route handlers and middleware,
@@ -116,9 +119,17 @@ export type Routes<Services_ = Services> = Layer.Layer<
  */
 export const make = <Id extends string, Groups extends HttpApiGroup.Constraint>(
   routes: Routes,
-  options?: { readonly api?: HttpApi.HttpApi<Id, Groups> | undefined },
+  options?: {
+    readonly observability?: Layer.Layer<never> | undefined;
+    readonly api?: HttpApi.HttpApi<Id, Groups> | undefined;
+  },
 ): ConvexHttpRouter =>
-  makeWithLayer(routes, RegisteredFunction.baseActionLayer, options?.api);
+  makeWithLayer(
+    routes,
+    RegisteredFunction.baseActionLayer,
+    options?.api,
+    options?.observability,
+  );
 
 /**
  * Derive HTTP capabilities and ID scopes from the generated database schema.
@@ -131,7 +142,10 @@ export const forSchema =
   ) =>
   <Id extends string, Groups extends HttpApiGroup.Constraint>(
     routes: Routes<Handler.ActionServices<DatabaseSchema_>>,
-    options?: { readonly api?: HttpApi.HttpApi<Id, Groups> | undefined },
+    options?: {
+      readonly observability?: Layer.Layer<never> | undefined;
+      readonly api?: HttpApi.HttpApi<Id, Groups> | undefined;
+    },
   ): ConvexHttpRouter =>
     makeWithLayer<
       Handler.ActionServices<DatabaseSchema_>,
@@ -148,6 +162,8 @@ export const forSchema =
       ),
       (ctx) => RegisteredFunction.actionLayer(schema, ctx),
       options?.api,
+      options?.observability,
+      schema.target.kind === "component",
     );
 
 // Convex uses a component-relative path to select its HTTP action but passes
@@ -175,15 +191,38 @@ const makeWithLayer = <
   routes: Routes<Services_>,
   layer: (ctx: GenericActionCtx<DataModel_>) => Layer.Layer<Services_>,
   api: HttpApi.HttpApi<Id, Groups> | undefined,
+  observability?: Layer.Layer<never>,
+  siteRelative = false,
 ): ConvexHttpRouter => {
   applyMonkeyPatches();
 
+  const spanName = Layer.effect(
+    HttpMiddleware.SpanNameGenerator,
+    Effect.gen(function* () {
+      const prefix = siteRelative
+        ? (yield* Config.schema(
+            Schema.URLFromString,
+            "CONVEX_SITE_URL",
+          )).pathname.replace(/\/$/, "")
+        : "";
+      return (request: HttpServerRequest.HttpServerRequest) =>
+        convexHttpRouter.lookup(
+          new URL(request.originalUrl).pathname.slice(prefix.length) || "/",
+          request.method as (typeof ROUTABLE_HTTP_METHODS)[number],
+        )?.[2] ?? "/*";
+    }).pipe(Effect.orDie),
+  );
+
   // Provided (not just merged) so that route layers' own construction—e.g.
   // a `Layer.unwrap` reading `Config`—resolves configuration through the
   // Convex-aware provider; merged so that request fibers—endpoint handlers
   // and middleware—do too.
   const AppLayer = routes.pipe(
-    Layer.provideMerge(ConvexLogger.layer),
+    Layer.provideMerge(
+      observability === undefined
+        ? ConvexLogger.layer
+        : Layer.merge(ObservabilityRuntime.memoized(observability), spanName),
+    ),
     Layer.provideMerge(ConvexConfigProvider.layer),
     Layer.provide(HttpServer.layerServices),
   );
@@ -193,6 +232,17 @@ const makeWithLayer = <
   // exposes as a per-request context argument.
   const { handler } = HttpRouter.toWebHandler(AppLayer, {
     disableLogger: true,
+    /* oxlint-disable effecttsgo/any-unknown-in-error-context -- Keep Effect's erased HTTP boundary errors intact. */
+    ...(observability === undefined
+      ? {}
+      : {
+          middleware: (effect) =>
+            Effect.andThen(
+              Effect.annotateCurrentSpan("kind", "httpAction"),
+              effect,
+            ),
+        }),
+    /* oxlint-enable effecttsgo/any-unknown-in-error-context */
   });
 
   const httpAction = httpActionGeneric((ctx, request): Promise<Response> => {

package/src/MiddlewareImpl.ts

@@ -1,28 +1,28 @@
 import type * as FunctionSpec from "@confect/core/FunctionSpec";
 import type * as GroupSpec from "@confect/core/GroupSpec";
 import * as MiddlewareSpec from "@confect/core/MiddlewareSpec";
-import * as Registry from "./Registry";
+import * as Registry from "./Registry.js";
 import type { FunctionType } from "convex/server";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Ref from "effect/Ref";
-import type * as Auth from "./Auth";
-import type * as DatabaseReader from "./DatabaseReader";
-import type * as DatabaseSchema from "./DatabaseSchema";
-import type * as Handler from "./Handler";
-import type { ExecutionMetadata } from "./ExecutionMetadata";
-import type { RequestMetadata } from "./RequestMetadata";
-import type { TransactionMetadata } from "./TransactionMetadata";
-import type * as MutationRunner from "./MutationRunner";
-import type * as QueryRunner from "./QueryRunner";
-import type { QueryTransactionContext } from "./QueryTransactionContext";
-import type * as Scheduler from "./Scheduler";
-import type { Storage } from "./Storage";
-import type * as StorageReader from "./StorageReader";
-import type * as StorageWriter from "./StorageWriter";
-import * as MiddlewareRegistryItem from "./MiddlewareRegistryItem";
-import { setNestedProperty } from "./internal/utils";
+import type * as Auth from "./Auth.js";
+import type * as DatabaseReader from "./DatabaseReader.js";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import type * as Handler from "./Handler.js";
+import type { ExecutionMetadata } from "./ExecutionMetadata.js";
+import type { RequestMetadata } from "./RequestMetadata.js";
+import type { TransactionMetadata } from "./TransactionMetadata.js";
+import type * as MutationRunner from "./MutationRunner.js";
+import type * as QueryRunner from "./QueryRunner.js";
+import type { QueryTransactionContext } from "./QueryTransactionContext.js";
+import type * as Scheduler from "./Scheduler.js";
+import type { Storage } from "./Storage.js";
+import type * as StorageReader from "./StorageReader.js";
+import type * as StorageWriter from "./StorageWriter.js";
+import * as MiddlewareRegistryItem from "./MiddlewareRegistryItem.js";
+import { setNestedProperty } from "./internal/utils.js";
 
 /**
  * Marker service produced by providing a middleware's implementation to a

package/src/MutationCtx.ts

@@ -1,7 +1,7 @@
 import type * as IdScope from "@confect/core/IdScope";
 import type { GenericDataModel, GenericMutationCtx } from "convex/server";
 import * as Context from "effect/Context";
-import type * as ComponentCtx from "./ComponentCtx";
+import type * as ComponentCtx from "./ComponentCtx.js";
 import * as Layer from "effect/Layer";
 
 export type MutationCtxTag<

package/src/MutationRunner.ts

@@ -4,7 +4,7 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import type * as Schema from "effect/Schema";
-import * as MutationTransactionContext from "./MutationTransactionContext";
+import * as MutationTransactionContext from "./MutationTransactionContext.js";
 
 export type Options = MutationTransactionContext.MutationOptions;
 

package/src/MutationTransactionContext.ts

@@ -7,10 +7,10 @@ import type {
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import type { Options as MutationOptions } from "./QueryTransactionContext";
+import type { Options as MutationOptions } from "./QueryTransactionContext.js";
 
 export type { TransactionLimits } from "convex/server";
-export type { Options as MutationOptions } from "./QueryTransactionContext";
+export type { Options as MutationOptions } from "./QueryTransactionContext.js";
 export type QueryOptions = AdvancedRunQueryOptions;
 
 const make = (

package/src/OfficialComponent.ts

@@ -0,0 +1,151 @@
+import * as Ref from "@confect/core/Ref";
+import type {
+  DefaultFunctionArgs,
+  GenericActionCtx,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+} from "convex/server";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as ActionCtx from "./ActionCtx.js";
+import type * as ActionRunner from "./ActionRunner.js";
+import * as MutationCtx from "./MutationCtx.js";
+import type * as MutationRunner from "./MutationRunner.js";
+import * as QueryCtx from "./QueryCtx.js";
+import type * as QueryRunner from "./QueryRunner.js";
+
+/**
+ * An official component's method rejected. `cause` is the rejection as thrown.
+ */
+export class ComponentCallFailed extends Schema.TaggedError<ComponentCallFailed>()(
+  "ComponentCallFailed",
+  { component: Schema.String, method: Schema.String, cause: Schema.Defect() },
+) {}
+
+declare const unsupported: unique symbol;
+type Unsupported = typeof unsupported;
+type Needs<Param> = [GenericActionCtx<GenericDataModel>] extends [Param]
+  ? [GenericMutationCtx<GenericDataModel>] extends [Param]
+    ? [GenericQueryCtx<GenericDataModel>] extends [Param]
+      ? QueryRunner.QueryRunner
+      : MutationRunner.MutationRunner
+    : [GenericQueryCtx<GenericDataModel>] extends [Param]
+      ? Unsupported
+      : ActionRunner.ActionRunner
+  : Unsupported;
+
+type Method<Official> = {
+  [K in keyof Official & string]: Official[K] extends (
+    ctx: infer Ctx,
+    ...args: infer _Args
+  ) => Promise<unknown>
+    ? Needs<Ctx> extends Unsupported
+      ? never
+      : K
+    : never;
+}[keyof Official & string];
+
+type Call<F> = F extends (
+  ctx: infer Ctx,
+  ...args: infer Args
+) => Promise<infer A>
+  ? (...args: Args) => Effect.Effect<A, never, Needs<Ctx>>
+  : never;
+
+type Lifted<Official> = <M extends Method<Official>>(
+  method: M,
+  ...args: Parameters<Call<Official[M]>>
+) => ReturnType<Call<Official[M]>>;
+
+/**
+ * Lift official promise methods, deriving each capability from its ctx
+ * parameter. A rejection is caller misuse, a limit or a platform fault rather
+ * than a domain fact, so it dies.
+ */
+export const make = <Official extends object>(
+  component: string,
+  official: Official,
+): Lifted<Official> => {
+  const context = Effect.gen(function* () {
+    const action = yield* Effect.serviceOption(
+      ActionCtx.ActionCtx<GenericDataModel>(),
+    );
+    if (Option.isSome(action)) return action.value;
+    const mutation = yield* Effect.serviceOption(
+      MutationCtx.MutationCtx<GenericDataModel>(),
+    );
+    if (Option.isSome(mutation)) return mutation.value;
+    const query = yield* Effect.serviceOption(
+      QueryCtx.QueryCtx<GenericDataModel>(),
+    );
+    if (Option.isSome(query)) return query.value;
+    return yield* Effect.die(
+      new Error(`${component} called outside a Confect handler`),
+    );
+  });
+  const call = Effect.fn(`${component}.call`)(function* (
+    method: Method<Official>,
+    ...args: unknown[]
+  ) {
+    const ctx = yield* context;
+    // Method selects promise methods whose first argument accepts a native handler context.
+    const invoke = official[method] as (
+      native: typeof ctx,
+      ...args: unknown[]
+    ) => Promise<unknown>;
+    return yield* Effect.tryPromise({
+      try: () => invoke.call(official, ctx, ...args),
+      catch: (cause) => ComponentCallFailed.make({ component, method, cause }),
+    }).pipe(Effect.orDie);
+  });
+  // Confect installs the native ctx with the runner capability inferred by Needs.
+  return call as unknown as Lifted<Official>;
+};
+
+/**
+ * A function reference with its encoded arguments, ready for an official method
+ * that takes both.
+ */
+export interface Fn<R extends Ref.Any> {
+  readonly reference: Ref.FunctionReference<R>;
+  readonly args: DefaultFunctionArgs;
+}
+
+/**
+ * Encode a ref's arguments through its codecs to the wire record an official
+ * method expects.
+ */
+export const encodeCall = <R extends Ref.Any>(
+  ref: R,
+  args: NoInfer<Ref.Args<R>>,
+): Effect.Effect<Fn<R>> =>
+  Ref.encodeArgs(ref, args).pipe(
+    Effect.flatMap(
+      Schema.decodeUnknownEffect(Schema.Record(Schema.String, Schema.Unknown)),
+    ),
+    Effect.map((encoded) => ({
+      reference: Ref.getFunctionReference(ref),
+      args: encoded,
+    })),
+    Effect.orDie,
+  );
+
+/**
+ * Encode a callback's real field without fabricating the rest of its arguments.
+ */
+export const encodeField = <
+  R extends Ref.AnyConfect,
+  K extends keyof Ref.Args<R> & keyof Ref.ArgsFields<R>,
+>(
+  ref: R,
+  key: K,
+  value: NoInfer<Ref.Args<R>[K]>,
+): Effect.Effect<unknown> => {
+  const fields = ref.args.fields as Record<
+    keyof Ref.ArgsFields<R>,
+    Schema.Codec<unknown, unknown>
+  >;
+  return Schema.encodeUnknownEffect(fields[key])(value).pipe(Effect.orDie);
+};

package/src/OrderedQuery.ts

@@ -10,10 +10,10 @@ import { identity, pipe } from "effect/Function";
 import type { Option } from "effect";
 import * as Effect from "effect/Effect";
 import * as Stream from "effect/Stream";
-import type * as DatabaseSchema from "./DatabaseSchema";
-import * as Document from "./Document";
-import type * as TableInfo from "./TableInfo";
-import type * as Table from "./Table";
+import type * as DatabaseSchema from "./DatabaseSchema.js";
+import * as Document from "./Document.js";
+import type * as TableInfo from "./TableInfo.js";
+import type * as Table from "./Table.js";
 
 type NativePaginate<TableInfo_ extends TableInfo.AnyWithProps, Doc> = (
   options: PaginationOptions,