@zintrust/core 2.4.7 → 2.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "2.4.7",
+  "version": "2.4.8",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/src/cache/Cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../src/cache/Cache.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2QtD,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IACnD,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,WAAW,CAAC;CAC9B,CAAC,CAAC;AA0IH,eAAO,MAAM,KAAK;UAnTC,CAAC,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;WAsDjC,CAAC,QAAQ,MAAM,EAAE,KAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;UAM1C,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;kBAkBjD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iBAiBtB,OAAO,CAAC,IAAI,CAAC;eAgBb,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;qBAenB,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAapC,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAgB5C,WAAW;iCA6IG,MAAM,KAAG,OAAO;mBA3H9B,MAAM,KAAG,UAAU;iBAuHvB,IAAI;EA4BpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,KAAK;UArUC,CAAC,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;WAsDjC,CAAC,QAAQ,MAAM,EAAE,KAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;UAM1C,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;kBAkBjD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iBAiBtB,OAAO,CAAC,IAAI,CAAC;eAgBb,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;qBAenB,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAapC,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAgB5C,WAAW;iCA6IG,MAAM,KAAG,OAAO;mBA3H9B,MAAM,KAAG,UAAU;iBAuHvB,IAAI;EAiCI,CAAC"}
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../src/cache/Cache.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA6QtD,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IACnD,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,WAAW,CAAC;CAC9B,CAAC,CAAC;AA0IH,eAAO,MAAM,KAAK;UArTC,CAAC,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;WAwDjC,CAAC,QAAQ,MAAM,EAAE,KAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;UAM1C,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;kBAkBjD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iBAiBtB,OAAO,CAAC,IAAI,CAAC;eAgBb,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;qBAenB,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAapC,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAgB5C,WAAW;iCA6IG,MAAM,KAAG,OAAO;mBA3H9B,MAAM,KAAG,UAAU;iBAuHvB,IAAI;EA4BpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,KAAK;UAvUC,CAAC,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;WAwDjC,CAAC,QAAQ,MAAM,EAAE,KAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;UAM1C,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;kBAkBjD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iBAiBtB,OAAO,CAAC,IAAI,CAAC;eAgBb,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;qBAenB,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAapC,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAgB5C,WAAW;iCA6IG,MAAM,KAAG,OAAO;mBA3H9B,MAAM,KAAG,UAAU;iBAuHvB,IAAI;EAiCI,CAAC"}

package/src/cache/Cache.js

@@ -102,14 +102,14 @@ const runMany = async (driver, keys, storeName) => {
         return [];
     const prefixedKeys = keys.map((key) => autoPrefixKey(key));
     const startedAt = Date.now();
-    const many = driver.many;
+    const batchedMany = driver.many;
     let values;
-    const batched = typeof many === 'function';
+    const batched = typeof batchedMany === 'function';
     if (batched) {
-        values = await many(prefixedKeys);
+        values = await batchedMany(prefixedKeys);
     }
     else {
-        values = await Promise.all(prefixedKeys.map(async (prefixedKey) => driver.get(prefixedKey)));
+        values = (await Promise.all(prefixedKeys.map(async (prefixedKey) => driver.get(prefixedKey))));
     }
     const elapsed = Date.now() - startedAt;
     const normalized = prefixedKeys.map((_prefixedKey, index) => values[index] ?? null);

package/src/cli/d1/D1SqlMigrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"D1SqlMigrations.d.ts","sourceRoot":"","sources":["../../../../src/cli/d1/D1SqlMigrations.ts"],"names":[],"mappings":"AAYA,KAAK,6BAA6B,GAAG;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AA6OF,eAAO,MAAM,eAAe;0BACE,6BAA6B,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;EAmC5F,CAAC"}
+{"version":3,"file":"D1SqlMigrations.d.ts","sourceRoot":"","sources":["../../../../src/cli/d1/D1SqlMigrations.ts"],"names":[],"mappings":"AAYA,KAAK,6BAA6B,GAAG;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAmPF,eAAO,MAAM,eAAe;0BACE,6BAA6B,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;EAmC5F,CAAC"}

package/src/cli/d1/D1SqlMigrations.js

@@ -144,6 +144,10 @@ const createCaptureDb = (onSql) => {
             await RESOLVED_VOID;
             return callback(this);
         },
+        async withReadSession(fn) {
+            const result = await fn(this);
+            return { result, bookmark: null };
+        },
         table() {
             throw ErrorFactory.createCliError('D1 SQL compilation does not support QueryBuilder-based migrations yet. Use db.query(...) with explicit SQL.');
         },

package/src/config/features.d.ts

@@ -1,3 +1,4 @@
+import type { D1ReadConstraint } from '../orm/DatabaseAdapter';
 /**
  * Feature Flags - Controls access to advanced/experimental features
  * Sealed namespace for immutability
@@ -13,6 +14,16 @@ export declare const FeatureFlags: Readonly<{
      * Returns cached flag value (no environment lookup)
      */
     isRawQueryEnabled(): boolean;
+    /**
+     * Whether D1 read replication (Sessions API) is enabled. When off,
+     * `IDatabase.withReadSession` is a passthrough and reads hit the primary.
+     */
+    isD1ReadReplicationEnabled(): boolean;
+    /**
+     * Default session constraint applied by `withReadSession` when the caller
+     * does not specify one.
+     */
+    getD1ReadDefaultConstraint(): D1ReadConstraint;
     /**
      * Reset flags (primarily for testing)
      */
@@ -22,6 +33,14 @@ export declare const FeatureFlags: Readonly<{
      * Primarily for testing to avoid 'as any' type casting
      */
     setRawQueryEnabled(enabled: boolean): void;
+    /**
+     * Set D1 read replication enabled state (primarily for testing).
+     */
+    setD1ReadReplicationEnabled(enabled: boolean): void;
+    /**
+     * Set the default D1 read constraint (primarily for testing).
+     */
+    setD1ReadDefaultConstraint(constraint: D1ReadConstraint): void;
 }>;
 export default FeatureFlags;
 //# sourceMappingURL=features.d.ts.map

package/src/config/features.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../../src/config/features.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB;;;OAGG;kBACW,IAAI;IAclB;;;OAGG;yBACkB,OAAO;IAI5B;;OAEG;aACM,IAAI;IAIb;;;OAGG;gCACyB,OAAO,GAAG,IAAI;EAG1C,CAAC;AAEH,eAAe,YAAY,CAAC"}
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../../src/config/features.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAiB7D;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB;;;OAGG;kBACW,IAAI;IAyBlB;;;OAGG;yBACkB,OAAO;IAI5B;;;OAGG;kCAC2B,OAAO;IAIrC;;;OAGG;kCAC2B,gBAAgB;IAI9C;;OAEG;aACM,IAAI;IAMb;;;OAGG;gCACyB,OAAO,GAAG,IAAI;IAI1C;;OAEG;yCACkC,OAAO,GAAG,IAAI;IAInD;;OAEG;2CACoC,gBAAgB,GAAG,IAAI;EAG9D,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/src/config/features.js

@@ -5,6 +5,13 @@ import { Logger } from './logger.js';
  * Internal state managed by the module
  */
 let _rawQueryEnabled = false;
+const D1_READ_DEFAULT_CONSTRAINT = 'first-unconstrained';
+let _d1ReadReplicationEnabled = false;
+let _d1ReadDefaultConstraint = D1_READ_DEFAULT_CONSTRAINT;
+const normalizeReadConstraint = (raw) => {
+    const value = raw.trim().toLowerCase();
+    return value === 'first-primary' ? 'first-primary' : 'first-unconstrained';
+};
 /**
  * Feature Flags - Controls access to advanced/experimental features
  * Sealed namespace for immutability
@@ -16,6 +23,11 @@ export const FeatureFlags = Object.freeze({
      */
     initialize() {
         _rawQueryEnabled = Env.get('USE_RAW_QRY') === 'true';
+        _d1ReadReplicationEnabled = Env.getBool('D1_READ_REPLICATION', false);
+        _d1ReadDefaultConstraint = normalizeReadConstraint(Env.get('D1_READ_DEFAULT_CONSTRAINT', D1_READ_DEFAULT_CONSTRAINT));
+        if (_d1ReadReplicationEnabled) {
+            Logger.info(`✓ D1 read replication ENABLED (default constraint: ${_d1ReadDefaultConstraint})`);
+        }
         if (_rawQueryEnabled) {
             Logger.warn('⚠️  FEATURE FLAG ENABLED: Raw SQL Queries are now available via adapter.rawQuery()');
             Logger.warn('⚠️  This bypasses QueryBuilder safety - use only when necessary');
@@ -32,11 +44,27 @@ export const FeatureFlags = Object.freeze({
     isRawQueryEnabled() {
         return _rawQueryEnabled;
     },
+    /**
+     * Whether D1 read replication (Sessions API) is enabled. When off,
+     * `IDatabase.withReadSession` is a passthrough and reads hit the primary.
+     */
+    isD1ReadReplicationEnabled() {
+        return _d1ReadReplicationEnabled;
+    },
+    /**
+     * Default session constraint applied by `withReadSession` when the caller
+     * does not specify one.
+     */
+    getD1ReadDefaultConstraint() {
+        return _d1ReadDefaultConstraint;
+    },
     /**
      * Reset flags (primarily for testing)
      */
     reset() {
         _rawQueryEnabled = false;
+        _d1ReadReplicationEnabled = false;
+        _d1ReadDefaultConstraint = D1_READ_DEFAULT_CONSTRAINT;
     },
     /**
      * Set raw query enabled state
@@ -45,5 +73,17 @@ export const FeatureFlags = Object.freeze({
     setRawQueryEnabled(enabled) {
         _rawQueryEnabled = enabled;
     },
+    /**
+     * Set D1 read replication enabled state (primarily for testing).
+     */
+    setD1ReadReplicationEnabled(enabled) {
+        _d1ReadReplicationEnabled = enabled;
+    },
+    /**
+     * Set the default D1 read constraint (primarily for testing).
+     */
+    setD1ReadDefaultConstraint(constraint) {
+        _d1ReadDefaultConstraint = constraint;
+    },
 });
 export default FeatureFlags;

package/src/index.js

@@ -1,11 +1,11 @@
 /**
- * @zintrust/core v2.4.7
+ * @zintrust/core v2.4.8
  *
  * ZinTrust Framework - Production-Grade TypeScript Backend
  * Built for performance, type safety, and exceptional developer experience
  *
  * Build Information:
- *   Built: 2026-06-01T22:49:09.622Z
+ *   Built: 2026-06-02T08:44:54.755Z
  *   Node: >=20.0.0
  *   License: MIT
  *
@@ -21,7 +21,7 @@
  * Available at runtime for debugging and health checks
  */
 export const ZINTRUST_VERSION = '0.1.41';
-export const ZINTRUST_BUILD_DATE = '2026-06-01T22:49:09.586Z'; // Replaced during build
+export const ZINTRUST_BUILD_DATE = '2026-06-02T08:44:54.704Z'; // Replaced during build
 export { Application } from './boot/Application.js';
 export { AwsSigV4 } from './common/index.js';
 export { SignedRequest } from './security/SignedRequest.js';

package/src/orm/Database.d.ts

@@ -3,7 +3,7 @@
  * Central database connection management and query execution
  */
 import type { SupportedDriver } from '../migrations/enum';
-import { type DatabaseConfig, type IDatabaseAdapter, type QueryResult } from './DatabaseAdapter';
+import { type D1ReadConstraint, type DatabaseConfig, type IDatabaseAdapter, type QueryResult } from './DatabaseAdapter';
 import type { IQueryBuilder } from './QueryBuilder';
 export type RawValue = {
     __raw: string;
@@ -17,6 +17,33 @@ export interface IDatabase {
     execute(sql: string, parameters?: unknown[], isRead?: boolean): Promise<QueryResult>;
     raw(value: string): RawValue;
     transaction<T>(callback: (db: IDatabase) => Promise<T>): Promise<T>;
+    /**
+     * Scope a unit of work to a D1 read-replication session and surface the
+     * resulting bookmark for the caller to persist and replay.
+     *
+     * Reads inside the session observe sequential consistency; writes still hit
+     * the primary. The `constraint` only governs where the first read may be
+     * served, and defaults to `D1_READ_DEFAULT_CONSTRAINT`
+     * (`"first-unconstrained"`).
+     *
+     * Consistency guidance for adopters:
+     * - Persist a **per-actor bookmark** (e.g. a signed cookie/header) and pass
+     *   it as `constraint` so a user always reads state at least as fresh as
+     *   their own last write, across requests and regions.
+     * - Use `"first-primary"` for a read that immediately follows a write in the
+     *   **same** request and must be read-your-writes without a bookmark.
+     * - Pure, staleness-tolerant reads (catalogs, listings, dashboards) can use
+     *   `"first-unconstrained"` with no bookmark for the lowest latency.
+     *
+     * When `D1_READ_REPLICATION` is off or the driver has no session support,
+     * this runs `fn` directly against the primary and returns `bookmark: null`.
+     */
+    withReadSession<T>(fn: (db: IDatabase) => Promise<T>, options?: {
+        constraint?: D1ReadConstraint;
+    }): Promise<{
+        result: T;
+        bookmark: string | null;
+    }>;
     table(name: string): IQueryBuilder;
     onBeforeQuery(handler: (query: string, params: unknown[]) => void): void;
     onAfterQuery(handler: (query: string, params: unknown[], duration: number) => void): void;

package/src/orm/Database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Database.d.ts","sourceRoot":"","sources":["../../../src/orm/Database.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAWxD,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,MAAM,MAAM,QAAQ,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,WAAW,SAAS;IACxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,WAAW,IAAI,OAAO,CAAC;IACvB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACjF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACrF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC7B,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC;IACnC,aAAa,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACzE,YAAY,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1F,cAAc,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1E,aAAa,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3F,kBAAkB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvD,OAAO,IAAI,eAAe,CAAC;IAC3B,SAAS,IAAI,cAAc,CAAC;IAC5B,OAAO,IAAI,IAAI,CAAC;CACjB;AAmgBD,eAAO,MAAM,QAAQ;IACnB;;OAEG;oBACa,cAAc,GAAG,SAAS;EAI1C,CAAC;AAIH,eAAO,MAAM,oBAAoB,GAC/B,SAAQ,cAAc,GAAG,SAAqB,EAC9C,uBAA0B,KACzB,OAAO,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,CAMxC,CAAC;AAEF,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,UAAU,SAAY,GAAG,SAAS,CAmCtF;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAQ1F;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAanD"}
+{"version":3,"file":"Database.d.ts","sourceRoot":"","sources":["../../../src/orm/Database.ts"],"names":[],"mappings":"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"}

package/src/orm/Database.js

@@ -5,6 +5,7 @@
 import { OpenTelemetry } from '../observability/OpenTelemetry.js';
 import { Cloudflare } from '../config/cloudflare.js';
 import { Env } from '../config/env.js';
+import { FeatureFlags } from '../config/features.js';
 import { Logger } from '../config/logger.js';
 import { ErrorFactory } from '../exceptions/ZintrustError.js';
 import { EventEmitter } from '../node-singletons/events.js';
@@ -175,6 +176,15 @@ const initializeAdapters = (dbConfig) => {
     const readAdapters = [writeAdapter];
     return { writeAdapter, readAdapters };
 };
+/**
+ * Read-replication routing metadata to surface in traces, when present.
+ */
+const routingMeta = (result) => {
+    if (result.servedByPrimary === undefined && result.servedByRegion === undefined) {
+        return undefined;
+    }
+    return { servedByPrimary: result.servedByPrimary, servedByRegion: result.servedByRegion };
+};
 /**
  * Execute a query with events and timing
  */
@@ -183,7 +193,7 @@ const executeQuery = async (adapter, eventEmitter, sql, parameters, method) => {
     const startTime = Date.now();
     const result = await adapter[method](sql, parameters);
     const duration = Date.now() - startTime;
-    eventEmitter.emit('after-query', sql, parameters, duration);
+    eventEmitter.emit('after-query', sql, parameters, duration, routingMeta(result));
     return BaseAdapter.normalizeRows(result.rows);
 };
 const executeFullQuery = async (adapter, eventEmitter, sql, parameters) => {
@@ -191,7 +201,7 @@ const executeFullQuery = async (adapter, eventEmitter, sql, parameters) => {
     const startTime = Date.now();
     const result = await adapter.query(sql, parameters);
     const duration = Date.now() - startTime;
-    eventEmitter.emit('after-query', sql, parameters, duration);
+    eventEmitter.emit('after-query', sql, parameters, duration, routingMeta(result));
     return BaseAdapter.normalizeQueryResult(result);
 };
 const executeQueryOne = async (adapter, eventEmitter, sql, parameters) => {
@@ -308,6 +318,18 @@ const createQueryHandlers = (writeAdapter, _readAdapters, eventEmitter, connecte
                 await db.connect();
             return writeAdapter.transaction(async () => callback(db));
         },
+        async withReadSession(fn, options) {
+            if (connected.value === false)
+                await db.connect();
+            // The write adapter owns the D1 binding; read adapters for D1 alias it.
+            const runReadSession = writeAdapter.runReadSession?.bind(writeAdapter);
+            if (FeatureFlags.isD1ReadReplicationEnabled() === false || runReadSession === undefined) {
+                const result = await fn(db);
+                return { result, bookmark: null };
+            }
+            const constraint = options?.constraint ?? FeatureFlags.getD1ReadDefaultConstraint();
+            return runReadSession(constraint, async () => fn(db));
+        },
     };
 };
 const setupDbInstrumentation = (dbConfig, eventEmitter) => {
@@ -325,6 +347,7 @@ const applyQueryHandlers = (db, queryHandlers) => {
     db.queryOne = queryHandlers.queryOne;
     db.execute = queryHandlers.execute;
     db.transaction = queryHandlers.transaction;
+    db.withReadSession = queryHandlers.withReadSession;
 };
 const createDbFacade = (input) => {
     const { dbConfig, writeAdapter, eventEmitter, connected, getAdapter, connectionHandlers, queryHandlers, cleanupFunctions, } = input;
@@ -341,6 +364,7 @@ const createDbFacade = (input) => {
             return { __raw: value };
         },
         transaction: queryHandlers.transaction,
+        withReadSession: queryHandlers.withReadSession,
         table(name) {
             return QueryBuilder.create(name, db);
         },

package/src/orm/DatabaseAdapter.d.ts

@@ -4,24 +4,56 @@
  */
 import type { SupportedDriver } from '../migrations/enum';
 /**
- * Minimal D1 Database interface for type safety
+ * Read-replication constraint for a D1 session.
+ *
+ * - `"first-primary"`: first query in the session goes to the primary
+ *   (read-your-writes without a bookmark).
+ * - `"first-unconstrained"`: first query may be served by any replica
+ *   (lowest latency; tolerates slightly stale reads).
+ * - any other `string`: an opaque D1 bookmark that resumes a prior session's
+ *   consistency point.
+ */
+export type D1ReadConstraint = 'first-primary' | 'first-unconstrained' | (string & {});
+/**
+ * Bound statement shape shared by the primary binding and a session handle.
+ */
+export interface ID1BoundStatement {
+    all<T = unknown>(): Promise<{
+        results?: T[];
+        success: boolean;
+        error?: string;
+        meta?: Record<string, unknown>;
+    }>;
+    first<T = unknown>(): Promise<T | null>;
+    run(): Promise<{
+        success: boolean;
+        error?: string;
+        meta?: Record<string, unknown>;
+    }>;
+}
+export interface ID1PreparedStatement {
+    bind(...values: unknown[]): ID1BoundStatement;
+}
+/**
+ * Minimal D1 Database interface for type safety.
+ *
+ * `withSession` is optional: it is present when the bound database has read
+ * replication enabled. The driver tolerates its absence and falls back to
+ * direct-to-primary execution.
  */
 export interface ID1Database {
-    prepare(sql: string): {
-        bind(...values: unknown[]): {
-            all<T = unknown>(): Promise<{
-                results?: T[];
-                success: boolean;
-                error?: string;
-                meta?: Record<string, unknown>;
-            }>;
-            first<T = unknown>(): Promise<T | null>;
-            run(): Promise<{
-                success: boolean;
-                error?: string;
-            }>;
-        };
-    };
+    prepare(sql: string): ID1PreparedStatement;
+    withSession?(constraint?: D1ReadConstraint): ID1DatabaseSession;
+}
+/**
+ * Session-scoped handle returned by `ID1Database.withSession`.
+ *
+ * Carries a bookmark representing a point in the database's history so reads
+ * within the session observe sequential consistency.
+ */
+export interface ID1DatabaseSession {
+    prepare(sql: string): ID1PreparedStatement;
+    getBookmark(): string | null;
 }
 export interface DatabaseConfig {
     d1?: ID1Database;
@@ -39,6 +71,13 @@ export interface QueryResult {
     rows: Record<string, unknown>[];
     rowCount: number;
     lastInsertId?: string | number | bigint;
+    /**
+     * Read-replication routing metadata, when the driver exposes it (D1).
+     * `servedByPrimary` is `true` when the query hit the primary, `false` when a
+     * replica served it; `servedByRegion` is the replica/primary region code.
+     */
+    servedByPrimary?: boolean;
+    servedByRegion?: string;
 }
 export interface IDatabaseAdapter {
     /**
@@ -85,6 +124,20 @@ export interface IDatabaseAdapter {
      * For SQL databases, this typically means dropping user tables.
      */
     resetSchema?(): Promise<void>;
+    /**
+     * Run `fn` inside a read-replication session (D1 only).
+     *
+     * Every statement issued by `fn` is routed through a session-scoped handle so
+     * reads observe sequential consistency. Returns the function result together
+     * with the latest bookmark to persist and replay on the next request.
+     *
+     * Adapters without read-replication support leave this undefined; callers
+     * should fall back to executing `fn` directly with a `null` bookmark.
+     */
+    runReadSession?<T>(constraint: D1ReadConstraint, fn: () => Promise<T>): Promise<{
+        result: T;
+        bookmark: string | null;
+    }>;
     /**
      * Get database type
      */

package/src/orm/DatabaseAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DatabaseAdapter.d.ts","sourceRoot":"","sources":["../../../src/orm/DatabaseAdapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DatabaseAdapter.d.ts","sourceRoot":"","sources":["../../../src/orm/DatabaseAdapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,qBAAqB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,CAAC,GAAG,OAAO,KAAK,OAAO,CAAC;QAC1B,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QACd,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,CAAC,CAAC;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxC,GAAG,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,iBAAiB,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAAC;IAC3C,WAAW,CAAC,CAAC,UAAU,CAAC,EAAE,gBAAgB,GAAG,kBAAkB,CAAC;CACjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAAC;IAC3C,WAAW,IAAI,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,WAAW,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACxC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEhE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAEtF;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;OAEG;IACH,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEhF;;;OAGG;IACH,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,qBAAqB,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;OAIG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;;;;;;;OASG;IACH,cAAc,CAAC,CAAC,CAAC,EACf,UAAU,EAAE,gBAAgB,EAC5B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAEnD;;OAEG;IACH,OAAO,IAAI,eAAe,CAAC;IAE3B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACvC;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW;8BACI,OAAO,GAAG,OAAO;sBAKzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;wBAM/C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;yBAIpD,CAAC,SAAS,WAAW,UAAU,CAAC,GAAG,CAAC;IAOzD;;OAEG;oBACa,OAAO,GAAG,MAAM;IAmChC;;OAEG;iCAEI,MAAM,cACC,OAAO,EAAE,mBACL,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GACxC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,EAAE,CAAA;KAAE;EASzC,CAAC"}

package/src/orm/adapters/D1Adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"D1Adapter.d.ts","sourceRoot":"","sources":["../../../../src/orm/adapters/D1Adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EACV,cAAc,EAEd,gBAAgB,EAEjB,MAAM,sBAAsB,CAAC;AA0D9B;;GAEG;AACH,eAAO,MAAM,SAAS;IACpB;;OAEG;oBAEa,cAAc,GAAG,gBAAgB;EAqIjD,CAAC;AAEH,eAAe,SAAS,CAAC"}
+{"version":3,"file":"D1Adapter.d.ts","sourceRoot":"","sources":["../../../../src/orm/adapters/D1Adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EAEV,cAAc,EAGd,gBAAgB,EAEjB,MAAM,sBAAsB,CAAC;AA2E9B;;GAEG;AACH,eAAO,MAAM,SAAS;IACpB;;OAEG;oBAEa,cAAc,GAAG,gBAAgB;EAiKjD,CAAC;AAEH,eAAe,SAAS,CAAC"}

package/src/orm/adapters/D1Adapter.js

@@ -8,6 +8,7 @@ import { ErrorFactory } from '../../exceptions/ZintrustError.js';
 import { isObject } from '../../helper/index.js';
 import { AdaptersEnum } from '../../migrations/enum/index.js';
 import { BaseAdapter } from '../DatabaseAdapter.js';
+import { createReadSessionScope, openSession } from '../adapters/D1ReadSession.js';
 import { QueryBuilder } from '../QueryBuilder.js';
 const isRecord = (value) => isObject(value);
 const toNumber = (value) => {
@@ -44,6 +45,22 @@ const extractMeta = (value) => {
         toInsertId(value['last_insert_rowid']);
     return { changes, lastInsertId };
 };
+/**
+ * Extract read-replication routing metadata from a D1 result `meta`, when D1
+ * exposes it. Returns an empty object when replication is off (no such fields).
+ */
+const extractServedBy = (value) => {
+    if (!isRecord(value))
+        return {};
+    const out = {};
+    const primary = value['served_by_primary'];
+    if (typeof primary === 'boolean')
+        out.servedByPrimary = primary;
+    const region = value['served_by_region'];
+    if (typeof region === 'string' && region.trim() !== '')
+        out.servedByRegion = region;
+    return out;
+};
 /**
  * Get D1 binding from config or global environment
  */
@@ -60,6 +77,22 @@ export const D1Adapter = Object.freeze({
     // eslint-disable-next-line max-lines-per-function
     create(_config) {
         let connected = false;
+        const sessionScope = createReadSessionScope();
+        /**
+         * Resolve the statement source for the current operation: the active
+         * read-replication session handle when one is in scope, otherwise the raw
+         * binding. Throws a config error when no binding is available.
+         */
+        const resolveExecutor = () => {
+            const active = sessionScope.peek();
+            if (active !== undefined)
+                return active.db;
+            const db = getD1Binding(_config);
+            if (db === null) {
+                throw ErrorFactory.createConfigError('D1 database binding not found');
+            }
+            return db;
+        };
         return {
             // eslint-disable-next-line @typescript-eslint/require-await
             async connect() {
@@ -74,10 +107,7 @@ export const D1Adapter = Object.freeze({
             async query(sql, parameters) {
                 if (!connected)
                     throw ErrorFactory.createConnectionError('Database not connected');
-                const db = getD1Binding(_config);
-                if (db === null) {
-                    throw ErrorFactory.createConfigError('D1 database binding not found');
-                }
+                const db = resolveExecutor();
                 try {
                     const stmt = db.prepare(sql);
                     if (isMutatingSql(sql)) {
@@ -88,6 +118,7 @@ export const D1Adapter = Object.freeze({
                             rows: [],
                             rowCount: meta.changes,
                             lastInsertId: meta.lastInsertId,
+                            ...extractServedBy(runRecord.meta),
                         };
                     }
                     const result = await stmt.bind(...parameters).all();
@@ -99,6 +130,7 @@ export const D1Adapter = Object.freeze({
                         rows,
                         rowCount: rows.length > 0 ? rows.length : meta.changes,
                         lastInsertId: meta.lastInsertId,
+                        ...extractServedBy(metaValue),
                     };
                 }
                 catch (error) {
@@ -108,10 +140,7 @@ export const D1Adapter = Object.freeze({
             async queryOne(sql, parameters) {
                 if (!connected)
                     throw ErrorFactory.createConnectionError('Database not connected');
-                const db = getD1Binding(_config);
-                if (db === null) {
-                    throw ErrorFactory.createConfigError('D1 database binding not found');
-                }
+                const db = resolveExecutor();
                 try {
                     const stmt = db.prepare(sql);
                     const result = await stmt.bind(...parameters).first();
@@ -124,10 +153,7 @@ export const D1Adapter = Object.freeze({
             async ping() {
                 if (!connected)
                     throw ErrorFactory.createConnectionError('Database not connected');
-                const db = getD1Binding(_config);
-                if (db === null) {
-                    throw ErrorFactory.createConfigError('D1 database binding not found');
-                }
+                const db = resolveExecutor();
                 try {
                     // Use a minimal, side-effect-free query.
                     await db.prepare(QueryBuilder.create('').select('1').toSQL()).bind().first();
@@ -147,6 +173,23 @@ export const D1Adapter = Object.freeze({
                     throw ErrorFactory.createTryCatchError('Transaction failed', error);
                 }
             },
+            async runReadSession(constraint, fn) {
+                if (!connected)
+                    throw ErrorFactory.createConnectionError('Database not connected');
+                const db = getD1Binding(_config);
+                if (db === null) {
+                    throw ErrorFactory.createConfigError('D1 database binding not found');
+                }
+                const handle = openSession(db, constraint);
+                if (handle === null) {
+                    // Replication not enabled on the binding: run directly against the
+                    // primary and report no bookmark.
+                    const result = await fn();
+                    return { result, bookmark: null };
+                }
+                const result = await sessionScope.run(handle, fn);
+                return { result, bookmark: handle.getBookmark() };
+            },
             getType() {
                 return AdaptersEnum.d1;
             },
@@ -160,10 +203,7 @@ export const D1Adapter = Object.freeze({
                 if (!connected) {
                     throw ErrorFactory.createConnectionError('Database not connected');
                 }
-                const db = getD1Binding(_config);
-                if (db === null) {
-                    throw ErrorFactory.createConfigError('D1 database binding not found');
-                }
+                const db = resolveExecutor();
                 try {
                     Logger.warn(`Raw SQL Query executed: ${sql}`, Logger.withTraceSkipContext({ sql, parameters }));
                     const stmt = db.prepare(sql);

package/src/orm/adapters/D1ReadSession.d.ts

@@ -0,0 +1,34 @@
+/**
+ * D1 read-replication session scoping.
+ *
+ * Opens a D1 Sessions API handle and scopes it to the async context running a
+ * unit of work, so the D1 adapter can transparently route statements through
+ * the session while it is active. Falls back to direct-to-primary execution
+ * when the bound database has no `withSession` (replication disabled).
+ *
+ * Works in both `zin s` (Node) and `zin s --wg` (Workers): it lazily upgrades
+ * to `AsyncLocalStorage` when available and otherwise uses a synchronous
+ * single-slot fallback, mirroring `@http/RequestContext`.
+ */
+import type { D1ReadConstraint, ID1Database, ID1DatabaseSession } from '../DatabaseAdapter';
+export interface D1SessionHandle {
+    readonly db: ID1DatabaseSession;
+    getBookmark(): string | null;
+}
+/**
+ * Open a session against the bound database, or `null` when the binding does
+ * not support read replication (then reads simply come from the primary).
+ */
+export declare const openSession: (d1: ID1Database, constraint: D1ReadConstraint) => D1SessionHandle | null;
+export interface ReadSessionScope {
+    /** Run `fn` with `handle` bound to the current async context. */
+    run<T>(handle: D1SessionHandle, fn: () => Promise<T>): Promise<T>;
+    /** Read the session bound to the current async context, if any. */
+    peek(): D1SessionHandle | undefined;
+}
+/**
+ * Create an independent session scope. One per adapter instance keeps separate
+ * database connections from sharing session state.
+ */
+export declare const createReadSessionScope: () => ReadSessionScope;
+//# sourceMappingURL=D1ReadSession.d.ts.map

package/src/orm/adapters/D1ReadSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"D1ReadSession.d.ts","sourceRoot":"","sources":["../../../../src/orm/adapters/D1ReadSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,WAAW,IAAI,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,IAAI,WAAW,EACf,YAAY,gBAAgB,KAC3B,eAAe,GAAG,IAIpB,CAAC;AAkCF,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClE,mEAAmE;IACnE,IAAI,IAAI,eAAe,GAAG,SAAS,CAAC;CACrC;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAAO,gBAiBzC,CAAC"}

package/src/orm/adapters/D1ReadSession.js

@@ -0,0 +1,69 @@
+/**
+ * D1 read-replication session scoping.
+ *
+ * Opens a D1 Sessions API handle and scopes it to the async context running a
+ * unit of work, so the D1 adapter can transparently route statements through
+ * the session while it is active. Falls back to direct-to-primary execution
+ * when the bound database has no `withSession` (replication disabled).
+ *
+ * Works in both `zin s` (Node) and `zin s --wg` (Workers): it lazily upgrades
+ * to `AsyncLocalStorage` when available and otherwise uses a synchronous
+ * single-slot fallback, mirroring `@http/RequestContext`.
+ */
+/**
+ * Open a session against the bound database, or `null` when the binding does
+ * not support read replication (then reads simply come from the primary).
+ */
+export const openSession = (d1, constraint) => {
+    if (typeof d1.withSession !== 'function')
+        return null;
+    const session = d1.withSession(constraint);
+    return { db: session, getBookmark: () => session.getBookmark() ?? null };
+};
+const createFallbackStorage = () => {
+    let store;
+    return {
+        run(handle, callback) {
+            const prev = store;
+            store = handle;
+            try {
+                return callback();
+            }
+            finally {
+                store = prev;
+            }
+        },
+        getStore() {
+            return store;
+        },
+    };
+};
+let alsClassPromise = null;
+const loadAsyncLocalStorage = async () => {
+    alsClassPromise ??= import('../../node-singletons/async_hooks.js')
+        .then((mod) => mod.AsyncLocalStorage ?? null)
+        .catch(() => null);
+    return alsClassPromise;
+};
+/**
+ * Create an independent session scope. One per adapter instance keeps separate
+ * database connections from sharing session state.
+ */
+export const createReadSessionScope = () => {
+    let storage = createFallbackStorage();
+    const ready = loadAsyncLocalStorage()
+        .then((AsyncLocalStorage) => {
+        if (AsyncLocalStorage !== null)
+            storage = new AsyncLocalStorage();
+    })
+        .catch(() => undefined);
+    return {
+        async run(handle, fn) {
+            await ready;
+            return storage.run(handle, fn);
+        },
+        peek() {
+            return storage.getStore();
+        },
+    };
+};

package/src/proxy/d1/ZintrustD1Proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ZintrustD1Proxy.d.ts","sourceRoot":"","sources":["../../../../src/proxy/d1/ZintrustD1Proxy.ts"],"names":[],"mappings":"AAUA,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;AAEjD,KAAK,qBAAqB,GAAG;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,GAAG,EAAE;QACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACrE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;QAChE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC;KAChG,CAAC;IACF,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrF,CAAC;AAEF,KAAK,WAAW,CAAC,CAAC,IAAI;IACpB,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;CACf,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACzB,IAAI,EAAE,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,mBAAmB,CAAC;IACpD,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,KAAK,EAAE,CAAC,CAAC,GAAG,OAAO,OAAO,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5C,GAAG,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;CACjC,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,mBAAmB,CAAC;CAC/C,CAAC;AAEF,KAAK,KAAK,GAAG;IACX,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAiTF,eAAO,MAAM,eAAe;;;mBAGL,OAAO,OAAO,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC;EAqB5D,CAAC;AAEH,eAAe,eAAe,CAAC"}
+{"version":3,"file":"ZintrustD1Proxy.d.ts","sourceRoot":"","sources":["../../../../src/proxy/d1/ZintrustD1Proxy.ts"],"names":[],"mappings":"AAUA,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;AAEjD,KAAK,qBAAqB,GAAG;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,GAAG,EAAE;QACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACrE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;QAChE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC;KAChG,CAAC;IACF,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrF,CAAC;AAEF,KAAK,WAAW,CAAC,CAAC,IAAI;IACpB,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;CACf,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACzB,IAAI,EAAE,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,mBAAmB,CAAC;IACpD,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,KAAK,EAAE,CAAC,CAAC,GAAG,OAAO,OAAO,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5C,GAAG,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;CACjC,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,mBAAmB,CAAC;CAC/C,CAAC;AAEF,KAAK,KAAK,GAAG;IACX,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AA2UF,eAAO,MAAM,eAAe;;;mBAGL,OAAO,OAAO,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC;EAqB5D,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/src/proxy/d1/ZintrustD1Proxy.js

@@ -76,6 +76,18 @@ const isMutatingSql = (sql) => {
         normalized.startsWith('alter') ||
         normalized.startsWith('replace'));
 };
+const routingFromMeta = (meta) => {
+    if (!isRecord(meta))
+        return undefined;
+    const out = {};
+    const primary = meta['served_by_primary'];
+    if (typeof primary === 'boolean')
+        out.servedByPrimary = primary;
+    const region = meta['served_by_region'];
+    if (typeof region === 'string' && region.trim() !== '')
+        out.servedByRegion = region;
+    return out.servedByPrimary === undefined && out.servedByRegion === undefined ? undefined : out;
+};
 const requireDb = (env) => {
     const db = resolveD1Binding(env);
     if (db === null) {
@@ -149,7 +161,7 @@ const handleQuery = async (request, env) => {
             .prepare(resolved.sql)
             .bind(...resolved.params)
             .all();
-        SystemTraceWorkerBridge.emitQuery(resolved.sql, resolved.params, Date.now() - startedAt, 'd1-proxy');
+        SystemTraceWorkerBridge.emitQuery(resolved.sql, resolved.params, Date.now() - startedAt, 'd1-proxy', routingFromMeta(result.meta));
         const rows = result.results ?? [];
         return json(200, { rows, rowCount: rows.length });
     }
@@ -186,7 +198,7 @@ const handleExec = async (request, env) => {
             .prepare(resolved.sql)
             .bind(...resolved.params)
             .run();
-        SystemTraceWorkerBridge.emitQuery(resolved.sql, resolved.params, Date.now() - startedAt, 'd1-proxy');
+        SystemTraceWorkerBridge.emitQuery(resolved.sql, resolved.params, Date.now() - startedAt, 'd1-proxy', routingFromMeta(out.meta));
         return json(200, { ok: true, meta: out.meta });
     }
     catch (error) {
@@ -230,14 +242,14 @@ const handleStatement = async (request, env) => {
                 .prepare(sql)
                 .bind(...parsed.params)
                 .run();
-            SystemTraceWorkerBridge.emitQuery(sql, parsed.params, Date.now() - startedAt, 'd1-proxy');
+            SystemTraceWorkerBridge.emitQuery(sql, parsed.params, Date.now() - startedAt, 'd1-proxy', routingFromMeta(out.meta));
             return json(200, { ok: true, meta: out.meta });
         }
         const out = await resolved.db
             .prepare(sql)
             .bind(...parsed.params)
             .all();
-        SystemTraceWorkerBridge.emitQuery(sql, parsed.params, Date.now() - startedAt, 'd1-proxy');
+        SystemTraceWorkerBridge.emitQuery(sql, parsed.params, Date.now() - startedAt, 'd1-proxy', routingFromMeta(out.meta));
         const rows = out.results ?? [];
         return json(200, { rows, rowCount: rows.length });
     }

package/src/trace/SystemTraceBridge.d.ts

@@ -21,7 +21,10 @@ export declare const SystemTraceBridge: Readonly<{
     emitJobProcessed: (name: string) => void;
     emitMail: (to: string, subject: string, template?: string, text?: string, html?: string) => void;
     emitNotification: (notification: string, channels: string[], notifiable?: string, message?: string, payload?: unknown) => void;
-    emitQuery: (query: string, params: unknown[], duration: number, connection?: string) => void;
+    emitQuery: (query: string, params: unknown[], duration: number, connection?: string, routing?: {
+        servedByPrimary?: boolean;
+        servedByRegion?: string;
+    }) => void;
     emitRedis: (command: string, duration: number) => void;
 }>;
 export default SystemTraceBridge;

package/src/trace/SystemTraceBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SystemTraceBridge.d.ts","sourceRoot":"","sources":["../../../src/trace/SystemTraceBridge.ts"],"names":[],"mappings":"AAsOA,eAAO,MAAM,iBAAiB;mBALJ,OAAO,CAAC,OAAO,CAAC;sBAlBjB,OAAO,GAAG,QAAQ,GAAG,QAAQ,WAAW,MAAM,KAAG,IAAI;2BA/FjE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,OAChD,MAAM,YACD,MAAM,QACV,OAAO,YACH,OAAO,UACT,MAAM,QACR,MAAM,KACX,IAAI;wBA+FC,MAAM,QACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YACnB,MAAM,YACN,MAAM,WACP,MAAM,KACd,IAAI;sBAlBkB,MAAM,iBAAiB,MAAM,YAAY,OAAO,KAAG,IAAI;8BAlC/C;QAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,KAAG,IAAI;4BArDuB,MAAM,SAAS,MAAM,cAAc,MAAM,SAAS,OAAO,KAAG,IAAI;0BAYlE,MAAM,SAAS,KAAK,KAAG,IAAI;6BANxB,MAAM,KAAG,IAAI;mBAyBvC,MAAM,WACD,MAAM,aACJ,MAAM,SACV,MAAM,SACN,MAAM,KACZ,IAAI;qCAjBS,MAAM,YACV,MAAM,EAAE,eACL,MAAM,YACT,MAAM,YACN,OAAO,KAChB,IAAI;uBAoCE,MAAM,UACL,OAAO,EAAE,YACP,MAAM,eACH,MAAM,KAClB,IAAI;yBAMqB,MAAM,YAAY,MAAM,KAAG,IAAI;EAiDzD,CAAC;AAEH,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"SystemTraceBridge.d.ts","sourceRoot":"","sources":["../../../src/trace/SystemTraceBridge.ts"],"names":[],"mappings":"AA6OA,eAAO,MAAM,iBAAiB;mBALJ,OAAO,CAAC,OAAO,CAAC;sBAlBjB,OAAO,GAAG,QAAQ,GAAG,QAAQ,WAAW,MAAM,KAAG,IAAI;2BAhGjE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,OAChD,MAAM,YACD,MAAM,QACV,OAAO,YACH,OAAO,UACT,MAAM,QACR,MAAM,KACX,IAAI;wBAgGC,MAAM,QACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YACnB,MAAM,YACN,MAAM,WACP,MAAM,KACd,IAAI;sBAlBkB,MAAM,iBAAiB,MAAM,YAAY,OAAO,KAAG,IAAI;8BAnC/C;QAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,KAAG,IAAI;4BArDuB,MAAM,SAAS,MAAM,cAAc,MAAM,SAAS,OAAO,KAAG,IAAI;0BAYlE,MAAM,SAAS,KAAK,KAAG,IAAI;6BANxB,MAAM,KAAG,IAAI;mBAyBvC,MAAM,WACD,MAAM,aACJ,MAAM,SACV,MAAM,SACN,MAAM,KACZ,IAAI;qCAjBS,MAAM,YACV,MAAM,EAAE,eACL,MAAM,YACT,MAAM,YACN,OAAO,KAChB,IAAI;uBAoCE,MAAM,UACL,OAAO,EAAE,YACP,MAAM,eACH,MAAM,YACT;QAAE,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,KAC/D,IAAI;yBAMqB,MAAM,YAAY,MAAM,KAAG,IAAI;EAiDzD,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/trace/SystemTraceBridge.js

@@ -2,7 +2,7 @@ let cachedModule;
 let loadPromise = null;
 const importSystemTrace = async () => {
     try {
-        return (await import('@zintrust/trace'));
+        return await import('@zintrust/trace');
     }
     catch {
         return null;
@@ -74,9 +74,9 @@ const emitHttpClient = (payload) => {
         module.HttpClientWatcher?.emit(payload);
     });
 };
-const emitQuery = (query, params, duration, connection) => {
+const emitQuery = (query, params, duration, connection, routing) => {
     withSystemTrace((module) => {
-        module.QueryWatcher?.emit(query, params, duration, connection);
+        module.QueryWatcher?.emit(query, params, duration, connection, routing);
     });
 };
 const emitRedis = (command, duration) => {

package/src/trace/SystemTraceWorkerBridge.d.ts

@@ -1,7 +1,10 @@
 export declare const SystemTraceWorkerBridge: Readonly<{
     emitCache: (operation: "get" | "set" | "delete" | "clear" | "has", key: string, duration: number, hit?: boolean, payload?: unknown, store?: string, ttl?: number) => void;
     emitEvent: (name: string, listenerCount: number, payload?: unknown) => void;
-    emitQuery: (query: string, params: unknown[], duration: number, connection?: string) => void;
+    emitQuery: (query: string, params: unknown[], duration: number, connection?: string, routing?: {
+        servedByPrimary?: boolean;
+        servedByRegion?: string;
+    }) => void;
 }>;
 export default SystemTraceWorkerBridge;
 //# sourceMappingURL=SystemTraceWorkerBridge.d.ts.map

package/src/trace/SystemTraceWorkerBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SystemTraceWorkerBridge.d.ts","sourceRoot":"","sources":["../../../src/trace/SystemTraceWorkerBridge.ts"],"names":[],"mappings":"AAgEA,eAAO,MAAM,uBAAuB;2BA9BvB,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,OAChD,MAAM,YACD,MAAM,QACV,OAAO,YACH,OAAO,UACT,MAAM,QACR,MAAM,KACX,IAAI;sBAMkB,MAAM,iBAAiB,MAAM,YAAY,OAAO,KAAG,IAAI;uBAOvE,MAAM,UACL,OAAO,EAAE,YACP,MAAM,eACH,MAAM,KAClB,IAAI;EAUL,CAAC;AAEH,eAAe,uBAAuB,CAAC"}
+{"version":3,"file":"SystemTraceWorkerBridge.d.ts","sourceRoot":"","sources":["../../../src/trace/SystemTraceWorkerBridge.ts"],"names":[],"mappings":"AAuEA,eAAO,MAAM,uBAAuB;2BA/BvB,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,OAChD,MAAM,YACD,MAAM,QACV,OAAO,YACH,OAAO,UACT,MAAM,QACR,MAAM,KACX,IAAI;sBAMkB,MAAM,iBAAiB,MAAM,YAAY,OAAO,KAAG,IAAI;uBAOvE,MAAM,UACL,OAAO,EAAE,YACP,MAAM,eACH,MAAM,YACT;QAAE,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,KAC/D,IAAI;EAUL,CAAC;AAEH,eAAe,uBAAuB,CAAC"}

package/src/trace/SystemTraceWorkerBridge.js

@@ -22,9 +22,9 @@ const emitEvent = (name, listenerCount, payload) => {
         module.emitEvent?.(name, listenerCount, payload);
     });
 };
-const emitQuery = (query, params, duration, connection) => {
+const emitQuery = (query, params, duration, connection, routing) => {
     withWorkerTraceModule((module) => {
-        module.emitQuery?.(query, params, duration, connection);
+        module.emitQuery?.(query, params, duration, connection, routing);
     });
 };
 export const SystemTraceWorkerBridge = Object.freeze({