@adonis-agora/durable 0.1.0

package/dist/src/tokens.js

@@ -0,0 +1,18 @@
+/**
+ * Dependency-injection tokens. Adapters bind their implementations to these so `core` and
+ * `@dudousxd/nestjs-durable` depend only on the interfaces in `./interfaces`.
+ *
+ * These use `Symbol.for(key)` (the global symbol registry), NOT `Symbol(key)`, so the token is the
+ * SAME instance no matter how many times `core` is evaluated in a process. A consumer can hold more
+ * than one physical copy of `core` at runtime — pnpm peer-dependency multiplexing installs a
+ * separate virtual copy per distinct peer set, and the dual ESM/CJS build can be loaded once as
+ * `import` (`index.js`) and once as `require` (`index.cjs`). A plain `Symbol()` would mint a
+ * DISTINCT token per copy, so `DurableModule` (provider) and `DashboardService` / a store adapter
+ * (injector) could resolve different symbols → Nest can't satisfy the dependency
+ * (`STATE_STORE is not available in the DurableApiModule context`). A registered symbol collapses
+ * them to one. Mirrors the `CONTEXT_ACCESSOR` token in `@dudousxd/nestjs-durable`'s `tokens.ts`.
+ */
+export const STATE_STORE = Symbol.for('@agora/durable:STATE_STORE');
+export const TRANSPORT = Symbol.for('@agora/durable:TRANSPORT');
+export const DURABLE_OPTIONS = Symbol.for('@agora/durable:DURABLE_OPTIONS');
+//# sourceMappingURL=tokens.js.map

package/dist/src/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AACpE,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAChE,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC"}

package/dist/src/transport-pool.d.ts

@@ -0,0 +1,30 @@
+import type { GroupHealth, Heartbeat, NamedTransport, RemoteTask, StepResult, WorkflowStepEvent } from './interfaces.js';
+/**
+ * An ordered pool of named transports. The engine dispatches on the first and fails over to the
+ * next on a dispatch error; a step can pin one by id. Pure transport plumbing — no run lifecycle —
+ * so it lives apart from the engine.
+ */
+export declare class TransportPool {
+    private readonly transports;
+    constructor(transports: NamedTransport[]);
+    get size(): number;
+    /** Register the engine's result/heartbeat/step-event handlers on EVERY transport — a result can come
+     *  back on whichever one delivered the task, so failover stays symmetric. `onStepEvent` is wired only
+     *  on transports that carry streamed workflow step lifecycle (BullMQ); others simply skip it. */
+    bind(onResult: (result: StepResult) => Promise<void>, onHeartbeat: (beat: Heartbeat) => Promise<void>, onStepEvent?: (event: WorkflowStepEvent) => Promise<void>): void;
+    /**
+     * Dispatch `task` over the pool: try the preferred (or first) transport, fail over to the next on
+     * a dispatch error, and stamp the task with the id of the transport that accepted it (so a worker
+     * replies on the matching one). Throws if every transport fails.
+     */
+    dispatch(task: Omit<RemoteTask, 'transport'>, preferId?: string): Promise<void>;
+    /** Worker-health for `group`, merged across every transport that can report it (a group's queue
+     *  and its workers may live on any pinned transport). Undefined when no transport implements
+     *  `groupHealth` (e.g. a pure in-process transport — nothing to introspect). */
+    groupHealth(group: string): Promise<GroupHealth | undefined>;
+    /** Distinct worker groups with a live heartbeat, merged across every transport that can report it. */
+    listWorkerGroups(): Promise<string[]>;
+    /** Pinned `preferId` first, then the rest (failover order). */
+    private ordered;
+}
+//# sourceMappingURL=transport-pool.d.ts.map

package/dist/src/transport-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-pool.d.ts","sourceRoot":"","sources":["../../src/transport-pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,cAAc,EACd,UAAU,EACV,UAAU,EACV,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAEzB;;;;GAIG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,cAAc,EAAE;IAEzD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;qGAEiG;IACjG,IAAI,CACF,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,EAC/C,WAAW,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,EAC/C,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GACxD,IAAI;IAUP;;;;OAIG;IACG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAarF;;oFAEgF;IAC1E,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAalE,sGAAsG;IAChG,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAU3C,+DAA+D;IAC/D,OAAO,CAAC,OAAO;CAMhB"}

package/dist/src/transport-pool.js

@@ -0,0 +1,82 @@
+/**
+ * An ordered pool of named transports. The engine dispatches on the first and fails over to the
+ * next on a dispatch error; a step can pin one by id. Pure transport plumbing — no run lifecycle —
+ * so it lives apart from the engine.
+ */
+export class TransportPool {
+    transports;
+    constructor(transports) {
+        this.transports = transports;
+    }
+    get size() {
+        return this.transports.length;
+    }
+    /** Register the engine's result/heartbeat/step-event handlers on EVERY transport — a result can come
+     *  back on whichever one delivered the task, so failover stays symmetric. `onStepEvent` is wired only
+     *  on transports that carry streamed workflow step lifecycle (BullMQ); others simply skip it. */
+    bind(onResult, onHeartbeat, onStepEvent) {
+        for (const { transport } of this.transports) {
+            transport.onResult(onResult);
+            transport.onHeartbeat(onHeartbeat);
+            if (onStepEvent && transport.onStepEvent) {
+                transport.onStepEvent(onStepEvent);
+            }
+        }
+    }
+    /**
+     * Dispatch `task` over the pool: try the preferred (or first) transport, fail over to the next on
+     * a dispatch error, and stamp the task with the id of the transport that accepted it (so a worker
+     * replies on the matching one). Throws if every transport fails.
+     */
+    async dispatch(task, preferId) {
+        let lastErr;
+        for (const { id, transport } of this.ordered(preferId)) {
+            try {
+                await transport.dispatch({ ...task, transport: id });
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+            }
+        }
+        throw lastErr ?? new Error('no transport accepted the dispatch');
+    }
+    /** Worker-health for `group`, merged across every transport that can report it (a group's queue
+     *  and its workers may live on any pinned transport). Undefined when no transport implements
+     *  `groupHealth` (e.g. a pure in-process transport — nothing to introspect). */
+    async groupHealth(group) {
+        const reports = [];
+        for (const { transport } of this.transports) {
+            if (transport.groupHealth)
+                reports.push(await transport.groupHealth(group));
+        }
+        if (reports.length === 0)
+            return undefined;
+        return {
+            group,
+            depth: reports.reduce((sum, r) => sum + r.depth, 0),
+            liveWorkers: reports.flatMap((r) => r.liveWorkers),
+        };
+    }
+    /** Distinct worker groups with a live heartbeat, merged across every transport that can report it. */
+    async listWorkerGroups() {
+        const groups = new Set();
+        for (const { transport } of this.transports) {
+            if (transport.listWorkerGroups) {
+                for (const g of await transport.listWorkerGroups())
+                    groups.add(g);
+            }
+        }
+        return [...groups];
+    }
+    /** Pinned `preferId` first, then the rest (failover order). */
+    ordered(preferId) {
+        if (!preferId)
+            return this.transports;
+        const pref = this.transports.filter((t) => t.id === preferId);
+        if (pref.length === 0)
+            throw new Error(`transport "${preferId}" is not registered`);
+        return [...pref, ...this.transports.filter((t) => t.id !== preferId)];
+    }
+}
+//# sourceMappingURL=transport-pool.js.map

package/dist/src/transport-pool.js.map

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

package/dist/src/transports/db-helpers.d.ts

@@ -0,0 +1,10 @@
+import { Database } from '@adonisjs/lucid/database';
+/**
+ * Build a standalone Lucid `Database` over an in-memory SQLite (`better-sqlite3`) — the "using Lucid
+ * outside an app" pattern. We construct `Database(config, logger, emitter)` directly (the three args
+ * Lucid's provider passes) so the transport runs against real SQL with no AdonisJS app boot.
+ */
+export declare function makeMemoryDb(): Database;
+/** A fresh in-memory db with the transport tables already created. */
+export declare function makeTransportDb(): Promise<Database>;
+//# sourceMappingURL=db-helpers.d.ts.map

package/dist/src/transports/db-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-helpers.d.ts","sourceRoot":"","sources":["../../../src/transports/db-helpers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGpD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,QAAQ,CAoBvC;AAED,sEAAsE;AACtE,wBAAsB,eAAe,IAAI,OAAO,CAAC,QAAQ,CAAC,CAIzD"}

package/dist/src/transports/db-helpers.js

@@ -0,0 +1,33 @@
+import { Emitter } from '@adonisjs/core/events';
+import { Logger } from '@adonisjs/core/logger';
+import { Database } from '@adonisjs/lucid/database';
+import { createDurableTransportTables } from './db-schema.js';
+/**
+ * Build a standalone Lucid `Database` over an in-memory SQLite (`better-sqlite3`) — the "using Lucid
+ * outside an app" pattern. We construct `Database(config, logger, emitter)` directly (the three args
+ * Lucid's provider passes) so the transport runs against real SQL with no AdonisJS app boot.
+ */
+export function makeMemoryDb() {
+    const logger = new Logger({ enabled: false });
+    const emitter = new Emitter(undefined);
+    return new Database({
+        connection: 'sqlite',
+        connections: {
+            sqlite: {
+                client: 'better-sqlite3',
+                connection: { filename: ':memory:' },
+                useNullAsDefault: true,
+                // A `:memory:` SQLite db is per-connection: pin the pool to ONE connection so every query
+                // (and the schema) hits the same in-memory database.
+                pool: { min: 1, max: 1 },
+            },
+        },
+    }, logger, emitter);
+}
+/** A fresh in-memory db with the transport tables already created. */
+export async function makeTransportDb() {
+    const db = makeMemoryDb();
+    await createDurableTransportTables(db);
+    return db;
+}
+//# sourceMappingURL=db-helpers.js.map

package/dist/src/transports/db-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-helpers.js","sourceRoot":"","sources":["../../../src/transports/db-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,SAAkB,CAAC,CAAC;IAChD,OAAO,IAAI,QAAQ,CACjB;QACE,UAAU,EAAE,QAAQ;QACpB,WAAW,EAAE;YACX,MAAM,EAAE;gBACN,MAAM,EAAE,gBAAgB;gBACxB,UAAU,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE;gBACpC,gBAAgB,EAAE,IAAI;gBACtB,0FAA0F;gBAC1F,qDAAqD;gBACrD,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;aACzB;SACF;KACF,EACD,MAAM,EACN,OAAO,CACR,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;IAC1B,MAAM,4BAA4B,CAAC,EAAE,CAAC,CAAC;IACvC,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/src/transports/db-schema.d.ts

@@ -0,0 +1,28 @@
+import type { Database } from '@adonisjs/lucid/database';
+/**
+ * The DB transport's table names. Distinct from the durable *store* tables (`durable_workflow_runs`
+ * etc.) — these carry the point-to-point work channels (tasks / results / heartbeats / control), so
+ * the transport can share one database with the store without colliding.
+ */
+export declare const TRANSPORT_TABLES: {
+    readonly tasks: "durable_transport_tasks";
+    readonly results: "durable_transport_results";
+    readonly heartbeats: "durable_transport_heartbeats";
+    readonly control: "durable_transport_control";
+};
+/**
+ * Idempotent DDL for the four transport tables, via Lucid's schema builder (Knex). Portable across
+ * SQLite / Postgres / MySQL: JSON payloads (`input`/`output`/`error`/`payload`) are stored as TEXT
+ * and (de)serialized by the transport, and every timestamp is an epoch-ms `bigInteger`, so there's
+ * no dependency on a dialect's native JSON/date type.
+ *
+ * Each row is a one-shot message claimed by exactly one consumer (atomic conditional UPDATE on
+ * `claimed_by`) and then deleted once handled — the DB is the queue.
+ *
+ * Call this on boot or once at deploy time. For an AdonisJS app prefer the published migration
+ * (`node ace configure @adonis-agora/durable`); this helper is for standalone use and tests.
+ */
+export declare function createDurableTransportTables(db: Database): Promise<void>;
+/** Drop every transport table. Used by tests and the migration `down`. */
+export declare function dropDurableTransportTables(db: Database): Promise<void>;
+//# sourceMappingURL=db-schema.d.ts.map

package/dist/src/transports/db-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-schema.d.ts","sourceRoot":"","sources":["../../../src/transports/db-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,wBAAsB,4BAA4B,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAqE9E;AAED,0EAA0E;AAC1E,wBAAsB,0BAA0B,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5E"}

package/dist/src/transports/db-schema.js

@@ -0,0 +1,98 @@
+/**
+ * The DB transport's table names. Distinct from the durable *store* tables (`durable_workflow_runs`
+ * etc.) — these carry the point-to-point work channels (tasks / results / heartbeats / control), so
+ * the transport can share one database with the store without colliding.
+ */
+export const TRANSPORT_TABLES = {
+    tasks: 'durable_transport_tasks',
+    results: 'durable_transport_results',
+    heartbeats: 'durable_transport_heartbeats',
+    control: 'durable_transport_control',
+};
+/**
+ * Idempotent DDL for the four transport tables, via Lucid's schema builder (Knex). Portable across
+ * SQLite / Postgres / MySQL: JSON payloads (`input`/`output`/`error`/`payload`) are stored as TEXT
+ * and (de)serialized by the transport, and every timestamp is an epoch-ms `bigInteger`, so there's
+ * no dependency on a dialect's native JSON/date type.
+ *
+ * Each row is a one-shot message claimed by exactly one consumer (atomic conditional UPDATE on
+ * `claimed_by`) and then deleted once handled — the DB is the queue.
+ *
+ * Call this on boot or once at deploy time. For an AdonisJS app prefer the published migration
+ * (`node ace configure @adonis-agora/durable`); this helper is for standalone use and tests.
+ */
+export async function createDurableTransportTables(db) {
+    // Knex's schema builder is stateful — take a FRESH `db.connection().schema` per hasTable/createTable
+    // so each DDL statement executes exactly once.
+    const conn = () => db.connection().schema;
+    // ── tasks: engine → worker (a RemoteTask) ──────────────────────────────────
+    if (!(await conn().hasTable(TRANSPORT_TABLES.tasks))) {
+        await conn().createTable(TRANSPORT_TABLES.tasks, (table) => {
+            table.string('step_id').primary();
+            table.string('run_id').notNullable();
+            table.integer('seq').notNullable();
+            table.string('name').notNullable();
+            table.string('grp').notNullable();
+            table.text('input');
+            table.string('traceparent');
+            table.text('context');
+            table.string('transport');
+            table.integer('attempt').notNullable();
+            table.string('claimed_by');
+            table.bigInteger('claimed_at');
+            table.bigInteger('created_at').notNullable();
+            table.index(['grp', 'claimed_at', 'created_at'], 'durable_transport_tasks_grp_idx');
+        });
+    }
+    // ── results: worker → engine (a StepResult) ────────────────────────────────
+    if (!(await conn().hasTable(TRANSPORT_TABLES.results))) {
+        await conn().createTable(TRANSPORT_TABLES.results, (table) => {
+            table.string('step_id').primary();
+            table.string('run_id').notNullable();
+            table.integer('seq').notNullable();
+            table.string('status').notNullable();
+            table.text('output');
+            table.text('error');
+            table.bigInteger('started_at');
+            table.text('events');
+            table.string('claimed_by');
+            table.bigInteger('claimed_at');
+            table.bigInteger('created_at').notNullable();
+            table.index(['claimed_at', 'created_at'], 'durable_transport_results_idx');
+        });
+    }
+    // ── heartbeats: worker → engine (liveness for a long step) ─────────────────
+    if (!(await conn().hasTable(TRANSPORT_TABLES.heartbeats))) {
+        await conn().createTable(TRANSPORT_TABLES.heartbeats, (table) => {
+            table.increments('id').primary();
+            table.string('run_id').notNullable();
+            table.integer('seq').notNullable();
+            table.string('step_id').notNullable();
+            table.string('grp').notNullable();
+            table.string('claimed_by');
+            table.bigInteger('claimed_at');
+            table.bigInteger('created_at').notNullable();
+            table.index(['claimed_at', 'created_at'], 'durable_transport_heartbeats_idx');
+        });
+    }
+    // ── control: best-effort control-plane messages (single-consumer) ──────────
+    if (!(await conn().hasTable(TRANSPORT_TABLES.control))) {
+        await conn().createTable(TRANSPORT_TABLES.control, (table) => {
+            table.increments('id').primary();
+            table.text('payload').notNullable();
+            table.string('claimed_by');
+            table.bigInteger('claimed_at');
+            table.bigInteger('created_at').notNullable();
+            table.index(['claimed_at', 'created_at'], 'durable_transport_control_idx');
+        });
+    }
+}
+/** Drop every transport table. Used by tests and the migration `down`. */
+export async function dropDurableTransportTables(db) {
+    const conn = () => db.connection().schema;
+    await conn().dropTableIfExists(TRANSPORT_TABLES.control);
+    await conn().dropTableIfExists(TRANSPORT_TABLES.heartbeats);
+    await conn().dropTableIfExists(TRANSPORT_TABLES.results);
+    await conn().dropTableIfExists(TRANSPORT_TABLES.tasks);
+}
+//# sourceMappingURL=db-schema.js.map

package/dist/src/transports/db-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-schema.js","sourceRoot":"","sources":["../../../src/transports/db-schema.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,yBAAyB;IAChC,OAAO,EAAE,2BAA2B;IACpC,UAAU,EAAE,8BAA8B;IAC1C,OAAO,EAAE,2BAA2B;CAC5B,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,EAAY;IAC7D,qGAAqG;IACrG,+CAA+C;IAC/C,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC;IAE1C,8EAA8E;IAC9E,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,EAAE,CAAC,WAAW,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE;YACzD,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;YAClC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;YACrC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACnC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;YACnC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpB,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACtB,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAC1B,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;YACvC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC3B,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;YAC/B,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YAC7C,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,CAAC,EAAE,iCAAiC,CAAC,CAAC;QACtF,CAAC,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAC9E,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,EAAE,CAAC,WAAW,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3D,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;YAClC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;YACrC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACnC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpB,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC3B,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;YAC/B,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YAC7C,KAAK,CAAC,KAAK,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,EAAE,+BAA+B,CAAC,CAAC;QAC7E,CAAC,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAC9E,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,EAAE,CAAC,WAAW,CAAC,gBAAgB,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE;YAC9D,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACjC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;YACrC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACnC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;YACtC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YAClC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC3B,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;YAC/B,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YAC7C,KAAK,CAAC,KAAK,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,EAAE,kCAAkC,CAAC,CAAC;QAChF,CAAC,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAC9E,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,EAAE,CAAC,WAAW,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3D,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;YACpC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC3B,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;YAC/B,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;YAC7C,KAAK,CAAC,KAAK,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,EAAE,+BAA+B,CAAC,CAAC;QAC7E,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,EAAY;IAC3D,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC;IAC1C,MAAM,IAAI,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACzD,MAAM,IAAI,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC5D,MAAM,IAAI,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACzD,MAAM,IAAI,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC"}

package/dist/src/transports/db.d.ts

@@ -0,0 +1,81 @@
+import type { Database } from '@adonisjs/lucid/database';
+import { type ControlMessage, type ControlPlane, type Heartbeat, type RemoteTask, type StepResult, type Transport } from '../interfaces.js';
+import { type StepHandler } from '../protocol.js';
+export interface DbTransportOptions {
+    /**
+     * The Lucid `Database` to read/write. Use the app's own `db` service (no broker, no extra
+     * connection) — the database you already have IS the queue.
+     */
+    db: Database;
+    /**
+     * The worker group this instance serves. Required to register {@link DbTransport.handle} consumers
+     * — the task poll loop claims rows for this group. Omit on an engine-only instance that just
+     * dispatches + consumes results/heartbeats.
+     */
+    group?: string;
+    /** Lucid connection name to use. Defaults to the `Database` default connection. */
+    connectionName?: string;
+    /** Poll interval (ms) for the result/task/heartbeat/control loops. Default 200ms. */
+    pollIntervalMs?: number;
+    /** How long a claimed-but-unfinished row is owned before it's reclaimable (crash recovery). Default 30s. */
+    leaseMs?: number;
+    /** Max rows claimed per poll. Default 20. */
+    batchSize?: number;
+    /** Create the transport tables on first use if missing. Default true. */
+    autoCreate?: boolean;
+    /** Stable id for this process (stamped on heartbeats / control `from` / `claimed_by`). Default random. */
+    instanceId?: string;
+}
+/**
+ * A poll-based, DB-table-backed {@link Transport} (and best-effort {@link ControlPlane}) over
+ * AdonisJS **Lucid** — DBOS-style. Instead of a broker (Redis/SQS), remote steps are **rows** in the
+ * same database the durable store already uses: `dispatch` inserts a task row; a worker poller claims
+ * unclaimed task rows (atomic conditional `UPDATE … SET claimed_by`), runs the handler via
+ * {@link runStepHandler}, and writes a result row the engine polls. Heartbeats and control messages
+ * ride their own tables. Zero new infrastructure — often the simplest production transport.
+ *
+ * Claiming is portable across SQLite / Postgres / MySQL: it uses a compare-and-set UPDATE on
+ * `claimed_by`/`claimed_at` (no `FOR UPDATE SKIP LOCKED`), so multiple workers never double-process a
+ * row, and a crashed worker's claim is reclaimed once its lease (`leaseMs`) expires.
+ *
+ * Trade-off vs a real broker: throughput is bounded by polling + row contention — great for
+ * workflow/pipeline scale (modest rate, long steps), not for high-fanout firehoses. The
+ * {@link ControlPlane} here is single-consumer (one row → one poller), correct for a single engine
+ * instance but NOT a true broadcast.
+ *
+ * Run one instance engine-side (`onResult` + `dispatch`) and one per worker process (`handle()` for
+ * its group). Call {@link start} to begin the engine-side pollers; `handle()` auto-starts the task
+ * loop. The wire payloads are the documented `RemoteTask`/`StepResult` JSON.
+ *
+ * Usually you don't construct this directly: `config/durable.ts` selects it via
+ * `transports.db({ ... })` and the provider builds it for you.
+ */
+export declare class DbTransport implements Transport, ControlPlane {
+    #private;
+    constructor(options: DbTransportOptions);
+    /** Stable id stamped on heartbeats, control `from`, and `claimed_by`. */
+    get instanceId(): string;
+    dispatch(task: RemoteTask): Promise<void>;
+    /**
+     * Register a step handler (worker side). Starts this group's task poll loop on the first call —
+     * each claimed task runs through {@link runStepHandler} and its result is written for the engine.
+     */
+    handle(name: string, fn: StepHandler): void;
+    /** Worker side: publish a liveness heartbeat for an in-flight long step. */
+    heartbeat(beat: Heartbeat): Promise<void>;
+    onResult(handler: (result: StepResult) => Promise<void>): void;
+    onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
+    publishControl(msg: ControlMessage): Promise<void>;
+    onControl(handler: (msg: ControlMessage) => void): void;
+    /**
+     * No-op convenience: the loops auto-start when `onResult`/`onHeartbeat`/`onControl`/`handle` are
+     * registered. Exposed for symmetry and to mirror broker transports — call it after wiring handlers
+     * if you prefer an explicit start. Returns once the schema is ready.
+     */
+    start(): Promise<void>;
+    /** Stop every poll loop. Does not close the shared `Database`. */
+    stop(): Promise<void>;
+    /** Stop the pollers (alias of {@link stop} for the `Transport.close` contract). */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=db.d.ts.map

package/dist/src/transports/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../../src/transports/db.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAKzD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAqElE,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,EAAE,EAAE,QAAQ,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4GAA4G;IAC5G,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0GAA0G;IAC1G,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAY,YAAW,SAAS,EAAE,YAAY;;gBAc7C,OAAO,EAAE,kBAAkB;IAYvC,yEAAyE;IACzE,IAAI,UAAU,IAAI,MAAM,CAEvB;IAoBK,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B/C;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI;IAW3C,4EAA4E;IACtE,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA4D/C,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAI9D,WAAW,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAyCxD,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxD,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI;IAkFvD;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,kEAAkE;IAC5D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,mFAAmF;IAC7E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}