@zintrust/trace 0.9.4 → 1.5.0

package/README.md

@@ -39,6 +39,9 @@ TRACE_PROXY_PATH=/zin/trace/write
 TRACE_PROXY_KEY_ID=           # optional — falls back to APP_NAME
 TRACE_PROXY_SECRET=           # optional — falls back to APP_KEY
 TRACE_PROXY_TIMEOUT_MS=30000
+TRACE_PROXY_MIDDLEWARE=       # optional — comma-separated route middleware applied on the receiver
+TRACE_PROXY_RATE_LIMIT_MAX=0  # optional — when > 0, adds rateLimit:<max>:<window> automatically
+TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES=0
 TRACE_PRUNE_HOURS=24          # how long entries are kept (default: 24)
 TRACE_SLOW_QUERY_MS=100       # slow-query threshold in ms (default: 100)
 TRACE_LOG_LEVEL=info          # minimum log level captured (default: info)
@@ -61,6 +64,8 @@ When `TRACE_CONTENT_QUEUE_DRIVER` is set, trace writes enqueue through that regi
 
 When `TRACE_PROXY=true`, the local runtime keeps collecting the same trace payload it would normally send to storage, but it sends the write/update/stale-family operations to `TRACE_PROXY_URL + TRACE_PROXY_PATH` instead of writing directly to the local trace database. The receiver can then persist those entries with the standard `TraceStorage` flow.
 
+On the receiver, use `TRACE_PROXY_MIDDLEWARE` for any gateway middleware such as `auth,admin`. If you want a dedicated ingest rate limit without encoding `rateLimit:<max>:<window>` by hand, set `TRACE_PROXY_RATE_LIMIT_MAX` and `TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES`; the gateway appends that parameterized rate-limit middleware automatically.
+
 This currently works with any queue driver already registered in ZinTrust. First-class Cloudflare Queue support still requires a dedicated queue driver and queue-runtime registration for that transport.
 
 ### 2. Enable the plugin in `zintrust.plugins.*`

package/dist/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.9.4",
-  "buildDate": "2026-04-23T11:29:28.904Z",
+  "version": "1.5.0",
+  "buildDate": "2026-04-24T13:06:46.205Z",
   "buildEnvironment": {
-    "node": "v22.22.1",
-    "platform": "darwin",
-    "arch": "arm64"
+    "node": "v20.20.2",
+    "platform": "linux",
+    "arch": "x64"
   },
   "git": {
-    "commit": "eebcc3ad",
-    "branch": "release"
+    "commit": "739aa697",
+    "branch": "master"
   },
   "package": {
     "engines": {
@@ -29,10 +29,6 @@
       "size": 4640,
       "sha256": "c51cc312046b6b2bbe1673f1ff9508425cc7140a1d2341907f67aa36069c09f9"
     },
-    "build-manifest.json": {
-      "size": 14744,
-      "sha256": "92fc9e1e76ba84696dbdaf02aa2ed7588c6e1234d586e24bf8bab4f54104ad61"
-    },
     "cli-register.d.ts": {
       "size": 255,
       "sha256": "da8d689fe5ef32e97e755f28017e4d3cb1aa63489073a71907ea41ad5761ede9"
@@ -87,15 +83,15 @@
     },
     "index.js": {
       "size": 3421,
-      "sha256": "478b80c6aa6c2eea2d109aa2e6fe090d77469d186b3e6a19ababb7d1f6d0be7e"
+      "sha256": "596b52f0589be73fccdf8badb2ad90ed1075aba8e71d93d040284315ba9cec01"
     },
     "ingest/TraceIngestGateway.d.ts": {
       "size": 786,
       "sha256": "3a0a46fa5bbf5367047214533ec0ee92a171ee35a60d25c197eea1eed1ff0f65"
     },
     "ingest/TraceIngestGateway.js": {
-      "size": 8456,
-      "sha256": "56df56cecda7110d1096c3beef1ef62c386f4a0e85120ebfb4cdfc5ab3b758d7"
+      "size": 10936,
+      "sha256": "c95f0e42f1294d8ae2e406a5910f8e74044c2b586e82e726876d75ddfafef27e"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.d.ts": {
       "size": 304,
@@ -153,21 +149,13 @@
       "size": 19822,
       "sha256": "c553356d90c812f7de430d5679b1d44468131433e034ae2ea89e2876b1254444"
     },
-    "storage/DebuggerStorage.d.ts": {
-      "size": 517,
-      "sha256": "c9c215aaa414f7b0c1fec6c82b054fc52bdf97af58f96f35c7f96672fb859c31"
-    },
-    "storage/DebuggerStorage.js": {
-      "size": 7442,
-      "sha256": "5ecce0fcfcf695df587a7b90a7a5c7efd2e64ad13c9f2d104b392f89f34f0dc4"
-    },
     "storage/ProxyTraceStorage.d.ts": {
       "size": 339,
       "sha256": "9c724ff342dfe82da12e7cce95593f6623faa80c40f97593719b8e78e95f266d"
     },
     "storage/ProxyTraceStorage.js": {
-      "size": 4158,
-      "sha256": "097d82e94c6ef38661fb57a20d378ba890dbacd03a22666aaf4aba4dfdedf735"
+      "size": 4330,
+      "sha256": "672c95ed022504b2e5be62f3c2b31bac168ac06158d793dd020f7e38907e8f64"
     },
     "storage/TraceContentBudget.d.ts": {
       "size": 1306,

package/dist/ingest/TraceIngestGateway.js

@@ -13,8 +13,18 @@ const parseMiddleware = (value) => value
     .split(',')
     .map((entry) => entry.trim())
     .filter((entry) => entry.length > 0);
+const isParameterizedRateLimitMiddleware = (value) => {
+    return /^rateLimit:\d+:\d+(?:\.\d+)?$/.test(value.trim());
+};
+const trimTrailingSlashes = (value) => {
+    let trimmed = value;
+    while (trimmed.endsWith('/')) {
+        trimmed = trimmed.slice(0, -1);
+    }
+    return trimmed;
+};
 const appendSuffix = (path, suffix) => {
-    const base = normalizePath(path).replace(/\/+$/, '');
+    const base = trimTrailingSlashes(normalizePath(path));
     const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
     return `${base}${tail}`;
 };
@@ -179,32 +189,101 @@ const resolveStorage = (overrides) => {
     }
     return TraceStorage.resolveStorage(db);
 };
+const readConfiguredKeyId = (overrides) => {
+    return (overrides?.keyId ?? Env.get('TRACE_PROXY_KEY_ID', '')).trim();
+};
+const readConfiguredSecret = (overrides) => {
+    return (overrides?.secret ?? Env.get('TRACE_PROXY_SECRET', '')).trim();
+};
+const resolveKeyId = (overrides) => {
+    const configuredKeyId = readConfiguredKeyId(overrides);
+    if (configuredKeyId !== '')
+        return configuredKeyId;
+    return (Env.APP_NAME || 'zintrust').trim();
+};
+const resolveSecret = (overrides) => {
+    const configuredSecret = readConfiguredSecret(overrides);
+    if (configuredSecret !== '')
+        return configuredSecret;
+    return Env.APP_KEY;
+};
+const resolveSigningWindowMs = (overrides) => {
+    return overrides?.signingWindowMs ?? Env.getInt('TRACE_PROXY_SIGNING_WINDOW_MS', 60000);
+};
+const resolveNonceTtlMs = (overrides) => {
+    return overrides?.nonceTtlMs ?? Env.getInt('TRACE_PROXY_NONCE_TTL_MS', 120000);
+};
+const resolveRateLimitMax = () => {
+    return Env.getInt('TRACE_PROXY_RATE_LIMIT_MAX', 0);
+};
+const resolveRateLimitWindowMinutes = () => {
+    const windowMinutes = Env.getFloat('TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES', 0);
+    return Math.max(windowMinutes, 0);
+};
+const createRateLimitMiddleware = () => {
+    const max = resolveRateLimitMax();
+    const windowMinutes = resolveRateLimitWindowMinutes();
+    if (!Number.isFinite(max) || !Number.isInteger(max)) {
+        throw ErrorFactory.createConfigError('TRACE_PROXY_RATE_LIMIT_MAX must be a valid integer', {
+            value: max,
+            envKey: 'TRACE_PROXY_RATE_LIMIT_MAX',
+        });
+    }
+    if (!Number.isFinite(windowMinutes)) {
+        throw ErrorFactory.createConfigError('TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES must be a valid number', {
+            value: windowMinutes,
+            envKey: 'TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES',
+        });
+    }
+    if (max <= 0 || windowMinutes <= 0) {
+        return undefined;
+    }
+    return `rateLimit:${max}:${windowMinutes}`;
+};
+const resolveMiddleware = (overrides) => {
+    if (overrides?.middleware !== undefined) {
+        return overrides.middleware;
+    }
+    const configured = parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', ''));
+    const rateLimitMiddleware = createRateLimitMiddleware();
+    if (rateLimitMiddleware === undefined) {
+        return configured;
+    }
+    return [
+        ...configured.filter((entry) => !isParameterizedRateLimitMiddleware(entry)),
+        rateLimitMiddleware,
+    ];
+};
 const readSettings = (overrides) => {
-    const configuredSecret = (overrides?.secret ?? Env.get('TRACE_PROXY_SECRET', '')).trim();
-    const configuredKeyId = (overrides?.keyId ?? Env.get('TRACE_PROXY_KEY_ID', '')).trim();
     return {
         basePath: normalizePath(overrides?.basePath ?? Env.get('TRACE_PROXY_PATH', '/zin/trace/write')),
-        keyId: configuredKeyId === '' ? (Env.APP_NAME || 'zintrust').trim() : configuredKeyId,
-        secret: configuredSecret === '' ? Env.APP_KEY : configuredSecret,
-        signingWindowMs: overrides?.signingWindowMs ?? Env.getInt('TRACE_PROXY_SIGNING_WINDOW_MS', 60000),
-        nonceTtlMs: overrides?.nonceTtlMs ?? Env.getInt('TRACE_PROXY_NONCE_TTL_MS', 120000),
-        middleware: overrides?.middleware ?? parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', '')),
+        keyId: resolveKeyId(overrides),
+        secret: resolveSecret(overrides),
+        signingWindowMs: resolveSigningWindowMs(overrides),
+        nonceTtlMs: resolveNonceTtlMs(overrides),
+        middleware: resolveMiddleware(overrides),
         storage: resolveStorage(overrides),
     };
 };
+const getRouteOptions = (settings) => {
+    if (settings.middleware.length === 0)
+        return undefined;
+    return { middleware: settings.middleware };
+};
+const registerRoutes = (router, settings) => {
+    const routeOptions = getRouteOptions(settings);
+    const updatePath = appendSuffix(settings.basePath, '/update');
+    const markFamilyStalePath = appendSuffix(settings.basePath, '/mark-family-stale');
+    Router.post(router, settings.basePath, createWriteHandler(settings, settings.basePath), routeOptions);
+    Router.post(router, updatePath, createUpdateHandler(settings, updatePath), routeOptions);
+    Router.post(router, markFamilyStalePath, createMarkFamilyStaleHandler(settings, markFamilyStalePath), routeOptions);
+};
 export const TraceIngestGateway = Object.freeze({
     create(overrides) {
         const settings = readSettings(overrides);
-        const routeOptions = settings.middleware.length > 0
-            ? { middleware: settings.middleware }
-            : undefined;
-        const updatePath = appendSuffix(settings.basePath, '/update');
-        const markFamilyStalePath = appendSuffix(settings.basePath, '/mark-family-stale');
         return {
             registerRoutes(router) {
-                Router.post(router, settings.basePath, createWriteHandler(settings, settings.basePath), routeOptions);
-                Router.post(router, updatePath, createUpdateHandler(settings, updatePath), routeOptions);
-                Router.post(router, markFamilyStalePath, createMarkFamilyStaleHandler(settings, markFamilyStalePath), routeOptions);
+                registerRoutes(router, settings);
             },
         };
     },

package/dist/storage/ProxyTraceStorage.js

@@ -13,6 +13,13 @@ const normalizePath = (value) => {
         return '/zin/trace/write';
     return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
 };
+const trimTrailingSlashes = (value) => {
+    let trimmed = value;
+    while (trimmed.endsWith('/')) {
+        trimmed = trimmed.slice(0, -1);
+    }
+    return trimmed;
+};
 const createUnsupportedReadError = () => ErrorFactory.createConfigError('Trace proxy sender storage does not expose dashboard/query operations. Use the trace server for reads.');
 const buildSettings = (settings) => {
     ensureConfigured(settings);
@@ -37,7 +44,7 @@ const buildSettings = (settings) => {
     };
 };
 const appendSuffix = (path, suffix) => {
-    const base = normalizePath(path).replace(/\/+$/, '');
+    const base = trimTrailingSlashes(normalizePath(path));
     const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
     return `${base}${tail}`;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.9.4",
+  "version": "1.5.0",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.9.4"
+    "@zintrust/core": "^1.2.0"
   },
   "publishConfig": {
     "access": "public"

package/src/ingest/TraceIngestGateway.ts

@@ -56,8 +56,20 @@ const parseMiddleware = (value: string): ReadonlyArray<string> =>
     .map((entry) => entry.trim())
     .filter((entry) => entry.length > 0);
 
+const isParameterizedRateLimitMiddleware = (value: string): boolean => {
+  return /^rateLimit:\d+:\d+(?:\.\d+)?$/.test(value.trim());
+};
+
+const trimTrailingSlashes = (value: string): string => {
+  let trimmed = value;
+  while (trimmed.endsWith('/')) {
+    trimmed = trimmed.slice(0, -1);
+  }
+  return trimmed;
+};
+
 const appendSuffix = (path: string, suffix: string): string => {
-  const base = normalizePath(path).replace(/\/+$/, '');
+  const base = trimTrailingSlashes(normalizePath(path));
   const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
   return `${base}${tail}`;
 };
@@ -259,49 +271,134 @@ const resolveStorage = (overrides?: TraceIngestGatewayOverrides): ITraceStorage
   return TraceStorage.resolveStorage(db);
 };
 
-const readSettings = (overrides?: TraceIngestGatewayOverrides): TraceIngestGatewaySettings => {
-  const configuredSecret = (overrides?.secret ?? Env.get('TRACE_PROXY_SECRET', '')).trim();
-  const configuredKeyId = (overrides?.keyId ?? Env.get('TRACE_PROXY_KEY_ID', '')).trim();
+const readConfiguredKeyId = (overrides?: TraceIngestGatewayOverrides): string => {
+  return (overrides?.keyId ?? Env.get('TRACE_PROXY_KEY_ID', '')).trim();
+};
+
+const readConfiguredSecret = (overrides?: TraceIngestGatewayOverrides): string => {
+  return (overrides?.secret ?? Env.get('TRACE_PROXY_SECRET', '')).trim();
+};
+
+const resolveKeyId = (overrides?: TraceIngestGatewayOverrides): string => {
+  const configuredKeyId = readConfiguredKeyId(overrides);
+  if (configuredKeyId !== '') return configuredKeyId;
+  return (Env.APP_NAME || 'zintrust').trim();
+};
+
+const resolveSecret = (overrides?: TraceIngestGatewayOverrides): string => {
+  const configuredSecret = readConfiguredSecret(overrides);
+  if (configuredSecret !== '') return configuredSecret;
+  return Env.APP_KEY;
+};
+
+const resolveSigningWindowMs = (overrides?: TraceIngestGatewayOverrides): number => {
+  return overrides?.signingWindowMs ?? Env.getInt('TRACE_PROXY_SIGNING_WINDOW_MS', 60000);
+};
+
+const resolveNonceTtlMs = (overrides?: TraceIngestGatewayOverrides): number => {
+  return overrides?.nonceTtlMs ?? Env.getInt('TRACE_PROXY_NONCE_TTL_MS', 120000);
+};
+
+const resolveRateLimitMax = (): number => {
+  return Env.getInt('TRACE_PROXY_RATE_LIMIT_MAX', 0);
+};
+
+const resolveRateLimitWindowMinutes = (): number => {
+  const windowMinutes = Env.getFloat('TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES', 0);
+  return Math.max(windowMinutes, 0);
+};
+
+const createRateLimitMiddleware = (): string | undefined => {
+  const max = resolveRateLimitMax();
+  const windowMinutes = resolveRateLimitWindowMinutes();
 
+  if (!Number.isFinite(max) || !Number.isInteger(max)) {
+    throw ErrorFactory.createConfigError('TRACE_PROXY_RATE_LIMIT_MAX must be a valid integer', {
+      value: max,
+      envKey: 'TRACE_PROXY_RATE_LIMIT_MAX',
+    });
+  }
+
+  if (!Number.isFinite(windowMinutes)) {
+    throw ErrorFactory.createConfigError(
+      'TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES must be a valid number',
+      {
+        value: windowMinutes,
+        envKey: 'TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES',
+      }
+    );
+  }
+
+  if (max <= 0 || windowMinutes <= 0) {
+    return undefined;
+  }
+
+  return `rateLimit:${max}:${windowMinutes}`;
+};
+
+const resolveMiddleware = (overrides?: TraceIngestGatewayOverrides): ReadonlyArray<string> => {
+  if (overrides?.middleware !== undefined) {
+    return overrides.middleware;
+  }
+
+  const configured = parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', ''));
+  const rateLimitMiddleware = createRateLimitMiddleware();
+  if (rateLimitMiddleware === undefined) {
+    return configured;
+  }
+
+  return [
+    ...configured.filter((entry) => !isParameterizedRateLimitMiddleware(entry)),
+    rateLimitMiddleware,
+  ];
+};
+
+const readSettings = (overrides?: TraceIngestGatewayOverrides): TraceIngestGatewaySettings => {
   return {
     basePath: normalizePath(overrides?.basePath ?? Env.get('TRACE_PROXY_PATH', '/zin/trace/write')),
-    keyId: configuredKeyId === '' ? (Env.APP_NAME || 'zintrust').trim() : configuredKeyId,
-    secret: configuredSecret === '' ? Env.APP_KEY : configuredSecret,
-    signingWindowMs:
-      overrides?.signingWindowMs ?? Env.getInt('TRACE_PROXY_SIGNING_WINDOW_MS', 60000),
-    nonceTtlMs: overrides?.nonceTtlMs ?? Env.getInt('TRACE_PROXY_NONCE_TTL_MS', 120000),
-    middleware: overrides?.middleware ?? parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', '')),
+    keyId: resolveKeyId(overrides),
+    secret: resolveSecret(overrides),
+    signingWindowMs: resolveSigningWindowMs(overrides),
+    nonceTtlMs: resolveNonceTtlMs(overrides),
+    middleware: resolveMiddleware(overrides),
     storage: resolveStorage(overrides),
   };
 };
 
+const getRouteOptions = (settings: TraceIngestGatewaySettings): RouteOptions | undefined => {
+  if (settings.middleware.length === 0) return undefined;
+  return { middleware: settings.middleware } as RouteOptions;
+};
+
+const registerRoutes = (router: IRouter, settings: TraceIngestGatewaySettings): void => {
+  const routeOptions = getRouteOptions(settings);
+  const updatePath = appendSuffix(settings.basePath, '/update');
+  const markFamilyStalePath = appendSuffix(settings.basePath, '/mark-family-stale');
+
+  Router.post(
+    router,
+    settings.basePath,
+    createWriteHandler(settings, settings.basePath),
+    routeOptions
+  );
+  Router.post(router, updatePath, createUpdateHandler(settings, updatePath), routeOptions);
+  Router.post(
+    router,
+    markFamilyStalePath,
+    createMarkFamilyStaleHandler(settings, markFamilyStalePath),
+    routeOptions
+  );
+};
+
 export const TraceIngestGateway = Object.freeze({
   create(overrides?: TraceIngestGatewayOverrides): {
     registerRoutes: (router: IRouter) => void;
   } {
     const settings = readSettings(overrides);
-    const routeOptions: RouteOptions | undefined =
-      settings.middleware.length > 0
-        ? ({ middleware: settings.middleware } as RouteOptions)
-        : undefined;
-    const updatePath = appendSuffix(settings.basePath, '/update');
-    const markFamilyStalePath = appendSuffix(settings.basePath, '/mark-family-stale');
 
     return {
       registerRoutes(router: IRouter): void {
-        Router.post(
-          router,
-          settings.basePath,
-          createWriteHandler(settings, settings.basePath),
-          routeOptions
-        );
-        Router.post(router, updatePath, createUpdateHandler(settings, updatePath), routeOptions);
-        Router.post(
-          router,
-          markFamilyStalePath,
-          createMarkFamilyStaleHandler(settings, markFamilyStalePath),
-          routeOptions
-        );
+        registerRoutes(router, settings);
       },
     };
   },

package/src/storage/ProxyTraceStorage.ts

@@ -41,6 +41,14 @@ const normalizePath = (value: string): string => {
   return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
 };
 
+const trimTrailingSlashes = (value: string): string => {
+  let trimmed = value;
+  while (trimmed.endsWith('/')) {
+    trimmed = trimmed.slice(0, -1);
+  }
+  return trimmed;
+};
+
 const createUnsupportedReadError = (): Error =>
   ErrorFactory.createConfigError(
     'Trace proxy sender storage does not expose dashboard/query operations. Use the trace server for reads.'
@@ -90,7 +98,7 @@ const buildSettings = (settings: ProxyTraceStorageSettings): ProxyRequestSetting
 };
 
 const appendSuffix = (path: string, suffix: string): string => {
-  const base = normalizePath(path).replace(/\/+$/, '');
+  const base = trimTrailingSlashes(normalizePath(path));
   const tail = suffix.startsWith('/') ? suffix : `/${suffix}`;
   return `${base}${tail}`;
 };

package/dist/storage/DebuggerStorage.d.ts

@@ -1,13 +0,0 @@
-/**
- * TraceStorage — sealed namespace wrapping the D1/SQLite driver.
- * 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 { ITraceStorage } from '../types';
-export declare const TraceStorage: Readonly<{
-    resolveStorage: (db: IDatabase) => ITraceStorage;
-    reset: () => void;
-    familyHash: (input: string) => string;
-}>;
-export { type ITraceStorage } from '../types';

package/dist/storage/DebuggerStorage.js

@@ -1,195 +0,0 @@
-import { familyHash } from '../utils/familyHash.js';
-const TABLE_ENTRIES = 'zin_trace_entries';
-const TABLE_TAGS = 'zin_trace_entries_tags';
-const TABLE_MONITORING = 'zin_trace_monitoring';
-const generateUuid = () => crypto.randomUUID();
-const rowToEntry = (row, tags) => ({
-    uuid: row.uuid,
-    batchId: row.batch_id,
-    familyHash: row.family_hash ?? undefined,
-    type: row.type,
-    content: JSON.parse(row.content),
-    tags,
-    isLatest: Boolean(row.is_latest),
-    createdAt: row.created_at,
-});
-const insertTags = async (db, uuid, tags) => {
-    if (tags.length === 0)
-        return;
-    await Promise.all(tags.map(async (tag) => {
-        await db.execute(`INSERT OR IGNORE INTO ${TABLE_TAGS} (entry_uuid, tag) VALUES (?, ?)`, [
-            uuid,
-            tag,
-        ]);
-    }));
-};
-const buildEntryFilters = (opts) => {
-    const conditions = [];
-    const params = [];
-    if (opts.type) {
-        conditions.push('e.type = ?');
-        params.push(opts.type);
-    }
-    if (opts.batchId) {
-        conditions.push('e.batch_id = ?');
-        params.push(opts.batchId);
-    }
-    if (opts.from) {
-        conditions.push('e.created_at >= ?');
-        params.push(opts.from);
-    }
-    if (opts.to) {
-        conditions.push('e.created_at <= ?');
-        params.push(opts.to);
-    }
-    let joinClause = '';
-    if (opts.tag) {
-        joinClause = `INNER JOIN ${TABLE_TAGS} t ON t.entry_uuid = e.uuid AND t.tag = ?`;
-        params.unshift(opts.tag);
-    }
-    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
-    const countParams = opts.tag ? [opts.tag, ...params.slice(1)] : [...params];
-    return { joinClause, whereClause, params, countParams };
-};
-const loadTagsByUuid = async (db, uuids) => {
-    const tagsByUuid = new Map();
-    if (uuids.length === 0)
-        return tagsByUuid;
-    const tagRows = (await db.query(`SELECT entry_uuid, tag FROM ${TABLE_TAGS} WHERE entry_uuid IN (${uuids.map(() => '?').join(',')})`, uuids));
-    for (const tagRow of tagRows) {
-        const tags = tagsByUuid.get(tagRow.entry_uuid) ?? [];
-        tags.push(tagRow.tag);
-        tagsByUuid.set(tagRow.entry_uuid, tags);
-    }
-    return tagsByUuid;
-};
-// The storage facade intentionally groups related DB operations in one factory.
-// eslint-disable-next-line max-lines-per-function
-const createStorage = (db) => {
-    const writeEntry = async (entry) => {
-        const uuid = entry.uuid || generateUuid();
-        await db.execute(`INSERT INTO ${TABLE_ENTRIES} (uuid, batch_id, family_hash, type, content, is_latest, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`, [
-            uuid,
-            entry.batchId,
-            entry.familyHash ?? null,
-            entry.type,
-            JSON.stringify(entry.content),
-            entry.isLatest ? 1 : 0,
-            entry.createdAt,
-        ]);
-        await insertTags(db, uuid, entry.tags);
-    };
-    const updateEntry = async (uuid, patch) => {
-        const sets = [];
-        const params = [];
-        if (patch.content !== undefined) {
-            sets.push('content = ?');
-            params.push(JSON.stringify(patch.content));
-        }
-        if (patch.isLatest !== undefined) {
-            sets.push('is_latest = ?');
-            params.push(patch.isLatest ? 1 : 0);
-        }
-        if (sets.length === 0)
-            return;
-        params.push(uuid);
-        await db.execute(`UPDATE ${TABLE_ENTRIES} SET ${sets.join(', ')} WHERE uuid = ?`, params);
-    };
-    const markFamilyStale = async (hash, exceptUuid) => {
-        await db.execute(`UPDATE ${TABLE_ENTRIES} SET is_latest = 0
-       WHERE family_hash = ? AND uuid != ? AND is_latest = 1`, [hash, exceptUuid]);
-    };
-    const queryEntries = async (opts) => {
-        const page = opts.page ?? 1;
-        const perPage = opts.perPage ?? 50;
-        const offset = (page - 1) * perPage;
-        const { joinClause, whereClause, params, countParams } = buildEntryFilters(opts);
-        const countResult = (await db.queryOne(`SELECT COUNT(*) as cnt FROM ${TABLE_ENTRIES} e ${joinClause} ${whereClause}`, countParams));
-        const total = countResult?.cnt ?? 0;
-        const rows = (await db.query(`SELECT e.id, e.uuid, e.batch_id, e.family_hash, e.type, e.content, e.is_latest, e.created_at
-       FROM ${TABLE_ENTRIES} e ${joinClause} ${whereClause}
-       ORDER BY e.created_at DESC, e.id DESC
-       LIMIT ? OFFSET ?`, [...params, perPage, offset]));
-        const tagsByUuid = await loadTagsByUuid(db, rows.map((row) => row.uuid));
-        return {
-            data: rows.map((row) => rowToEntry(row, tagsByUuid.get(row.uuid) ?? [])),
-            total,
-        };
-    };
-    const getEntry = async (uuid) => {
-        const row = (await db.queryOne(`SELECT id, uuid, batch_id, family_hash, type, content, is_latest, created_at
-       FROM ${TABLE_ENTRIES}
-       WHERE uuid = ?`, [uuid]));
-        if (!row)
-            return null;
-        const tags = (await db.query(`SELECT tag FROM ${TABLE_TAGS} WHERE entry_uuid = ?`, [
-            uuid,
-        ]));
-        return rowToEntry(row, tags.map((tag) => tag.tag));
-    };
-    const getBatch = async (batchId) => {
-        const rows = (await db.query(`SELECT id, uuid, batch_id, family_hash, type, content, is_latest, created_at
-       FROM ${TABLE_ENTRIES}
-       WHERE batch_id = ?
-       ORDER BY created_at ASC, id ASC`, [batchId]));
-        if (rows.length === 0)
-            return [];
-        const tagsByUuid = await loadTagsByUuid(db, rows.map((row) => row.uuid));
-        return rows.map((row) => rowToEntry(row, tagsByUuid.get(row.uuid) ?? []));
-    };
-    const prune = async (olderThanMs, keepExceptions = false) => {
-        const countResult = (await db.queryOne(`SELECT COUNT(*) as cnt FROM ${TABLE_ENTRIES}
-       WHERE created_at < ?
-       ${keepExceptions ? "AND type != 'exception'" : ''}`, [olderThanMs]));
-        const deleted = countResult?.cnt ?? 0;
-        if (deleted === 0)
-            return 0;
-        await db.execute(`DELETE FROM ${TABLE_ENTRIES}
-       WHERE created_at < ?
-       ${keepExceptions ? "AND type != 'exception'" : ''}`, [olderThanMs]);
-        return deleted;
-    };
-    const clear = async () => {
-        await db.execute(`DELETE FROM ${TABLE_ENTRIES}`, []);
-    };
-    const getMonitoring = async () => {
-        const rows = (await db.query(`SELECT tag FROM ${TABLE_MONITORING}`, []));
-        return rows.map((row) => row.tag);
-    };
-    const addMonitoring = async (tag) => {
-        await db.execute(`INSERT OR IGNORE INTO ${TABLE_MONITORING} (tag) VALUES (?)`, [tag]);
-    };
-    const removeMonitoring = async (tag) => {
-        await db.execute(`DELETE FROM ${TABLE_MONITORING} WHERE tag = ?`, [tag]);
-    };
-    const stats = async () => {
-        const rows = (await db.query(`SELECT type, COUNT(*) as cnt FROM ${TABLE_ENTRIES} GROUP BY type`, []));
-        const output = {};
-        for (const row of rows) {
-            output[row.type] = row.cnt;
-        }
-        return output;
-    };
-    return {
-        writeEntry,
-        updateEntry,
-        markFamilyStale,
-        queryEntries,
-        getEntry,
-        getBatch,
-        prune,
-        clear,
-        getMonitoring,
-        addMonitoring,
-        removeMonitoring,
-        stats,
-    };
-};
-const resolveStorage = (db) => {
-    return createStorage(db);
-};
-const reset = () => {
-    return;
-};
-export const TraceStorage = Object.freeze({ resolveStorage, reset, familyHash });