@byline/core 3.20.4 → 4.0.0

package/dist/config/routes.test.node.js

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeRootRelativeRedirect } from '../utils/root-relative-redirect.js';
+import { defineClientConfig, getClientConfig } from './config.js';
+import { resolveRoutes } from './routes.js';
+describe('resolveRoutes', () => {
+    it('returns canonical defaults', () => {
+        const routes = resolveRoutes();
+        expect(routes).toEqual({ admin: '/admin', api: '/api', signIn: '/sign-in' });
+        expect(Object.isFrozen(routes)).toBe(true);
+    });
+    it.each([
+        ['cms', '/cms'],
+        ['/cms', '/cms'],
+        ['/cms/', '/cms'],
+        ['///cms///', '/cms'],
+        ['/internal/cms/', '/internal/cms'],
+    ])('canonicalizes an admin route of %j', (admin, expected) => {
+        expect(resolveRoutes({ admin }).admin).toBe(expected);
+    });
+    it('falls back for empty route values', () => {
+        expect(resolveRoutes({ admin: '', api: '  ', signIn: '' })).toEqual({
+            admin: '/admin',
+            api: '/api',
+            signIn: '/sign-in',
+        });
+    });
+    it.each([
+        '/../cms',
+        '/cms?next=x',
+        '/cms#section',
+        '/cms\\users',
+        '/%63ms',
+    ])('rejects a non-segment admin route of %j', (admin) => {
+        expect(() => resolveRoutes({ admin })).toThrow(/routes\.admin/);
+    });
+    it('normalizes and validates the API route too', () => {
+        expect(resolveRoutes({ api: 'content-api/' }).api).toBe('/content-api');
+        expect(resolveRoutes({ api: '/internal/api' }).api).toBe('/internal/api');
+    });
+    it.each([
+        ['staff/login', '/staff/login'],
+        ['/staff/login/', '/staff/login'],
+        ['/staff//login/', '/staff/login'],
+    ])('canonicalizes a sign-in route of %j', (signIn, expected) => {
+        expect(resolveRoutes({ signIn }).signIn).toBe(expected);
+    });
+    it.each([
+        'https://evil.test/login',
+        '//evil.test/login',
+        '/staff/login?next=/cms',
+        '/staff/login#form',
+        '/staff\\login',
+        '/staff/%6cogin',
+        '/staff/../login',
+    ])('rejects an unsafe sign-in route of %j', (signIn) => {
+        expect(() => resolveRoutes({ signIn })).toThrow(/routes\.signIn/);
+    });
+    it('rejects conflicting admin and API segments', () => {
+        expect(() => resolveRoutes({ admin: '/internal', api: 'internal/' })).toThrow(/routes\.admin and routes\.api/);
+    });
+    it.each([
+        ['/internal', '/internal/api'],
+        ['/internal/admin', '/internal'],
+    ])('rejects overlapping admin and API trees %j and %j', (admin, api) => {
+        expect(() => resolveRoutes({ admin, api })).toThrow(/routes\.admin and routes\.api/);
+    });
+    it.each([
+        ['/cms', '/cms'],
+        ['/cms', '/cms/login'],
+        ['/cms', '/api/login'],
+        ['/internal/cms', '/internal'],
+    ])('rejects conflicting admin %j and sign-in %j paths', (admin, signIn) => {
+        expect(() => resolveRoutes({ admin, signIn })).toThrow(/routes\.signIn/);
+    });
+});
+describe('normalizeRootRelativeRedirect', () => {
+    it.each([
+        ['/cms', '/cms'],
+        ['/cms/account?tab=profile#name', '/cms/account?tab=profile#name'],
+        ['/cms/account?query=hello world', '/cms/account?query=hello%20world'],
+    ])('accepts and canonicalizes %j', (value, expected) => {
+        expect(normalizeRootRelativeRedirect(value)).toBe(expected);
+    });
+    it.each([
+        '',
+        ' /cms',
+        'https://evil.test',
+        '//evil.test',
+        '/\\evil.test',
+        '/cms\\account',
+        '/cms\naccount',
+        '/cms\u0085account',
+        '/cms/../account',
+        '/cms/./account',
+        '/%2F%2Fevil.test',
+        '/cms/%2e%2e/account',
+    ])('rejects %j', (value) => {
+        expect(normalizeRootRelativeRedirect(value)).toBeUndefined();
+    });
+});
+describe('route configuration boundary', () => {
+    it('stores and exposes resolved routes independently of partial input', () => {
+        const input = { admin: 'internal/cms/' };
+        const registered = defineClientConfig({
+            serverURL: 'https://example.test',
+            routes: input,
+            collections: [],
+            admin: [],
+            i18n: {
+                interface: { defaultLocale: 'en', locales: [] },
+                content: { defaultLocale: 'en', locales: [] },
+            },
+        });
+        input.admin = '/changed';
+        expect(registered.routes).toEqual({
+            admin: '/internal/cms',
+            api: '/api',
+            signIn: '/sign-in',
+        });
+        expect(getClientConfig().routes).toBe(registered.routes);
+        expect(Object.isFrozen(registered.routes)).toBe(true);
+    });
+    it('prevents post-registration route mutation', () => {
+        const { routes } = defineClientConfig({
+            serverURL: 'https://example.test',
+            routes: { admin: '/internal/cms' },
+            collections: [],
+            admin: [],
+            i18n: {
+                interface: { defaultLocale: 'en', locales: [] },
+                content: { defaultLocale: 'en', locales: [] },
+            },
+        });
+        expect(() => {
+            ;
+            routes.admin = '/changed';
+        }).toThrow(TypeError);
+        expect(getClientConfig().routes.admin).toBe('/internal/cms');
+    });
+    it('rejects unsafe routes during registration', () => {
+        expect(() => defineClientConfig({
+            serverURL: 'https://example.test',
+            routes: { admin: '/cms?next=/account' },
+            collections: [],
+            admin: [],
+            i18n: {
+                interface: { defaultLocale: 'en', locales: [] },
+                content: { defaultLocale: 'en', locales: [] },
+            },
+        })).toThrow(/routes\.admin/);
+    });
+});

package/dist/core.d.ts

@@ -9,10 +9,10 @@ import { type AbilityDescriptor, AbilityRegistry, type SessionProvider } from '@
 import type { Logger as PinoLogger } from 'pino';
 import { type BylineLogger } from './lib/logger.js';
 import { type CollectionRecord } from './services/collection-bootstrap.js';
-import type { CollectionDefinition, IDbAdapter, IStorageProvider, ServerConfig } from './@types/index.js';
+import type { CollectionDefinition, IDbAdapter, IStorageProvider, ResolvedServerConfig, ServerConfig } from './@types/index.js';
 export interface BylineCore<TAdminStore = unknown> {
-    config: ServerConfig<TAdminStore>;
-    collections: CollectionDefinition[];
+    config: ResolvedServerConfig<TAdminStore>;
+    collections: readonly CollectionDefinition[];
     db: IDbAdapter;
     storage: IStorageProvider | undefined;
     logger: BylineLogger;

package/dist/core.js

@@ -7,11 +7,12 @@
  */
 import { AbilityRegistry } from '@byline/auth';
 import { registerCollectionAbilities } from './auth/register-collection-abilities.js';
-import { defineBylineCore, defineServerConfig, getBylineCoreUnsafe } from './config/config.js';
+import { defineBylineCore, getBylineCoreUnsafe, registerServerConfig, resolveServerConfig, } from './config/config.js';
 import { createBylineLogger, defineLogger } from './lib/logger.js';
 import { Registry } from './lib/registry.js';
 import { ensureCollections } from './services/collection-bootstrap.js';
 import { discoverCounterGroups } from './services/discover-counter-groups.js';
+import { validateTreeAuditCapability } from './services/document-lifecycle/audit.js';
 import { validateTranslations } from './services/i18n-validator.js';
 import { validateRichTextFieldFlags } from './services/richtext-populate.js';
 import { validateSearchConfig } from './services/validate-search-config.js';
@@ -32,11 +33,12 @@ export const initBylineCore = async (config, pinoLogger) => {
         const { pino } = await import('pino');
         pinoLogger = pino({ level: 'info' });
     }
+    const resolvedConfig = resolveServerConfig(config);
     const registry = new Registry()
-        .addValue('config', config)
-        .addValue('collections', config.collections)
-        .addValue('db', config.db)
-        .addValue('storage', config.storage)
+        .addValue('config', resolvedConfig)
+        .addValue('collections', resolvedConfig.collections)
+        .addValue('db', resolvedConfig.db)
+        .addValue('storage', resolvedConfig.storage)
         .addFactory('logger', createBylineLogger);
     const composed = registry.compose({ pinoLogger });
     // Validate richText field flags against the registered server adapter
@@ -44,15 +46,18 @@ export const initBylineCore = async (config, pinoLogger) => {
     // (both flags off) and missing-adapter cases at boot rather than at
     // request time.
     validateRichTextFieldFlags(composed.collections, {
-        populate: config.fields?.richText?.populate != null,
-        embed: config.fields?.richText?.embed != null,
+        populate: resolvedConfig.fields?.richText?.populate != null,
+        embed: resolvedConfig.fields?.richText?.embed != null,
     });
     // Validate search configuration: a collection that opts into search must
     // have a SearchProvider registered, otherwise indexing / client.search()
     // would silently no-op. Fail-fast at boot, same posture as richText above.
     validateSearchConfig(composed.collections, {
-        provider: config.search != null,
+        provider: resolvedConfig.search != null,
     });
+    // Tree edges are unversioned metadata and may only run on adapters that can
+    // lock, mutate, and append audit rows in one transaction.
+    validateTreeAuditCapability(composed.collections, composed.db);
     // Validate the admin i18n translation registry against the configured
     // interface locale set. Throws on structural errors (missing bundle for
     // a declared locale, defaultLocale outside the permitted set, …); soft
@@ -62,9 +67,9 @@ export const initBylineCore = async (config, pinoLogger) => {
     // validator takes the assembled shape so locale config and bundle
     // travel together.
     const i18nValidation = validateTranslations({
-        defaultLocale: config.i18n.interface.defaultLocale,
-        locales: config.i18n.interface.locales,
-        translations: config.i18n.translations,
+        defaultLocale: resolvedConfig.i18n.interface.defaultLocale,
+        locales: resolvedConfig.i18n.interface.locales,
+        translations: resolvedConfig.i18n.translations,
     });
     for (const warning of i18nValidation.warnings) {
         composed.logger.warn({
@@ -73,9 +78,6 @@ export const initBylineCore = async (config, pinoLogger) => {
             missingKeys: warning.missingKeys,
         }, `[i18n] '${warning.locale}.${warning.namespace}' is missing ${warning.missingKeys.length} key(s) relative to the other locales`);
     }
-    // Backward compat: populate globalThis singletons
-    defineServerConfig(config);
-    defineLogger(composed.logger);
     // Reconcile collection definitions with the database: insert new rows,
     // bump schema versions when the fingerprint has drifted, and build the
     // in-memory record cache used by the lifecycle/upload/client paths.
@@ -140,6 +142,10 @@ export const initBylineCore = async (config, pinoLogger) => {
         sessionProvider: composed.config.sessionProvider,
         adminStore: composed.config.adminStore,
     };
+    // Commit globals only after the replacement core has fully initialized. A
+    // failed reinitialization leaves the prior config, logger, and core intact.
+    registerServerConfig(resolvedConfig);
+    defineLogger(composed.logger);
     // Register on the global singleton so server-side packages
     // (`@byline/host-tanstack-start/server-fns/*`, future hosts) can read
     // post-init state via `getBylineCore()` instead of importing the

package/dist/core.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core.test.node.js

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { defineServerConfig, getServerConfig } from './config/config.js';
+import { initBylineCore } from './core.js';
+function serverConfig(admin) {
+    return {
+        serverURL: 'https://example.test',
+        routes: { admin },
+        collections: [],
+        db: {},
+        i18n: {
+            interface: { defaultLocale: 'en', locales: [] },
+            content: { defaultLocale: 'en', locales: [] },
+        },
+    };
+}
+describe('initBylineCore configuration registration', () => {
+    it('does not overwrite a valid singleton when synchronous validation fails', async () => {
+        const valid = defineServerConfig(serverConfig('/stable/admin'));
+        const invalid = serverConfig('/replacement/admin');
+        invalid.i18n = {
+            interface: { defaultLocale: 'en', locales: ['en'] },
+            content: { defaultLocale: 'en', locales: [] },
+        };
+        await expect(initBylineCore(invalid, {})).rejects.toThrow(/translations bundle/i);
+        expect(getServerConfig()).toBe(valid);
+        expect(getServerConfig().routes.admin).toBe('/stable/admin');
+    });
+});

package/dist/index.d.ts

@@ -1,20 +1,21 @@
 export * from './@types/index.js';
-export { applyBeforeRead, assertActorCanPerform, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, registerCollectionAbilities, } from './auth/index.js';
+export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, registerCollectionAbilities, } from './auth/index.js';
 export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
-export { BylineError, ERR_AUDIT_UNSUPPORTED, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_STORAGE, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, } from './lib/errors.js';
+export { BylineError, 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 { 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';
 export * from './patches/index.js';
-export { mergePredicates, type ParseContext, type ParsedSort, type ParsedWhere, parseSort, parseWhere, } from './query/parse-where.js';
+export { mergePredicates, type ParseContext, type ParsedSort, type ParsedWhere, parsePredicateFilters, parseSort, parseWhere, } from './query/parse-where.js';
 export { getCollectionSchemasForPath } from './schemas/zod/cache.js';
 export * from './services/index.js';
 export * from './storage/index.js';
+export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js';
 export { formatTextValue, looksLikeISODate, type SlugifierFn, type SlugifyContext, slugify, } from './utils/slugify.js';
 export { getUploadFields, hasUploadField, isUploadField } from './utils/storage-utils.js';
 export * from './workflow/index.js';

package/dist/index.js

@@ -15,22 +15,23 @@
 // through this main entry or `@byline/client`.
 // ---------------------------------------------------------------------------
 export * from './@types/index.js';
-export { applyBeforeRead, assertActorCanPerform, COLLECTION_ABILITY_VERBS, collectionAbilityKey, registerCollectionAbilities, } from './auth/index.js';
+export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, registerCollectionAbilities, } from './auth/index.js';
 export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
-export { BylineError, ERR_AUDIT_UNSUPPORTED, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_STORAGE, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, } from './lib/errors.js';
+export { BylineError, 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 { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { getLogger } from './lib/logger.js';
 export { AsyncRegistry, Registry } from './lib/registry.js';
 export * from './patches/index.js';
-export { mergePredicates, parseSort, parseWhere, } from './query/parse-where.js';
+export { mergePredicates, parsePredicateFilters, parseSort, parseWhere, } from './query/parse-where.js';
 export { getCollectionSchemasForPath } from './schemas/zod/cache.js';
 export * from './services/index.js';
 export * from './storage/index.js';
+export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js';
 export { formatTextValue, looksLikeISODate, slugify, } from './utils/slugify.js';
 export { getUploadFields, hasUploadField, isUploadField } from './utils/storage-utils.js';
 export * from './workflow/index.js';

package/dist/lib/errors.d.ts

@@ -85,9 +85,15 @@ export declare const ErrorCodes: {
     readonly DATABASE: 'ERR_DATABASE';
     readonly STORAGE: 'ERR_STORAGE';
     readonly READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED';
+    readonly READ_RECURSION: 'ERR_READ_RECURSION';
     readonly PATH_CONFLICT: 'ERR_PATH_CONFLICT';
     readonly AUDIT_UNSUPPORTED: 'ERR_AUDIT_UNSUPPORTED';
+    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]";
 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;
@@ -97,6 +103,7 @@ export declare const ERR_PATCH_FAILED: (opts: BylineErrorOptions, errorConstruct
 export declare const ERR_DATABASE: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_STORAGE: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_READ_BUDGET_EXCEEDED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+export declare const ERR_READ_RECURSION: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 /**
  * Thrown when a write attempts to set `path` to a value already used by
  * another document in the same `(collection, locale)` scope. Surfaces the
@@ -114,3 +121,9 @@ export declare const ERR_PATH_CONFLICT: (opts: BylineErrorOptions, errorConstruc
  * docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
  */
 export declare const ERR_AUDIT_UNSUPPORTED: (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
+ * reconcile, while transports can distinguish it from a rolled-back mutation.
+ */
+export declare const ERR_TREE_HOOK_COMMITTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;

package/dist/lib/errors.js

@@ -53,6 +53,7 @@ export class BylineError extends Error {
             super(message, { cause });
         }
         this.code = code;
+        this.name = 'BylineError';
         this.details = details;
         this.logExtra = logExtra;
         this.logLevel = logLevel;
@@ -118,9 +119,15 @@ export const ErrorCodes = {
     DATABASE: 'ERR_DATABASE',
     STORAGE: 'ERR_STORAGE',
     READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED',
+    READ_RECURSION: 'ERR_READ_RECURSION',
     PATH_CONFLICT: 'ERR_PATH_CONFLICT',
     AUDIT_UNSUPPORTED: 'ERR_AUDIT_UNSUPPORTED',
+    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]';
 // ---------------------------------------------------------------------------
 // Pre-instantiated factories
 // ---------------------------------------------------------------------------
@@ -133,6 +140,7 @@ export const ERR_PATCH_FAILED = createErrorType(ErrorCodes.PATCH_FAILED);
 export const ERR_DATABASE = createErrorType(ErrorCodes.DATABASE);
 export const ERR_STORAGE = createErrorType(ErrorCodes.STORAGE);
 export const ERR_READ_BUDGET_EXCEEDED = createErrorType(ErrorCodes.READ_BUDGET_EXCEEDED);
+export const ERR_READ_RECURSION = createErrorType(ErrorCodes.READ_RECURSION);
 /**
  * Thrown when a write attempts to set `path` to a value already used by
  * another document in the same `(collection, locale)` scope. Surfaces the
@@ -150,3 +158,9 @@ export const ERR_PATH_CONFLICT = createErrorType(ErrorCodes.PATH_CONFLICT, 'warn
  * docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
  */
 export const ERR_AUDIT_UNSUPPORTED = createErrorType(ErrorCodes.AUDIT_UNSUPPORTED);
+/**
+ * A tree mutation and its audit row committed, but its post-commit
+ * `afterTreeChange` work failed. Callers still receive a rejection so they can
+ * reconcile, while transports can distinguish it from a rolled-back mutation.
+ */
+export const ERR_TREE_HOOK_COMMITTED = createErrorType(ErrorCodes.TREE_HOOK_COMMITTED, 'warn');

package/dist/query/parse-where.d.ts

@@ -28,7 +28,7 @@ declare const DOCUMENT_LEVEL_KEYS: Set<string>;
  */
 export interface ParseContext {
     /** All registered collection definitions. */
-    collections: CollectionDefinition[];
+    collections: readonly CollectionDefinition[];
     /** Resolve a collection path → DB row id. */
     resolveCollectionId: (path: string) => Promise<string>;
     /**
@@ -87,6 +87,15 @@ declare const DOCUMENT_SORT_COLUMNS: Record<string, string>;
  * sensible composition through a relation hop.
  */
 export declare function parseWhere(where: WhereClause | undefined, definition: CollectionDefinition, ctx?: ParseContext): Promise<ParsedWhere>;
+/**
+ * Compile a predicate wholly to adapter `DocumentFilter`s. Unlike
+ * `parseWhere`, top-level `status` and `path` are emitted as document-column
+ * filters rather than scalar list-query options. This is the form used by
+ * `beforeRead` on detail, populate, count, and tree reads.
+ */
+export declare function parsePredicateFilters(where: QueryPredicate | undefined, definition: CollectionDefinition, ctx?: ParseContext, options?: {
+    strict?: boolean;
+}): Promise<DocumentFilter[]>;
 /**
  * Combine a `beforeRead` hook predicate with a caller-supplied where
  * clause using implicit AND. Returns whichever side is non-empty, or

package/dist/query/parse-where.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { ERR_VALIDATION } from '../lib/errors.js';
 import { fieldTypeToStore } from '../storage/field-store-map.js';
 // ---------------------------------------------------------------------------
 // Document-level reserved keys
@@ -44,6 +45,144 @@ const DOCUMENT_SORT_COLUMNS = {
 export async function parseWhere(where, definition, ctx) {
     return parseWhereInternal(where, definition, ctx, { isNested: false, inCombinator: false });
 }
+/**
+ * Compile a predicate wholly to adapter `DocumentFilter`s. Unlike
+ * `parseWhere`, top-level `status` and `path` are emitted as document-column
+ * filters rather than scalar list-query options. This is the form used by
+ * `beforeRead` on detail, populate, count, and tree reads.
+ */
+export async function parsePredicateFilters(where, definition, ctx, options = {}) {
+    if (options.strict) {
+        await validateSecurityPredicate(where, definition, ctx);
+    }
+    const parsed = await parseWhereInternal(where, definition, ctx, {
+        isNested: false,
+        inCombinator: true,
+    });
+    return parsed.filters;
+}
+const FILTER_OPERATORS = new Set([
+    '$eq',
+    '$ne',
+    '$gt',
+    '$gte',
+    '$lt',
+    '$lte',
+    '$contains',
+    '$in',
+    '$nin',
+]);
+const DOCUMENT_COLUMN_OPERATORS = {
+    status: new Set(['$eq', '$ne', '$in', '$nin']),
+    path: new Set(['$eq', '$ne', '$contains', '$in', '$nin']),
+    id: new Set(['$eq', '$ne', '$in', '$nin']),
+};
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Fail-closed validation used only for security predicates from hooks. */
+async function validateSecurityPredicate(predicate, definition, ctx, allowEmpty = false) {
+    if (predicate == null || typeof predicate !== 'object' || Array.isArray(predicate)) {
+        throw invalidSecurityPredicate(definition.path, 'predicate must be an object');
+    }
+    const entries = Object.entries(predicate).filter(([, value]) => value !== undefined);
+    if (entries.length === 0 && !allowEmpty) {
+        throw invalidSecurityPredicate(definition.path, 'predicate must contain at least one clause');
+    }
+    for (const [key, value] of entries) {
+        if (key === '$and' || key === '$or') {
+            if (!Array.isArray(value) || value.length === 0) {
+                throw invalidSecurityPredicate(definition.path, `${key} must be a non-empty array`);
+            }
+            for (const child of value) {
+                await validateSecurityPredicate(child, definition, ctx);
+            }
+            continue;
+        }
+        if (key === 'query') {
+            throw invalidSecurityPredicate(definition.path, '`query` is not supported in beforeRead security predicates');
+        }
+        if (key === 'status' || key === 'path' || key === 'id') {
+            validateDocumentColumnPredicate(value, definition.path, key);
+            continue;
+        }
+        const field = definition.fields.find((candidate) => candidate.name === key);
+        if (field == null) {
+            throw invalidSecurityPredicate(definition.path, `unknown field '${key}'`);
+        }
+        if (field.type === 'relation' && (isQuantifierObject(value) || isPlainSubWhere(value))) {
+            const targetPath = field.targetCollection;
+            const target = targetPath
+                ? ctx?.collections.find((candidate) => candidate.path === targetPath)
+                : null;
+            if (target == null) {
+                throw invalidSecurityPredicate(definition.path, `cannot resolve target collection for relation field '${key}'`);
+            }
+            if (isQuantifierObject(value)) {
+                for (const [quantifier, nested] of Object.entries(value)) {
+                    await validateSecurityPredicate(nested, target, ctx, quantifier === '$none');
+                }
+            }
+            else {
+                await validateSecurityPredicate(value, target, ctx);
+            }
+            continue;
+        }
+        if (fieldTypeToStore[field.type] == null) {
+            throw invalidSecurityPredicate(definition.path, `field '${key}' cannot be used as a predicate`);
+        }
+        validateSecurityOperator(value, definition.path, key);
+    }
+}
+function validateDocumentColumnPredicate(value, collectionPath, column) {
+    validateSecurityOperator(value, collectionPath, column);
+    const parsed = normaliseToOperator(value);
+    if (parsed == null || !DOCUMENT_COLUMN_OPERATORS[column].has(parsed.operator)) {
+        throw invalidSecurityPredicate(collectionPath, `operator '${parsed?.operator ?? 'unknown'}' is not supported for '${column}'`);
+    }
+    const values = Array.isArray(parsed.value) ? parsed.value : [parsed.value];
+    if ((parsed.operator === '$in' || parsed.operator === '$nin') && !Array.isArray(parsed.value)) {
+        throw invalidSecurityPredicate(collectionPath, `${parsed.operator} for '${column}' requires an array`);
+    }
+    if (parsed.operator !== '$in' && parsed.operator !== '$nin' && Array.isArray(parsed.value)) {
+        throw invalidSecurityPredicate(collectionPath, `${parsed.operator} for '${column}' requires a string`);
+    }
+    if (values.some((item) => typeof item !== 'string')) {
+        throw invalidSecurityPredicate(collectionPath, `predicate for '${column}' requires string values`);
+    }
+    if (column === 'id' && values.some((item) => !UUID_RE.test(item))) {
+        throw invalidSecurityPredicate(collectionPath, `predicate for 'id' requires UUID values; use { id: { $in: [] } } to deny all rows`);
+    }
+}
+function validateSecurityOperator(value, collectionPath, fieldName) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return;
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw invalidSecurityPredicate(collectionPath, `invalid predicate for '${fieldName}'`);
+    }
+    const entries = Object.entries(value);
+    if (entries.length !== 1 || !FILTER_OPERATORS.has(entries[0]?.[0] ?? '')) {
+        throw invalidSecurityPredicate(collectionPath, `predicate for '${fieldName}' must contain exactly one supported operator`);
+    }
+    const [operator, operand] = entries[0] ?? [];
+    if ((operator === '$in' || operator === '$nin') && !Array.isArray(operand)) {
+        throw invalidSecurityPredicate(collectionPath, `${operator} for '${fieldName}' requires an array`);
+    }
+    if (operator === '$contains' && typeof operand !== 'string') {
+        throw invalidSecurityPredicate(collectionPath, `$contains for '${fieldName}' requires a string`);
+    }
+    if (operand === undefined) {
+        throw invalidSecurityPredicate(collectionPath, `operator for '${fieldName}' requires a value`);
+    }
+}
+function invalidSecurityPredicate(collectionPath, reason) {
+    return ERR_VALIDATION({
+        message: `invalid beforeRead predicate for '${collectionPath}': ${reason}`,
+        details: { collectionPath, reason },
+    });
+}
 /**
  * Combine a `beforeRead` hook predicate with a caller-supplied where
  * clause using implicit AND. Returns whichever side is non-empty, or
@@ -179,7 +318,7 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                         kind: 'docColumn',
                         column: 'status',
                         operator: parsed.operator,
-                        value: parsed.value === null ? null : String(parsed.value),
+                        value: stringifyDocumentColumnValue(parsed.value),
                     });
                 }
                 continue;
@@ -211,7 +350,7 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                         kind: 'docColumn',
                         column: 'path',
                         operator: parsed.operator,
-                        value: parsed.value === null ? null : String(parsed.value),
+                        value: stringifyDocumentColumnValue(parsed.value),
                     });
                 }
                 continue;
@@ -449,5 +588,10 @@ function normaliseToOperator(raw) {
         value: val,
     };
 }
+function stringifyDocumentColumnValue(value) {
+    if (value === null)
+        return null;
+    return Array.isArray(value) ? value.map(String) : String(value);
+}
 /** Exported for testing. */
 export { DOCUMENT_LEVEL_KEYS, DOCUMENT_SORT_COLUMNS };