@zintrust/trace 2.0.0 → 2.1.3

package/README.md

@@ -91,6 +91,30 @@ import serviceManifest from './bootstrap/service-manifest';
 ProjectRuntime.set({ serviceManifest });
 ```
 
+#### Cloudflare Workers waitUntil Support
+
+For reliable trace persistence in Cloudflare Workers, set the execution context in your Worker fetch handler:
+
+```ts
+// src/worker.ts or your Worker entrypoint
+import { BackgroundTaskScheduler } from '@zintrust/trace';
+
+export default {
+  async fetch(request, env, ctx) {
+    // Enable reliable trace persistence via ctx.waitUntil()
+    BackgroundTaskScheduler.setExecutionContext(ctx);
+
+    // Initialize and run your ZinTrust app
+    const app = createApp();
+    await app.boot();
+
+    return app.handle(request);
+  },
+};
+```
+
+This ensures trace writes complete reliably even after the HTTP response is sent. Without this, trace writes may be lost in Workers environments. See [docs/WORKER_WAITUNTIL_SUPPORT.md](./docs/WORKER_WAITUNTIL_SUPPORT.md) for details.
+
 Why this is the preferred path:
 
 - The plugin files are the framework-owned opt-in point that ZinTrust already auto-loads during boot.

package/dist/TraceConnection.d.ts

@@ -1,4 +1,4 @@
-import type { IDatabase } from '@zintrust/core';
+import type { IDatabase } from '@zintrust/core/database';
 type TraceErrorFactory = {
     createConfigError?(message: string, details?: unknown): Error;
 };

package/dist/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "name": "@zintrust/trace",
-  "version": "2.0.0",
-  "buildDate": "2026-05-20T20:04:23.602Z",
+  "version": "2.1.3",
+  "buildDate": "2026-05-27T04:11:41.644Z",
   "buildEnvironment": {
-    "node": "v20.20.2",
-    "platform": "linux",
-    "arch": "x64"
+    "node": "v22.22.1",
+    "platform": "darwin",
+    "arch": "arm64"
   },
   "git": {
-    "commit": "be96835b",
-    "branch": "master"
+    "commit": "c82f6263",
+    "branch": "release"
   },
   "package": {
     "engines": {
@@ -22,13 +22,17 @@
   },
   "files": {
     "TraceConnection.d.ts": {
-      "size": 1500,
-      "sha256": "0748601bebff011a0b3dbab736617d5e3dffe4af671f4b6f7af03012d58e5464"
+      "size": 1509,
+      "sha256": "09a6d63712628d917cd6f64550ebf527c7b419da369983a57151808d32a5a666"
     },
     "TraceConnection.js": {
       "size": 4640,
       "sha256": "c51cc312046b6b2bbe1673f1ff9508425cc7140a1d2341907f67aa36069c09f9"
     },
+    "build-manifest.json": {
+      "size": 15929,
+      "sha256": "be6384c7124a8d2d845db13d13bdbbafd294b758fb3f4a64af6b4bfdb26c4f86"
+    },
     "cli-register.d.ts": {
       "size": 255,
       "sha256": "da8d689fe5ef32e97e755f28017e4d3cb1aa63489073a71907ea41ad5761ede9"
@@ -54,20 +58,20 @@
       "sha256": "00a82a58e18fb33934f449a9fb379a2f90023570ceed1676eae0aed59b02ddeb"
     },
     "dashboard/handlers.d.ts": {
-      "size": 993,
-      "sha256": "430f5b294d960e13e2ec39ed5c22f6655f85c46c2de9455c222505c67298ec6a"
+      "size": 998,
+      "sha256": "788a2c71fdd77adbcef3e41bffe7ddf07f04bc1bdd10e6f19cfcd3ba6b9e858b"
     },
     "dashboard/handlers.js": {
       "size": 10011,
       "sha256": "a5f7f3d624a844df27ddc9d4908e73d91a4aac9b2aac1aefff1f391913353897"
     },
     "dashboard/routes.d.ts": {
-      "size": 997,
-      "sha256": "0ac87bc54e57978e8a9ac5924d248e1f984927bb6c819ea5528ab1179b0b50b8"
+      "size": 797,
+      "sha256": "988be2431f7cde857403dcbd84949f425c1ed668b3c41faa3d104dd891d6c0dc"
     },
     "dashboard/routes.js": {
-      "size": 2501,
-      "sha256": "06f0bf42214ed7691907443c0a1d5a4d8c3db3ce3f7b8269ba401ff421a54dfd"
+      "size": 2627,
+      "sha256": "b59d95e8bfe256b2904d6000d672036faa68983e296cd8c82ae782cb0b804fcb"
     },
     "dashboard/ui.d.ts": {
       "size": 117,
@@ -78,52 +82,52 @@
       "sha256": "6a19ca4b079944cf0070633a0694de28d034f78ff2d1f02af00707cd2434751f"
     },
     "index.d.ts": {
-      "size": 2693,
-      "sha256": "901aaefe88fb2cc1e7771cd541f41ebcfe6443390bd66905eacbda51f1a6f73d"
+      "size": 2770,
+      "sha256": "83fdbdc30ce9c926c35cb5a95f480797cb7d12c8a52237dd7a19ec62dfe93dac"
     },
     "index.js": {
-      "size": 3421,
-      "sha256": "09fa209693e5195efa6a58f18d869af4fef501a25462bc910ed7cec5c975a6bf"
+      "size": 3670,
+      "sha256": "cb7b0d00db90067076a82dbb339b942dee72803cfe730303081f5102008d1140"
     },
     "ingest/TraceIngestGateway.d.ts": {
-      "size": 786,
-      "sha256": "3a0a46fa5bbf5367047214533ec0ee92a171ee35a60d25c197eea1eed1ff0f65"
+      "size": 791,
+      "sha256": "7362cb112369bfa2091cb10ce3fc557bc9be5bf9e17abeba32e23bc58bbf9f57"
     },
     "ingest/TraceIngestGateway.js": {
-      "size": 10936,
-      "sha256": "c95f0e42f1294d8ae2e406a5910f8e74044c2b586e82e726876d75ddfafef27e"
+      "size": 11105,
+      "sha256": "d4f07c03cb9e34293058255e8ad7d7d83e2b332256f6ca3a3d2011dcb857fb37"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.d.ts": {
-      "size": 304,
-      "sha256": "7d99b4d7c02855d6e68ad87e39dffff5fec83a406bdf2414665c23ba3ce8711d"
+      "size": 313,
+      "sha256": "be62bd700b040e7df58dc76f8282fa1400b57d19f089a63b3f4677df16e203d4"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.js": {
-      "size": 955,
-      "sha256": "6aa54f3a6a95a78714e9b14d7f6adb4e94e9420e4e17ac467b43fef12bbc2583"
+      "size": 964,
+      "sha256": "49c5df2a7caac1da82652db591914bfa00fde7591814a9f945f861f0a705fba7"
     },
     "migrations/20260331000002_create_zin_trace_entries_tags_table.d.ts": {
-      "size": 304,
-      "sha256": "6d07c135b0fa34acbda2f7f0788e4db657b00ba7c7459e2b203c8ded9c55b9dc"
+      "size": 313,
+      "sha256": "95d6824268fc69ec4a8cab4a551ca600d27983d0e0b13c51ffc5c9b4e55bec39"
     },
     "migrations/20260331000002_create_zin_trace_entries_tags_table.js": {
-      "size": 737,
-      "sha256": "614280fc7f3a5826c3e8334e2a38d707b562217fb68a660aff0d9a6c072f7b2a"
+      "size": 746,
+      "sha256": "726375b0f404d2c6d55d195e52bf978e6f95b6ad4d241fa23ed7d8d1bb369412"
     },
     "migrations/20260331000003_create_zin_trace_monitoring_table.d.ts": {
-      "size": 308,
-      "sha256": "019e84f70cedf363eaf85a115d935abed841627b4a31d7fa34131352d402187a"
+      "size": 317,
+      "sha256": "d45a119cd221faaaf804fd466d2e5678e137751fc9ab3bc6bc6992b1190fb7fb"
     },
     "migrations/20260331000003_create_zin_trace_monitoring_table.js": {
-      "size": 522,
-      "sha256": "dd80ea1fdfe6ea7f57330b2dff530d97ee8054081436f41bbf234b814cb1df19"
+      "size": 531,
+      "sha256": "fe52d93d169ae65e6092f05535b35c728d11253580b39bdd629a64fdd94c64ab"
     },
     "migrations/20260407193000_widen_trace_created_at_for_sql.d.ts": {
-      "size": 335,
-      "sha256": "6e9c826a08a983927d9e801b2740f58d0cf6fbf7bff02ee5c1fd01227f73b741"
+      "size": 344,
+      "sha256": "9243e0feab40bda7bfc1e5417d93c64b28166df5326adad30bdbcf9a03a7c7fb"
     },
     "migrations/20260407193000_widen_trace_created_at_for_sql.js": {
-      "size": 1185,
-      "sha256": "1de9d8e4a91ffeaed4a0bc5cf942e428cd76bdb6b65bc67fa76ef62f3c99e94d"
+      "size": 1194,
+      "sha256": "ebb0d825d66b774f010f0fe689200ef7e3f1bcd74612d7090ff372daa9754a61"
     },
     "migrations/index.d.ts": {
       "size": 280,
@@ -146,16 +150,24 @@
       "sha256": "535869aa1bfcdf0ec26fad27d7f18bb8822bc586c38fcc5ffdde5274ecbea17e"
     },
     "register.js": {
-      "size": 19680,
-      "sha256": "042a7585e68a8a676e25f33c9a176c6f263bccb4a63090b4d2cea52b9bcdd193"
+      "size": 19896,
+      "sha256": "4516e527351016a9c2a0ea751a130cc3c42e19cd6cd817bf422663d2a613bf51"
+    },
+    "runtime/BackgroundTaskScheduler.d.ts": {
+      "size": 1182,
+      "sha256": "4ebb3549575f57210ffffce663a2f62e2d8a8ff0c56ad265259e559736ebccb2"
+    },
+    "runtime/BackgroundTaskScheduler.js": {
+      "size": 3254,
+      "sha256": "aa304666a000e6ccb0ae0a5e2bed701d610cf371955d4137a085c970fa11e230"
     },
     "storage/ProxyTraceStorage.d.ts": {
       "size": 339,
       "sha256": "9c724ff342dfe82da12e7cce95593f6623faa80c40f97593719b8e78e95f266d"
     },
     "storage/ProxyTraceStorage.js": {
-      "size": 4330,
-      "sha256": "672c95ed022504b2e5be62f3c2b31bac168ac06158d793dd020f7e38907e8f64"
+      "size": 4379,
+      "sha256": "697db8971137d42804d9abd375839f45b443589ef72d368a1b9f715fd8c5b8af"
     },
     "storage/TraceContentBudget.d.ts": {
       "size": 1306,
@@ -186,12 +198,12 @@
       "sha256": "35d93c82d6db80071946adaa8e40d012408b469949f1002f85ae3fd20b0a70c8"
     },
     "storage/TraceServiceTag.js": {
-      "size": 1916,
-      "sha256": "1ddad82563c98ddbb4033e9b8fb31901d635cffa7024d499a896f0d7a6d00900"
+      "size": 1923,
+      "sha256": "7e84325813e5399465e4794199895460aa7223c6a7b64339f0b241a7ca1295ee"
     },
     "storage/TraceStorage.d.ts": {
-      "size": 517,
-      "sha256": "c9c215aaa414f7b0c1fec6c82b054fc52bdf97af58f96f35c7f96672fb859c31"
+      "size": 526,
+      "sha256": "6de5990ca98178d909012e6678d95b30be1bfa29fdb0519974b37df60fbb3d20"
     },
     "storage/TraceStorage.js": {
       "size": 15322,
@@ -214,8 +226,8 @@
       "sha256": "ed5e83e108cd15f9a3976be71e966bdf0c44d8e0266d1d2dbad189f0885ad501"
     },
     "types.d.ts": {
-      "size": 10037,
-      "sha256": "68a2de953af2fce1a12447078177ff886f10e853c760378e13478b2558648868"
+      "size": 10214,
+      "sha256": "cc3510f7c6c859795d368a1fca2f3ec2322135387bb60bd189fd72ac833b9a7c"
     },
     "types.js": {
       "size": 696,
@@ -330,8 +342,8 @@
       "sha256": "0f58c50fd77704151399ca6cb6ec7890a9aef86afe28235951971f8cc9c1d600"
     },
     "watchers/ExceptionWatcher.js": {
-      "size": 3816,
-      "sha256": "52d21188c499fa409fa50691fee3d27ea08ad93b26199d9a42c08e76217d6de2"
+      "size": 4253,
+      "sha256": "7d4c63675bb78857ba8a7be91e11a770201fd80d2fa7ee857d2e78dab3665f15"
     },
     "watchers/GateWatcher.d.ts": {
       "size": 262,
@@ -346,16 +358,16 @@
       "sha256": "dfb13bba526d5338e4dcd7a5aa0f72a61a03d9e2f6a250250c0bb8f0054c9712"
     },
     "watchers/HttpClientWatcher.js": {
-      "size": 5898,
-      "sha256": "320b5a264f26bfeb29ba9246ffa65b79e244db715a4614d69a1425364062d5f9"
+      "size": 6335,
+      "sha256": "224b3cf85eba2e7f700a8cdcc61a0fe285ff0460a5c6550c83b0ea506e41c865"
     },
     "watchers/HttpWatcher.d.ts": {
       "size": 96,
       "sha256": "ce9a95a670f755193fd74ce721dbfa4b30f20c879a6566ebb35229b3b2435429"
     },
     "watchers/HttpWatcher.js": {
-      "size": 6880,
-      "sha256": "a69795a885d6b350012bb3be7a93a0a1a6e71070873cd172e3bd672b67b4ac08"
+      "size": 7302,
+      "sha256": "3bfe58db8346474da1efb6a5a050786e2d70d43ab02d437c116510254387735e"
     },
     "watchers/JobWatcher.d.ts": {
       "size": 441,
@@ -370,8 +382,8 @@
       "sha256": "f3ddc5f8b58c6c86ac6b464dd48e5a55e79ab2bf2e735feacffc7480e4ccc0c4"
     },
     "watchers/LogWatcher.js": {
-      "size": 3290,
-      "sha256": "0297479465b25f93ab0b11bfd6c2083afe9023fdddaa1b7841d12d68b294fa3e"
+      "size": 3626,
+      "sha256": "6b9e86824141e170a731b44c2b3af6f3dff1e06a9d09b6a7e6c9c01453b8c6cf"
     },
     "watchers/MailWatcher.d.ts": {
       "size": 244,
@@ -410,8 +422,8 @@
       "sha256": "5d5046c65e5b683369c7709f1acd09b60aec3e7f44748fd1baeb35498836465b"
     },
     "watchers/QueryWatcher.js": {
-      "size": 2855,
-      "sha256": "dcb9fe2049e71b5fc850286758737d80738a07dd470d96f36e418d4f54e16263"
+      "size": 3293,
+      "sha256": "f2d02707308e091ef065f1d6e264b7f2d799ed4a60b90efe664f9d9f7ad6266a"
     },
     "watchers/RedisWatcher.d.ts": {
       "size": 294,

package/dist/dashboard/handlers.d.ts

@@ -2,7 +2,7 @@
  * TraceDashboard handlers — pure handler functions wired to ITraceStorage.
  * No auth in this layer — caller mounts middleware as needed.
  */
-import type { IRequest, IResponse } from '@zintrust/core';
+import type { IRequest, IResponse } from '@zintrust/core/http';
 import type { ITraceStorage } from '../types';
 export declare const setHandlerStorage: (s: ITraceStorage) => void;
 export declare function listEntries(req: IRequest, res: IResponse): Promise<void>;

package/dist/dashboard/routes.d.ts

@@ -1,9 +1,4 @@
-/**
- * Dashboard route registrar for @zintrust/trace.
- * Mounts the SPA + all REST API endpoints under the configured basePath.
- * Auth is NOT applied here — callers add middleware via routeOptions.
- */
-import { type IRouter } from '@zintrust/core';
+import { type IRouter } from '@zintrust/core/http';
 import type { ITraceStorage } from '../types';
 export type TraceDashboardOptions = {
     /** Base path for the dashboard, e.g. '/trace'. Defaults to '/trace'. */

package/dist/dashboard/routes.js

@@ -3,7 +3,10 @@
  * Mounts the SPA + all REST API endpoints under the configured basePath.
  * Auth is NOT applied here — callers add middleware via routeOptions.
  */
-import { appConfig, ErrorFactory, Router, useDatabase, } from '@zintrust/core';
+import { appConfig } from '@zintrust/core/config';
+import { useDatabase } from '@zintrust/core/database';
+import { ErrorFactory } from '@zintrust/core/errors';
+import { Router } from '@zintrust/core/http';
 import { TraceConfig } from '../config.js';
 import { TraceStorage } from '../storage/index.js';
 import { assertTraceConnectionResolved, resolveDashboardTraceConnectionName, } from '../TraceConnection.js';

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export type { ITraceStorage } from './storage';
 export { TraceContentBudget } from './storage/TraceContentBudget';
 export { TraceContentRedaction } from './storage/TraceContentRedaction';
 export { TraceContext } from './context';
+export { BackgroundTaskScheduler } from './runtime/BackgroundTaskScheduler';
 export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes';
 export type { TraceDashboardOptions, TraceDashboardRegistrationOptions } from './dashboard/routes';
 export { registerTraceIngestGateway, TraceIngestGateway } from './ingest/TraceIngestGateway';

package/dist/index.js

@@ -21,6 +21,10 @@ export { TraceContentRedaction } from './storage/TraceContentRedaction.js';
 // ---------------------------------------------------------------------------
 export { TraceContext } from './context.js';
 // ---------------------------------------------------------------------------
+// Runtime
+// ---------------------------------------------------------------------------
+export { BackgroundTaskScheduler } from './runtime/BackgroundTaskScheduler.js';
+// ---------------------------------------------------------------------------
 // Dashboard
 // ---------------------------------------------------------------------------
 export { registerTraceDashboard, registerTraceRoutes } from './dashboard/routes.js';

package/dist/ingest/TraceIngestGateway.d.ts

@@ -1,4 +1,4 @@
-import { type IRouter } from '@zintrust/core';
+import { type IRouter } from '@zintrust/core/http';
 import type { ITraceStorage } from '../types';
 type TraceIngestGatewaySettings = {
     basePath: string;

package/dist/ingest/TraceIngestGateway.js

@@ -1,4 +1,8 @@
-import { Env, ErrorFactory, Router, SignedRequest, useDatabase, } from '@zintrust/core';
+import { Env } from '@zintrust/core/config';
+import { useDatabase } from '@zintrust/core/database';
+import { ErrorFactory } from '@zintrust/core/errors';
+import { Router, } from '@zintrust/core/http';
+import { SignedRequest } from '@zintrust/core/security';
 import { TraceConfig } from '../config.js';
 import { TraceStorage } from '../storage/index.js';
 const nonces = new Map();

package/dist/migrations/20260331000001_create_zin_trace_entries_table.d.ts

@@ -2,7 +2,7 @@
  * Migration: CreateZinTraceEntriesTable
  * Creates the main entries table for @zintrust/trace
  */
-import { type IDatabase } from '@zintrust/core';
+import { type IDatabase } from '@zintrust/core/database';
 export interface Migration {
     up(db: IDatabase): Promise<void>;
     down(db: IDatabase): Promise<void>;

package/dist/migrations/20260331000001_create_zin_trace_entries_table.js

@@ -2,7 +2,7 @@
  * Migration: CreateZinTraceEntriesTable
  * Creates the main entries table for @zintrust/trace
  */
-import { MigrationSchema } from '@zintrust/core';
+import { MigrationSchema } from '@zintrust/core/database';
 export const migration = {
     async up(db) {
         const schema = MigrationSchema.create(db);

package/dist/migrations/20260331000002_create_zin_trace_entries_tags_table.d.ts

@@ -2,7 +2,7 @@
  * Migration: CreateZinTraceEntriesTagsTable
  * Creates the tag join table for @zintrust/trace
  */
-import { type IDatabase } from '@zintrust/core';
+import { type IDatabase } from '@zintrust/core/database';
 export interface Migration {
     up(db: IDatabase): Promise<void>;
     down(db: IDatabase): Promise<void>;

package/dist/migrations/20260331000002_create_zin_trace_entries_tags_table.js

@@ -2,7 +2,7 @@
  * Migration: CreateZinTraceEntriesTagsTable
  * Creates the tag join table for @zintrust/trace
  */
-import { MigrationSchema } from '@zintrust/core';
+import { MigrationSchema } from '@zintrust/core/database';
 export const migration = {
     async up(db) {
         const schema = MigrationSchema.create(db);

package/dist/migrations/20260331000003_create_zin_trace_monitoring_table.d.ts

@@ -2,7 +2,7 @@
  * Migration: CreateZinTraceMonitoringTable
  * Creates the tag watchlist table for @zintrust/trace
  */
-import { type IDatabase } from '@zintrust/core';
+import { type IDatabase } from '@zintrust/core/database';
 export interface Migration {
     up(db: IDatabase): Promise<void>;
     down(db: IDatabase): Promise<void>;

package/dist/migrations/20260331000003_create_zin_trace_monitoring_table.js

@@ -2,7 +2,7 @@
  * Migration: CreateZinTraceMonitoringTable
  * Creates the tag watchlist table for @zintrust/trace
  */
-import { MigrationSchema } from '@zintrust/core';
+import { MigrationSchema } from '@zintrust/core/database';
 export const migration = {
     async up(db) {
         const schema = MigrationSchema.create(db);

package/dist/migrations/20260407193000_widen_trace_created_at_for_sql.d.ts

@@ -2,7 +2,7 @@
  * Migration: WidenTraceCreatedAtForSql
  * Ensures SQL engines that treat INTEGER as 32-bit can store millisecond timestamps.
  */
-import { type IDatabase } from '@zintrust/core';
+import { type IDatabase } from '@zintrust/core/database';
 export interface Migration {
     up(db: IDatabase): Promise<void>;
     down(db: IDatabase): Promise<void>;

package/dist/migrations/20260407193000_widen_trace_created_at_for_sql.js

@@ -2,7 +2,7 @@
  * Migration: WidenTraceCreatedAtForSql
  * Ensures SQL engines that treat INTEGER as 32-bit can store millisecond timestamps.
  */
-import { MigrationSchema } from '@zintrust/core';
+import { MigrationSchema } from '@zintrust/core/database';
 const alterCreatedAt = async (db) => {
     const driver = db.getType?.() ?? 'sqlite';
     if (driver === 'sqlite' || driver === 'd1' || driver === 'd1-remote')

package/dist/register.js

@@ -21,6 +21,7 @@
  */
 import { TraceConfig } from './config.js';
 import { TraceContext } from './context.js';
+import { BackgroundTaskScheduler } from './runtime/BackgroundTaskScheduler.js';
 import { ProxyTraceStorage, TraceServiceTag, TraceStorage } from './storage/index.js';
 import { TraceContentBudget } from './storage/TraceContentBudget.js';
 import { TraceContentRedaction } from './storage/TraceContentRedaction.js';
@@ -319,7 +320,14 @@ const createTraceWatcherArgs = async (core, Env, config) => {
         connectionName: resolvedConnectionName,
         logger: core.Logger,
     });
-    return { storage, config, db: observedDb };
+    return {
+        storage,
+        config,
+        db: observedDb,
+        scheduleBackgroundTask: (task) => {
+            BackgroundTaskScheduler.schedule(task);
+        },
+    };
 };
 const registerTraceWatchers = async (watcherArgs) => {
     const [{ HttpWatcher }, { QueryWatcher }, { LogWatcher }, { ExceptionWatcher }, { JobWatcher }, { CacheWatcher }, { ScheduleWatcher }, { MailWatcher }, { AuthWatcher }, { EventWatcher }, { ModelWatcher }, { NotificationWatcher }, { RedisWatcher }, { GateWatcher }, { MiddlewareWatcher }, { CommandWatcher }, { BatchWatcher }, { DumpWatcher }, { ViewWatcher }, { HttpClientWatcher },] = await Promise.all([

package/dist/runtime/BackgroundTaskScheduler.d.ts

@@ -0,0 +1,38 @@
+/**
+ * BackgroundTaskScheduler — runtime-agnostic background task scheduling.
+ * Maps to ctx.waitUntil() in Cloudflare Workers, normal promises in Node.
+ */
+type ExecutionContext = {
+    waitUntil(promise: Promise<unknown>): void;
+};
+type BackgroundTaskScheduler = {
+    schedule(task: Promise<void>): void;
+    isAvailable(): boolean;
+};
+export declare const BackgroundTaskScheduler: Readonly<{
+    /**
+     * Set the Worker execution context for waitUntil support.
+     * Call this from your Cloudflare Worker fetch handler:
+     *   BackgroundTaskScheduler.setExecutionContext(ctx);
+     */
+    setExecutionContext(ctx: ExecutionContext): void;
+    /**
+     * Get the current scheduler instance.
+     */
+    getScheduler(): BackgroundTaskScheduler;
+    /**
+     * Schedule a background task.
+     * In Workers: uses ctx.waitUntil() if context is set
+     * In Node: fire-and-forget with error suppression
+     */
+    schedule(task: Promise<void>): void;
+    /**
+     * Check if a proper scheduler is available (i.e., Workers context is set).
+     */
+    isAvailable(): boolean;
+    /**
+     * Reset the scheduler (useful for testing).
+     */
+    reset(): void;
+}>;
+export {};

package/dist/runtime/BackgroundTaskScheduler.js

@@ -0,0 +1,105 @@
+/**
+ * BackgroundTaskScheduler — runtime-agnostic background task scheduling.
+ * Maps to ctx.waitUntil() in Cloudflare Workers, normal promises in Node.
+ */
+let _executionContext;
+let _scheduler;
+const isCloudflareRuntime = () => {
+    const globalRef = typeof globalThis === 'undefined' ? undefined : globalThis;
+    if (!globalRef)
+        return false;
+    // @ts-ignore - navigator is available in workers
+    if (typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers') {
+        return true;
+    }
+    return (typeof globalRef.caches !== 'undefined' ||
+        typeof globalRef.WebSocketPair === 'function' ||
+        typeof globalRef.CF !== 'undefined');
+};
+const createWorkerScheduler = (ctx) => {
+    return Object.freeze({
+        schedule(task) {
+            ctx.waitUntil(task);
+        },
+        isAvailable() {
+            return true;
+        },
+    });
+};
+const createNodeScheduler = () => {
+    return Object.freeze({
+        schedule(task) {
+            // In Node, fire-and-forget is acceptable since the process doesn't terminate
+            // like Workers do. We still catch errors to prevent unhandled rejections.
+            task.catch(() => {
+                // Silently ignore background task errors to avoid noise
+                // The individual watchers handle their own error logging
+            });
+        },
+        isAvailable() {
+            return true;
+        },
+    });
+};
+const createFallbackScheduler = () => {
+    return Object.freeze({
+        schedule(task) {
+            // Fallback: fire-and-forget with error suppression
+            task.catch(() => undefined);
+        },
+        isAvailable() {
+            return false;
+        },
+    });
+};
+export const BackgroundTaskScheduler = Object.freeze({
+    /**
+     * Set the Worker execution context for waitUntil support.
+     * Call this from your Cloudflare Worker fetch handler:
+     *   BackgroundTaskScheduler.setExecutionContext(ctx);
+     */
+    setExecutionContext(ctx) {
+        _executionContext = ctx;
+        _scheduler = createWorkerScheduler(ctx);
+    },
+    /**
+     * Get the current scheduler instance.
+     */
+    getScheduler() {
+        if (_scheduler)
+            return _scheduler;
+        if (_executionContext) {
+            _scheduler = createWorkerScheduler(_executionContext);
+            return _scheduler;
+        }
+        if (isCloudflareRuntime()) {
+            // We're in Workers but no context was set - use fallback
+            _scheduler = createFallbackScheduler();
+            return _scheduler;
+        }
+        // Node.js or other runtime
+        _scheduler = createNodeScheduler();
+        return _scheduler;
+    },
+    /**
+     * Schedule a background task.
+     * In Workers: uses ctx.waitUntil() if context is set
+     * In Node: fire-and-forget with error suppression
+     */
+    schedule(task) {
+        this.getScheduler().schedule(task);
+    },
+    /**
+     * Check if a proper scheduler is available (i.e., Workers context is set).
+     */
+    isAvailable() {
+        return this.getScheduler().isAvailable();
+    },
+    /**
+     * Reset the scheduler (useful for testing).
+     */
+    reset() {
+        _executionContext = undefined;
+        _scheduler = undefined;
+    },
+});

package/dist/storage/ProxyTraceStorage.js

@@ -1,4 +1,5 @@
-import { ErrorFactory, RemoteSignedJson } from '@zintrust/core';
+import { ErrorFactory } from '@zintrust/core/errors';
+import { RemoteSignedJson } from '@zintrust/core/security';
 const ensureConfigured = (settings) => {
     if (settings.baseUrl.trim() === '') {
         throw ErrorFactory.createConfigError('TRACE_PROXY_URL is required when TRACE_PROXY=true');

package/dist/storage/TraceServiceTag.js

@@ -1,4 +1,4 @@
-import { ErrorFactory } from '@zintrust/core';
+import { ErrorFactory } from '@zintrust/core/errors';
 const appendServiceTag = (entry, serviceTag) => {
     const normalizedTag = serviceTag?.trim() ?? '';
     if (normalizedTag === '' || entry.tags.includes(normalizedTag)) {

package/dist/storage/TraceStorage.d.ts

@@ -3,7 +3,7 @@
  * Resolves the correct IDatabase from the app config, then delegates all
  * read/write operations to the trace storage facade.
  */
-import type { IDatabase } from '@zintrust/core';
+import type { IDatabase } from '@zintrust/core/database';
 import type { ITraceStorage } from '../types';
 export declare const TraceStorage: Readonly<{
     resolveStorage: (db: IDatabase) => ITraceStorage;

package/dist/types.d.ts

@@ -2,7 +2,7 @@
  * Types for @zintrust/trace
  * Sealed type definitions — no side effects.
  */
-import type { IDatabase } from '@zintrust/core';
+import type { IDatabase } from '@zintrust/core/database';
 export declare const EntryType: Readonly<{
     readonly REQUEST: "request";
     readonly QUERY: "query";
@@ -272,6 +272,8 @@ export interface ITraceWatcherConfig {
     db?: IDatabase;
     /** Optional: provide to allow HttpWatcher to register as global middleware. */
     registerMiddleware?: (fn: (req: unknown, res: unknown, next: () => Promise<void>) => Promise<void>) => void;
+    /** Optional: schedule a background task (maps to ctx.waitUntil in Workers, normal promise in Node). */
+    scheduleBackgroundTask?: (task: Promise<void>) => void;
 }
 export interface ITraceWatcher {
     register(opts: ITraceWatcherConfig): () => void;

package/dist/watchers/ExceptionWatcher.js

@@ -35,6 +35,7 @@ const buildContent = (err, context) => {
     };
 };
 let _storage = null;
+let _scheduleBackgroundTask = null;
 let _listenerRefCount = 0;
 let _ignoreRoutes = [];
 let _ignorePaths = [];
@@ -72,7 +73,7 @@ const captureException = (err, context) => {
     const content = buildContent(err, context);
     const hash = familyHash(`${content.class}:${content.file}:${content.line}`);
     const uuid = crypto.randomUUID();
-    storage
+    const writePromise = storage
         .writeEntry({
         uuid,
         batchId: context?.batchId ?? TraceContext.getBatchId(),
@@ -85,13 +86,19 @@ const captureException = (err, context) => {
     })
         .then(() => storage.markFamilyStale(hash, uuid))
         .catch(() => undefined);
+    // Use background task scheduler if available (Workers waitUntil support)
+    if (_scheduleBackgroundTask) {
+        _scheduleBackgroundTask(writePromise);
+    }
+    // Otherwise, the promise is already fire-and-forget with error suppression
 };
 export const ExceptionWatcher = Object.freeze({
     capture: captureException,
-    register({ storage, config }) {
+    register({ storage, config, scheduleBackgroundTask }) {
         if (config.watchers.exception === false)
             return () => undefined;
         _storage = storage;
+        _scheduleBackgroundTask = scheduleBackgroundTask ?? null;
         _ignoreRoutes = config.ignoreRoutes;
         _ignorePaths = config.ignorePaths;
         if (_listenerRefCount === 0) {
@@ -104,6 +111,7 @@ export const ExceptionWatcher = Object.freeze({
                 unregisterProcessListeners();
             }
             _storage = null;
+            _scheduleBackgroundTask = null;
             _ignoreRoutes = [];
             _ignorePaths = [];
         };

package/dist/watchers/HttpClientWatcher.js

@@ -4,6 +4,7 @@ import { AuthTag } from '../utils/authTag.js';
 import { redactHeaders, redactUnknown } from '../utils/redact.js';
 import { RequestFilter } from '../utils/requestFilter.js';
 let _storage = null;
+let _scheduleBackgroundTask = null;
 let _redactHeaderNames = [];
 let _redactBodyFields = [];
 let _ignoreRoutes = [];
@@ -126,7 +127,7 @@ const emit = ({ source, method, url, requestHeaders, responseStatus, duration, r
         responseBody,
         error,
     }, sourceRule, normalizedSource);
-    _storage
+    const writePromise = _storage
         .writeEntry({
         uuid: crypto.randomUUID(),
         batchId: TraceContext.getBatchId(),
@@ -137,13 +138,19 @@ const emit = ({ source, method, url, requestHeaders, responseStatus, duration, r
         createdAt: TraceContext.now(),
     })
         .catch(() => undefined);
+    // Use background task scheduler if available (Workers waitUntil support)
+    if (_scheduleBackgroundTask) {
+        _scheduleBackgroundTask(writePromise);
+    }
+    // Otherwise, the promise is already fire-and-forget with error suppression
 };
 export const HttpClientWatcher = Object.freeze({
     emit,
-    register({ storage, config }) {
+    register({ storage, config, scheduleBackgroundTask }) {
         if (!isWatcherEnabled(config.watchers.clientRequest))
             return () => undefined;
         _storage = storage;
+        _scheduleBackgroundTask = scheduleBackgroundTask ?? null;
         _clientRequestWatcher =
             typeof config.watchers.clientRequest === 'object' && config.watchers.clientRequest !== null
                 ? config.watchers.clientRequest
@@ -154,6 +161,7 @@ export const HttpClientWatcher = Object.freeze({
         _ignorePaths = config.ignorePaths;
         return () => {
             _storage = null;
+            _scheduleBackgroundTask = null;
             _clientRequestWatcher = undefined;
             _redactBodyFields = [];
             _ignoreRoutes = [];

package/dist/watchers/HttpWatcher.js

@@ -1,4 +1,4 @@
-import { Logger } from '@zintrust/core';
+import { Logger } from '@zintrust/core/logger';
 import { TraceContext } from '../context.js';
 import { EntryType } from '../types.js';
 import { AuthTag } from '../utils/authTag.js';
@@ -130,7 +130,7 @@ const shouldIgnore = (req, config) => {
 };
 const isWatcherEnabled = (config) => config.watchers.request !== false;
 export const HttpWatcher = Object.freeze({
-    register({ storage, config, registerMiddleware }) {
+    register({ storage, config, registerMiddleware, scheduleBackgroundTask, }) {
         if (!isWatcherEnabled(config))
             return () => undefined;
         if (!registerMiddleware)
@@ -162,14 +162,22 @@ export const HttpWatcher = Object.freeze({
                     isLatest: true,
                     createdAt: TraceContext.now(),
                 };
-                storage.writeEntry(entry).catch((error) => {
+                const writePromise = storage.writeEntry(entry).catch((error) => {
                     Logger.warn('[trace] HttpWatcher writeEntry failed', {
                         method: content.method,
                         uri: content.uri,
                         entryUuid: entry.uuid,
                         error: error instanceof Error ? error.message : String(error),
                     });
-                }); // fire-and-forget
+                });
+                // Use background task scheduler if available (Workers waitUntil support)
+                if (scheduleBackgroundTask) {
+                    scheduleBackgroundTask(writePromise);
+                }
+                else {
+                    // Fallback to fire-and-forget for backward compatibility
+                    writePromise.catch(() => undefined);
+                }
             };
             const completionHandler = registerCompletionHandler(response, persistEntry);
             await next();

package/dist/watchers/LogWatcher.js

@@ -1,7 +1,7 @@
 /**
  * LogWatcher — captures Logger output via Logger.addSink().
  */
-import { Logger } from '@zintrust/core';
+import { Logger } from '@zintrust/core/logger';
 import { TraceContext } from '../context.js';
 import { EntryType } from '../types.js';
 import { AuthTag } from '../utils/authTag.js';
@@ -54,7 +54,7 @@ const shouldSkipTraceInfrastructureLog = (message, context) => {
         isTraceStorageQueryLog(message, context));
 };
 export const LogWatcher = Object.freeze({
-    register({ storage, config }) {
+    register({ storage, config, scheduleBackgroundTask }) {
         if (config.watchers.log === false)
             return () => undefined;
         const minPriority = LEVEL_PRIORITY[config.logMinLevel] ?? 1;
@@ -75,7 +75,7 @@ export const LogWatcher = Object.freeze({
                 context: context ?? undefined,
                 hostname: TraceContext.getHostname(),
             };
-            storage
+            const writePromise = storage
                 .writeEntry({
                 uuid: crypto.randomUUID(),
                 batchId: TraceContext.getBatchId(),
@@ -86,6 +86,11 @@ export const LogWatcher = Object.freeze({
                 createdAt: TraceContext.now(),
             })
                 .catch(() => undefined);
+            // Use background task scheduler if available (Workers waitUntil support)
+            if (scheduleBackgroundTask) {
+                scheduleBackgroundTask(writePromise);
+            }
+            // Otherwise, the promise is already fire-and-forget with error suppression
         });
         return unsubscribe;
     },

package/dist/watchers/QueryWatcher.js

@@ -7,6 +7,7 @@ import { EntryType } from '../types.js';
 import { AuthTag } from '../utils/authTag.js';
 let _storage = null;
 let _config = null;
+let _scheduleBackgroundTask = null;
 const bindingsInterpolated = (sql, params) => {
     // Inline params for display only — safe, not for re-execution.
     let i = 0;
@@ -51,7 +52,7 @@ const emit = (query, params, duration, connection = 'default') => {
     const tags = AuthTag.append([]);
     if (slow)
         tags.push('slow');
-    _storage
+    const writePromise = _storage
         .writeEntry({
         uuid: crypto.randomUUID(),
         batchId,
@@ -63,16 +64,22 @@ const emit = (query, params, duration, connection = 'default') => {
         createdAt: TraceContext.now(),
     })
         .catch(() => undefined);
+    // Use background task scheduler if available (Workers waitUntil support)
+    if (_scheduleBackgroundTask) {
+        _scheduleBackgroundTask(writePromise);
+    }
+    // Otherwise, the promise is already fire-and-forget with error suppression
 };
 export const QueryWatcher = Object.freeze({
     emit,
-    register({ storage, config, db: injectedDb }) {
+    register({ storage, config, db: injectedDb, scheduleBackgroundTask, }) {
         if (config.watchers.query === false)
             return () => undefined;
         if (!injectedDb)
             return () => undefined; // no db available
         _storage = storage;
         _config = config;
+        _scheduleBackgroundTask = scheduleBackgroundTask ?? null;
         const db = injectedDb;
         const handler = (query, params, duration) => {
             emit(query, params, duration);
@@ -81,6 +88,7 @@ export const QueryWatcher = Object.freeze({
         return () => {
             _storage = null;
             _config = null;
+            _scheduleBackgroundTask = null;
             db.offAfterQuery?.(handler);
         };
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "2.0.0",
+  "version": "2.1.3",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",