@byline/core 3.6.0 → 3.8.0

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

@@ -415,6 +415,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/@types/field-types.d.ts

@@ -665,4 +665,26 @@ export interface RichTextEmbedContext {
  * each field's `embedRelationsOnSave` flag.
  */
 export type RichTextEmbedFn = (ctx: RichTextEmbedContext) => Promise<void>;
+/**
+ * Context passed to the richtext markdown serializer for one rich-text
+ * field value. Read-only and synchronous — the export surface walks the
+ * stored editor JSON directly (no editor instantiation, no DB reads).
+ */
+export interface RichTextToMarkdownContext {
+    /** The richText field's value (raw editor JSON, possibly stringified). */
+    value: unknown;
+    /** Field path within the document — e.g. `'body'` or `'content.0.caption'`. */
+    fieldPath: string;
+    /** Collection path the document belongs to. */
+    collectionPath: string;
+}
+/**
+ * Server-side markdown serializer contract for the agent-readable export
+ * surface (`documentToMarkdown`, `.md` routes, `llms.txt`). Editor
+ * adapters export an implementation (e.g. `lexicalToMarkdown` from
+ * `@byline/richtext-lexical/server`); installations register one via
+ * `ServerConfig.fields.richText.toMarkdown`. One-way and lossy-tolerant
+ * by contract — output is never re-imported.
+ */
+export type RichTextToMarkdownFn = (ctx: RichTextToMarkdownContext) => string;
 export {};

package/dist/@types/site-config.d.ts

@@ -10,7 +10,7 @@ import type { SlugifierFn } from '../utils/slugify.js';
 import type { CollectionAdminConfig } from './admin-types.js';
 import type { CollectionDefinition } from './collection-types.js';
 import type { IDbAdapter } from './db-types.js';
-import type { RichTextEditorComponent, RichTextEmbedFn, RichTextPopulateFn } from './field-types.js';
+import type { RichTextEditorComponent, RichTextEmbedFn, RichTextPopulateFn, RichTextToMarkdownFn } from './field-types.js';
 import type { IStorageProvider } from './storage-types.js';
 export type DbAdapterFn = (args: {
     connectionString: string;
@@ -307,6 +307,13 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
         richText?: {
             populate?: RichTextPopulateFn;
             embed?: RichTextEmbedFn;
+            /**
+             * `toMarkdown` — one-way markdown serializer for the agent-readable
+             * export surface (`documentToMarkdown`, `.md` routes, `llms.txt`).
+             * Optional: only installations that expose a markdown surface need
+             * it. Synchronous and read-only — it walks stored editor JSON.
+             */
+            toMarkdown?: RichTextToMarkdownFn;
         };
     };
 }

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,14 @@ 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`). `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.
+ */
+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,16 @@ 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';
+/**
+ * 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.
+ */
+export function actorId(ctx) {
+    return ctx.requestContext?.actor?.id;
+}
 /**
  * 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

@@ -139,6 +139,17 @@ 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-super-admin');
+        });
         it('invokes beforeCreate and afterCreate hooks in order', async () => {
             const callOrder = [];
             const hooks = {
@@ -307,6 +318,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-super-admin');
+        });
         it('fetches the original before calling hooks', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({ status: 'draft', fields: { title: 'Old' } });

package/dist/services/document-to-markdown.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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
+ */
+/**
+ * `documentToMarkdown` — the document-grain markdown assembler for the
+ * agent-readable export surface (`.md` routes, `llms.txt`). See
+ * docs/TODO.md → "Markdown export".
+ *
+ * A page is a composite (text, richtext, blocks, arrays, relations); this
+ * walks the collection's schema and the locale-resolved field data in
+ * lockstep and emits ONE markdown document: YAML frontmatter, an H1 from
+ * `useAsTitle`, then fields as sections. One-way and lossy-tolerant by
+ * contract — the output is read-only and never re-imported.
+ *
+ * Editor-agnostic: rich-text leaves are delegated to the registered
+ * `RichTextToMarkdownFn` (the seam beside `embed` / `populate` in
+ * `ServerConfig.fields.richText`), passed in explicitly via options so
+ * this module stays pure and unit-testable without `initBylineCore()`.
+ * Routing knowledge stays out of core the same way: relation and file
+ * URLs resolve through caller-supplied callbacks.
+ *
+ * Rendering rules (the format contract — see the unit tests):
+ *   - `useAsTitle` field → frontmatter `title` + body `# H1` (not repeated
+ *     as a section).
+ *   - A field named `summary` → frontmatter `description` + an unlabelled
+ *     lead paragraph (the standfirst).
+ *   - `richText` fields and `blocks` fields render their content directly,
+ *     with no `## Label` heading — they ARE the document body.
+ *   - Scalar fields (text, textArea, datetime, select, checkbox, numbers)
+ *     → `**Label:** value` lines.
+ *   - `relation` → `**Label:** [title](url)` when populated + resolvable.
+ *   - `image` / `file` → `![alt](url)`.
+ *   - `group` → `## Label` + nested walk; `array` → `## Label` + items.
+ *   - Empty values are skipped entirely — no empty headings.
+ */
+import { type CollectionDefinition, type RichTextToMarkdownFn } from '../@types/index.js';
+export interface MarkdownSourceDocument {
+    /** The document's URL slug (`byline_document_paths` projection). */
+    path?: string;
+    /** Locale-resolved, camelCase field data (the `ClientDocument.fields` shape). */
+    fields: Record<string, any>;
+    updatedAt?: Date | string;
+}
+export interface DocumentToMarkdownOptions {
+    /**
+     * The content locale this render represents (one `.md` variant per
+     * content locale — same cache key dimension as the HTML page).
+     */
+    locale?: string;
+    /** Absolute canonical URL of the HTML page; emitted into frontmatter. */
+    canonicalUrl?: string;
+    /**
+     * Rich-text serializer (the `ServerConfig.fields.richText.toMarkdown`
+     * seam). Without it, rich-text leaves are skipped.
+     */
+    richTextToMarkdown?: RichTextToMarkdownFn;
+    /**
+     * Resolve a relation target to a public URL. Receives the target's
+     * collection path and document slug; return `undefined` to render the
+     * relation as plain text (no link).
+     */
+    resolveUrl?: (collectionPath: string, documentPath: string) => string | undefined;
+    /**
+     * Resolve an upload field value (`StoredFileValue`) to a public URL.
+     * Falls back to the value's own `storageUrl`; the image is skipped when
+     * neither yields a URL.
+     */
+    resolveFileUrl?: (value: Record<string, any>) => string | undefined;
+    /** Extra frontmatter entries, merged after the standard keys. */
+    frontmatter?: Record<string, unknown>;
+}
+/**
+ * Render one document to a markdown string (frontmatter + body).
+ */
+export declare function documentToMarkdown(doc: MarkdownSourceDocument, definition: CollectionDefinition, options?: DocumentToMarkdownOptions): string;

package/dist/services/document-to-markdown.js

@@ -0,0 +1,267 @@
+/**
+ * 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
+ */
+/**
+ * `documentToMarkdown` — the document-grain markdown assembler for the
+ * agent-readable export surface (`.md` routes, `llms.txt`). See
+ * docs/TODO.md → "Markdown export".
+ *
+ * A page is a composite (text, richtext, blocks, arrays, relations); this
+ * walks the collection's schema and the locale-resolved field data in
+ * lockstep and emits ONE markdown document: YAML frontmatter, an H1 from
+ * `useAsTitle`, then fields as sections. One-way and lossy-tolerant by
+ * contract — the output is read-only and never re-imported.
+ *
+ * Editor-agnostic: rich-text leaves are delegated to the registered
+ * `RichTextToMarkdownFn` (the seam beside `embed` / `populate` in
+ * `ServerConfig.fields.richText`), passed in explicitly via options so
+ * this module stays pure and unit-testable without `initBylineCore()`.
+ * Routing knowledge stays out of core the same way: relation and file
+ * URLs resolve through caller-supplied callbacks.
+ *
+ * Rendering rules (the format contract — see the unit tests):
+ *   - `useAsTitle` field → frontmatter `title` + body `# H1` (not repeated
+ *     as a section).
+ *   - A field named `summary` → frontmatter `description` + an unlabelled
+ *     lead paragraph (the standfirst).
+ *   - `richText` fields and `blocks` fields render their content directly,
+ *     with no `## Label` heading — they ARE the document body.
+ *   - Scalar fields (text, textArea, datetime, select, checkbox, numbers)
+ *     → `**Label:** value` lines.
+ *   - `relation` → `**Label:** [title](url)` when populated + resolvable.
+ *   - `image` / `file` → `![alt](url)`.
+ *   - `group` → `## Label` + nested walk; `array` → `## Label` + items.
+ *   - Empty values are skipped entirely — no empty headings.
+ */
+import { isArrayField, isBlocksField, isGroupField, } from '../@types/index.js';
+/**
+ * Render one document to a markdown string (frontmatter + body).
+ */
+export function documentToMarkdown(doc, definition, options = {}) {
+    const ctx = { definition, options };
+    const fields = doc.fields ?? {};
+    const title = stringValue(resolveLocalized(fields[definition.useAsTitle ?? ''], options.locale));
+    const summary = stringValue(resolveLocalized(fields.summary, options.locale));
+    const published = dateValue(resolveLocalized(fields.publishedOn, options.locale));
+    // --- frontmatter -------------------------------------------------------
+    const fm = {};
+    if (title)
+        fm.title = title;
+    if (summary)
+        fm.description = summary;
+    if (options.canonicalUrl)
+        fm.canonical = options.canonicalUrl;
+    if (options.locale)
+        fm.locale = options.locale;
+    fm.collection = definition.path;
+    if (published)
+        fm.published = published;
+    const updated = dateValue(doc.updatedAt);
+    if (updated)
+        fm.updated = updated;
+    Object.assign(fm, options.frontmatter ?? {});
+    // --- body ---------------------------------------------------------------
+    const blocks = [];
+    if (title)
+        blocks.push(`# ${title}`);
+    if (summary)
+        blocks.push(summary);
+    // Fields already represented above never repeat as sections.
+    const handled = new Set([definition.useAsTitle, 'summary', 'publishedOn']);
+    blocks.push(...serializeFieldSet(definition.fields, fields, ctx, 2, handled));
+    return `${renderFrontmatter(fm)}\n\n${blocks.join('\n\n')}\n`;
+}
+function serializeFieldSet(fields, data, ctx, level, skip) {
+    const out = [];
+    for (const field of fields) {
+        if (skip?.has(field.name))
+            continue;
+        const value = resolveLocalized(data?.[field.name], ctx.options.locale);
+        if (isEmpty(value))
+            continue;
+        const rendered = serializeField(field, value, ctx, level);
+        if (rendered != null && rendered.length > 0)
+            out.push(rendered);
+    }
+    return out;
+}
+function serializeField(field, value, ctx, level) {
+    if (isGroupField(field)) {
+        const inner = serializeFieldSet(field.fields, asRecord(value), ctx, level + 1);
+        if (inner.length === 0)
+            return null;
+        return [heading(level, field.label ?? field.name), ...inner].join('\n\n');
+    }
+    if (isArrayField(field)) {
+        if (!Array.isArray(value) || value.length === 0)
+            return null;
+        const items = value
+            .map((item) => serializeFieldSet(field.fields, asRecord(item), ctx, level + 1).join('\n\n'))
+            .filter((s) => s.length > 0);
+        if (items.length === 0)
+            return null;
+        return [heading(level, field.label ?? field.name), ...items].join('\n\n');
+    }
+    if (isBlocksField(field)) {
+        if (!Array.isArray(value) || value.length === 0)
+            return null;
+        const rendered = [];
+        for (const item of value) {
+            const record = asRecord(item);
+            const block = field.blocks.find((b) => b.blockType === record._type);
+            if (block == null)
+                continue;
+            // Blocks are the document body: their fields render directly, with
+            // no per-block heading and no `**Label:**` prefix for richtext.
+            const inner = serializeFieldSet(block.fields, record, ctx, level);
+            if (inner.length > 0)
+                rendered.push(inner.join('\n\n'));
+        }
+        return rendered.length > 0 ? rendered.join('\n\n') : null;
+    }
+    switch (field.type) {
+        case 'richText': {
+            const toMarkdown = ctx.options.richTextToMarkdown;
+            if (toMarkdown == null)
+                return null;
+            const markdown = toMarkdown({
+                value,
+                fieldPath: field.name,
+                collectionPath: ctx.definition.path,
+            });
+            return markdown.trim().length > 0 ? markdown.trim() : null;
+        }
+        case 'relation':
+            return serializeRelation(field, value, ctx);
+        case 'image':
+        case 'file':
+            return serializeUpload(field, value, ctx);
+        case 'date':
+        case 'time':
+        case 'datetime': {
+            const iso = dateValue(value);
+            return iso ? labelled(field, iso) : null;
+        }
+        case 'checkbox':
+        case 'boolean':
+        case 'json':
+        case 'object':
+            // No markdown projection: booleans are almost always presentation
+            // toggles (constrainedWidth, featured) and json/object is
+            // machine-shaped — the export renders content, not configuration.
+            return null;
+        default: {
+            const text = stringValue(value);
+            return text ? labelled(field, text) : null;
+        }
+    }
+}
+function serializeRelation(field, value, ctx) {
+    const record = asRecord(value);
+    const target = asRecord(record.document);
+    const targetFields = asRecord(target.fields);
+    const displayField = field.displayField;
+    const title = stringValue(displayField ? targetFields[displayField] : undefined) ??
+        stringValue(targetFields.title) ??
+        stringValue(target.path);
+    if (record._resolved !== true || title == null)
+        return null;
+    const targetCollection = field.targetCollection;
+    const url = targetCollection && typeof target.path === 'string'
+        ? ctx.options.resolveUrl?.(targetCollection, target.path)
+        : undefined;
+    return labelled(field, url ? `[${title}](${url})` : title);
+}
+function serializeUpload(field, value, ctx) {
+    const record = asRecord(value);
+    const url = ctx.options.resolveFileUrl?.(record) ?? stringValue(record.storageUrl);
+    if (url == null)
+        return null;
+    const alt = stringValue(record.alt) ??
+        stringValue(record.originalFilename) ??
+        stringValue(field.label) ??
+        field.name;
+    return `![${alt.replace(/[[\]]/g, '')}](${url})`;
+}
+// ---------------------------------------------------------------------------
+// Value helpers
+// ---------------------------------------------------------------------------
+/**
+ * Locale-scoped reads deliver flat values; `locale: 'all'` reads deliver
+ * `{ en: …, fr: … }` envelopes. Pick the requested locale (or the first
+ * available) when an envelope sneaks through, so the export never prints
+ * `[object Object]`.
+ */
+function resolveLocalized(value, locale) {
+    if (value != null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        !(value instanceof Date)) {
+        const record = value;
+        const keys = Object.keys(record);
+        const localeLike = keys.length > 0 && keys.every((k) => /^[a-z]{2}(-[A-Za-z]{2,4})?$/.test(k));
+        if (localeLike) {
+            if (locale && locale in record)
+                return record[locale];
+            return record[keys[0]];
+        }
+    }
+    return value;
+}
+function asRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function isEmpty(value) {
+    if (value == null)
+        return true;
+    if (typeof value === 'string')
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+function stringValue(value) {
+    if (typeof value === 'string')
+        return value.trim().length > 0 ? value : null;
+    if (typeof value === 'number')
+        return String(value);
+    return null;
+}
+function dateValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'string') {
+        const date = new Date(value);
+        if (!Number.isNaN(date.getTime()))
+            return date.toISOString();
+    }
+    return null;
+}
+function heading(level, text) {
+    return `${'#'.repeat(Math.min(level, 6))} ${text}`;
+}
+function labelled(field, value) {
+    return `**${field.label ?? field.name}:** ${value}`;
+}
+/** Minimal YAML emitter — flat keys, quoted strings, no nesting needed. */
+function renderFrontmatter(entries) {
+    const lines = ['---'];
+    for (const [key, value] of Object.entries(entries)) {
+        if (value == null)
+            continue;
+        if (typeof value === 'string') {
+            lines.push(`${key}: "${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+        }
+        else {
+            lines.push(`${key}: ${String(value)}`);
+        }
+    }
+    lines.push('---');
+    return lines.join('\n');
+}

package/dist/services/document-to-markdown.test.node.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/services/document-to-markdown.test.node.js

@@ -0,0 +1,161 @@
+/**
+ * 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
+ */
+/**
+ * Contract tests for the document-grain markdown assembler. The expected
+ * strings ARE the format contract — agents build on this shape, so a
+ * change here is a consumer-visible format change and should be
+ * deliberate (docs/TODO.md → "The output is a contract surface").
+ */
+import { describe, expect, it } from 'vitest';
+import { documentToMarkdown } from './document-to-markdown.js';
+const definition = {
+    path: 'docs',
+    labels: { singular: 'Doc', plural: 'Docs' },
+    useAsTitle: 'title',
+    fields: [
+        { name: 'title', label: 'Title', type: 'text', localized: true },
+        { name: 'summary', label: 'Summary', type: 'textArea', localized: true },
+        { name: 'subtitle', label: 'Subtitle', type: 'text' },
+        { name: 'publishedOn', label: 'Published On', type: 'datetime' },
+        { name: 'featured', label: 'Featured', type: 'checkbox', optional: true },
+        {
+            name: 'featureImage',
+            label: 'Feature Image',
+            type: 'relation',
+            targetCollection: 'media',
+            displayField: 'title',
+            optional: true,
+        },
+        {
+            name: 'meta',
+            label: 'Meta',
+            type: 'group',
+            fields: [{ name: 'keywords', label: 'Keywords', type: 'text', optional: true }],
+        },
+        {
+            name: 'content',
+            label: 'Content',
+            type: 'blocks',
+            optional: true,
+            blocks: [
+                {
+                    blockType: 'richTextBlock',
+                    labels: { singular: 'Rich Text', plural: 'Rich Texts' },
+                    fields: [{ name: 'richText', label: 'Rich Text', type: 'richText', localized: true }],
+                },
+            ],
+        },
+    ],
+};
+const baseDoc = {
+    path: 'getting-started',
+    updatedAt: new Date('2026-06-01T12:00:00Z'),
+    fields: {
+        title: 'Getting Started',
+        summary: 'How to begin.',
+        publishedOn: new Date('2026-05-01T00:00:00Z'),
+    },
+};
+describe('documentToMarkdown', () => {
+    it('renders frontmatter, H1, and the summary standfirst', () => {
+        const markdown = documentToMarkdown(baseDoc, definition, {
+            locale: 'en',
+            canonicalUrl: 'https://example.com/docs/getting-started',
+        });
+        expect(markdown).toBe([
+            '---',
+            'title: "Getting Started"',
+            'description: "How to begin."',
+            'canonical: "https://example.com/docs/getting-started"',
+            'locale: "en"',
+            'collection: "docs"',
+            'published: "2026-05-01T00:00:00.000Z"',
+            'updated: "2026-06-01T12:00:00.000Z"',
+            '---',
+            '',
+            '# Getting Started',
+            '',
+            'How to begin.',
+            '',
+        ].join('\n'));
+    });
+    it('renders scalar fields as labelled lines and skips empty values', () => {
+        const markdown = documentToMarkdown({
+            ...baseDoc,
+            fields: { ...baseDoc.fields, subtitle: 'A subtitle', featured: true },
+        }, definition, {});
+        expect(markdown).toContain('**Subtitle:** A subtitle');
+        // Booleans render nothing — presentation toggles are not content.
+        expect(markdown).not.toContain('Featured');
+        expect(markdown).not.toContain('Keywords'); // empty group skipped, no heading
+    });
+    it('renders blocks content directly via the richtext seam — no heading', () => {
+        const markdown = documentToMarkdown({
+            ...baseDoc,
+            fields: {
+                ...baseDoc.fields,
+                content: [
+                    { _type: 'richTextBlock', richText: { root: { children: [] } } },
+                    { _type: 'richTextBlock', richText: { root: { children: [] } } },
+                ],
+            },
+        }, definition, {
+            richTextToMarkdown: ({ fieldPath }) => `serialized(${fieldPath})`,
+        });
+        expect(markdown).toContain('serialized(richText)\n\nserialized(richText)');
+        expect(markdown).not.toContain('## Content');
+    });
+    it('skips richtext entirely when no serializer is registered', () => {
+        const markdown = documentToMarkdown({
+            ...baseDoc,
+            fields: {
+                ...baseDoc.fields,
+                content: [{ _type: 'richTextBlock', richText: { root: { children: [] } } }],
+            },
+        }, definition, {});
+        expect(markdown).not.toContain('serialized');
+        expect(markdown).not.toContain('[object');
+    });
+    it('renders populated relations as links via resolveUrl', () => {
+        const markdown = documentToMarkdown({
+            ...baseDoc,
+            fields: {
+                ...baseDoc.fields,
+                featureImage: {
+                    targetDocumentId: 'm-1',
+                    _resolved: true,
+                    document: { path: 'hero-shot', fields: { title: 'Hero Shot' } },
+                },
+            },
+        }, definition, { resolveUrl: (collection, path) => `/${collection}/${path}` });
+        expect(markdown).toContain('**Feature Image:** [Hero Shot](/media/hero-shot)');
+    });
+    it('renders unresolved relations as nothing', () => {
+        const markdown = documentToMarkdown({
+            ...baseDoc,
+            fields: {
+                ...baseDoc.fields,
+                featureImage: { targetDocumentId: 'gone', _resolved: false },
+            },
+        }, definition, {});
+        expect(markdown).not.toContain('Feature Image');
+    });
+    it('renders group fields as sections', () => {
+        const markdown = documentToMarkdown({ ...baseDoc, fields: { ...baseDoc.fields, meta: { keywords: 'cms, markdown' } } }, definition, {});
+        expect(markdown).toContain('## Meta\n\n**Keywords:** cms, markdown');
+    });
+    it('unwraps locale envelopes that reach the export untrimmed', () => {
+        const markdown = documentToMarkdown({ ...baseDoc, fields: { ...baseDoc.fields, title: { en: 'English', fr: 'Français' } } }, definition, { locale: 'fr' });
+        expect(markdown).toContain('# Français');
+        expect(markdown).not.toContain('[object');
+    });
+    it('escapes double quotes in frontmatter strings', () => {
+        const markdown = documentToMarkdown({ ...baseDoc, fields: { ...baseDoc.fields, title: 'The "Big" One' } }, definition, {});
+        expect(markdown).toContain('title: "The \\"Big\\" One"');
+    });
+});

package/dist/services/index.d.ts

@@ -5,6 +5,7 @@ export { type CollectionRecord, type EnsureCollectionsInput, ensureCollections,
 export { type DiscoverCounterGroupsInput, discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle/index.js';
 export * from './document-read.js';
+export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { type InterfaceI18nConfig, type TranslationDriftWarning, type ValidateTranslationsResult, validateTranslations, } from './i18n-validator.js';
 export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, type UnresolvedRelationValue, } from './populate.js';

package/dist/services/index.js

@@ -6,6 +6,7 @@ export { ensureCollections, } from './collection-bootstrap.js';
 export { discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle/index.js';
 export * from './document-read.js';
+export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { validateTranslations, } from './i18n-validator.js';
 export { createReadContext, populateDocuments, } from './populate.js';

package/package.json

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