@byline/core 3.21.0 → 4.1.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,9 +9,9 @@ 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>;
+    config: ResolvedServerConfig<TAdminStore>;
     collections: readonly CollectionDefinition[];
     db: IDbAdapter;
     storage: IStorageProvider | undefined;

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/host/host-request-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * The host-framework request bridge — the seam that makes the server-side
+ * client stack (`@byline/client/server`) host-agnostic.
+ *
+ * Everything request-scoped in that stack bottoms out in three
+ * primitives: "which request am I in" (identity for per-request
+ * memoization), "read a cookie", and "write a cookie" (admin session
+ * refresh rotates tokens). A host adapter implements those three over its
+ * framework's runtime and registers the bridge once at server boot;
+ * `@byline/client/server` is written against the interface and never
+ * imports a framework.
+ *
+ * Registration follows the same pattern as the config singletons in
+ * `config/config.ts`: a `Symbol.for` slot on `globalThis`, so every copy
+ * of this module (Vite SSR can resolve workspace-linked packages through
+ * different module graphs) shares the same state. Server-only by nature —
+ * hosts register from their boot path (side-effect imports guarantee
+ * registration before any request is handled), and nothing in a browser
+ * graph should ever reach for it.
+ */
+export interface HostCookieSetOptions {
+    httpOnly?: boolean;
+    sameSite?: 'lax' | 'strict' | 'none';
+    secure?: boolean;
+    path?: string;
+    maxAge?: number;
+}
+export interface HostRequestBridge {
+    /**
+     * A stable identity object for the current HTTP request, or `undefined`
+     * when running outside a request (seed scripts, background jobs, unit
+     * tests). Used purely as a WeakMap key for per-request memoization —
+     * never inspected.
+     */
+    getRequest(): object | undefined;
+    /** Read a request cookie. Returns `undefined` when not present. */
+    getCookie(name: string): string | undefined;
+    /** Write a response cookie (admin session refresh, preview toggles). */
+    setCookie(name: string, value: string, options?: HostCookieSetOptions): void;
+}
+/**
+ * Register the host adapter's bridge. Idempotent and last-write-wins —
+ * host adapters register from side-effect imports, which may evaluate
+ * more than once across module graphs.
+ */
+export declare function registerHostRequestBridge(bridge: HostRequestBridge): void;
+/** The registered bridge, or `undefined` when no host has registered one. */
+export declare function tryGetHostRequestBridge(): HostRequestBridge | undefined;
+/**
+ * The registered bridge, throwing with setup guidance when absent. Cookie
+ * reads/writes require a host; scripts and tests that have no request
+ * should pass an explicit `requestContext` to `createBylineClient`
+ * instead of using the request-bound getters.
+ */
+export declare function getHostRequestBridge(): HostRequestBridge;

package/dist/host/host-request-bridge.js

@@ -0,0 +1,38 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+const BYLINE_HOST_REQUEST_BRIDGE = Symbol.for('__byline_host_request_bridge__');
+/**
+ * Register the host adapter's bridge. Idempotent and last-write-wins —
+ * host adapters register from side-effect imports, which may evaluate
+ * more than once across module graphs.
+ */
+export function registerHostRequestBridge(bridge) {
+    ;
+    globalThis[BYLINE_HOST_REQUEST_BRIDGE] = bridge;
+}
+/** The registered bridge, or `undefined` when no host has registered one. */
+export function tryGetHostRequestBridge() {
+    return globalThis[BYLINE_HOST_REQUEST_BRIDGE] ?? undefined;
+}
+/**
+ * The registered bridge, throwing with setup guidance when absent. Cookie
+ * reads/writes require a host; scripts and tests that have no request
+ * should pass an explicit `requestContext` to `createBylineClient`
+ * instead of using the request-bound getters.
+ */
+export function getHostRequestBridge() {
+    const bridge = tryGetHostRequestBridge();
+    if (!bridge) {
+        throw new Error('No HostRequestBridge registered. A host adapter (e.g. ' +
+            '@byline/host-tanstack-start) must call registerHostRequestBridge() ' +
+            'at server boot before request-bound client getters can resolve ' +
+            'cookies. Scripts and tests should pass an explicit requestContext ' +
+            'to createBylineClient instead.');
+    }
+    return bridge;
+}

package/dist/index.d.ts

@@ -1,20 +1,22 @@
 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 { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.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,24 @@
 // 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 { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.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

@@ -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