@byline/core 3.20.4 → 4.0.0

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

@@ -13,7 +13,9 @@ 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 { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, selfHealTreePlacement, } from './internals.js';
+import { normalizeNumericFields } from '../normalize-numeric-fields.js';
+import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
+import { selfHealTreePlacement } from './tree.js';
 /**
  * Update a document via full replacement (PUT semantics).
  *
@@ -22,8 +24,8 @@ import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invok
  *
  * Flow:
  *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`
+ *   2. Normalize date and numeric fields
+ *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`, then normalize numerics again
  *   4. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   5. `hooks.afterUpdate({ data, originalData, collectionPath, documentId, documentVersionId })`
  */
@@ -43,7 +45,9 @@ export async function updateDocument(ctx, params) {
         });
         const originalData = latest ?? {};
         normaliseDateFields(data);
+        normalizeNumericFields(definition.fields, data);
         await invokeHook(hooks?.beforeUpdate, { data, originalData, collectionPath });
+        normalizeNumericFields(definition.fields, data);
         // Counter fields are immutable: carry their values forward from the
         // previous version rather than trusting whatever (or nothing) the
         // caller sent. Lazy-allocates when a counter was added to the
@@ -111,8 +115,8 @@ export async function updateDocument(ctx, params) {
  *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
  *   2. Optimistic concurrency check on `documentVersionId`
  *   3. `applyPatches(definition, originalData, patches)` → `nextData`
- *   4. `normaliseDateFields(nextData)`
- *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`
+ *   4. Normalize date and numeric fields
+ *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`, then normalize numerics again
  *   6. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   7. `hooks.afterUpdate({ data: nextData, originalData, collectionPath, documentId, documentVersionId })`
  *
@@ -160,8 +164,10 @@ export async function updateDocumentWithPatches(ctx, params) {
         const nextData = patchedDocument;
         // 4. Normalise dates.
         normaliseDateFields(nextData);
+        normalizeNumericFields(definition.fields, nextData);
         // 5. beforeUpdate hook.
         await invokeHook(hooks?.beforeUpdate, { data: nextData, originalData, collectionPath });
+        normalizeNumericFields(definition.fields, nextData);
         // 5b. Carry counter values forward from the previous version (or
         // lazy-allocate if the previous version is missing a value). See
         // updateDocument for the rationale — patch-based updates are

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

@@ -24,6 +24,14 @@ const minimalCollection = {
         ],
     },
 };
+const numericCollection = {
+    ...minimalCollection,
+    fields: [
+        { name: 'quantity', type: 'integer' },
+        { name: 'score', type: 'float' },
+        { name: 'price', type: 'decimal' },
+    ],
+};
 /** Build a mock IDbAdapter. Returns the adapter plus individual mock fns. */
 function createMockDb() {
     const createDocumentVersion = vi.fn().mockResolvedValue({
@@ -34,6 +42,7 @@ function createMockDb() {
     const archivePublishedVersions = vi.fn().mockResolvedValue(0);
     const softDeleteDocument = vi.fn().mockResolvedValue(1);
     const getDocumentById = vi.fn().mockResolvedValue(null);
+    const getDocumentSystemFieldsForUpdate = vi.fn().mockResolvedValue(null);
     const getCurrentVersionMetadata = vi.fn().mockResolvedValue(null);
     const getCurrentPath = vi.fn().mockResolvedValue('current-path');
     // Audit capability (docs/06-auth-and-security/02-auditability.md — W2). `withTransaction` is a passthrough
@@ -59,6 +68,16 @@ function createMockDb() {
                 setOrderKey: vi.fn(),
                 placeTreeNode: vi.fn(),
                 removeFromTree: vi.fn(),
+                promoteChildrenAndRemoveFromTree: vi.fn(async () => ({
+                    removed: {
+                        changed: false,
+                        before: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        after: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        beforeSiblingDocumentIds: [],
+                        beforeSubtreeDocumentIds: [],
+                    },
+                    promoted: [],
+                })),
             },
             counters: {
                 ensureCounterGroup: vi.fn(),
@@ -75,6 +94,7 @@ function createMockDb() {
                 getCollectionById: vi.fn(),
             },
             documents: {
+                getDocumentSystemFieldsForUpdate,
                 getDocumentById,
                 getCurrentVersionMetadata,
                 getCurrentPath,
@@ -95,6 +115,16 @@ function createMockDb() {
                 getTreeParent: vi.fn(),
                 getTreeSubtree: vi.fn(),
             },
+            audit: {
+                getDocumentAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+                findAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+            },
         },
     };
     return {
@@ -104,6 +134,7 @@ function createMockDb() {
         archivePublishedVersions,
         softDeleteDocument,
         getDocumentById,
+        getDocumentSystemFieldsForUpdate,
         getCurrentVersionMetadata,
         getCurrentPath,
         auditAppend,
@@ -235,6 +266,23 @@ describe('Document lifecycle service', () => {
             const persistedData = createDocumentVersion.mock.calls[0]?.[0].documentData;
             expect(persistedData.title).toBe('Mutated');
         });
+        it('normalizes numeric values before and after beforeCreate', async () => {
+            const { db, createDocumentVersion } = createMockDb();
+            const beforeCreate = vi.fn(({ data }) => {
+                expect(data).toMatchObject({ quantity: 2, score: 1.5, price: '10.00' });
+                data.quantity = '3';
+                data.price = 12.5;
+            });
+            const definition = { ...numericCollection, hooks: { beforeCreate } };
+            await createDocument(buildCtx(db, definition), {
+                data: { quantity: '2', score: '1.5', price: ' 10.00 ' },
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].documentData).toMatchObject({
+                quantity: 3,
+                score: 1.5,
+                price: '12.5',
+            });
+        });
         it('derives path from useAsPath source field via the slugifier', async () => {
             const { db, createDocumentVersion } = createMockDb();
             const definition = { ...minimalCollection, useAsPath: 'title' };
@@ -378,6 +426,24 @@ describe('Document lifecycle service', () => {
             }));
             expect(createDocumentVersion).toHaveBeenCalledOnce();
         });
+        it('normalizes numeric values before and after beforeUpdate', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({ fields: { quantity: 1, score: 1, price: '1.0' } });
+            const beforeUpdate = vi.fn(({ data }) => {
+                expect(data.score).toBe(25);
+                data.score = '3.5';
+            });
+            const definition = { ...numericCollection, hooks: { beforeUpdate } };
+            await updateDocument(buildCtx(db, definition), {
+                documentId: 'doc-1',
+                data: { quantity: '2', score: '2.5e1', price: 4.25 },
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].documentData).toEqual({
+                quantity: 2,
+                score: 3.5,
+                price: '4.25',
+            });
+        });
         it('afterUpdate receives documentId and documentVersionId', async () => {
             const afterUpdate = vi.fn();
             const { db, getDocumentById } = createMockDb();
@@ -670,6 +736,29 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('normalizes patched and hook-produced numeric values before persistence', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                fields: { quantity: 1, score: 1, price: '1.00' },
+            });
+            const beforeUpdate = vi.fn(({ data }) => {
+                expect(data.quantity).toBe(7);
+                data.price = ' 8.500 ';
+            });
+            const definition = { ...numericCollection, hooks: { beforeUpdate } };
+            await updateDocumentWithPatches(buildCtx(db, definition), {
+                documentId: 'doc-1',
+                patches: [
+                    { kind: 'field.set', path: 'quantity', value: '7.0' },
+                    { kind: 'field.set', path: 'score', value: '2.75' },
+                ],
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].documentData).toEqual({
+                quantity: 7,
+                score: 2.75,
+                price: '8.500',
+            });
+        });
     });
     // -----------------------------------------------------------------------
     // changeDocumentStatus
@@ -824,6 +913,38 @@ describe('Document lifecycle service', () => {
             expect(result.archivedCount).toBe(1);
             expect(archivePublishedVersions).toHaveBeenCalledWith({ document_id: 'doc-1' });
         });
+        it('records an atomic published to archived status audit when versions change', async () => {
+            const { db, archivePublishedVersions, auditAppend, withTransaction } = createMockDb();
+            archivePublishedVersions.mockResolvedValue(2);
+            await unpublishDocument(buildCtx(db), { documentId: 'doc-1' });
+            expect(withTransaction).toHaveBeenCalledOnce();
+            expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
+                documentId: 'doc-1',
+                collectionId: 'col-1',
+                actorId: TEST_ACTOR_ID,
+                actorRealm: 'admin',
+                action: 'document.status.changed',
+                field: 'status',
+                before: 'published',
+                after: 'archived',
+            }));
+        });
+        it('does not record an audit row when no published version changes', async () => {
+            const { db, archivePublishedVersions, auditAppend } = createMockDb();
+            archivePublishedVersions.mockResolvedValue(0);
+            await unpublishDocument(buildCtx(db), { documentId: 'doc-1' });
+            expect(auditAppend).not.toHaveBeenCalled();
+        });
+        it('does not run afterUnpublish when the atomic audit unit fails', async () => {
+            const afterUnpublish = vi.fn();
+            const { db, archivePublishedVersions, auditAppend } = createMockDb();
+            archivePublishedVersions.mockResolvedValue(1);
+            auditAppend.mockRejectedValue(new Error('audit failed'));
+            await expect(unpublishDocument(buildCtx(db, { ...minimalCollection, hooks: { afterUnpublish } }), {
+                documentId: 'doc-1',
+            })).rejects.toThrow('audit failed');
+            expect(afterUnpublish).not.toHaveBeenCalled();
+        });
         it('invokes beforeUnpublish and afterUnpublish hooks', async () => {
             const callOrder = [];
             const hooks = {
@@ -927,6 +1048,23 @@ describe('Document lifecycle service', () => {
                 action: 'document.deleted',
             }));
         });
+        it('rejects a beforeDelete failure without soft-deleting the document', async () => {
+            const beforeDelete = vi.fn(async () => {
+                throw new Error('pre-commit hook failed');
+            });
+            const afterDelete = vi.fn();
+            const { db, getDocumentById, softDeleteDocument } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'doc-to-delete',
+                fields: {},
+            });
+            const definition = { ...minimalCollection, hooks: { beforeDelete, afterDelete } };
+            await expect(deleteDocument(buildCtx(db, definition), { documentId: 'doc-1' })).rejects.toThrow('pre-commit hook failed');
+            expect(softDeleteDocument).not.toHaveBeenCalled();
+            expect(afterDelete).not.toHaveBeenCalled();
+        });
         it('cleans up stored files for upload fields at any nesting depth', async () => {
             const { db, getDocumentById } = createMockDb();
             const upload = { mimeTypes: ['application/pdf'], maxFileSize: 1024 };
@@ -979,28 +1117,108 @@ describe('Document lifecycle service', () => {
                 'files/b.pdf',
             ]);
         });
+        it('returns only allowlisted failures and keeps raw details in internal logs', async () => {
+            const { db, getDocumentById } = createMockDb();
+            const upload = { mimeTypes: ['application/pdf'], maxFileSize: 1024 };
+            const hookError = Object.assign(new Error('hook leaked private/hooks/search.ts'), {
+                code: 'ERR_SEARCH',
+            });
+            const definition = {
+                ...minimalCollection,
+                fields: [{ name: 'file', label: 'File', type: 'file', upload }],
+                hooks: {
+                    afterDelete: async () => {
+                        throw hookError;
+                    },
+                },
+            };
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'doc-to-delete',
+                fields: {
+                    file: {
+                        storagePath: 'private/original.pdf',
+                        variants: [
+                            { storagePath: 'private/preview.pdf' },
+                            { storagePath: 'private/thumbnail.pdf' },
+                        ],
+                    },
+                },
+            });
+            const storageDelete = vi.fn(async (storagePath) => {
+                if (storagePath === 'private/original.pdf') {
+                    throw Object.assign(new Error('storage unavailable'), { code: ErrorCodes.STORAGE });
+                }
+                if (storagePath === 'private/thumbnail.pdf')
+                    throw new Error('cleanup failed');
+            });
+            const ctx = {
+                ...buildCtx(db, definition),
+                storage: { delete: storageDelete },
+                logger: { ...noopLogger, error: vi.fn() },
+            };
+            const result = await deleteDocument(ctx, { documentId: 'doc-1' });
+            expect(storageDelete.mock.calls.map((call) => call[0])).toEqual([
+                'private/original.pdf',
+                'private/preview.pdf',
+                'private/thumbnail.pdf',
+            ]);
+            expect(result).toEqual({
+                deletedVersionCount: 1,
+                outcome: 'committed-with-side-effect-failures',
+                sideEffectFailures: [
+                    { phase: 'storageCleanup', code: 'ERR_STORAGE' },
+                    { phase: 'storageCleanup', code: 'ERR_UNHANDLED' },
+                    { phase: 'afterDelete', code: 'ERR_UNHANDLED' },
+                ],
+            });
+            const serializedResult = JSON.stringify(result);
+            expect(serializedResult).not.toContain('storage unavailable');
+            expect(serializedResult).not.toContain('cleanup failed');
+            expect(serializedResult).not.toContain('hook leaked');
+            expect(serializedResult).not.toContain('private/');
+            expect(serializedResult).not.toContain('ERR_SEARCH');
+            expect(ctx.logger.error).toHaveBeenCalledWith(expect.objectContaining({
+                err: expect.objectContaining({ message: 'storage unavailable' }),
+                documentId: 'doc-1',
+                storagePath: 'private/original.pdf',
+            }), 'failed to delete storage file');
+            expect(ctx.logger.error).toHaveBeenCalledWith(expect.objectContaining({
+                err: expect.objectContaining({ message: 'cleanup failed' }),
+                documentId: 'doc-1',
+                storagePath: 'private/thumbnail.pdf',
+            }), 'failed to delete storage file');
+            expect(ctx.logger.error).toHaveBeenCalledWith(expect.objectContaining({ err: hookError, documentId: 'doc-1' }), 'afterDelete hook failed after document delete');
+        });
     });
     // -----------------------------------------------------------------------
     // updateDocumentSystemFields (audited, non-versioned)
     // -----------------------------------------------------------------------
     describe('updateDocumentSystemFields', () => {
-        function setupDoc(getDocumentById, overrides) {
-            getDocumentById.mockResolvedValue({
-                document_version_id: 'ver-1',
-                document_id: 'doc-1',
+        function setupDoc(getDocumentSystemFieldsForUpdate, overrides) {
+            getDocumentSystemFieldsForUpdate.mockResolvedValue({
                 path: 'old-slug',
                 source_locale: 'en',
                 availableLocales: ['en'],
-                fields: {},
                 ...overrides,
             });
         }
         it('records document.path.changed when the path actually changes', async () => {
-            const { db, getDocumentById, auditAppend, withTransaction } = createMockDb();
-            setupDoc(getDocumentById);
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend, withTransaction } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
             const ctx = buildCtx(db);
-            await updateDocumentSystemFields(ctx, { documentId: 'doc-1', path: 'new-slug' });
+            const result = await updateDocumentSystemFields(ctx, {
+                documentId: 'doc-1',
+                path: 'new-slug',
+            });
             expect(withTransaction).toHaveBeenCalledOnce();
+            expect(result).toMatchObject({
+                changed: true,
+                pathChanged: true,
+                availableLocalesChanged: false,
+                path: 'new-slug',
+            });
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
                 action: 'document.path.changed',
                 field: 'path',
@@ -1008,21 +1226,38 @@ describe('Document lifecycle service', () => {
                 after: 'new-slug',
             }));
         });
-        it('records no audit row when the path is unchanged', async () => {
-            const { db, getDocumentById, auditAppend } = createMockDb();
-            setupDoc(getDocumentById);
-            const ctx = buildCtx(db);
-            await updateDocumentSystemFields(ctx, { documentId: 'doc-1', path: 'old-slug' });
+        it('does not write, audit, or fire the hook when the path is unchanged', async () => {
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend, withTransaction } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
+            const afterSystemFieldsChange = vi.fn();
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange },
+            });
+            const result = await updateDocumentSystemFields(ctx, {
+                documentId: 'doc-1',
+                path: 'old-slug',
+            });
+            expect(result).toMatchObject({ changed: false, pathChanged: false });
+            expect(db.commands.documents.updateDocumentPath).not.toHaveBeenCalled();
+            expect(withTransaction).toHaveBeenCalledOnce();
             expect(auditAppend).not.toHaveBeenCalled();
+            expect(afterSystemFieldsChange).not.toHaveBeenCalled();
         });
         it('records document.locales.changed with before/after sets', async () => {
-            const { db, getDocumentById, auditAppend } = createMockDb();
-            setupDoc(getDocumentById);
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
             const ctx = buildCtx(db);
-            await updateDocumentSystemFields(ctx, {
+            const result = await updateDocumentSystemFields(ctx, {
                 documentId: 'doc-1',
                 availableLocales: ['en', 'fr'],
             });
+            expect(result).toMatchObject({
+                changed: true,
+                pathChanged: false,
+                availableLocalesChanged: true,
+                availableLocalesWritten: true,
+            });
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
                 action: 'document.locales.changed',
                 field: 'availableLocales',
@@ -1030,6 +1265,181 @@ describe('Document lifecycle service', () => {
                 after: ['en', 'fr'],
             }));
         });
+        it('treats reordered and duplicated locale values as a no-op set', async () => {
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend, withTransaction } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate, { availableLocales: ['en', 'fr'] });
+            const afterSystemFieldsChange = vi.fn();
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange },
+            });
+            const result = await updateDocumentSystemFields(ctx, {
+                documentId: 'doc-1',
+                availableLocales: ['fr', 'en', 'fr'],
+            });
+            expect(result).toMatchObject({ changed: false, availableLocalesChanged: false });
+            expect(db.commands.documents.setDocumentAvailableLocales).not.toHaveBeenCalled();
+            expect(withTransaction).toHaveBeenCalledOnce();
+            expect(auditAppend).not.toHaveBeenCalled();
+            expect(afterSystemFieldsChange).not.toHaveBeenCalled();
+        });
+        it('fires ordered hooks after commit with previous and current field snapshots', async () => {
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend, withTransaction } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
+            const order = [];
+            db.commands.documents.updateDocumentPath.mockImplementation(async () => {
+                order.push('path-write');
+            });
+            db.commands.documents.setDocumentAvailableLocales.mockImplementation(async () => {
+                order.push('locales-write');
+            });
+            auditAppend.mockImplementation(async () => {
+                order.push('audit');
+                return { id: 'audit-1' };
+            });
+            withTransaction.mockImplementation(async (fn) => {
+                order.push('transaction:start');
+                const value = await fn();
+                order.push('transaction:commit');
+                return value;
+            });
+            const firstHook = vi.fn(async () => {
+                order.push('hook:first');
+            });
+            const secondHook = vi.fn(async () => {
+                order.push('hook:second');
+            });
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange: [firstHook, secondHook] },
+            });
+            await updateDocumentSystemFields(ctx, {
+                documentId: 'doc-1',
+                path: 'new-slug',
+                availableLocales: ['fr', 'en', 'fr'],
+            });
+            expect(order).toEqual([
+                'transaction:start',
+                'path-write',
+                'audit',
+                'locales-write',
+                'audit',
+                'transaction:commit',
+                'hook:first',
+                'hook:second',
+            ]);
+            expect(firstHook).toHaveBeenCalledWith({
+                documentId: 'doc-1',
+                collectionPath: 'articles',
+                requested: { path: true, availableLocales: true },
+                changed: { path: true, availableLocales: true },
+                reconciliation: false,
+                previousPath: 'old-slug',
+                currentPath: 'new-slug',
+                previousAvailableLocales: ['en'],
+                currentAvailableLocales: ['fr', 'en'],
+            });
+        });
+        it('does not fire side-effect hooks when the audited transaction fails', async () => {
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
+            const afterSystemFieldsChange = vi.fn();
+            auditAppend.mockRejectedValue(new Error('audit failed'));
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange },
+            });
+            await expect(updateDocumentSystemFields(ctx, { documentId: 'doc-1', path: 'new-slug' })).rejects.toThrow('audit failed');
+            expect(db.commands.documents.updateDocumentPath).toHaveBeenCalledOnce();
+            expect(afterSystemFieldsChange).not.toHaveBeenCalled();
+        });
+        it('propagates an after-hook failure without folding it into the committed transaction', async () => {
+            const { db, getDocumentSystemFieldsForUpdate, withTransaction } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
+            let committed = false;
+            withTransaction.mockImplementation(async (fn) => {
+                const value = await fn();
+                committed = true;
+                return value;
+            });
+            const afterSystemFieldsChange = vi.fn(async () => {
+                expect(committed).toBe(true);
+                throw new Error('cache unavailable');
+            });
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange },
+            });
+            await expect(updateDocumentSystemFields(ctx, { documentId: 'doc-1', availableLocales: ['en', 'fr'] })).rejects.toThrow('cache unavailable');
+            expect(committed).toBe(true);
+            expect(db.commands.documents.setDocumentAvailableLocales).toHaveBeenCalledOnce();
+            expect(afterSystemFieldsChange).toHaveBeenCalledOnce();
+        });
+        it('re-runs reconciliation on an explicit no-op retry after a committed hook failure', async () => {
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
+            const afterSystemFieldsChange = vi
+                .fn()
+                .mockRejectedValueOnce(new Error('search unavailable'))
+                .mockResolvedValue(undefined);
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange },
+            });
+            await expect(updateDocumentSystemFields(ctx, { documentId: 'doc-1', path: 'new-slug' })).rejects.toThrow('search unavailable');
+            setupDoc(getDocumentSystemFieldsForUpdate, { path: 'new-slug' });
+            const retry = await updateDocumentSystemFields(ctx, {
+                documentId: 'doc-1',
+                path: 'new-slug',
+                reconcile: true,
+            });
+            expect(retry).toMatchObject({ changed: false, reconciliation: true });
+            expect(db.commands.documents.updateDocumentPath).toHaveBeenCalledOnce();
+            expect(auditAppend).toHaveBeenCalledOnce();
+            expect(afterSystemFieldsChange).toHaveBeenCalledTimes(2);
+            expect(afterSystemFieldsChange).toHaveBeenLastCalledWith(expect.objectContaining({
+                requested: { path: true, availableLocales: false },
+                changed: { path: false, availableLocales: false },
+                reconciliation: true,
+                previousPath: 'new-slug',
+                currentPath: 'new-slug',
+            }));
+        });
+        it('uses the locked transaction snapshot for audit and invalidation payloads', async () => {
+            const { db, getDocumentById, getDocumentSystemFieldsForUpdate, auditAppend } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                path: 'stale-path',
+                source_locale: 'en',
+                availableLocales: ['en'],
+            });
+            setupDoc(getDocumentSystemFieldsForUpdate, {
+                path: 'concurrent-path',
+                availableLocales: ['en', 'fr'],
+            });
+            const afterSystemFieldsChange = vi.fn();
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange },
+            });
+            await updateDocumentSystemFields(ctx, {
+                documentId: 'doc-1',
+                path: 'final-path',
+                availableLocales: ['de'],
+            });
+            expect(getDocumentById).not.toHaveBeenCalled();
+            expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({ field: 'path', before: 'concurrent-path', after: 'final-path' }));
+            expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
+                field: 'availableLocales',
+                before: ['en', 'fr'],
+                after: ['de'],
+            }));
+            expect(afterSystemFieldsChange).toHaveBeenCalledWith(expect.objectContaining({
+                previousPath: 'concurrent-path',
+                currentPath: 'final-path',
+                previousAvailableLocales: ['en', 'fr'],
+                currentAvailableLocales: ['de'],
+            }));
+        });
     });
     // -----------------------------------------------------------------------
     // restoreDocumentVersion

package/dist/services/document-read.d.ts

@@ -5,21 +5,29 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { CollectionDefinition, ReadContext } from '../@types/index.js';
+import type { CollectionDefinition, ReadContext, ReadMode } from '../@types/index.js';
 /**
  * Fire the `afterRead` hook for one reconstructed document.
  *
- * No-op when the collection has no hook. No-op when the document has
- * already been through `afterRead` in this `ReadContext` — enforces the
- * "once per document per logical request" rule that forecloses the
- * A→B→A infinite loop when hooks perform their own reads.
+ * No-op when the collection has no hook, when this exact materialized object
+ * completed the hook already. An active logical version fails closed with
+ * `ERR_READ_RECURSION`: even the same object may be only partially processed,
+ * so returning it cannot be proven safe. Fresh raw objects are always redacted
+ * once the active call completes. Failed hooks do not mark the object complete,
+ * and active state is cleared in `finally` so a later retry can proceed.
  *
  * The hook receives the raw storage-shape document (mutable) and the
- * shared `ReadContext` so it can thread the same context through any
+ * operation's authenticated context plus the shared `ReadContext`, so it can
+ * redact by actor and thread the same context through any
  * nested `client.collection(...).findById(id, { _readContext })` calls.
  */
 export declare function applyAfterRead(params: {
     doc: Record<string, any>;
     definition: CollectionDefinition;
     readContext: ReadContext;
+    requestContext: import('@byline/auth').RequestContext;
+    locale?: string;
+    readMode?: ReadMode;
+    projection?: readonly string[];
+    materialization?: string;
 }): Promise<void>;