@voyant-travel/db 0.108.0

package/dist/schema/infra/write_intents.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Async write intents (RFC voyant#1687 Phase 3.2 — the queued write
+ * pipeline's result mailbox).
+ *
+ * An intent is "a write the caller asked for but didn't wait for": the
+ * route validates the payload, stores it here, durably emits a
+ * `<kind>.requested` event (transactional outbox), and answers
+ * **202 + a status URL**. The outbox delivers the event to the intent's
+ * handler — with the outbox's at-least-once retries, backoff, and
+ * dead-lettering — and the handler writes the outcome back onto the
+ * row. Under a payday spike, callers get instant 202s and the work
+ * drains at the outbox's controlled pace instead of thundering-herding
+ * the booking transaction.
+ *
+ * Dedup: `idempotency_key` is unique — a retried POST with the same key
+ * returns the SAME intent rather than enqueueing twice.
+ *
+ * Status semantics: `pending` until a handler settles it. Handlers
+ * distinguish FINAL business outcomes (capacity conflict → `failed`
+ * with a result payload, never retried) from infra errors (thrown →
+ * the outbox retries). A stale sweep fails intents whose event
+ * dead-lettered.
+ */
+export declare const writeIntentsTable: Omit<import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "write_intents";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "write_intents";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        kind: import("drizzle-orm/pg-core").PgColumn<{
+            name: "kind";
+            tableName: "write_intents";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        payload: import("drizzle-orm/pg-core").PgColumn<{
+            name: "payload";
+            tableName: "write_intents";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        idempotencyKey: import("drizzle-orm/pg-core").PgColumn<{
+            name: "idempotency_key";
+            tableName: "write_intents";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "write_intents";
+            dataType: "string";
+            columnType: "PgText";
+            data: "failed" | "pending" | "succeeded";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["pending", "succeeded", "failed"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        result: import("drizzle-orm/pg-core").PgColumn<{
+            name: "result";
+            tableName: "write_intents";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        error: import("drizzle-orm/pg-core").PgColumn<{
+            name: "error";
+            tableName: "write_intents";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "write_intents";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        completedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "completed_at";
+            tableName: "write_intents";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>, "enableRLS">;
+export type WriteIntentRow = typeof writeIntentsTable.$inferSelect;
+//# sourceMappingURL=write_intents.d.ts.map

package/dist/schema/infra/write_intents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write_intents.d.ts","sourceRoot":"","sources":["../../../src/schema/infra/write_intents.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBA0BjB,CAAA;AAEb,MAAM,MAAM,cAAc,GAAG,OAAO,iBAAiB,CAAC,YAAY,CAAA"}

package/dist/schema/infra/write_intents.js

@@ -0,0 +1,50 @@
+import { sql } from "drizzle-orm";
+import { index, jsonb, pgTable, text, timestamp, uniqueIndex } from "drizzle-orm/pg-core";
+import { typeId } from "../../lib/index.js";
+/**
+ * Async write intents (RFC voyant#1687 Phase 3.2 — the queued write
+ * pipeline's result mailbox).
+ *
+ * An intent is "a write the caller asked for but didn't wait for": the
+ * route validates the payload, stores it here, durably emits a
+ * `<kind>.requested` event (transactional outbox), and answers
+ * **202 + a status URL**. The outbox delivers the event to the intent's
+ * handler — with the outbox's at-least-once retries, backoff, and
+ * dead-lettering — and the handler writes the outcome back onto the
+ * row. Under a payday spike, callers get instant 202s and the work
+ * drains at the outbox's controlled pace instead of thundering-herding
+ * the booking transaction.
+ *
+ * Dedup: `idempotency_key` is unique — a retried POST with the same key
+ * returns the SAME intent rather than enqueueing twice.
+ *
+ * Status semantics: `pending` until a handler settles it. Handlers
+ * distinguish FINAL business outcomes (capacity conflict → `failed`
+ * with a result payload, never retried) from infra errors (thrown →
+ * the outbox retries). A stale sweep fails intents whose event
+ * dead-lettered.
+ */
+export const writeIntentsTable = pgTable("write_intents", {
+    id: typeId("write_intents"),
+    /** Handler routing key, e.g. "storefront.booking.bootstrap". */
+    kind: text("kind").notNull(),
+    /** The validated request payload the handler will execute. */
+    payload: jsonb("payload").notNull(),
+    /** Client-supplied (Idempotency-Key) or generated. Unique. */
+    idempotencyKey: text("idempotency_key").notNull(),
+    status: text("status", { enum: ["pending", "succeeded", "failed"] })
+        .notNull()
+        .default("pending"),
+    /** Handler outcome payload (success result OR final-failure detail). */
+    result: jsonb("result"),
+    /** Infra/dead-letter error detail for failed intents. */
+    error: text("error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+}, (table) => [
+    uniqueIndex("write_intents_idempotency_key_uniq").on(table.idempotencyKey),
+    // Stale-sweep working set; partial keeps it tiny.
+    // agent-quality: raw-sql reviewed -- owner: db; dynamic SQL interpolation uses Drizzle parameter binding or vetted SQL identifiers.
+    index("write_intents_pending_idx").on(table.createdAt).where(sql `${table.status} = 'pending'`),
+]).enableRLS();
+//# sourceMappingURL=write_intents.js.map

package/dist/schema/infra/write_intents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write_intents.js","sourceRoot":"","sources":["../../../src/schema/infra/write_intents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AACjC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEzF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CACtC,eAAe,EACf;IACE,EAAE,EAAE,MAAM,CAAC,eAAe,CAAC;IAC3B,gEAAgE;IAChE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE;IAC5B,8DAA8D;IAC9D,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IACnC,8DAA8D;IAC9D,cAAc,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE;IACjD,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,CAAC;SACjE,OAAO,EAAE;SACT,OAAO,CAAC,SAAS,CAAC;IACrB,wEAAwE;IACxE,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB,yDAAyD;IACzD,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC,YAAY,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE;IACjF,WAAW,EAAE,SAAS,CAAC,cAAc,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;CAC/D,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,WAAW,CAAC,oCAAoC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC;IAC1E,kDAAkD;IAClD,oIAAoI;IACpI,KAAK,CAAC,2BAA2B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,CAAA,GAAG,KAAK,CAAC,MAAM,cAAc,CAAC;CAC/F,CACF,CAAC,SAAS,EAAE,CAAA"}

package/dist/schema/voyant/bookings.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bookings.d.ts.map

package/dist/schema/voyant/bookings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookings.d.ts","sourceRoot":"","sources":["../../../src/schema/voyant/bookings.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAA"}

package/dist/schema/voyant/bookings.js

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

package/dist/schema/voyant/bookings.js.map

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

package/dist/schema/voyant/finance.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=finance.d.ts.map

package/dist/schema/voyant/finance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finance.d.ts","sourceRoot":"","sources":["../../../src/schema/voyant/finance.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAA"}

package/dist/schema/voyant/finance.js

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

package/dist/schema/voyant/finance.js.map

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

package/dist/test-utils.d.ts

@@ -0,0 +1,17 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+/**
+ * Creates a database client connected to the test database.
+ * Requires the test Postgres instance from `docker-compose.test.yml`.
+ *
+ * Always uses the Node.js adapter (postgres.js) since tests run in Node.
+ */
+export declare function createTestDb(): PostgresJsDatabase;
+/**
+ * Closes the shared test database client for the current process.
+ */
+export declare function closeTestDb(): Promise<void>;
+/**
+ * Truncates all non-system tables in the test database.
+ */
+export declare function cleanupTestDb(db: PostgresJsDatabase): Promise<void>;
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../src/test-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AA4BjE;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAcjD;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAKjD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUzE"}

package/dist/test-utils.js

@@ -0,0 +1,56 @@
+import { sql } from "drizzle-orm";
+import { createDbClient } from "./index.js";
+const TEST_DB_PORT = process.env.TEST_DATABASE_PORT ?? "5436";
+const TEST_DB_NAME = "voyant_test";
+const TEST_DB_USER = "test";
+const TEST_DB_PASSWORD = "test";
+function buildDefaultTestDbUrl(port) {
+    const url = new URL("postgres://localhost");
+    url.port = port;
+    url.pathname = `/${TEST_DB_NAME}`;
+    url.username = TEST_DB_USER;
+    url.password = TEST_DB_PASSWORD;
+    return url.toString();
+}
+const TEST_DB_URL = process.env.TEST_DATABASE_URL ?? buildDefaultTestDbUrl(TEST_DB_PORT);
+let testDbSingleton = null;
+/**
+ * Creates a database client connected to the test database.
+ * Requires the test Postgres instance from `docker-compose.test.yml`.
+ *
+ * Always uses the Node.js adapter (postgres.js) since tests run in Node.
+ */
+export function createTestDb() {
+    if (!testDbSingleton) {
+        testDbSingleton = createDbClient(TEST_DB_URL, {
+            adapter: "node",
+            nodeMaxConnections: 1,
+            // Production timeout defaults don't apply to test infrastructure:
+            // cleanupTestDb's TRUNCATE over the full ~350-table schema can
+            // exceed the 10s statement_timeout on a cold Postgres, killing
+            // every integration suite's setup.
+            timeouts: { statementMs: false, queryMs: false, connectMs: false },
+        });
+    }
+    return testDbSingleton;
+}
+/**
+ * Closes the shared test database client for the current process.
+ */
+export async function closeTestDb() {
+    const db = testDbSingleton;
+    testDbSingleton = null;
+    await db?.$client?.end?.({ timeout: 0 });
+}
+/**
+ * Truncates all non-system tables in the test database.
+ */
+export async function cleanupTestDb(db) {
+    const result = await db.execute(sql `SELECT tablename FROM pg_tables WHERE schemaname = 'public'`);
+    const tables = result;
+    if (tables.length > 0) {
+        const names = tables.map((r) => `"${r.tablename}"`).join(", ");
+        await db.execute(sql.raw(`TRUNCATE ${names} CASCADE`));
+    }
+}
+//# sourceMappingURL=test-utils.js.map

package/dist/test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.js","sourceRoot":"","sources":["../src/test-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAGjC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,MAAM,CAAA;AAC7D,MAAM,YAAY,GAAG,aAAa,CAAA;AAClC,MAAM,YAAY,GAAG,MAAM,CAAA;AAC3B,MAAM,gBAAgB,GAAG,MAAM,CAAA;AAE/B,SAAS,qBAAqB,CAAC,IAAY;IACzC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,sBAAsB,CAAC,CAAA;IAC3C,GAAG,CAAC,IAAI,GAAG,IAAI,CAAA;IACf,GAAG,CAAC,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAA;IACjC,GAAG,CAAC,QAAQ,GAAG,YAAY,CAAA;IAC3B,GAAG,CAAC,QAAQ,GAAG,gBAAgB,CAAA;IAC/B,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAA;AACvB,CAAC;AAED,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,qBAAqB,CAAC,YAAY,CAAC,CAAA;AAQxF,IAAI,eAAe,GAAwC,IAAI,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,eAAe,GAAG,cAAc,CAAC,WAAW,EAAE;YAC5C,OAAO,EAAE,MAAM;YACf,kBAAkB,EAAE,CAAC;YACrB,kEAAkE;YAClE,+DAA+D;YAC/D,+DAA+D;YAC/D,mCAAmC;YACnC,QAAQ,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE;SACnE,CAAiC,CAAA;IACpC,CAAC;IAED,OAAO,eAAe,CAAA;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,EAAE,GAAG,eAAe,CAAA;IAC1B,eAAe,GAAG,IAAI,CAAA;IAEtB,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAA;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAsB;IACxD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAC7B,GAAG,CAAA,6DAA6D,CACjE,CAAA;IAED,MAAM,MAAM,GAAG,MAAiC,CAAA;IAChD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC9D,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,KAAK,UAAU,CAAC,CAAC,CAAA;IACxD,CAAC;AACH,CAAC"}

package/dist/transaction-capability.d.ts

@@ -0,0 +1,11 @@
+export declare const VOYANT_DB_SUPPORTS_TRANSACTIONS: unique symbol;
+export declare const VOYANT_DB_DISPOSE: unique symbol;
+export type DbTransactionCapability = {
+    [VOYANT_DB_SUPPORTS_TRANSACTIONS]?: boolean;
+};
+export type DbDisposeCapability = {
+    [VOYANT_DB_DISPOSE]?: () => Promise<void>;
+};
+export declare function dbSupportsTransactions(db: unknown): boolean | undefined;
+export declare function dbClientDispose(db: unknown): (() => Promise<void>) | undefined;
+//# sourceMappingURL=transaction-capability.d.ts.map

package/dist/transaction-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-capability.d.ts","sourceRoot":"","sources":["../src/transaction-capability.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,eAA+C,CAAA;AAC3F,eAAO,MAAM,iBAAiB,eAAkC,CAAA;AAEhE,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,+BAA+B,CAAC,CAAC,EAAE,OAAO,CAAA;CAC5C,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,CAAC,iBAAiB,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C,CAAA;AAED,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAOvE;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAO9E"}

package/dist/transaction-capability.js

@@ -0,0 +1,17 @@
+export const VOYANT_DB_SUPPORTS_TRANSACTIONS = Symbol.for("voyant.db.supportsTransactions");
+export const VOYANT_DB_DISPOSE = Symbol.for("voyant.db.dispose");
+export function dbSupportsTransactions(db) {
+    if (!db || (typeof db !== "object" && typeof db !== "function")) {
+        return undefined;
+    }
+    const capability = db[VOYANT_DB_SUPPORTS_TRANSACTIONS];
+    return typeof capability === "boolean" ? capability : undefined;
+}
+export function dbClientDispose(db) {
+    if (!db || (typeof db !== "object" && typeof db !== "function")) {
+        return undefined;
+    }
+    const dispose = db[VOYANT_DB_DISPOSE];
+    return typeof dispose === "function" ? dispose : undefined;
+}
+//# sourceMappingURL=transaction-capability.js.map

package/dist/transaction-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-capability.js","sourceRoot":"","sources":["../src/transaction-capability.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,+BAA+B,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAA;AAC3F,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AAUhE,MAAM,UAAU,sBAAsB,CAAC,EAAW;IAChD,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,EAAE,KAAK,UAAU,CAAC,EAAE,CAAC;QAChE,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,UAAU,GAAI,EAA8B,CAAC,+BAA+B,CAAC,CAAA;IACnF,OAAO,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAA;AACjE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,EAAW;IACzC,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,EAAE,KAAK,UAAU,CAAC,EAAE,CAAC;QAChE,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,OAAO,GAAI,EAA0B,CAAC,iBAAiB,CAAC,CAAA;IAC9D,OAAO,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AAC5D,CAAC"}

package/dist/transaction.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Run `callback` inside a database transaction when the driver supports one,
+ * or invoke it directly against the same `db` handle when it doesn't.
+ *
+ * Designed for Voyant services that share code paths between drivers with
+ * different transaction semantics:
+ *
+ * - `postgres-js` (node) and `neon-serverless` (WebSocket): real transactions.
+ *   The driver's `transaction(...)` method is used.
+ * - `neon-http` (edge): the HTTP driver tagged with
+ *   `VOYANT_DB_SUPPORTS_TRANSACTIONS = false` by `createDbClient`. The
+ *   callback runs directly against `db`. Writes execute as independent
+ *   statements — atomicity is lost on this driver. Callers that need true
+ *   atomicity must select a transaction-capable adapter at startup.
+ *
+ * Nested calls are detected via a `WeakSet`: when invoked with a `tx` handle
+ * that the helper already opened, the callback runs in-place against that
+ * same handle (no second `BEGIN`).
+ *
+ * As a defense-in-depth, if a driver's `transaction()` throws with
+ * "No transactions support …" *before* the callback executes (i.e. the
+ * capability tag is missing on an HTTP-like driver), the helper retries by
+ * invoking the callback directly. Errors raised *after* the callback starts
+ * are not retried — they propagate.
+ */
+export declare function withOptionalTransaction<TDb, T>(db: TDb, callback: (tx: TDb) => Promise<T>): Promise<T>;
+/** @internal — exposed for tests so they can assert WeakSet behavior */
+export declare const __test__: {
+    activeTransactionDbs: WeakSet<object>;
+};
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,CAAC,EAClD,EAAE,EAAE,GAAG,EACP,QAAQ,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC,CAqCZ;AAED,wEAAwE;AACxE,eAAO,MAAM,QAAQ;;CAEpB,CAAA"}

package/dist/transaction.js

@@ -0,0 +1,72 @@
+import { dbSupportsTransactions } from "./transaction-capability.js";
+const activeTransactionDbs = new WeakSet();
+function isUnsupportedTransactionError(error) {
+    return error instanceof Error && /No transactions support/i.test(error.message);
+}
+/**
+ * Run `callback` inside a database transaction when the driver supports one,
+ * or invoke it directly against the same `db` handle when it doesn't.
+ *
+ * Designed for Voyant services that share code paths between drivers with
+ * different transaction semantics:
+ *
+ * - `postgres-js` (node) and `neon-serverless` (WebSocket): real transactions.
+ *   The driver's `transaction(...)` method is used.
+ * - `neon-http` (edge): the HTTP driver tagged with
+ *   `VOYANT_DB_SUPPORTS_TRANSACTIONS = false` by `createDbClient`. The
+ *   callback runs directly against `db`. Writes execute as independent
+ *   statements — atomicity is lost on this driver. Callers that need true
+ *   atomicity must select a transaction-capable adapter at startup.
+ *
+ * Nested calls are detected via a `WeakSet`: when invoked with a `tx` handle
+ * that the helper already opened, the callback runs in-place against that
+ * same handle (no second `BEGIN`).
+ *
+ * As a defense-in-depth, if a driver's `transaction()` throws with
+ * "No transactions support …" *before* the callback executes (i.e. the
+ * capability tag is missing on an HTTP-like driver), the helper retries by
+ * invoking the callback directly. Errors raised *after* the callback starts
+ * are not retried — they propagate.
+ */
+export async function withOptionalTransaction(db, callback) {
+    if (db && typeof db === "object" && activeTransactionDbs.has(db)) {
+        return callback(db);
+    }
+    if (dbSupportsTransactions(db) === false) {
+        return callback(db);
+    }
+    const maybeTransactional = db;
+    if (typeof maybeTransactional.transaction !== "function") {
+        return callback(db);
+    }
+    let callbackStarted = false;
+    try {
+        return await maybeTransactional.transaction(async (tx) => {
+            callbackStarted = true;
+            const txKey = tx;
+            const trackable = txKey && typeof txKey === "object";
+            if (trackable) {
+                activeTransactionDbs.add(txKey);
+            }
+            try {
+                return await callback(tx);
+            }
+            finally {
+                if (trackable) {
+                    activeTransactionDbs.delete(txKey);
+                }
+            }
+        });
+    }
+    catch (error) {
+        if (!callbackStarted && isUnsupportedTransactionError(error)) {
+            return callback(db);
+        }
+        throw error;
+    }
+}
+/** @internal — exposed for tests so they can assert WeakSet behavior */
+export const __test__ = {
+    activeTransactionDbs,
+};
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAEpE,MAAM,oBAAoB,GAAG,IAAI,OAAO,EAAU,CAAA;AAElD,SAAS,6BAA6B,CAAC,KAAc;IACnD,OAAO,KAAK,YAAY,KAAK,IAAI,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;AACjF,CAAC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,EAAO,EACP,QAAiC;IAEjC,IAAI,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,oBAAoB,CAAC,GAAG,CAAC,EAAY,CAAC,EAAE,CAAC;QAC3E,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAA;IACrB,CAAC;IAED,IAAI,sBAAsB,CAAC,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC;QACzC,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAA;IACrB,CAAC;IAED,MAAM,kBAAkB,GAAG,EAA+B,CAAA;IAC1D,IAAI,OAAO,kBAAkB,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QACzD,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAA;IACrB,CAAC;IAED,IAAI,eAAe,GAAG,KAAK,CAAA;IAC3B,IAAI,CAAC;QACH,OAAO,MAAM,kBAAkB,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YACvD,eAAe,GAAG,IAAI,CAAA;YACtB,MAAM,KAAK,GAAG,EAAa,CAAA;YAC3B,MAAM,SAAS,GAAG,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAA;YACpD,IAAI,SAAS,EAAE,CAAC;gBACd,oBAAoB,CAAC,GAAG,CAAC,KAAe,CAAC,CAAA;YAC3C,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,QAAQ,CAAC,EAAE,CAAC,CAAA;YAC3B,CAAC;oBAAS,CAAC;gBACT,IAAI,SAAS,EAAE,CAAC;oBACd,oBAAoB,CAAC,MAAM,CAAC,KAAe,CAAC,CAAA;gBAC9C,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,eAAe,IAAI,6BAA6B,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7D,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAA;QACrB,CAAC;QACD,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,oBAAoB;CACrB,CAAA"}