@byline/core 4.15.0 → 4.17.0

package/dist/auth/filter-readable-collections.test.node.js

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { describe, expect, it } from 'vitest';
+import { defineSingleton } from '../@types/index.js';
 import { filterReadableCollections } from './filter-readable-collections.js';
 const define = (path) => ({
     path,
@@ -15,10 +16,16 @@ const define = (path) => ({
 const news = define('news');
 const pages = define('pages');
 const media = define('media');
+const settings = defineSingleton({
+    path: 'site-settings',
+    label: 'Site settings',
+    fields: [{ name: 'title', label: 'Title', type: 'text' }],
+});
 const all = [news, pages, media];
 describe('filterReadableCollections', () => {
     it('returns every collection for a super admin, regardless of abilities', () => {
-        expect(filterReadableCollections(all, { isSuperAdmin: true, abilities: [] })).toEqual(all);
+        const resources = [...all, settings];
+        expect(filterReadableCollections(resources, { isSuperAdmin: true, abilities: [] })).toEqual(resources);
     });
     it('returns nothing when the actor holds no abilities', () => {
         expect(filterReadableCollections(all, { isSuperAdmin: false, abilities: [] })).toEqual([]);
@@ -51,6 +58,24 @@ describe('filterReadableCollections', () => {
         });
         expect(result).toEqual([]);
     });
+    it('uses the singleton read namespace for singleton resources', () => {
+        expect(filterReadableCollections([settings], {
+            isSuperAdmin: false,
+            abilities: ['singletons.site-settings.read'],
+        })).toEqual([settings]);
+    });
+    it('does not let the collection namespace bleed into a singleton path', () => {
+        expect(filterReadableCollections([settings], {
+            isSuperAdmin: false,
+            abilities: ['collections.site-settings.read'],
+        })).toEqual([]);
+    });
+    it('does not advertise an update-only singleton without read access', () => {
+        expect(filterReadableCollections([settings], {
+            isSuperAdmin: false,
+            abilities: ['singletons.site-settings.update'],
+        })).toEqual([]);
+    });
     it('does not match on a prefix of a collection path', () => {
         const result = filterReadableCollections([define('news-categories')], {
             isSuperAdmin: false,

package/dist/auth/index.d.ts

@@ -8,4 +8,4 @@
 export { applyBeforeRead, bindReadContextAuthority, compileBeforeReadFilters, } from './apply-before-read.js';
 export { assertActorCanPerform } from './assert-actor-can-perform.js';
 export { type ActorAbilitySnapshot, filterReadableCollections, } from './filter-readable-collections.js';
-export { COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, registerCollectionAbilities, } from './register-collection-abilities.js';
+export { COLLECTION_ABILITY_VERBS, type CollectionAbilityResource, type CollectionAbilityResourceDescriptor, type CollectionAbilityVerb, collectionAbilityKey, type DocumentAbilityResource, type DocumentAbilityVerbFor, documentAbilityKey, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, type SingletonAbilityResource, type SingletonAbilityResourceDescriptor, type SingletonAbilityVerb, } from './register-collection-abilities.js';

package/dist/auth/index.js

@@ -8,4 +8,4 @@
 export { applyBeforeRead, bindReadContextAuthority, compileBeforeReadFilters, } from './apply-before-read.js';
 export { assertActorCanPerform } from './assert-actor-can-perform.js';
 export { filterReadableCollections, } from './filter-readable-collections.js';
-export { COLLECTION_ABILITY_VERBS, collectionAbilityKey, registerCollectionAbilities, } from './register-collection-abilities.js';
+export { COLLECTION_ABILITY_VERBS, collectionAbilityKey, documentAbilityKey, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, } from './register-collection-abilities.js';

package/dist/auth/register-collection-abilities.d.ts

@@ -6,37 +6,41 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { AbilityRegistry } from '@byline/auth';
-import type { CollectionDefinition } from '../@types/index.js';
-/**
- * Auto-register the CRUD + workflow abilities contributed by a collection.
- *
- * Every registered collection contributes exactly seven abilities, all in
- * the `collections.<path>` group:
- *
- *   - `collections.<path>.read`          — enumerate / fetch documents
- *   - `collections.<path>.create`        — create new documents
- *   - `collections.<path>.update`        — modify existing documents
- *   - `collections.<path>.delete`        — delete documents (soft or hard)
- *   - `collections.<path>.publish`       — transition a document into the
- *                                          `published` status
- *   - `collections.<path>.changeStatus`  — any other workflow transition
- *                                          (draft → custom state, etc.)
- *   - `collections.<path>.reindex`       — rebuild the collection's search
- *                                          index (admin maintenance task)
- *
- * Registration is unconditional: every collection in Byline has a workflow
- * (the default `draft → published → archived` one when not explicitly
- * configured), so `publish` and `changeStatus` always apply; `reindex` is
- * likewise uniform (a no-op for collections without a `search` config).
- * Keeping the seven-ability contract uniform makes the role editor UI
- * predictable and avoids hidden conditional logic downstream.
- *
- * Called from `initBylineCore()` for each declared collection. See
- * docs/07-auth-and-security/01-authn-authz.md.
- */
-export declare function registerCollectionAbilities(registry: AbilityRegistry, definition: CollectionDefinition): void;
+import { type CollectionDefinition, type MultiCollectionDefinition, type SingletonDefinition } from '../@types/index.js';
 /** The ability suffixes that every collection contributes. Exposed for contract tests. */
 export declare const COLLECTION_ABILITY_VERBS: readonly ['read', 'create', 'update', 'delete', 'publish', 'changeStatus', 'reindex'];
+/** The smaller ability family contributed by every singleton. */
+export declare const SINGLETON_ABILITY_VERBS: readonly ['read', 'update', 'publish', 'changeStatus'];
 export type CollectionAbilityVerb = (typeof COLLECTION_ABILITY_VERBS)[number];
-/** Compute the full ability key for a collection path and verb. */
+export type SingletonAbilityVerb = (typeof SINGLETON_ABILITY_VERBS)[number];
+/** Minimal explicit descriptor for collection ability checks. */
+export interface CollectionAbilityResourceDescriptor {
+    kind: 'collection';
+    path: string;
+}
+/** Minimal explicit descriptor for singleton ability checks. */
+export interface SingletonAbilityResourceDescriptor {
+    kind: 'singleton';
+    path: string;
+}
+export type CollectionAbilityResource = MultiCollectionDefinition | CollectionAbilityResourceDescriptor;
+export type SingletonAbilityResource = SingletonDefinition | SingletonAbilityResourceDescriptor;
+export type DocumentAbilityResource = CollectionAbilityResource | SingletonAbilityResource;
+/** Correlate the permitted verb family with the resource kind. */
+export type DocumentAbilityVerbFor<Resource extends DocumentAbilityResource> = Resource extends SingletonAbilityResource ? SingletonAbilityVerb : CollectionAbilityVerb;
+/**
+ * Compute a document-resource ability key from a kind-bearing descriptor.
+ *
+ * TypeScript callers cannot pair a known singleton with collection-only verbs.
+ * Runtime validation preserves the same boundary for untyped JavaScript callers
+ * and for union-typed definitions whose concrete kind is known only at runtime.
+ */
+export declare function documentAbilityKey<Resource extends DocumentAbilityResource>(resource: Resource, verb: DocumentAbilityVerbFor<Resource>): string;
+/** @deprecated Use {@link documentAbilityKey} with a kind-bearing resource descriptor. */
 export declare function collectionAbilityKey(path: string, verb: CollectionAbilityVerb): string;
+/** Auto-register the seven abilities contributed by a multi-document collection. */
+export declare function registerCollectionAbilities(registry: AbilityRegistry, definition: MultiCollectionDefinition): void;
+/** Auto-register the four read, update, and workflow abilities for a singleton. */
+export declare function registerSingletonAbilities(registry: AbilityRegistry, definition: SingletonDefinition): void;
+/** Register the correct ability family for either document-resource kind. */
+export declare function registerDocumentAbilities(registry: AbilityRegistry, definition: CollectionDefinition): void;

package/dist/auth/register-collection-abilities.js

@@ -5,81 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-/**
- * Auto-register the CRUD + workflow abilities contributed by a collection.
- *
- * Every registered collection contributes exactly seven abilities, all in
- * the `collections.<path>` group:
- *
- *   - `collections.<path>.read`          — enumerate / fetch documents
- *   - `collections.<path>.create`        — create new documents
- *   - `collections.<path>.update`        — modify existing documents
- *   - `collections.<path>.delete`        — delete documents (soft or hard)
- *   - `collections.<path>.publish`       — transition a document into the
- *                                          `published` status
- *   - `collections.<path>.changeStatus`  — any other workflow transition
- *                                          (draft → custom state, etc.)
- *   - `collections.<path>.reindex`       — rebuild the collection's search
- *                                          index (admin maintenance task)
- *
- * Registration is unconditional: every collection in Byline has a workflow
- * (the default `draft → published → archived` one when not explicitly
- * configured), so `publish` and `changeStatus` always apply; `reindex` is
- * likewise uniform (a no-op for collections without a `search` config).
- * Keeping the seven-ability contract uniform makes the role editor UI
- * predictable and avoids hidden conditional logic downstream.
- *
- * Called from `initBylineCore()` for each declared collection. See
- * docs/07-auth-and-security/01-authn-authz.md.
- */
-export function registerCollectionAbilities(registry, definition) {
-    const path = definition.path;
-    const group = `collections.${path}`;
-    const base = `collections.${path}`;
-    const { singular, plural } = definition.labels;
-    registry.register({
-        key: `${base}.read`,
-        label: `Read ${plural}`,
-        group,
-        source: 'collection',
-    });
-    registry.register({
-        key: `${base}.create`,
-        label: `Create ${singular}`,
-        group,
-        source: 'collection',
-    });
-    registry.register({
-        key: `${base}.update`,
-        label: `Update ${singular}`,
-        group,
-        source: 'collection',
-    });
-    registry.register({
-        key: `${base}.delete`,
-        label: `Delete ${singular}`,
-        group,
-        source: 'collection',
-    });
-    registry.register({
-        key: `${base}.publish`,
-        label: `Publish ${plural}`,
-        group,
-        source: 'collection',
-    });
-    registry.register({
-        key: `${base}.changeStatus`,
-        label: `Change status of ${plural}`,
-        group,
-        source: 'collection',
-    });
-    registry.register({
-        key: `${base}.reindex`,
-        label: `Reindex ${plural} search`,
-        group,
-        source: 'collection',
-    });
-}
+import { isSingleton, } from '../@types/index.js';
 /** The ability suffixes that every collection contributes. Exposed for contract tests. */
 export const COLLECTION_ABILITY_VERBS = [
     'read',
@@ -90,7 +16,85 @@ export const COLLECTION_ABILITY_VERBS = [
     'changeStatus',
     'reindex',
 ];
-/** Compute the full ability key for a collection path and verb. */
+/** The smaller ability family contributed by every singleton. */
+export const SINGLETON_ABILITY_VERBS = ['read', 'update', 'publish', 'changeStatus'];
+/**
+ * Compute a document-resource ability key from a kind-bearing descriptor.
+ *
+ * TypeScript callers cannot pair a known singleton with collection-only verbs.
+ * Runtime validation preserves the same boundary for untyped JavaScript callers
+ * and for union-typed definitions whose concrete kind is known only at runtime.
+ */
+export function documentAbilityKey(resource, verb) {
+    const kind = resourceKind(resource);
+    const candidate = verb;
+    const allowed = kind === 'singleton' ? SINGLETON_ABILITY_VERBS : COLLECTION_ABILITY_VERBS;
+    if (!allowed.includes(candidate)) {
+        throw new TypeError(`ability verb '${candidate}' is not valid for resource kind '${kind}'`);
+    }
+    return `${resourceNamespace(kind)}.${resource.path}.${candidate}`;
+}
+/** @deprecated Use {@link documentAbilityKey} with a kind-bearing resource descriptor. */
 export function collectionAbilityKey(path, verb) {
-    return `collections.${path}.${verb}`;
+    return documentAbilityKey({ kind: 'collection', path }, verb);
+}
+/** Auto-register the seven abilities contributed by a multi-document collection. */
+export function registerCollectionAbilities(registry, definition) {
+    const group = documentAbilityGroup(definition);
+    const { singular, plural } = definition.labels;
+    const labels = {
+        read: `Read ${plural}`,
+        create: `Create ${singular}`,
+        update: `Update ${singular}`,
+        delete: `Delete ${singular}`,
+        publish: `Publish ${plural}`,
+        changeStatus: `Change status of ${plural}`,
+        reindex: `Reindex ${plural} search`,
+    };
+    for (const verb of COLLECTION_ABILITY_VERBS) {
+        registry.register({
+            key: documentAbilityKey(definition, verb),
+            label: labels[verb],
+            group,
+            source: 'collection',
+        });
+    }
+}
+/** Auto-register the four read, update, and workflow abilities for a singleton. */
+export function registerSingletonAbilities(registry, definition) {
+    const group = documentAbilityGroup(definition);
+    const label = definition.label;
+    const labels = {
+        read: `Read ${label}`,
+        update: `Update ${label}`,
+        publish: `Publish ${label}`,
+        changeStatus: `Change status of ${label}`,
+    };
+    for (const verb of SINGLETON_ABILITY_VERBS) {
+        registry.register({
+            key: documentAbilityKey(definition, verb),
+            label: labels[verb],
+            group,
+            source: 'collection',
+        });
+    }
+}
+/** Register the correct ability family for either document-resource kind. */
+export function registerDocumentAbilities(registry, definition) {
+    if (isSingleton(definition)) {
+        registerSingletonAbilities(registry, definition);
+        return;
+    }
+    registerCollectionAbilities(registry, definition);
+}
+function documentAbilityGroup(resource) {
+    return `${resourceNamespace(resourceKind(resource))}.${resource.path}`;
+}
+function resourceKind(resource) {
+    if ('kind' in resource)
+        return resource.kind;
+    return resource.singleton === true ? 'singleton' : 'collection';
+}
+function resourceNamespace(kind) {
+    return kind === 'singleton' ? 'singletons' : 'collections';
 }

package/dist/auth/register-collection-abilities.test.node.js

@@ -7,7 +7,7 @@
  */
 import { AbilityRegistry } from '@byline/auth';
 import { describe, expect, it } from 'vitest';
-import { COLLECTION_ABILITY_VERBS, collectionAbilityKey, registerCollectionAbilities, } from './register-collection-abilities.js';
+import { COLLECTION_ABILITY_VERBS, collectionAbilityKey, documentAbilityKey, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, } from './register-collection-abilities.js';
 function pageCollection() {
     return {
         path: 'pages',
@@ -30,8 +30,16 @@ function newsCollection() {
         },
     };
 }
+function siteSettings() {
+    return {
+        singleton: true,
+        path: 'site-settings',
+        label: 'Site settings',
+        fields: [{ name: 'title', type: 'text' }],
+    };
+}
 describe('registerCollectionAbilities', () => {
-    it('registers exactly the six CRUD + workflow abilities for a collection', () => {
+    it('registers exactly the seven collection abilities', () => {
         const registry = new AbilityRegistry();
         registerCollectionAbilities(registry, pageCollection());
         const keys = registry.list().map((d) => d.key);
@@ -101,7 +109,47 @@ describe('registerCollectionAbilities', () => {
         expect(registry.size).toBe(14);
     });
 });
-describe('COLLECTION_ABILITY_VERBS / collectionAbilityKey', () => {
+describe('registerSingletonAbilities', () => {
+    it('registers exactly the four singleton abilities', () => {
+        const registry = new AbilityRegistry();
+        registerSingletonAbilities(registry, siteSettings());
+        expect(registry.list().map((descriptor) => descriptor.key)).toEqual([
+            'singletons.site-settings.read',
+            'singletons.site-settings.update',
+            'singletons.site-settings.publish',
+            'singletons.site-settings.changeStatus',
+        ]);
+    });
+    it('uses the singleton label and one singleton group', () => {
+        const registry = new AbilityRegistry();
+        registerSingletonAbilities(registry, siteSettings());
+        expect(registry.list().map((descriptor) => descriptor.label)).toEqual([
+            'Read Site settings',
+            'Update Site settings',
+            'Publish Site settings',
+            'Change status of Site settings',
+        ]);
+        expect(registry.byGroup().get('singletons.site-settings')).toHaveLength(4);
+    });
+    it('does not register collection-only verbs', () => {
+        const registry = new AbilityRegistry();
+        registerSingletonAbilities(registry, siteSettings());
+        expect(registry.has('singletons.site-settings.create')).toBe(false);
+        expect(registry.has('singletons.site-settings.delete')).toBe(false);
+        expect(registry.has('singletons.site-settings.reindex')).toBe(false);
+    });
+});
+describe('registerDocumentAbilities', () => {
+    it('dispatches both definition kinds into isolated ability families', () => {
+        const registry = new AbilityRegistry();
+        registerDocumentAbilities(registry, pageCollection());
+        registerDocumentAbilities(registry, siteSettings());
+        expect(registry.size).toBe(11);
+        expect(registry.byGroup().get('collections.pages')).toHaveLength(7);
+        expect(registry.byGroup().get('singletons.site-settings')).toHaveLength(4);
+    });
+});
+describe('ability verb contracts / documentAbilityKey', () => {
     it('COLLECTION_ABILITY_VERBS exposes the canonical verb list in registration order', () => {
         expect(COLLECTION_ABILITY_VERBS).toEqual([
             'read',
@@ -113,15 +161,45 @@ describe('COLLECTION_ABILITY_VERBS / collectionAbilityKey', () => {
             'reindex',
         ]);
     });
-    it('collectionAbilityKey composes a flat dotted key', () => {
-        expect(collectionAbilityKey('pages', 'publish')).toBe('collections.pages.publish');
-        expect(collectionAbilityKey('news', 'changeStatus')).toBe('collections.news.changeStatus');
+    it('SINGLETON_ABILITY_VERBS exposes the canonical verb list in registration order', () => {
+        expect(SINGLETON_ABILITY_VERBS).toEqual(['read', 'update', 'publish', 'changeStatus']);
+    });
+    it('composes a kind-aware flat dotted key from definitions and explicit descriptors', () => {
+        expect(documentAbilityKey(pageCollection(), 'publish')).toBe('collections.pages.publish');
+        expect(documentAbilityKey(siteSettings(), 'changeStatus')).toBe('singletons.site-settings.changeStatus');
+        expect(documentAbilityKey({ kind: 'collection', path: 'news' }, 'read')).toBe('collections.news.read');
+        expect(documentAbilityKey({ kind: 'singleton', path: 'navigation' }, 'update')).toBe('singletons.navigation.update');
+    });
+    it('preserves the deprecated collectionAbilityKey string-path contract', () => {
+        expect(collectionAbilityKey('news', 'read')).toBe('collections.news.read');
     });
     it('matches the keys produced by registerCollectionAbilities', () => {
         const registry = new AbilityRegistry();
-        registerCollectionAbilities(registry, pageCollection());
+        const definition = pageCollection();
+        registerCollectionAbilities(registry, definition);
         for (const verb of COLLECTION_ABILITY_VERBS) {
-            expect(registry.has(collectionAbilityKey('pages', verb))).toBe(true);
+            expect(registry.has(documentAbilityKey(definition, verb))).toBe(true);
         }
     });
+    it('matches the keys produced by registerSingletonAbilities', () => {
+        const registry = new AbilityRegistry();
+        const definition = siteSettings();
+        registerSingletonAbilities(registry, definition);
+        for (const verb of SINGLETON_ABILITY_VERBS) {
+            expect(registry.has(documentAbilityKey(definition, verb))).toBe(true);
+        }
+    });
+    it('rejects collection-only verbs for singleton descriptors at compile time and runtime', () => {
+        const singleton = siteSettings();
+        const compileOnlyInvalidCall = () => {
+            documentAbilityKey(singleton, 
+            // @ts-expect-error create is not a singleton ability verb
+            'create');
+        };
+        expect(compileOnlyInvalidCall).toBeTypeOf('function');
+        const untypedKey = documentAbilityKey;
+        expect(() => untypedKey(singleton, 'create')).toThrow(/verb 'create'.*singleton/);
+        expect(() => untypedKey(singleton, 'delete')).toThrow(/verb 'delete'.*singleton/);
+        expect(() => untypedKey(singleton, 'reindex')).toThrow(/verb 'reindex'.*singleton/);
+    });
 });

package/dist/codegen/fixtures/all-fields.expected.d.ts

@@ -122,3 +122,6 @@ export type CollectionFieldsAllLocalesByPath = {
     minimal: MinimalFieldsAllLocales;
 };
 export type CollectionPath = keyof CollectionFieldsByPath;
+export type SingletonFieldsByPath = Record<never, never>;
+export type SingletonFieldsAllLocalesByPath = Record<never, never>;
+export type SingletonPath = keyof SingletonFieldsByPath;

package/dist/codegen/index.d.ts

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { CollectionDefinition } from '../@types/index.js';
+import { type CollectionDefinition } from '../@types/index.js';
 /**
  * Emit deterministic application collection types from evaluated runtime definitions.
  * The returned hash is SHA-256 over the versioned format domain and generated module body.

package/dist/codegen/index.js

@@ -6,8 +6,9 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { createHash } from 'node:crypto';
-const FORMAT_VERSION = 2;
-const HASH_DOMAIN = '@byline/core/codegen:collection-types:v2\n';
+import { isSingleton, } from '../@types/index.js';
+const FORMAT_VERSION = 3;
+const HASH_DOMAIN = '@byline/core/codegen:collection-types:v3\n';
 const IMPORT_ORDER = ['JsonObject', 'JsonValue', 'RelatedDocumentValue', 'StoredFileValue'];
 function compareStrings(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
@@ -285,6 +286,8 @@ function emitBody(analysis) {
         alias: collectionNames.get(definition) ?? 'UnnamedFields',
         definition,
     }));
+    const multiCollectionContracts = collectionContracts.filter((collection) => !isSingleton(collection.definition));
+    const singletonContracts = collectionContracts.filter((collection) => isSingleton(collection.definition));
     const blockAliasByKey = new Map(blocks.map((block) => [block.key, block.alias]));
     function fieldSetType(fields, mode) {
         return objectType(fields.map((field) => ({
@@ -400,15 +403,25 @@ function emitBody(analysis) {
     for (const collection of [...collectionContracts].sort((a, b) => compareStrings(a.alias, b.alias))) {
         declarations.push(`export type ${collection.alias} = ${fieldSetType(collection.definition.fields, 'single').join('\n')}`, '', `export type ${collection.alias}AllLocales = ${fieldSetType(collection.definition.fields, 'all').join('\n')}`, '');
     }
-    declarations.push('export type CollectionFieldsByPath = {');
-    for (const collection of collectionContracts) {
-        declarations.push(`  ${propertyKey(collection.definition.path)}: ${collection.alias}`);
-    }
-    declarations.push('}', '', 'export type CollectionFieldsAllLocalesByPath = {');
-    for (const collection of collectionContracts) {
-        declarations.push(`  ${propertyKey(collection.definition.path)}: ${collection.alias}AllLocales`);
+    function emitRegistry(name, contracts, suffix) {
+        if (contracts.length === 0) {
+            declarations.push(`export type ${name} = {}`);
+            return;
+        }
+        declarations.push(`export type ${name} = {`);
+        for (const contract of contracts) {
+            declarations.push(`  ${propertyKey(contract.definition.path)}: ${contract.alias}${suffix}`);
+        }
+        declarations.push('}');
     }
-    declarations.push('}', '', 'export type CollectionPath = keyof CollectionFieldsByPath');
+    emitRegistry('CollectionFieldsByPath', multiCollectionContracts, '');
+    declarations.push('');
+    emitRegistry('CollectionFieldsAllLocalesByPath', multiCollectionContracts, 'AllLocales');
+    declarations.push('', 'export type CollectionPath = keyof CollectionFieldsByPath', '');
+    emitRegistry('SingletonFieldsByPath', singletonContracts, '');
+    declarations.push('');
+    emitRegistry('SingletonFieldsAllLocalesByPath', singletonContracts, 'AllLocales');
+    declarations.push('', 'export type SingletonPath = keyof SingletonFieldsByPath');
     const usedImports = IMPORT_ORDER.filter((name) => imports.has(name));
     const importLines = usedImports.length === 0
         ? []
@@ -424,16 +437,19 @@ function emitBody(analysis) {
         .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.
+    // Register the app's collection and singleton registries with @byline/client
+    // through a second declaration merge. Every bare `BylineClient` in the app's
+    // program — including the `@byline/client/server` getters — then resolves its
+    // collection generic to `CollectionFieldsByPath`. The singleton member is
+    // emitted now so Plan 3's parallel `RegisteredSingletons` fallback can resolve
+    // `SingletonFieldsByPath` through the same merge without runtime definitions.
+    // 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",
+        "    singletons: import('@byline/generated-types').SingletonFieldsByPath",
         '  }',
         '}',
     ];

package/dist/codegen/index.test.node.js

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineCollection, defineSingleton, } from '../@types/collection-types.js';
 import { AllFieldsCollection, AllFieldsCollections, } from './fixtures/all-fields.js';
 import { emitCollectionTypes } from './index.js';
 const fixtureDirectory = resolve(dirname(fileURLToPath(import.meta.url)), 'fixtures');
@@ -24,16 +25,19 @@ describe('emitCollectionTypes', () => {
         expectTypeOf().toEqualTypeOf();
         expectTypeOf().toEqualTypeOf();
         expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
     });
     it('emits a versioned header, verifiable body hash, and canonical formatting', () => {
         const { source, hash } = emitCollectionTypes([collection('plain', [])]);
         const body = source.split('\n').slice(4).join('\n');
-        expect(source).toMatch(/^\/\/ Generated by @byline\/core\/codegen\n\/\/ Format version: 2\n\/\/ Hash: [a-f0-9]{64}\n\n/);
-        expect(hash).toBe(createHash('sha256').update(`@byline/core/codegen:collection-types:v2\n${body}`).digest('hex'));
+        expect(source).toMatch(/^\/\/ Generated by @byline\/core\/codegen\n\/\/ Format version: 3\n\/\/ Hash: [a-f0-9]{64}\n\n/);
+        expect(hash).toBe(createHash('sha256').update(`@byline/core/codegen:collection-types:v3\n${body}`).digest('hex'));
         expect(source).toContain(`// Hash: ${hash}`);
         expect(source.endsWith('\n')).toBe(true);
         expect(source).not.toContain('\r');
         expect(source).not.toContain(';');
+        expect(source).toContain('  export type SingletonFieldsByPath = {}');
+        expect(source).toContain('  export type SingletonFieldsAllLocalesByPath = {}');
     });
     it('declares every type inside the @byline/generated-types augmentation block', () => {
         const { source } = emitCollectionTypes([collection('plain', [{ name: 'title', type: 'text' }])]);
@@ -49,10 +53,39 @@ describe('emitCollectionTypes', () => {
             "declare module '@byline/client' {",
             '  interface Register {',
             "    collections: import('@byline/generated-types').CollectionFieldsByPath",
+            "    singletons: import('@byline/generated-types').SingletonFieldsByPath",
             '  }',
             '}',
         ].join('\n'));
     });
+    it('partitions collection and singleton registries and registers both with the client', () => {
+        const definitions = [
+            defineCollection({
+                path: 'articles',
+                labels: { singular: 'Article', plural: 'Articles' },
+                fields: [{ name: 'title', type: 'text' }],
+            }),
+            defineSingleton({
+                path: 'site-settings',
+                label: 'Site settings',
+                fields: [{ name: 'siteName', type: 'text', localized: true }],
+            }),
+        ];
+        const { source } = emitCollectionTypes(definitions);
+        expect(source).toContain('export type SingletonPath = keyof SingletonFieldsByPath');
+        expect(source).toContain('export type CollectionPath = keyof CollectionFieldsByPath');
+        expect(source).toMatch(/export type SingletonFieldsByPath = \{[^}]*'site-settings'/);
+        expect(source).toMatch(/export type SingletonFieldsAllLocalesByPath = \{[^}]*'site-settings'/);
+        expect(source).not.toMatch(/export type CollectionFieldsByPath = \{[^}]*'site-settings'/);
+        expect(source).not.toMatch(/export type CollectionFieldsAllLocalesByPath = \{[^}]*'site-settings'/);
+        expect(source).toMatch(/export type CollectionFieldsByPath = \{[^}]*articles/);
+        expect(source).not.toMatch(/export type SingletonFieldsByPath = \{[^}]*articles/);
+        expect(source).toContain("singletons: import('@byline/generated-types').SingletonFieldsByPath");
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+    });
     it('sorts collections and declarations without changing field, select, or block union order', () => {
         const alpha = collection('alpha', [
             {

package/dist/config/attach-hooks.d.ts

@@ -1,11 +1,11 @@
-import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, FileField, ImageField, ServerHooksConfig, UploadHooks, UploadHooksLoader } from '../@types/index.js';
-type CollectionHookValue = CollectionHooks | CollectionHooksLoader;
+import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, FileField, ImageField, ServerHooksConfig, SingletonHooks, SingletonHooksLoader, UploadHooks, UploadHooksLoader } from '../@types/index.js';
+type DocumentHookValue = CollectionHooks | CollectionHooksLoader | SingletonHooks | SingletonHooksLoader;
 type UploadHookValue = UploadHooks | UploadHooksLoader;
 type UploadField = ImageField | FileField;
 export type HookAttachmentOperation = {
     kind: 'collection';
     target: CollectionDefinition;
-    hooks: CollectionHookValue | undefined;
+    hooks: DocumentHookValue | undefined;
 } | {
     kind: 'upload';
     target: UploadField;

package/dist/config/attach-hooks.js

@@ -1,3 +1,4 @@
+import { assertHooksMatchDefinition } from '../@types/collection-types.js';
 import { formatDeclarationPath, walkFieldDeclarations } from '../paths/index.js';
 const registryCollectionHooks = new WeakMap();
 const registryUploadHooks = new WeakMap();
@@ -61,6 +62,8 @@ export function commitHookAttachment(operations) {
 }
 function planCollectionAttachment(collection, requested, operations) {
     const owned = registryCollectionHooks.get(collection);
+    assertInlineHookFamily(collection, collection.hooks);
+    assertInlineHookFamily(collection, requested);
     assertOwnershipIntact(`collection "${collection.path}"`, collection.hooks, owned);
     if (requested === undefined) {
         if (owned !== undefined) {
@@ -75,6 +78,11 @@ function planCollectionAttachment(collection, requested, operations) {
         operations.push({ kind: 'collection', target: collection, hooks: requested });
     }
 }
+function assertInlineHookFamily(definition, hooks) {
+    if (hooks !== undefined && typeof hooks !== 'function') {
+        assertHooksMatchDefinition(definition, hooks);
+    }
+}
 function planUploadAttachment(path, field, requested, operations) {
     const owned = registryUploadHooks.get(field);
     assertOwnershipIntact(`upload field "${path}"`, field.upload?.hooks, owned);