@byline/core 3.8.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

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.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 }),
     };
 }
 // ---------------------------------------------------------------------------
@@ -148,7 +152,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 +341,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();

package/package.json

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