@byline/core 4.15.0 → 4.17.0

package/dist/@types/admin-types.d.ts

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { BlockFieldData, CollectionDefinition, WorkflowStatus } from './collection-types.js';
+import type { BlockFieldData, MultiCollectionDefinition, SingletonDefinition, WorkflowStatus } from './collection-types.js';
 import type { Block, FieldComponentSlots, RichTextEditorComponent } from './field-types.js';
 /**
  * Props passed to a custom list-view component registered via
@@ -168,22 +168,23 @@ export interface FieldAdminConfig {
     editor?: RichTextEditorComponent;
 }
 /**
- * One labelled group of collections on the admin dashboard.
+ * One labelled group of document resources on the admin dashboard.
  *
  * Declared in display order on `AdminConfig.collectionGroups` and referenced by
- * `name` from `CollectionAdminConfig.group`. Array order is the order headings
- * appear on the dashboard; a group with no member collections is not rendered
+ * `name` from a collection or singleton admin config. The registry keeps its
+ * established `collectionGroups` name for compatibility. Array order is the order headings
+ * appear on the dashboard; a group with no member resources is not rendered
  * at all, so no heading ever sits above an empty section.
  */
 export interface CollectionGroupDefinition {
     /**
-     * Stable key referenced by `CollectionAdminConfig.group`. Boot-validated —
+     * Stable key referenced by an admin resource's `group`. Boot-validated —
      * a reference to an undeclared name throws at startup rather than silently
      * producing an extra heading.
      */
     name: string;
     /**
-     * Heading text rendered above this group's collections.
+     * Heading text rendered above this group's document resources.
      *
      * A plain string, deliberately not translated: `CollectionDefinition.labels`
      * are themselves rendered untranslated on the dashboard, so translating group
@@ -208,6 +209,44 @@ export interface PreviewDocument<F = any> {
     status: string;
     fields: F;
 }
+/** Minimal pathless document shape passed to `SingletonAdminConfig.preview.url`. */
+export interface SingletonPreviewDocument<F = any> {
+    id: string;
+    status: string;
+    fields: F;
+}
+/**
+ * Admin UI configuration consumed directly by Byline's form renderer.
+ *
+ * Collection-specific list, dashboard, and preview configuration belongs on
+ * {@link CollectionAdminConfig}; this base contains only the reusable form
+ * composition contract.
+ */
+export interface FormAdminConfig {
+    /** Named tab components. Each set is one tab bar. */
+    tabSets?: TabSetDefinition[];
+    /** Named horizontal-row layouts. */
+    rows?: RowDefinition[];
+    /** Named labelled-fieldset clusters. */
+    groups?: GroupDefinition[];
+    /**
+     * Composition: how the primitives above (and any raw schema fields) flow
+     * into the form's `main` and `sidebar` regions. When omitted, the
+     * renderer synthesises a default that places every schema field in
+     * `main` in declaration order.
+     */
+    layout?: LayoutDefinition;
+    /**
+     * Per-field rendering overrides, keyed by schema path: a top-level field
+     * name (`title`) or a dotted, index-free path through `group` / `array`
+     * structure fields (`files.filesGroup.publicationFile`). Paths address
+     * field *declarations*, never item instances (no `[0]` indices), and never
+     * traverse a `blocks` field — blocks take their overrides from the
+     * blockType-keyed `AdminConfig.blockAdmin` registry instead.
+     * Placement is no longer expressed here — see the layout primitives above.
+     */
+    fields?: Record<string, FieldAdminConfig>;
+}
 /**
  * Admin UI configuration for a collection.
  * This is the presentation/UI layer — separate from the data schema.
@@ -215,7 +254,9 @@ export interface PreviewDocument<F = any> {
  * Linked to a `CollectionDefinition` by `slug` matching the collection's
  * `path`.
  */
-export interface CollectionAdminConfig<T = any> {
+export interface CollectionAdminConfig<T = any> extends FormAdminConfig {
+    /** Explicit resource discriminator. Stamped by `defineAdmin`. */
+    singleton?: false;
     /** Must match the `path` of the corresponding `CollectionDefinition`. */
     slug: string;
     /**
@@ -281,29 +322,6 @@ export interface CollectionAdminConfig<T = any> {
     itemViewSort?: ListDefaultSort<T>;
     /** Default columns to show when no explicit column config is provided. */
     defaultColumns?: string[];
-    /** Named tab components. Each set is one tab bar. */
-    tabSets?: TabSetDefinition[];
-    /** Named horizontal-row layouts. */
-    rows?: RowDefinition[];
-    /** Named labelled-fieldset clusters. */
-    groups?: GroupDefinition[];
-    /**
-     * Composition: how the primitives above (and any raw schema fields) flow
-     * into the form's `main` and `sidebar` regions. When omitted, the
-     * renderer synthesises a default that places every schema field in
-     * `main` in declaration order.
-     */
-    layout?: LayoutDefinition;
-    /**
-     * Per-field rendering overrides, keyed by schema path: a top-level field
-     * name (`title`) or a dotted, index-free path through `group` / `array`
-     * structure fields (`files.filesGroup.publicationFile`). Paths address
-     * field *declarations*, never item instances (no `[0]` indices), and never
-     * traverse a `blocks` field — blocks take their overrides from the
-     * blockType-keyed `AdminConfig.blockAdmin` registry instead.
-     * Placement is no longer expressed here — see the layout primitives above.
-     */
-    fields?: Record<string, FieldAdminConfig>;
     /**
      * Preview URL configuration for the admin's live-preview affordance
      * (`<PreviewLink>` icon on the document edit page header). When omitted,
@@ -411,6 +429,38 @@ export interface CollectionAdminConfig<T = any> {
      */
     listActions?: Array<(props: ListActionComponentProps) => any>;
 }
+/** Admin UI configuration for a singleton document resource. */
+export interface SingletonAdminConfig<T = any> extends FormAdminConfig {
+    /** Explicit resource discriminator. Stamped by `defineSingletonAdmin`. */
+    singleton: true;
+    /** Must match the `path` of the corresponding `SingletonDefinition`. */
+    slug: string;
+    /**
+     * Dashboard group this resource belongs to. The registry remains named
+     * `AdminConfig.collectionGroups` for backwards compatibility.
+     */
+    group?: string;
+    /**
+     * Explicit public preview URL for the singleton's site-wide effect.
+     * Unlike collection previews, no internal document path is available or
+     * used as a fallback.
+     */
+    preview?: {
+        url: (doc: SingletonPreviewDocument<T>, ctx: {
+            locale?: string;
+        }) => string | null;
+    };
+    /** Collection-list options are invalid for a cardinality-one resource. */
+    columns?: never;
+    defaultSort?: never;
+    defaultColumns?: never;
+    itemView?: never;
+    itemViewSort?: never;
+    listView?: never;
+    listActions?: never;
+}
+/** Admin presentation config for either registered document-resource kind. */
+export type AdminResourceConfig<T = any> = CollectionAdminConfig<T> | SingletonAdminConfig<T>;
 /**
  * Props passed to each `CollectionAdminConfig.listActions` component. Kept
  * minimal and framework-agnostic (`@byline/core` is React-free); components
@@ -424,7 +474,12 @@ export interface ListActionComponentProps {
  * Type-safe factory for creating a `CollectionAdminConfig` linked to a schema.
  * Sets `slug` from the schema's `path`.
  */
-export declare function defineAdmin<T = any>(schema: CollectionDefinition, config: Omit<CollectionAdminConfig<T>, 'slug'>): CollectionAdminConfig<T>;
+export declare function defineAdmin<T = any>(schema: MultiCollectionDefinition, config: Omit<CollectionAdminConfig<T>, 'slug' | 'singleton'>): CollectionAdminConfig<T>;
+/**
+ * Type-safe factory for a `SingletonAdminConfig` linked to a singleton schema.
+ * Sets both the schema path and resource discriminator for authors.
+ */
+export declare function defineSingletonAdmin<T = any>(schema: SingletonDefinition, config: Omit<SingletonAdminConfig<T>, 'slug' | 'singleton'>): SingletonAdminConfig<T>;
 /**
  * Admin UI configuration for a block — the block-scoped analogue of
  * `CollectionAdminConfig`, carrying **rendering overrides only**.

package/dist/@types/admin-types.js

@@ -11,8 +11,20 @@
  */
 export function defineAdmin(schema, config) {
     return {
+        ...config,
+        singleton: false,
         slug: schema.path,
+    };
+}
+/**
+ * Type-safe factory for a `SingletonAdminConfig` linked to a singleton schema.
+ * Sets both the schema path and resource discriminator for authors.
+ */
+export function defineSingletonAdmin(schema, config) {
+    return {
         ...config,
+        singleton: true,
+        slug: schema.path,
     };
 }
 /**

package/dist/@types/collection-types.d.ts

@@ -483,6 +483,60 @@ export interface AfterUpdateContext {
         locale: string;
     };
 }
+/** The public singleton operation represented by a save-hook invocation. */
+export type SingletonSaveOperation = {
+    type: 'save';
+} | {
+    type: 'restore';
+    sourceVersionId: string;
+} | {
+    type: 'copyToLocale';
+    sourceLocale: string;
+    targetLocale: string;
+    overwrite: boolean;
+};
+/**
+ * Context passed to a singleton's `beforeSave` hooks.
+ *
+ * The hook runs inside the singleton transaction after the slot lock and
+ * current-value read. It may mutate `data` before the next immutable version
+ * is written. `documentId` and `originalData` are `null` only for the first
+ * materialising save.
+ *
+ * Restore carries the complete all-locale field tree with `locale: 'all'`.
+ * Copy-to-locale carries the merged target payload and the target locale's
+ * prior values; it never exposes the raw source-locale payload as `data`.
+ */
+export interface BeforeSingletonSaveContext {
+    data: Record<string, any>;
+    originalData: Record<string, any> | null;
+    singletonPath: string;
+    locale: string;
+    requestContext: RequestContext;
+    isInitialSave: boolean;
+    operation: SingletonSaveOperation;
+    documentId: string | null;
+}
+/**
+ * Context passed to a singleton's `afterSave` hooks after the save transaction
+ * commits. A hook failure rejects the public call but cannot roll back the
+ * persisted document version or initial slot mapping.
+ *
+ * Public-cache invalidation is deliberately host-owned rather than automatic.
+ * Hosts commonly invalidate preview caches after every save and public caches
+ * only when publication changes, using the status hooks for the latter.
+ */
+export interface AfterSingletonSaveContext {
+    data: Record<string, any>;
+    originalData: Record<string, any> | null;
+    singletonPath: string;
+    locale: string;
+    requestContext: RequestContext;
+    isInitialSave: boolean;
+    operation: SingletonSaveOperation;
+    documentId: string;
+    documentVersionId: string;
+}
 /**
  * Context passed to `afterSystemFieldsChange` after a non-versioned document
  * path and/or advertised-locale change commits successfully.
@@ -829,11 +883,11 @@ export interface AfterReadContext {
  * `LEFT JOIN LATERAL` SQL machinery the client's existing `where` parser
  * emits, then ANDs onto whatever the caller passed in `where`.
  *
- * Returning `undefined` (or simply `void`) means "no scoping" — typically
- * the superuser / unconditional-read branch. Return `{ id: { $in: [] } }`
- * when the actor cannot read anything; it compiles to an always-false SQL
- * predicate without passing an invalid UUID to Postgres. Do not throw, because
- * callers expect empty list results rather than collapsed endpoints.
+ * Returning `undefined` (or `void`) means "no scoping" — typically the
+ * superuser / unconditional-read branch. Return `false` when the actor cannot
+ * read anything; it normalises to `{ id: { $in: [] } }` and compiles to an
+ * always-false SQL predicate without passing an invalid UUID to the database.
+ * Do not throw, because callers expect empty results rather than collapsed endpoints.
  *
  * The hook receives:
  *   - `requestContext` — the authenticated request, including `actor`. The
@@ -845,7 +899,7 @@ export interface AfterReadContext {
  *     same hook function is reused across collections).
  *
  * See `docs/07-auth-and-security/01-authn-authz.md` for the strategic rationale; the Quick
- * Reference there carries six worked recipes.
+ * Reference there carries seven worked recipes.
  */
 export interface BeforeReadContext {
     collectionPath: string;
@@ -854,17 +908,19 @@ export interface BeforeReadContext {
 }
 /**
  * A `beforeRead` hook function. Returns a `QueryPredicate` to scope the
- * query, or `void`/`undefined` to apply no scoping. May be async — actors
- * needing tenant lookups or role-metadata fetches commonly are.
+ * query, `false` to deny every row, or `void`/`undefined` to apply no
+ * scoping. May be async — actors needing tenant lookups or role-metadata
+ * fetches commonly are.
  */
-export type BeforeReadHookFn = (ctx: BeforeReadContext) => QueryPredicate | void | Promise<QueryPredicate | void>;
+export type BeforeReadHookFn = (ctx: BeforeReadContext) => QueryPredicate | false | void | Promise<QueryPredicate | false | void>;
 /**
  * Slot type for `beforeRead`.
  *
  * Distinct from the generic `CollectionHookSlot` because `beforeRead`
  * returns a value (a predicate). When multiple hook functions are
  * configured, their predicates are combined with implicit AND in
- * declaration order; functions that return `void` are skipped.
+ * declaration order; `false` remains restrictive in any position, and
+ * functions that return `void` are skipped.
  */
 export type BeforeReadHookSlot = BeforeReadHookFn | BeforeReadHookFn[];
 /**
@@ -952,6 +1008,31 @@ export interface CollectionHooks {
      */
     afterRead?: CollectionHookSlot<AfterReadContext>;
 }
+/** A singleton-hook function signature, parameterised by context type. */
+export type SingletonHookFn<Ctx> = (ctx: Ctx) => void | Promise<void>;
+/** A singleton hook slot: one function or an ordered array of functions. */
+export type SingletonHookSlot<Ctx> = SingletonHookFn<Ctx> | SingletonHookFn<Ctx>[];
+/**
+ * Lifecycle hooks for a singleton document slot.
+ *
+ * The family describes public singleton operations rather than the internal
+ * create/update branch used to persist them. `beforeSave` runs inside the
+ * locked transaction and may mutate `data`; `afterSave` runs only after that
+ * transaction commits. Read, status, and unpublish hooks retain the shared
+ * document contracts.
+ */
+export interface SingletonHooks {
+    /** Runs for every singleton save, including initial materialisation. */
+    beforeSave?: SingletonHookSlot<BeforeSingletonSaveContext>;
+    /** Runs after every singleton save commits. See its cache-invalidation JSDoc. */
+    afterSave?: SingletonHookSlot<AfterSingletonSaveContext>;
+    beforeStatusChange?: SingletonHookSlot<StatusChangeContext>;
+    afterStatusChange?: SingletonHookSlot<StatusChangeContext>;
+    beforeUnpublish?: SingletonHookSlot<BeforeUnpublishContext>;
+    afterUnpublish?: SingletonHookSlot<AfterUnpublishContext>;
+    beforeRead?: BeforeReadHookSlot;
+    afterRead?: SingletonHookSlot<AfterReadContext>;
+}
 /**
  * A lazy loader for a collection's hooks — the function form of
  * `CollectionDefinition.hooks`. Returns the `CollectionHooks` object, or a
@@ -965,6 +1046,11 @@ export interface CollectionHooks {
  * server-only code through `ServerConfig.hooks.collections` from a server-only
  * entry instead.
  *
+ * The loader remains lazy, so its returned family cannot be inspected during
+ * startup. A mismatched family fails on first lifecycle use instead. The
+ * import result is cached, but {@link resolveHooks} repeats family validation
+ * for the current definition on every call, including cache hits.
+ *
  * @example
  * // docs.schema.ts — only for isomorphic-safe hooks
  * export const Docs = defineCollection({
@@ -982,7 +1068,26 @@ export type CollectionHooksLoader = () => Promise<CollectionHooks | {
     default: CollectionHooks;
 }>;
 /**
- * Resolve a collection's `hooks` to a concrete `CollectionHooks` object.
+ * A lazy loader for a singleton's hooks.
+ *
+ * Loaders remain lazy: their returned family is validated on first lifecycle
+ * use, not at startup, because eagerly importing server hook modules would
+ * defeat the loader boundary. The import result is cached by loader identity,
+ * but family validation still runs against the current definition on every
+ * {@link resolveHooks} call so one reused loader cannot bypass the kind check.
+ */
+export type SingletonHooksLoader = () => Promise<SingletonHooks | {
+    default: SingletonHooks;
+}>;
+type ResolvedDocumentHooks = CollectionHooks & SingletonHooks;
+/**
+ * Assert that an inspected hook object belongs to the definition's resource
+ * family. Inline objects are checked during startup attachment; lazily loaded
+ * objects are checked by {@link resolveHooks} on every resolution.
+ */
+export declare function assertHooksMatchDefinition(definition: CollectionDefinition, hooks: CollectionHooks | SingletonHooks): void;
+/**
+ * Resolve a document definition's `hooks` to a concrete, validated hook object.
  *
  * - The inline-object form (`hooks: { … }`) is returned as-is.
  * - The loader form (`hooks: () => import('./docs.hooks.js')`) is invoked
@@ -991,9 +1096,14 @@ export type CollectionHooksLoader = () => Promise<CollectionHooks | {
  *   through here, so a loader's dynamic `import()` runs at most once per
  *   process regardless of how many documents flow through it.
  *
+ * Inline families are also validated during startup attachment. A loader
+ * cannot be inspected without importing it, so a mismatched loader fails on
+ * first lifecycle use rather than at boot. Validation runs on every call,
+ * including cache hits, against the current definition.
+ *
  * Returns `undefined` when no hooks are declared.
  */
-export declare function resolveHooks(definition: CollectionDefinition): Promise<CollectionHooks | undefined>;
+export declare function resolveHooks(definition: CollectionDefinition): Promise<ResolvedDocumentHooks | undefined>;
 /**
  * Type-safe factory for authoring a collection's hooks in a separate
  * module (the loader form: `hooks: () => import('./docs.hooks.js')`).
@@ -1014,15 +1124,34 @@ export declare function resolveHooks(definition: CollectionDefinition): Promise<
  * })
  */
 export declare function defineHooks(hooks: CollectionHooks): CollectionHooks;
-export interface CollectionDefinition {
-    labels: {
-        singular: string;
-        plural: string;
-    };
+/** Fields and lifecycle configuration shared by every document resource kind. */
+export interface DocumentDefinitionBase {
     path: string;
     fields: Field[];
     /** Sequential workflow configuration. Falls back to DEFAULT_WORKFLOW if omitted. */
     workflow?: WorkflowConfig;
+    /**
+     * Optional explicit version pin. When omitted, the startup bootstrap
+     * auto-increments the collection's stored version any time the schema
+     * fingerprint changes. When set, the value is used verbatim as long as it
+     * is >= the currently-stored version; pinning backwards throws at startup.
+     *
+     * The stamped version is written onto every `documentVersions` row so that
+     * a document can later be resolved against the schema shape it was
+     * authored under.
+     */
+    version?: number;
+}
+/** A collection of many documents — Byline's original and default resource kind. */
+export interface MultiCollectionDefinition extends DocumentDefinitionBase {
+    /** Absent or `false` on a multi-document collection. */
+    singleton?: false;
+    labels: {
+        singular: string;
+        plural: string;
+    };
+    /** A multi-document collection uses `labels`, never the singleton's `label`. */
+    label?: never;
     /**
      * Lifecycle hooks for server-side document operations.
      *
@@ -1231,30 +1360,82 @@ export interface CollectionDefinition {
      * docs/04-collections/04-document-trees.md.
      */
     tree?: boolean;
+}
+/**
+ * A single named document slot for an installation. Cardinality is
+ * zero-or-one: the slot exists as soon as the definition is registered, and
+ * its document is materialised by the first save.
+ *
+ * Collection-only options are absent by construction: there is no list to sort,
+ * search, or paginate, no sibling documents to order or arrange in a tree, and
+ * no public slug (`path` is internal metadata; see the design spec).
+ */
+export interface SingletonDefinition extends DocumentDefinitionBase {
+    singleton: true;
+    /** Singular display label. A singleton has no plural form. */
+    label: string;
     /**
-     * Optional explicit version pin. When omitted, the startup bootstrap
-     * auto-increments the collection's stored version any time the schema
-     * fingerprint changes. When set, the value is used verbatim as long as it
-     * is >= the currently-stored version; pinning backwards throws at startup.
-     *
-     * The stamped version is written onto every `documentVersions` row so that
-     * a document can later be resolved against the schema shape it was
-     * authored under.
+     * Singleton lifecycle hooks, expressed as save/read/workflow operations.
+     * Inline objects are family-validated at startup. A loader remains lazy and
+     * is therefore family-validated on first lifecycle use and every subsequent
+     * resolution, including cache hits shared with another definition.
      */
-    version?: number;
+    hooks?: SingletonHooks | SingletonHooksLoader;
+    /**
+     * Collection-only members remain explicit `never` properties rather than
+     * being omitted. Without them, `defineSingleton`'s generic parameter can
+     * absorb excess properties and collection-only configuration would pass at
+     * the definition site.
+     */
+    labels?: never;
+    useAsTitle?: never;
+    useAsPath?: never;
+    orderable?: never;
+    tree?: never;
+    search?: never;
+    listSearch?: never;
+    advertiseLocales?: never;
+    showStats?: never;
+    linksInEditor?: never;
+    buildDocumentPath?: never;
 }
+/** A registered multi-document collection or singleton document slot. */
+export type CollectionDefinition = MultiCollectionDefinition | SingletonDefinition;
 /**
  * Type-safe factory for creating a CollectionDefinition.
  * Returns the definition as-is but provides type checking.
  */
-export declare function defineCollection<const C extends CollectionDefinition>(definition: C & CollectionDefinition): C;
+export declare function defineCollection<const C extends MultiCollectionDefinition>(definition: C & MultiCollectionDefinition): C;
+/**
+ * Type-safe factory for a singleton definition. Adds the `singleton: true`
+ * discriminant so authors never write it themselves, and locks in literal
+ * types for `path` and field names so the generated path registries resolve
+ * precisely. Mirrors `defineCollection`.
+ */
+export declare function defineSingleton<const S extends Omit<SingletonDefinition, 'singleton'>>(definition: S & Omit<SingletonDefinition, 'singleton'>): S & {
+    singleton: true;
+};
+/** Narrows a definition to the singleton variant. */
+export declare function isSingleton(definition: CollectionDefinition): definition is SingletonDefinition;
 export type CollectionFieldData<C extends CollectionDefinition> = FieldSetData<C['fields']>;
 export type CollectionFieldDataAllLocales<C extends CollectionDefinition> = FieldSetDataAllLocales<C['fields']>;
 /** Broad collection registry used when an application has not supplied its schema types. */
 export type CollectionRegistry = Record<string, Record<string, any>>;
-/** Infer a path-to-fields registry from a shared readonly collection-definition tuple. */
+/** Infer the multi-collection path-to-fields registry from a shared definition tuple. */
 export type InferCollectionRegistry<TCollections extends readonly CollectionDefinition[]> = {
-    [TCollection in TCollections[number] as TCollection['path']]: CollectionFieldData<TCollection>;
+    [TCollection in TCollections[number] as TCollection extends SingletonDefinition ? never : TCollection['path']]: CollectionFieldData<TCollection>;
+};
+/** Infer the all-locale multi-collection registry from a shared definition tuple. */
+export type InferCollectionRegistryAllLocales<TCollections extends readonly CollectionDefinition[]> = {
+    [TCollection in TCollections[number] as TCollection extends SingletonDefinition ? never : TCollection['path']]: CollectionFieldDataAllLocales<TCollection>;
+};
+/** Infer the singleton path-to-fields registry from a shared definition tuple. */
+export type InferSingletonRegistry<TCollections extends readonly CollectionDefinition[]> = {
+    [TCollection in TCollections[number] as TCollection extends SingletonDefinition ? TCollection['path'] : never]: CollectionFieldData<TCollection>;
+};
+/** Infer the all-locale singleton registry from a shared definition tuple. */
+export type InferSingletonRegistryAllLocales<TCollections extends readonly CollectionDefinition[]> = {
+    [TCollection in TCollections[number] as TCollection extends SingletonDefinition ? TCollection['path'] : never]: CollectionFieldDataAllLocales<TCollection>;
 };
 /**
  * Type-safe factory for creating a Block. Returns the definition as-is,
@@ -1340,3 +1521,4 @@ export type CollectionDataAllLocales<C extends CollectionDefinition> = Prettify<
     created_at: Date;
     updated_at: Date;
 } & CollectionFieldDataAllLocales<C>>;
+export {};

package/dist/@types/collection-types.js

@@ -175,8 +175,46 @@ export function normalizeCollectionHook(hook) {
     return Array.isArray(hook) ? hook : [hook];
 }
 const resolvedHooksCache = new WeakMap();
+function completeHookNames() {
+    return (names) => names;
+}
+const COLLECTION_ONLY_HOOK_NAMES = completeHookNames()([
+    'beforeCreate',
+    'afterCreate',
+    'beforeUpdate',
+    'afterUpdate',
+    'afterSystemFieldsChange',
+    'beforeDelete',
+    'afterDelete',
+    'afterTreeChange',
+]);
+const SINGLETON_ONLY_HOOK_NAMES = completeHookNames()([
+    'beforeSave',
+    'afterSave',
+]);
 /**
- * Resolve a collection's `hooks` to a concrete `CollectionHooks` object.
+ * Assert that an inspected hook object belongs to the definition's resource
+ * family. Inline objects are checked during startup attachment; lazily loaded
+ * objects are checked by {@link resolveHooks} on every resolution.
+ */
+export function assertHooksMatchDefinition(definition, hooks) {
+    const record = hooks;
+    if (isSingleton(definition)) {
+        for (const name of COLLECTION_ONLY_HOOK_NAMES) {
+            if (record[name] !== undefined) {
+                throw new Error(`Singleton "${definition.path}" cannot use collection hook "${name}".`);
+            }
+        }
+        return;
+    }
+    for (const name of SINGLETON_ONLY_HOOK_NAMES) {
+        if (record[name] !== undefined) {
+            throw new Error(`Collection "${definition.path}" cannot use singleton hook "${name}".`);
+        }
+    }
+}
+/**
+ * Resolve a document definition's `hooks` to a concrete, validated hook object.
  *
  * - The inline-object form (`hooks: { … }`) is returned as-is.
  * - The loader form (`hooks: () => import('./docs.hooks.js')`) is invoked
@@ -185,18 +223,27 @@ const resolvedHooksCache = new WeakMap();
  *   through here, so a loader's dynamic `import()` runs at most once per
  *   process regardless of how many documents flow through it.
  *
+ * Inline families are also validated during startup attachment. A loader
+ * cannot be inspected without importing it, so a mismatched loader fails on
+ * first lifecycle use rather than at boot. Validation runs on every call,
+ * including cache hits, against the current definition.
+ *
  * Returns `undefined` when no hooks are declared.
  */
 export async function resolveHooks(definition) {
     const hooks = definition.hooks;
-    if (typeof hooks !== 'function')
+    if (typeof hooks !== 'function') {
+        if (hooks !== undefined)
+            assertHooksMatchDefinition(definition, hooks);
         return hooks;
-    const cached = resolvedHooksCache.get(hooks);
-    if (cached)
-        return cached;
-    const loaded = await hooks();
-    const resolved = 'default' in loaded ? loaded.default : loaded;
-    resolvedHooksCache.set(hooks, resolved);
+    }
+    let resolved = resolvedHooksCache.get(hooks);
+    if (resolved === undefined) {
+        const loaded = await hooks();
+        resolved = ('default' in loaded ? loaded.default : loaded);
+        resolvedHooksCache.set(hooks, resolved);
+    }
+    assertHooksMatchDefinition(definition, resolved);
     return resolved;
 }
 /**
@@ -228,6 +275,19 @@ export function defineHooks(hooks) {
 export function defineCollection(definition) {
     return definition;
 }
+/**
+ * Type-safe factory for a singleton definition. Adds the `singleton: true`
+ * discriminant so authors never write it themselves, and locks in literal
+ * types for `path` and field names so the generated path registries resolve
+ * precisely. Mirrors `defineCollection`.
+ */
+export function defineSingleton(definition) {
+    return { ...definition, singleton: true };
+}
+/** Narrows a definition to the singleton variant. */
+export function isSingleton(definition) {
+    return definition.singleton === true;
+}
 // ---------------------------------------------------------------------------
 // Block helpers — mirrors of defineCollection / CollectionFieldData / etc.
 // ---------------------------------------------------------------------------