@byline/core 3.7.0 → 3.9.0

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

@@ -208,6 +208,24 @@ export interface IDbAdapter {
         collections: ICollectionQueries;
         documents: IDocumentQueries;
     };
+    /**
+     * 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
@@ -415,6 +433,8 @@ export interface IDocumentCommands {
         documentId: string;
         locale: string;
         status?: string;
+        /** Acting user id for the version audit trail (`created_by`). See docs/AUDIT.md. */
+        createdBy?: string;
     }): Promise<{
         newVersionId: string;
         previousVersionId: string;

package/dist/schemas/zod/builder.d.ts

@@ -12,6 +12,8 @@ export declare const createBaseSchema: (collection?: CollectionDefinition) => z.
     hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
     createdAt: z.ZodISODateTime;
     updatedAt: z.ZodISODateTime;
+    createdBy: z.ZodOptional<z.ZodUUID>;
+    eventType: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const createFieldsSchema: (fields: Field[], strict?: boolean) => z.ZodObject<{
     [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -44,6 +46,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     fields: z.ZodObject<{
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -62,6 +66,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
@@ -78,6 +84,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -113,6 +121,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -140,6 +150,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
@@ -157,6 +169,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     fields: z.ZodObject<{
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -175,6 +189,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
@@ -191,6 +207,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -226,6 +244,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -253,6 +273,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
@@ -270,6 +292,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     fields: z.ZodObject<{
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -288,6 +312,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
@@ -304,6 +330,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -339,6 +367,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -366,6 +396,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
@@ -383,6 +415,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     fields: z.ZodObject<{
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -401,6 +435,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
@@ -417,6 +453,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -452,6 +490,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -479,6 +519,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;

package/dist/schemas/zod/builder.js

@@ -205,6 +205,11 @@ export const createBaseSchema = (collection) => {
         hasPublishedVersion: z.boolean().optional(),
         createdAt: z.iso.datetime(),
         updatedAt: z.iso.datetime(),
+        // Version audit metadata — acting user + action (see docs/AUDIT.md — Workstream 1).
+        // Declared so list/get/history responses carry them through the
+        // server-fn parse; Zod would otherwise strip them as undeclared keys.
+        createdBy: z.uuid().optional(),
+        eventType: z.string().optional(),
     });
 };
 // Create field schemas for a collection.

package/dist/services/document-lifecycle/copy-to-locale.js

@@ -10,7 +10,7 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
-import { applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
+import { actorId, applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
 import { mergeLocaleData } from './merge-locale-data.js';
 /**
  * Copy a document's content from one locale into another, in place on
@@ -133,6 +133,7 @@ export async function copyToLocale(ctx, params) {
             status: getDefaultStatus(definition),
             locale: params.targetLocale,
             previousVersionId,
+            createdBy: actorId(ctx),
         });
         const documentVersionId = extractVersionId(writeResult.document);
         await invokeHook(hooks?.afterUpdate, {

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

@@ -13,7 +13,7 @@ import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { slugify } from '../../utils/slugify.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+import { actorId, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
 /**
  * Create a new document.
  *
@@ -75,6 +75,7 @@ export async function createDocument(ctx, params) {
             status: params.status ?? data.status ?? getDefaultStatus(definition),
             locale: params.locale ?? defaultLocale,
             orderKey,
+            createdBy: actorId(ctx),
         })
             .catch((err) => rethrowPathConflict(err, resolvedPath, defaultLocale));
         const documentId = extractDocumentId(result.document);

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

@@ -10,7 +10,7 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
-import { invokeHook } from './internals.js';
+import { actorId, invokeHook } from './internals.js';
 /**
  * Remove one content locale's data from a document, in place on the same
  * document, by writing a new immutable version that omits that locale's
@@ -90,6 +90,7 @@ export async function deleteLocale(ctx, params) {
             documentId: params.documentId,
             locale: params.locale,
             status: getDefaultStatus(definition),
+            createdBy: actorId(ctx),
         });
         if (result == null) {
             throw ERR_NOT_FOUND({

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

@@ -12,7 +12,7 @@ import { withLogContext } from '../../lib/logger.js';
 import { slugify } from '../../utils/slugify.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, isPathConflictError, maybeAppendOrderKey, rethrowPathConflict, stripMetaIdsInPlace, } from './internals.js';
+import { actorId, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, isPathConflictError, maybeAppendOrderKey, rethrowPathConflict, stripMetaIdsInPlace, } from './internals.js';
 /**
  * Apply the `" (copy)"` suffix to the configured `useAsTitle` field on a
  * duplicate's data tree. Handles both shapes:
@@ -170,6 +170,7 @@ export async function duplicateDocument(ctx, params) {
                 status: defaultStatus,
                 locale: 'all',
                 orderKey,
+                createdBy: actorId(ctx),
             })
                 .catch((err) => rethrowPathConflict(err, finalPath, defaultLocale));
         }
@@ -194,6 +195,7 @@ export async function duplicateDocument(ctx, params) {
                 status: defaultStatus,
                 locale: 'all',
                 orderKey,
+                createdBy: actorId(ctx),
             })
                 .catch((retryErr) => rethrowPathConflict(retryErr, finalPath, defaultLocale));
         }

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

@@ -15,6 +15,22 @@ import { type CollectionDefinition, type CollectionHookSlot } from '../../@types
 import type { BylineLogger } from '../../lib/logger.js';
 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`).
+ *
+ * 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;
 /**
  * Safely invoke an optional hook slot, awaiting the result if it returns a
  * Promise. When the slot is an array of functions they are executed

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

@@ -17,6 +17,30 @@ 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`).
+ *
+ * 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) {
+    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
  * Promise. When the slot is an array of functions they are executed

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

@@ -10,7 +10,7 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
-import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook } from './internals.js';
+import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, } from './internals.js';
 /**
  * Restore a historical document version as the new current version.
  *
@@ -139,6 +139,7 @@ export async function restoreDocumentVersion(ctx, params) {
             status: getDefaultStatus(definition),
             locale: 'all',
             previousVersionId: currentMeta.document_version_id,
+            createdBy: actorId(ctx),
         });
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);

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

@@ -13,7 +13,7 @@ import { applyPatches } from '../../patches/index.js';
 import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
+import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
 /**
  * Update a document via full replacement (PUT semantics).
  *
@@ -85,6 +85,7 @@ export async function updateDocument(ctx, params) {
             status: defaultStatus,
             locale: requestLocale,
             previousVersionId: originalData.document_version_id,
+            createdBy: actorId(ctx),
         })
             .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;
@@ -198,6 +199,7 @@ export async function updateDocumentWithPatches(ctx, params) {
             status: defaultStatus,
             locale: requestLocale,
             previousVersionId: originalData.document_version_id,
+            createdBy: actorId(ctx),
         })
             .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;

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

@@ -104,6 +104,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 +121,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 }),
     };
 }
 // ---------------------------------------------------------------------------
@@ -139,6 +143,28 @@ describe('Document lifecycle service', () => {
             expect(result.documentId).toBe('doc-1');
             expect(result.documentVersionId).toBe('ver-1');
         });
+        it('passes the acting user id as createdBy for the audit trail', async () => {
+            const { db, createDocumentVersion } = createMockDb();
+            const ctx = buildCtx(db);
+            await createDocument(ctx, {
+                data: { title: 'Hello' },
+                locale: 'en',
+            });
+            // Audit contract (docs/AUDIT.md — W1): every version row
+            // records the actor that created it.
+            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 = [];
             const hooks = {
@@ -307,6 +333,16 @@ describe('Document lifecycle service', () => {
     // updateDocument (PUT)
     // -----------------------------------------------------------------------
     describe('updateDocument', () => {
+        it('passes the acting user id as createdBy for the audit trail', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({ status: 'draft', fields: { title: 'Old' } });
+            const ctx = buildCtx(db);
+            await updateDocument(ctx, {
+                documentId: 'doc-1',
+                data: { title: 'New' },
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe(TEST_ACTOR_ID);
+        });
         it('fetches the original before calling hooks', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({ status: 'draft', fields: { title: 'Old' } });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.7.0",
+  "version": "3.9.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.7.0"
+    "@byline/auth": "3.9.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",