silgi 0.51.6 → 0.51.8

package/dist/core/handler.mjs

@@ -1,11 +1,9 @@
 import { routerCache } from "./router-utils.mjs";
-import { compileRouter, createContext, releaseContext } from "../compile.mjs";
+import { compileRouter, createContext, detachContext, releaseContext } from "../compile.mjs";
 import { applyContext } from "./dispatch.mjs";
 import { detectResponseFormat, encodeResponse, makeErrorResponse } from "./codec.mjs";
-import { runWithCtx } from "./context-bridge.mjs";
 import { parseInput } from "./input.mjs";
 import { iteratorToEventStream } from "./sse.mjs";
-import { analyticsTraceMap } from "./trace-map.mjs";
 import { parseUrlPath } from "./url.mjs";
 //#region src/core/handler.ts
 /**
@@ -46,20 +44,25 @@ function wrapStreamWithRelease(source, ctx) {
 		}
 	});
 }
+/**
+* Build the Response for a handler's output. The pooled `ctx` is released
+* by the caller's `using` scope; for streaming outputs we detach `ctx` first
+* so the stream becomes the sole owner (releases on stream end/cancel).
+*/
 function makeResponse(output, route, format, ctx) {
-	if (output instanceof Response) {
-		releaseContext(ctx);
-		return output;
+	if (output instanceof Response) return output;
+	if (output instanceof ReadableStream) {
+		detachContext(ctx);
+		return new Response(wrapStreamWithRelease(output, ctx), { headers: { "content-type": "application/octet-stream" } });
 	}
-	if (output instanceof ReadableStream) return new Response(wrapStreamWithRelease(output, ctx), { headers: { "content-type": "application/octet-stream" } });
 	if (output && typeof output === "object" && Symbol.asyncIterator in output) {
+		detachContext(ctx);
 		const stream = iteratorToEventStream(output);
 		return new Response(wrapStreamWithRelease(stream, ctx), { headers: {
 			"content-type": "text/event-stream",
 			"cache-control": "no-cache"
 		} });
 	}
-	releaseContext(ctx);
 	const cacheHeaders = route.cacheControl ? { "cache-control": route.cacheControl } : void 0;
 	if (format !== "json") return encodeResponse(output, 200, format, cacheHeaders);
 	return new Response(JSON.stringify(output), { headers: cacheHeaders ? {
@@ -81,12 +84,11 @@ function wrapHandler(handler, router, options, prefix) {
 		if (options.scalar) {
 			const { wrapWithScalar } = await import("../scalar.mjs");
 			const scalarOpts = typeof options.scalar === "object" ? options.scalar : {};
-			h = wrapWithScalar(h, router, scalarOpts, prefix);
+			h = wrapWithScalar(h, router, scalarOpts, prefix, options.schemaRegistry);
 		}
 		if (options.analytics) {
 			const { wrapWithAnalytics } = await import("../plugins/analytics.mjs");
-			const analyticsOpts = typeof options.analytics === "object" ? options.analytics : {};
-			h = wrapWithAnalytics(h, router, analyticsOpts);
+			h = wrapWithAnalytics(h, router, options.analytics, options.schemaRegistry, options.hooks);
 		}
 		wrapped = h;
 	}
@@ -96,7 +98,7 @@ function wrapHandler(handler, router, options, prefix) {
 		return initPromise.then(() => wrapped(request));
 	};
 }
-function createFetchHandler(routerDef, contextFactory, hooks, prefix) {
+function createFetchHandler(routerDef, contextFactory, hooks, prefix, bridge) {
 	let compiledRouter = routerCache.get(routerDef);
 	if (!compiledRouter) {
 		compiledRouter = compileRouter(routerDef);
@@ -116,6 +118,13 @@ function createFetchHandler(routerDef, contextFactory, hooks, prefix) {
 			if (result instanceof Promise) result.catch(() => {});
 		} catch {}
 	}
+	function awaitHook(name, event) {
+		if (!hooks) return;
+		try {
+			const result = hooks.callHook(name, event);
+			if (result instanceof Promise) return result.catch(() => {});
+		} catch {}
+	}
 	return async function handleRequest(request) {
 		const url = request.url;
 		let fullPath = parseUrlPath(url);
@@ -149,14 +158,17 @@ function createFetchHandler(routerDef, contextFactory, hooks, prefix) {
 			});
 		}
 		const format = detectResponseFormat(request);
-		const ctx = createContext();
+		using ctx = createContext();
 		let rawInput;
 		try {
 			const baseCtxResult = contextFactory(request);
 			applyContext(ctx, baseCtxResult instanceof Promise ? await baseCtxResult : baseCtxResult);
 			if (match.params) ctx.params = match.params;
-			const reqTrace = analyticsTraceMap.get(request);
-			if (reqTrace) ctx.__analyticsTrace = reqTrace;
+			const prepareResult = awaitHook("request:prepare", {
+				request,
+				ctx
+			});
+			if (prepareResult) await prepareResult;
 			if (!route.passthrough) rawInput = await parseInput(request, url, qMark);
 			if (match.params && Object.keys(match.params).length > 0) rawInput = rawInput != null && typeof rawInput === "object" ? {
 				...match.params,
@@ -166,17 +178,21 @@ function createFetchHandler(routerDef, contextFactory, hooks, prefix) {
 				path: pathname,
 				input: rawInput
 			});
-			const pipelineResult = runWithCtx(ctx, () => route.handler(ctx, rawInput, request.signal));
+			const pipelineResult = bridge ? bridge.run(ctx, () => route.handler(ctx, rawInput, request.signal)) : route.handler(ctx, rawInput, request.signal);
 			const output = pipelineResult instanceof Promise ? await pipelineResult : pipelineResult;
 			callHook("response", {
 				path: pathname,
 				output,
 				durationMs: 0
 			});
+			callHook("response:finalize", {
+				request,
+				ctx,
+				output
+			});
 			const response = makeResponse(output, route, format, ctx);
 			return response instanceof Promise ? await response : response;
 		} catch (error) {
-			releaseContext(ctx);
 			callHook("error", {
 				path: pathname,
 				error

package/dist/core/schema-converter.d.mts

@@ -0,0 +1,131 @@
+import { AnySchema } from "./schema.mjs";
+
+//#region src/core/schema-converter.d.ts
+/**
+ * JSON Schema subset used for OpenAPI / analytics output.
+ *
+ * @category Schema
+ */
+interface JSONSchema {
+  type?: string | string[];
+  format?: string;
+  properties?: Record<string, JSONSchema>;
+  required?: string[];
+  items?: JSONSchema;
+  anyOf?: JSONSchema[];
+  oneOf?: JSONSchema[];
+  allOf?: JSONSchema[];
+  enum?: unknown[];
+  const?: unknown;
+  description?: string;
+  title?: string;
+  default?: unknown;
+  [key: string]: unknown;
+}
+/**
+ * Options passed to a converter's `toJsonSchema` method.
+ *
+ * @category Schema
+ */
+interface ConvertOptions {
+  strategy: 'input' | 'output';
+}
+/**
+ * A converter that translates a specific Standard Schema vendor's schemas
+ * into JSON Schema. Pass instances via `silgi({ schemaConverters: [...] })`.
+ *
+ * @remarks
+ * Implement this interface to add OpenAPI / analytics support for a custom
+ * schema library. The `vendor` string must match the `~standard.vendor`
+ * property reported by the schema library's Standard Schema implementation.
+ *
+ * @example
+ * ```ts
+ * import type { SchemaConverter } from 'silgi'
+ *
+ * const myConverter: SchemaConverter = {
+ *   vendor: 'my-lib',
+ *   toJsonSchema(schema, opts) {
+ *     return { type: 'string' }
+ *   },
+ * }
+ * ```
+ *
+ * @category Schema
+ */
+interface SchemaConverter {
+  /** The Standard Schema `~standard.vendor` string this converter handles (e.g. `"zod"`). */
+  vendor: string;
+  /**
+   * Convert a schema to a JSON Schema object.
+   *
+   * @param schema - The schema to convert.
+   * @param opts - Conversion options including `strategy` (`'input'` | `'output'`).
+   * @returns A JSON Schema object. Return `{}` for unsupported/unknown schemas.
+   */
+  toJsonSchema(schema: AnySchema, opts: ConvertOptions): JSONSchema;
+}
+/**
+ * A per-instance registry mapping vendor strings to their converters.
+ *
+ * Built by {@link createSchemaRegistry} and threaded through the handler
+ * pipeline to scalar and analytics wrappers.
+ *
+ * @category Schema
+ */
+type SchemaRegistry = Map<string, SchemaConverter>;
+/**
+ * Build a {@link SchemaRegistry} from an array of converters.
+ *
+ * @param converters - Array of {@link SchemaConverter} objects, each
+ *   declaring their own `vendor`.
+ * @returns A `Map<string, SchemaConverter>` keyed by `converter.vendor`.
+ *
+ * @example
+ * ```ts
+ * import { zodConverter } from 'silgi/zod'
+ * import { createSchemaRegistry } from 'silgi'
+ *
+ * const registry = createSchemaRegistry([zodConverter])
+ * ```
+ *
+ * @category Schema
+ */
+declare function createSchemaRegistry(converters?: SchemaConverter[]): SchemaRegistry;
+/**
+ * Convert any Standard Schema to JSON Schema.
+ *
+ * @remarks
+ * Resolution order:
+ * 1. **Native fast path** — `schema['~standard'].jsonSchema.input()`
+ *    (Valibot, ArkType, Zod v4, …). No registry needed.
+ * 2. **Registry lookup** — finds a converter by
+ *    `schema['~standard'].vendor`. Registry must be passed explicitly;
+ *    there is no global mutable state.
+ * 3. **Empty schema `{}`** — emits a one-time `console.warn` per vendor
+ *    when a registry was provided but contained no matching converter.
+ *    No warn when no registry was passed (caller opted out).
+ *
+ * @param schema - Any Standard Schema compatible schema object.
+ * @param strategy - `'input'` (default) for pre-transform types; `'output'`
+ *   for post-transform.
+ * @param registry - Optional {@link SchemaRegistry} built from
+ *   {@link createSchemaRegistry}. When omitted the function still handles
+ *   schemas that expose the native `jsonSchema.input()` fast path.
+ * @returns A JSON Schema object. Returns `{}` when conversion is not possible.
+ *
+ * @example
+ * ```ts
+ * import { zodConverter } from 'silgi/zod'
+ * import { createSchemaRegistry, schemaToJsonSchema } from 'silgi'
+ * import { z } from 'zod'
+ *
+ * const registry = createSchemaRegistry([zodConverter])
+ * const json = schemaToJsonSchema(z.object({ name: z.string() }), 'input', registry)
+ * ```
+ *
+ * @category Schema
+ */
+declare function schemaToJsonSchema(schema: AnySchema, strategy?: 'input' | 'output', registry?: SchemaRegistry): JSONSchema;
+//#endregion
+export { ConvertOptions, JSONSchema, SchemaConverter, SchemaRegistry, createSchemaRegistry, schemaToJsonSchema };

package/dist/core/schema-converter.mjs

@@ -0,0 +1,82 @@
+//#region src/core/schema-converter.ts
+/**
+* Build a {@link SchemaRegistry} from an array of converters.
+*
+* @param converters - Array of {@link SchemaConverter} objects, each
+*   declaring their own `vendor`.
+* @returns A `Map<string, SchemaConverter>` keyed by `converter.vendor`.
+*
+* @example
+* ```ts
+* import { zodConverter } from 'silgi/zod'
+* import { createSchemaRegistry } from 'silgi'
+*
+* const registry = createSchemaRegistry([zodConverter])
+* ```
+*
+* @category Schema
+*/
+function createSchemaRegistry(converters = []) {
+	const map = /* @__PURE__ */ new Map();
+	for (const converter of converters) map.set(converter.vendor, converter);
+	return map;
+}
+const _warnedVendors = /* @__PURE__ */ new Set();
+/**
+* Convert any Standard Schema to JSON Schema.
+*
+* @remarks
+* Resolution order:
+* 1. **Native fast path** — `schema['~standard'].jsonSchema.input()`
+*    (Valibot, ArkType, Zod v4, …). No registry needed.
+* 2. **Registry lookup** — finds a converter by
+*    `schema['~standard'].vendor`. Registry must be passed explicitly;
+*    there is no global mutable state.
+* 3. **Empty schema `{}`** — emits a one-time `console.warn` per vendor
+*    when a registry was provided but contained no matching converter.
+*    No warn when no registry was passed (caller opted out).
+*
+* @param schema - Any Standard Schema compatible schema object.
+* @param strategy - `'input'` (default) for pre-transform types; `'output'`
+*   for post-transform.
+* @param registry - Optional {@link SchemaRegistry} built from
+*   {@link createSchemaRegistry}. When omitted the function still handles
+*   schemas that expose the native `jsonSchema.input()` fast path.
+* @returns A JSON Schema object. Returns `{}` when conversion is not possible.
+*
+* @example
+* ```ts
+* import { zodConverter } from 'silgi/zod'
+* import { createSchemaRegistry, schemaToJsonSchema } from 'silgi'
+* import { z } from 'zod'
+*
+* const registry = createSchemaRegistry([zodConverter])
+* const json = schemaToJsonSchema(z.object({ name: z.string() }), 'input', registry)
+* ```
+*
+* @category Schema
+*/
+function schemaToJsonSchema(schema, strategy = "input", registry) {
+	const std = schema?.["~standard"];
+	if (std?.jsonSchema?.input) try {
+		const result = std.jsonSchema.input({ target: "draft-2020-12" });
+		if (result && typeof result === "object") {
+			const { $schema: _, ...rest } = result;
+			return rest;
+		}
+	} catch {}
+	const vendor = typeof std?.vendor === "string" ? std.vendor : void 0;
+	if (vendor && registry) {
+		const converter = registry.get(vendor);
+		if (converter) try {
+			return converter.toJsonSchema(schema, { strategy });
+		} catch {}
+		else if (!_warnedVendors.has(vendor)) {
+			_warnedVendors.add(vendor);
+			console.warn(`[silgi] No schema converter registered for vendor "${vendor}". Pass schemaConverters: [${vendor}Converter] to silgi() to enable OpenAPI / analytics schema generation.`);
+		}
+	}
+	return {};
+}
+//#endregion
+export { createSchemaRegistry, schemaToJsonSchema };

package/dist/core/serve.d.mts

@@ -26,8 +26,8 @@ interface ServeOptions {
   hostname?: string;
   /** Enable Scalar API Reference UI at /api/reference and /api/openapi.json */
   scalar?: boolean | ScalarOptions;
-  /** Enable analytics dashboard at /api/analytics */
-  analytics?: boolean | AnalyticsOptions;
+  /** Enable analytics dashboard at /api/analytics — requires `auth` to be set */
+  analytics?: AnalyticsOptions;
   /**
    * WebSocket RPC configuration.
    *

package/dist/core/serve.mjs

@@ -14,11 +14,18 @@ function routerHasSubscription(def) {
 	for (const v of Object.values(def)) if (routerHasSubscription(v)) return true;
 	return false;
 }
-async function createServeHandler(routerDef, contextFactory, hooks, options) {
+async function createServeHandler(routerDef, contextFactory, hooks, options, schemaRegistry, bridge) {
 	const port = options?.port ?? 3e3;
 	const hostname = options?.hostname ?? "127.0.0.1";
 	const prefix = options?.basePath ? normalizePrefix(options.basePath) : void 0;
-	const httpHandler = wrapHandler(createFetchHandler(routerDef, contextFactory, hooks, prefix), routerDef, options, prefix);
+	const httpHandler = wrapHandler(createFetchHandler(routerDef, contextFactory, hooks, prefix, bridge), routerDef, options ? {
+		...options,
+		schemaRegistry,
+		hooks
+	} : {
+		schemaRegistry,
+		hooks
+	}, prefix);
 	const shutdownOpt = options?.gracefulShutdown ?? true;
 	let gracefulShutdown;
 	if (typeof shutdownOpt === "object") gracefulShutdown = {

package/dist/core/task.mjs

@@ -24,13 +24,13 @@ function createTaskFromProcedure(config, resolveFn, inputSchema, use, contextFac
 	const dispatch = async (rawInput, parentCtx) => {
 		const input = inputSchema ? await validateSchema(inputSchema, rawInput) : rawInput;
 		const ctx = contextFactory ? await contextFactory() : {};
-		const parentTrace = parentCtx?.__analyticsTrace;
+		const parentTrace = parentCtx?.trace;
 		const spanStart = parentTrace ? performance.now() : 0;
 		let reqTrace = null;
 		try {
 			const { RequestTrace } = await import("../plugins/analytics.mjs");
 			reqTrace = new RequestTrace();
-			ctx.__analyticsTrace = reqTrace;
+			ctx.trace = reqTrace;
 		} catch {}
 		const t0 = performance.now();
 		try {

package/dist/index.d.mts

@@ -1,12 +1,15 @@
 import { AnySchema, InferSchemaInput, InferSchemaOutput, Schema, ValidationError, type, validateSchema } from "./core/schema.mjs";
 import { ScheduledTaskInfo, TaskDef, TaskEvent, collectCronTasks, getScheduledTasks, runTask, setTaskAnalytics, startCronJobs, stopCronJobs } from "./core/task.mjs";
 import { ErrorDef, ErrorDefItem, FailFn, GuardDef, GuardFn, InferClient, InferContextFromUse, InferGuardOutput, Meta, MiddlewareDef, ProcedureDef, ProcedureType, ResolveContext, RouterDef, WrapDef, WrapFn } from "./types.mjs";
+import { ConvertOptions, JSONSchema, SchemaConverter, SchemaRegistry, createSchemaRegistry, schemaToJsonSchema } from "./core/schema-converter.mjs";
 import { ScalarOptions, generateOpenAPI, scalarHTML } from "./scalar.mjs";
 import { ProcedureBuilder, ProcedureBuilderWithOutput } from "./builder.mjs";
+import { ContextBridge, createContextBridge } from "./core/context-bridge.mjs";
 import { ServeOptions, SilgiServer } from "./core/serve.mjs";
 import { Driver, Storage, StorageConfig, StorageValue, initStorage, resetStorage, useStorage } from "./core/storage.mjs";
 import { SilgiConfig, SilgiInstance, silgi } from "./silgi.mjs";
-import { SilgiError, SilgiErrorCode, SilgiErrorJSON, SilgiErrorOptions, isDefinedError, toSilgiError } from "./core/error.mjs";
+import { SilgiError, SilgiErrorCode, SilgiErrorJSON, SilgiErrorOptions, isDefinedError, isSilgiError, toSilgiError } from "./core/error.mjs";
+import { BaseContext } from "./core/context.mjs";
 import { AsyncIteratorClass, mapAsyncIterator } from "./core/iterator.mjs";
 import { EventMeta, getEventMeta, withEventMeta } from "./core/sse.mjs";
 import { CallableOptions, callable } from "./callable.mjs";
@@ -14,4 +17,4 @@ import { LifecycleHooks, lifecycleWrap } from "./lifecycle.mjs";
 import { mapInput } from "./map-input.mjs";
 import { compileProcedure, compileRouter, createContext } from "./compile.mjs";
 import { LazyRouter, isLazy, lazy, resolveLazy } from "./lazy.mjs";
-export { type AnySchema, AsyncIteratorClass, type CallableOptions, type Driver, type ErrorDef, type ErrorDefItem, type EventMeta, type FailFn, type GuardDef, type GuardFn, type InferClient, type InferContextFromUse, type InferGuardOutput, type InferSchemaInput, type InferSchemaOutput, type LazyRouter, type LifecycleHooks, type Meta, type MiddlewareDef, type ProcedureBuilder, type ProcedureBuilderWithOutput, type ProcedureDef, type ProcedureType, type ResolveContext, type RouterDef, type ScalarOptions, type ScheduledTaskInfo, type Schema, type ServeOptions, type SilgiConfig, SilgiError, type SilgiErrorCode, type SilgiErrorJSON, type SilgiErrorOptions, type SilgiInstance, type SilgiServer, type Storage, type StorageConfig, type StorageValue, type TaskDef, type TaskEvent, ValidationError, type WrapDef, type WrapFn, callable, collectCronTasks, compileProcedure, compileRouter, createContext, generateOpenAPI, getEventMeta, getScheduledTasks, initStorage, isDefinedError, isLazy, lazy, lifecycleWrap, mapAsyncIterator, mapInput, resetStorage, resolveLazy, runTask, scalarHTML, setTaskAnalytics, silgi, startCronJobs, stopCronJobs, toSilgiError, type, useStorage, validateSchema, withEventMeta };
+export { type AnySchema, AsyncIteratorClass, type BaseContext, type CallableOptions, type ContextBridge, type ConvertOptions, type Driver, type ErrorDef, type ErrorDefItem, type EventMeta, type FailFn, type GuardDef, type GuardFn, type InferClient, type InferContextFromUse, type InferGuardOutput, type InferSchemaInput, type InferSchemaOutput, type JSONSchema, type LazyRouter, type LifecycleHooks, type Meta, type MiddlewareDef, type ProcedureBuilder, type ProcedureBuilderWithOutput, type ProcedureDef, type ProcedureType, type ResolveContext, type RouterDef, type ScalarOptions, type ScheduledTaskInfo, type Schema, type SchemaConverter, type SchemaRegistry, type ServeOptions, type SilgiConfig, SilgiError, type SilgiErrorCode, type SilgiErrorJSON, type SilgiErrorOptions, type SilgiInstance, type SilgiServer, type Storage, type StorageConfig, type StorageValue, type TaskDef, type TaskEvent, ValidationError, type WrapDef, type WrapFn, callable, collectCronTasks, compileProcedure, compileRouter, createContext, createContextBridge, createSchemaRegistry, generateOpenAPI, getEventMeta, getScheduledTasks, initStorage, isDefinedError, isLazy, isSilgiError, lazy, lifecycleWrap, mapAsyncIterator, mapInput, resetStorage, resolveLazy, runTask, scalarHTML, schemaToJsonSchema, setTaskAnalytics, silgi, startCronJobs, stopCronJobs, toSilgiError, type, useStorage, validateSchema, withEventMeta };

package/dist/index.mjs

@@ -1,9 +1,11 @@
 import { ValidationError, type, validateSchema } from "./core/schema.mjs";
 import { collectCronTasks, getScheduledTasks, runTask, setTaskAnalytics, startCronJobs, stopCronJobs } from "./core/task.mjs";
-import { SilgiError, isDefinedError, toSilgiError } from "./core/error.mjs";
+import { SilgiError, isDefinedError, isSilgiError, toSilgiError } from "./core/error.mjs";
 import { compileProcedure, compileRouter, createContext } from "./compile.mjs";
+import { createContextBridge } from "./core/context-bridge.mjs";
 import { AsyncIteratorClass, mapAsyncIterator } from "./core/iterator.mjs";
 import { getEventMeta, withEventMeta } from "./core/sse.mjs";
+import { createSchemaRegistry, schemaToJsonSchema } from "./core/schema-converter.mjs";
 import { silgi } from "./silgi.mjs";
 import { callable } from "./callable.mjs";
 import { lifecycleWrap } from "./lifecycle.mjs";
@@ -11,4 +13,4 @@ import { mapInput } from "./map-input.mjs";
 import { isLazy, lazy, resolveLazy } from "./lazy.mjs";
 import { initStorage, resetStorage, useStorage } from "./core/storage.mjs";
 import { generateOpenAPI, scalarHTML } from "./scalar.mjs";
-export { AsyncIteratorClass, SilgiError, ValidationError, callable, collectCronTasks, compileProcedure, compileRouter, createContext, generateOpenAPI, getEventMeta, getScheduledTasks, initStorage, isDefinedError, isLazy, lazy, lifecycleWrap, mapAsyncIterator, mapInput, resetStorage, resolveLazy, runTask, scalarHTML, setTaskAnalytics, silgi, startCronJobs, stopCronJobs, toSilgiError, type, useStorage, validateSchema, withEventMeta };
+export { AsyncIteratorClass, SilgiError, ValidationError, callable, collectCronTasks, compileProcedure, compileRouter, createContext, createContextBridge, createSchemaRegistry, generateOpenAPI, getEventMeta, getScheduledTasks, initStorage, isDefinedError, isLazy, isSilgiError, lazy, lifecycleWrap, mapAsyncIterator, mapInput, resetStorage, resolveLazy, runTask, scalarHTML, schemaToJsonSchema, setTaskAnalytics, silgi, startCronJobs, stopCronJobs, toSilgiError, type, useStorage, validateSchema, withEventMeta };

package/dist/integrations/better-auth/index.d.mts

@@ -1,4 +1,25 @@
 //#region src/integrations/better-auth/index.d.ts
+/**
+ * Associate a silgi context with a `Request` so the Better Auth tracing
+ * plugin can read it without mutating the `Request` object.
+ *
+ * @remarks
+ * Prefer this helper over the legacy `(request as any).__silgiCtx = ctx`
+ * assignment. The underlying storage is a module-level `WeakMap`, so
+ * entries are released automatically when the `Request` is GC'd.
+ *
+ * @param request - The `Request` currently being handled.
+ * @param ctx - The silgi context to associate, typically including `trace`.
+ *
+ * @example
+ * ```ts
+ * import { setRequestContext } from 'silgi/better-auth'
+ *
+ * setRequestContext(request, ctx)
+ * await auth.handler(request)
+ * ```
+ */
+declare function setRequestContext(request: Request, ctx: Record<string, unknown>): void;
 interface TracingConfig {
   /** Capture request body as span input (default: true) */
   captureInput?: boolean;
@@ -38,4 +59,4 @@ declare function instrumentBetterAuth<T extends Record<string, any>>(auth: T): T
  */
 declare function withCtx<T>(ctx: Record<string, unknown>, fn: () => T): T;
 //#endregion
-export { TracingConfig, instrumentBetterAuth, tracing, withCtx };
+export { TracingConfig, instrumentBetterAuth, setRequestContext, tracing, withCtx };

package/dist/integrations/better-auth/index.mjs

@@ -1,4 +1,4 @@
-import { getCtx, runWithCtx } from "../../core/context-bridge.mjs";
+import { createContextBridge } from "../../core/context-bridge.mjs";
 //#region src/integrations/better-auth/index.ts
 /**
 * Silgi + Better Auth tracing integration.
@@ -6,20 +6,88 @@ import { getCtx, runWithCtx } from "../../core/context-bridge.mjs";
 * Provides a Better Auth plugin factory that auto-traces all auth operations
 * (sign-in, sign-up, OAuth, session management, etc.) into silgi analytics.
 *
-* The silgi request context is passed via `request.__silgiCtx`, set by
-* the silgi auth handler before calling `auth.handler(request)`.
+* The silgi request context is associated with a `Request` in three ways,
+* tried in priority order:
+* 1. {@link setRequestContext}(request, ctx) — the blessed API (GC-friendly
+*    WeakMap, no mutation of the `Request` object).
+* 2. `(request as any).__silgiCtx = ctx` — legacy property assignment; kept
+*    working for existing users but `setRequestContext` is preferred.
+* 3. `silgi.runInContext(ctx, fn)` / `withCtx(ctx, fn)` — AsyncLocalStorage
+*    fallback when no Request is in scope (e.g., background jobs).
 *
 * @example
 * ```ts
-* import { tracing } from 'silgi/better-auth'
+* import { tracing, setRequestContext } from 'silgi/better-auth'
 *
 * const auth = betterAuth({
-*   plugins: [
-*     tracing(),  // auto-traces all auth operations
-*   ],
+*   plugins: [tracing()],
 * })
+*
+* // In your silgi handler:
+* setRequestContext(request, ctx)
+* await auth.handler(request)
 * ```
 */
+/**
+* Module-level compat bridge — backs the exported `withCtx()` helper so
+* tests and programmatic callers can still install an ambient context
+* without needing a silgi instance. The request path in `handler.ts`
+* uses `silgi.runInContext` on the per-instance bridge and never flows
+* through this one, so there is no inter-instance context collision.
+*
+* @internal
+*/
+const _compatBridge = createContextBridge();
+function getCtx() {
+	return _compatBridge.current();
+}
+function runWithCtx(ctx, fn) {
+	return _compatBridge.run(ctx, fn);
+}
+/**
+* Keyed on `Request` identity. GC-friendly: entry auto-released when the
+* `Request` is collected.
+*
+* @internal
+*/
+const _requestContextMap = /* @__PURE__ */ new WeakMap();
+/**
+* Associate a silgi context with a `Request` so the Better Auth tracing
+* plugin can read it without mutating the `Request` object.
+*
+* @remarks
+* Prefer this helper over the legacy `(request as any).__silgiCtx = ctx`
+* assignment. The underlying storage is a module-level `WeakMap`, so
+* entries are released automatically when the `Request` is GC'd.
+*
+* @param request - The `Request` currently being handled.
+* @param ctx - The silgi context to associate, typically including `trace`.
+*
+* @example
+* ```ts
+* import { setRequestContext } from 'silgi/better-auth'
+*
+* setRequestContext(request, ctx)
+* await auth.handler(request)
+* ```
+*/
+function setRequestContext(request, ctx) {
+	_requestContextMap.set(request, ctx);
+}
+/**
+* Internal resolver that tries, in order: WeakMap (new API), legacy
+* `__silgiCtx` property (deprecated but supported), and finally the
+* integration's compat bridge ALS.
+*
+* @internal
+*/
+function resolveRequestContext(request) {
+	const fromMap = _requestContextMap.get(request);
+	if (fromMap) return fromMap;
+	const legacy = request.__silgiCtx;
+	if (legacy && typeof legacy === "object") return legacy;
+	return getCtx();
+}
 function matchOperation(path) {
 	const normalized = path.replace(/^\/+/, "");
 	if (normalized.endsWith("/sign-up/email") || normalized === "sign-up/email") return {
@@ -151,9 +219,9 @@ function tracing(config) {
 				try {
 					const request = ctx.request;
 					if (!request) return;
-					const silgiCtx = request.__silgiCtx ?? getCtx();
+					const silgiCtx = resolveRequestContext(request);
 					if (!silgiCtx) return;
-					const reqTrace = silgiCtx.__analyticsTrace;
+					const reqTrace = silgiCtx.trace;
 					if (!reqTrace) return;
 					const meta = requestMetas.get(request);
 					requestMetas.delete(request);
@@ -284,7 +352,7 @@ function withCtx(ctx, fn) {
 }
 function wrapApiMethod(originalFn, operation, method) {
 	return async function instrumented(...args) {
-		const reqTrace = getCtx()?.__analyticsTrace;
+		const reqTrace = getCtx()?.trace;
 		if (!reqTrace) return originalFn.apply(this, args);
 		const spanName = `auth.api.${operation}`;
 		const start = performance.now();
@@ -328,4 +396,4 @@ function wrapApiMethod(originalFn, operation, method) {
 	};
 }
 //#endregion
-export { instrumentBetterAuth, tracing, withCtx };
+export { instrumentBetterAuth, setRequestContext, tracing, withCtx };

package/dist/integrations/drizzle/index.mjs

@@ -1,4 +1,4 @@
-import { getCtx, runWithCtx } from "../../core/context-bridge.mjs";
+import { createContextBridge } from "../../core/context-bridge.mjs";
 //#region src/integrations/drizzle/index.ts
 /**
 * Silgi + Drizzle ORM tracing integration.
@@ -31,6 +31,23 @@ import { getCtx, runWithCtx } from "../../core/context-bridge.mjs";
 * })
 * ```
 */
+/**
+* Module-level compat bridge — backs the exported `withCtx()` helper for
+* programmatic and test usage. Production request paths flow through
+* `silgi.runInContext()` via `src/core/handler.ts` and never touch this
+* bridge, so there is no cross-instance context bleed during normal
+* operation. The bridge exists only so `withCtx(ctx, fn)` works without
+* a silgi instance in scope.
+*
+* @internal
+*/
+const _compatBridge = createContextBridge();
+function getCtx() {
+	return _compatBridge.current();
+}
+function runWithCtx(ctx, fn) {
+	return _compatBridge.run(ctx, fn);
+}
 const INSTRUMENTED = "__silgiDrizzleInstrumented";
 const DEFAULT_DB_SYSTEM = "postgresql";
 const DEFAULT_MAX_QUERY_LENGTH = 1e3;
@@ -83,7 +100,7 @@ function patchSession(session, cfg, isTx) {
 		session.prepareQuery = function patchedPrepareQuery(...args) {
 			const prepared = originalPrepareQuery.apply(this, args);
 			if (!prepared || typeof prepared.execute !== "function") return prepared;
-			const reqTrace = getCtx()?.__analyticsTrace;
+			const reqTrace = getCtx()?.trace;
 			if (!reqTrace) return prepared;
 			const queryText = extractQueryText(args[0]) ?? prepared.rawQueryConfig?.text ?? prepared.queryConfig?.text ?? null;
 			const originalExecute = prepared.execute.bind(prepared);
@@ -97,7 +114,7 @@ function patchSession(session, cfg, isTx) {
 	if (typeof session.query === "function") {
 		const originalQuery = session.query.bind(session);
 		session.query = function patchedQuery(queryString, params) {
-			const reqTrace = getCtx()?.__analyticsTrace;
+			const reqTrace = getCtx()?.trace;
 			if (!reqTrace) return originalQuery.call(this, queryString, params);
 			return traceExecution(reqTrace, cfg, queryString ?? null, isTx, originalQuery, this, [queryString, params]);
 		};
@@ -126,7 +143,7 @@ function patchRawClient(client, cfg) {
 	if (!methodName) return false;
 	const originalMethod = client[methodName].bind(client);
 	client[methodName] = function patchedClientMethod(...args) {
-		const reqTrace = getCtx()?.__analyticsTrace;
+		const reqTrace = getCtx()?.trace;
 		if (!reqTrace) return originalMethod.apply(this, args);
 		return traceExecution(reqTrace, cfg, extractQueryText(args[0]) ?? null, false, originalMethod, this, args);
 	};
@@ -140,7 +157,7 @@ function patchSessionExecute(session, cfg) {
 	if (session[INSTRUMENTED]) return false;
 	const originalExecute = session.execute.bind(session);
 	session.execute = function patchedDeepExecute(...args) {
-		const reqTrace = getCtx()?.__analyticsTrace;
+		const reqTrace = getCtx()?.trace;
 		if (!reqTrace) return originalExecute.apply(this, args);
 		return traceExecution(reqTrace, cfg, extractQueryText(args[0]) ?? null, false, originalExecute, this, args);
 	};

package/dist/integrations/zod/converter.d.mts

@@ -72,4 +72,4 @@ declare class ZodSchemaConverter implements SchemaConverter {
   convert(schema: AnySchema, options: ConvertOptions): [boolean, JSONSchema];
 }
 //#endregion
-export { CompositeSchemaConverter, ConvertOptions, JSONSchema, SchemaConverter, ZodSchemaConverter };
+export { CompositeSchemaConverter, ConvertOptions, JSONSchema, ZodSchemaConverter };