@happyvertical/smrt-config 0.51.32 → 0.51.34

package/dist/index.d.ts

@@ -1,1376 +1,10 @@
-import { DomainKnowledgeConfig } from '@happyvertical/smrt-types';
-
-/** Canonical config stored at `runtime` in `smrt.config.ts`. */
-export declare interface ApplicationRuntimeConfig {
-    profile: ApplicationRuntimeProfile;
-    providers?: RuntimeProviderOverrides;
-}
-
-/**
- * Stable application-runtime profile contract.
- *
- * Profiles select infrastructure composition only. Domain models, generated
- * surfaces, effect metadata, and approval policy are deliberately outside the
- * override surface so moving an application cannot silently change behavior.
- */
-export declare type ApplicationRuntimeProfile = 'local' | 'self-hosted' | 'cloud';
-
-export declare type AssetOwnership = 'user' | 'operator' | 'managed';
-
-export declare type AssetStorageProvider = 'local-files' | 's3-compatible' | 'managed-object-storage';
-
-export declare type AuthenticationProvider = 'owner-bootstrap' | 'oidc' | 'magic-link' | 'hosted-identity';
-
-export declare type BackupProvider = 'file-snapshot' | 'operator' | 'managed';
-
-/**
- * Reset all cached configuration state.
- *
- * Clears three independent caches:
- * 1. `globalThis.__smrtConfigCache` — the merged config loaded by {@link loadConfig}.
- * 2. The internal loader cache (`globalThis.__smrtLoaderCachedConfig`) and the
- *    cosmiconfig explorer instance.
- * 3. The runtime override store populated by {@link setConfig}.
- *
- * After calling this, {@link getConfig} returns `null` and a fresh
- * {@link loadConfig} call will re-read from disk.
- *
- * WARNING: This is a global reset — it affects every module sharing the same
- * runtime, not just the caller. Use with care outside of test teardown.
- *
- * @example
- * ```ts
- * afterEach(() => {
- *   clearCache(); // reset between tests
- * });
- * ```
- *
- * @see {@link loadConfig}
- * @see {@link setConfig}
- */
-export declare function clearCache(): void;
-
-/**
- * Reset the runtime configuration override store to an empty object.
- *
- * Called by {@link clearCache} in `index.ts` as part of a full cache reset.
- * Useful in tests to ensure a clean state between cases.
- *
- * @see {@link setConfig}
- */
-export declare function clearRuntimeConfig(): void;
-
-/**
- * CLI package configuration.
- *
- * Placed under the `cli` key in `smrt.config.js`. Consumed by
- * `@happyvertical/smrt-cli` for `smrt db:*` and migration commands.
- *
- * @example
- * ```js
- * export default defineConfig({
- *   cli: {
- *     database: { type: 'sqlite', url: 'file:./local.db' },
- *     migrations: { mode: 'dynamic', directory: './migrations' },
- *   },
- * });
- * ```
- *
- * @see {@link DatabaseConfig}
- * @see {@link MigrationsConfig}
- */
-export declare interface CliConfig {
-    /**
-     * Database connection settings
-     */
-    database?: DatabaseConfig;
-    /**
-     * Migration settings
-     */
-    migrations?: MigrationsConfig;
-    /**
-     * Required manifest/object/field/database-shape contract for schema commands.
-     */
-    schemaContract?: SchemaContractConfig;
-}
-
-export declare type ConnectionOwnership = 'user' | 'operator' | 'managed';
-
-/**
- * Database connection configuration for CLI commands.
- *
- * Placed under `cli.database` in `smrt.config.js`. Used by
- * `@happyvertical/smrt-cli` to connect for migration and inspection commands.
- *
- * @see {@link CliConfig}
- */
-export declare interface DatabaseConfig {
-    /**
-     * Database type
-     *
-     * @default 'sqlite'
-     */
-    type?: 'sqlite' | 'postgres' | 'duckdb';
-    /**
-     * Database connection URL
-     *
-     * For SQLite: file path or ':memory:'
-     * For PostgreSQL: postgresql://user:pass@host:port/dbname
-     */
-    url?: string;
-}
-
-export declare type DatabaseEngine = 'sqlite' | 'postgres';
-
-/**
- * Type-safe helper for authoring `smrt.config.js` files.
- *
- * This is an identity function — it returns its argument unchanged. Its sole
- * purpose is to provide TypeScript type-checking and IDE auto-completion when
- * writing the config object literal.
- *
- * @param config - The config object to validate against {@link SmrtConfig}.
- * @returns The same object, unchanged.
- *
- * @example
- * ```js
- * // smrt.config.js
- * import { defineConfig } from '@happyvertical/smrt-config';
- *
- * export default defineConfig({
- *   smrt: { logLevel: 'info' },
- *   site: { name: 'My Site', ... },
- * });
- * ```
- *
- * @see {@link SmrtConfig}
- * @see {@link loadConfig}
- */
-export declare function defineConfig(config: SmrtConfig): SmrtConfig;
-
-/**
- * Export configuration for static site generation.
- *
- * Placed under the `export` key in `smrt.config.js`. Controls how database
- * records are exported to static files during SSG builds. Each additional
- * key beyond `fieldExportDefault` and `format` defines a named export file.
- *
- * @example
- * ```js
- * export default defineConfig({
- *   export: {
- *     fieldExportDefault: true,
- *     articles: { types: ['Article'], filters: { status: ['published'] } },
- *     games: { types: ['Game'], orderBy: '-date', format: 'ndjson' },
- *   },
- * });
- * ```
- *
- * @see {@link ExportFileConfig}
- * @see {@link exportConfig}
- */
-export declare interface ExportConfig {
-    /**
-     * Default export behavior for fields without explicit `exported` annotation
-     *
-     * - true: Export all fields by default (simpler, for most sites)
-     * - false: Only export fields with explicit `exported: true`
-     *
-     * @default true
-     */
-    fieldExportDefault?: boolean;
-    /**
-     * Default output format for all exports
-     * @default 'json'
-     */
-    format?: 'json' | 'ndjson' | 'csv' | 'sqlite';
-    /**
-     * Export file configurations
-     * Keys become filenames (e.g., 'contents' -> 'contents.json')
-     */
-    [filename: string]: ExportFileConfig | boolean | string | undefined;
-}
-
-/**
- * Serialize a configuration object to a formatted string for SSG file output.
- *
- * By default, {@link sanitizeConfig} is applied before serialization to strip
- * any keys that match secret patterns (API keys, passwords, tokens, etc.).
- * Pass `includeSecrets: true` only in secured server-side contexts.
- *
- * @param config - Configuration object to export. Any JSON-serializable value.
- * @param options - Format, indentation, and secret-inclusion options.
- * @returns A JSON string, or an ES module string (`export default {...};\n`)
- *   when `format: 'js'`.
- *
- * @example
- * ```ts
- * // Write a sanitized JSON export file for SSG
- * const json = exportConfig(agentConfig);
- * await fs.writeFile('./public/config.json', json);
- * ```
- *
- * @example
- * ```ts
- * // ES module format (importable via `import config from './config.js'`)
- * const js = exportConfig(agentConfig, { format: 'js' });
- * ```
- *
- * @see {@link sanitizeConfig}
- * @see {@link parseExportedConfig}
- * @see {@link ExportConfigOptions}
- */
-export declare function exportConfig(config: unknown, options?: ExportConfigOptions): string;
-
-/**
- * Options accepted by {@link exportConfig}.
- */
-export declare interface ExportConfigOptions {
-    /**
-     * Include secrets in the export (use with caution!)
-     * @default false
-     */
-    includeSecrets?: boolean;
-    /**
-     * Output format
-     * - 'json': Plain JSON format
-     * - 'js': ES module format (export default)
-     * @default 'json'
-     */
-    format?: 'json' | 'js';
-    /**
-     * Number of spaces for indentation
-     * @default 2
-     */
-    indent?: number;
-}
-
-/**
- * Configuration for a single SSG export file.
- *
- * Each key in {@link ExportConfig} (besides `fieldExportDefault` and `format`)
- * becomes the output filename. Records are queried from the database, filtered,
- * ordered, and written to `{key}.json` (or the specified format).
- *
- * @example
- * ```js
- * export default defineConfig({
- *   export: {
- *     articles: {
- *       types: ['Article'],
- *       filters: { status: ['published'] },
- *       orderBy: '-publishDate',
- *       limit: 500,
- *     },
- *   },
- * });
- * ```
- *
- * @see {@link ExportConfig}
- * @see {@link ExportFilterValue}
- */
-export declare interface ExportFileConfig {
-    /**
-     * SMRT object types to include in this export
-     * Uses className (e.g., 'MeetingRecap', 'Game')
-     */
-    types: string[];
-    /**
-     * Field whitelist - only export these fields
-     * If specified, overrides exclude and fieldExportDefault
-     */
-    include?: string[];
-    /**
-     * Field blacklist - exclude these fields
-     * Applied after schema-level exported: false check
-     */
-    exclude?: string[];
-    /**
-     * Filters to apply when querying records
-     * Keys are field names, values are filter conditions
-     *
-     * @example
-     * filters: {
-     *   status: ['published'],  // shorthand for status IN ('published')
-     *   publish_date: { gte: '2025-01-01' },
-     *   council_slug: ['town-of-bentley'],
-     * }
-     */
-    filters?: Record<string, string[] | number[] | ExportFilterValue>;
-    /**
-     * Output format for this file
-     * @default 'json'
-     */
-    format?: 'json' | 'ndjson' | 'csv' | 'sqlite';
-    /**
-     * Field to order by
-     * Prefix with '-' for descending (e.g., '-publish_date')
-     */
-    orderBy?: string;
-    /**
-     * Maximum records per file
-     * If exceeded, creates paginated files (e.g., contents-1.json, contents-2.json)
-     */
-    limit?: number;
-    /**
-     * Create separate files per unique value of this field
-     * e.g., shardBy: 'year' creates contents-2024.json, contents-2025.json
-     */
-    shardBy?: string;
-}
-
-/**
- * Filter operators for export queries.
- *
- * Used as values in {@link ExportFileConfig.filters} to build SQL `WHERE`
- * clauses when exporting records to static files.
- *
- * @example
- * ```js
- * filters: {
- *   publishDate: { gte: '2025-01-01', lt: '2026-01-01' },
- *   status: { in: ['published', 'featured'] },
- * }
- * ```
- *
- * @see {@link ExportFileConfig}
- */
-export declare interface ExportFilterValue {
-    /** Equals (shorthand: just the value) */
-    eq?: string | number | boolean;
-    /** Not equals */
-    ne?: string | number | boolean;
-    /** Greater than */
-    gt?: string | number;
-    /** Greater than or equal */
-    gte?: string | number;
-    /** Less than */
-    lt?: string | number;
-    /** Less than or equal */
-    lte?: string | number;
-    /** In array */
-    in?: (string | number)[];
-    /** Contains (text) */
-    contains?: string;
-}
-
-/** Return a fresh copy of the documented preset for inspection and tooling. */
-export declare function getApplicationRuntimePreset(profile: ApplicationRuntimeProfile): Readonly<RuntimeProviders>;
-
-/**
- * Return the loaded file configuration synchronously.
- *
- * Reads from `globalThis.__smrtConfigCache` without triggering a file search.
- * Returns `null` when {@link loadConfig} has not been called yet (or after
- * {@link clearCache} resets the cache).
- *
- * @returns The cached {@link SmrtConfig}, or `null` if not yet loaded.
- *
- * @example
- * ```ts
- * const config = getConfig();
- * if (config?.smrt?.logLevel === 'debug') {
- *   console.log('Debug logging enabled');
- * }
- * ```
- *
- * @see {@link loadConfig}
- * @see {@link resolveConfiguredApplicationRuntime}
- * @see {@link getSiteConfig}
- * @see {@link getModuleConfig}
- */
-export declare function getConfig(): SmrtConfig | null;
-
-/**
- * Return the resolved configuration for a named module.
- *
- * Merges four layers in ascending priority order:
- * 1. `defaults` (caller-supplied fallbacks)
- * 2. Global `smrt` section of the loaded config
- * 3. `modules[moduleName]` section of the loaded config
- * 4. Runtime `modules[moduleName]` overrides set via {@link setConfig}
- *
- * Works synchronously — call {@link loadConfig} first to populate the cache.
- * If no config has been loaded, only `defaults` are returned.
- *
- * @param moduleName - Key in `config.modules` (e.g., `'praeco'`).
- * @param defaults - Optional fallback values used when a key is absent from all
- *   higher-priority layers.
- * @returns The fully merged module config typed as `T`.
- *
- * @example
- * ```ts
- * const config = getModuleConfig('praeco', {
- *   rssLimit: 50,
- *   fetchTimeout: 10_000,
- * });
- * // config.rssLimit may be overridden by smrt.config.js or setConfig()
- * ```
- *
- * @see {@link getPackageConfig}
- * @see {@link setConfig}
- * @see {@link SmrtConfig.modules}
- */
-export declare function getModuleConfig<T extends Record<string, unknown>>(moduleName: string, defaults?: T): T;
-
-/**
- * Return the resolved configuration for a named package.
- *
- * Identical to {@link getModuleConfig} but reads from `config.packages` instead
- * of `config.modules`. Use this inside `@happyvertical/smrt-*` packages that
- * want to expose their own config section without conflicting with user-defined
- * module names.
- *
- * Merges four layers in ascending priority order:
- * 1. `defaults` (caller-supplied fallbacks)
- * 2. Global `smrt` section of the loaded config
- * 3. `packages[packageName]` section of the loaded config
- * 4. Runtime `packages[packageName]` overrides set via {@link setConfig}
- *
- * @param packageName - Key in `config.packages` (e.g., `'ai'`, `'spider'`).
- * @param defaults - Optional fallback values.
- * @returns The fully merged package config typed as `T`.
- *
- * @example
- * ```ts
- * // Inside @happyvertical/smrt-ai package
- * const config = getPackageConfig('ai', {
- *   defaultModel: 'gpt-4o-mini',
- *   maxTokens: 2048,
- * });
- * ```
- *
- * @see {@link getModuleConfig}
- * @see {@link setConfig}
- * @see {@link SmrtConfig.packages}
- */
-export declare function getPackageConfig<T extends Record<string, unknown>>(packageName: string, defaults?: T): T;
-
-/**
- * Return the current runtime configuration override store.
- *
- * Used internally by {@link getModuleConfig} and {@link getPackageConfig} to
- * layer runtime overrides on top of file-based config. Prefer those helpers
- * for reading config; this is a low-level accessor.
- *
- * @returns The accumulated runtime config partial.
- */
-export declare function getRuntimeConfig(): Partial<SmrtConfig>;
-
-/**
- * Return the `site` section of the loaded configuration.
- *
- * Equivalent to `getConfig()?.site ?? null`. Returns `null` both when no
- * config has been loaded and when the loaded config has no `site` key.
- *
- * @returns The {@link SiteConfig} object, or `null` if not defined.
- *
- * @example
- * ```ts
- * const site = getSiteConfig();
- * const title = site?.name ?? 'Untitled Site';
- * ```
- *
- * @see {@link SiteConfig}
- * @see {@link getConfig}
- */
-export declare function getSiteConfig(): SiteConfig | null;
-
-export declare type JobTopology = 'inline' | 'embedded' | 'external' | 'scalable';
-
-/**
- * Load and parse configuration from the project root.
- *
- * Searches for `smrt.config.{js,mjs,cjs,json}` starting from the current
- * working directory and walking up the tree (unless `searchParents: false`).
- * The result is stored in `globalThis.__smrtConfigCache` so every module in
- * the process — including pnpm workspace packages loaded from different paths
- * — sees the same instance.
- *
- * Must be called before {@link getConfig}, {@link getModuleConfig}, or
- * {@link getPackageConfig} return meaningful values (they fall back to an
- * empty config if called before loading).
- *
- * @param options - Optional search path, parent traversal, and cache control.
- * @returns The parsed {@link SmrtConfig}. Returns `{}` if no file is found.
- *
- * @example
- * ```ts
- * // Typical app startup
- * import { loadConfig } from '@happyvertical/smrt-config';
- * await loadConfig();
- * ```
- *
- * @example
- * ```ts
- * // Load a specific file (tests / scripts)
- * const config = await loadConfig({ configPath: './fixtures/smrt.config.js', cache: false });
- * ```
- *
- * @see {@link getConfig}
- * @see {@link clearCache}
- * @see {@link LoadConfigOptions}
- */
-export declare function loadConfig(options?: LoadConfigOptions): Promise<SmrtConfig>;
-
-/**
- * Options accepted by {@link loadConfig}.
- *
- * All fields are optional; omitting them triggers cosmiconfig's default
- * search behaviour (scan `cwd` upward for `smrt.config.{js,mjs,cjs,json}`).
- */
-export declare interface LoadConfigOptions {
-    /**
-     * Absolute or relative path to a specific config file.
-     * When provided, cosmiconfig loads this file directly instead of searching.
-     */
-    configPath?: string;
-    /**
-     * Whether to search parent directories when no config is found in `cwd`.
-     *
-     * @default true
-     */
-    searchParents?: boolean;
-    /**
-     * Directory to start the config search from. Defaults to `process.cwd()`.
-     * Ignored when `configPath` is provided. Useful for tests and for tools that
-     * resolve config relative to a project root other than the current directory.
-     */
-    searchFrom?: string;
-    /**
-     * Whether to cache the loaded config in `globalThis.__smrtLoaderCachedConfig`.
-     * Disable for test isolation or hot-reload scenarios.
-     *
-     * @default true
-     */
-    cache?: boolean;
-}
-
-/**
- * Merge three config layers in ascending priority order.
- *
- * Priority (highest to lowest):
- * 1. `runtime` — runtime overrides set via {@link setConfig}
- * 2. `fileConfig` — values loaded from `smrt.config.js`
- * 3. `defaults` — caller-supplied fallback values
- *
- * Uses {@link deepMerge} internally, so `null` / `undefined` source values
- * never overwrite existing target values.
- *
- * @param defaults - Lowest-priority base values (caller defaults).
- * @param fileConfig - Mid-priority values from the loaded config file.
- * @param runtime - Highest-priority runtime override values.
- * @returns A new object with all three layers merged.
- *
- * @example
- * ```ts
- * const merged = mergeConfigs(
- *   { timeout: 5000, retries: 3 },
- *   { retries: 5 },
- *   { timeout: 1000 },
- * );
- * // => { timeout: 1000, retries: 5 }
- * ```
- */
-export declare function mergeConfigs<T extends Record<string, unknown>>(defaults: T, fileConfig: Partial<T>, runtime: Partial<T>): T;
-
-/**
- * Shallow-merge an exported (DB-backed) config into a base (file-backed) config.
- *
- * Object values are deep-merged recursively. Primitive values and arrays from
- * `exportedConfig` replace their counterparts in `baseConfig`. This is a
- * one-level-smarter spread that lets file-based env overrides win when placed
- * after the spread.
- *
- * Intended for the SSG pattern where an agent exports its runtime config to a
- * static JSON file and `smrt.config.js` imports it as a base:
- *
- * @example
- * ```js
- * // smrt.config.js
- * import exported from './smrt.exported.json' with { type: 'json' };
- *
- * export default defineConfig({
- *   modules: {
- *     praeco: mergeExportedConfig(exported, {
- *       apiEndpoint: process.env.API_URL, // env override wins
- *     }),
- *   },
- * });
- * ```
- *
- * @param baseConfig - Lower-priority base (typically from the DB export file).
- * @param exportedConfig - Higher-priority overrides (typically env / file-based).
- * @returns A new merged object of type `T`.
- *
- * @see {@link exportConfig}
- * @see {@link parseExportedConfig}
- */
-export declare function mergeExportedConfig<T extends Record<string, unknown>>(baseConfig: T, exportedConfig: Partial<T>): T;
-
-/**
- * Database migrations configuration.
- *
- * Controls how migrations are generated, stored, and applied. Placed under
- * the `cli.migrations` key in `smrt.config.js` and consumed by
- * `@happyvertical/smrt-cli` migration commands (`smrt db:migrate`, etc.).
- *
- * @see {@link CliConfig}
- */
-export declare interface MigrationsConfig {
-    /**
-     * Directory for migration files (relative to project root)
-     *
-     * @default './migrations'
-     */
-    directory?: string;
-    /**
-     * Table name for tracking applied migrations
-     *
-     * @default '_smrt_schema_migrations'
-     */
-    table?: string;
-    /**
-     * Legacy file format setting. File-backed migration generation is not supported.
-     *
-     * @default 'sql'
-     */
-    format?: 'sql' | 'typescript';
-    /**
-     * Migration file naming strategy
-     *
-     * - 'sequence': Sequential numbers (0001, 0002, ...)
-     * - 'timestamp': Unix timestamp-based (20240115143052)
-     *
-     * @default 'sequence'
-     */
-    naming?: 'sequence' | 'timestamp';
-    /**
-     * Migration mode.
-     *
-     * SMRT schema migrations are manifest-driven. File-backed modes are not
-     * supported unless a future file migration executor is implemented.
-     *
-     * @default 'dynamic'
-     */
-    mode?: 'dynamic';
-    /**
-     * Configure mode per environment.
-     *
-     * Overrides the `mode` setting based on NODE_ENV
-     */
-    modeByEnvironment?: {
-        development?: 'dynamic';
-        test?: 'dynamic';
-        staging?: 'dynamic';
-        production?: 'dynamic';
-    };
-    /**
-     * Automatically generate DOWN scripts where safe
-     *
-     * Some operations (DROP COLUMN) may lose data and should be reviewed.
-     *
-     * @default true
-     */
-    autoGenerateDown?: boolean;
-    /**
-     * PostgreSQL-specific settings
-     */
-    postgres?: MigrationsPostgresConfig;
-}
-
-/**
- * PostgreSQL-specific migration settings.
- *
- * Nested under `migrations.postgres` in {@link MigrationsConfig}.
- */
-export declare interface MigrationsPostgresConfig {
-    /**
-     * Allow `CREATE INDEX CONCURRENTLY` when concurrent-index mode is requested
-     * with `smrt db:migrate --postgres-safe`.
-     *
-     * Concurrent builds avoid the batch's table locks but cannot run inside a
-     * transaction, so that mode is not atomic. Setting this to `false` vetoes
-     * the flag: index DDL then stays inside the atomic transaction, still bounded
-     * by the timeouts below. The flag is the opt-in — this key alone does not
-     * enable concurrent mode.
-     *
-     * @default true
-     */
-    useConcurrently?: boolean;
-    /**
-     * `lock_timeout` applied to every PostgreSQL migration statement.
-     *
-     * Accepts a bare millisecond count or an `ms`/`s`/`min`/`h` suffix. `'0'`
-     * disables the timeout, as PostgreSQL defines it.
-     *
-     * @default '30s'
-     */
-    lockTimeout?: string;
-    /**
-     * `statement_timeout` applied to every PostgreSQL migration statement.
-     *
-     * Same accepted forms as {@link MigrationsPostgresConfig.lockTimeout}.
-     *
-     * @default '60s'
-     */
-    statementTimeout?: string;
-}
-
-export declare type NetworkExposure = 'loopback' | 'public';
-
-export declare type OwnerBootstrapMode = 'single-use' | 'disabled';
-
-/**
- * Parse a config string previously produced by {@link exportConfig} back into
- * a plain JavaScript object.
- *
- * Handles both output formats:
- * - **JSON** — standard `JSON.parse`.
- * - **JS module** — strips the `export default` prefix and trailing semicolon
- *   before parsing as JSON.
- *
- * Throws a `SyntaxError` if the content is not valid JSON after stripping.
- *
- * @param content - Exported config string (`'json'` or `'js'` format).
- * @returns Parsed configuration value.
- *
- * @example
- * ```ts
- * const raw = await fs.readFile('./smrt.exported.json', 'utf8');
- * const config = parseExportedConfig(raw);
- * ```
- *
- * @see {@link exportConfig}
- * @see {@link mergeExportedConfig}
- */
-export declare function parseExportedConfig(content: string): unknown;
-
-/** PostgreSQL ACL contract. Applied only through explicit db:permissions. */
-export declare interface PostgresPermissionsConfig {
-    schema: string;
-    /** Assert this schema is dedicated to the managed application. */
-    schemaExclusive: true;
-    migrationOwner: string;
-    runtimeRole: string;
-    /** Additional managed tables beyond discovered models and present system tables. */
-    managedTables?: string[];
-    /** Existing operator-owned tables retained outside the runtime data surface. */
-    retainedTables?: string[];
-    /** Exact zero-argument trigger functions bound only to managed tables. */
-    managedTriggerFunctions?: string[];
-    /** Explicit safe monitoring columns; there is no default table-wide access. */
-    monitor?: {
-        role: string;
-        tables: Record<string, string[]>;
-    };
-}
-
-/**
- * Resolve a safe preset and explicit provider overrides into a stable snapshot.
- *
- * The resolver is pure: it reads no environment variables, paths, credentials,
- * clocks, or process state. Invalid and unknown fields fail before startup.
- */
-export declare function resolveApplicationRuntime(config: ApplicationRuntimeConfig): Readonly<ResolvedApplicationRuntime>;
-
-/**
- * Resolve the effective application runtime using the documented config
- * priority: runtime overrides set by {@link setConfig} > loaded file config >
- * profile defaults.
- *
- * This accessor is intentionally separate from {@link getConfig}, whose legacy
- * contract returns the loaded file object only. When a runtime override selects
- * a different profile, lower-priority provider overrides are discarded so they
- * cannot leak profile-specific choices (for example local files or inline jobs)
- * into the new profile. Provider overrides still deep-merge when the profile is
- * unchanged.
- *
- * @returns A validated, deterministic, secret-free runtime snapshot.
- * @throws {RuntimeProfileValidationError} When no profile is configured or the
- * effective provider composition violates a profile invariant.
- */
-export declare function resolveConfiguredApplicationRuntime(): Readonly<ResolvedApplicationRuntime>;
-
-/** Deterministic, secret-free runtime diagnostic snapshot. */
-export declare interface ResolvedApplicationRuntime {
-    readonly schemaVersion: 1;
-    readonly profile: ApplicationRuntimeProfile;
-    readonly providers: RuntimeProviders;
-    readonly capabilities: RuntimeCapabilities;
-    readonly invariants: RuntimeInvariants;
-    readonly diagnostics: {
-        readonly secretValuesIncluded: false;
-        readonly overrides: readonly RuntimeOverrideReport[];
-        readonly unsafeOverrides: readonly [];
-    };
-}
-
-export declare interface RuntimeAssetProvider {
-    readonly provider: AssetStorageProvider;
-    readonly ownership: AssetOwnership;
-}
-
-export declare interface RuntimeAuthenticationProvider {
-    readonly provider: AuthenticationProvider;
-    readonly ownerBootstrap: OwnerBootstrapMode;
-}
-
-/** Derived capabilities used by startup, doctor, tests, and agent inspection. */
-export declare interface RuntimeCapabilities {
-    readonly ownerBootstrap: boolean;
-    readonly publicAuthentication: boolean;
-    readonly defaultTenant: boolean;
-    readonly multiTenant: boolean;
-    readonly localAssets: boolean;
-    readonly externalWorkers: boolean;
-    readonly backup: true;
-    readonly logicalExport: true;
-    readonly logicalImport: true;
-    readonly diagnostics: true;
-    readonly orchestrationHealth: boolean;
-}
-
-export declare interface RuntimeDatabaseProvider {
-    readonly engine: DatabaseEngine;
-    readonly connectionOwnership: ConnectionOwnership;
-}
-
-/** Behaviors that provider/profile selection is never allowed to change. */
-export declare interface RuntimeInvariants {
-    readonly domainModels: 'identical';
-    readonly generatedRest: 'identical';
-    readonly generatedCli: 'identical';
-    readonly generatedMcp: 'identical';
-    readonly generatedWebMcp: 'identical';
-    readonly mcpExposurePolicy: 'identical';
-    readonly webMcpExposurePolicy: 'identical';
-    readonly actionEffects: 'identical';
-    readonly approvalPolicy: 'identical';
-    readonly authorizationRecords: 'required';
-    readonly jobInvocation: 'identical';
-    readonly portability: 'logical-export-import';
-}
-
-export declare interface RuntimeJobProvider {
-    readonly topology: JobTopology;
-}
-
-export declare interface RuntimeNetworkProvider {
-    readonly exposure: NetworkExposure;
-    readonly tls: boolean;
-}
-
-export declare interface RuntimeOverrideReport {
-    readonly path: string;
-    readonly from: string | boolean;
-    readonly to: string | boolean;
-}
-
-export declare interface RuntimePortabilityProvider {
-    readonly backup: BackupProvider;
-    readonly logicalExport: true;
-    readonly logicalImport: true;
-}
-
-/** Aggregates deterministic, actionable failures before application startup. */
-export declare class RuntimeProfileValidationError extends Error {
-    readonly issues: readonly RuntimeProfileValidationIssue[];
-    constructor(issues: RuntimeProfileValidationIssue[]);
-}
-
-export declare interface RuntimeProfileValidationIssue {
-    code: 'invalid_config' | 'unsupported_field' | 'incompatible_provider';
-    path: string;
-    message: string;
-    recovery: string;
-}
-
-/**
- * Explicit provider changes layered over a profile's safe preset.
- *
- * Every override is revalidated with the completed composition. Capability and
- * surface-policy fields are intentionally absent: providers cannot use this
- * seam to weaken cross-profile invariants.
- */
-export declare interface RuntimeProviderOverrides {
-    database?: Partial<RuntimeDatabaseProvider>;
-    authentication?: Partial<RuntimeAuthenticationProvider>;
-    tenancy?: Partial<RuntimeTenancyProvider>;
-    assets?: Partial<RuntimeAssetProvider>;
-    secrets?: Partial<RuntimeSecretProvider>;
-    jobs?: Partial<RuntimeJobProvider>;
-    network?: Partial<RuntimeNetworkProvider>;
-}
-
-/** Fully selected infrastructure providers for an application runtime. */
-export declare interface RuntimeProviders {
-    readonly database: RuntimeDatabaseProvider;
-    readonly authentication: RuntimeAuthenticationProvider;
-    readonly tenancy: RuntimeTenancyProvider;
-    readonly assets: RuntimeAssetProvider;
-    readonly secrets: RuntimeSecretProvider;
-    readonly jobs: RuntimeJobProvider;
-    readonly network: RuntimeNetworkProvider;
-    readonly portability: RuntimePortabilityProvider;
-}
-
-export declare interface RuntimeSecretProvider {
-    readonly provider: SecretProvider;
-    readonly ownership: SecretOwnership;
-}
-
-export declare interface RuntimeTenancyProvider {
-    readonly mode: TenancyMode;
-    readonly context: TenantContextMode;
-    readonly isolation: TenantIsolation;
-}
-
-/**
- * Config export utilities for static site generation
- *
- * These utilities enable exporting database-backed agent configurations
- * to static files for SSG sites.
- *
- * @module
- */
-/**
- * Deep-clone a config object, removing every key that looks like a secret.
- *
- * Keys are tested (case-insensitively, across camelCase / snake_case / kebab /
- * UPPER variants) against {@link SECRET_PATTERNS}, which cover secrets such as
- * `apiKey`/`api_key`, `password`, `secret`, `token`, `credential`, `private`,
- * `auth`/`authorization`/`oauth`, `accessKey`, `signingKey`, `encryptionKey`,
- * `connectionString`, and `dbUrl`. The policy biases toward over-redaction
- * because these exports are typically published as static, publicly served
- * assets — see {@link SECRET_PATTERNS} for the full rationale.
- *
- * Nested objects are recursively sanitized; arrays are mapped element-by-element.
- * `number` / `boolean` primitives pass through unchanged; `string` values are
- * additionally run through value-level redaction that masks credentials embedded
- * in a URL (`scheme://user:pass@host` → `scheme://***@host`) as well as
- * high-confidence secret-token shapes pasted into otherwise-benign keys
- * (OpenAI/Anthropic `sk-...`, AWS `AKIA...` access key IDs, GitHub/Slack/Google
- * tokens, `Bearer ...` headers, and PEM private-key blocks) — catching secrets
- * stored under a benign key the key-based patterns don't match.
- *
- * Own `__proto__` / `constructor` / `prototype` keys are dropped to prevent the
- * cloned result's prototype from being reassigned via the `__proto__` setter.
- *
- * This function is called automatically by {@link exportConfig} unless
- * `includeSecrets: true` is passed.
- *
- * @param config - Value to sanitize. Accepts any JSON-serializable structure.
- * @returns A new value with all secret keys omitted. `null` / `undefined` are
- *   returned as-is.
- *
- * @example
- * ```ts
- * const sanitized = sanitizeConfig({
- *   apiEndpoint: 'https://api.example.com',
- *   apiKey: 'sk-secret-123',
- *   nested: { password: 'hunter2', name: 'test' },
- * });
- * // => { apiEndpoint: 'https://api.example.com', nested: { name: 'test' } }
- * ```
- *
- * @see {@link exportConfig}
- */
-export declare function sanitizeConfig(config: unknown): unknown;
-
-/**
- * Semantic schema contract enforced by SMRT schema commands.
- *
- * Object and field requirements are checked against the loaded SMRT registry.
- * Required fields are also translated to physical table/column checks after
- * migration/status introspection. `requiredDatabaseShape` is reserved for
- * database objects that SMRT cannot infer from manifests.
- */
-export declare interface SchemaContractConfig {
-    requiredObjects?: string[];
-    requiredFields?: string[];
-    requiredDatabaseShape?: {
-        tables?: string[];
-        columns?: string[];
-        indexes?: string[];
-    };
-}
-
-export declare type SecretOwnership = 'user' | 'operator' | 'managed';
-
-export declare type SecretProvider = 'local-file' | 'environment' | 'external' | 'managed';
-
-/**
- * Apply runtime configuration overrides.
- *
- * Deep-merges `config` into an in-memory store that takes the highest priority
- * in every subsequent {@link getModuleConfig} / {@link getPackageConfig} call.
- * Successive calls accumulate. When a call explicitly changes the runtime
- * profile, the stored runtime provider subtree is reset before merging so
- * profile-specific selectors cannot leak into the new profile.
- *
- * Common uses:
- * - Inject test doubles or environment-specific values without a config file.
- * - Apply feature flags from a remote source after startup.
- *
- * @param config - Partial {@link SmrtConfig} to merge into the runtime store.
- *   `null` values are ignored (they do not clear existing keys).
- *
- * @example
- * ```ts
- * setConfig({ modules: { ai: { defaultModel: 'gpt-4o' } } });
- * ```
- *
- * @see {@link clearCache}
- * @see {@link getModuleConfig}
- */
-export declare function setConfig(config: Partial<SmrtConfig>): void;
-
-/**
- * Site identity and configuration for SMRT site templates.
- *
- * Placed under the `site` key in `smrt.config.js`. Retrieved at runtime
- * via {@link getSiteConfig}. Used by site templates
- * (`template-sveltekit`, `template-site-static-json`) to define name,
- * description, navigation, location, and theme.
- *
- * @example
- * ```js
- * export default defineConfig({
- *   site: {
- *     name: 'Bentley Alberta',
- *     description: 'Community news for Bentley, AB',
- *     url: 'https://bentley.ca',
- *     location: { name: 'Bentley', latitude: 52.4, longitude: -113.9, timezone: 'America/Edmonton' },
- *     navigation: { primary: [{ label: 'Home', href: '/' }] },
- *   },
- * });
- * ```
- *
- * @see {@link getSiteConfig}
- * @see {@link SiteLocation}
- * @see {@link SiteNavigation}
- * @see {@link SiteTheme}
- */
-export declare interface SiteConfig {
-    /** Full site name (e.g., "Bentley Alberta") */
-    name: string;
-    /** Short name for mobile/compact displays */
-    shortName?: string;
-    /** Site description for SEO */
-    description: string;
-    /** Production URL */
-    url?: string;
-    /** Contact email for the site */
-    contactEmail?: string;
-    /** Publisher/organization info */
-    publisher?: SitePublisher;
-    /** Geographic location */
-    location: SiteLocation;
-    /** Navigation structure */
-    navigation: SiteNavigation;
-    /** Theme/branding */
-    theme?: SiteTheme;
-    /** Additional metadata */
-    meta?: {
-        /** Theme color for mobile browsers */
-        themeColor?: string;
-        /** Open Graph locale */
-        ogLocale?: string;
-        /** Google Tag Manager ID */
-        gtmId?: string;
-    };
-}
-
-/**
- * Geographic location for the site, used for proximity search and display.
- *
- * @see {@link SiteConfig}
- */
-export declare interface SiteLocation {
-    /** Display name (e.g., "Bentley" or "Bentley, AB") */
-    name: string;
-    /** Latitude coordinate */
-    latitude: number;
-    /** Longitude coordinate */
-    longitude: number;
-    /** IANA timezone (e.g., "America/Edmonton") */
-    timezone: string;
-}
-
-/**
- * Site navigation structure containing primary and optional footer links.
- *
- * @see {@link SiteConfig}
- * @see {@link SiteNavigationLink}
- */
-export declare interface SiteNavigation {
-    /** Primary navigation links (header) */
-    primary: SiteNavigationLink[];
-    /** Footer navigation links */
-    footer?: SiteNavigationLink[];
-}
-
-/**
- * A single navigation link item used in site menus.
- *
- * @see {@link SiteNavigation}
- */
-export declare interface SiteNavigationLink {
-    label: string;
-    href: string;
-    icon?: string;
-}
-
-/**
- * Publisher or organization information displayed in site footers and metadata.
- *
- * @see {@link SiteConfig}
- */
-export declare interface SitePublisher {
-    /** Organization name (e.g., "Blindman Press") */
-    name: string;
-    /** Organization website URL */
-    url?: string;
-    /** GitHub organization URL */
-    github?: string;
-}
-
-/**
- * Site theme and branding color palette.
- *
- * Colors should be provided as CSS hex values (e.g., `'#3b82f6'`).
- *
- * @see {@link SiteConfig}
- */
-export declare interface SiteTheme {
-    /** Primary brand color (hex) */
-    primaryColor: string;
-    /** Light variant of primary color */
-    primaryLight?: string;
-    /** Dark variant of primary color */
-    primaryDark?: string;
-}
-
-/**
- * Root SMRT configuration structure.
- *
- * This is the shape of the object returned by `smrt.config.{js,ts,json}` and
- * consumed by {@link loadConfig}. Use {@link defineConfig} for type-safe
- * authoring with IDE auto-completion.
- *
- * Priority order (highest to lowest):
- * 1. Runtime overrides set via {@link setConfig}
- * 2. File-based config loaded by {@link loadConfig}
- * 3. Defaults passed to {@link getModuleConfig} / {@link getPackageConfig}
- *
- * @example
- * ```js
- * // smrt.config.js
- * import { defineConfig } from '@happyvertical/smrt-config';
- *
- * export default defineConfig({
- *   smrt: { logLevel: 'info', environment: 'production' },
- *   site: { name: 'My Site', ... },
- *   modules: { praeco: { rssLimit: 50 } },
- *   packages: { ai: { defaultModel: 'gpt-4o' } },
- * });
- * ```
- *
- * @see {@link loadConfig}
- * @see {@link defineConfig}
- * @see {@link SmrtGlobalConfig}
- */
-export declare interface SmrtConfig {
-    /** Global SMRT framework options — lowest-priority base for all modules. */
-    smrt?: SmrtGlobalConfig;
-    /** Site identity and configuration (for site templates). */
-    site?: SiteConfig;
-    /** Export configuration for static site generation. */
-    export?: ExportConfig;
-    /** Domain-scoped agent/developer knowledge generation and exposure. */
-    knowledge?: DomainKnowledgeConfig;
-    /** Validated application infrastructure composition. */
-    runtime?: ApplicationRuntimeConfig;
-    /**
-     * Module-scoped configurations keyed by module name.
-     * Retrieved via {@link getModuleConfig}.
-     */
-    modules?: {
-        [moduleName: string]: Record<string, unknown>;
-    };
-    /**
-     * Package-scoped configurations keyed by package name.
-     * Retrieved via {@link getPackageConfig}.
-     */
-    packages?: {
-        [packageName: string]: Record<string, unknown>;
-    };
-}
-
-/**
- * Global SMRT framework options that apply to all modules unless overridden.
- *
- * Placed under the `smrt` key in `smrt.config.js`. Values here propagate
- * as the lowest-priority base for every `getModuleConfig()` and
- * `getPackageConfig()` call.
- *
- * @example
- * ```js
- * // smrt.config.js
- * export default defineConfig({
- *   smrt: {
- *     logLevel: 'debug',
- *     environment: 'development',
- *     embeddings: { provider: 'local' },
- *   },
- * });
- * ```
- *
- * @see {@link SmrtConfig}
- * @see {@link getModuleConfig}
- * @see {@link getPackageConfig}
- */
-export declare interface SmrtGlobalConfig {
-    postgresPermissions?: PostgresPermissionsConfig;
-    cacheDir?: string;
-    logLevel?: 'debug' | 'info' | 'warn' | 'error';
-    environment?: 'development' | 'production' | 'test';
-    /**
-     * Schema migration strategy when parent class schema changes
-     *
-     * Options:
-     * - 'warn': Log warning about schema mismatch, require manual migration (safest)
-     * - 'auto-add': Automatically ALTER TABLE to add new parent fields (default, convenient)
-     *
-     * Note: Removing columns is never automatic - always requires manual migration
-     *
-     * @default 'auto-add'
-     */
-    schemaMigration?: {
-        strategy?: 'warn' | 'auto-add';
-    };
-    /**
-     * Inheritance configuration
-     */
-    inheritance?: {
-        /**
-         * Behavior when an ancestor class is missing from the registry
-         *
-         * Options:
-         * - 'error': Throw an error (strict, catches bugs)
-         * - 'warn': Log warning and skip (lenient, default)
-         *
-         * @default 'warn'
-         */
-        onMissingAncestor?: 'error' | 'warn';
-        /**
-         * Size of LRU cache for inheritance chains and merged fields
-         *
-         * Higher values improve performance but use more memory.
-         * Each entry stores one inheritance chain (array of strings).
-         *
-         * @default 200
-         */
-        cacheSize?: number;
-    };
-    /**
-     * Embedding configuration for semantic search
-     *
-     * Project-level settings that apply to all SMRT objects
-     * unless overridden in the @smrt() decorator.
-     */
-    embeddings?: {
-        /**
-         * Standard dimensions for embeddings in this project
-         *
-         * All embeddings should use the same dimensions for consistency.
-         * Common values: 384, 768, 1536
-         *
-         * @default 768
-         */
-        dimensions?: number;
-        /**
-         * Embedding provider type
-         *
-         * - 'local': Use local Node.js model (@xenova/transformers)
-         * - 'ai': Use AI library (OpenAI, etc.)
-         * - 'auto': Try local first, fallback to AI
-         *
-         * @default 'local'
-         */
-        provider?: 'local' | 'ai' | 'auto';
-        /**
-         * Local model to use (when provider is 'local' or 'auto')
-         *
-         * Hugging Face model ID for @xenova/transformers.
-         * Model is downloaded on first use (~440MB for bge-base-en-v1.5).
-         *
-         * @default 'Xenova/bge-base-en-v1.5'
-         */
-        localModel?: string;
-        /**
-         * AI model to use (when provider is 'ai' or fallback)
-         *
-         * OpenAI embedding model name.
-         *
-         * @default 'text-embedding-3-small'
-         */
-        aiModel?: string;
-        /**
-         * Whether to fallback to AI if local embedding fails
-         *
-         * Only applies when provider is 'auto'.
-         *
-         * @default true
-         */
-        fallbackToAI?: boolean;
-        /**
-         * Storage mode for embeddings
-         *
-         * - 'json': Store as JSON text, in-memory similarity (works everywhere)
-         * - 'native': Use database vector operations when available, fallback to json
-         *
-         * @default 'json'
-         */
-        storage?: 'json' | 'native';
-    };
-    /**
-     * Optional typed-decision provider configuration. This is deliberately
-     * separate from generation configuration: configuring decisions never
-     * changes the client used by `do()` or `describe()`.
-     */
-    decisions?: {
-        /** The currently supported typed-decision provider. */
-        type: 'typesafe';
-        /** Provider credential. Prefer an environment-backed value in deployments. */
-        apiKey?: string;
-        /** Optional provider endpoint override, primarily for approved test hosts. */
-        baseUrl?: string;
-        /** Default decision model; individual evaluations may override it. */
-        defaultModel?: string;
-        /** Inclusive predicate threshold. A probability equal to it is true. */
-        threshold?: number;
-        /**
-         * Opt in to a generative tie-break only when the probability is inside the
-         * finite band centered on the threshold. Provider failures never use it.
-         */
-        uncertaintyFallback?: {
-            band: number;
-        };
-    };
-    [key: string]: unknown;
-}
-
-export declare type TenancyMode = 'default-tenant' | 'single-tenant' | 'multi-tenant';
-
-export declare type TenantContextMode = 'defaulted' | 'required';
-
-export declare type TenantIsolation = 'application' | 'database-rls';
-
-export { }
-
-
+import { type ResolvedApplicationRuntime } from './runtime-profile.js';
+import type { LoadConfigOptions, SmrtConfig } from './types.js';
+export { type ExportConfigOptions, exportConfig, mergeExportedConfig, parseExportedConfig, sanitizeConfig, } from './export.js';
+export { clearRuntimeConfig, getRuntimeConfig, mergeConfigs } from './merge.js';
+export type { ApplicationRuntimeConfig, ApplicationRuntimeProfile, AssetOwnership, AssetStorageProvider, AuthenticationProvider, BackupProvider, ConnectionOwnership, DatabaseEngine, JobTopology, NetworkExposure, OwnerBootstrapMode, ResolvedApplicationRuntime, RuntimeAssetProvider, RuntimeAuthenticationProvider, RuntimeCapabilities, RuntimeDatabaseProvider, RuntimeInvariants, RuntimeJobProvider, RuntimeNetworkProvider, RuntimeOverrideReport, RuntimePortabilityProvider, RuntimeProfileValidationIssue, RuntimeProviderOverrides, RuntimeProviders, RuntimeSecretProvider, RuntimeTenancyProvider, SecretOwnership, SecretProvider, TenancyMode, TenantContextMode, TenantIsolation, } from './runtime-profile.js';
+export { getApplicationRuntimePreset, RuntimeProfileValidationError, resolveApplicationRuntime, } from './runtime-profile.js';
+export type { CliConfig, DatabaseConfig, ExportConfig, ExportFileConfig, ExportFilterValue, LoadConfigOptions, MigrationsConfig, MigrationsPostgresConfig, PostgresPermissionsConfig, SchemaContractConfig, SiteConfig, SiteLocation, SiteNavigation, SiteNavigationLink, SitePublisher, SiteTheme, SmrtConfig, SmrtGlobalConfig, } from './types.js';
 /**
  * Extend globalThis to include our config cache properties.
  * Using globalThis ensures all module instances share the same config,
@@ -1386,22 +20,235 @@ declare global {
     var __smrtConfigCache: SmrtConfig | null | undefined;
     var __smrtRuntimeConfig: Partial<SmrtConfig> | undefined;
 }
-
-
-declare global {
-    var __smrtRuntimeConfig: Partial<SmrtConfig> | undefined;
-}
-
-
 /**
- * Extend globalThis to include loader cache properties.
- * Using globalThis ensures all module instances share the same loader state,
- * which is critical in monorepos where the same package can be loaded
- * from different paths (e.g., pnpm store vs workspace symlink).
+ * Load and parse configuration from the project root.
  *
- * @see https://github.com/happyvertical/smrt/issues/543
+ * Searches for `smrt.config.{js,mjs,cjs,json}` starting from the current
+ * working directory and walking up the tree (unless `searchParents: false`).
+ * The result is stored in `globalThis.__smrtConfigCache` so every module in
+ * the process — including pnpm workspace packages loaded from different paths
+ * — sees the same instance.
+ *
+ * Must be called before {@link getConfig}, {@link getModuleConfig}, or
+ * {@link getPackageConfig} return meaningful values (they fall back to an
+ * empty config if called before loading).
+ *
+ * @param options - Optional search path, parent traversal, and cache control.
+ * @returns The parsed {@link SmrtConfig}. Returns `{}` if no file is found.
+ *
+ * @example
+ * ```ts
+ * // Typical app startup
+ * import { loadConfig } from '@happyvertical/smrt-config';
+ * await loadConfig();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Load a specific file (tests / scripts)
+ * const config = await loadConfig({ configPath: './fixtures/smrt.config.js', cache: false });
+ * ```
+ *
+ * @see {@link getConfig}
+ * @see {@link clearCache}
+ * @see {@link LoadConfigOptions}
  */
-declare global {
-    var __smrtLoaderCachedConfig: SmrtConfig | null | undefined;
-    var __smrtLoaderExplorer: ReturnType<typeof cosmiconfig> | null | undefined;
-}
+export declare function loadConfig(options?: LoadConfigOptions): Promise<SmrtConfig>;
+/**
+ * Return the loaded file configuration synchronously.
+ *
+ * Reads from `globalThis.__smrtConfigCache` without triggering a file search.
+ * Returns `null` when {@link loadConfig} has not been called yet (or after
+ * {@link clearCache} resets the cache).
+ *
+ * @returns The cached {@link SmrtConfig}, or `null` if not yet loaded.
+ *
+ * @example
+ * ```ts
+ * const config = getConfig();
+ * if (config?.smrt?.logLevel === 'debug') {
+ *   console.log('Debug logging enabled');
+ * }
+ * ```
+ *
+ * @see {@link loadConfig}
+ * @see {@link resolveConfiguredApplicationRuntime}
+ * @see {@link getSiteConfig}
+ * @see {@link getModuleConfig}
+ */
+export declare function getConfig(): SmrtConfig | null;
+/**
+ * Resolve the effective application runtime using the documented config
+ * priority: runtime overrides set by {@link setConfig} > loaded file config >
+ * profile defaults.
+ *
+ * This accessor is intentionally separate from {@link getConfig}, whose legacy
+ * contract returns the loaded file object only. When a runtime override selects
+ * a different profile, lower-priority provider overrides are discarded so they
+ * cannot leak profile-specific choices (for example local files or inline jobs)
+ * into the new profile. Provider overrides still deep-merge when the profile is
+ * unchanged.
+ *
+ * @returns A validated, deterministic, secret-free runtime snapshot.
+ * @throws {RuntimeProfileValidationError} When no profile is configured or the
+ * effective provider composition violates a profile invariant.
+ */
+export declare function resolveConfiguredApplicationRuntime(): Readonly<ResolvedApplicationRuntime>;
+/**
+ * Return the `site` section of the loaded configuration.
+ *
+ * Equivalent to `getConfig()?.site ?? null`. Returns `null` both when no
+ * config has been loaded and when the loaded config has no `site` key.
+ *
+ * @returns The {@link SiteConfig} object, or `null` if not defined.
+ *
+ * @example
+ * ```ts
+ * const site = getSiteConfig();
+ * const title = site?.name ?? 'Untitled Site';
+ * ```
+ *
+ * @see {@link SiteConfig}
+ * @see {@link getConfig}
+ */
+export declare function getSiteConfig(): import('./types.js').SiteConfig | null;
+/**
+ * Return the resolved configuration for a named module.
+ *
+ * Merges four layers in ascending priority order:
+ * 1. `defaults` (caller-supplied fallbacks)
+ * 2. Global `smrt` section of the loaded config
+ * 3. `modules[moduleName]` section of the loaded config
+ * 4. Runtime `modules[moduleName]` overrides set via {@link setConfig}
+ *
+ * Works synchronously — call {@link loadConfig} first to populate the cache.
+ * If no config has been loaded, only `defaults` are returned.
+ *
+ * @param moduleName - Key in `config.modules` (e.g., `'praeco'`).
+ * @param defaults - Optional fallback values used when a key is absent from all
+ *   higher-priority layers.
+ * @returns The fully merged module config typed as `T`.
+ *
+ * @example
+ * ```ts
+ * const config = getModuleConfig('praeco', {
+ *   rssLimit: 50,
+ *   fetchTimeout: 10_000,
+ * });
+ * // config.rssLimit may be overridden by smrt.config.js or setConfig()
+ * ```
+ *
+ * @see {@link getPackageConfig}
+ * @see {@link setConfig}
+ * @see {@link SmrtConfig.modules}
+ */
+export declare function getModuleConfig<T extends Record<string, unknown>>(moduleName: string, defaults?: T): T;
+/**
+ * Return the resolved configuration for a named package.
+ *
+ * Identical to {@link getModuleConfig} but reads from `config.packages` instead
+ * of `config.modules`. Use this inside `@happyvertical/smrt-*` packages that
+ * want to expose their own config section without conflicting with user-defined
+ * module names.
+ *
+ * Merges four layers in ascending priority order:
+ * 1. `defaults` (caller-supplied fallbacks)
+ * 2. Global `smrt` section of the loaded config
+ * 3. `packages[packageName]` section of the loaded config
+ * 4. Runtime `packages[packageName]` overrides set via {@link setConfig}
+ *
+ * @param packageName - Key in `config.packages` (e.g., `'ai'`, `'spider'`).
+ * @param defaults - Optional fallback values.
+ * @returns The fully merged package config typed as `T`.
+ *
+ * @example
+ * ```ts
+ * // Inside @happyvertical/smrt-ai package
+ * const config = getPackageConfig('ai', {
+ *   defaultModel: 'gpt-4o-mini',
+ *   maxTokens: 2048,
+ * });
+ * ```
+ *
+ * @see {@link getModuleConfig}
+ * @see {@link setConfig}
+ * @see {@link SmrtConfig.packages}
+ */
+export declare function getPackageConfig<T extends Record<string, unknown>>(packageName: string, defaults?: T): T;
+/**
+ * Apply runtime configuration overrides.
+ *
+ * Deep-merges `config` into an in-memory store that takes the highest priority
+ * in every subsequent {@link getModuleConfig} / {@link getPackageConfig} call.
+ * Successive calls accumulate. When a call explicitly changes the runtime
+ * profile, the stored runtime provider subtree is reset before merging so
+ * profile-specific selectors cannot leak into the new profile.
+ *
+ * Common uses:
+ * - Inject test doubles or environment-specific values without a config file.
+ * - Apply feature flags from a remote source after startup.
+ *
+ * @param config - Partial {@link SmrtConfig} to merge into the runtime store.
+ *   `null` values are ignored (they do not clear existing keys).
+ *
+ * @example
+ * ```ts
+ * setConfig({ modules: { ai: { defaultModel: 'gpt-4o' } } });
+ * ```
+ *
+ * @see {@link clearCache}
+ * @see {@link getModuleConfig}
+ */
+export declare function setConfig(config: Partial<SmrtConfig>): void;
+/**
+ * Reset all cached configuration state.
+ *
+ * Clears three independent caches:
+ * 1. `globalThis.__smrtConfigCache` — the merged config loaded by {@link loadConfig}.
+ * 2. The internal loader cache (`globalThis.__smrtLoaderCachedConfig`) and the
+ *    cosmiconfig explorer instance.
+ * 3. The runtime override store populated by {@link setConfig}.
+ *
+ * After calling this, {@link getConfig} returns `null` and a fresh
+ * {@link loadConfig} call will re-read from disk.
+ *
+ * WARNING: This is a global reset — it affects every module sharing the same
+ * runtime, not just the caller. Use with care outside of test teardown.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => {
+ *   clearCache(); // reset between tests
+ * });
+ * ```
+ *
+ * @see {@link loadConfig}
+ * @see {@link setConfig}
+ */
+export declare function clearCache(): void;
+/**
+ * Type-safe helper for authoring `smrt.config.js` files.
+ *
+ * This is an identity function — it returns its argument unchanged. Its sole
+ * purpose is to provide TypeScript type-checking and IDE auto-completion when
+ * writing the config object literal.
+ *
+ * @param config - The config object to validate against {@link SmrtConfig}.
+ * @returns The same object, unchanged.
+ *
+ * @example
+ * ```js
+ * // smrt.config.js
+ * import { defineConfig } from '@happyvertical/smrt-config';
+ *
+ * export default defineConfig({
+ *   smrt: { logLevel: 'info' },
+ *   site: { name: 'My Site', ... },
+ * });
+ * ```
+ *
+ * @see {@link SmrtConfig}
+ * @see {@link loadConfig}
+ */
+export declare function defineConfig(config: SmrtConfig): SmrtConfig;
+//# sourceMappingURL=index.d.ts.map