@byline/db-postgres 3.8.0 → 3.10.0

package/dist/database/schema/index.d.ts

@@ -3312,4 +3312,187 @@ export declare const jsonStoreRelations: import("drizzle-orm").Relations<"byline
     document: import("drizzle-orm").One<"byline_document_versions", true>;
     collection: import("drizzle-orm").One<"byline_collections", true>;
 }>;
+export declare const auditLog: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "byline_audit_log";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        document_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "document_id";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        collection_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "collection_id";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        actor_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor_id";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        actor_realm: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor_realm";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 16;
+        }>;
+        action: import("drizzle-orm/pg-core").PgColumn<{
+            name: "action";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 64;
+        }>;
+        field: import("drizzle-orm/pg-core").PgColumn<{
+            name: "field";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 128;
+        }>;
+        before: import("drizzle-orm/pg-core").PgColumn<{
+            name: "before";
+            tableName: "byline_audit_log";
+            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;
+        }, {}, {}>;
+        after: import("drizzle-orm/pg-core").PgColumn<{
+            name: "after";
+            tableName: "byline_audit_log";
+            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;
+        }, {}, {}>;
+        occurred_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: "occurred_at";
+            tableName: "byline_audit_log";
+            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;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 export { adminPermissions, adminPermissionsRelations, adminRefreshTokens, adminRefreshTokensRelations, adminRoleAdminUser, adminRoleAdminUserRelations, adminRoles, adminRolesRelations, adminUsers, adminUsersRelations, } from './auth.js';

package/dist/database/schema/index.js

@@ -632,6 +632,39 @@ export const jsonStoreRelations = relations(jsonStore, ({ one }) => ({
     }),
 }));
 // ---------------------------------------------------------------------------
+// Audit log — byline_audit_log
+// ---------------------------------------------------------------------------
+// Document-grain audit log. Records the changes the immutable version stream
+// does NOT capture an actor for: non-versioned system-field writes (path,
+// availableLocales), in-place status transitions, and deletions — plus, later,
+// admin-module events. One generic table (nullable `document_id`, namespaced
+// `action`) so the system-wide activity report and future admin-realm auditing
+// fit without a second migration. Append-only and deliberately **FK-free**: an
+// audit row is an immutable historical fact that must outlive the document,
+// collection, or actor it references — a `document.deleted` row cannot be
+// allowed to cascade-delete itself. See docs/AUDIT.md — Workstream 2.
+export const auditLog = pgTable('byline_audit_log', {
+    id: uuid('id').primaryKey(), // UUIDv7 — time-ordered, so id ordering ≈ time ordering
+    document_id: uuid('document_id'), // NULL for admin-realm (non-document) events; no FK
+    collection_id: uuid('collection_id'), // no FK — outlives the collection
+    actor_id: uuid('actor_id'), // NULL = system / internal tooling / non-UUID synthetic actor
+    actor_realm: varchar('actor_realm', { length: 16 }).notNull(), // 'admin' | 'user' | 'system'
+    action: varchar('action', { length: 64 }).notNull(), // namespaced, e.g. 'document.path.changed'
+    field: varchar('field', { length: 128 }), // the changed field where meaningful (e.g. 'path'), else NULL
+    before: jsonb('before'),
+    after: jsonb('after'),
+    occurred_at: timestamp('occurred_at', { precision: 6, withTimezone: true })
+        .notNull()
+        .defaultNow(),
+}, (table) => [
+    // Per-document history, time-ordered (id is UUIDv7).
+    index('idx_audit_log_document_id').on(table.document_id, table.id),
+    // Per-actor activity — the system-wide report's actor filter.
+    index('idx_audit_log_actor_id').on(table.actor_id, table.id),
+    // Action-type filter for the activity report.
+    index('idx_audit_log_action').on(table.action, table.id),
+]);
+// ---------------------------------------------------------------------------
 // Auth schema — byline_admin_users, byline_admin_roles, etc.
 // See ./auth.ts for definitions and rationale.
 // ---------------------------------------------------------------------------

package/dist/index.js

@@ -8,6 +8,9 @@
 import { drizzle } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './database/schema/index.js';
+import { DBManagerImpl, TXManagerImpl } from './lib/db-manager.js';
+import { createAuditCommands } from './modules/audit/audit-commands.js';
+import { createAuditQueries } from './modules/audit/audit-queries.js';
 import { createCounterCommands } from './modules/counters/counters-commands.js';
 import { createCommandBuilders, } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
@@ -19,15 +22,31 @@ export const pgAdapter = ({ connectionString, collections, defaultContentLocale,
         connectionTimeoutMillis,
     });
     const db = drizzle(pool, { schema });
-    const commandBuilders = createCommandBuilders(db, defaultContentLocale);
+    // Request-scoped transaction propagation (docs/TRANSACTIONS.md). The command
+    // builders run on the DBManager — each `this.db` access resolves to the
+    // ambient transaction when a `withTransaction` boundary is open, else the
+    // pool. Queries and counters stay on the raw `db` for now (reads don't need
+    // to join the audit transaction); they migrate opportunistically.
+    const dbManager = new DBManagerImpl({ dbPool: db });
+    const txManager = new TXManagerImpl({ db: dbManager });
+    const commandBuilders = createCommandBuilders(dbManager, defaultContentLocale);
     const queryBuilders = createQueryBuilders(db, collections, defaultContentLocale);
     const counterCommands = createCounterCommands(db);
+    // Audit writes run on the DBManager so they join an ambient `withTransaction`
+    // (atomic with the mutation they record); audit reads run on the pool.
+    const auditCommands = createAuditCommands(dbManager);
+    const auditQueries = createAuditQueries(db);
     return {
         commands: {
             ...commandBuilders,
             counters: counterCommands,
+            audit: auditCommands,
         },
-        queries: queryBuilders,
+        queries: {
+            ...queryBuilders,
+            audit: auditQueries,
+        },
+        withTransaction: (fn) => txManager.withTransaction(fn),
         drizzle: db,
         pool,
         backfillVersionLocales: () => commandBuilders.documents.backfillVersionLocales(),

package/dist/lib/db-manager.d.ts

@@ -0,0 +1,61 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Request-scoped transaction propagation via AsyncLocalStorage.
+ *
+ * Ported from the Modulus project (`db-manager.ts`) — the same ALS mechanism
+ * Byline's logger already uses (`packages/core/src/lib/logger.ts`,
+ * `withLogContext`). The full design — the service-owned `withTransaction`
+ * boundary, the DB↔DB vs DB↔external distinction, the incremental-adoption
+ * caveat, and the serverless db-contract-seam decisions — lives in
+ * `docs/TRANSACTIONS.md`. This machinery is deliberately adapter-internal:
+ * transactions are driver-specific, so `@byline/core` only declares the
+ * `withTransaction` capability on `IDbAdapter`, never the implementation.
+ */
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../database/schema/index.js';
+/**
+ * The executor every storage command runs on: either the connection pool
+ * (autonomous, statement-at-a-time) or — when a `withTransaction` boundary is
+ * open in the current async context — that transaction. Commands obtain it via
+ * `DBManager.get()` and never thread a transaction handle through their
+ * signatures.
+ */
+export type DBExecutor = NodePgDatabase<typeof schema>;
+export interface DBManager {
+    /**
+     * The current executor: the ambient transaction when a `withTransaction`
+     * boundary is open in this async context, otherwise the pool.
+     */
+    get(): DBExecutor;
+}
+export declare class DBManagerImpl implements DBManager {
+    private readonly dbPool;
+    constructor(deps: {
+        dbPool: DBExecutor;
+    });
+    get(): DBExecutor;
+}
+export interface TXManager {
+    /**
+     * Run `fn` inside a single database transaction. Every `DBManager.get()`
+     * call made during `fn` (transitively, across `await`s) returns that
+     * transaction, so the commands `fn` invokes commit or roll back together.
+     *
+     * Nesting: when already inside a `withTransaction`, the inner call opens a
+     * SAVEPOINT (Drizzle nested transaction) — an inner throw rolls back to the
+     * savepoint, an outer throw rolls back everything.
+     */
+    withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+export declare class TXManagerImpl implements TXManager {
+    private readonly db;
+    constructor(deps: {
+        db: DBManager;
+    });
+    withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+}

package/dist/lib/db-manager.js

@@ -0,0 +1,43 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Request-scoped transaction propagation via AsyncLocalStorage.
+ *
+ * Ported from the Modulus project (`db-manager.ts`) — the same ALS mechanism
+ * Byline's logger already uses (`packages/core/src/lib/logger.ts`,
+ * `withLogContext`). The full design — the service-owned `withTransaction`
+ * boundary, the DB↔DB vs DB↔external distinction, the incremental-adoption
+ * caveat, and the serverless db-contract-seam decisions — lives in
+ * `docs/TRANSACTIONS.md`. This machinery is deliberately adapter-internal:
+ * transactions are driver-specific, so `@byline/core` only declares the
+ * `withTransaction` capability on `IDbAdapter`, never the implementation.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const transactionALS = new AsyncLocalStorage();
+export class DBManagerImpl {
+    dbPool;
+    constructor(deps) {
+        this.dbPool = deps.dbPool;
+    }
+    get() {
+        return transactionALS.getStore() ?? this.dbPool;
+    }
+}
+export class TXManagerImpl {
+    db;
+    constructor(deps) {
+        this.db = deps.db;
+    }
+    withTransaction(fn) {
+        return this.db.get().transaction((tx) => 
+        // `tx` is Drizzle's PgTransaction; it carries the full query-builder
+        // surface every command uses. The cast bridges the one structural gap
+        // to NodePgDatabase — the transaction lacks `$client`, which no command
+        // touches. See docs/TRANSACTIONS.md.
+        transactionALS.run(tx, fn));
+    }
+}

package/dist/lib/test-helper.d.ts

@@ -1,9 +1,12 @@
 import type { CollectionDefinition } from '@byline/core';
 import { type NodePgDatabase } from 'drizzle-orm/node-postgres';
 import * as schema from '../database/schema/index.js';
+import { DBManagerImpl, TXManagerImpl } from './db-manager.js';
 export declare function setupTestDB(collections?: CollectionDefinition[]): {
     pool: import("pg").Pool;
     db: NodePgDatabase<typeof schema>;
+    dbManager: DBManagerImpl;
+    txManager: TXManagerImpl;
     commandBuilders: {
         collections: import("../modules/storage/storage-commands.js").CollectionCommands;
         documents: import("../modules/storage/storage-commands.js").DocumentCommands;

package/dist/lib/test-helper.js

@@ -3,9 +3,12 @@ import pg from 'pg';
 import * as schema from '../database/schema/index.js';
 import { createCommandBuilders } from '../modules/storage/storage-commands.js';
 import { createQueryBuilders } from '../modules/storage/storage-queries.js';
+import { DBManagerImpl, TXManagerImpl } from './db-manager.js';
 import { assertTestDatabase } from './test-db.js';
 let pool;
 let db;
+let dbManager;
+let txManager;
 let commandBuilders;
 let queryBuilders;
 export function setupTestDB(collections = []) {
@@ -26,19 +29,25 @@ export function setupTestDB(collections = []) {
     if (!db) {
         db = drizzle(pool, { schema });
     }
+    if (!dbManager) {
+        dbManager = new DBManagerImpl({ dbPool: db });
+        txManager = new TXManagerImpl({ db: dbManager });
+    }
     if (!commandBuilders) {
-        commandBuilders = createCommandBuilders(db, 'en');
+        commandBuilders = createCommandBuilders(dbManager, 'en');
     }
     // Recreate queryBuilders when collections are provided so that
     // DocumentQueries can resolve collection definitions by path.
     queryBuilders = createQueryBuilders(db, collections, 'en');
-    return { pool, db, commandBuilders, queryBuilders };
+    return { pool, db, dbManager, txManager, commandBuilders, queryBuilders };
 }
 export async function teardownTestDB() {
     if (pool) {
         await pool.end();
         pool = undefined;
         db = undefined;
+        dbManager = undefined;
+        txManager = undefined;
         commandBuilders = undefined;
         queryBuilders = undefined;
     }

package/dist/modules/audit/audit-commands.d.ts

@@ -0,0 +1,27 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Append-only audit-log writes (docs/AUDIT.md — Workstream 2). A deliberately
+ * dumb command: it inserts one row and knows nothing about *which* changes
+ * warrant an audit entry — that policy lives in the lifecycle services, which
+ * wrap the mutation + this append in `withTransaction` so they commit
+ * atomically. Runs on the `DBManager` executor, so an `append` issued inside a
+ * `withTransaction` boundary joins the ambient transaction.
+ */
+import type { AuditLogAppendInput, IAuditCommands } from '@byline/core';
+import type { DBManager } from '../../lib/db-manager.js';
+export declare class AuditCommands implements IAuditCommands {
+    private dbManager;
+    constructor(dbManager: DBManager);
+    /** Ambient transaction when a `withTransaction` boundary is open, else the pool. */
+    private get db();
+    append(input: AuditLogAppendInput): Promise<{
+        id: string;
+    }>;
+}
+export declare function createAuditCommands(dbManager: DBManager): AuditCommands;

package/dist/modules/audit/audit-commands.js

@@ -0,0 +1,40 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { v7 as uuidv7 } from 'uuid';
+import { auditLog } from '../../database/schema/index.js';
+export class AuditCommands {
+    dbManager;
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    /** Ambient transaction when a `withTransaction` boundary is open, else the pool. */
+    get db() {
+        return this.dbManager.get();
+    }
+    async append(input) {
+        const id = uuidv7(); // time-ordered, so id ordering ≈ occurred_at ordering
+        await this.db.insert(auditLog).values({
+            id,
+            document_id: input.documentId ?? null,
+            collection_id: input.collectionId ?? null,
+            actor_id: input.actorId ?? null,
+            actor_realm: input.actorRealm,
+            action: input.action,
+            field: input.field ?? null,
+            // `?? null` only coerces undefined → SQL NULL; a real `false`/`0`/`''`
+            // before/after value is preserved.
+            before: input.before ?? null,
+            after: input.after ?? null,
+            // occurred_at defaults to now() at the DB.
+        });
+        return { id };
+    }
+}
+export function createAuditCommands(dbManager) {
+    return new AuditCommands(dbManager);
+}

package/dist/modules/audit/audit-queries.d.ts

@@ -0,0 +1,29 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Audit-log reads (docs/AUDIT.md — Workstreams 3 & 4). Reads run on the pool
+ * directly — they never need to join an audit write's transaction — so this
+ * takes the raw connection rather than the `DBManager`. Access scoping is the
+ * caller's responsibility (the document's own read gate); these queries do no
+ * scoping of their own.
+ */
+import type { AuditLogPage, IAuditQueries } from '@byline/core';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../database/schema/index.js';
+type DatabaseConnection = NodePgDatabase<typeof schema>;
+export declare class AuditQueries implements IAuditQueries {
+    private db;
+    constructor(db: DatabaseConnection);
+    getDocumentAuditLog(params: {
+        document_id: string;
+        page?: number;
+        page_size?: number;
+    }): Promise<AuditLogPage>;
+}
+export declare function createAuditQueries(db: DatabaseConnection): AuditQueries;
+export {};

package/dist/modules/audit/audit-queries.js

@@ -0,0 +1,55 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { desc, eq, sql } from 'drizzle-orm';
+import { auditLog } from '../../database/schema/index.js';
+function toEntry(row) {
+    return {
+        id: row.id,
+        documentId: row.document_id,
+        collectionId: row.collection_id,
+        actorId: row.actor_id,
+        actorRealm: row.actor_realm,
+        action: row.action,
+        field: row.field,
+        before: row.before,
+        after: row.after,
+        occurredAt: row.occurred_at,
+    };
+}
+export class AuditQueries {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getDocumentAuditLog(params) {
+        const page = params.page ?? 1;
+        const pageSize = params.page_size ?? 20;
+        const offset = (page - 1) * pageSize;
+        const totalResult = await this.db
+            .select({ count: sql `count(*)` })
+            .from(auditLog)
+            .where(eq(auditLog.document_id, params.document_id));
+        const total = Number(totalResult[0]?.count) || 0;
+        const totalPages = Math.ceil(total / pageSize);
+        const rows = await this.db
+            .select()
+            .from(auditLog)
+            .where(eq(auditLog.document_id, params.document_id))
+            // id is UUIDv7 — DESC is newest-first without a separate sort column.
+            .orderBy(desc(auditLog.id))
+            .limit(pageSize)
+            .offset(offset);
+        return {
+            entries: rows.map(toEntry),
+            meta: { total, page, pageSize, totalPages },
+        };
+    }
+}
+export function createAuditQueries(db) {
+    return new AuditQueries(db);
+}

package/dist/modules/audit/tests/audit-log.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/modules/audit/tests/audit-log.test.js

@@ -0,0 +1,117 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Integration tests for the audit-log storage layer (docs/AUDIT.md — W2):
+ * `audit.append` (write) + `audit.getDocumentAuditLog` (read), and the
+ * load-bearing property that an `append` issued inside `withTransaction`
+ * commits or rolls back **with** the transaction it is part of.
+ */
+import { v7 as uuidv7 } from 'uuid';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+import { createAuditCommands } from '../audit-commands.js';
+import { createAuditQueries } from '../audit-queries.js';
+let auditCommands;
+let auditQueries;
+let txManager;
+describe('audit-log storage', () => {
+    beforeAll(() => {
+        const testDB = setupTestDB([]);
+        txManager = testDB.txManager;
+        auditCommands = createAuditCommands(testDB.dbManager);
+        auditQueries = createAuditQueries(testDB.db);
+    });
+    afterAll(async () => {
+        await teardownTestDB();
+    });
+    it('appends an entry and reads it back with full field fidelity', async () => {
+        const documentId = uuidv7();
+        const collectionId = uuidv7();
+        const actorId = uuidv7();
+        await auditCommands.append({
+            documentId,
+            collectionId,
+            actorId,
+            actorRealm: 'admin',
+            action: 'document.path.changed',
+            field: 'path',
+            before: 'old-slug',
+            after: 'new-slug',
+        });
+        const page = await auditQueries.getDocumentAuditLog({ document_id: documentId });
+        expect(page.meta.total).toBe(1);
+        const entry = page.entries[0];
+        expect(entry.documentId).toBe(documentId);
+        expect(entry.collectionId).toBe(collectionId);
+        expect(entry.actorId).toBe(actorId);
+        expect(entry.actorRealm).toBe('admin');
+        expect(entry.action).toBe('document.path.changed');
+        expect(entry.field).toBe('path');
+        expect(entry.before).toBe('old-slug');
+        expect(entry.after).toBe('new-slug');
+        expect(entry.occurredAt).toBeInstanceOf(Date);
+    });
+    it('persists NULL actor + structured before/after, and returns newest-first', async () => {
+        const documentId = uuidv7();
+        // A system write (no actor) with object-shaped before/after.
+        await auditCommands.append({
+            documentId,
+            actorId: null,
+            actorRealm: 'system',
+            action: 'document.locales.changed',
+            field: 'availableLocales',
+            before: ['en'],
+            after: ['en', 'fr'],
+        });
+        await auditCommands.append({
+            documentId,
+            actorRealm: 'admin',
+            action: 'document.status.changed',
+            field: 'status',
+            before: 'draft',
+            after: 'published',
+        });
+        const page = await auditQueries.getDocumentAuditLog({ document_id: documentId });
+        expect(page.meta.total).toBe(2);
+        // UUIDv7 ids → newest first: the status change was appended last.
+        expect(page.entries[0]?.action).toBe('document.status.changed');
+        expect(page.entries[1]?.action).toBe('document.locales.changed');
+        const localesEntry = page.entries[1];
+        expect(localesEntry.actorId).toBeNull();
+        expect(localesEntry.before).toEqual(['en']);
+        expect(localesEntry.after).toEqual(['en', 'fr']);
+    });
+    it('rolls back the audit row when its enclosing transaction throws', async () => {
+        const documentId = uuidv7();
+        await expect(txManager.withTransaction(async () => {
+            await auditCommands.append({
+                documentId,
+                actorRealm: 'admin',
+                action: 'document.deleted',
+            });
+            // The unit of work fails after the audit append. If the append had run
+            // on the pool rather than the ambient tx, the row would survive.
+            throw new Error('boom');
+        })).rejects.toThrow('boom');
+        const page = await auditQueries.getDocumentAuditLog({ document_id: documentId });
+        expect(page.meta.total).toBe(0);
+    });
+    it('commits the audit row with its enclosing transaction', async () => {
+        const documentId = uuidv7();
+        await txManager.withTransaction(async () => {
+            await auditCommands.append({
+                documentId,
+                actorRealm: 'admin',
+                action: 'document.deleted',
+            });
+        });
+        const page = await auditQueries.getDocumentAuditLog({ document_id: documentId });
+        expect(page.meta.total).toBe(1);
+        expect(page.entries[0]?.action).toBe('document.deleted');
+    });
+});

package/dist/modules/storage/storage-commands.d.ts

@@ -6,9 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { CollectionDefinition, ICollectionCommands, IDocumentCommands } from '@byline/core';
-import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
-import type * as schema from '../../database/schema/index.js';
-type DatabaseConnection = NodePgDatabase<typeof schema>;
+import type { DBManager } from '../../lib/db-manager.js';
 /** Outcome of re-anchoring a single document's content source locale. */
 export type ReAnchorStatus = 'reanchored' | 'skipped-incomplete' | 'already-anchored' | 'not-found';
 export interface ReAnchorResult {
@@ -36,8 +34,15 @@ export interface ReAnchorReport {
  * CollectionCommands
  */
 export declare class CollectionCommands implements ICollectionCommands {
-    private db;
-    constructor(db: DatabaseConnection);
+    private dbManager;
+    constructor(dbManager: DBManager);
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     */
+    private get db();
     create(path: string, config: CollectionDefinition, opts?: {
         version?: number;
         schemaHash?: string;
@@ -73,9 +78,16 @@ export declare class CollectionCommands implements ICollectionCommands {
  * DocumentCommands
  */
 export declare class DocumentCommands implements IDocumentCommands {
-    private db;
+    private dbManager;
     private defaultContentLocale;
-    constructor(db: DatabaseConnection, defaultContentLocale: string);
+    constructor(dbManager: DBManager, defaultContentLocale: string);
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     */
+    private get db();
     /**
      * createDocumentVersion
      *
@@ -379,8 +391,7 @@ export declare class DocumentCommands implements IDocumentCommands {
         order_key: string;
     }): Promise<void>;
 }
-export declare function createCommandBuilders(db: DatabaseConnection, defaultContentLocale: string): {
+export declare function createCommandBuilders(dbManager: DBManager, defaultContentLocale: string): {
     collections: CollectionCommands;
     documents: DocumentCommands;
 };
-export {};

package/dist/modules/storage/storage-commands.js

@@ -15,9 +15,18 @@ import { getFirstOrThrow } from './storage-utils.js';
  * CollectionCommands
  */
 export class CollectionCommands {
-    db;
-    constructor(db) {
-        this.db = db;
+    dbManager;
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     */
+    get db() {
+        return this.dbManager.get();
     }
     async create(path, config, opts) {
         return await this.db
@@ -51,12 +60,21 @@ export class CollectionCommands {
  * DocumentCommands
  */
 export class DocumentCommands {
-    db;
+    dbManager;
     defaultContentLocale;
-    constructor(db, defaultContentLocale) {
-        this.db = db;
+    constructor(dbManager, defaultContentLocale) {
+        this.dbManager = dbManager;
         this.defaultContentLocale = defaultContentLocale;
     }
+    /**
+     * The executor for this call — the ambient transaction when a
+     * `withTransaction` boundary is open, otherwise the pool. Resolved per
+     * access so every `this.db.*` below transparently joins an enclosing
+     * transaction with no call-site change. See docs/TRANSACTIONS.md.
+     */
+    get db() {
+        return this.dbManager.get();
+    }
     /**
      * createDocumentVersion
      *
@@ -836,9 +854,9 @@ export class DocumentCommands {
             .where(eq(documents.id, params.document_id));
     }
 }
-export function createCommandBuilders(db, defaultContentLocale) {
+export function createCommandBuilders(dbManager, defaultContentLocale) {
     return {
-        collections: new CollectionCommands(db),
-        documents: new DocumentCommands(db, defaultContentLocale),
+        collections: new CollectionCommands(dbManager),
+        documents: new DocumentCommands(dbManager, defaultContentLocale),
     };
 }

package/dist/modules/storage/tests/storage-transactions.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/modules/storage/tests/storage-transactions.test.js

@@ -0,0 +1,108 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Integration tests for request-scoped transaction propagation
+ * (`withTransaction` / DBManager / TXManager — see docs/TRANSACTIONS.md).
+ *
+ * Proves the load-bearing guarantee the audit log depends on: multiple
+ * `commands.*` calls wrapped in one `withTransaction` commit or roll back
+ * **together**, with no transaction handle threaded through their signatures.
+ * The commands join the ambient transaction purely via the AsyncLocalStorage
+ * propagation in DBManager.get().
+ */
+import { eq } from 'drizzle-orm';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { collections } from '../../../database/schema/index.js';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+let db;
+let dbManager;
+let txManager;
+let commandBuilders;
+const ts = Date.now();
+const createdPaths = [];
+async function collectionExists(path) {
+    const rows = await db
+        .select({ id: collections.id })
+        .from(collections)
+        .where(eq(collections.path, path));
+    return rows.length > 0;
+}
+describe('withTransaction propagation + atomicity', () => {
+    beforeAll(() => {
+        const testDB = setupTestDB([]);
+        db = testDB.db;
+        dbManager = testDB.dbManager;
+        txManager = testDB.txManager;
+        commandBuilders = testDB.commandBuilders;
+    });
+    afterAll(async () => {
+        for (const path of createdPaths) {
+            try {
+                const rows = await db
+                    .select({ id: collections.id })
+                    .from(collections)
+                    .where(eq(collections.path, path));
+                if (rows[0])
+                    await commandBuilders.collections.delete(rows[0].id);
+            }
+            catch (error) {
+                console.error('cleanup failed for', path, error);
+            }
+        }
+        await teardownTestDB();
+    });
+    it('get() returns the pool outside a transaction and the tx inside it', async () => {
+        // Outside any boundary, the executor is the pool itself.
+        expect(dbManager.get()).toBe(db);
+        let insideExecutor;
+        await txManager.withTransaction(async () => {
+            insideExecutor = dbManager.get();
+        });
+        // Inside the boundary it is the ambient transaction — a different handle.
+        expect(insideExecutor).not.toBe(db);
+    });
+    it('commits every command in the boundary together', async () => {
+        const a = `tx-commit-a-${ts}`;
+        const b = `tx-commit-b-${ts}`;
+        createdPaths.push(a, b);
+        await txManager.withTransaction(async () => {
+            await commandBuilders.collections.create(a, {
+                path: a,
+                labels: { singular: 'A', plural: 'As' },
+                fields: [{ name: 'title', type: 'text' }],
+            });
+            await commandBuilders.collections.create(b, {
+                path: b,
+                labels: { singular: 'B', plural: 'Bs' },
+                fields: [{ name: 'title', type: 'text' }],
+            });
+        });
+        expect(await collectionExists(a)).toBe(true);
+        expect(await collectionExists(b)).toBe(true);
+    });
+    it('rolls back every command in the boundary when it throws', async () => {
+        const a = `tx-rollback-a-${ts}`;
+        const b = `tx-rollback-b-${ts}`;
+        const boom = new Error('boom');
+        await expect(txManager.withTransaction(async () => {
+            // First write succeeds...
+            await commandBuilders.collections.create(a, {
+                path: a,
+                labels: { singular: 'A', plural: 'As' },
+                fields: [{ name: 'title', type: 'text' }],
+            });
+            // ...then the unit of work fails after it. If the first write ran on
+            // the pool rather than the ambient tx, it would survive this throw.
+            throw boom;
+        })).rejects.toThrow('boom');
+        // Atomicity: the successful-looking first write was rolled back with the
+        // failing transaction. Neither collection exists.
+        expect(await collectionExists(a)).toBe(false);
+        expect(await collectionExists(b)).toBe(false);
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -57,9 +57,9 @@
     "pg": "^8.21.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/admin": "3.8.0",
-    "@byline/auth": "3.8.0",
-    "@byline/core": "3.8.0"
+    "@byline/auth": "3.10.0",
+    "@byline/admin": "3.10.0",
+    "@byline/core": "3.10.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",