@byline/core 3.8.0 → 3.10.0

package/dist/@types/db-types.d.ts

@@ -203,11 +203,39 @@ export interface IDbAdapter {
         collections: ICollectionCommands;
         documents: IDocumentCommands;
         counters: ICounterCommands;
+        /**
+         * Append-only audit-log writes (docs/AUDIT.md — Workstream 2). Optional
+         * capability, paired with `withTransaction`: a consumer that records audit
+         * entries asserts both are present and throws otherwise (it must never
+         * silently skip the audit row). Adapters that model the audit log
+         * implement it; others omit it.
+         */
+        audit?: IAuditCommands;
     };
     queries: {
         collections: ICollectionQueries;
         documents: IDocumentQueries;
+        /** Audit-log reads — per-document history, system-wide report. See docs/AUDIT.md. */
+        audit?: IAuditQueries;
     };
+    /**
+     * Optional capability: run `fn` inside a single database transaction so the
+     * writes it performs commit or roll back atomically. The adapter propagates
+     * the transaction to every `commands.*` call made within `fn` (see
+     * docs/TRANSACTIONS.md — AsyncLocalStorage propagation), so a service can
+     * compose multiple commands into one unit of work without threading a
+     * transaction handle through their signatures.
+     *
+     * **Loud-failure contract.** Optional because not every adapter can provide
+     * interactive transactions — a pure HTTP-gateway serverless driver (Neon
+     * HTTP, Cloudflare D1, …) cannot. An adapter that cannot **must omit this
+     * method** (or implement it to throw); a consumer that requires atomicity
+     * (e.g. the audit log) MUST assert its presence and throw — never silently
+     * run non-atomically, which would defeat the very guarantee it provides. See
+     * docs/TRANSACTIONS.md ("Serverless / HTTP-gateway databases — the contract
+     * seam").
+     */
+    withTransaction?: <T>(fn: () => Promise<T>) => Promise<T>;
     /**
      * Optional maintenance: stamp `source_locale` (the per-document content
      * anchor) on documents created before the column existed, setting NULL rows
@@ -221,6 +249,81 @@ export interface IDbAdapter {
         rowsUpdated: number;
     }>;
 }
+/**
+ * The realm of the actor that performed an audited change. `'admin'` for
+ * admin-user actions, `'user'` reserved for the end-user realm, `'system'`
+ * for deliberate internal-tooling writes. See docs/AUDIT.md.
+ */
+export type AuditActorRealm = 'admin' | 'user' | 'system';
+/** Input to `IAuditCommands.append` — one audit-log row. */
+export interface AuditLogAppendInput {
+    /** The document the change concerns; NULL for admin-realm (non-document) events. */
+    documentId?: string | null;
+    collectionId?: string | null;
+    /** The acting user id, only when it is a real persisted user (a UUID); NULL otherwise. */
+    actorId?: string | null;
+    actorRealm: AuditActorRealm;
+    /** Namespaced action, e.g. `document.path.changed`. */
+    action: string;
+    /** The changed field where meaningful (e.g. `path`); NULL for whole-entity events. */
+    field?: string | null;
+    /** Prior value (JSON-serialisable); NULL where not applicable. */
+    before?: unknown;
+    /** New value (JSON-serialisable); NULL where not applicable. */
+    after?: unknown;
+}
+/** A materialised audit-log row. */
+export interface AuditLogEntry {
+    id: string;
+    documentId: string | null;
+    collectionId: string | null;
+    actorId: string | null;
+    actorRealm: string;
+    action: string;
+    field: string | null;
+    before: unknown;
+    after: unknown;
+    occurredAt: Date;
+}
+/** A page of audit-log entries with pagination metadata. */
+export interface AuditLogPage {
+    entries: AuditLogEntry[];
+    meta: {
+        total: number;
+        page: number;
+        pageSize: number;
+        totalPages: number;
+    };
+}
+/**
+ * Append-only audit-log writes. The companion read interface is
+ * `IAuditQueries`. See docs/AUDIT.md — Workstream 2.
+ */
+export interface IAuditCommands {
+    /**
+     * Append one immutable audit-log row. The adapter generates the row id
+     * (UUIDv7) and `occurred_at`. Runs on the ambient executor, so when called
+     * inside `withTransaction` it commits atomically with the mutation it
+     * records — the load-bearing guarantee of the audit log.
+     */
+    append(input: AuditLogAppendInput): Promise<{
+        id: string;
+    }>;
+}
+/** Audit-log reads. See docs/AUDIT.md — Workstreams 3 & 4. */
+export interface IAuditQueries {
+    /**
+     * The audit history for one document, newest first, paged. Backs the
+     * document-history view. The caller is responsible for the access gate
+     * (the document's own read pipeline) before reaching this — it does no
+     * scoping of its own.
+     */
+    getDocumentAuditLog(params: {
+        document_id: string;
+        page?: number;
+        page_size?: number;
+    }): Promise<AuditLogPage>;
+}
 /**
  * Adapter capability for the shared-pool counter mechanism backing the
  * `counter` field type. See `packages/core/src/@types/field-types.ts`

package/dist/lib/errors.d.ts

@@ -86,6 +86,7 @@ export declare const ErrorCodes: {
     readonly STORAGE: "ERR_STORAGE";
     readonly READ_BUDGET_EXCEEDED: "ERR_READ_BUDGET_EXCEEDED";
     readonly PATH_CONFLICT: "ERR_PATH_CONFLICT";
+    readonly AUDIT_UNSUPPORTED: "ERR_AUDIT_UNSUPPORTED";
 };
 export declare const ERR_UNHANDLED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_NOT_FOUND: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
@@ -103,3 +104,13 @@ export declare const ERR_READ_BUDGET_EXCEEDED: (opts: BylineErrorOptions, errorC
  * `byline_document_paths(collection_id, locale, path)`.
  */
 export declare const ERR_PATH_CONFLICT: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+/**
+ * Thrown when an audited write (a document-grain change that must be recorded
+ * atomically — path / available-locales / status / delete) runs against a db
+ * adapter that does not provide both the `withTransaction` capability and the
+ * `commands.audit` / `queries.audit` surfaces. A misconfiguration, not a
+ * user error: an auditability guarantee cannot be honoured non-atomically, so
+ * the write is refused loudly rather than recorded with a gap. See
+ * docs/TRANSACTIONS.md and docs/AUDIT.md.
+ */
+export declare const ERR_AUDIT_UNSUPPORTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;

package/dist/lib/errors.js

@@ -119,6 +119,7 @@ export const ErrorCodes = {
     STORAGE: 'ERR_STORAGE',
     READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED',
     PATH_CONFLICT: 'ERR_PATH_CONFLICT',
+    AUDIT_UNSUPPORTED: 'ERR_AUDIT_UNSUPPORTED',
 };
 // ---------------------------------------------------------------------------
 // Pre-instantiated factories
@@ -139,3 +140,13 @@ export const ERR_READ_BUDGET_EXCEEDED = createErrorType(ErrorCodes.READ_BUDGET_E
  * `byline_document_paths(collection_id, locale, path)`.
  */
 export const ERR_PATH_CONFLICT = createErrorType(ErrorCodes.PATH_CONFLICT, 'warn');
+/**
+ * Thrown when an audited write (a document-grain change that must be recorded
+ * atomically — path / available-locales / status / delete) runs against a db
+ * adapter that does not provide both the `withTransaction` capability and the
+ * `commands.audit` / `queries.audit` surfaces. A misconfiguration, not a
+ * user error: an auditability guarantee cannot be honoured non-atomically, so
+ * the write is refused loudly rather than recorded with a gap. See
+ * docs/TRANSACTIONS.md and docs/AUDIT.md.
+ */
+export const ERR_AUDIT_UNSUPPORTED = createErrorType(ErrorCodes.AUDIT_UNSUPPORTED);

package/dist/services/document-lifecycle/audit.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { AuditActorRealm, AuditLogAppendInput, IDbAdapter } from '../../@types/index.js';
+import type { DocumentLifecycleContext } from './context.js';
+/** Namespaced audit actions for document-grain changes. */
+export declare const AUDIT_ACTIONS: {
+    readonly pathChanged: "document.path.changed";
+    readonly localesChanged: "document.locales.changed";
+    readonly statusChanged: "document.status.changed";
+    readonly deleted: "document.deleted";
+};
+/**
+ * The actor id + realm for an audit-log row. Mirrors `actorId()`: a real
+ * persisted user carries a UUID id and is recorded with realm `'admin'`
+ * (these write-points are admin-gated, document-grain operations). A synthetic
+ * script/seed actor (non-UUID) or no actor is a system/tooling write — NULL id,
+ * realm `'system'`. (A future `UserAuth`-driven write-point would extend this
+ * to `'user'`.)
+ */
+export declare function auditActor(ctx: DocumentLifecycleContext): {
+    actorId: string | undefined;
+    actorRealm: AuditActorRealm;
+};
+/** A non-null audit capability resolved from an adapter that supports it. */
+export interface AuditCapability {
+    withTransaction: <T>(fn: () => Promise<T>) => Promise<T>;
+    append: (input: AuditLogAppendInput) => Promise<{
+        id: string;
+    }>;
+}
+/**
+ * Assert the adapter can record an audited write atomically — it must provide
+ * **both** `withTransaction` and `commands.audit`. Returns a non-null
+ * capability the caller composes; throws `ERR_AUDIT_UNSUPPORTED` otherwise,
+ * rather than silently skipping the audit row or running it non-atomically.
+ * See docs/TRANSACTIONS.md and docs/AUDIT.md.
+ */
+export declare function requireAuditCapability(db: IDbAdapter): AuditCapability;
+/** Order-insensitive equality for the advertised-locale set. */
+export declare function sameLocaleSet(a: readonly string[], b: readonly string[]): boolean;

package/dist/services/document-lifecycle/audit.js

@@ -0,0 +1,67 @@
+/**
+ * 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 write helpers for the document-grain lifecycle write-points
+ * (docs/AUDIT.md — Workstream 2). The audit log records the changes the
+ * immutable version stream does NOT capture an actor for: non-versioned
+ * system-field writes (path, available-locales), in-place status transitions,
+ * and deletions. Each such mutation and its audit row commit atomically inside
+ * `withTransaction` — a silently-unwritten audit row is the one unacceptable
+ * outcome (see docs/TRANSACTIONS.md).
+ */
+import { ERR_AUDIT_UNSUPPORTED } from '../../lib/errors.js';
+import { actorId } from './internals.js';
+/** Namespaced audit actions for document-grain changes. */
+export const AUDIT_ACTIONS = {
+    pathChanged: 'document.path.changed',
+    localesChanged: 'document.locales.changed',
+    statusChanged: 'document.status.changed',
+    deleted: 'document.deleted',
+};
+/**
+ * The actor id + realm for an audit-log row. Mirrors `actorId()`: a real
+ * persisted user carries a UUID id and is recorded with realm `'admin'`
+ * (these write-points are admin-gated, document-grain operations). A synthetic
+ * script/seed actor (non-UUID) or no actor is a system/tooling write — NULL id,
+ * realm `'system'`. (A future `UserAuth`-driven write-point would extend this
+ * to `'user'`.)
+ */
+export function auditActor(ctx) {
+    const id = actorId(ctx);
+    return id != null
+        ? { actorId: id, actorRealm: 'admin' }
+        : { actorId: undefined, actorRealm: 'system' };
+}
+/**
+ * Assert the adapter can record an audited write atomically — it must provide
+ * **both** `withTransaction` and `commands.audit`. Returns a non-null
+ * capability the caller composes; throws `ERR_AUDIT_UNSUPPORTED` otherwise,
+ * rather than silently skipping the audit row or running it non-atomically.
+ * See docs/TRANSACTIONS.md and docs/AUDIT.md.
+ */
+export function requireAuditCapability(db) {
+    const withTransaction = db.withTransaction;
+    const audit = db.commands.audit;
+    if (withTransaction == null || audit == null) {
+        throw ERR_AUDIT_UNSUPPORTED({
+            message: 'audited write requires a db adapter with withTransaction + commands.audit support',
+        });
+    }
+    return {
+        withTransaction: (fn) => withTransaction(fn),
+        append: (input) => audit.append(input),
+    };
+}
+/** Order-insensitive equality for the advertised-locale set. */
+export function sameLocaleSet(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const sa = [...a].sort();
+    const sb = [...b].sort();
+    return sa.every((v, i) => v === sb[i]);
+}

package/dist/services/document-lifecycle/delete.js

@@ -10,6 +10,7 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getUploadFields } from '../../utils/storage-utils.js';
+import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
 import { invokeHook } from './internals.js';
 /**
  * Soft-delete a document.
@@ -91,9 +92,26 @@ export async function deleteDocument(ctx, params) {
         };
         // 2. beforeDelete hook.
         await invokeHook(hooks?.beforeDelete, hookCtx);
-        // 3. Soft-delete all versions.
-        const deletedVersionCount = await db.commands.documents.softDeleteDocument({
-            document_id: params.documentId,
+        // 3. Soft-delete all versions, atomically with the audit record. A
+        //    whole-document delete mints no new version, so the version stream
+        //    never records it — the audit log is the only place a deletion is
+        //    accountable (docs/AUDIT.md). Storage-file cleanup (step 4) is a
+        //    DB↔external side-effect and stays OUTSIDE the transaction — it is
+        //    post-commit, best-effort compensation (docs/TRANSACTIONS.md).
+        const audit = requireAuditCapability(db);
+        const actor = auditActor(ctx);
+        let deletedVersionCount = 0;
+        await audit.withTransaction(async () => {
+            deletedVersionCount = await db.commands.documents.softDeleteDocument({
+                document_id: params.documentId,
+            });
+            await audit.append({
+                documentId: params.documentId,
+                collectionId: ctx.collectionId,
+                actorId: actor.actorId,
+                actorRealm: actor.actorRealm,
+                action: AUDIT_ACTIONS.deleted,
+            });
         });
         // 4. Clean up storage files. Non-fatal: logs errors but does not throw.
         if (ctx.storage && storagePathsToDelete.length > 0) {

package/dist/services/document-lifecycle/internals.d.ts

@@ -17,10 +17,18 @@ import type { SlugifierFn } from '../../utils/slugify.js';
 import type { DocumentLifecycleContext } from './context.js';
 /**
  * The acting user's id for the version audit trail (`created_by` on
- * `byline_document_versions`). `undefined` for internal-tooling callers
- * without a `requestContext` (seeds, migrations — the documented escape
- * hatch), which persists as NULL. Both actor realms (`AdminAuth`,
- * `UserAuth`) carry `id`. See docs/AUDIT.md — Workstream 1.
+ * `byline_document_versions`).
+ *
+ * Returns the id only when it is a real **persisted user id** — i.e. a UUID.
+ * Synthetic actors used by scripts, seeds, and tests (e.g.
+ * `createSuperAdminContext({ id: 'import-docs-script' })`, or the default
+ * `'super-admin'`) are **not** users: their non-UUID ids would be rejected by
+ * the `uuid` column outright, and the correct audit value for a system/tooling
+ * write is NULL regardless. So a non-UUID id — and a missing `requestContext`
+ * (the seeds/migrations escape hatch) — both yield `undefined` → NULL
+ * `created_by`, which the history strip renders as "unknown". Real
+ * `AdminAuth` / `UserAuth` actors always carry UUID ids, so their attribution
+ * is unaffected. See docs/AUDIT.md — Workstream 1.
  */
 export declare function actorId(ctx: DocumentLifecycleContext): string | undefined;
 /**

package/dist/services/document-lifecycle/internals.js

@@ -17,15 +17,29 @@ import { ERR_PATH_CONFLICT, ErrorCodes } from '../../lib/errors.js';
 import { generateKeyBetween } from '../../lib/fractional-index.js';
 import { createReadContext } from '../populate.js';
 import { embedRichTextFields } from '../richtext-embed.js';
+/**
+ * Matches a canonical UUID (any version). Real admin / end-user actors carry
+ * UUID ids (`uuidv7`); synthetic actors do not.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * The acting user's id for the version audit trail (`created_by` on
- * `byline_document_versions`). `undefined` for internal-tooling callers
- * without a `requestContext` (seeds, migrations — the documented escape
- * hatch), which persists as NULL. Both actor realms (`AdminAuth`,
- * `UserAuth`) carry `id`. See docs/AUDIT.md — Workstream 1.
+ * `byline_document_versions`).
+ *
+ * Returns the id only when it is a real **persisted user id** — i.e. a UUID.
+ * Synthetic actors used by scripts, seeds, and tests (e.g.
+ * `createSuperAdminContext({ id: 'import-docs-script' })`, or the default
+ * `'super-admin'`) are **not** users: their non-UUID ids would be rejected by
+ * the `uuid` column outright, and the correct audit value for a system/tooling
+ * write is NULL regardless. So a non-UUID id — and a missing `requestContext`
+ * (the seeds/migrations escape hatch) — both yield `undefined` → NULL
+ * `created_by`, which the history strip renders as "unknown". Real
+ * `AdminAuth` / `UserAuth` actors always carry UUID ids, so their attribution
+ * is unaffected. See docs/AUDIT.md — Workstream 1.
  */
 export function actorId(ctx) {
-    return ctx.requestContext?.actor?.id;
+    const id = ctx.requestContext?.actor?.id;
+    return id != null && UUID_RE.test(id) ? id : undefined;
 }
 /**
  * Safely invoke an optional hook slot, awaiting the result if it returns a

package/dist/services/document-lifecycle/status.js

@@ -10,6 +10,7 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_INVALID_TRANSITION, ERR_NOT_FOUND } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getWorkflow, validateStatusTransition } from '../../workflow/workflow.js';
+import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
 import { invokeHook } from './internals.js';
 /**
  * Change a document's workflow status.
@@ -85,18 +86,34 @@ export async function changeDocumentStatus(ctx, params) {
         };
         // 3. beforeStatusChange hook.
         await invokeHook(hooks?.beforeStatusChange, hookCtx);
-        // 4. Mutate status in-place.
-        await db.commands.documents.setDocumentStatus({
-            document_version_id: documentVersionId,
-            status: params.nextStatus,
-        });
-        // 5. Auto-archive previous published versions.
-        if (params.nextStatus === 'published') {
-            await db.commands.documents.archivePublishedVersions({
-                document_id: params.documentId,
-                excludeVersionId: documentVersionId,
+        // 4–5. Mutate status in-place + auto-archive, atomically with the audit
+        //      record. Status mutates the version row rather than minting a new
+        //      version, so the version stream never captures *who* changed it —
+        //      the audit log is its only accountability home (docs/AUDIT.md).
+        const audit = requireAuditCapability(db);
+        const actor = auditActor(ctx);
+        await audit.withTransaction(async () => {
+            await db.commands.documents.setDocumentStatus({
+                document_version_id: documentVersionId,
+                status: params.nextStatus,
             });
-        }
+            if (params.nextStatus === 'published') {
+                await db.commands.documents.archivePublishedVersions({
+                    document_id: params.documentId,
+                    excludeVersionId: documentVersionId,
+                });
+            }
+            await audit.append({
+                documentId: params.documentId,
+                collectionId,
+                actorId: actor.actorId,
+                actorRealm: actor.actorRealm,
+                action: AUDIT_ACTIONS.statusChanged,
+                field: 'status',
+                before: currentStatus,
+                after: params.nextStatus,
+            });
+        });
         // 6. afterStatusChange hook.
         await invokeHook(hooks?.afterStatusChange, hookCtx);
         return { previousStatus: currentStatus, newStatus: params.nextStatus };

package/dist/services/document-lifecycle/system-fields.d.ts

@@ -38,7 +38,9 @@ export interface UpdateDocumentSystemFieldsResult {
  *      `setDocumentAvailableLocales`.
  *
  * No content hooks fire — these are not content writes. Accountability for
- * these mutations is the job of the (planned) document-grain audit log.
+ * these mutations is the document-grain audit log: each field that actually
+ * changes records a `document.path.changed` / `document.locales.changed` row
+ * atomically with the write (docs/AUDIT.md — Workstream 2).
  *
  * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
  * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.

package/dist/services/document-lifecycle/system-fields.js

@@ -8,6 +8,7 @@
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
+import { AUDIT_ACTIONS, auditActor, requireAuditCapability, sameLocaleSet } from './audit.js';
 import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
 /**
  * Write a document's system-managed, document-grain fields — `path` and the
@@ -34,7 +35,9 @@ import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
  *      `setDocumentAvailableLocales`.
  *
  * No content hooks fire — these are not content writes. Accountability for
- * these mutations is the job of the (planned) document-grain audit log.
+ * these mutations is the document-grain audit log: each field that actually
+ * changes records a `document.path.changed` / `document.locales.changed` row
+ * atomically with the write (docs/AUDIT.md — Workstream 2).
  *
  * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
  * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.
@@ -72,25 +75,59 @@ export async function updateDocumentSystemFields(ctx, params) {
             documentId: params.documentId,
             logger: ctx.logger,
         });
-        if (pathForCommand !== undefined) {
-            await db.commands.documents
-                .updateDocumentPath({
-                documentId: params.documentId,
-                collectionId,
-                locale: sourceLocale,
-                path: pathForCommand,
-            })
-                .catch((err) => rethrowPathConflict(err, pathForCommand, defaultLocale));
-        }
-        // Advertised locales: rewrite the document-grain set wholesale.
+        // Both document-grain writes and their audit rows commit atomically.
+        // These fields are non-versioned, so the version stream never records
+        // them — the audit log is their only accountability home. One audit row
+        // per field that actually changed (docs/AUDIT.md).
+        const currentPath = originalData.path;
+        const currentLocales = originalData.availableLocales ?? [];
         const availableLocalesWritten = params.availableLocales !== undefined;
-        if (params.availableLocales !== undefined) {
-            await db.commands.documents.setDocumentAvailableLocales({
-                documentId: params.documentId,
-                collectionId,
-                availableLocales: params.availableLocales,
-            });
-        }
+        const audit = requireAuditCapability(db);
+        const actor = auditActor(ctx);
+        await audit.withTransaction(async () => {
+            if (pathForCommand !== undefined) {
+                await db.commands.documents
+                    .updateDocumentPath({
+                    documentId: params.documentId,
+                    collectionId,
+                    locale: sourceLocale,
+                    path: pathForCommand,
+                })
+                    .catch((err) => rethrowPathConflict(err, pathForCommand, defaultLocale));
+                if (pathForCommand !== currentPath) {
+                    await audit.append({
+                        documentId: params.documentId,
+                        collectionId,
+                        actorId: actor.actorId,
+                        actorRealm: actor.actorRealm,
+                        action: AUDIT_ACTIONS.pathChanged,
+                        field: 'path',
+                        before: currentPath ?? null,
+                        after: pathForCommand,
+                    });
+                }
+            }
+            // Advertised locales: rewrite the document-grain set wholesale.
+            if (params.availableLocales !== undefined) {
+                await db.commands.documents.setDocumentAvailableLocales({
+                    documentId: params.documentId,
+                    collectionId,
+                    availableLocales: params.availableLocales,
+                });
+                if (!sameLocaleSet(currentLocales, params.availableLocales)) {
+                    await audit.append({
+                        documentId: params.documentId,
+                        collectionId,
+                        actorId: actor.actorId,
+                        actorRealm: actor.actorRealm,
+                        action: AUDIT_ACTIONS.localesChanged,
+                        field: 'availableLocales',
+                        before: currentLocales,
+                        after: params.availableLocales,
+                    });
+                }
+            }
+        });
         return {
             documentId: params.documentId,
             path: pathForCommand,

package/dist/services/document-lifecycle.test.node.js

@@ -8,7 +8,7 @@
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { BylineError, ERR_PATH_CONFLICT, ErrorCodes } from '../lib/errors.js';
-import { changeDocumentStatus, copyToLocale, createDocument, deleteDocument, duplicateDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentWithPatches, } from './document-lifecycle/index.js';
+import { changeDocumentStatus, copyToLocale, createDocument, deleteDocument, duplicateDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentSystemFields, updateDocumentWithPatches, } from './document-lifecycle/index.js';
 // ---------------------------------------------------------------------------
 // Fixtures / Helpers
 // ---------------------------------------------------------------------------
@@ -36,6 +36,11 @@ function createMockDb() {
     const getDocumentById = vi.fn().mockResolvedValue(null);
     const getCurrentVersionMetadata = vi.fn().mockResolvedValue(null);
     const getCurrentPath = vi.fn().mockResolvedValue('current-path');
+    // Audit capability (docs/AUDIT.md — W2). `withTransaction` is a passthrough
+    // in unit tests (runs the unit of work immediately, no real tx); `append`
+    // records the calls so write-point tests can assert the audit rows emitted.
+    const auditAppend = vi.fn().mockResolvedValue({ id: 'audit-1' });
+    const withTransaction = vi.fn(async (fn) => fn());
     const db = {
         commands: {
             collections: {
@@ -45,8 +50,8 @@ function createMockDb() {
             },
             documents: {
                 createDocumentVersion,
-                updateDocumentPath: vi.fn(),
-                setDocumentAvailableLocales: vi.fn(),
+                updateDocumentPath: vi.fn().mockResolvedValue(undefined),
+                setDocumentAvailableLocales: vi.fn().mockResolvedValue(undefined),
                 setDocumentStatus,
                 archivePublishedVersions,
                 softDeleteDocument,
@@ -57,7 +62,9 @@ function createMockDb() {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
             },
+            audit: { append: auditAppend },
         },
+        withTransaction: withTransaction,
         queries: {
             collections: {
                 getAllCollections: vi.fn(),
@@ -92,6 +99,8 @@ function createMockDb() {
         getDocumentById,
         getCurrentVersionMetadata,
         getCurrentPath,
+        auditAppend,
+        withTransaction,
     };
 }
 const noopLogger = {
@@ -104,6 +113,10 @@ const noopLogger = {
     trace: vi.fn(),
     silent: vi.fn(),
 };
+// A real persisted-user id is a UUID; `actorId()` only attributes UUIDs (see
+// the regression note below). Use a valid UUID so the default context's
+// writes are attributed.
+const TEST_ACTOR_ID = '01901234-0000-7000-8000-000000000001';
 function buildCtx(db, definition = minimalCollection) {
     return {
         db,
@@ -117,7 +130,7 @@ function buildCtx(db, definition = minimalCollection) {
         // tests do not have to care about ability enforcement. The dedicated
         // "enforcement" block below covers the missing-context / missing-ability
         // negative cases.
-        requestContext: createSuperAdminContext({ id: 'test-super-admin' }),
+        requestContext: createSuperAdminContext({ id: TEST_ACTOR_ID }),
     };
 }
 // ---------------------------------------------------------------------------
@@ -148,7 +161,18 @@ describe('Document lifecycle service', () => {
             });
             // Audit contract (docs/AUDIT.md — W1): every version row
             // records the actor that created it.
-            expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe('test-super-admin');
+            expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe(TEST_ACTOR_ID);
+        });
+        it('writes NULL createdBy for a synthetic (non-UUID) script/seed actor', async () => {
+            // Regression guard (v3.8.0): a synthetic super-admin id such as
+            // `import-docs-script` is not a real user and is not a UUID — writing
+            // it into the `created_by` UUID column crashed every import/seed. Such
+            // system/tooling writes must attribute to NULL, not the synthetic id.
+            const { db, createDocumentVersion } = createMockDb();
+            const ctx = buildCtx(db);
+            ctx.requestContext = createSuperAdminContext({ id: 'import-docs-script' });
+            await createDocument(ctx, { data: { title: 'Hello' }, locale: 'en' });
+            expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBeUndefined();
         });
         it('invokes beforeCreate and afterCreate hooks in order', async () => {
             const callOrder = [];
@@ -326,7 +350,7 @@ describe('Document lifecycle service', () => {
                 documentId: 'doc-1',
                 data: { title: 'New' },
             });
-            expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe('test-super-admin');
+            expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe(TEST_ACTOR_ID);
         });
         it('fetches the original before calling hooks', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
@@ -668,6 +692,24 @@ describe('Document lifecycle service', () => {
             expect(result.previousStatus).toBe('draft');
             expect(result.newStatus).toBe('published');
         });
+        it('records a document.status.changed audit row atomically (from → to)', async () => {
+            const { db, getCurrentVersionMetadata, auditAppend, withTransaction } = createMockDb();
+            getCurrentVersionMetadata.mockResolvedValue({ ...metadataRow });
+            const ctx = buildCtx(db);
+            await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' });
+            // The mutation + audit row run inside one withTransaction (docs/AUDIT.md).
+            expect(withTransaction).toHaveBeenCalledOnce();
+            expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
+                documentId: 'doc-1',
+                collectionId: 'col-1',
+                actorId: TEST_ACTOR_ID,
+                actorRealm: 'admin',
+                action: 'document.status.changed',
+                field: 'status',
+                before: 'draft',
+                after: 'published',
+            }));
+        });
         it('throws ERR_NOT_FOUND when document is missing', async () => {
             const { db, getCurrentVersionMetadata } = createMockDb();
             getCurrentVersionMetadata.mockResolvedValue(null);
@@ -859,6 +901,76 @@ describe('Document lifecycle service', () => {
             expect(beforeDelete).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'doc-to-delete' }));
             expect(afterDelete).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'doc-to-delete' }));
         });
+        it('records a document.deleted audit row atomically with the soft-delete', async () => {
+            const { db, getDocumentById, softDeleteDocument, auditAppend, withTransaction } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'doc-to-delete',
+                fields: {},
+            });
+            const ctx = buildCtx(db);
+            await deleteDocument(ctx, { documentId: 'doc-1' });
+            expect(withTransaction).toHaveBeenCalledOnce();
+            expect(softDeleteDocument).toHaveBeenCalledWith({ document_id: 'doc-1' });
+            expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
+                documentId: 'doc-1',
+                collectionId: 'col-1',
+                actorRealm: 'admin',
+                action: 'document.deleted',
+            }));
+        });
+    });
+    // -----------------------------------------------------------------------
+    // updateDocumentSystemFields (audited, non-versioned)
+    // -----------------------------------------------------------------------
+    describe('updateDocumentSystemFields', () => {
+        function setupDoc(getDocumentById, overrides) {
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'old-slug',
+                source_locale: 'en',
+                availableLocales: ['en'],
+                fields: {},
+                ...overrides,
+            });
+        }
+        it('records document.path.changed when the path actually changes', async () => {
+            const { db, getDocumentById, auditAppend, withTransaction } = createMockDb();
+            setupDoc(getDocumentById);
+            const ctx = buildCtx(db);
+            await updateDocumentSystemFields(ctx, { documentId: 'doc-1', path: 'new-slug' });
+            expect(withTransaction).toHaveBeenCalledOnce();
+            expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'document.path.changed',
+                field: 'path',
+                before: 'old-slug',
+                after: 'new-slug',
+            }));
+        });
+        it('records no audit row when the path is unchanged', async () => {
+            const { db, getDocumentById, auditAppend } = createMockDb();
+            setupDoc(getDocumentById);
+            const ctx = buildCtx(db);
+            await updateDocumentSystemFields(ctx, { documentId: 'doc-1', path: 'old-slug' });
+            expect(auditAppend).not.toHaveBeenCalled();
+        });
+        it('records document.locales.changed with before/after sets', async () => {
+            const { db, getDocumentById, auditAppend } = createMockDb();
+            setupDoc(getDocumentById);
+            const ctx = buildCtx(db);
+            await updateDocumentSystemFields(ctx, {
+                documentId: 'doc-1',
+                availableLocales: ['en', 'fr'],
+            });
+            expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'document.locales.changed',
+                field: 'availableLocales',
+                before: ['en'],
+                after: ['en', 'fr'],
+            }));
+        });
     });
     // -----------------------------------------------------------------------
     // restoreDocumentVersion

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.8.0"
+    "@byline/auth": "3.10.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",