@gaganref/confect-server 0.0.0-stage → 10.3.1-fork.1

package/src/RegisteredFunction.ts

@@ -0,0 +1,391 @@
+import type { FunctionSpec, RuntimeAndFunctionType } from "@confect/core";
+import * as IdScope from "@confect/core/IdScope";
+import type * as FunctionProvenance from "@confect/core/FunctionProvenance";
+import * as MiddlewareSpec from "@confect/core/MiddlewareSpec";
+import {
+  compileArgsSchema,
+  compileReturnsSchema,
+} from "@confect/core/SchemaToValidator";
+import {
+  type DefaultFunctionArgs,
+  type FunctionVisibility,
+  type GenericActionCtx,
+  type GenericDataModel,
+  type StorageReader as ConvexStorageReader,
+  type RegisteredAction,
+  type RegisteredMutation,
+  type RegisteredQuery,
+} from "convex/server";
+import type { Value } from "convex/values";
+import { ConvexError } from "convex/values";
+import { pipe } from "effect/Function";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+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";
+
+export type Any =
+  | RegisteredQuery<FunctionVisibility, DefaultFunctionArgs, any>
+  | RegisteredMutation<FunctionVisibility, DefaultFunctionArgs, any>
+  | RegisteredAction<FunctionVisibility, DefaultFunctionArgs, any>;
+
+type ConfectRegisteredFunction<
+  FunctionSpec_ extends FunctionSpec.AnyWithProps,
+> =
+  FunctionSpec.EncodedArgs<FunctionSpec_> extends infer Args_ extends
+    DefaultFunctionArgs
+    ? RuntimeAndFunctionType.GetFunctionType<
+        FunctionSpec_["runtimeAndFunctionType"]
+      > extends "query"
+      ? RegisteredQuery<
+          FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
+          Args_,
+          Promise<FunctionSpec.EncodedReturns<FunctionSpec_>>
+        >
+      : RuntimeAndFunctionType.GetFunctionType<
+            FunctionSpec_["runtimeAndFunctionType"]
+          > extends "mutation"
+        ? RegisteredMutation<
+            FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
+            Args_,
+            Promise<FunctionSpec.EncodedReturns<FunctionSpec_>>
+          >
+        : RuntimeAndFunctionType.GetFunctionType<
+              FunctionSpec_["runtimeAndFunctionType"]
+            > extends "action"
+          ? RegisteredAction<
+              FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
+              Args_,
+              Promise<FunctionSpec.EncodedReturns<FunctionSpec_>>
+            >
+          : never
+    : never;
+
+export type ConvexRegisteredFunction<
+  FunctionSpec_ extends FunctionSpec.AnyWithProps,
+> = FunctionSpec_ extends FunctionSpec.AnyWithProps
+  ? FunctionSpec.GetFunctionProvenance<FunctionSpec_> extends FunctionProvenance.Convex<
+      infer Args_ extends DefaultFunctionArgs,
+      infer Returns_
+    >
+    ? RuntimeAndFunctionType.GetFunctionType<
+        FunctionSpec_["runtimeAndFunctionType"]
+      > extends "query"
+      ? RegisteredQuery<
+          FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
+          Args_,
+          Returns_
+        >
+      : RuntimeAndFunctionType.GetFunctionType<
+            FunctionSpec_["runtimeAndFunctionType"]
+          > extends "mutation"
+        ? RegisteredMutation<
+            FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
+            Args_,
+            Returns_
+          >
+        : RuntimeAndFunctionType.GetFunctionType<
+              FunctionSpec_["runtimeAndFunctionType"]
+            > extends "action"
+          ? RegisteredAction<
+              FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
+              Args_,
+              Returns_
+            >
+          : never
+    : never
+  : never;
+
+export type RegisteredFunction<
+  FunctionSpec_ extends FunctionSpec.AnyWithProps,
+> =
+  FunctionSpec_ extends FunctionSpec.WithFunctionProvenance<
+    FunctionSpec_,
+    FunctionProvenance.AnyConvex
+  >
+    ? ConvexRegisteredFunction<FunctionSpec_>
+    : FunctionSpec_ extends FunctionSpec.WithFunctionProvenance<
+          FunctionSpec_,
+          FunctionProvenance.AnyConfect
+        >
+      ? ConfectRegisteredFunction<FunctionSpec_>
+      : never;
+
+/**
+ * Wrap a function's handler effect in its resolved middleware chain, per
+ * invocation, after args decode. Iterated innermost-first so that the
+ * first-attached (group-level, in attachment order) middleware ends up
+ * outermost and runs first. Erased types: the public safety story lives at the
+ * `MiddlewareSpec.MiddlewareImpl`/`MiddlewareImpl.make` signatures, and the
+ * composed effect's error channel is re-accounted by
+ * {@link combineErrorSchemas}.
+ */
+export const applyMiddleware = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>,
+  invocation: MiddlewareSpec.MiddlewareOptions["invocation"],
+): Effect.Effect<A, any, R> => {
+  return resolvedMiddlewares.reduceRight<Effect.Effect<any, any, any>>(
+    // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context -- The erased middleware error remains intact so runHandlerPromise can validate it against the combined error schema.
+    (wrapped, middleware) => {
+      const context =
+        "options" in middleware.middlewareSpec
+          ? { options: middleware.options, invocation }
+          : { invocation };
+      // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context -- Resolved middleware is type-erased after its public implementation boundary; its error and service channels are restored by the surrounding function contract.
+      return middleware.middlewareImpl(wrapped, context);
+    },
+    effect,
+  );
+};
+
+/**
+ * The error-schema allowlist for a function with middleware: the function's own
+ * declared `error` schema unioned with every covering middleware's error
+ * schema. `undefined` (⇒ every failure dies) only when neither declares
+ * one—mirroring the ref-side union clients decode against.
+ */
+export const combineErrorSchemas = (
+  error: Schema.Codec<any, any> | undefined,
+  resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>,
+): Schema.Codec<any, any> | undefined => {
+  const schemas = [
+    ...(error !== undefined ? [error] : []),
+    ...MiddlewareSpec.errorSchemas(
+      resolvedMiddlewares.map(({ middlewareSpec }) => middlewareSpec),
+    ),
+  ];
+  return schemas.length === 0
+    ? undefined
+    : schemas.length === 1
+      ? schemas[0]
+      : Schema.Union(schemas);
+};
+
+/**
+ * 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`:
+ *
+ * - 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.
+ *
+ * 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 `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.
+ */
+export const runHandlerPromise =
+  (
+    errorSchema: Schema.Codec<any, any> | undefined,
+    runOptions?: {
+      readonly scheduler?: EffectScheduler.Scheduler | 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 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)),
+                ),
+              ),
+            ),
+          );
+    return Effect.runPromise(
+      Effect.result(rethrowConvexErrorDefects(withConvexError)).pipe(
+        Effect.provide(ConvexLogger.layer),
+        Effect.provideService(Console.Console, globalThis.console),
+      ),
+      runOptions,
+    ).then(
+      Result.match({
+        onFailure: (error) => {
+          throw error;
+        },
+        onSuccess: (value) => value,
+      }),
+    );
+  };
+
+export const actionFunctionBase = <
+  Schema extends DatabaseSchema.AnyWithProps,
+  Args,
+  ConvexArgs extends DefaultFunctionArgs,
+  Returns,
+  ConvexReturns,
+  E,
+  R,
+>({
+  name,
+  functionVisibility,
+  args,
+  returns,
+  error,
+  handler,
+  resolvedMiddlewares = [],
+  createLayer,
+  scope = IdScope.app,
+}: {
+  name: string;
+  functionVisibility: FunctionVisibility;
+  args: Schema.Codec<Args, ConvexArgs>;
+  returns: Schema.Codec<Returns, ConvexReturns>;
+  error: Schema.Codec<Error, Value> | undefined;
+  handler: (a: Args) => Effect.Effect<Returns, E, R>;
+  resolvedMiddlewares?: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+  createLayer: (
+    ctx: GenericActionCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
+  ) => Layer.Layer<R>;
+  scope?: IdScope.IdScope;
+}) => ({
+  args: compileArgsSchema(args, scope),
+  returns: compileReturnsSchema(returns, scope),
+  handler: (
+    ctx: GenericActionCtx<DataModel.ToConvex<DataModel.FromSchema<Schema>>>,
+    actualArgs: ConvexArgs,
+  ): Promise<ConvexReturns> =>
+    Effect.gen(function* () {
+      const decodedArgs = yield* pipe(
+        actualArgs,
+        Schema.decodeUnknownEffect(args),
+        Effect.catchTag("SchemaError", Effect.die),
+      );
+      // 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),
+        resolvedMiddlewares,
+        {
+          name,
+          functionType: "action",
+          functionVisibility,
+          args: decodedArgs,
+        },
+      ).pipe(Effect.provide(createLayer(ctx)));
+      return yield* pipe(
+        decodedReturns,
+        Schema.encodeEffect(returns),
+        Effect.catchTag("SchemaError", Effect.die),
+      );
+    }).pipe(runHandlerPromise(combineErrorSchemas(error, resolvedMiddlewares))),
+});
+
+export type ActionServices<
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+> = Handler.ActionServices<DatabaseSchema_>;
+
+/**
+ * The ctx-backed action services that don't depend on a Confect database
+ * schema. {@link actionLayer} adds the schema-typed `VectorSearch` on top; the
+ * HTTP API handler uses this base directly.
+ */
+export const baseActionLayer = <ConvexDataModel extends GenericDataModel>(
+  ctx: GenericActionCtx<ConvexDataModel>,
+) =>
+  Layer.mergeAll(
+    Scheduler.layer(ctx.scheduler),
+    Auth.layer(ctx.auth),
+    ExecutionMetadata.layer(ctx.meta),
+    RequestMetadata.layer(ctx.meta),
+    Storage.layer(ctx.storage),
+    StorageWriter.StorageWriter.layer(ctx.storage),
+    StorageActionWriter.StorageActionWriter.layer(ctx.storage),
+    QueryRunner.layer(ctx.runQuery.bind(ctx)),
+    MutationRunner.layer(ctx.runMutation.bind(ctx)),
+    ActionRunner.layer(ctx.runAction.bind(ctx)),
+    Layer.succeed(ActionCtx.ActionCtx<ConvexDataModel>(), ctx),
+  );
+
+export const actionLayer = <
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+>(
+  databaseSchema: DatabaseSchema_,
+  ctx: GenericActionCtx<
+    DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>
+  >,
+) =>
+  Layer.mergeAll(
+    Scheduler.layer<DatabaseSchema.Scope<DatabaseSchema_>>(
+      ctx.scheduler,
+      databaseSchema.target.scope,
+    ),
+    Auth.layerForTarget<DatabaseSchema_["target"]>(
+      databaseSchema.target,
+      ctx.auth,
+    ),
+    ExecutionMetadata.layer(ctx.meta),
+    RequestMetadata.layer(ctx.meta),
+    storageLayer<DatabaseSchema.Scope<DatabaseSchema_>>(ctx.storage),
+    StorageWriter.StorageWriter.layer<DatabaseSchema.Scope<DatabaseSchema_>>(
+      ctx.storage,
+      databaseSchema.target.scope,
+    ),
+    StorageActionWriter.StorageActionWriter.layer<
+      DatabaseSchema.Scope<DatabaseSchema_>
+    >(ctx.storage, databaseSchema.target.scope),
+    QueryRunner.layer(ctx.runQuery.bind(ctx)),
+    MutationRunner.layer(ctx.runMutation.bind(ctx)),
+    ActionRunner.layer(ctx.runAction.bind(ctx)),
+    ActionCtx.layer<
+      DataModel.ToConvex<DataModel.FromSchema<DatabaseSchema_>>,
+      DatabaseSchema.Scope<DatabaseSchema_>
+    >(ctx, databaseSchema.target.scope),
+    VectorSearch.layer(ctx.vectorSearch.bind(ctx)),
+  );
+
+// Scoped readers share the same runtime service and ID strings. Reuse the
+// reader supplied by Storage so both APIs keep the same reader instance.
+export const storageLayer = <Scope extends IdScope.IdScope>(
+  reader: ConvexStorageReader,
+): Layer.Layer<Storage.Storage | StorageReader.ForScope<Scope>> =>
+  Storage.layer(reader) as Layer.Layer<
+    Storage.Storage | StorageReader.ForScope<Scope>
+  >;

package/src/RegisteredFunctions.ts

@@ -0,0 +1,88 @@
+import * as ConvexFunctionDefinitions from "./ConvexFunctionDefinitions";
+import type * as FunctionSpec from "@confect/core/FunctionSpec";
+import type * as GroupSpec from "@confect/core/GroupSpec";
+import type * as Spec from "@confect/core/Spec";
+import type { Layer, Types } from "effect";
+import type * as DatabaseSchema from "./DatabaseSchema";
+import type * as GroupImpl from "./GroupImpl";
+import type * as RegisteredFunction from "./RegisteredFunction";
+
+export type RegisteredFunctions<Spec_ extends Spec.AnyWithProps> =
+  Types.Simplify<RegisteredFunctionsHelper<Spec.Groups<Spec_>>>;
+
+type RegisteredFunctionsHelper<Groups extends GroupSpec.AnyWithProps> = {
+  [GroupName in GroupSpec.Name<Groups>]: GroupSpec.WithName<
+    Groups,
+    GroupName
+  > extends infer Group extends GroupSpec.AnyWithProps
+    ? RegisteredFunctionsForGroupSpec<Group>
+    : never;
+};
+
+/**
+ * The `RegisteredFunction` record for a group's own declared functions.
+ */
+type RegisteredFunctionsOf<Group extends GroupSpec.AnyWithProps> = {
+  [
+    FunctionName in FunctionSpec.Name<GroupSpec.Functions<Group>>
+  ]: FunctionSpec.WithName<
+    GroupSpec.Functions<Group>,
+    FunctionName
+  > extends infer FunctionSpec_ extends FunctionSpec.AnyWithProps
+    ? RegisteredFunction.RegisteredFunction<FunctionSpec_>
+    : never;
+};
+
+/**
+ * The registered-functions record for a single group, derived from the group's
+ * own `GroupSpec`: its declared functions, plus any nested subgroups it carries
+ * directly. This is the node that `buildForGroup` returns—computed from the
+ * leaf `GroupSpec` itself rather than by navigating the project-wide assembled
+ * `Spec` to a dot-path, so the per-group registry's type depends only on its
+ * own leaf. For the filesystem layout a leaf `GroupSpec` carries no subgroups
+ * (subdirectory children are assembled separately into `_generated/spec.ts`),
+ * so this resolves to just the leaf's functions.
+ */
+export type RegisteredFunctionsForGroupSpec<
+  Group extends GroupSpec.AnyWithProps,
+> =
+  GroupSpec.Groups<Group> extends infer SubGroups extends GroupSpec.AnyWithProps
+    ? Types.Simplify<
+        RegisteredFunctionsHelper<SubGroups> & RegisteredFunctionsOf<Group>
+      >
+    : RegisteredFunctionsOf<Group>;
+
+export interface AnyWithProps {
+  readonly [key: string]: RegisteredFunction.Any | AnyWithProps;
+}
+
+/**
+ * Build the registered Convex functions for a single group from its finalized
+ * `GroupImpl` layer.
+ *
+ * The `groupLayer` parameter requires `GroupImpl<"Finalized">`, so impls that
+ * were never piped through `GroupImpl.finalize` (and impls with unmet
+ * `FunctionImpl` requirements, which cannot be finalized) are rejected at the
+ * codegen boundary, not just deep inside Convex at runtime.
+ *
+ * The group layer is built with a fresh, isolated `Registry` (rather than the
+ * globally-cached default `Context.Reference`), so each `FunctionImpl.make`
+ * registers under its flat, single-segment function-name key without colliding
+ * with any other group built in the same process—the built registry holds
+ * exactly this group's functions at the top level.
+ *
+ * Only the runtime `databaseSchema` value is needed at runtime (it is forwarded
+ * to isolate registration to build each function's ctx services); the group's
+ * `GroupSpec` is supplied purely as the `Group` type parameter to shape the
+ * returned record. Generated isolate modules instead prepare definitions with
+ * `ConvexFunctionDefinitions.buildForGroup` and add local forwarding handlers
+ * before shared registration. Node groups use
+ * `RegisteredNodeFunction.buildForGroup` from the Node entry.
+ */
+export const buildForGroup = <Group extends GroupSpec.AnyWithProps>(
+  databaseSchema: DatabaseSchema.AnyWithProps,
+  groupLayer: Layer.Layer<GroupImpl.GroupImpl<"Finalized">>,
+): RegisteredFunctionsForGroupSpec<Group> =>
+  ConvexFunctionDefinitions.register<Group>(
+    ConvexFunctionDefinitions.buildForGroup(databaseSchema, groupLayer),
+  );

package/src/RegisteredNodeFunction.ts

@@ -0,0 +1,120 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import {
+  actionGeneric,
+  type DefaultFunctionArgs,
+  type FunctionVisibility,
+  internalActionGeneric,
+} from "convex/server";
+import type { Effect } from "effect";
+import type { Schema } from "effect";
+import * as Layer from "effect/Layer";
+import * as Match from "effect/Match";
+import type * as DatabaseSchema from "./DatabaseSchema";
+import * as RegisteredFunction from "./RegisteredFunction";
+import * as FunctionRegistryItem from "./FunctionRegistryItem";
+import * as ResolvedMiddleware from "./ResolvedMiddleware";
+import * as GroupRegistry from "./GroupRegistry";
+import type * as GroupSpec from "@confect/core/GroupSpec";
+import type * as GroupImpl from "./GroupImpl";
+import type * as RegisteredFunctions from "./RegisteredFunctions";
+import { mapLeaves } from "./internal/utils";
+
+export const buildForGroup = <Group extends GroupSpec.AnyWithProps>(
+  databaseSchema: DatabaseSchema.AnyWithProps,
+  groupLayer: Layer.Layer<GroupImpl.GroupImpl<"Finalized">>,
+): RegisteredFunctions.RegisteredFunctionsForGroupSpec<Group> => {
+  const { functionRegistryItems, middlewareRegistryItems } =
+    GroupRegistry.make(groupLayer);
+  return mapLeaves<FunctionRegistryItem.AnyWithProps, RegisteredFunction.Any>(
+    functionRegistryItems as {
+      [key: string]: FunctionRegistryItem.AnyWithProps;
+    },
+    FunctionRegistryItem.isFunctionRegistryItem,
+    (item) =>
+      Match.value(item).pipe(
+        Match.tag("Convex", ({ handler }) => handler),
+        Match.tag("Confect", (confect) =>
+          make(
+            databaseSchema,
+            confect,
+            ResolvedMiddleware.resolve(confect, middlewareRegistryItems),
+          ),
+        ),
+        Match.exhaustive,
+      ),
+  ) as RegisteredFunctions.RegisteredFunctionsForGroupSpec<Group>;
+};
+
+export const make = (
+  databaseSchema: DatabaseSchema.AnyWithProps,
+  item: FunctionRegistryItem.ConfectFunctionRegistryItem,
+  resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware> = [],
+): RegisteredFunction.Any => {
+  const genericFunction = Match.value(item.functionVisibility).pipe(
+    Match.when("public", () => actionGeneric),
+    Match.when("internal", () => internalActionGeneric),
+    Match.exhaustive,
+  );
+
+  return genericFunction(
+    nodeActionFunction(databaseSchema, {
+      name: item.name,
+      functionVisibility: item.functionVisibility,
+      args: item.args,
+      returns: item.returns,
+      error: item.error,
+      handler: item.handler,
+      resolvedMiddlewares,
+    }),
+  );
+};
+
+const nodeActionFunction = <
+  DatabaseSchema_ extends DatabaseSchema.AnyWithProps,
+  Args,
+  ConvexArgs extends DefaultFunctionArgs,
+  Returns,
+  ConvexReturns,
+  E,
+>(
+  databaseSchema: DatabaseSchema_,
+  {
+    name,
+    functionVisibility,
+    args,
+    returns,
+    error,
+    handler,
+    resolvedMiddlewares,
+  }: {
+    name: string;
+    functionVisibility: FunctionVisibility;
+    args: Schema.Codec<Args, ConvexArgs>;
+    returns: Schema.Codec<Returns, ConvexReturns>;
+    error: Schema.Codec<any, any> | undefined;
+    handler: (
+      a: Args,
+    ) => Effect.Effect<
+      Returns,
+      E,
+      | RegisteredFunction.ActionServices<DatabaseSchema_>
+      | NodeServices.NodeServices
+    >;
+    resolvedMiddlewares: ReadonlyArray<ResolvedMiddleware.ResolvedMiddleware>;
+  },
+) =>
+  RegisteredFunction.actionFunctionBase({
+    scope: databaseSchema.target.scope,
+    name,
+    functionVisibility,
+    args,
+    returns,
+    error,
+    handler,
+    resolvedMiddlewares,
+    createLayer: (ctx) =>
+      Layer.mergeAll(
+        RegisteredFunction.actionLayer(databaseSchema, ctx),
+        NodeServices.layer,
+      ),
+  });

package/src/Registry.ts

@@ -0,0 +1,17 @@
+import * as Context from "effect/Context";
+import * as Ref from "effect/Ref";
+import type { RegistryItems } from "./RegistryItems";
+
+/**
+ * Effect `Context.Reference` shared by everything that touches a group's
+ * registry—`FunctionImpl`/`MiddlewareImpl` initializers write to it,
+ * `RegisteredFunctions` reads it, and the CLI's impl validation inspects it—all
+ * through this one tag, without relying on Effect's global default-value cache
+ * to align separately-defined tags by string key.
+ */
+export const Registry = Context.Reference<Ref.Ref<RegistryItems>>(
+  "@confect/server/Registry",
+  {
+    defaultValue: () => Ref.makeUnsafe<RegistryItems>({}),
+  },
+);

package/src/RegistryItems.ts

@@ -0,0 +1,40 @@
+import * as Array from "effect/Array";
+import { pipe } from "effect/Function";
+import * as Record from "effect/Record";
+import * as FunctionRegistryItem from "./FunctionRegistryItem";
+import * as MiddlewareRegistryItem from "./MiddlewareRegistryItem";
+
+/**
+ * Runtime tree that mirrors a `Spec`'s group structure. Values remain unknown
+ * at this boundary so producers and consumers can narrow branches and registry
+ * items as needed.
+ */
+export interface RegistryItems {
+  readonly [key: string]: unknown;
+}
+
+/**
+ * The names of the function-shaped entries in a group's (flat, isolated)
+ * registry. `FunctionImpl.make` registers each function under a single-segment
+ * key, so the registry built for one group contains exactly that group's
+ * functions at the top level.
+ */
+export const functionNames = (items: RegistryItems): ReadonlyArray<string> =>
+  pipe(
+    Record.toEntries(items),
+    Array.filter(([, value]) =>
+      FunctionRegistryItem.isFunctionRegistryItem(value),
+    ),
+    Array.map(([name]) => name),
+  );
+
+/**
+ * The keys of the middleware implementations registered into a group's registry
+ * (stored under `middleware:<key>` entries by `MiddlewareImpl`).
+ */
+export const middlewareKeys = (items: RegistryItems): ReadonlyArray<string> =>
+  pipe(
+    Record.values(items),
+    Array.filter(MiddlewareRegistryItem.isMiddlewareRegistryItem),
+    Array.map((item) => item.middlewareSpec.key),
+  );

package/src/RequestMetadata.ts

@@ -0,0 +1,20 @@
+import type { MutationMeta } from "convex/server";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+export type { RequestMetadata as Metadata } from "convex/server";
+
+const make = (meta: Pick<MutationMeta, "getRequestMetadata">) => ({
+  get: Effect.fn("RequestMetadata.get")(() =>
+    Effect.promise(() => meta.getRequestMetadata()),
+  ),
+});
+
+export class RequestMetadata extends Context.Service<
+  RequestMetadata,
+  ReturnType<typeof make>
+>()("@confect/server/RequestMetadata") {}
+
+export const layer = (meta: Pick<MutationMeta, "getRequestMetadata">) =>
+  Layer.succeed(RequestMetadata, make(meta));