@gobing-ai/ts-infra 0.4.38 → 0.4.40

package/README.md

@@ -275,6 +275,8 @@ The consumer claims ready jobs, resets stuck processing jobs after the visibilit
 
 `stop()` drains gracefully: it stops polling, then waits for work already in flight — including a poll cycle that has claimed nothing yet — before resolving. The wait is capped by `drainTimeoutMs` (default 30s) so a stuck handler cannot block shutdown; when the cap is hit, `queue.consumer.stopped` reports `drained: false` with the outstanding `inFlightAtStop` count.
 
+**Queue identity.** Once a consumer is event-enabled (an `events` bus is configured), it **must** supply a non-empty, already-trimmed `queueName` — construction throws `Queue consumer queueName …` otherwise, so an observable consumer can never emit an anonymous `queue.consumer.started`/`queue.consumer.stopped` row. The name is validated, never normalized, and is emitted byte-for-byte as `queueName` on both lifecycle details. Silent consumers (no `events`) may omit identity entirely.
+
 **Queue lifecycle events** are opt-in through the injected `EventBus`:
 
 ```ts
@@ -291,7 +293,10 @@ events.on('queue.consumer.started', () => { /* ... */ });
 events.on('queue.consumer.stopped', () => { /* ... */ });
 
 const queue = new DBJobQueue<Payload>(dao, events);                // emits enqueued
-const consumer = new DBQueueConsumer<Payload>(dao, { events });    // emits the rest
+const consumer = new DBQueueConsumer<Payload>(dao, {
+    events,                             // emits lifecycle + job events
+    queueName: 'email-jobs',            // required when `events` is configured (ADR-068)
+});
 ```
 
 ### Scheduler — cron-like actions

package/dist/events.d.ts

@@ -47,6 +47,8 @@ export interface QueueJobEnqueuedDetail extends QueueJobRef, WithEventSeverity {
 }
 /** Payload for `queue.consumer.started` — the polling loop began. */
 export interface QueueConsumerStartedDetail extends WithEventSeverity {
+    /** Queue identity the consumer polls (validated `QueueConsumerConfig.queueName`). */
+    queueName: string;
     /** Epoch ms when the consumer was started. */
     startedAt: number;
     /** Polling interval in ms. */
@@ -60,6 +62,8 @@ export interface QueueConsumerStartedDetail extends WithEventSeverity {
 }
 /** Payload for `queue.consumer.stopped` — the polling loop was halted. */
 export interface QueueConsumerStoppedDetail extends WithEventSeverity {
+    /** Queue identity the consumer polls (validated `QueueConsumerConfig.queueName`). */
+    queueName: string;
     /** Epoch ms when `stop()` was called. */
     stoppedAt: number;
     /** Drain deadline in ms applied to in-flight handlers at stop time. */

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/job-queue/db-job-queue.d.ts

@@ -25,7 +25,11 @@ export declare class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private readonly baseDelay;
     private readonly maxDelay;
     private readonly drainTimeoutMs;
-    private readonly events;
+    /**
+     * Validated event sink: the bus plus the non-empty queue name its lifecycle rows
+     * require (ADR-068). `undefined` for silent consumers — no `events`, no identity.
+     */
+    private readonly eventSink;
     private timer;
     private running;
     private inFlight;

package/dist/job-queue/db-job-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db-job-queue.d.ts","sourceRoot":"","sources":["../../src/job-queue/db-job-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAkB,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAER,WAAW,EAKd,MAAM,WAAW,CAAC;AAUnB,OAAO,KAAK,EAAE,cAAc,EAAO,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAQ7G,kFAAkF;AAClF,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;IAEnD,QAAQ,CAAC,GAAG,EAAE,WAAW;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBADf,GAAG,EAAE,WAAW,EACR,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,YAAA;IAG7C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAO5E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAY3F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;CAGrC;AAcD,qFAAqF;AACrF,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAgB7D,OAAO,CAAC,QAAQ,CAAC,GAAG;IAfxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAC3D,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAA8B;gBAG5B,GAAG,EAAE,WAAW,EACjC,MAAM,GAAE,mBAAwB;IAYpC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAI9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IActB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoCrB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAIlC,sFAAsF;IAChF,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IA4BpC,OAAO,CAAC,QAAQ;YAWF,IAAI;YAgBJ,UAAU;YA8CV,WAAW;CAqC5B"}
+{"version":3,"file":"db-job-queue.d.ts","sourceRoot":"","sources":["../../src/job-queue/db-job-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAkB,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EACR,WAAW,EAKd,MAAM,WAAW,CAAC;AAUnB,OAAO,KAAK,EAAE,cAAc,EAAO,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAQ7G,kFAAkF;AAClF,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;IAEnD,QAAQ,CAAC,GAAG,EAAE,WAAW;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBADf,GAAG,EAAE,WAAW,EACR,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,YAAA;IAG7C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAO5E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAY3F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;CAGrC;AAcD,qFAAqF;AACrF,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAoB7D,OAAO,CAAC,QAAQ,CAAC,GAAG;IAnBxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgE;IAC1F,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAA8B;gBAG5B,GAAG,EAAE,WAAW,EACjC,MAAM,GAAE,mBAAwB;IAYpC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAI9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAuCrB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAIlC,sFAAsF;IAChF,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IA4BpC,OAAO,CAAC,QAAQ;YAWF,IAAI;YAgBJ,UAAU;YA8CV,WAAW;CAqC5B"}

package/dist/job-queue/db-job-queue.js

@@ -62,7 +62,11 @@ export class DBQueueConsumer {
     baseDelay;
     maxDelay;
     drainTimeoutMs;
-    events;
+    /**
+     * Validated event sink: the bus plus the non-empty queue name its lifecycle rows
+     * require (ADR-068). `undefined` for silent consumers — no `events`, no identity.
+     */
+    eventSink;
     timer = null;
     running = false;
     inFlight = 0;
@@ -76,7 +80,7 @@ export class DBQueueConsumer {
         this.baseDelay = nonNegativeFiniteConfig('baseDelay', config.baseDelay ?? 1_000);
         this.maxDelay = nonNegativeFiniteConfig('maxDelay', config.maxDelay ?? 60_000);
         this.drainTimeoutMs = nonNegativeFiniteConfig('drainTimeoutMs', config.drainTimeoutMs ?? 30_000);
-        this.events = config.events;
+        this.eventSink = resolveEventSink(config);
     }
     register(type, handler) {
         this.handlers.set(type, handler);
@@ -86,14 +90,18 @@ export class DBQueueConsumer {
             return;
         this.running = true;
         this.schedule(0);
-        await this.events?.emit('queue.consumer.started', {
-            startedAt: Date.now(),
-            pollInterval: this.pollInterval,
-            batchSize: this.batchSize,
-            maxConcurrency: this.maxConcurrency,
-            visibilityTimeout: this.visibilityTimeout,
-            severity: 'info',
-        });
+        const sink = this.eventSink;
+        if (sink !== undefined) {
+            await sink.bus.emit('queue.consumer.started', {
+                startedAt: Date.now(),
+                pollInterval: this.pollInterval,
+                batchSize: this.batchSize,
+                maxConcurrency: this.maxConcurrency,
+                visibilityTimeout: this.visibilityTimeout,
+                queueName: sink.queueName,
+                severity: 'info',
+            });
+        }
     }
     async stop() {
         const wasRunning = this.running;
@@ -117,14 +125,17 @@ export class DBQueueConsumer {
         }
         if (wasRunning) {
             const drained = this.inFlight === 0;
-            const detail = {
-                stoppedAt: Date.now(),
-                drainTimeoutMs: this.drainTimeoutMs,
-                inFlightAtStop: this.inFlight,
-                drained,
-                severity: drained ? 'info' : 'warning',
-            };
-            await this.events?.emit('queue.consumer.stopped', detail);
+            const sink = this.eventSink;
+            if (sink !== undefined) {
+                await sink.bus.emit('queue.consumer.stopped', {
+                    stoppedAt: Date.now(),
+                    drainTimeoutMs: this.drainTimeoutMs,
+                    inFlightAtStop: this.inFlight,
+                    drained,
+                    queueName: sink.queueName,
+                    severity: drained ? 'info' : 'warning',
+                });
+            }
         }
     }
     async stats() {
@@ -220,7 +231,7 @@ export class DBQueueConsumer {
                     attempt: job.attempts,
                     severity: 'info',
                 };
-                await this.events?.emit('queue.job.completed', completed);
+                await this.eventSink?.bus.emit('queue.job.completed', completed);
             }
             catch (error) {
                 const durationMs = performance.now() - startMs;
@@ -244,7 +255,7 @@ export class DBQueueConsumer {
                 durationMs,
                 severity: 'error',
             };
-            await this.events?.emit('queue.job.failed', failed);
+            await this.eventSink?.bus.emit('queue.job.failed', failed);
             return;
         }
         const delay = Math.min(this.maxDelay, this.baseDelay * 2 ** Math.max(0, attempts - 1));
@@ -259,7 +270,7 @@ export class DBQueueConsumer {
             error: message,
             severity: 'warning',
         };
-        await this.events?.emit('queue.job.retrying', retrying);
+        await this.eventSink?.bus.emit('queue.job.retrying', retrying);
     }
 }
 function toJob(record) {
@@ -300,3 +311,23 @@ function nonNegativeFiniteConfig(name, value) {
     }
     return value;
 }
+/**
+ * Resolve the validated event sink from `QueueConsumerConfig`: any supplied `queueName`
+ * must be non-empty and already trimmed, and an event-enabled consumer (one with an
+ * `events` bus) must supply one. Silent consumers may omit identity because they emit no
+ * lifecycle rows. The name is validated but never normalized — the emitted detail is
+ * byte-for-byte the config.
+ */
+function resolveEventSink(config) {
+    const name = config.queueName;
+    if (name !== undefined && (name.length === 0 || name.trim() !== name)) {
+        throw new TypeError(`Queue consumer queueName must be a non-empty, already-trimmed string; received ${JSON.stringify(name)}`);
+    }
+    if (config.events === undefined) {
+        return undefined;
+    }
+    if (name === undefined) {
+        throw new TypeError('Queue consumer queueName is required when events is configured');
+    }
+    return { bus: config.events, queueName: name };
+}

package/dist/job-queue/types.d.ts

@@ -56,6 +56,13 @@ export interface QueueConsumerConfig {
     maxDelay?: number;
     /** Upper bound (ms, default 30_000) on how long `stop()` waits for in-flight work to drain. */
     drainTimeoutMs?: number;
+    /**
+     * Identity of the queue this consumer polls. Runtime-required whenever `events` is
+     * configured (ADR-068): an observable consumer must never emit an anonymous lifecycle
+     * row. Silent consumers (no `events`) may omit it. A supplied value must be non-empty
+     * and already trimmed; it is validated but never normalized.
+     */
+    queueName?: string;
     /**
      * Optional bus for queue lifecycle events with correlator-grade detail payloads:
      * `queue.consumer.started` / `queue.consumer.stopped` (config snapshot + drain

package/dist/job-queue/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/job-queue/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,yEAAyE;AACzE,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC;AAED,iDAAiD;AACjD,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAErE,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAClC;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/job-queue/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,yEAAyE;AACzE,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACjC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC;AAED,iDAAiD;AACjD,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAErE,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAClC;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.4.38",
+    "version": "0.4.40",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -78,12 +78,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-infra-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.4.38",
+        "@gobing-ai/ts-utils": "^0.4.40",
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.38",
-        "@gobing-ai/ts-runtime": "^0.4.38",
+        "@gobing-ai/ts-db": "^0.4.40",
+        "@gobing-ai/ts-runtime": "^0.4.40",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -116,8 +116,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.38",
-        "@gobing-ai/ts-runtime": "^0.4.38",
+        "@gobing-ai/ts-db": "^0.4.40",
+        "@gobing-ai/ts-runtime": "^0.4.40",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/events.ts

@@ -55,6 +55,8 @@ export interface QueueJobEnqueuedDetail extends QueueJobRef, WithEventSeverity {
 
 /** Payload for `queue.consumer.started` — the polling loop began. */
 export interface QueueConsumerStartedDetail extends WithEventSeverity {
+    /** Queue identity the consumer polls (validated `QueueConsumerConfig.queueName`). */
+    queueName: string;
     /** Epoch ms when the consumer was started. */
     startedAt: number;
     /** Polling interval in ms. */
@@ -69,6 +71,8 @@ export interface QueueConsumerStartedDetail extends WithEventSeverity {
 
 /** Payload for `queue.consumer.stopped` — the polling loop was halted. */
 export interface QueueConsumerStoppedDetail extends WithEventSeverity {
+    /** Queue identity the consumer polls (validated `QueueConsumerConfig.queueName`). */
+    queueName: string;
     /** Epoch ms when `stop()` was called. */
     stoppedAt: number;
     /** Drain deadline in ms applied to in-flight handlers at stop time. */

package/src/job-queue/db-job-queue.ts

@@ -1,7 +1,6 @@
 import type { QueueJobDao, QueueJobRecord, QueueStats } from '@gobing-ai/ts-db';
 import type { EventBus } from '../event-bus/event-bus';
 import type {
-    QueueConsumerStoppedDetail,
     QueueEvents,
     QueueJobCompletedDetail,
     QueueJobEnqueuedDetail,
@@ -78,7 +77,11 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private readonly baseDelay: number;
     private readonly maxDelay: number;
     private readonly drainTimeoutMs: number;
-    private readonly events: EventBus<QueueEvents> | undefined;
+    /**
+     * Validated event sink: the bus plus the non-empty queue name its lifecycle rows
+     * require (ADR-068). `undefined` for silent consumers — no `events`, no identity.
+     */
+    private readonly eventSink: { bus: EventBus<QueueEvents>; queueName: string } | undefined;
     private timer: ReturnType<typeof setTimeout> | null = null;
     private running = false;
     private inFlight = 0;
@@ -95,7 +98,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         this.baseDelay = nonNegativeFiniteConfig('baseDelay', config.baseDelay ?? 1_000);
         this.maxDelay = nonNegativeFiniteConfig('maxDelay', config.maxDelay ?? 60_000);
         this.drainTimeoutMs = nonNegativeFiniteConfig('drainTimeoutMs', config.drainTimeoutMs ?? 30_000);
-        this.events = config.events;
+        this.eventSink = resolveEventSink(config);
     }
 
     register(type: string, handler: JobHandler<T>): void {
@@ -106,14 +109,18 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         if (this.running) return;
         this.running = true;
         this.schedule(0);
-        await this.events?.emit('queue.consumer.started', {
-            startedAt: Date.now(),
-            pollInterval: this.pollInterval,
-            batchSize: this.batchSize,
-            maxConcurrency: this.maxConcurrency,
-            visibilityTimeout: this.visibilityTimeout,
-            severity: 'info',
-        });
+        const sink = this.eventSink;
+        if (sink !== undefined) {
+            await sink.bus.emit('queue.consumer.started', {
+                startedAt: Date.now(),
+                pollInterval: this.pollInterval,
+                batchSize: this.batchSize,
+                maxConcurrency: this.maxConcurrency,
+                visibilityTimeout: this.visibilityTimeout,
+                queueName: sink.queueName,
+                severity: 'info',
+            });
+        }
     }
 
     async stop(): Promise<void> {
@@ -141,14 +148,17 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         }
         if (wasRunning) {
             const drained = this.inFlight === 0;
-            const detail: QueueConsumerStoppedDetail = {
-                stoppedAt: Date.now(),
-                drainTimeoutMs: this.drainTimeoutMs,
-                inFlightAtStop: this.inFlight,
-                drained,
-                severity: drained ? 'info' : 'warning',
-            };
-            await this.events?.emit('queue.consumer.stopped', detail);
+            const sink = this.eventSink;
+            if (sink !== undefined) {
+                await sink.bus.emit('queue.consumer.stopped', {
+                    stoppedAt: Date.now(),
+                    drainTimeoutMs: this.drainTimeoutMs,
+                    inFlightAtStop: this.inFlight,
+                    drained,
+                    queueName: sink.queueName,
+                    severity: drained ? 'info' : 'warning',
+                });
+            }
         }
     }
 
@@ -249,7 +259,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
                     attempt: job.attempts,
                     severity: 'info',
                 };
-                await this.events?.emit('queue.job.completed', completed);
+                await this.eventSink?.bus.emit('queue.job.completed', completed);
             } catch (error) {
                 const durationMs = performance.now() - startMs;
                 getQueueJobProcessingDuration().record(durationMs, { type: job.type });
@@ -277,7 +287,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
                 durationMs,
                 severity: 'error',
             };
-            await this.events?.emit('queue.job.failed', failed);
+            await this.eventSink?.bus.emit('queue.job.failed', failed);
             return;
         }
 
@@ -293,7 +303,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
             error: message,
             severity: 'warning',
         };
-        await this.events?.emit('queue.job.retrying', retrying);
+        await this.eventSink?.bus.emit('queue.job.retrying', retrying);
     }
 }
 
@@ -339,3 +349,26 @@ function nonNegativeFiniteConfig(name: string, value: number): number {
     }
     return value;
 }
+
+/**
+ * Resolve the validated event sink from `QueueConsumerConfig`: any supplied `queueName`
+ * must be non-empty and already trimmed, and an event-enabled consumer (one with an
+ * `events` bus) must supply one. Silent consumers may omit identity because they emit no
+ * lifecycle rows. The name is validated but never normalized — the emitted detail is
+ * byte-for-byte the config.
+ */
+function resolveEventSink(config: QueueConsumerConfig): { bus: EventBus<QueueEvents>; queueName: string } | undefined {
+    const name = config.queueName;
+    if (name !== undefined && (name.length === 0 || name.trim() !== name)) {
+        throw new TypeError(
+            `Queue consumer queueName must be a non-empty, already-trimmed string; received ${JSON.stringify(name)}`,
+        );
+    }
+    if (config.events === undefined) {
+        return undefined;
+    }
+    if (name === undefined) {
+        throw new TypeError('Queue consumer queueName is required when events is configured');
+    }
+    return { bus: config.events, queueName: name };
+}

package/src/job-queue/types.ts

@@ -60,6 +60,13 @@ export interface QueueConsumerConfig {
     maxDelay?: number;
     /** Upper bound (ms, default 30_000) on how long `stop()` waits for in-flight work to drain. */
     drainTimeoutMs?: number;
+    /**
+     * Identity of the queue this consumer polls. Runtime-required whenever `events` is
+     * configured (ADR-068): an observable consumer must never emit an anonymous lifecycle
+     * row. Silent consumers (no `events`) may omit it. A supplied value must be non-empty
+     * and already trimmed; it is validated but never normalized.
+     */
+    queueName?: string;
     /**
      * Optional bus for queue lifecycle events with correlator-grade detail payloads:
      * `queue.consumer.started` / `queue.consumer.stopped` (config snapshot + drain