@byline/core 3.21.0 → 4.1.0

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

@@ -42,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
@@ -67,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(),
@@ -83,6 +94,7 @@ function createMockDb() {
                 getCollectionById: vi.fn(),
             },
             documents: {
+                getDocumentSystemFieldsForUpdate,
                 getDocumentById,
                 getCurrentVersionMetadata,
                 getCurrentPath,
@@ -103,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 {
@@ -112,6 +134,7 @@ function createMockDb() {
         archivePublishedVersions,
         softDeleteDocument,
         getDocumentById,
+        getDocumentSystemFieldsForUpdate,
         getCurrentVersionMetadata,
         getCurrentPath,
         auditAppend,
@@ -890,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 = {
@@ -993,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 };
@@ -1045,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',
@@ -1074,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',
@@ -1096,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>;

package/dist/services/document-read.js

@@ -21,6 +21,8 @@
  * `beforeCreate` / `afterCreate` hooks.
  */
 import { normalizeCollectionHook, resolveHooks } from '../@types/index.js';
+import { resolveReadContextRoot } from '../auth/read-context-scope.js';
+import { ERR_READ_RECURSION } from '../lib/errors.js';
 async function invokeHook(hook, ctx) {
     const fns = normalizeCollectionHook(hook);
     for (const fn of fns) {
@@ -30,13 +32,16 @@ async function invokeHook(hook, ctx) {
 /**
  * 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 async function applyAfterRead(params) {
@@ -47,14 +52,47 @@ export async function applyAfterRead(params) {
     const docId = params.doc?.document_id;
     if (typeof docId !== 'string')
         return;
-    const key = `${params.definition.path}:${docId}`;
-    if (params.readContext.afterReadFired.has(key))
+    const versionId = typeof params.doc?.document_version_id === 'string'
+        ? params.doc.document_version_id
+        : `document:${docId}`;
+    const state = getAfterReadState(params.readContext);
+    if (state.processed.has(params.doc))
         return;
-    params.readContext.afterReadFired.add(key);
+    // ReadContext already scopes the operation; keeping identity out of this key
+    // prevents a nested caller from evading the guard with another context clone.
+    const activeKey = `${params.definition.path}:${versionId}`;
+    if (state.active.has(activeKey)) {
+        throw ERR_READ_RECURSION({
+            message: `afterRead recursion blocked for active version '${versionId}'`,
+            details: {
+                collectionPath: params.definition.path,
+                documentId: docId,
+                documentVersionId: versionId,
+            },
+        });
+    }
     const ctx = {
         doc: params.doc,
         collectionPath: params.definition.path,
+        requestContext: params.requestContext,
         readContext: params.readContext,
     };
-    await invokeHook(hook, ctx);
+    state.active.add(activeKey);
+    try {
+        await invokeHook(hook, ctx);
+        state.processed.add(params.doc);
+    }
+    finally {
+        state.active.delete(activeKey);
+    }
+}
+const afterReadStates = new WeakMap();
+function getAfterReadState(readContext) {
+    const root = resolveReadContextRoot(readContext);
+    const existing = afterReadStates.get(root);
+    if (existing)
+        return existing;
+    const state = { active: new Set(), processed: new WeakSet() };
+    afterReadStates.set(root, state);
+    return state;
 }