@byline/core 3.21.0 → 4.0.0

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

@@ -17,6 +17,7 @@ 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';
+import { createRichTextDocumentReader } from '../richtext-populate.js';
 /**
  * Matches a canonical UUID (any version). Real admin / end-user actors carry
  * UUID ids (`uuidv7`); synthetic actors do not.
@@ -70,20 +71,38 @@ export async function applyRichTextEmbed(ctx, data) {
     // `initBylineCore()` (unit tests, isolated tooling) — they have no
     // adapter to invoke, so this is a soft no-op.
     let embed;
+    let richTextPopulate;
+    let collections;
     try {
-        embed = getServerConfig().fields?.richText?.embed;
+        const config = getServerConfig();
+        embed = config.fields?.richText?.embed;
+        richTextPopulate = config.fields?.richText?.populate;
+        collections = config.collections;
     }
     catch {
         return;
     }
-    if (embed == null)
+    if (embed == null || ctx.requestContext == null)
         return;
+    const readContext = createReadContext();
+    const requestContext = { ...ctx.requestContext, readMode: 'published' };
     await embedRichTextFields({
         fields: ctx.definition.fields,
         collectionPath: ctx.collectionPath,
         data,
         embed,
-        readContext: createReadContext(),
+        readContext,
+        requestContext,
+        readMode: 'published',
+        readDocuments: createRichTextDocumentReader({
+            db: ctx.db,
+            collections,
+            requestContext,
+            readContext,
+            readMode: 'published',
+            locale: ctx.defaultLocale,
+            richTextPopulate,
+        }),
         logger: ctx.logger,
     });
 }
@@ -103,49 +122,6 @@ export async function maybeAppendOrderKey(ctx, collectionPath) {
     });
     return generateKeyBetween(last, null);
 }
-/**
- * Append a document as the **last root** of its `tree: true` collection's tree.
- * Mints a fresh root-group `order_key` after the current trailing root. Used by
- * create's auto-place and update's self-heal so a tree collection never strands a
- * document in the "unplaced" limbo. Issues the storage command directly — the
- * caller has already asserted the relevant ability and this is a system step.
- */
-export async function appendTreeRoot(ctx, documentId) {
-    const roots = await ctx.db.queries.documents.getTreeChildren({
-        collectionId: ctx.collectionId,
-        parentDocumentId: null,
-    });
-    await ctx.db.commands.documents.placeTreeNode({
-        collectionId: ctx.collectionId,
-        documentId,
-        parentDocumentId: null,
-        beforeDocumentId: roots.at(-1)?.document_id ?? null,
-    });
-}
-/**
- * Self-heal a genuinely-*unplaced* document on update: if the collection is a
- * tree and the document has no edge row, append it as a root (mirroring create's
- * auto-place). `getTreeParent` distinguishes unplaced from root, so an existing
- * root or child is left exactly where it is — only strays (e.g. docs created
- * before the flag, or whose create-time auto-place failed) are re-treed.
- *
- * No-op for non-tree collections. Best-effort and post-version: a failure leaves
- * the document saved-but-unplaced and is logged, never thrown. See
- * docs/04-collections/03-document-trees.md.
- */
-export async function selfHealTreePlacement(ctx, documentId) {
-    if (ctx.definition.tree !== true)
-        return;
-    try {
-        const { placed } = await ctx.db.queries.documents.getTreeParent({ document_id: documentId });
-        if (placed)
-            return;
-        await appendTreeRoot(ctx, documentId);
-    }
-    catch (err) {
-        ctx.logger.error({ err, documentId }, 'failed to self-heal tree placement on update');
-    }
-}
 /** Extract `id` from the document object returned by `createDocumentVersion`. */
 export function extractVersionId(document) {
     return document?.id ?? document?.document_version_id ?? '';

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

@@ -33,7 +33,7 @@ export declare function changeDocumentStatus(ctx: DocumentLifecycleContext, para
  *
  * Flow:
  *   1. `hooks.beforeUnpublish({ documentId, collectionPath })`
- *   2. `db.commands.documents.archivePublishedVersions(...)`
+ *   2. Archive published versions and append the status audit atomically
  *   3. `hooks.afterUnpublish({ documentId, collectionPath, archivedCount })`
  */
 export declare function unpublishDocument(ctx: DocumentLifecycleContext, params: {

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

@@ -124,7 +124,7 @@ export async function changeDocumentStatus(ctx, params) {
  *
  * Flow:
  *   1. `hooks.beforeUnpublish({ documentId, collectionPath })`
- *   2. `db.commands.documents.archivePublishedVersions(...)`
+ *   2. Archive published versions and append the status audit atomically
  *   3. `hooks.afterUnpublish({ documentId, collectionPath, archivedCount })`
  */
 export async function unpublishDocument(ctx, params) {
@@ -153,8 +153,25 @@ export async function unpublishDocument(ctx, params) {
             collectionPath,
             path,
         });
-        const archivedCount = await db.commands.documents.archivePublishedVersions({
-            document_id: params.documentId,
+        const audit = requireAuditCapability(db);
+        const actor = auditActor(ctx);
+        const archivedCount = await audit.withTransaction(async () => {
+            const count = await db.commands.documents.archivePublishedVersions({
+                document_id: params.documentId,
+            });
+            if (count > 0) {
+                await audit.append({
+                    documentId: params.documentId,
+                    collectionId,
+                    actorId: actor.actorId,
+                    actorRealm: actor.actorRealm,
+                    action: AUDIT_ACTIONS.statusChanged,
+                    field: 'status',
+                    before: 'published',
+                    after: 'archived',
+                });
+            }
+            return count;
         });
         await invokeHook(hooks?.afterUnpublish, {
             documentId: params.documentId,

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

@@ -10,7 +10,13 @@ export interface UpdateDocumentSystemFieldsResult {
     documentId: string;
     /** The path actually written, or `undefined` when no path write occurred. */
     path?: string;
-    /** Whether the advertised-locale set was rewritten this call. */
+    /** Whether either system field actually changed. */
+    changed: boolean;
+    /** Whether a no-op request emitted the reconciliation hook. */
+    reconciliation: boolean;
+    pathChanged: boolean;
+    availableLocalesChanged: boolean;
+    /** Whether the advertised-locale set was actually rewritten this call. */
     availableLocalesWritten: boolean;
 }
 /**
@@ -29,7 +35,8 @@ export interface UpdateDocumentSystemFieldsResult {
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
- *   2. Fetch the document to resolve its `source_locale` anchor + current path.
+ *   2. Inside the audit transaction, lock the logical document and read its
+ *      authoritative source locale, path, and advertised locales.
  *   3. Path (when supplied): `resolvePathForUpdate` enforces the source-locale
  *      rule (translation-locale path edits are dropped with a warn); a real
  *      change is written via `updateDocumentPath`, mapping the unique-constraint
@@ -37,10 +44,14 @@ export interface UpdateDocumentSystemFieldsResult {
  *   4. `availableLocales` (when supplied): rewritten wholesale via
  *      `setDocumentAvailableLocales`.
  *
- * No content hooks fire — these are not content writes. Accountability for
- * 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/06-auth-and-security/02-auditability.md — Workstream 2).
+ * Content hooks do not fire because these are not content writes. Actual
+ * changes emit `afterSystemFieldsChange` after the audited write commits. A
+ * caller can pass `reconcile: true` to emit the same hook for a no-op retry
+ * after an earlier post-commit hook failure. Hook failures reject the call but
+ * never roll back the already-committed write/audit.
+ * Accountability for these mutations is the document-grain audit log: each
+ * changed field records a `document.path.changed` /
+ * `document.locales.changed` row atomically with the write.
  *
  * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
  * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.
@@ -61,4 +72,6 @@ export declare function updateDocumentSystemFields(ctx: DocumentLifecycleContext
      * included — replaces the set wholesale.
      */
     availableLocales?: string[];
+    /** Re-run `afterSystemFieldsChange` when requested values are already current. */
+    reconcile?: boolean;
 }): Promise<UpdateDocumentSystemFieldsResult>;

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

@@ -5,11 +5,12 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { ERR_NOT_FOUND } from '../../lib/errors.js';
+import { ERR_AUDIT_UNSUPPORTED, 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';
+import { invokeHook, resolvePathForUpdate, rethrowPathConflict } from './internals.js';
 /**
  * Write a document's system-managed, document-grain fields — `path` and the
  * editorial `availableLocales` set — **without** minting a new version or
@@ -26,7 +27,8 @@ import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
- *   2. Fetch the document to resolve its `source_locale` anchor + current path.
+ *   2. Inside the audit transaction, lock the logical document and read its
+ *      authoritative source locale, path, and advertised locales.
  *   3. Path (when supplied): `resolvePathForUpdate` enforces the source-locale
  *      rule (translation-locale path edits are dropped with a warn); a real
  *      change is written via `updateDocumentPath`, mapping the unique-constraint
@@ -34,58 +36,67 @@ import { resolvePathForUpdate, rethrowPathConflict } from './internals.js';
  *   4. `availableLocales` (when supplied): rewritten wholesale via
  *      `setDocumentAvailableLocales`.
  *
- * No content hooks fire — these are not content writes. Accountability for
- * 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/06-auth-and-security/02-auditability.md — Workstream 2).
+ * Content hooks do not fire because these are not content writes. Actual
+ * changes emit `afterSystemFieldsChange` after the audited write commits. A
+ * caller can pass `reconcile: true` to emit the same hook for a no-op retry
+ * after an earlier post-commit hook failure. Hook failures reject the call but
+ * never roll back the already-committed write/audit.
+ * Accountability for these mutations is the document-grain audit log: each
+ * changed field records a `document.path.changed` /
+ * `document.locales.changed` row atomically with the write.
  *
  * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
  * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.
  */
 export async function updateDocumentSystemFields(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocumentSystemFields' }, async () => {
-        const { db, collectionId, collectionPath, defaultLocale } = ctx;
+        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
         const requestLocale = params.locale ?? defaultLocale;
-        // Resolve the document's source-locale anchor + current path. Both feed
-        // the path source-locale guard below; the fetch also asserts existence.
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: requestLocale,
-            reconstruct: true,
-        });
-        if (latest == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
-        const originalData = latest;
-        const sourceLocale = originalData.source_locale ?? defaultLocale;
-        // Path: honour the same source-locale-only rule the versioned write
-        // uses. `resolvePathForUpdate` returns `undefined` to mean "skip the
-        // write" (null/empty override, or a translation-locale save).
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
-        const pathForCommand = resolvePathForUpdate({
-            explicitPath,
-            currentPath: originalData.path,
-            requestLocale,
-            sourceLocale,
-            documentId: params.documentId,
-            logger: ctx.logger,
-        });
-        // 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/06-auth-and-security/02-auditability.md).
-        const currentPath = originalData.path;
-        const currentLocales = originalData.availableLocales ?? [];
-        const availableLocalesWritten = params.availableLocales !== undefined;
+        const requested = {
+            path: explicitPath !== null,
+            availableLocales: params.availableLocales !== undefined,
+        };
+        const requestedLocales = params.availableLocales === undefined ? undefined : [...new Set(params.availableLocales)];
         const audit = requireAuditCapability(db);
+        const getDocumentSystemFieldsForUpdate = db.queries.documents.getDocumentSystemFieldsForUpdate;
+        if (typeof getDocumentSystemFieldsForUpdate !== 'function') {
+            throw ERR_AUDIT_UNSUPPORTED({
+                message: 'audited system-field writes require a transaction-scoped lock/read capability',
+            });
+        }
+        const lockSystemFields = getDocumentSystemFieldsForUpdate.bind(db.queries.documents);
         const actor = auditActor(ctx);
-        await audit.withTransaction(async () => {
-            if (pathForCommand !== undefined) {
+        // The logical document row is the mutex for both document-grain fields.
+        // Reading after that lock prevents concurrent writers from auditing a
+        // stale before value or omitting an intermediate old path from the event.
+        const outcome = await audit.withTransaction(async () => {
+            const snapshot = await lockSystemFields({
+                collection_id: collectionId,
+                document_id: params.documentId,
+            });
+            if (snapshot == null) {
+                throw ERR_NOT_FOUND({
+                    message: 'document not found',
+                    details: { documentId: params.documentId },
+                }).log(ctx.logger);
+            }
+            const sourceLocale = snapshot.source_locale ?? defaultLocale;
+            const currentPath = snapshot.path ?? undefined;
+            const currentLocales = snapshot.availableLocales;
+            const nextLocales = requestedLocales ?? currentLocales;
+            const pathForCommand = resolvePathForUpdate({
+                explicitPath,
+                currentPath,
+                requestLocale,
+                sourceLocale,
+                documentId: params.documentId,
+                logger: ctx.logger,
+            });
+            const pathChanged = pathForCommand !== undefined && pathForCommand !== currentPath;
+            const availableLocalesChanged = requestedLocales !== undefined && !sameLocaleSet(currentLocales, nextLocales);
+            if (pathChanged) {
                 await db.commands.documents
                     .updateDocumentPath({
                     documentId: params.documentId,
@@ -93,45 +104,72 @@ export async function updateDocumentSystemFields(ctx, params) {
                     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,
-                    });
-                }
+                    .catch((err) => rethrowPathConflict(err, pathForCommand, sourceLocale));
+                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) {
+            if (availableLocalesChanged) {
                 await db.commands.documents.setDocumentAvailableLocales({
                     documentId: params.documentId,
                     collectionId,
-                    availableLocales: params.availableLocales,
+                    availableLocales: nextLocales,
+                });
+                await audit.append({
+                    documentId: params.documentId,
+                    collectionId,
+                    actorId: actor.actorId,
+                    actorRealm: actor.actorRealm,
+                    action: AUDIT_ACTIONS.localesChanged,
+                    field: 'availableLocales',
+                    before: currentLocales,
+                    after: nextLocales,
                 });
-                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 {
+                pathForCommand,
+                pathChanged,
+                availableLocalesChanged,
+                previousPath: currentPath,
+                currentPath: pathChanged ? pathForCommand : currentPath,
+                previousAvailableLocales: [...currentLocales],
+                currentAvailableLocales: [...nextLocales],
+            };
         });
+        const changed = outcome.pathChanged || outcome.availableLocalesChanged;
+        const reconciliation = !changed && params.reconcile === true;
+        if (changed || reconciliation) {
+            const hooks = await resolveHooks(definition);
+            await invokeHook(hooks?.afterSystemFieldsChange, {
+                documentId: params.documentId,
+                collectionPath,
+                requested,
+                changed: {
+                    path: outcome.pathChanged,
+                    availableLocales: outcome.availableLocalesChanged,
+                },
+                reconciliation,
+                previousPath: outcome.previousPath,
+                currentPath: outcome.currentPath,
+                previousAvailableLocales: outcome.previousAvailableLocales,
+                currentAvailableLocales: outcome.currentAvailableLocales,
+            });
+        }
         return {
             documentId: params.documentId,
-            path: pathForCommand,
-            availableLocalesWritten,
+            path: outcome.pathChanged ? outcome.pathForCommand : undefined,
+            changed,
+            reconciliation,
+            pathChanged: outcome.pathChanged,
+            availableLocalesChanged: outcome.availableLocalesChanged,
+            availableLocalesWritten: outcome.availableLocalesChanged,
         };
     });
 }

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

@@ -5,42 +5,40 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { type TreeAuditCapability } from './audit.js';
+import type { TreeDeleteMutationResult } from '../../@types/index.js';
 import type { DocumentLifecycleContext } from './context.js';
-/**
- * Place or move a node within the collection's tree (place / reorder /
- * re-parent — one upsert). Asserts the `update` ability, performs the storage
- * write, then fires `afterTreeChange` with the affected set. The affected-set
- * reads are skipped entirely when the collection declares no `afterTreeChange`
- * hook, so the event machinery adds no overhead to collections that don't
- * consume it.
- */
-export declare function placeTreeNode(ctx: DocumentLifecycleContext, params: {
+interface PlaceParams {
     documentId: string;
     parentDocumentId: string | null;
     beforeDocumentId?: string | null;
     afterDocumentId?: string | null;
-}): Promise<{
+    ifUnplaced?: boolean;
+    /** Re-fire the post-commit hook when the requested placement is already current. */
+    reconcile?: boolean;
+}
+/** Place, re-parent, or reorder a node; explicit no-op retries may reconcile hooks. */
+export declare function placeTreeNode(ctx: DocumentLifecycleContext, params: PlaceParams): Promise<{
     orderKey: string;
 }>;
-/**
- * Remove a node from the tree (back to the *unplaced* state). Asserts `update`,
- * performs the storage delete, then fires `afterTreeChange`. Distinct from
- * deleting the document.
- */
+/** Best-effort create/self-heal primitive that never moves an already-placed node. */
+export declare function appendTreeRoot(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
+/** Best-effort post-version repair; locked `ifUnplaced` closes the check/write race. */
+export declare function selfHealTreePlacement(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
+/** Remove a node to the unplaced state; an already-unplaced node is a true no-op. */
 export declare function removeFromTree(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    reconcile?: boolean;
 }): Promise<void>;
 /**
- * Promote a soft-deleted node's children to root and remove the node from the
- * tree — the application-level equivalent of the table's `parent → set null`
- * (promote) and `child → cascade` (leave) foreign keys, which only fire on a
- * *hard* row delete. Byline deletes are soft (the document row survives), so the
- * tree must be reconciled here. Fires one `afterTreeChange` (`promote-on-delete`)
- * covering the deleted node, the promoted children, and their subtrees.
- *
- * Best-effort and idempotent: a node with no children or no edge row is a no-op.
- * Called by the document delete lifecycle for `tree: true` collections.
+ * Reconcile delete-time edges and append parent plus child-specific audit rows.
+ * The caller owns the transaction; delete uses this beside soft-delete/audit.
  */
+export declare function reconcileTreeOnDeleteInTransaction(ctx: DocumentLifecycleContext, documentId: string, capability: TreeAuditCapability): Promise<TreeDeleteMutationResult>;
+/** Fire the promotion invalidation after its transaction commits. */
+export declare function firePromoteTreeChange(ctx: DocumentLifecycleContext, documentId: string, result: TreeDeleteMutationResult): Promise<void>;
+/** Standalone audited reconciliation used by internal tooling and tests. */
 export declare function promoteChildrenAndRemove(ctx: DocumentLifecycleContext, params: {
     documentId: string;
 }): Promise<void>;
+export {};