@byline/core 4.18.0 → 4.19.0

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

@@ -786,9 +786,12 @@ export interface IDocumentCommands {
         createdBy?: string;
         /**
          * When updating an existing document, the version ID of the version being
-         * replaced. If provided and `locale` is a specific locale (not 'all'),
-         * field-value rows for other locales are copied forward from this version
-         * into the new one so that per-locale content is not lost.
+         * replaced. The adapter verifies this ID against the current live version
+         * while holding the document-row lock and throws `ERR_CONFLICT` when it is
+         * stale. A locale-specific write to an existing versioned document must
+         * provide this value so field rows for every other locale can be copied
+         * forward safely. `locale: 'all'` writes replace the complete locale tree
+         * and may omit it; when supplied, it must still be current.
          */
         previousVersionId?: string;
         /**

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
-export { BylineError, type DbErrorClassification, type DbErrorCode, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
+export { BylineError, type DbErrorClassification, type DbErrorCode, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { type BylineLogger, getLogger } from './lib/logger.js';
 export { AsyncRegistry, type RegisteredServices, Registry } from './lib/registry.js';

package/dist/index.js

@@ -20,7 +20,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
-export { BylineError, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
+export { BylineError, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { getLogger } from './lib/logger.js';
 export { AsyncRegistry, Registry } from './lib/registry.js';

package/dist/lib/errors.d.ts

@@ -88,12 +88,15 @@ export declare const ErrorCodes: {
     readonly READ_RECURSION: 'ERR_READ_RECURSION';
     readonly PATH_CONFLICT: 'ERR_PATH_CONFLICT';
     readonly AUDIT_UNSUPPORTED: 'ERR_AUDIT_UNSUPPORTED';
+    readonly DOCUMENT_HOOK_COMMITTED: 'ERR_DOCUMENT_HOOK_COMMITTED';
     readonly TREE_HOOK_COMMITTED: 'ERR_TREE_HOOK_COMMITTED';
 };
 /** Stable message fallback for stale tree-placement `ERR_CONFLICT` errors. */
 export declare const TREE_PLACEMENT_STALE_MARKER = "[ERR_CONFLICT:TREE_PLACEMENT_STALE]";
 /** Stable message fallback for `ERR_TREE_HOOK_COMMITTED` errors. */
 export declare const TREE_HOOK_COMMITTED_MARKER = "[ERR_TREE_HOOK_COMMITTED]";
+/** Stable message fallback for `ERR_DOCUMENT_HOOK_COMMITTED` errors. */
+export declare const DOCUMENT_HOOK_COMMITTED_MARKER = "[ERR_DOCUMENT_HOOK_COMMITTED]";
 export declare const ERR_UNHANDLED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_NOT_FOUND: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_CONFLICT: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
@@ -121,6 +124,13 @@ export declare const ERR_PATH_CONFLICT: (opts: BylineErrorOptions, errorConstruc
  * docs/03-architecture/03-transactions.md and docs/07-auth-and-security/02-auditability.md.
  */
 export declare const ERR_AUDIT_UNSUPPORTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+/**
+ * A document version committed, but its post-commit `afterCreate` or
+ * `afterUpdate` hook failed. Callers still receive a rejection so existing
+ * SDK error handling keeps working, while hosts can distinguish this from a
+ * rolled-back write and reconcile their UI without replaying the mutation.
+ */
+export declare const ERR_DOCUMENT_HOOK_COMMITTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 /**
  * A tree mutation and its audit row committed, but its post-commit
  * `afterTreeChange` work failed. Callers still receive a rejection so they can

package/dist/lib/errors.js

@@ -122,12 +122,15 @@ export const ErrorCodes = {
     READ_RECURSION: 'ERR_READ_RECURSION',
     PATH_CONFLICT: 'ERR_PATH_CONFLICT',
     AUDIT_UNSUPPORTED: 'ERR_AUDIT_UNSUPPORTED',
+    DOCUMENT_HOOK_COMMITTED: 'ERR_DOCUMENT_HOOK_COMMITTED',
     TREE_HOOK_COMMITTED: 'ERR_TREE_HOOK_COMMITTED',
 };
 /** Stable message fallback for stale tree-placement `ERR_CONFLICT` errors. */
 export const TREE_PLACEMENT_STALE_MARKER = '[ERR_CONFLICT:TREE_PLACEMENT_STALE]';
 /** Stable message fallback for `ERR_TREE_HOOK_COMMITTED` errors. */
 export const TREE_HOOK_COMMITTED_MARKER = '[ERR_TREE_HOOK_COMMITTED]';
+/** Stable message fallback for `ERR_DOCUMENT_HOOK_COMMITTED` errors. */
+export const DOCUMENT_HOOK_COMMITTED_MARKER = '[ERR_DOCUMENT_HOOK_COMMITTED]';
 // ---------------------------------------------------------------------------
 // Pre-instantiated factories
 // ---------------------------------------------------------------------------
@@ -158,6 +161,13 @@ export const ERR_PATH_CONFLICT = createErrorType(ErrorCodes.PATH_CONFLICT, 'warn
  * docs/03-architecture/03-transactions.md and docs/07-auth-and-security/02-auditability.md.
  */
 export const ERR_AUDIT_UNSUPPORTED = createErrorType(ErrorCodes.AUDIT_UNSUPPORTED);
+/**
+ * A document version committed, but its post-commit `afterCreate` or
+ * `afterUpdate` hook failed. Callers still receive a rejection so existing
+ * SDK error handling keeps working, while hosts can distinguish this from a
+ * rolled-back write and reconcile their UI without replaying the mutation.
+ */
+export const ERR_DOCUMENT_HOOK_COMMITTED = createErrorType(ErrorCodes.DOCUMENT_HOOK_COMMITTED, 'warn');
 /**
  * A tree mutation and its audit row committed, but its post-commit
  * `afterTreeChange` work failed. Callers still receive a rejection so they can

package/dist/services/document-lifecycle/committed-hook.d.ts

@@ -0,0 +1,24 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { ErrorCodes } from '../../lib/errors.js';
+import type { DocumentLifecycleContext } from './context.js';
+export type DocumentHookCommittedPhase = 'afterCreate' | 'afterUpdate' | 'afterSave';
+export type DocumentHookSideEffectCode = typeof ErrorCodes.STORAGE | typeof ErrorCodes.UNHANDLED;
+export interface DocumentHookCommittedDetails {
+    phase: DocumentHookCommittedPhase;
+    documentId: string;
+    documentVersionId: string;
+    sideEffectCode: DocumentHookSideEffectCode;
+}
+/** Read and validate the public, non-sensitive metadata from a committed hook failure. */
+export declare function getDocumentHookCommittedDetails(error: unknown): DocumentHookCommittedDetails | null;
+/**
+ * Run a hook after its document version has committed, preserving rejection
+ * semantics while making the committed state machine-readable to hosts.
+ */
+export declare function runCommittedDocumentHook(ctx: DocumentLifecycleContext, details: Omit<DocumentHookCommittedDetails, 'sideEffectCode'>, callback: () => Promise<void>): Promise<void>;

package/dist/services/document-lifecycle/committed-hook.js

@@ -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
+ */
+import { DOCUMENT_HOOK_COMMITTED_MARKER, ERR_DOCUMENT_HOOK_COMMITTED, ErrorCodes, } from '../../lib/errors.js';
+function readStringProperty(value, key) {
+    try {
+        if ((typeof value !== 'object' || value === null) && typeof value !== 'function') {
+            return undefined;
+        }
+        const property = Reflect.get(value, key);
+        return typeof property === 'string' ? property : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sideEffectCode(error) {
+    return readStringProperty(error, 'code') === ErrorCodes.STORAGE
+        ? ErrorCodes.STORAGE
+        : ErrorCodes.UNHANDLED;
+}
+/** Read and validate the public, non-sensitive metadata from a committed hook failure. */
+export function getDocumentHookCommittedDetails(error) {
+    if (readStringProperty(error, 'code') !== ErrorCodes.DOCUMENT_HOOK_COMMITTED)
+        return null;
+    let details;
+    try {
+        details = Reflect.get(error, 'details');
+    }
+    catch {
+        return null;
+    }
+    if (typeof details !== 'object' || details === null)
+        return null;
+    const phase = readStringProperty(details, 'phase');
+    const documentId = readStringProperty(details, 'documentId');
+    const documentVersionId = readStringProperty(details, 'documentVersionId');
+    const failureCode = readStringProperty(details, 'sideEffectCode');
+    if (phase !== 'afterCreate' && phase !== 'afterUpdate' && phase !== 'afterSave')
+        return null;
+    if (!documentId || !documentVersionId)
+        return null;
+    if (failureCode !== ErrorCodes.STORAGE && failureCode !== ErrorCodes.UNHANDLED)
+        return null;
+    return {
+        phase,
+        documentId,
+        documentVersionId,
+        sideEffectCode: failureCode,
+    };
+}
+/**
+ * Run a hook after its document version has committed, preserving rejection
+ * semantics while making the committed state machine-readable to hosts.
+ */
+export async function runCommittedDocumentHook(ctx, details, callback) {
+    try {
+        await callback();
+    }
+    catch (cause) {
+        const committedError = ERR_DOCUMENT_HOOK_COMMITTED({
+            message: `${DOCUMENT_HOOK_COMMITTED_MARKER} document write committed but ${details.phase} failed`,
+            cause,
+            captureStack: true,
+            details: { ...details, sideEffectCode: sideEffectCode(cause) },
+        });
+        try {
+            committedError.log(ctx.logger);
+        }
+        catch {
+            // Diagnostic logging cannot erase the machine-readable committed result.
+        }
+        throw committedError;
+    }
+}

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

@@ -10,6 +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 { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
 import { mergeLocaleData } from './merge-locale-data.js';
 import { persistExistingDocumentVersion } from './persistence.js';
@@ -133,7 +134,7 @@ export async function copyToLocale(ctx, params) {
             previousVersionId,
         });
         const documentVersionId = extractVersionId(writeResult.document);
-        await invokeHook(hooks?.afterUpdate, {
+        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId: params.documentId, documentVersionId }, () => invokeHook(hooks?.afterUpdate, {
             data: merged.data,
             originalData: targetFields,
             collectionPath,
@@ -143,7 +144,7 @@ export async function copyToLocale(ctx, params) {
             // touches it. Read it off the target envelope.
             path: targetRecord.path ?? '',
             copyToLocale: copyToLocaleMarker,
-        });
+        }));
         return {
             documentId: params.documentId,
             documentVersionId,

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

@@ -15,6 +15,7 @@ import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
 import { normalizeNumericFields } from '../normalize-numeric-fields.js';
 import { requireTreeAuditCapability } from './audit.js';
+import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
 import { persistInitialDocumentVersion } from './persistence.js';
 import { appendTreeRoot } from './tree.js';
@@ -101,13 +102,13 @@ export async function createDocument(ctx, params) {
                 ctx.logger.error({ err, documentId }, 'failed to auto-place new document in tree');
             }
         }
-        await invokeHook(hooks?.afterCreate, {
+        await runCommittedDocumentHook(ctx, { phase: 'afterCreate', documentId, documentVersionId }, () => invokeHook(hooks?.afterCreate, {
             data,
             collectionPath,
             documentId,
             documentVersionId,
             path: resolvedPath,
-        });
+        }));
         return { documentId, documentVersionId };
     });
 }

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

@@ -10,6 +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 { runCommittedDocumentHook } from './committed-hook.js';
 import { actorId, invokeHook } from './internals.js';
 import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
 /**
@@ -106,7 +107,11 @@ export async function deleteLocale(ctx, params) {
                 return deleted;
             },
         });
-        await invokeHook(hooks?.afterUpdate, {
+        await runCommittedDocumentHook(ctx, {
+            phase: 'afterUpdate',
+            documentId: params.documentId,
+            documentVersionId: result.newVersionId,
+        }, () => invokeHook(hooks?.afterUpdate, {
             data: originalData,
             originalData,
             collectionPath,
@@ -116,7 +121,7 @@ export async function deleteLocale(ctx, params) {
             // never touches it. Read it off the target envelope.
             path: targetRecord.path ?? '',
             deleteLocale: deleteLocaleMarker,
-        });
+        }));
         return {
             documentId: params.documentId,
             documentVersionId: result.newVersionId,

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

@@ -12,6 +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 { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, isPathConflictError, maybeAppendOrderKey, rethrowPathConflict, stripMetaIdsInPlace, } from './internals.js';
 import { persistInitialDocumentVersion } from './persistence.js';
 /**
@@ -191,14 +192,18 @@ export async function duplicateDocument(ctx, params) {
         const newDocumentId = extractDocumentId(result.document);
         const newDocumentVersionId = extractVersionId(result.document);
         // 8. afterCreate hook with duplicate marker.
-        await invokeHook(hooks?.afterCreate, {
+        await runCommittedDocumentHook(ctx, {
+            phase: 'afterCreate',
+            documentId: newDocumentId,
+            documentVersionId: newDocumentVersionId,
+        }, () => invokeHook(hooks?.afterCreate, {
             data: clonedFields,
             collectionPath,
             documentId: newDocumentId,
             documentVersionId: newDocumentVersionId,
             path: finalPath,
             duplicate: duplicateMarker,
-        });
+        }));
         return {
             documentId: newDocumentId,
             documentVersionId: newDocumentVersionId,

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

@@ -22,6 +22,7 @@
  * One module per operation; shared helpers live in `internals.ts` (not
  * re-exported here — the public surface is exactly this barrel).
  */
+export { getDocumentHookCommittedDetails } from './committed-hook.js';
 export { copyToLocale } from './copy-to-locale.js';
 export { createDocument } from './create.js';
 export { deleteDocument } from './delete.js';
@@ -33,6 +34,7 @@ export { changeDocumentStatus, unpublishDocument } from './status.js';
 export { updateDocumentSystemFields } from './system-fields.js';
 export { placeTreeNode, promoteChildrenAndRemove, removeFromTree } from './tree.js';
 export { updateDocument, updateDocumentWithPatches } from './update.js';
+export type { DocumentHookCommittedDetails, DocumentHookCommittedPhase, DocumentHookSideEffectCode, } from './committed-hook.js';
 export type { DocumentLifecycleContext } from './context.js';
 export type { CopyToLocaleResult } from './copy-to-locale.js';
 export type { CreateDocumentResult } from './create.js';

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

@@ -22,6 +22,7 @@
  * One module per operation; shared helpers live in `internals.ts` (not
  * re-exported here — the public surface is exactly this barrel).
  */
+export { getDocumentHookCommittedDetails } from './committed-hook.js';
 export { copyToLocale } from './copy-to-locale.js';
 export { createDocument } from './create.js';
 export { deleteDocument } from './delete.js';

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

@@ -10,6 +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 { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook } from './internals.js';
 import { persistExistingDocumentVersion } from './persistence.js';
 /**
@@ -142,7 +143,7 @@ export async function restoreDocumentVersion(ctx, params) {
         const documentVersionId = extractVersionId(result.document);
         // 7. afterUpdate. Restore is path-sticky: the canonical path comes
         //    from the current version's envelope (originalData), not the source.
-        await invokeHook(hooks?.afterUpdate, {
+        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId }, () => invokeHook(hooks?.afterUpdate, {
             data: sourceFields,
             originalData,
             collectionPath,
@@ -150,7 +151,7 @@ export async function restoreDocumentVersion(ctx, params) {
             documentVersionId,
             path: originalData.path ?? '',
             restore: restoreContext,
-        });
+        }));
         return {
             documentId,
             documentVersionId,

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

@@ -14,6 +14,7 @@ import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
 import { normalizeNumericFields } from '../normalize-numeric-fields.js';
+import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
 import { persistExistingDocumentVersion } from './persistence.js';
 import { selfHealTreePlacement } from './tree.js';
@@ -92,14 +93,14 @@ export async function updateDocument(ctx, params) {
         // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any
         // save re-trees a stray (system step, best-effort, no-op when placed).
         await selfHealTreePlacement(ctx, documentId);
-        await invokeHook(hooks?.afterUpdate, {
+        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId }, () => invokeHook(hooks?.afterUpdate, {
             data,
             originalData,
             collectionPath,
             documentId,
             documentVersionId,
             path: pathForCommand ?? originalData.path,
-        });
+        }));
         return { documentId, documentVersionId };
     });
 }
@@ -206,14 +207,14 @@ export async function updateDocumentWithPatches(ctx, params) {
         // save re-trees a stray (system step, best-effort, no-op when placed).
         await selfHealTreePlacement(ctx, documentId);
         // 7. afterUpdate hook.
-        await invokeHook(hooks?.afterUpdate, {
+        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId }, () => invokeHook(hooks?.afterUpdate, {
             data: nextData,
             originalData,
             collectionPath,
             documentId,
             documentVersionId,
             path: pathForCommand ?? originalData.path,
-        });
+        }));
         return { documentId, documentVersionId };
     });
 }

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

@@ -335,6 +335,36 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('classifies an afterCreate failure as post-commit and retains committed ids', async () => {
+            const afterCreate = vi.fn().mockRejectedValue(new Error('cache unavailable'));
+            const { db, createDocumentVersion } = createMockDb();
+            const definition = { ...minimalCollection, hooks: { afterCreate } };
+            await expect(createDocument(buildCtx(db, definition), { data: { title: 'X' } })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterCreate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-1',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
+        it('preserves committed classification when diagnostic logging also fails', async () => {
+            const afterCreate = vi.fn().mockRejectedValue(new Error('cache unavailable'));
+            const { db } = createMockDb();
+            const definition = { ...minimalCollection, hooks: { afterCreate } };
+            const ctx = buildCtx(db, definition);
+            ctx.logger = {
+                ...noopLogger,
+                log: vi.fn(() => {
+                    throw new Error('logger failed');
+                }),
+            };
+            await expect(createDocument(ctx, { data: { title: 'X' } })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+            });
+        });
         it('afterCreate receives the resolved canonical path', async () => {
             const afterCreate = vi.fn();
             const { db } = createMockDb();
@@ -591,6 +621,25 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('classifies an afterUpdate failure as post-commit and retains committed ids', async () => {
+            const afterUpdate = vi.fn().mockRejectedValue(new Error('search unavailable'));
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({ fields: { title: 'Old' } });
+            const definition = { ...minimalCollection, hooks: { afterUpdate } };
+            await expect(updateDocument(buildCtx(db, definition), {
+                documentId: 'doc-1',
+                data: { title: 'New' },
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-1',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('afterUpdate carries the sticky path forward when none is supplied', async () => {
             const afterUpdate = vi.fn();
             const { db, getDocumentById } = createMockDb();
@@ -832,6 +881,31 @@ describe('Document lifecycle service', () => {
                 patches: [],
             })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.NOT_FOUND);
         });
+        it('classifies a post-patch afterUpdate failure without replaying the version write', async () => {
+            const afterUpdate = vi
+                .fn()
+                .mockRejectedValue(Object.assign(new Error('storage unavailable'), { code: ErrorCodes.STORAGE }));
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'previous-version',
+                fields: { title: 'Old' },
+            });
+            const definition = { ...minimalCollection, hooks: { afterUpdate } };
+            await expect(updateDocumentWithPatches(buildCtx(db, definition), {
+                documentId: 'doc-1',
+                documentVersionId: 'previous-version',
+                patches: [{ kind: 'field.set', path: 'title', value: 'New' }],
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-1',
+                    sideEffectCode: ErrorCodes.STORAGE,
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('throws ERR_CONFLICT on version mismatch', async () => {
             const { db, getDocumentById } = createMockDb();
             getDocumentById.mockResolvedValue({
@@ -1069,6 +1143,30 @@ describe('Document lifecycle service', () => {
             });
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({ action: 'document.publish.schedule.suspended' }));
         });
+        it('classifies a delete-locale afterUpdate failure after the new version commits', async () => {
+            const { db, deleteDocumentLocale, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'current-path',
+                _availableVersionLocales: ['en', 'fr'],
+                fields: { title: 'Bonjour' },
+            });
+            const definition = {
+                ...minimalCollection,
+                hooks: { afterUpdate: vi.fn().mockRejectedValue(new Error('search unavailable')) },
+            };
+            await expect(deleteLocale(buildCtx(db, definition), { documentId: 'doc-1', locale: 'fr' })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-2',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(deleteDocumentLocale).toHaveBeenCalledOnce();
+        });
         it('cancels an active schedule as an effect of an ordinary status transition', async () => {
             const { db, getCurrentVersionMetadata, cancelPublishSchedule, auditAppend } = createMockDb();
             getCurrentVersionMetadata.mockResolvedValue(metadataRow);
@@ -1947,6 +2045,26 @@ describe('Document lifecycle service', () => {
                 restore: { sourceVersionId },
             }));
         });
+        it('classifies a restore afterUpdate failure after the restored version commits', async () => {
+            const { db, sourceVersionId, createDocumentVersion } = setupRestore();
+            const definition = {
+                ...minimalCollection,
+                hooks: { afterUpdate: vi.fn().mockRejectedValue(new Error('search unavailable')) },
+            };
+            await expect(restoreDocumentVersion(buildCtx(db, definition), {
+                documentId: 'doc-1',
+                sourceVersionId,
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-restored',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('throws ERR_FORBIDDEN when actor lacks collections.<path>.update', async () => {
             const { db, sourceVersionId } = setupRestore();
             const ctx = buildCtx(db);
@@ -2246,6 +2364,24 @@ describe('Document lifecycle service', () => {
             expect(typeof afterCtx.path).toBe('string');
             expect(afterCtx.path).toBe(writtenPath);
         });
+        it('classifies a duplicate afterCreate failure with the committed document ids', async () => {
+            const withHooks = {
+                ...localizedCollection,
+                hooks: { afterCreate: vi.fn().mockRejectedValue(new Error('search unavailable')) },
+            };
+            const mocks = createMockDb();
+            setupSource(mocks);
+            await expect(duplicateDocument(buildCtx(mocks.db, withHooks), { sourceDocumentId: 'doc-source' })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterCreate',
+                    documentId: 'doc-new',
+                    documentVersionId: 'ver-new',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(mocks.createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('enforces collections.<path>.create — rejects an admin actor missing the ability', async () => {
             const mocks = createMockDb();
             setupSource(mocks);
@@ -2537,6 +2673,28 @@ describe('Document lifecycle service', () => {
             // Sticky path read off the target-locale envelope.
             expect(afterUpdate.mock.calls[0]?.[0].path).toBe('hello');
         });
+        it('classifies a copy-to-locale afterUpdate failure after the version commits', async () => {
+            const withHooks = {
+                ...mixedCollection,
+                hooks: { afterUpdate: vi.fn().mockRejectedValue(new Error('search unavailable')) },
+            };
+            const { mocks } = setupSourceTarget();
+            await expect(copyToLocale(buildCtx(mocks.db, withHooks), {
+                documentId: 'doc-1',
+                sourceLocale: 'en',
+                targetLocale: 'fr',
+                overwrite: false,
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: {
+                    phase: 'afterUpdate',
+                    documentId: 'doc-1',
+                    documentVersionId: 'ver-new',
+                    sideEffectCode: ErrorCodes.UNHANDLED,
+                },
+            });
+            expect(mocks.createDocumentVersion).toHaveBeenCalledOnce();
+        });
         it('enforces collections.<path>.update — rejects an admin actor missing the ability', async () => {
             const { mocks } = setupSourceTarget();
             const ctx = buildCtx(mocks.db, mixedCollection);

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

@@ -8,6 +8,7 @@
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { DbErrorCodes, ERR_CONFLICT, ERR_VALIDATION } from '../../lib/errors.js';
+import { runCommittedDocumentHook } from '../document-lifecycle/committed-hook.js';
 import { extractDocumentId, extractVersionId } from '../document-lifecycle/internals.js';
 /**
  * Assert the kind-aware singleton update ability without touching storage.
@@ -104,7 +105,11 @@ export async function commitSingletonSave(params) {
             },
         };
     });
-    await invokeSingletonHook(hooks?.afterSave, committed.afterSaveContext);
+    await runCommittedDocumentHook(ctx, {
+        phase: 'afterSave',
+        documentId: committed.documentId,
+        documentVersionId: committed.documentVersionId,
+    }, () => invokeSingletonHook(hooks?.afterSave, committed.afterSaveContext));
     return {
         documentId: committed.documentId,
         documentVersionId: committed.documentVersionId,

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

@@ -7,7 +7,7 @@
  */
 import { AdminAuth, createRequestContext } from '@byline/auth';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { DbErrorCodes } from '../lib/errors.js';
+import { DbErrorCodes, ErrorCodes } from '../lib/errors.js';
 import { copySingletonToLocale, resolveSingletonDocumentId, restoreSingletonVersion, updateSingleton, } from './singleton-lifecycle/index.js';
 const noopLogger = {
     log: vi.fn(),
@@ -334,7 +334,15 @@ describe('singleton lifecycle service', () => {
                 },
             },
         });
-        await expect(updateSingleton(harness.ctx, { data: { title: 'Committed' } })).rejects.toThrow('notification failed');
+        await expect(updateSingleton(harness.ctx, { data: { title: 'Committed' } })).rejects.toMatchObject({
+            code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+            details: {
+                phase: 'afterSave',
+                documentId: 'doc-1',
+                documentVersionId: 'ver-1',
+                sideEffectCode: ErrorCodes.UNHANDLED,
+            },
+        });
         expect(harness.committedTransactions()).toBe(1);
         expect(harness.mappedDocumentId()).toBe('doc-1');
         expect(harness.currentVersion()?.document_version_id).toBe('ver-1');

package/dist/storage/document-version-parent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 type DocumentVersionParentConflictReason = 'missing' | 'stale';
+export interface DocumentVersionParentAssertion {
+    documentId: string;
+    locale?: string;
+    previousVersionId?: string;
+    currentVersionId: string | null;
+}
+/**
+ * Protect immutable-version carry-forward from an absent or stale parent.
+ * Callers must obtain `currentVersionId` while holding the logical document's
+ * write lock; this helper owns only the adapter-independent invariant.
+ */
+export declare function assertDocumentVersionParent(params: DocumentVersionParentAssertion): void;

package/dist/storage/document-version-parent.js

@@ -0,0 +1,34 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { ERR_CONFLICT } from '../lib/errors.js';
+/**
+ * Protect immutable-version carry-forward from an absent or stale parent.
+ * Callers must obtain `currentVersionId` while holding the logical document's
+ * write lock; this helper owns only the adapter-independent invariant.
+ */
+export function assertDocumentVersionParent(params) {
+    const localeScopedWrite = params.locale != null && params.locale !== 'all';
+    const reason = localeScopedWrite && params.currentVersionId != null && params.previousVersionId == null
+        ? 'missing'
+        : params.previousVersionId != null && params.previousVersionId !== params.currentVersionId
+            ? 'stale'
+            : null;
+    if (reason == null)
+        return;
+    throw ERR_CONFLICT({
+        message: reason === 'missing'
+            ? 'previous document version is required for a locale-scoped write'
+            : 'previous document version is stale',
+        details: {
+            reason,
+            documentId: params.documentId,
+            previousVersionId: params.previousVersionId ?? null,
+            currentVersionId: params.currentVersionId,
+        },
+    });
+}

package/dist/storage/document-version-parent.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/storage/document-version-parent.test.node.js

@@ -0,0 +1,60 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { ErrorCodes } from '../lib/errors.js';
+import { assertDocumentVersionParent } from './document-version-parent.js';
+describe('assertDocumentVersionParent', () => {
+    it.each([
+        { label: 'the first version', locale: 'en', currentVersionId: null },
+        { label: "an existing locale: 'all' write", locale: 'all', currentVersionId: 'ver-current' },
+        { label: 'an existing locale-less full-tree write', currentVersionId: 'ver-current' },
+    ])('allows an omitted parent for $label', ({ locale, currentVersionId }) => {
+        expect(() => assertDocumentVersionParent({ documentId: 'doc-1', locale, currentVersionId })).not.toThrow();
+    });
+    it('allows the current parent for a locale-scoped write', () => {
+        expect(() => assertDocumentVersionParent({
+            documentId: 'doc-1',
+            locale: 'fr',
+            previousVersionId: 'ver-current',
+            currentVersionId: 'ver-current',
+        })).not.toThrow();
+    });
+    it('classifies an omitted locale-scoped parent as missing', () => {
+        expect(() => assertDocumentVersionParent({
+            documentId: 'doc-1',
+            locale: 'fr',
+            currentVersionId: 'ver-current',
+        })).toThrowError(expect.objectContaining({
+            code: ErrorCodes.CONFLICT,
+            message: 'previous document version is required for a locale-scoped write',
+            details: {
+                reason: 'missing',
+                documentId: 'doc-1',
+                previousVersionId: null,
+                currentVersionId: 'ver-current',
+            },
+        }));
+    });
+    it.each(['fr', 'all', undefined])('classifies a mismatched parent as stale for locale %s', (locale) => {
+        expect(() => assertDocumentVersionParent({
+            documentId: 'doc-1',
+            locale,
+            previousVersionId: 'ver-stale',
+            currentVersionId: 'ver-current',
+        })).toThrowError(expect.objectContaining({
+            code: ErrorCodes.CONFLICT,
+            message: 'previous document version is stale',
+            details: {
+                reason: 'stale',
+                documentId: 'doc-1',
+                previousVersionId: 'ver-stale',
+                currentVersionId: 'ver-current',
+            },
+        }));
+    });
+});

package/dist/storage/index.d.ts

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 export { fingerprintCollection } from './collection-fingerprint.js';
+export { assertDocumentVersionParent, type DocumentVersionParentAssertion, type DocumentVersionParentConflictReason, } from './document-version-parent.js';
 export { ALL_STORE_TYPES, type FieldStoreKind, type FieldStoreMapping, fieldTypeToStore, fieldTypeToStoreType, type StoreType, } from './field-store-map.js';
 export { flattenFieldSetData } from './storage-flatten.js';
 export { extractFlattenedFieldValue, type RestoreResult, restoreFieldSetData, } from './storage-restore.js';

package/dist/storage/index.js

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 export { fingerprintCollection } from './collection-fingerprint.js';
+export { assertDocumentVersionParent, } from './document-version-parent.js';
 export { ALL_STORE_TYPES, fieldTypeToStore, fieldTypeToStoreType, } from './field-store-map.js';
 export { flattenFieldSetData } from './storage-flatten.js';
 export { extractFlattenedFieldValue, restoreFieldSetData, } from './storage-restore.js';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.18.0",
+  "version": "4.19.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -87,7 +87,7 @@
     "sharp": "^0.35.4",
     "uuid": "^14.0.2",
     "zod": "^4.4.3",
-    "@byline/auth": "4.18.0"
+    "@byline/auth": "4.19.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.10",