@hotmeshio/long-tail-dbos 0.0.0-stage → 0.1.0

package/build/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WAIT_DEFAULTS = exports.STEP = exports.toMs = exports.LongTailRequestError = exports.configureLongTail = exports.waitSeconds = exports.conditional = void 0;
+var conditional_1 = require("./conditional");
+Object.defineProperty(exports, "conditional", { enumerable: true, get: function () { return conditional_1.conditional; } });
+Object.defineProperty(exports, "waitSeconds", { enumerable: true, get: function () { return conditional_1.waitSeconds; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "configureLongTail", { enumerable: true, get: function () { return config_1.configureLongTail; } });
+var lt_client_1 = require("./lt-client");
+Object.defineProperty(exports, "LongTailRequestError", { enumerable: true, get: function () { return lt_client_1.LongTailRequestError; } });
+var duration_1 = require("./duration");
+Object.defineProperty(exports, "toMs", { enumerable: true, get: function () { return duration_1.toMs; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "STEP", { enumerable: true, get: function () { return constants_1.STEP; } });
+Object.defineProperty(exports, "WAIT_DEFAULTS", { enumerable: true, get: function () { return constants_1.WAIT_DEFAULTS; } });

package/build/lt-client.d.ts

@@ -0,0 +1,38 @@
+/** A non-2xx response or transport failure from Long Tail. */
+export declare class LongTailRequestError extends Error {
+    readonly status: number | undefined;
+    readonly body: unknown;
+    readonly context: {
+        method: string;
+        url: string;
+    };
+    constructor(message: string, status: number | undefined, body: unknown, context: {
+        method: string;
+        url: string;
+    }, options?: {
+        cause?: unknown;
+    });
+}
+export interface OpenWaitBody {
+    workflowId: string;
+    runScope: string;
+    workflowType?: string;
+    waitKey: string;
+    role: string;
+    type: string;
+    subtype?: string;
+    description?: string;
+    priority?: number;
+    metadata?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+    expiresAt?: string;
+}
+export interface OpenWaitResponse {
+    escalationId: string;
+    status: string;
+    created: boolean;
+}
+/** POST /api/escalations/waits: idempotent on (workflowId, runScope, waitKey). */
+export declare function postOpenWait(body: OpenWaitBody): Promise<OpenWaitResponse>;
+/** POST /api/escalations/:id/cancel. A row that is already closed is not an error. */
+export declare function postCancel(escalationId: string): Promise<void>;

package/build/lt-client.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LongTailRequestError = void 0;
+exports.postOpenWait = postOpenWait;
+exports.postCancel = postCancel;
+const config_1 = require("./config");
+const constants_1 = require("./constants");
+/** A non-2xx response or transport failure from Long Tail. */
+class LongTailRequestError extends Error {
+    status;
+    body;
+    context;
+    constructor(message, status, body, context, options) {
+        super(message, options);
+        this.status = status;
+        this.body = body;
+        this.context = context;
+        this.name = 'LongTailRequestError';
+    }
+}
+exports.LongTailRequestError = LongTailRequestError;
+/** POST /api/escalations/waits: idempotent on (workflowId, runScope, waitKey). */
+function postOpenWait(body) {
+    return request('POST', constants_1.LT_PATHS.OPEN_WAIT, body);
+}
+/** POST /api/escalations/:id/cancel. A row that is already closed is not an error. */
+async function postCancel(escalationId) {
+    try {
+        await request('POST', constants_1.LT_PATHS.CANCEL(escalationId), {});
+    }
+    catch (err) {
+        if (err instanceof LongTailRequestError && err.status === 409)
+            return;
+        throw err;
+    }
+}
+async function request(method, path, body) {
+    const { url, apiKey, requestTimeoutMs } = (0, config_1.getLongTailConnection)();
+    const target = `${url}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), requestTimeoutMs ?? constants_1.WAIT_DEFAULTS.REQUEST_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(target, {
+            method,
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        const reason = controller.signal.aborted ? 'timed out' : 'failed';
+        throw new LongTailRequestError(`Long Tail ${method} ${path} ${reason}`, undefined, undefined, { method, url: target }, { cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const parsed = await parseBody(response);
+    if (!response.ok) {
+        const detail = typeof parsed === 'object' && parsed && 'error' in parsed ? `: ${parsed.error}` : '';
+        throw new LongTailRequestError(`Long Tail ${method} ${path} returned ${response.status}${detail}`, response.status, parsed, { method, url: target });
+    }
+    return parsed;
+}
+async function parseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    if ((response.headers.get('content-type') ?? '').includes('application/json')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}

package/build/provider/index.d.ts

@@ -0,0 +1,22 @@
+import { DBOSClient } from '@dbos-inc/dbos-sdk';
+import { type LTDurableProvider } from '@hotmeshio/long-tail';
+import { type WorkflowCounter } from './list';
+export interface DbosProviderConfig {
+    /** The DBOS system database the application uses. */
+    systemDatabaseUrl: string;
+    /** Postgres schema of the DBOS system tables, when not the default. */
+    systemDatabaseSchemaName?: string;
+}
+/** The subset of DBOSClient the provider calls. */
+export type DbosClientLike = Pick<DBOSClient, 'getWorkflow' | 'listWorkflows' | 'listWorkflowSteps' | 'send' | 'cancelWorkflow' | 'destroy'>;
+export interface DbosProvider extends LTDurableProvider {
+    /** Release the client's and the counter's database pools. */
+    close(): Promise<void>;
+}
+/** A Long Tail durable provider for workflows running on DBOS. */
+export declare function dbosProvider(config: DbosProviderConfig): Promise<DbosProvider>;
+/** Without a counter the provider does not list. */
+export declare function createDbosProvider(client: DbosClientLike, countWorkflows?: WorkflowCounter): DbosProvider;
+export { buildExecution, type DbosStep } from './steps-map';
+export { toJobStatus, toJobState, isTerminal } from './status';
+export { createWorkflowCounter, countWorkflowsSql, listFilter, LIST_STATE_STATUSES, type WorkflowCounter } from './list';

package/build/provider/index.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_STATE_STATUSES = exports.listFilter = exports.countWorkflowsSql = exports.createWorkflowCounter = exports.isTerminal = exports.toJobState = exports.toJobStatus = exports.buildExecution = void 0;
+exports.dbosProvider = dbosProvider;
+exports.createDbosProvider = createDbosProvider;
+const dbos_sdk_1 = require("@dbos-inc/dbos-sdk");
+const pg_1 = require("pg");
+const long_tail_1 = require("@hotmeshio/long-tail");
+const constants_1 = require("../constants");
+const list_1 = require("./list");
+const status_1 = require("./status");
+const steps_map_1 = require("./steps-map");
+/** A Long Tail durable provider for workflows running on DBOS. */
+async function dbosProvider(config) {
+    if (!config?.systemDatabaseUrl)
+        throw new Error('dbosProvider: systemDatabaseUrl is required');
+    const client = await dbos_sdk_1.DBOSClient.create({
+        systemDatabaseUrl: config.systemDatabaseUrl,
+        ...(config.systemDatabaseSchemaName ? { systemDatabaseSchemaName: config.systemDatabaseSchemaName } : {}),
+    });
+    // DBOSClient lists but does not count; the executions list needs a total.
+    const pool = new pg_1.Pool({ connectionString: config.systemDatabaseUrl, max: constants_1.COUNT_POOL_SIZE });
+    const provider = createDbosProvider(client, (0, list_1.createWorkflowCounter)(pool, config.systemDatabaseSchemaName));
+    return {
+        ...provider,
+        async close() {
+            await provider.close();
+            await pool.end();
+        },
+    };
+}
+/** Without a counter the provider does not list. */
+function createDbosProvider(client, countWorkflows) {
+    return {
+        name: constants_1.PROVIDER_NAME,
+        capabilities: { native: false, execution: true, terminate: true, list: !!countWorkflows },
+        async deliver(ref, outcome) {
+            // A send to a finished workflow is stored and never read, so check first.
+            const status = await client.getWorkflow(ref.workflowId);
+            if (!status || (0, status_1.isTerminal)(status.status))
+                return long_tail_1.DELIVERY_RESULT.GONE;
+            try {
+                await client.send(ref.workflowId, outcome, ref.waitKey, outcome.escalationId);
+                return long_tail_1.DELIVERY_RESULT.DELIVERED;
+            }
+            catch (err) {
+                if (err instanceof dbos_sdk_1.Error.DBOSNonExistentWorkflowError)
+                    return long_tail_1.DELIVERY_RESULT.GONE;
+                throw err;
+            }
+        },
+        async describe(workflowId) {
+            return (0, status_1.toJobStatus)(workflowId, await client.getWorkflow(workflowId));
+        },
+        async export(workflowId, options) {
+            const status = await client.getWorkflow(workflowId);
+            if (!status)
+                throw new Error(`DBOS workflow ${workflowId} not found`);
+            return (0, steps_map_1.buildExecution)(status, await allSteps(client, workflowId), options);
+        },
+        async terminate(workflowId) {
+            await client.cancelWorkflow(workflowId);
+        },
+        ...(countWorkflows ? {
+            async list(query) {
+                const filter = (0, list_1.listFilter)(query);
+                const [rows, total] = await Promise.all([
+                    client.listWorkflows({ ...filter, limit: query.limit, offset: query.offset, sortDesc: true, loadInput: false, loadOutput: false }),
+                    countWorkflows(query),
+                ]);
+                return { workflows: rows.map((row) => (0, status_1.toJobStatus)(row.workflowID, row)), total };
+            },
+        } : {}),
+        close: () => client.destroy(),
+    };
+}
+async function allSteps(client, workflowId) {
+    const steps = [];
+    for (let offset = 0;; offset += constants_1.STEP_PAGE_SIZE) {
+        const page = (await client.listWorkflowSteps(workflowId, { limit: constants_1.STEP_PAGE_SIZE, offset })) ?? [];
+        steps.push(...page);
+        if (page.length < constants_1.STEP_PAGE_SIZE)
+            return steps;
+    }
+}
+var steps_map_2 = require("./steps-map");
+Object.defineProperty(exports, "buildExecution", { enumerable: true, get: function () { return steps_map_2.buildExecution; } });
+var status_2 = require("./status");
+Object.defineProperty(exports, "toJobStatus", { enumerable: true, get: function () { return status_2.toJobStatus; } });
+Object.defineProperty(exports, "toJobState", { enumerable: true, get: function () { return status_2.toJobState; } });
+Object.defineProperty(exports, "isTerminal", { enumerable: true, get: function () { return status_2.isTerminal; } });
+var list_2 = require("./list");
+Object.defineProperty(exports, "createWorkflowCounter", { enumerable: true, get: function () { return list_2.createWorkflowCounter; } });
+Object.defineProperty(exports, "countWorkflowsSql", { enumerable: true, get: function () { return list_2.countWorkflowsSql; } });
+Object.defineProperty(exports, "listFilter", { enumerable: true, get: function () { return list_2.listFilter; } });
+Object.defineProperty(exports, "LIST_STATE_STATUSES", { enumerable: true, get: function () { return list_2.LIST_STATE_STATUSES; } });

package/build/provider/list.d.ts

@@ -0,0 +1,20 @@
+import { type GetWorkflowsInput } from '@dbos-inc/dbos-sdk';
+import { type LTWorkflowListQuery, type LTWorkflowListState } from '@hotmeshio/long-tail';
+/** DBOS statuses behind each executions-list state. */
+export declare const LIST_STATE_STATUSES: Record<LTWorkflowListState, string[]>;
+/** The listWorkflows filter for a query, without paging. */
+export declare function listFilter(query: LTWorkflowListQuery): GetWorkflowsInput;
+/**
+ * Counts the workflows a query matches, with the conditions DBOS's
+ * listWorkflows applies: name, status and an id prefix matched with LIKE.
+ */
+export declare function countWorkflowsSql(schema?: string): string;
+export type WorkflowCounter = (query: LTWorkflowListQuery) => Promise<number>;
+export interface SqlQuerier {
+    query(text: string, values: unknown[]): Promise<{
+        rows: Array<{
+            total: number;
+        }>;
+    }>;
+}
+export declare function createWorkflowCounter(db: SqlQuerier, schema?: string): WorkflowCounter;

package/build/provider/list.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_STATE_STATUSES = void 0;
+exports.listFilter = listFilter;
+exports.countWorkflowsSql = countWorkflowsSql;
+exports.createWorkflowCounter = createWorkflowCounter;
+const dbos_sdk_1 = require("@dbos-inc/dbos-sdk");
+const long_tail_1 = require("@hotmeshio/long-tail");
+/** DBOS statuses behind each executions-list state. */
+exports.LIST_STATE_STATUSES = {
+    [long_tail_1.WORKFLOW_LIST_STATE.RUNNING]: [dbos_sdk_1.StatusString.PENDING, dbos_sdk_1.StatusString.ENQUEUED, 'DELAYED', 'SUSPENDED'],
+    [long_tail_1.WORKFLOW_LIST_STATE.COMPLETED]: [dbos_sdk_1.StatusString.SUCCESS],
+    [long_tail_1.WORKFLOW_LIST_STATE.FAILED]: [dbos_sdk_1.StatusString.ERROR, dbos_sdk_1.StatusString.CANCELLED, dbos_sdk_1.StatusString.MAX_RECOVERY_ATTEMPTS_EXCEEDED],
+};
+const DEFAULT_SCHEMA = 'dbos';
+const SCHEMA_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The listWorkflows filter for a query, without paging. */
+function listFilter(query) {
+    return {
+        ...(query.workflowType ? { workflowName: query.workflowType } : {}),
+        ...(query.state ? { status: exports.LIST_STATE_STATUSES[query.state] } : {}),
+        ...(query.idPrefix ? { workflow_id_prefix: query.idPrefix } : {}),
+    };
+}
+/**
+ * Counts the workflows a query matches, with the conditions DBOS's
+ * listWorkflows applies: name, status and an id prefix matched with LIKE.
+ */
+function countWorkflowsSql(schema = DEFAULT_SCHEMA) {
+    if (!SCHEMA_NAME.test(schema))
+        throw new Error(`Invalid DBOS system schema name: ${schema}`);
+    return `SELECT count(*)::int AS total FROM "${schema}".workflow_status
+    WHERE ($1::text IS NULL OR name = $1::text)
+      AND ($2::text[] IS NULL OR status = ANY($2::text[]))
+      AND ($3::text IS NULL OR workflow_uuid LIKE $3::text || '%')`;
+}
+function createWorkflowCounter(db, schema) {
+    const sql = countWorkflowsSql(schema);
+    return async (query) => {
+        const { rows } = await db.query(sql, [
+            query.workflowType ?? null,
+            query.state ? exports.LIST_STATE_STATUSES[query.state] : null,
+            query.idPrefix ?? null,
+        ]);
+        return rows[0]?.total ?? 0;
+    };
+}

package/build/provider/status.d.ts

@@ -0,0 +1,6 @@
+import { type WorkflowStatus } from '@dbos-inc/dbos-sdk';
+import { type LTJobState, type LTJobStatus } from '@hotmeshio/long-tail';
+export declare function toJobState(status: string | undefined): LTJobState;
+/** True once the workflow can no longer receive a message. */
+export declare function isTerminal(status: string): boolean;
+export declare function toJobStatus(workflowId: string, status: WorkflowStatus | undefined | null): LTJobStatus;

package/build/provider/status.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJobState = toJobState;
+exports.isTerminal = isTerminal;
+exports.toJobStatus = toJobStatus;
+const dbos_sdk_1 = require("@dbos-inc/dbos-sdk");
+const long_tail_1 = require("@hotmeshio/long-tail");
+const RUNNING = [dbos_sdk_1.StatusString.PENDING, dbos_sdk_1.StatusString.ENQUEUED, 'DELAYED', 'SUSPENDED'];
+const FAILED = [dbos_sdk_1.StatusString.ERROR, dbos_sdk_1.StatusString.MAX_RECOVERY_ATTEMPTS_EXCEEDED];
+function toJobState(status) {
+    if (!status)
+        return long_tail_1.JOB_STATE.UNKNOWN;
+    if (RUNNING.includes(status))
+        return long_tail_1.JOB_STATE.RUNNING;
+    if (status === dbos_sdk_1.StatusString.SUCCESS)
+        return long_tail_1.JOB_STATE.COMPLETED;
+    if (status === dbos_sdk_1.StatusString.CANCELLED)
+        return long_tail_1.JOB_STATE.CANCELLED;
+    if (FAILED.includes(status))
+        return long_tail_1.JOB_STATE.FAILED;
+    return long_tail_1.JOB_STATE.UNKNOWN;
+}
+/** True once the workflow can no longer receive a message. */
+function isTerminal(status) {
+    return !RUNNING.includes(status);
+}
+function toJobStatus(workflowId, status) {
+    if (!status)
+        return { workflowId, state: long_tail_1.JOB_STATE.UNKNOWN, providerState: 'NOT_FOUND' };
+    return {
+        workflowId,
+        workflowType: status.workflowName,
+        state: toJobState(status.status),
+        providerState: status.status,
+        startedAt: new Date(status.createdAt).toISOString(),
+        ...(status.completedAt ? { closedAt: new Date(status.completedAt).toISOString() } : {}),
+    };
+}

package/build/provider/steps-map.d.ts

@@ -0,0 +1,22 @@
+import type { WorkflowStatus } from '@dbos-inc/dbos-sdk';
+import { type LTExecutionExportOptions, type LTWorkflowExecution } from '@hotmeshio/long-tail';
+/** The fields of a DBOS StepInfo the timeline reads. */
+export interface DbosStep {
+    functionID: number;
+    name: string;
+    output: unknown;
+    error: unknown;
+    childWorkflowID: string | null;
+    startedAtEpochMs?: number;
+    completedAtEpochMs?: number;
+}
+/**
+ * DBOS status + steps as the Long Tail execution timeline.
+ *
+ * - User steps become activity scheduled/completed (or failed) pairs.
+ * - `lt.open` starts a signal wait; the next `DBOS.recv` ends it.
+ * - A timed recv writes its deadline as `DBOS.sleep` at the next function id; it is folded in.
+ * - A child start and its `DBOS.getResult` pair on the child id.
+ * - Steps record outputs only; DBOS does not store step inputs.
+ */
+export declare function buildExecution(status: WorkflowStatus, steps: DbosStep[], options?: LTExecutionExportOptions): LTWorkflowExecution;

package/build/provider/steps-map.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExecution = buildExecution;
+const long_tail_1 = require("@hotmeshio/long-tail");
+const constants_1 = require("../constants");
+const status_1 = require("./status");
+/**
+ * DBOS status + steps as the Long Tail execution timeline.
+ *
+ * - User steps become activity scheduled/completed (or failed) pairs.
+ * - `lt.open` starts a signal wait; the next `DBOS.recv` ends it.
+ * - A timed recv writes its deadline as `DBOS.sleep` at the next function id; it is folded in.
+ * - A child start and its `DBOS.getResult` pair on the child id.
+ * - Steps record outputs only; DBOS does not store step inputs.
+ */
+function buildExecution(status, steps, options = {}) {
+    const events = [];
+    const byId = new Map(steps.map((s) => [s.functionID, s]));
+    const push = (event_type, category, at, attrs, opts = {}) => {
+        if (opts.system && options.excludeSystem)
+            return;
+        events.push({
+            event_id: events.length + 1,
+            event_type,
+            category,
+            event_time: iso(at ?? status.createdAt),
+            duration_ms: opts.duration ?? null,
+            is_system: Boolean(opts.system),
+            attributes: { kind: event_type, ...attrs },
+        });
+    };
+    const result = (value) => (options.omitResults ? undefined : value);
+    push('workflow_execution_started', 'workflow', status.createdAt, { input: result(status.input) });
+    let openWaitKey = null;
+    for (const step of steps) {
+        const start = step.startedAtEpochMs;
+        const end = step.completedAtEpochMs;
+        if (step.name === constants_1.STEP.OPEN) {
+            const waitKey = step.output?.waitKey ?? null;
+            pushActivity(push, step, true, result);
+            if (waitKey) {
+                openWaitKey = waitKey;
+                push('signal_wait_started', 'signal', end ?? start, { signal_name: waitKey, timeline_key: `w:${waitKey}` });
+            }
+        }
+        else if (step.name === constants_1.DBOS_OP.RECV) {
+            const key = openWaitKey ?? `recv:${step.functionID}`;
+            push('workflow_execution_signaled', 'signal', end, { signal_name: key, timeline_key: `w:${key}`, input: result(step.output) });
+            openWaitKey = null;
+        }
+        else if (step.name === constants_1.DBOS_OP.SLEEP) {
+            if (isRecvDeadline(step, byId))
+                continue;
+            const duration = start !== undefined && end !== undefined ? end - start : null;
+            push('timer_started', 'timer', start, { timeline_key: `t:${step.functionID}` }, { duration });
+        }
+        else if (step.childWorkflowID && step.name !== constants_1.DBOS_OP.GET_RESULT) {
+            push('child_workflow_execution_started', 'child_workflow', start, { child_workflow_id: step.childWorkflowID, timeline_key: `c:${step.childWorkflowID}` });
+        }
+        else if (step.childWorkflowID && step.name === constants_1.DBOS_OP.GET_RESULT) {
+            const type = step.error ? 'child_workflow_execution_failed' : 'child_workflow_execution_completed';
+            push(type, 'child_workflow', end, { child_workflow_id: step.childWorkflowID, timeline_key: `c:${step.childWorkflowID}`, result: result(step.output), ...(step.error ? { failure: errorText(step.error) } : {}) });
+        }
+        else {
+            pushActivity(push, step, constants_1.DBOS_SYSTEM_STEPS.includes(step.name) || step.name.startsWith('DBOS.'), result);
+        }
+    }
+    const state = (0, status_1.toJobState)(status.status);
+    const closed = state !== 'running' && state !== 'unknown';
+    if (closed) {
+        const failed = state !== 'completed';
+        push(failed ? 'workflow_execution_failed' : 'workflow_execution_completed', 'workflow', status.completedAt ?? status.updatedAt, failed
+            ? { failure: errorText(status.error) }
+            : { result: result(status.output) });
+    }
+    return {
+        workflow_id: status.workflowID,
+        workflow_type: status.workflowName,
+        workflow_name: status.workflowName,
+        task_queue: status.queueName ?? '',
+        status: !closed ? 'running' : state === 'completed' ? 'completed' : 'failed',
+        provider_status: status.status,
+        start_time: iso(status.createdAt),
+        close_time: closed && status.completedAt ? iso(status.completedAt) : null,
+        duration_ms: closed && status.completedAt ? status.completedAt - status.createdAt : null,
+        ...(status.parentWorkflowID ? { parent_workflow_id: status.parentWorkflowID } : {}),
+        ...(closed && state === 'completed' ? { result: result(status.output) } : {}),
+        events,
+        summary: (0, long_tail_1.summarizeExecution)(events),
+    };
+}
+function pushActivity(push, step, system, result) {
+    const key = `s:${step.functionID}`;
+    push('activity_task_scheduled', 'activity', step.startedAtEpochMs, { activity_type: step.name, timeline_key: key }, { system });
+    if (step.completedAtEpochMs === undefined)
+        return;
+    const duration = step.startedAtEpochMs !== undefined ? step.completedAtEpochMs - step.startedAtEpochMs : null;
+    if (step.error) {
+        push('activity_task_failed', 'activity', step.completedAtEpochMs, { activity_type: step.name, timeline_key: key, failure: errorText(step.error) }, { system, duration });
+    }
+    else {
+        push('activity_task_completed', 'activity', step.completedAtEpochMs, { activity_type: step.name, timeline_key: key, result: result(step.output) }, { system, duration });
+    }
+}
+/**
+ * A timed recv writes its deadline as DBOS.sleep at the next function id. While
+ * the recv waits its own row is absent; the deadline row records no elapsed time
+ * and a wake time after it completed.
+ */
+function isRecvDeadline(step, byId) {
+    const before = byId.get(step.functionID - 1);
+    if (before)
+        return before.name === constants_1.DBOS_OP.RECV;
+    const wake = Number(step.output);
+    return step.completedAtEpochMs !== undefined && Number.isFinite(wake) && wake > step.completedAtEpochMs;
+}
+function errorText(error) {
+    if (error === undefined || error === null)
+        return undefined;
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'object' && 'message' in error)
+        return String(error.message);
+    return typeof error === 'string' ? error : JSON.stringify(error);
+}
+function iso(ms) {
+    return new Date(ms ?? Date.now()).toISOString();
+}

package/build/start.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Long Tail with DBOS as the durable engine, configured from the environment:
+ * DBOS_SYSTEM_DATABASE_URL (defaults to DATABASE_URL, one database), DBOS_SYSTEM_DATABASE_SCHEMA, DBOS_CONSOLE_URL,
+ * DATABASE_URL or POSTGRES_*, PORT, JWT_SECRET, LT_ADMIN_USER / LT_ADMIN_PASSWORD / LT_ADMIN_EMAIL, LT_ROLES.
+ * LT_START_CONFIG optionally names a JSON file with further start() settings.
+ */
+export declare function startLongTailDbos(env?: NodeJS.ProcessEnv): Promise<{
+    instance: import("@hotmeshio/long-tail").LTInstance;
+    shutdown(): Promise<void>;
+}>;

package/build/start.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startLongTailDbos = startLongTailDbos;
+const fs_1 = require("fs");
+const long_tail_1 = require("@hotmeshio/long-tail");
+const provider_1 = require("./provider");
+const DEFAULT_ADMIN = 'superadmin';
+const ENV_OWNED_KEYS = ['database', 'server', 'durable', 'workers', 'examples'];
+/**
+ * Long Tail with DBOS as the durable engine, configured from the environment:
+ * DBOS_SYSTEM_DATABASE_URL (defaults to DATABASE_URL, one database), DBOS_SYSTEM_DATABASE_SCHEMA, DBOS_CONSOLE_URL,
+ * DATABASE_URL or POSTGRES_*, PORT, JWT_SECRET, LT_ADMIN_USER / LT_ADMIN_PASSWORD / LT_ADMIN_EMAIL, LT_ROLES.
+ * LT_START_CONFIG optionally names a JSON file with further start() settings.
+ */
+async function startLongTailDbos(env = process.env) {
+    // 1. DBOS provider
+    const provider = await (0, provider_1.dbosProvider)({
+        systemDatabaseUrl: systemDatabaseUrl(env),
+        systemDatabaseSchemaName: env.DBOS_SYSTEM_DATABASE_SCHEMA || undefined,
+    });
+    // 2. Long Tail
+    const instance = await (0, long_tail_1.start)({
+        ...fileConfig(env.LT_START_CONFIG),
+        database: env.DATABASE_URL ? { connectionString: env.DATABASE_URL } : {
+            host: env.POSTGRES_HOST, port: env.POSTGRES_PORT ? Number(env.POSTGRES_PORT) : undefined,
+            user: env.POSTGRES_USER, password: env.POSTGRES_PASSWORD, database: env.POSTGRES_DB,
+        },
+        server: { port: env.PORT ? Number(env.PORT) : undefined },
+        ...(env.JWT_SECRET ? { auth: { secret: env.JWT_SECRET } } : {}),
+        ...(env.LT_ADMIN_PASSWORD ? { seed: { admin: {
+                    externalId: env.LT_ADMIN_USER ?? DEFAULT_ADMIN, email: env.LT_ADMIN_EMAIL, password: env.LT_ADMIN_PASSWORD,
+                } } } : {}),
+        ...(env.LT_ROLES ? { roles: env.LT_ROLES.split(',').map((role) => ({ role: role.trim() })).filter((r) => r.role) } : {}),
+        durable: { provider, consoleUrl: env.DBOS_CONSOLE_URL || undefined },
+    });
+    return {
+        instance,
+        async shutdown() {
+            await instance.shutdown();
+            await provider.close();
+        },
+    };
+}
+function systemDatabaseUrl(env) {
+    const value = env.DBOS_SYSTEM_DATABASE_URL || env.DATABASE_URL;
+    if (!value)
+        throw new Error('DBOS_SYSTEM_DATABASE_URL or DATABASE_URL is required');
+    return value;
+}
+function fileConfig(path) {
+    if (!path)
+        return {};
+    const parsed = JSON.parse((0, fs_1.readFileSync)(path, 'utf-8'));
+    for (const key of ENV_OWNED_KEYS) {
+        if (key in parsed)
+            throw new Error(`LT_START_CONFIG may not set "${key}"; it is set by environment or not allowed with DBOS`);
+    }
+    return parsed;
+}
+if (require.main === module) {
+    startLongTailDbos().then((running) => {
+        const stop = async () => {
+            await running.shutdown();
+            process.exit(0);
+        };
+        process.on('SIGTERM', stop);
+        process.on('SIGINT', stop);
+    }).catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/build/steps.d.ts

@@ -0,0 +1,7 @@
+import type { LTConditionalConfig, OpenedWait } from './types';
+/** Open the escalation this workflow waits on. Runs as a checkpointed step. */
+export declare function openWait(waitKey: string, config: LTConditionalConfig): Promise<OpenedWait>;
+/** Cancel the escalation when the recv deadline passes first. */
+export declare function closeWait(escalationId: string): Promise<void>;
+export declare const ltOpen: (this: unknown, waitKey: string, config: LTConditionalConfig) => Promise<OpenedWait>;
+export declare const ltClose: (this: unknown, escalationId: string) => Promise<void>;