@ouija-dev/bus 0.1.0

package/dist/bullmq-event-bus.d.ts

@@ -0,0 +1,51 @@
+import { type ConnectionOptions } from 'bullmq';
+import type { OuijaEventMap, OuijaTopic } from '@ouija-dev/types';
+import type { EventBus, EventHandler, PatternEventHandler, PublishOptions, Unsubscribe } from './event-bus.js';
+/**
+ * BullMQ-backed EventBus implementation.
+ *
+ * Fan-out strategy (v1 — simple and correct):
+ *  Each registered subscriber gets its own BullMQ queue named
+ *  `ouija.event-bus.<subscriberKey>`. When an event is published, one job is
+ *  enqueued per subscriber whose topic/pattern matches. The subscriber's Worker
+ *  processes that queue and calls the handler.
+ *
+ * This is O(N subscribers) on publish, which is acceptable for v1 where
+ * subscriber counts are single digits. If N grows, swap to Redis Streams
+ * consumer groups without changing the EventBus interface.
+ *
+ * Assumptions:
+ *  - Redis is configured with `maxmemory-policy noeviction`. Jobs must never
+ *    be silently dropped due to memory pressure.
+ *  - Connection is managed externally and passed in via `connection` option.
+ */
+export declare class BullMQEventBus implements EventBus {
+    private readonly connection;
+    private readonly subscribers;
+    private readonly deliveryQueues;
+    private readonly dispatchQueue;
+    private readonly dispatchWorker;
+    private closed;
+    constructor(connection: ConnectionOptions);
+    publish<TTopic extends OuijaTopic>(topic: TTopic, payload: OuijaEventMap[TTopic], options?: PublishOptions): Promise<string>;
+    subscribe<TTopic extends OuijaTopic>(topic: TTopic, handler: EventHandler<TTopic>): Promise<Unsubscribe>;
+    subscribePattern(pattern: string, handler: PatternEventHandler): Promise<Unsubscribe>;
+    /**
+     * Replay is not natively supported by BullMQ (jobs are ephemeral).
+     * A production implementation would query a persistent event store
+     * (Postgres `pipeline_events` table) and re-deliver events.
+     *
+     * This stub iterates completed jobs in the dispatch queue as a best-effort
+     * fallback. Callers should not rely on this for full catch-up — use the
+     * Postgres event log (Task 5) once available.
+     */
+    replay(topic: OuijaTopic, from: string, to: string, handler: PatternEventHandler): Promise<void>;
+    close(): Promise<void>;
+    private addSubscriber;
+    /**
+     * Fan out a published event to all matching subscribers.
+     * Called by the dispatch worker — runs inside BullMQ.
+     */
+    private fanOut;
+}
+//# sourceMappingURL=bullmq-event-bus.d.ts.map

package/dist/bullmq-event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq-event-bus.d.ts","sourceRoot":"","sources":["../src/bullmq-event-bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAE/D,OAAO,KAAK,EAAc,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,WAAW,EACZ,MAAM,gBAAgB,CAAC;AA0DxB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAElE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;IAE3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,MAAM,CAAS;gBAEX,UAAU,EAAE,iBAAiB;IAoCnC,OAAO,CAAC,MAAM,SAAS,UAAU,EACrC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC;IAuBZ,SAAS,CAAC,MAAM,SAAS,UAAU,EACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,WAAW,CAAC;IAajB,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC;IAQvB;;;;;;;;OAQG;IACG,MAAM,CACV,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAgCV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAwBd,aAAa;IA0D3B;;;OAGG;YACW,MAAM;CAwBrB"}

package/dist/bullmq-event-bus.js

@@ -0,0 +1,246 @@
+import { Queue, Worker } from 'bullmq';
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Glob pattern matching
+// ---------------------------------------------------------------------------
+/**
+ * Convert a glob-style pattern into a RegExp.
+ *
+ * Rules:
+ *  - `*`  matches any sequence of characters that does not contain `.`
+ *  - `**` matches any sequence of characters including `.`
+ *  - `.`  is treated as a literal dot
+ *
+ * Examples:
+ *  - `kanban.card.*`   matches `kanban.card.moved`, `kanban.card.created`
+ *  - `agent.**`        matches `agent.work.progress`, `agent.work.pr_ready`
+ *  - `git.*`           matches `git.pr` but NOT `git.pr.opened`
+ */
+function globToRegex(pattern) {
+    // Escape all regex metacharacters except * which we handle specially
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex special chars (. included)
+        .replace(/\\\.\\\./g, '\\.') // shouldn't occur but safety net
+        // Replace ** first (two stars), then single *
+        .replace(/\*\*/g, '\x00GLOBSTAR\x00')
+        .replace(/\*/g, '[^.]+')
+        .replace(/\x00GLOBSTAR\x00/g, '.+');
+    return new RegExp(`^${escaped}$`);
+}
+function topicMatchesPattern(topic, pattern) {
+    // Exact match short-circuit
+    if (topic === pattern)
+        return true;
+    try {
+        return globToRegex(pattern).test(topic);
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// BullMQEventBus
+// ---------------------------------------------------------------------------
+/**
+ * BullMQ-backed EventBus implementation.
+ *
+ * Fan-out strategy (v1 — simple and correct):
+ *  Each registered subscriber gets its own BullMQ queue named
+ *  `ouija.event-bus.<subscriberKey>`. When an event is published, one job is
+ *  enqueued per subscriber whose topic/pattern matches. The subscriber's Worker
+ *  processes that queue and calls the handler.
+ *
+ * This is O(N subscribers) on publish, which is acceptable for v1 where
+ * subscriber counts are single digits. If N grows, swap to Redis Streams
+ * consumer groups without changing the EventBus interface.
+ *
+ * Assumptions:
+ *  - Redis is configured with `maxmemory-policy noeviction`. Jobs must never
+ *    be silently dropped due to memory pressure.
+ *  - Connection is managed externally and passed in via `connection` option.
+ */
+export class BullMQEventBus {
+    connection;
+    subscribers = new Map();
+    // One Queue per subscriber key for fan-out delivery
+    deliveryQueues = new Map();
+    // Single publish queue used as the fan-out coordinator
+    dispatchQueue;
+    dispatchWorker;
+    closed = false;
+    constructor(connection) {
+        this.connection = connection;
+        // The dispatch queue receives one job per publish() call.
+        // Its worker fans out to per-subscriber delivery queues.
+        this.dispatchQueue = new Queue('ouija.event-bus.dispatch', {
+            connection,
+            defaultJobOptions: {
+                removeOnComplete: { count: 1000 },
+                removeOnFail: { count: 500 },
+                attempts: 3,
+                backoff: { type: 'exponential', delay: 1000 },
+            },
+        });
+        this.dispatchWorker = new Worker('ouija.event-bus.dispatch', async (job) => {
+            const event = job.data;
+            await this.fanOut(event);
+        }, { connection, concurrency: 10 });
+        this.dispatchWorker.on('failed', (job, err) => {
+            console.error(`[BullMQEventBus] dispatch job ${job?.id ?? 'unknown'} failed:`, err);
+        });
+    }
+    // -------------------------------------------------------------------------
+    // publish
+    // -------------------------------------------------------------------------
+    async publish(topic, payload, options = {}) {
+        if (this.closed)
+            throw new Error('BullMQEventBus is closed');
+        const event = {
+            id: randomUUID(),
+            topic,
+            payload,
+            timestamp: new Date().toISOString(),
+            sourcePlugin: options.sourcePlugin ?? 'unknown',
+            correlationId: options.correlationId ?? randomUUID(),
+        };
+        await this.dispatchQueue.add(`event:${topic}`, event, {
+            jobId: `event:${event.id}`,
+        });
+        return event.id;
+    }
+    // -------------------------------------------------------------------------
+    // subscribe (exact topic, fully typed)
+    // -------------------------------------------------------------------------
+    async subscribe(topic, handler) {
+        // Wrap typed handler as PatternEventHandler so we can store it uniformly
+        const patternHandler = async (event) => {
+            await handler(event);
+        };
+        return this.addSubscriber(topic, false, patternHandler);
+    }
+    // -------------------------------------------------------------------------
+    // subscribePattern (glob, intentionally type-unsafe)
+    // -------------------------------------------------------------------------
+    async subscribePattern(pattern, handler) {
+        return this.addSubscriber(pattern, true, handler);
+    }
+    // -------------------------------------------------------------------------
+    // replay
+    // -------------------------------------------------------------------------
+    /**
+     * Replay is not natively supported by BullMQ (jobs are ephemeral).
+     * A production implementation would query a persistent event store
+     * (Postgres `pipeline_events` table) and re-deliver events.
+     *
+     * This stub iterates completed jobs in the dispatch queue as a best-effort
+     * fallback. Callers should not rely on this for full catch-up — use the
+     * Postgres event log (Task 5) once available.
+     */
+    async replay(topic, from, to, handler) {
+        if (this.closed)
+            throw new Error('BullMQEventBus is closed');
+        const fromMs = new Date(from).getTime();
+        const toMs = new Date(to).getTime();
+        // BullMQ stores completed jobs temporarily. Fetch and filter.
+        const completed = await this.dispatchQueue.getCompleted(0, 1000);
+        const inRange = completed.filter((job) => {
+            const event = job.data;
+            if (event.topic !== topic)
+                return false;
+            const ts = new Date(event.timestamp).getTime();
+            return ts >= fromMs && ts <= toMs;
+        });
+        // Sort ascending by timestamp
+        inRange.sort((a, b) => {
+            const aTs = new Date(a.data.timestamp).getTime();
+            const bTs = new Date(b.data.timestamp).getTime();
+            return aTs - bTs;
+        });
+        for (const job of inRange) {
+            await handler(job.data);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // close
+    // -------------------------------------------------------------------------
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.dispatchWorker.close();
+        await this.dispatchQueue.close();
+        const closePromises = [];
+        for (const entry of this.subscribers.values()) {
+            closePromises.push(entry.worker.close());
+        }
+        for (const queue of this.deliveryQueues.values()) {
+            closePromises.push(queue.close());
+        }
+        await Promise.all(closePromises);
+        this.subscribers.clear();
+        this.deliveryQueues.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    async addSubscriber(topicOrPattern, isPattern, handler) {
+        if (this.closed)
+            throw new Error('BullMQEventBus is closed');
+        const key = `sub:${randomUUID()}`;
+        const deliveryQueueName = `ouija.event-bus.delivery.${key}`;
+        const deliveryQueue = new Queue(deliveryQueueName, {
+            connection: this.connection,
+            defaultJobOptions: {
+                removeOnComplete: { count: 500 },
+                removeOnFail: { count: 100 },
+                attempts: 3,
+                backoff: { type: 'exponential', delay: 500 },
+            },
+        });
+        const worker = new Worker(deliveryQueueName, async (job) => {
+            const event = job.data;
+            await handler(event);
+        }, { connection: this.connection, concurrency: 1 });
+        worker.on('failed', (job, err) => {
+            console.error(`[BullMQEventBus] delivery job ${job?.id ?? 'unknown'} for subscriber ${key} failed:`, err);
+        });
+        const entry = {
+            key,
+            topic: topicOrPattern,
+            isPattern,
+            handler,
+            worker,
+        };
+        this.subscribers.set(key, entry);
+        this.deliveryQueues.set(key, deliveryQueue);
+        const unsubscribe = async () => {
+            this.subscribers.delete(key);
+            const q = this.deliveryQueues.get(key);
+            this.deliveryQueues.delete(key);
+            await worker.close();
+            if (q)
+                await q.close();
+        };
+        return unsubscribe;
+    }
+    /**
+     * Fan out a published event to all matching subscribers.
+     * Called by the dispatch worker — runs inside BullMQ.
+     */
+    async fanOut(event) {
+        const enqueuePromises = [];
+        for (const [key, entry] of this.subscribers) {
+            const matches = entry.isPattern
+                ? topicMatchesPattern(event.topic, entry.topic)
+                : event.topic === entry.topic;
+            if (!matches)
+                continue;
+            const deliveryQueue = this.deliveryQueues.get(key);
+            if (!deliveryQueue)
+                continue;
+            enqueuePromises.push(deliveryQueue.add(`deliver:${event.id}:${key}`, event, { jobId: `deliver:${event.id}:${key}` }));
+        }
+        await Promise.all(enqueuePromises);
+    }
+}
+//# sourceMappingURL=bullmq-event-bus.js.map

package/dist/bullmq-event-bus.js.map

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

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

@@ -0,0 +1,26 @@
+import { type ConnectionOptions } from 'bullmq';
+import type { EnqueueOptions, JobHandler, JobQueue, QueueDataMap, QueueName } from './job-queue.js';
+/**
+ * BullMQ-backed JobQueue implementation.
+ *
+ * One BullMQ Queue per queue name. Workers are created lazily on the first
+ * `process()` call for a given queue name.
+ *
+ * Assumptions:
+ *  - Redis is configured with `maxmemory-policy noeviction`.
+ *  - All queue names are treated as static. Dynamic queue creation at runtime
+ *    is not supported in v1.
+ */
+export declare class BullMQJobQueue implements JobQueue {
+    private readonly connection;
+    private readonly queues;
+    private readonly workers;
+    private closed;
+    constructor(connection: ConnectionOptions);
+    enqueue<TQueue extends QueueName>(queue: TQueue, data: QueueDataMap[TQueue], options?: EnqueueOptions): Promise<string>;
+    process<TQueue extends QueueName>(queue: TQueue, handler: JobHandler<QueueDataMap[TQueue]>, concurrency?: number): Promise<void>;
+    cancelJob(queue: QueueName, jobId: string): Promise<void>;
+    close(): Promise<void>;
+    private getOrCreateQueue;
+}
+//# sourceMappingURL=bullmq-job-queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq-job-queue.d.ts","sourceRoot":"","sources":["../src/bullmq-job-queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC/D,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,SAAS,EACV,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,MAAM,CAAS;gBAEX,UAAU,EAAE,iBAAiB;IAQnC,OAAO,CAAC,MAAM,SAAS,SAAS,EACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC;IAgCZ,OAAO,CAAC,MAAM,SAAS,SAAS,EACpC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,EACzC,WAAW,SAAI,GACd,OAAO,CAAC,IAAI,CAAC;IAuCV,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BzD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB5B,OAAO,CAAC,gBAAgB;CAezB"}

package/dist/bullmq-job-queue.js

@@ -0,0 +1,134 @@
+import { Queue, Worker } from 'bullmq';
+/**
+ * BullMQ-backed JobQueue implementation.
+ *
+ * One BullMQ Queue per queue name. Workers are created lazily on the first
+ * `process()` call for a given queue name.
+ *
+ * Assumptions:
+ *  - Redis is configured with `maxmemory-policy noeviction`.
+ *  - All queue names are treated as static. Dynamic queue creation at runtime
+ *    is not supported in v1.
+ */
+export class BullMQJobQueue {
+    connection;
+    queues = new Map();
+    workers = new Map();
+    closed = false;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    // -------------------------------------------------------------------------
+    // enqueue
+    // -------------------------------------------------------------------------
+    async enqueue(queue, data, options = {}) {
+        if (this.closed)
+            throw new Error('BullMQJobQueue is closed');
+        const q = this.getOrCreateQueue(queue);
+        // Build options conditionally to satisfy exactOptionalPropertyTypes:
+        // never assign `undefined` to an optional property.
+        const jobOptions = {
+            attempts: options.attempts ?? 3,
+            backoff: options.backoff
+                ? { type: options.backoff.type, delay: options.backoff.delay }
+                : { type: 'exponential', delay: 1000 },
+            priority: options.priority ?? 0,
+            removeOnComplete: { count: 1000 },
+            removeOnFail: { count: 500 },
+        };
+        if (options.jobId !== undefined)
+            jobOptions['jobId'] = options.jobId;
+        if (options.delayMs !== undefined)
+            jobOptions['delay'] = options.delayMs;
+        const job = await q.add(queue, data, jobOptions);
+        if (!job.id) {
+            throw new Error(`BullMQ did not assign an ID to job on queue "${queue}"`);
+        }
+        return job.id;
+    }
+    // -------------------------------------------------------------------------
+    // process
+    // -------------------------------------------------------------------------
+    async process(queue, handler, concurrency = 1) {
+        if (this.closed)
+            throw new Error('BullMQJobQueue is closed');
+        // Close any existing worker for this queue before replacing the handler
+        const existing = this.workers.get(queue);
+        if (existing) {
+            await existing.close();
+            this.workers.delete(queue);
+        }
+        // Ensure the queue exists
+        this.getOrCreateQueue(queue);
+        const worker = new Worker(queue, async (job) => {
+            const jobId = job.id ?? 'unknown';
+            await handler(job.data, jobId);
+        }, {
+            connection: this.connection,
+            concurrency,
+        });
+        worker.on('failed', (job, err) => {
+            console.error(`[BullMQJobQueue] job ${job?.id ?? 'unknown'} on queue "${queue}" failed:`, err);
+        });
+        this.workers.set(queue, worker);
+    }
+    // -------------------------------------------------------------------------
+    // cancelJob
+    // -------------------------------------------------------------------------
+    async cancelJob(queue, jobId) {
+        if (this.closed)
+            return;
+        const q = this.queues.get(queue);
+        if (!q)
+            return;
+        const job = await q.getJob(jobId);
+        if (!job)
+            return;
+        // Remove the job regardless of its state (waiting, delayed, etc.)
+        // For active jobs, this will fail silently — a running job cannot be
+        // force-removed; the worker must complete or fail it naturally.
+        try {
+            await job.remove();
+        }
+        catch {
+            // Job may already be processing — log and move on
+            console.warn(`[BullMQJobQueue] could not cancel job "${jobId}" on queue "${queue}" — it may be active`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // close
+    // -------------------------------------------------------------------------
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const closePromises = [];
+        for (const worker of this.workers.values()) {
+            closePromises.push(worker.close());
+        }
+        for (const queue of this.queues.values()) {
+            closePromises.push(queue.close());
+        }
+        await Promise.all(closePromises);
+        this.workers.clear();
+        this.queues.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    getOrCreateQueue(name) {
+        const existing = this.queues.get(name);
+        if (existing)
+            return existing;
+        const queue = new Queue(name, {
+            connection: this.connection,
+            defaultJobOptions: {
+                removeOnComplete: { count: 1000 },
+                removeOnFail: { count: 500 },
+            },
+        });
+        this.queues.set(name, queue);
+        return queue;
+    }
+}
+//# sourceMappingURL=bullmq-job-queue.js.map

package/dist/bullmq-job-queue.js.map

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

package/dist/event-bus.d.ts

@@ -0,0 +1,61 @@
+import type { OuijaEvent, OuijaEventMap, OuijaTopic } from '@ouija-dev/types';
+/**
+ * Handler for a specific typed topic. Receives the full OuijaEvent envelope.
+ */
+export type EventHandler<TTopic extends OuijaTopic> = (event: OuijaEvent<TTopic>) => Promise<void>;
+/**
+ * Handler for pattern subscriptions. Type-unsafe by design — wildcards cannot
+ * be statically constrained to a single payload shape.
+ */
+export type PatternEventHandler = (event: OuijaEvent) => Promise<void>;
+/**
+ * Unsubscribe function returned by subscribe / subscribePattern.
+ * Calling it deregisters the handler and cleans up any BullMQ workers.
+ */
+export type Unsubscribe = () => Promise<void>;
+/**
+ * EventBus — pub/sub interface for Ouija domain events.
+ *
+ * Design rules (Decision 2 in spec §2.4):
+ *  - Separate from JobQueue at the interface level even though both use BullMQ.
+ *  - `subscribe` is typed: the handler receives the exact payload for TTopic.
+ *  - `subscribePattern` is intentionally type-unsafe: wildcards span multiple
+ *    topics and therefore multiple payload shapes. Callers must narrow.
+ *  - `replay` allows catch-up processing from persistent event storage.
+ */
+export interface EventBus {
+    /**
+     * Publish an event to all subscribers of `topic`.
+     * The bus generates the event envelope (id, timestamp, correlationId).
+     * Returns the generated event id.
+     */
+    publish<TTopic extends OuijaTopic>(topic: TTopic, payload: OuijaEventMap[TTopic], options?: PublishOptions): Promise<string>;
+    /**
+     * Subscribe to an exact topic. Returns an unsubscribe function.
+     * The handler is called once per published event.
+     */
+    subscribe<TTopic extends OuijaTopic>(topic: TTopic, handler: EventHandler<TTopic>): Promise<Unsubscribe>;
+    /**
+     * Subscribe to events matching a glob-style pattern, e.g. `kanban.card.*`
+     * or `agent.**`. Intentionally type-unsafe — callers must narrow the payload
+     * themselves. Returns an unsubscribe function.
+     */
+    subscribePattern(pattern: string, handler: PatternEventHandler): Promise<Unsubscribe>;
+    /**
+     * Replay stored events for a topic between `from` and `to` (ISO strings).
+     * Events are delivered to `handler` in chronological order.
+     * Used for catch-up processing and debugging.
+     */
+    replay(topic: OuijaTopic, from: string, to: string, handler: PatternEventHandler): Promise<void>;
+    /**
+     * Gracefully shut down the bus, draining in-flight handlers.
+     */
+    close(): Promise<void>;
+}
+export interface PublishOptions {
+    /** Explicit correlationId to propagate across services. Defaults to a new UUID. */
+    correlationId?: string;
+    /** Source plugin identifier. Defaults to 'unknown'. */
+    sourcePlugin?: string;
+}
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9E;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,UAAU,IAAI,CACpD,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,KACtB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvE;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,OAAO,CAAC,MAAM,SAAS,UAAU,EAC/B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,MAAM,SAAS,UAAU,EACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;OAIG;IACH,gBAAgB,CACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;OAIG;IACH,MAAM,CACJ,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/event-bus.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-bus.js.map

package/dist/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { EventBus, EventHandler, PatternEventHandler, PublishOptions, Unsubscribe, } from './event-bus.js';
+export type { JobQueue, JobHandler, QueueName, QueueDataMap, EnqueueOptions, AgentDispatchJobData, StallCheckJobData, EventBusJobData, } from './job-queue.js';
+export { QUEUE_NAMES } from './job-queue.js';
+export { BullMQEventBus } from './bullmq-event-bus.js';
+export { BullMQJobQueue } from './bullmq-job-queue.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,QAAQ,EACR,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { QUEUE_NAMES } from './job-queue.js';
+// BullMQ implementations
+export { BullMQEventBus } from './bullmq-event-bus.js';
+export { BullMQJobQueue } from './bullmq-job-queue.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,yBAAyB;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/job-queue.d.ts

@@ -0,0 +1,84 @@
+import type { OuijaEvent } from '@ouija-dev/types';
+export declare const QUEUE_NAMES: {
+    readonly agentDispatch: "ouija.agent-dispatch";
+    readonly stallCheck: "ouija.stall-check";
+    readonly eventBus: "ouija.event-bus";
+};
+export type QueueName = (typeof QUEUE_NAMES)[keyof typeof QUEUE_NAMES];
+export interface AgentDispatchJobData {
+    instanceId: string;
+    dispatchId: string;
+    agentId: string;
+    cardId: string;
+    projectId: string;
+    workOrderDescription: string;
+    /** ISO timestamp of when this dispatch was requested */
+    dispatchedAt: string;
+}
+export interface StallCheckJobData {
+    instanceId: string;
+    dispatchId: string;
+    /** ISO timestamp the stall check should fire at (BullMQ delay handles this) */
+    expectedBy: string;
+}
+/**
+ * Internal job data used by BullMQEventBus to fan-out events to subscribers.
+ * The subscriberKey uniquely identifies the registered handler.
+ */
+export interface EventBusJobData {
+    event: OuijaEvent;
+    subscriberKey: string;
+}
+export interface QueueDataMap {
+    [QUEUE_NAMES.agentDispatch]: AgentDispatchJobData;
+    [QUEUE_NAMES.stallCheck]: StallCheckJobData;
+    [QUEUE_NAMES.eventBus]: EventBusJobData;
+}
+export interface EnqueueOptions {
+    /** BullMQ job ID. If provided, duplicate jobs with same ID are deduplicated. */
+    jobId?: string;
+    /** Delay in milliseconds before the job becomes active. */
+    delayMs?: number;
+    /** Number of retry attempts on failure. Defaults to 3. */
+    attempts?: number;
+    /** Backoff strategy for retries. */
+    backoff?: {
+        type: 'exponential' | 'fixed';
+        delay: number;
+    };
+    /** Priority (lower number = higher priority). Defaults to 0. */
+    priority?: number;
+}
+export type JobHandler<TData> = (data: TData, jobId: string) => Promise<void>;
+/**
+ * JobQueue — durable task dispatch interface.
+ *
+ * Design rules (Decision 2 in spec §2.4):
+ *  - Separate from EventBus at the interface level.
+ *  - Typed via QueueDataMap: `enqueue<TQueue>` ensures data matches queue.
+ *  - One queue per concern (agentDispatch, stallCheck, eventBus).
+ *  - BullMQ implementation uses noeviction Redis — jobs must never be evicted.
+ */
+export interface JobQueue {
+    /**
+     * Enqueue a job on the specified queue.
+     * Returns the BullMQ job ID.
+     */
+    enqueue<TQueue extends QueueName>(queue: TQueue, data: QueueDataMap[TQueue], options?: EnqueueOptions): Promise<string>;
+    /**
+     * Register a processor for the specified queue.
+     * Workers are created lazily on the first `process()` call per queue.
+     * Calling process() twice on the same queue replaces the handler.
+     */
+    process<TQueue extends QueueName>(queue: TQueue, handler: JobHandler<QueueDataMap[TQueue]>, concurrency?: number): Promise<void>;
+    /**
+     * Remove a job by ID from the specified queue.
+     * No-ops if the job does not exist or is already completed.
+     */
+    cancelJob(queue: QueueName, jobId: string): Promise<void>;
+    /**
+     * Gracefully shut down all workers, waiting for in-flight jobs to complete.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=job-queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"job-queue.d.ts","sourceRoot":"","sources":["../src/job-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,kBAAkB,CAAC;AAM/D,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAMvE,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,WAAW,YAAY;IAC3B,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAClD,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC5C,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;CACzC;AAMD,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;QAC9B,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,MAAM,UAAU,CAAC,KAAK,IAAI,CAC9B,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,IAAI,CAAC,CAAC;AAMnB;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,OAAO,CAAC,MAAM,SAAS,SAAS,EAC9B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;OAIG;IACH,OAAO,CAAC,MAAM,SAAS,SAAS,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,EACzC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/job-queue.js

@@ -0,0 +1,9 @@
+// ---------------------------------------------------------------------------
+// Queue names — single source of truth
+// ---------------------------------------------------------------------------
+export const QUEUE_NAMES = {
+    agentDispatch: 'ouija.agent-dispatch',
+    stallCheck: 'ouija.stall-check',
+    eventBus: 'ouija.event-bus',
+};
+//# sourceMappingURL=job-queue.js.map

package/dist/job-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-queue.js","sourceRoot":"","sources":["../src/job-queue.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,aAAa,EAAE,sBAAsB;IACrC,UAAU,EAAE,mBAAmB;IAC/B,QAAQ,EAAE,iBAAiB;CACnB,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@ouija-dev/bus",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist/", "README.md"],
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "https://github.com/muhammadkh4n/ouija.git" },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ouija-dev/types": "*",
+    "bullmq": "^5.0.0",
+    "ioredis": "^5.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  }
+}