@byline/core 3.21.0 → 4.1.0

package/dist/auth/apply-before-read.d.ts

@@ -7,22 +7,17 @@
  */
 import type { RequestContext } from '@byline/auth';
 import { type CollectionDefinition } from '../@types/collection-types.js';
-import type { ReadContext } from '../@types/db-types.js';
+import { type ParseContext } from '../query/parse-where.js';
+import type { DocumentFilter, ReadContext } from '../@types/db-types.js';
 import type { QueryPredicate } from '../@types/query-predicate.js';
 /**
  * Resolve the per-collection `beforeRead` hook predicate for the current
  * request, with caching across populate fanout.
  *
- * Behaviour:
- *   - Cache hit on `readContext.beforeReadCache` (keyed by collection
- *     path) returns the cached value immediately. The actor is invariant
- *     for the lifetime of one `ReadContext`, so a single key per
- *     collection is sufficient.
- *   - Each configured hook function runs in declaration order. Predicates
- *     returned by multiple hooks are combined with implicit AND. Hooks
- *     that return `void` / `undefined` are skipped.
- *   - The result is stored in the cache (including `null` for "ran with
- *     no scoping") so subsequent batches in the same request reuse it.
+ * Each configured hook function runs in declaration order. Predicates from
+ * multiple hooks are combined with implicit AND. Results are cached in
+ * module-private state bound to one request authority; caller-owned
+ * `ReadContext` properties are never consulted for authorization.
  *
  * Returns `null` when no hook is configured, or every hook returned
  * void. Callers (`CollectionHandle`, `populateDocuments`) treat `null`
@@ -32,4 +27,21 @@ export declare function applyBeforeRead(params: {
     definition: CollectionDefinition;
     requestContext: RequestContext;
     readContext: ReadContext;
+    /** Stable adapter/client identity. Defaults to the definition for direct callers. */
+    securityDomain?: object;
 }): Promise<QueryPredicate | null>;
+/**
+ * Resolve and strictly compile the security predicate once per logical read.
+ * Promise caching also prevents concurrent populate branches from compiling
+ * the same predicate or resolving its relation collection ids more than once.
+ */
+export declare function compileBeforeReadFilters(params: {
+    definition: CollectionDefinition;
+    requestContext: RequestContext;
+    readContext: ReadContext;
+    parseContext: ParseContext;
+    /** Stable identity shared by every fanout path using this adapter/client. */
+    securityDomain: object;
+}): Promise<DocumentFilter[] | undefined>;
+/** Bind a logical read to one immutable request authority. */
+export declare function bindReadContextAuthority(readContext: ReadContext, requestContext: RequestContext): void;

package/dist/auth/apply-before-read.js

@@ -6,60 +6,166 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { resolveHooks, } from '../@types/collection-types.js';
+import { ERR_READ_RECURSION, ERR_VALIDATION } from '../lib/errors.js';
+import { parsePredicateFilters } from '../query/parse-where.js';
+import { createHookReadContext, getReadContextScope } from './read-context-scope.js';
+const readSecurityStates = new WeakMap();
 /**
  * Resolve the per-collection `beforeRead` hook predicate for the current
  * request, with caching across populate fanout.
  *
- * Behaviour:
- *   - Cache hit on `readContext.beforeReadCache` (keyed by collection
- *     path) returns the cached value immediately. The actor is invariant
- *     for the lifetime of one `ReadContext`, so a single key per
- *     collection is sufficient.
- *   - Each configured hook function runs in declaration order. Predicates
- *     returned by multiple hooks are combined with implicit AND. Hooks
- *     that return `void` / `undefined` are skipped.
- *   - The result is stored in the cache (including `null` for "ran with
- *     no scoping") so subsequent batches in the same request reuse it.
+ * Each configured hook function runs in declaration order. Predicates from
+ * multiple hooks are combined with implicit AND. Results are cached in
+ * module-private state bound to one request authority; caller-owned
+ * `ReadContext` properties are never consulted for authorization.
  *
  * Returns `null` when no hook is configured, or every hook returned
  * void. Callers (`CollectionHandle`, `populateDocuments`) treat `null`
  * the same as "no scoping" — they pass nothing extra to the adapter.
  */
 export async function applyBeforeRead(params) {
-    const { definition, requestContext, readContext } = params;
+    const { definition, requestContext, readContext, securityDomain = definition } = params;
     const collectionPath = definition.path;
-    if (readContext.beforeReadCache.has(collectionPath)) {
-        return readContext.beforeReadCache.get(collectionPath) ?? null;
+    const scope = getReadContextScope(readContext);
+    const entry = getBeforeReadCacheEntry(scope.root, requestContext, securityDomain, definition);
+    if (scope.ancestry.includes(entry)) {
+        throw ERR_READ_RECURSION({
+            message: `beforeRead recursion blocked for collection '${collectionPath}'`,
+            details: { collectionPath, readMode: requestContext.readMode ?? 'any' },
+        });
     }
-    const resolved = await resolveHooks(definition);
-    const hooks = normalizeBeforeReadHook(resolved?.beforeRead);
-    if (hooks.length === 0) {
-        readContext.beforeReadCache.set(collectionPath, null);
-        return null;
+    if (entry.predicate)
+        return entry.predicate;
+    const pending = (async () => {
+        const resolved = await resolveHooks(definition);
+        const hooks = normalizeBeforeReadHook(resolved?.beforeRead);
+        if (hooks.length === 0)
+            return null;
+        const predicates = [];
+        for (const hook of hooks) {
+            const result = await hook({
+                collectionPath,
+                requestContext,
+                readContext: createHookReadContext(scope, entry),
+            });
+            if (result != null)
+                predicates.push(result);
+        }
+        if (predicates.length === 0)
+            return null;
+        if (predicates.length === 1)
+            return predicates[0] ?? null;
+        return { $and: predicates };
+    })();
+    entry.predicate = pending;
+    return pending;
+}
+/**
+ * Resolve and strictly compile the security predicate once per logical read.
+ * Promise caching also prevents concurrent populate branches from compiling
+ * the same predicate or resolving its relation collection ids more than once.
+ */
+export async function compileBeforeReadFilters(params) {
+    const { definition, requestContext, readContext, parseContext, securityDomain } = params;
+    const scope = getReadContextScope(readContext);
+    const entry = getBeforeReadCacheEntry(scope.root, requestContext, securityDomain, definition);
+    if (scope.ancestry.includes(entry)) {
+        throw ERR_READ_RECURSION({
+            message: `beforeRead recursion blocked for collection '${definition.path}'`,
+            details: {
+                collectionPath: definition.path,
+                readMode: requestContext.readMode ?? 'any',
+            },
+        });
     }
-    const predicates = [];
-    for (const hook of hooks) {
-        const result = await hook({
-            collectionPath,
+    if (entry.compiledFilters)
+        return entry.compiledFilters;
+    const compiled = (async () => {
+        const predicate = await applyBeforeRead({
+            definition,
             requestContext,
             readContext,
+            securityDomain,
+        });
+        if (predicate == null)
+            return undefined;
+        const filters = await parsePredicateFilters(predicate, definition, parseContext, {
+            strict: true,
         });
-        if (result != null) {
-            predicates.push(result);
+        return filters.length > 0 ? filters : undefined;
+    })();
+    entry.compiledFilters = compiled;
+    return compiled;
+}
+/** Bind a logical read to one immutable request authority. */
+export function bindReadContextAuthority(readContext, requestContext) {
+    getReadSecurityState(readContext, requestContext);
+}
+function getReadSecurityState(readContext, requestContext) {
+    const root = getReadContextScope(readContext).root;
+    const authorityToken = requestAuthorityToken(requestContext);
+    const existing = readSecurityStates.get(root);
+    if (existing) {
+        if (existing.authorityToken !== authorityToken) {
+            throw ERR_VALIDATION({
+                message: 'ReadContext cannot be reused across request authorities',
+            });
         }
+        return existing;
+    }
+    const state = {
+        authorityToken,
+        domains: new WeakMap(),
+    };
+    readSecurityStates.set(root, state);
+    return state;
+}
+function getBeforeReadCacheEntry(readContext, requestContext, securityDomain, definition) {
+    const state = getReadSecurityState(readContext, requestContext);
+    let domain = state.domains.get(securityDomain);
+    if (!domain) {
+        domain = { definitions: new WeakMap() };
+        state.domains.set(securityDomain, domain);
     }
-    let combined;
-    if (predicates.length === 0) {
-        combined = null;
+    let definitionState = domain.definitions.get(definition);
+    if (!definitionState) {
+        definitionState = { modes: new Map() };
+        domain.definitions.set(definition, definitionState);
     }
-    else if (predicates.length === 1) {
-        combined = predicates[0];
+    const mode = requestContext.readMode ?? 'any';
+    let entry = definitionState.modes.get(mode);
+    if (!entry) {
+        entry = {};
+        definitionState.modes.set(mode, entry);
     }
-    else {
-        combined = { $and: predicates };
+    return entry;
+}
+/**
+ * `requestId` stays in the token deliberately. A `ReadContext` is a
+ * per-logical-request object, and predicates cached on it may embed
+ * request-time state (embargo cutoffs, preview windows), so reusing one
+ * across requests must fail loudly even for the same actor. The flip side
+ * is a contract on host adapters: a `RequestContext` factory must return
+ * the same instance for every call within one logical request (see
+ * `oncePerRequest` in `@byline/host-tanstack-start`) — a factory that
+ * mints a fresh `requestId` per call makes any two reads sharing a
+ * `ReadContext` throw the cross-authority error above.
+ */
+function requestAuthorityToken(requestContext) {
+    const actor = requestContext.actor;
+    if (actor == null) {
+        return JSON.stringify([requestContext.requestId, requestContext.locale ?? null, 'anonymous']);
     }
-    readContext.beforeReadCache.set(collectionPath, combined);
-    return combined;
+    const realm = 'isSuperAdmin' in actor ? 'admin' : 'user';
+    const isSuperAdmin = 'isSuperAdmin' in actor ? actor.isSuperAdmin : false;
+    return JSON.stringify([
+        requestContext.requestId,
+        requestContext.locale ?? null,
+        realm,
+        actor.id,
+        isSuperAdmin,
+        Array.from(actor.abilities).sort(),
+    ]);
 }
 /** Normalise a `beforeRead` slot (single function or array) into a flat array. */
 function normalizeBeforeReadHook(slot) {

package/dist/auth/apply-before-read.test.node.js

@@ -5,11 +5,12 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { createRequestContext } from '@byline/auth';
-import { describe, expect, it } from 'vitest';
+import { AdminAuth, createRequestContext } from '@byline/auth';
+import { describe, expect, it, vi } from 'vitest';
 import { defineCollection, defineWorkflow, } from '../@types/collection-types.js';
 import { createReadContext } from '../services/populate.js';
-import { applyBeforeRead } from './apply-before-read.js';
+import { applyBeforeRead, compileBeforeReadFilters } from './apply-before-read.js';
+import { resolveReadContextRoot } from './read-context-scope.js';
 const baseCollection = (hook) => defineCollection({
     path: 'posts',
     labels: { singular: 'Post', plural: 'Posts' },
@@ -101,6 +102,55 @@ describe('applyBeforeRead', () => {
         expect(second).toBeNull();
         expect(callCount).toBe(1);
     });
+    it('ignores a caller-preseeded public cache entry', async () => {
+        const hook = vi.fn(() => ({ title: 'allowed' }));
+        const readContext = createReadContext({
+            beforeReadCache: new Map([['posts:any', null]]),
+        });
+        const result = await applyBeforeRead({
+            definition: baseCollection(hook),
+            requestContext: createRequestContext(),
+            readContext,
+        });
+        expect(hook).toHaveBeenCalledOnce();
+        expect(result).toEqual({ title: 'allowed' });
+    });
+    it('ignores a caller-preseeded public cache entry on the compiled-filter path', async () => {
+        const hook = vi.fn(() => ({ title: 'allowed' }));
+        const readContext = createReadContext({
+            beforeReadCache: new Map([['posts:any', null]]),
+        });
+        const filters = await compileBeforeReadFilters({
+            definition: baseCollection(hook),
+            requestContext: createRequestContext(),
+            readContext,
+            securityDomain: {},
+            parseContext: { collections: [], resolveCollectionId: vi.fn() },
+        });
+        expect(hook).toHaveBeenCalledOnce();
+        expect(filters).toEqual([
+            expect.objectContaining({ kind: 'field', fieldName: 'title', value: 'allowed' }),
+        ]);
+    });
+    it('rejects reuse under a different actor authority', async () => {
+        const hook = vi.fn(({ requestContext }) => ({
+            title: requestContext.actor?.id,
+        }));
+        const definition = baseCollection(hook);
+        const readContext = createReadContext();
+        const requestId = 'same-logical-request';
+        const alice = createRequestContext({
+            actor: new AdminAuth({ id: 'alice', abilities: ['collections.posts.read'] }),
+            requestId,
+        });
+        const bob = createRequestContext({
+            actor: new AdminAuth({ id: 'bob', abilities: ['collections.posts.read'] }),
+            requestId,
+        });
+        await applyBeforeRead({ definition, requestContext: alice, readContext });
+        await expect(applyBeforeRead({ definition, requestContext: bob, readContext })).rejects.toThrow('cannot be reused across request authorities');
+        expect(hook).toHaveBeenCalledOnce();
+    });
     it('runs the hook again on a fresh ReadContext', async () => {
         let callCount = 0;
         const hook = () => {
@@ -113,6 +163,32 @@ describe('applyBeforeRead', () => {
         await applyBeforeRead({ definition: def, requestContext, readContext: createReadContext() });
         expect(callCount).toBe(2);
     });
+    it('caches independently by effective read mode', async () => {
+        const modes = [];
+        const hook = ({ requestContext }) => {
+            modes.push(requestContext.readMode);
+            return { status: requestContext.readMode === 'published' ? 'published' : 'draft' };
+        };
+        const definition = baseCollection(hook);
+        const readContext = createReadContext();
+        const base = createRequestContext();
+        await applyBeforeRead({
+            definition,
+            requestContext: { ...base, readMode: 'published' },
+            readContext,
+        });
+        await applyBeforeRead({
+            definition,
+            requestContext: { ...base, readMode: 'any' },
+            readContext,
+        });
+        await applyBeforeRead({
+            definition,
+            requestContext: { ...base, readMode: 'published' },
+            readContext,
+        });
+        expect(modes).toEqual(['published', 'any']);
+    });
     it('passes collectionPath, requestContext, and readContext through to the hook', async () => {
         let received;
         const hook = (ctx) => {
@@ -125,8 +201,40 @@ describe('applyBeforeRead', () => {
         expect(received).toMatchObject({
             collectionPath: 'posts',
             requestContext,
+        });
+        expect(received.readContext.visited).toBe(readContext.visited);
+    });
+    it('delegates scoped read-budget state to the logical root context', async () => {
+        const readContext = createReadContext({ maxReads: 4 });
+        const hook = ({ readContext: scoped }) => {
+            scoped.visited.add('posts:nested');
+            scoped.readCount += 1;
+            scoped.maxReads = 3;
+        };
+        await applyBeforeRead({
+            definition: baseCollection(hook),
+            requestContext: createRequestContext(),
+            readContext,
+        });
+        expect(readContext.visited).toContain('posts:nested');
+        expect(readContext.readCount).toBe(1);
+        expect(readContext.maxReads).toBe(3);
+    });
+    it('resolves scoped hook contexts to their logical root', async () => {
+        const readContext = createReadContext();
+        let scopedContext;
+        const hook = ({ readContext: scoped }) => {
+            scopedContext = scoped;
+        };
+        await applyBeforeRead({
+            definition: baseCollection(hook),
+            requestContext: createRequestContext(),
             readContext,
         });
+        if (!scopedContext)
+            throw new Error('beforeRead did not receive a scoped ReadContext');
+        expect(resolveReadContextRoot(scopedContext)).toBe(readContext);
+        expect(resolveReadContextRoot(readContext)).toBe(readContext);
     });
     it('supports an async hook', async () => {
         const hook = async () => {
@@ -140,4 +248,134 @@ describe('applyBeforeRead', () => {
         });
         expect(result).toEqual({ tenantId: 't-1' });
     });
+    it('compiles security filters and resolves relation collection ids once per read context', async () => {
+        const categories = defineCollection({
+            path: 'categories',
+            labels: { singular: 'Category', plural: 'Categories' },
+            fields: [{ name: 'tenant', type: 'text', label: 'Tenant' }],
+        });
+        const definition = defineCollection({
+            path: 'posts',
+            labels: { singular: 'Post', plural: 'Posts' },
+            fields: [
+                {
+                    name: 'category',
+                    type: 'relation',
+                    label: 'Category',
+                    targetCollection: 'categories',
+                },
+            ],
+            hooks: { beforeRead: () => ({ category: { tenant: 'alice' } }) },
+        });
+        const readContext = createReadContext();
+        const requestContext = createRequestContext({ readMode: 'published' });
+        const resolveCollectionId = vi.fn(async () => 'categories-id');
+        const params = {
+            definition,
+            requestContext,
+            readContext,
+            securityDomain: {},
+            parseContext: { collections: [definition, categories], resolveCollectionId },
+        };
+        const [first, second] = await Promise.all([
+            compileBeforeReadFilters(params),
+            compileBeforeReadFilters(params),
+        ]);
+        expect(second).toBe(first);
+        expect(resolveCollectionId).toHaveBeenCalledOnce();
+    });
+    it('compiles the same definition independently for different security domains', async () => {
+        const categories = defineCollection({
+            path: 'categories',
+            labels: { singular: 'Category', plural: 'Categories' },
+            fields: [{ name: 'tenant', type: 'text', label: 'Tenant' }],
+        });
+        const hook = vi.fn(() => ({ category: { tenant: 'alice' } }));
+        const definition = defineCollection({
+            path: 'posts',
+            labels: { singular: 'Post', plural: 'Posts' },
+            fields: [
+                {
+                    name: 'category',
+                    type: 'relation',
+                    label: 'Category',
+                    targetCollection: 'categories',
+                },
+            ],
+            hooks: { beforeRead: hook },
+        });
+        const readContext = createReadContext();
+        const requestContext = createRequestContext({ readMode: 'published' });
+        const resolveA = vi.fn(async () => 'categories-a');
+        const resolveB = vi.fn(async () => 'categories-b');
+        await compileBeforeReadFilters({
+            definition,
+            requestContext,
+            readContext,
+            securityDomain: {},
+            parseContext: { collections: [definition, categories], resolveCollectionId: resolveA },
+        });
+        await compileBeforeReadFilters({
+            definition,
+            requestContext,
+            readContext,
+            securityDomain: {},
+            parseContext: { collections: [definition, categories], resolveCollectionId: resolveB },
+        });
+        expect(hook).toHaveBeenCalledTimes(2);
+        expect(resolveA).toHaveBeenCalledOnce();
+        expect(resolveB).toHaveBeenCalledOnce();
+    });
+    it('fails closed on a recursive beforeRead for the same collection', async () => {
+        const readContext = createReadContext();
+        const requestContext = createRequestContext();
+        let definition;
+        const hook = async (ctx) => {
+            await applyBeforeRead({
+                definition,
+                requestContext: ctx.requestContext,
+                readContext: ctx.readContext,
+            });
+        };
+        definition = baseCollection(hook);
+        await expect(applyBeforeRead({ definition, requestContext, readContext })).rejects.toMatchObject({ code: 'ERR_READ_RECURSION' });
+    });
+    it('fails closed on an A to B to A beforeRead cycle', async () => {
+        const readContext = createReadContext();
+        const requestContext = createRequestContext();
+        const securityDomain = {};
+        let a;
+        let b;
+        a = defineCollection({
+            path: 'a',
+            labels: { singular: 'A', plural: 'As' },
+            fields: [{ name: 'title', type: 'text', label: 'Title' }],
+            hooks: {
+                beforeRead: async (ctx) => {
+                    await applyBeforeRead({
+                        definition: b,
+                        requestContext: ctx.requestContext,
+                        readContext: ctx.readContext,
+                        securityDomain,
+                    });
+                },
+            },
+        });
+        b = defineCollection({
+            path: 'b',
+            labels: { singular: 'B', plural: 'Bs' },
+            fields: [{ name: 'title', type: 'text', label: 'Title' }],
+            hooks: {
+                beforeRead: async (ctx) => {
+                    await applyBeforeRead({
+                        definition: a,
+                        requestContext: ctx.requestContext,
+                        readContext: ctx.readContext,
+                        securityDomain,
+                    });
+                },
+            },
+        });
+        await expect(applyBeforeRead({ definition: a, requestContext, readContext, securityDomain })).rejects.toMatchObject({ code: 'ERR_READ_RECURSION' });
+    });
 });

package/dist/auth/index.d.ts

@@ -5,6 +5,6 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-export { applyBeforeRead } from './apply-before-read.js';
+export { applyBeforeRead, bindReadContextAuthority, compileBeforeReadFilters, } from './apply-before-read.js';
 export { assertActorCanPerform } from './assert-actor-can-perform.js';
 export { COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, registerCollectionAbilities, } from './register-collection-abilities.js';

package/dist/auth/index.js

@@ -5,6 +5,6 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-export { applyBeforeRead } from './apply-before-read.js';
+export { applyBeforeRead, bindReadContextAuthority, compileBeforeReadFilters, } from './apply-before-read.js';
 export { assertActorCanPerform } from './assert-actor-can-perform.js';
 export { COLLECTION_ABILITY_VERBS, collectionAbilityKey, registerCollectionAbilities, } from './register-collection-abilities.js';

package/dist/auth/read-context-scope.d.ts

@@ -0,0 +1,20 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { ReadContext } from '../@types/db-types.js';
+export interface ReadContextScope {
+    root: ReadContext;
+    ancestry: readonly object[];
+}
+export declare function getReadContextScope(readContext: ReadContext): ReadContextScope;
+/** Resolve a scoped hook context to the ReadContext for its logical request. */
+export declare function resolveReadContextRoot(readContext: ReadContext): ReadContext;
+/**
+ * Carry hook ancestry by object identity, not by a forgeable public property.
+ * All mutable read-budget state still delegates to the logical root context.
+ */
+export declare function createHookReadContext(parent: ReadContextScope, entry: object): ReadContext;

package/dist/auth/read-context-scope.js

@@ -0,0 +1,48 @@
+/**
+ * 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 readContextScopes = new WeakMap();
+export function getReadContextScope(readContext) {
+    return readContextScopes.get(readContext) ?? { root: readContext, ancestry: [] };
+}
+/** Resolve a scoped hook context to the ReadContext for its logical request. */
+export function resolveReadContextRoot(readContext) {
+    return getReadContextScope(readContext).root;
+}
+/**
+ * Carry hook ancestry by object identity, not by a forgeable public property.
+ * All mutable read-budget state still delegates to the logical root context.
+ */
+export function createHookReadContext(parent, entry) {
+    const root = parent.root;
+    const scoped = {};
+    Object.defineProperties(scoped, {
+        visited: { enumerable: true, get: () => root.visited, set: (value) => (root.visited = value) },
+        beforeReadCache: {
+            enumerable: true,
+            get: () => root.beforeReadCache,
+            set: (value) => (root.beforeReadCache = value),
+        },
+        readCount: {
+            enumerable: true,
+            get: () => root.readCount,
+            set: (value) => (root.readCount = value),
+        },
+        maxReads: {
+            enumerable: true,
+            get: () => root.maxReads,
+            set: (value) => (root.maxReads = value),
+        },
+        maxDepth: {
+            enumerable: true,
+            get: () => root.maxDepth,
+            set: (value) => (root.maxDepth = value),
+        },
+    });
+    readContextScopes.set(scoped, { root, ancestry: [...parent.ancestry, entry] });
+    return scoped;
+}

package/dist/codegen/index.js

@@ -6,8 +6,8 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { createHash } from 'node:crypto';
-const FORMAT_VERSION = 1;
-const HASH_DOMAIN = '@byline/core/codegen:collection-types:v1\n';
+const FORMAT_VERSION = 2;
+const HASH_DOMAIN = '@byline/core/codegen:collection-types:v2\n';
 const IMPORT_ORDER = ['JsonObject', 'JsonValue', 'RelatedDocumentValue', 'StoredFileValue'];
 function compareStrings(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
@@ -411,7 +411,38 @@ function emitBody(analysis) {
     const importLines = usedImports.length === 0
         ? []
         : ['import type {', ...usedImports.map((name) => `  ${name},`), "} from '@byline/core'", ''];
-    return `${[...importLines, ...declarations].join('\n').replace(/\n+$/, '')}\n`;
+    // Every type declaration lives inside the `@byline/generated-types`
+    // declaration-merge block, so the published stub package is the one
+    // canonical import path for app collection types
+    // (`import type { NewsFields } from '@byline/generated-types'`). The
+    // file's top-level `@byline/core` imports remain visible inside the
+    // block (module augmentation is lexically scoped).
+    const declarationLines = declarations
+        .join('\n')
+        .replace(/\n+$/, '')
+        .split('\n')
+        .map((line) => (line.length === 0 ? line : `  ${line}`));
+    // Register the app's collection registry with @byline/client (a second
+    // declaration merge). Every bare `BylineClient` in the app's program —
+    // including the `@byline/client/server` getters — then resolves to
+    // `BylineClient<CollectionFieldsByPath>`. Both `@byline/generated-types`
+    // and `@byline/client` must be resolvable in the consuming program; apps
+    // that generate types depend on both.
+    const registerLines = [
+        "declare module '@byline/client' {",
+        '  interface Register {',
+        "    collections: import('@byline/generated-types').CollectionFieldsByPath",
+        '  }',
+        '}',
+    ];
+    return `${[
+        ...importLines,
+        "declare module '@byline/generated-types' {",
+        ...declarationLines,
+        '}',
+        '',
+        ...registerLines,
+    ].join('\n')}\n`;
 }
 /**
  * Emit deterministic application collection types from evaluated runtime definitions.