refactor(policy): replace AsyncLocalStorage with explicit queryContext map

Eliminates the policyContextStorage AsyncLocalStorage by threading a
per-operation Map<string,unknown> through the onQuery/onKyselyQuery hook
chain instead. This removes the node:async_hooks dependency from the
policy plugin (and the orm package browser stub that worked around it),
letting the Next.js sample drop serverExternalPackages overrides.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Azzerty23

packages/orm/package.json

@@ -26,7 +26,6 @@
     ],
     "exports": {
         ".": {
-            "browser": "./dist/browser.mjs",
             "import": {
                 "types": "./dist/index.d.mts",
                 "default": "./dist/index.mjs"

packages/orm/src/browser.ts

@@ -611,6 +611,10 @@ function createModelCrudHandler(
         throwIfNoResult = false,
     ) => {
         return createZenStackPromise(async (txClient?: ClientContract<any>) => {
+            // Per-operation context shared between onQuery and onKyselyQuery hooks.
+            // onQuery plugins write here; the context executor passes it to onKyselyQuery.
+            const queryContext = new Map<string, unknown>();
+
             let proceed = async (_args: unknown) => {
                 // prepare args for ext result: strip ext result field names from select/omit,
                 // inject needs fields into select (recursively handles nested relations)
@@ -619,7 +623,16 @@ function createModelCrudHandler(
                     ? prepareArgsForExtResult(_args, model, schema, plugins)
                     : _args;
 
-                const _handler = txClient ? handler.withClient(txClient) : handler;
+                // Bind queryContext to the executor so onKyselyQuery hooks can read it.
+                // Uses txClient's executor (which holds the tx connection) when in a transaction.
+                const baseClient = txClient ?? client;
+                const baseExecutor = (baseClient.$qb as any).getExecutor() as ZenStackQueryExecutor;
+                const contextExecutor = baseExecutor.withQueryContext(queryContext);
+                const contextClient = (baseClient as unknown as ClientImpl).withExecutor(
+                    contextExecutor,
+                ) as unknown as ClientContract<any>;
+
+                const _handler = handler.withClient(contextClient);
                 const r = await _handler.handle(operation, processedArgs);
                 if (!r && throwIfNoResult) {
                     throw createNotFoundError(model);
@@ -652,6 +665,7 @@ function createModelCrudHandler(
                             operation: nominalOperation,
                             // reflect the latest override if provided
                             args: _args,
+                            queryContext,
                             // ensure inner overrides are propagated to the previous proceed
                             proceed: (nextArgs: unknown) => _proceed(nextArgs),
                         };

packages/orm/src/client/client-impl.ts

@@ -86,6 +86,7 @@ export class ZenStackQueryExecutor extends DefaultQueryExecutor {
         private readonly connectionProvider: ConnectionProvider,
         plugins: KyselyPlugin[] = [],
         private suppressMutationHooks: boolean = false,
+        private readonly queryContext: Map<string, unknown> = new Map(),
     ) {
         super(compiler, adapter, connectionProvider, plugins);
 
@@ -214,6 +215,7 @@ export class ZenStackQueryExecutor extends DefaultQueryExecutor {
                     schema: this.client.$schema,
                     query,
                     proceed: _p,
+                    queryContext: this.queryContext,
                 });
                 return hookResult;
             };
@@ -777,6 +779,7 @@ In such cases, ZenStack cannot reliably determine the IDs of the mutated entitie
             this.connectionProvider,
             [...this.plugins, plugin],
             this.suppressMutationHooks,
+            this.queryContext,
         );
     }
 
@@ -789,6 +792,7 @@ In such cases, ZenStack cannot reliably determine the IDs of the mutated entitie
             this.connectionProvider,
             [...this.plugins, ...plugins],
             this.suppressMutationHooks,
+            this.queryContext,
         );
     }
 
@@ -801,6 +805,7 @@ In such cases, ZenStack cannot reliably determine the IDs of the mutated entitie
             this.connectionProvider,
             [plugin, ...this.plugins],
             this.suppressMutationHooks,
+            this.queryContext,
         );
     }
 
@@ -813,6 +818,7 @@ In such cases, ZenStack cannot reliably determine the IDs of the mutated entitie
             this.connectionProvider,
             [],
             this.suppressMutationHooks,
+            this.queryContext,
         );
     }
 
@@ -825,11 +831,33 @@ In such cases, ZenStack cannot reliably determine the IDs of the mutated entitie
             connectionProvider,
             this.plugins as KyselyPlugin[],
             this.suppressMutationHooks,
+            this.queryContext,
         );
         // replace client with a new one associated with the new executor
         newExecutor.client = this.client.withExecutor(newExecutor);
         return newExecutor;
     }
 
+    /**
+     * Create a new executor carrying the given per-operation query context.
+     * Called once per top-level ORM operation so that onQuery plugins can write
+     * values (e.g. `operation`, `fetchPolicyCodes`) that onKyselyQuery plugins read —
+     * without AsyncLocalStorage.
+     */
+    withQueryContext(queryContext: Map<string, unknown>): ZenStackQueryExecutor {
+        const newExecutor = new ZenStackQueryExecutor(
+            this.client,
+            this.driver,
+            this.compiler,
+            this.adapter,
+            this.connectionProvider,
+            this.plugins as KyselyPlugin[],
+            this.suppressMutationHooks,
+            queryContext,
+        );
+        newExecutor.client = this.client.withExecutor(newExecutor);
+        return newExecutor;
+    }
+
     // #endregion
 }

packages/orm/src/client/executor/zenstack-query-executor.ts

@@ -280,6 +280,13 @@ type OnQueryHookContext<Schema extends SchemaDef> = {
      * The ZenStack client that is performing the operation.
      */
     client: ClientContract<Schema>;
+
+    /**
+     * Per-operation mutable context shared between onQuery and onKyselyQuery hooks.
+     * Plugins may write values here in onQuery and read them in onKyselyQuery, avoiding
+     * the need for AsyncLocalStorage to bridge these two decoupled call sites.
+     */
+    queryContext: Map<string, unknown>;
 };
 
 // #endregion
@@ -390,6 +397,7 @@ export type OnKyselyQueryArgs<Schema extends SchemaDef> = {
     client: ClientContract<Schema>;
     query: RootOperationNode;
     proceed: ProceedKyselyQueryFunction;
+    queryContext: Map<string, unknown>;
 };
 
 export type ProceedKyselyQueryFunction = (query: RootOperationNode) => Promise<QueryResult<any>>;

packages/orm/src/client/plugin.ts

@@ -3,7 +3,6 @@ import { createConfig } from '@zenstackhq/tsdown-config';
 export default createConfig({
     entry: {
         index: 'src/index.ts',
-        browser: 'src/browser.ts',
         schema: 'src/schema.ts',
         helpers: 'src/helpers.ts',
         'common-types': 'src/common-types.ts',

packages/orm/tsdown.config.ts

@@ -1,7 +1,6 @@
 import { type OnKyselyQueryArgs, type RuntimePlugin } from '@zenstackhq/orm';
 import type { SchemaDef } from '@zenstackhq/orm/schema';
 import { z } from 'zod';
-import { policyContextStorage } from './context';
 import { check } from './functions';
 import type { PolicyPluginOptions } from './options';
 import { PolicyHandler } from './policy-handler';
@@ -45,27 +44,28 @@ export class PolicyPlugin implements RuntimePlugin<SchemaDef, PolicyExtQueryArgs
         $delete: fetchPolicyCodesSchema,
     };
 
-    // onQuery and onKyselyQuery are decoupled hook call sites with no shared argument path;
-    // AsyncLocalStorage bridges per-query context into the Kysely executor.
     onQuery(ctx: {
         operation: string;
         args: Record<string, unknown> | undefined;
         proceed: (args: Record<string, unknown> | undefined) => Promise<unknown>;
+        queryContext: Map<string, unknown>;
         [key: string]: unknown;
     }) {
-        return policyContextStorage.run(
-            { operation: ctx.operation, fetchPolicyCodes: ctx.args?.['fetchPolicyCodes'] as boolean | undefined },
-            () => ctx.proceed(ctx.args),
-        );
+        ctx.queryContext.set('policy:operation', ctx.operation);
+        const fetchPolicyCodes = ctx.args?.['fetchPolicyCodes'] as boolean | undefined;
+        if (fetchPolicyCodes !== undefined) {
+            ctx.queryContext.set('policy:fetchPolicyCodes', fetchPolicyCodes);
+        }
+        return ctx.proceed(ctx.args);
     }
 
-    onKyselyQuery({ query, client, proceed }: OnKyselyQueryArgs<SchemaDef>) {
-        const ctx = policyContextStorage.getStore();
+    onKyselyQuery({ query, client, proceed, queryContext }: OnKyselyQueryArgs<SchemaDef>) {
+        const fetchPolicyCodes = queryContext.get('policy:fetchPolicyCodes') as boolean | undefined;
         const effectiveOptions: PolicyPluginOptions =
-            ctx?.fetchPolicyCodes !== undefined
-                ? { ...this.options, fetchPolicyCodes: ctx.fetchPolicyCodes }
+            fetchPolicyCodes !== undefined
+                ? { ...this.options, fetchPolicyCodes }
                 : this.options;
-        const handler = new PolicyHandler<SchemaDef>(client, effectiveOptions);
+        const handler = new PolicyHandler<SchemaDef>(client, effectiveOptions, queryContext);
         return handler.handle(query, proceed);
     }
 }

packages/plugins/policy/src/context.ts

@@ -48,7 +48,6 @@ import {
 } from 'kysely';
 import { match } from 'ts-pattern';
 import { ColumnCollector } from './column-collector';
-import { policyContextStorage } from './context';
 import { ExpressionTransformer } from './expression-transformer';
 import type { PolicyPluginOptions } from './options';
 import type { Policy, PolicyOperation } from './types';
@@ -81,6 +80,7 @@ export class PolicyHandler<Schema extends SchemaDef> extends OperationNodeTransf
     constructor(
         private readonly client: ClientContract<Schema>,
         private readonly options: PolicyPluginOptions = {},
+        private readonly queryContext: Map<string, unknown> = new Map(),
     ) {
         super();
         this.dialect = getCrudDialect(this.client.$schema, this.client.$options);
@@ -107,7 +107,9 @@ export class PolicyHandler<Schema extends SchemaDef> extends OperationNodeTransf
             // When 0 rows returned on a throwing single-row read (findFirstOrThrow/findUniqueOrThrow), distinguish "not found" from policy denial
             if (
                 result.rows.length === 0 &&
-                SINGLE_ROW_OR_THROW_OPERATIONS.has(policyContextStorage.getStore()?.operation ?? '')
+                SINGLE_ROW_OR_THROW_OPERATIONS.has(
+                    (this.queryContext.get('policy:operation') as string | undefined) ?? '',
+                )
             ) {
                 await this.postReadZeroRowsCheck(selectNode, proceed);
             }