@dereekb/dbx-cli 13.11.17 → 13.12.0

package/src/lib/mcp-scan/manifest/load-tokens-registry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadTokenManifests}, and {@link createTokenRegistry}.
+ *
+ * Resolves the bundled token manifests that ship inside this package's
+ * `generated/` directory and merges them with any external sources
+ * declared in `dbx-mcp.config.json` under either `tokens.sources` (full
+ * manifest paths) or `tokens.scan[].out` (paths produced by a downstream
+ * app's own scan run).
+ *
+ * The resulting {@link TokenRegistry} is the data the
+ * `dbx_css_token_lookup` and `dbx_ui_smell_check` tools and the tokens
+ * resource read from. All I/O is injectable so unit tests can drive every
+ * branch without touching disk.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type TokenRegistry } from '../registry/tokens-runtime.js';
+import { type TokenLoaderWarning, type TokenManifestReadFile } from './tokens-loader.js';
+/**
+ * Function shape used by {@link loadTokenRegistry} to enumerate the
+ * bundled token manifest paths shipped with this package.
+ */
+export type BundledTokenManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadTokenRegistry}.
+ */
+export interface LoadTokenRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledTokenManifestPathsFactory;
+    readonly readFile?: TokenManifestReadFile;
+}
+/**
+ * Outcome from {@link loadTokenRegistry}. Surfaces both the registry and
+ * the loader warnings so callers (the server bootstrap) can log anything
+ * that fell through warn-and-skip.
+ */
+export interface LoadTokenRegistryResult {
+    readonly registry: TokenRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly TokenLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged tokens registry for the current MCP server.
+ *
+ * Bundled manifests load as strict sources — a malformed or missing bundled
+ * file is a build-time bug, not a configuration problem. External manifests
+ * declared in `dbx-mcp.config.json` (`tokens.sources` plus `tokens.scan[].out`)
+ * load as non-strict sources so a single bad downstream manifest does not
+ * take the registry down.
+ *
+ * Returns an {@link EMPTY_TOKEN_REGISTRY} with surfaced warnings when neither
+ * bundled nor external manifests yield any successful load. The caller is
+ * responsible for deciding whether an empty registry is a fatal startup
+ * error.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadTokenRegistry(input: LoadTokenRegistryInput): Promise<LoadTokenRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing at
+ * the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled token manifests.
+ */
+export declare function getDefaultBundledTokenManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-ui-components-registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadUiComponentManifests}, and {@link createUiComponentRegistry}.
+ *
+ * Resolves the bundled `@dereekb/*` ui-components manifests that ship inside
+ * this package's `generated/` directory and merges them with any external
+ * sources declared in `dbx-mcp.config.json` under `uiComponents.sources`.
+ * The resulting {@link UiComponentRegistry} is the data the lookup-ui /
+ * search-ui tools and the registry resource read from.
+ *
+ * All I/O is injectable so unit tests can drive every branch without touching
+ * disk. The default `bundledManifestPaths` factory uses `import.meta.url` to
+ * locate the package's `generated/` directory regardless of whether the
+ * caller imports the source or the bundled binary.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type UiComponentRegistry } from '../registry/ui-components-runtime.js';
+import { type UiComponentLoaderWarning, type UiComponentManifestReadFile } from './ui-components-loader.js';
+/**
+ * Function shape used by {@link loadUiComponentRegistry} to enumerate the
+ * bundled `@dereekb/*` manifest paths shipped with this package. Defaults to
+ * the JSON files inside the package's `generated/` directory.
+ */
+export type BundledUiManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadUiComponentRegistry}.
+ */
+export interface LoadUiComponentRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledUiManifestPathsFactory;
+    readonly readFile?: UiComponentManifestReadFile;
+}
+/**
+ * Outcome from {@link loadUiComponentRegistry}. Surfaces both the registry
+ * and the loader warnings so callers (the server bootstrap) can log anything
+ * that fell through warn-and-skip.
+ */
+export interface LoadUiComponentRegistryResult {
+    readonly registry: UiComponentRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly UiComponentLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged ui-components registry for the current MCP server.
+ *
+ * Bundled `@dereekb/*` manifests load as strict sources — a malformed or
+ * missing bundled file is a build-time bug, not a configuration problem.
+ * External manifests declared in `dbx-mcp.config.json` load as non-strict
+ * sources so a single bad downstream manifest does not take the registry
+ * down.
+ *
+ * Returns an {@link EMPTY_UI_COMPONENT_REGISTRY} with surfaced warnings
+ * when neither bundled nor external manifests yield any successful load —
+ * the loader's "zero successful manifests" guard. The caller is responsible
+ * for deciding whether an empty registry is a fatal startup error.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadUiComponentRegistry(input: LoadUiComponentRegistryInput): Promise<LoadUiComponentRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing at
+ * the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled `@dereekb/*` manifests.
+ */
+export declare function getDefaultBundledUiManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/load-utils-registry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Server-side composition of {@link findAndLoadConfig},
+ * {@link loadUtilManifests}, and {@link createUtilRegistry}.
+ *
+ * Resolves the bundled `@dereekb/*` utils manifests that ship inside this
+ * package's `generated/` directory and merges them with any external
+ * sources declared in `dbx-mcp.config.json` under `utils.sources`. The
+ * resulting {@link UtilRegistry} is the data the `dbx_util_lookup` and
+ * `dbx_util_search` tools read from.
+ *
+ * All I/O is injectable so unit tests can drive every branch without
+ * touching disk. The default `bundledManifestPaths` factory uses
+ * `import.meta.url` to locate the package's `generated/` directory
+ * regardless of whether the caller imports the source or the bundled
+ * binary.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ConfigWarning } from '../config/load-config.js';
+import { type UtilRegistry } from '../registry/utils-runtime.js';
+import { type UtilLoaderWarning, type UtilManifestReadFile } from './utils-loader.js';
+/**
+ * Function shape used by {@link loadUtilRegistry} to enumerate the bundled
+ * `@dereekb/*` manifest paths shipped with this package. Defaults to the
+ * JSON files inside the package's `generated/` directory.
+ */
+export type BundledUtilManifestPathsFactory = () => readonly string[];
+/**
+ * Input to {@link loadUtilRegistry}.
+ */
+export interface LoadUtilRegistryInput {
+    readonly cwd: string;
+    readonly bundledManifestPaths?: BundledUtilManifestPathsFactory;
+    readonly readFile?: UtilManifestReadFile;
+}
+/**
+ * Outcome from {@link loadUtilRegistry}. Surfaces both the registry and
+ * the loader warnings so callers (the server bootstrap) can log anything
+ * that fell through warn-and-skip.
+ */
+export interface LoadUtilRegistryResult {
+    readonly registry: UtilRegistry;
+    readonly configPath: Maybe<string>;
+    readonly configWarnings: readonly ConfigWarning[];
+    readonly loaderWarnings: readonly UtilLoaderWarning[];
+    readonly externalSourceCount: number;
+}
+/**
+ * Loads the merged utils registry for the current MCP server.
+ *
+ * Bundled `@dereekb/*` manifests load as non-strict sources because not
+ * every package may have @dbxUtil-tagged exports yet — a missing bundled
+ * file should warn and skip rather than fail server startup. External
+ * manifests declared in `dbx-mcp.config.json` likewise load as non-strict
+ * sources so a single bad downstream manifest does not take the registry
+ * down.
+ *
+ * Returns an {@link EMPTY_UTIL_REGISTRY} with surfaced warnings when
+ * neither bundled nor external manifests yield any successful load — the
+ * loader's "zero successful manifests" guard is caught and translated
+ * into an empty registry so a workspace that hasn't run
+ * `generate-manifests` yet still boots.
+ *
+ * @param input - Cwd plus optional injected bundled-path factory and reader.
+ * @returns The registry, the resolved config path (if any), and any warnings.
+ */
+export declare function loadUtilRegistry(input: LoadUtilRegistryInput): Promise<LoadUtilRegistryResult>;
+/**
+ * Re-exported so callers can build a deterministic test fixture pointing
+ * at the package's bundled manifests without touching `import.meta.url`.
+ *
+ * @returns The absolute paths of the bundled `@dereekb/*` manifests.
+ */
+export declare function getDefaultBundledUtilManifestPaths(): readonly string[];

package/src/lib/mcp-scan/manifest/loader.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Loader for semantic-types manifests.
+ *
+ * Reads one or more manifest files (bundled `@dereekb/*` registries plus any
+ * downstream-app manifests discovered via `dbx-mcp.config.json`), validates
+ * them against {@link SemanticTypeManifest}, and merges them into a single
+ * lookup-ready registry.
+ *
+ * The loader never performs file I/O directly inside the merge logic — all
+ * reads go through an injectable `readFile` so loader tests run entirely
+ * in-memory. Only `defaultReadFile` (and any caller-supplied alternative)
+ * touches the disk.
+ *
+ * Failure handling is split between *strict* and non-strict sources:
+ *   - **Strict** sources (default for `origin: 'bundled'`) throw on any
+ *     parse, version, or schema failure — these failures indicate a build
+ *     bug, not a configuration problem.
+ *   - **Non-strict** sources (default for `origin: 'external'`) emit a
+ *     {@link LoaderWarning} and are skipped, so a single malformed
+ *     downstream manifest does not take the registry down.
+ *
+ * If no source loads successfully (every source failed warn-and-skip) the
+ * loader throws — silent empty registries are the worst failure mode.
+ */
+import { type SemanticTypeEntry } from './semantic-types-schema.js';
+/**
+ * One manifest the loader is asked to ingest. `path` must be absolute (the
+ * caller is responsible for resolving any repo-relative `dbx-mcp.config.json`
+ * entries against the config file's directory before invoking the loader).
+ *
+ * `strict` defaults to `true` for `origin: 'bundled'` and `false` for
+ * `origin: 'external'`. Override the default to e.g. enforce strict
+ * validation on a known-good external source during CI.
+ */
+export interface ManifestSource {
+    readonly origin: 'bundled' | 'external';
+    readonly path: string;
+    readonly strict?: boolean;
+}
+/**
+ * Function shape used by the loader to read manifest contents. Defaults to
+ * `node:fs/promises.readFile(path, 'utf-8')` when not supplied. Tests
+ * inject a Map-backed implementation so they can drive the loader without
+ * touching disk.
+ */
+export type ManifestReadFile = (absolutePath: string) => Promise<string>;
+/**
+ * Input to {@link loadSemanticTypeManifests}.
+ */
+export interface LoadSemanticTypeManifestsInput {
+    readonly sources: readonly ManifestSource[];
+    readonly readFile?: ManifestReadFile;
+}
+/**
+ * Result of {@link loadSemanticTypeManifests}. `entries` is the merged
+ * lookup map keyed by `${package}::${name}`; `topicsIndex` is the inverted
+ * index from topic to entry keys (each bucket sorted alphabetically for
+ * deterministic output). `warnings` is sorted deterministically so test
+ * assertions over the array are stable across runs.
+ */
+export interface LoadSemanticTypeManifestsResult {
+    readonly entries: ReadonlyMap<string, SemanticTypeEntry>;
+    readonly topicsIndex: ReadonlyMap<string, readonly string[]>;
+    readonly warnings: readonly LoaderWarning[];
+    readonly loadedSources: readonly string[];
+}
+/**
+ * Discriminated union of all non-fatal events the loader emits. Strict
+ * sources convert these into thrown errors; non-strict sources collect
+ * them into the result's `warnings` array.
+ */
+export type LoaderWarning = {
+    readonly kind: 'manifest-missing';
+    readonly path: string;
+} | {
+    readonly kind: 'manifest-parse-failed';
+    readonly path: string;
+    readonly error: string;
+} | {
+    readonly kind: 'manifest-schema-failed';
+    readonly path: string;
+    readonly error: string;
+} | {
+    readonly kind: 'manifest-version-unsupported';
+    readonly path: string;
+    readonly version: unknown;
+} | {
+    readonly kind: 'source-label-collision';
+    readonly source: string;
+    readonly existingPath: string;
+    readonly droppedPath: string;
+} | {
+    readonly kind: 'entry-collision';
+    readonly entryKey: string;
+    readonly winningSource: string;
+    readonly losingSource: string;
+} | {
+    readonly kind: 'topic-unknown-core';
+    readonly entryKey: string;
+    readonly topic: string;
+} | {
+    readonly kind: 'topic-namespace-mismatch';
+    readonly entryKey: string;
+    readonly topic: string;
+    readonly expectedNamespace: string;
+};
+/**
+ * Loads, validates, and merges the supplied manifest sources into a single
+ * registry suitable for the (future) `lookup-semantic-type` /
+ * `search-semantic-type` MCP tools.
+ *
+ * Strict sources fail loud; non-strict sources fail soft. If every source
+ * fails — strict or not — the loader throws, since a silent empty registry
+ * provides no value to a downstream agent.
+ *
+ * @param input - Manifest sources plus an optional injected `readFile`
+ * @returns Merged entries, topic index, deterministic warnings, and the list of source labels that loaded.
+ * @throws {Error} When a strict source fails or when zero manifests load successfully.
+ */
+export declare function loadSemanticTypeManifests(input: LoadSemanticTypeManifestsInput): Promise<LoadSemanticTypeManifestsResult>;

package/src/lib/mcp-scan/manifest/manifest-loader-base.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Generic core for the per-domain manifest loaders (actions, filters,
+ * forge-fields, pipes, ui-components).
+ *
+ * Each domain loader (`actions-loader.ts`, etc.) is a thin wrapper that
+ * supplies an arktype schema, an index-key extractor, and an entry-key
+ * builder. The orchestration — read, parse, version-check, schema-validate,
+ * merge, dedupe, sort — lives here so the five domains do not duplicate
+ * ~150 lines of identical procedural code each.
+ *
+ * The semantic-types loader (`loader.ts`) is intentionally not migrated to
+ * this base: it carries extra topic-filtering logic and a different result
+ * shape, so consolidating it would expand scope without removing
+ * meaningful duplication.
+ */
+import { type } from 'arktype';
+/**
+ * One manifest the loader is asked to ingest. `path` must be absolute (the
+ * caller resolves any repo-relative `dbx-mcp.config.json` entries against
+ * the config file's directory before invoking the loader).
+ */
+export interface ManifestSource {
+    readonly origin: 'bundled' | 'external';
+    readonly path: string;
+    readonly strict?: boolean;
+}
+/**
+ * Function shape used by the loader to read manifest contents. Defaults to
+ * `node:fs/promises.readFile(path, 'utf-8')` when not supplied.
+ */
+export type ManifestReadFile = (absolutePath: string) => Promise<string>;
+/**
+ * Discriminated union of all non-fatal events the loader emits. Strict
+ * sources convert these into thrown errors; non-strict sources collect
+ * them into the result's `warnings` array.
+ */
+export type ManifestLoaderWarning = {
+    readonly kind: 'manifest-missing';
+    readonly path: string;
+} | {
+    readonly kind: 'manifest-parse-failed';
+    readonly path: string;
+    readonly error: string;
+} | {
+    readonly kind: 'manifest-schema-failed';
+    readonly path: string;
+    readonly error: string;
+} | {
+    readonly kind: 'manifest-version-unsupported';
+    readonly path: string;
+    readonly version: unknown;
+} | {
+    readonly kind: 'source-label-collision';
+    readonly source: string;
+    readonly existingPath: string;
+    readonly droppedPath: string;
+} | {
+    readonly kind: 'entry-collision';
+    readonly entryKey: string;
+    readonly winningSource: string;
+    readonly losingSource: string;
+};
+/**
+ * The minimum manifest envelope shape the base loader needs to merge a
+ * source. Each domain's full manifest type is a structural superset of
+ * this.
+ */
+export interface BaseManifest<TEntry> {
+    readonly source: string;
+    readonly entries: readonly TEntry[];
+}
+/**
+ * Per-domain configuration for {@link loadManifestsBase}.
+ */
+export interface ManifestLoaderConfig<TManifest extends BaseManifest<TEntry>, TEntry> {
+    /**
+     * Function name used in error messages — e.g. `loadActionManifests`.
+     */
+    readonly name: string;
+    /**
+     * Arktype validator for the domain's manifest envelope. The raw return
+     * value (`TManifest | type.errors`) is interrogated with `instanceof
+     * type.errors`.
+     */
+    readonly schema: (parsed: unknown) => TManifest | type.errors;
+    /**
+     * Pulls the inverted-index key out of one entry (e.g. `entry.role` for
+     * actions, `entry.kind` for filters).
+     */
+    readonly extractIndexValue: (entry: TEntry) => string;
+    /**
+     * Builds the merged-map key for one entry. Most domains use
+     * `${manifest.module}::${entry.slug}`; ui-components reads `module`
+     * from the entry itself instead of the envelope.
+     */
+    readonly buildEntryKey: (manifest: TManifest, entry: TEntry) => string;
+}
+/**
+ * Input to {@link loadManifestsBase}.
+ */
+export interface ManifestLoaderInput {
+    readonly sources: readonly ManifestSource[];
+    readonly readFile?: ManifestReadFile;
+}
+/**
+ * Generic result of {@link loadManifestsBase}. Domain wrappers re-emit
+ * `indexMap` under their own property name (`roleIndex`, `kindIndex`,
+ * `tierIndex`, `categoryIndex`).
+ */
+export interface ManifestLoaderBaseResult<TEntry> {
+    readonly entries: ReadonlyMap<string, TEntry>;
+    readonly indexMap: ReadonlyMap<string, readonly string[]>;
+    readonly warnings: readonly ManifestLoaderWarning[];
+    readonly loadedSources: readonly string[];
+}
+/**
+ * Loads, validates, and merges the supplied manifest sources into a single
+ * registry. Strict sources fail loud; non-strict sources fail soft. If
+ * every source fails — strict or not — the loader throws, since a silent
+ * empty registry provides no value to a downstream agent.
+ *
+ * Domain wrappers translate the generic result fields into their named
+ * shape (e.g. `indexMap` → `roleIndex`).
+ *
+ * @param input - Manifest sources plus an optional injected `readFile`
+ * @param config - Per-domain schema + key extractors + name for error messages.
+ * @returns Merged entries, generic index map, deterministic warnings, and the list of source labels that loaded.
+ * @throws {Error} When a strict source fails or when zero manifests load successfully.
+ */
+export declare function loadManifestsBase<TManifest extends BaseManifest<TEntry>, TEntry>(input: ManifestLoaderInput, config: ManifestLoaderConfig<TManifest, TEntry>): Promise<ManifestLoaderBaseResult<TEntry>>;

package/src/lib/mcp-scan/manifest/model-firebase-index-loader.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Loader for model-firebase-index manifests.
+ *
+ * Reads one or more manifest files (bundled `@dereekb/firebase` registry
+ * plus any downstream-app manifests discovered via `dbx-mcp.config.json`),
+ * validates them against {@link ModelFirebaseIndexManifest}, and merges
+ * them into a single lookup-ready registry.
+ *
+ * Failure handling mirrors the model-snapshot-fields loader: bundled
+ * sources are strict by default, external sources are not. If no source
+ * loads successfully the loader throws.
+ */
+import { type ModelFirebaseIndexEntry } from '@dereekb/dbx-cli/firestore-indexes';
+import { type ManifestLoaderWarning, type ManifestReadFile, type ManifestSource } from './manifest-loader-base.js';
+/**
+ * One manifest the loader is asked to ingest. `path` must be absolute.
+ */
+export type ModelFirebaseIndexManifestSource = ManifestSource;
+/**
+ * Function shape used by the loader to read manifest contents.
+ */
+export type ModelFirebaseIndexManifestReadFile = ManifestReadFile;
+/**
+ * Discriminated union of all non-fatal events the loader emits.
+ */
+export type ModelFirebaseIndexLoaderWarning = ManifestLoaderWarning;
+/**
+ * Input to {@link loadModelFirebaseIndexManifests}.
+ */
+export interface LoadModelFirebaseIndexManifestsInput {
+    readonly sources: readonly ModelFirebaseIndexManifestSource[];
+    readonly readFile?: ModelFirebaseIndexManifestReadFile;
+}
+/**
+ * Result of {@link loadModelFirebaseIndexManifests}.
+ */
+export interface LoadModelFirebaseIndexManifestsResult {
+    readonly entries: ReadonlyMap<string, ModelFirebaseIndexEntry>;
+    readonly collectionIndex: ReadonlyMap<string, readonly string[]>;
+    readonly warnings: readonly ModelFirebaseIndexLoaderWarning[];
+    readonly loadedSources: readonly string[];
+}
+/**
+ * Loads, validates, and merges the supplied manifest sources into a
+ * single registry suitable for the `dbx_model_firebase_index_*` MCP
+ * tools.
+ *
+ * @param input - Manifest sources plus an optional injected `readFile`
+ * @returns Merged entries, collection index, deterministic warnings, and
+ *   the list of source labels that loaded.
+ * @throws {Error} When a strict source fails or when zero manifests load successfully.
+ */
+export declare function loadModelFirebaseIndexManifests(input: LoadModelFirebaseIndexManifestsInput): Promise<LoadModelFirebaseIndexManifestsResult>;

package/src/lib/mcp-scan/manifest/model-snapshot-fields-loader.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Loader for model-snapshot-fields manifests.
+ *
+ * Reads one or more manifest files (bundled `@dereekb/firebase` registry plus
+ * any downstream-app manifests discovered via `dbx-mcp.config.json`),
+ * validates them against {@link ModelSnapshotFieldManifest}, and merges them
+ * into a single lookup-ready registry.
+ *
+ * Failure handling mirrors the utils loader: bundled sources are strict by
+ * default, external sources are not. If no source loads successfully the
+ * loader throws.
+ */
+import { type ModelSnapshotFieldEntry } from './model-snapshot-fields-schema.js';
+import { type ManifestLoaderWarning, type ManifestReadFile, type ManifestSource } from './manifest-loader-base.js';
+/**
+ * One manifest the loader is asked to ingest. `path` must be absolute.
+ */
+export type ModelSnapshotFieldManifestSource = ManifestSource;
+/**
+ * Function shape used by the loader to read manifest contents.
+ */
+export type ModelSnapshotFieldManifestReadFile = ManifestReadFile;
+/**
+ * Discriminated union of all non-fatal events the loader emits.
+ */
+export type ModelSnapshotFieldLoaderWarning = ManifestLoaderWarning;
+/**
+ * Input to {@link loadModelSnapshotFieldManifests}.
+ */
+export interface LoadModelSnapshotFieldManifestsInput {
+    readonly sources: readonly ModelSnapshotFieldManifestSource[];
+    readonly readFile?: ModelSnapshotFieldManifestReadFile;
+}
+/**
+ * Result of {@link loadModelSnapshotFieldManifests}. `entries` is the merged
+ * lookup map keyed by `${module}::${slug}`; `categoryIndex` is the inverted
+ * index from category value to entry keys (sorted alphabetically for
+ * deterministic output).
+ */
+export interface LoadModelSnapshotFieldManifestsResult {
+    readonly entries: ReadonlyMap<string, ModelSnapshotFieldEntry>;
+    readonly categoryIndex: ReadonlyMap<string, readonly string[]>;
+    readonly warnings: readonly ModelSnapshotFieldLoaderWarning[];
+    readonly loadedSources: readonly string[];
+}
+/**
+ * Loads, validates, and merges the supplied manifest sources into a single
+ * registry suitable for the `dbx_model_snapshot_field_*` MCP tools.
+ *
+ * @param input - Manifest sources plus an optional injected `readFile`
+ * @returns Merged entries, category index, deterministic warnings, and the list of source labels that loaded.
+ * @throws {Error} When a strict source fails or when zero manifests load successfully.
+ */
+export declare function loadModelSnapshotFieldManifests(input: LoadModelSnapshotFieldManifestsInput): Promise<LoadModelSnapshotFieldManifestsResult>;