@happyvertical/smrt-config 0.51.32 → 0.51.34

package/dist/types.d.ts

@@ -1,858 +1,711 @@
-import { DomainKnowledgeConfig } from '@happyvertical/smrt-types';
-
-/** Canonical config stored at `runtime` in `smrt.config.ts`. */
-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.
- */
-declare type ApplicationRuntimeProfile = 'local' | 'self-hosted' | 'cloud';
-
-declare type AssetOwnership = 'user' | 'operator' | 'managed';
-
-declare type AssetStorageProvider = 'local-files' | 's3-compatible' | 'managed-object-storage';
-
-declare type AuthenticationProvider = 'owner-bootstrap' | 'oidc' | 'magic-link' | 'hosted-identity';
-
-/**
- * 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;
-}
-
-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;
-}
-
-declare type DatabaseEngine = 'sqlite' | 'postgres';
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-
-declare type JobTopology = 'inline' | 'embedded' | 'external' | 'scalable';
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-
-declare type NetworkExposure = 'loopback' | 'public';
-
-declare type OwnerBootstrapMode = 'single-use' | 'disabled';
-
-/** 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[]>;
-    };
-}
-
-declare interface RuntimeAssetProvider {
-    readonly provider: AssetStorageProvider;
-    readonly ownership: AssetOwnership;
-}
-
-declare interface RuntimeAuthenticationProvider {
-    readonly provider: AuthenticationProvider;
-    readonly ownerBootstrap: OwnerBootstrapMode;
-}
-
-declare interface RuntimeDatabaseProvider {
-    readonly engine: DatabaseEngine;
-    readonly connectionOwnership: ConnectionOwnership;
-}
-
-declare interface RuntimeJobProvider {
-    readonly topology: JobTopology;
-}
-
-declare interface RuntimeNetworkProvider {
-    readonly exposure: NetworkExposure;
-    readonly tls: boolean;
-}
-
-/**
- * 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.
- */
-declare interface RuntimeProviderOverrides {
-    database?: Partial<RuntimeDatabaseProvider>;
-    authentication?: Partial<RuntimeAuthenticationProvider>;
-    tenancy?: Partial<RuntimeTenancyProvider>;
-    assets?: Partial<RuntimeAssetProvider>;
-    secrets?: Partial<RuntimeSecretProvider>;
-    jobs?: Partial<RuntimeJobProvider>;
-    network?: Partial<RuntimeNetworkProvider>;
-}
-
-declare interface RuntimeSecretProvider {
-    readonly provider: SecretProvider;
-    readonly ownership: SecretOwnership;
-}
-
-declare interface RuntimeTenancyProvider {
-    readonly mode: TenancyMode;
-    readonly context: TenantContextMode;
-    readonly isolation: TenantIsolation;
-}
-
-/**
- * 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[];
-    };
-}
-
-declare type SecretOwnership = 'user' | 'operator' | 'managed';
-
-declare type SecretProvider = 'local-file' | 'environment' | 'external' | 'managed';
-
-/**
- * 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;
-}
-
-declare type TenancyMode = 'default-tenant' | 'single-tenant' | 'multi-tenant';
-
-declare type TenantContextMode = 'defaulted' | 'required';
-
-declare type TenantIsolation = 'application' | 'database-rls';
-
-export { }
-
-
+import type { DomainKnowledgeConfig } from '@happyvertical/smrt-types';
+import type { ApplicationRuntimeConfig } from './runtime-profile.js';
+/** PostgreSQL ACL contract. Applied only through explicit db:permissions. */
+export 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[]>;
+    };
+}
+/**
+ * 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 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;
+}
+/**
+ * PostgreSQL-specific migration settings.
+ *
+ * Nested under `migrations.postgres` in {@link MigrationsConfig}.
+ */
+export 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;
+}
+/**
+ * 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 interface SchemaContractConfig {
+    requiredObjects?: string[];
+    requiredFields?: string[];
+    requiredDatabaseShape?: {
+        tables?: string[];
+        columns?: string[];
+        indexes?: string[];
+    };
+}
+/**
+ * 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 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;
+}
+/**
+ * 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 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;
+}
+/**
+ * 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 interface CliConfig {
+    /**
+     * Database connection settings
+     */
+    database?: DatabaseConfig;
+    /**
+     * Migration settings
+     */
+    migrations?: MigrationsConfig;
+    /**
+     * Required manifest/object/field/database-shape contract for schema commands.
+     */
+    schemaContract?: SchemaContractConfig;
+}
+/**
+ * A single navigation link item used in site menus.
+ *
+ * @see {@link SiteNavigation}
+ */
+export interface SiteNavigationLink {
+    label: string;
+    href: string;
+    icon?: string;
+}
+/**
+ * Site navigation structure containing primary and optional footer links.
+ *
+ * @see {@link SiteConfig}
+ * @see {@link SiteNavigationLink}
+ */
+export interface SiteNavigation {
+    /** Primary navigation links (header) */
+    primary: SiteNavigationLink[];
+    /** Footer navigation links */
+    footer?: SiteNavigationLink[];
+}
 /**
- * Extend globalThis to include our config cache properties.
- * Using globalThis ensures all module instances share the same config,
- * which is critical in monorepos where the same package can be loaded
- * from different paths (e.g., pnpm store vs workspace symlink).
+ * Geographic location for the site, used for proximity search and display.
  *
- * This fixes issue #543: external packages not receiving user config
- * when smrt-cli loads them.
+ * @see {@link SiteConfig}
+ */
+export 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 theme and branding color palette.
+ *
+ * Colors should be provided as CSS hex values (e.g., `'#3b82f6'`).
+ *
+ * @see {@link SiteConfig}
+ */
+export interface SiteTheme {
+    /** Primary brand color (hex) */
+    primaryColor: string;
+    /** Light variant of primary color */
+    primaryLight?: string;
+    /** Dark variant of primary color */
+    primaryDark?: string;
+}
+/**
+ * Publisher or organization information displayed in site footers and metadata.
+ *
+ * @see {@link SiteConfig}
+ */
+export interface SitePublisher {
+    /** Organization name (e.g., "Blindman Press") */
+    name: string;
+    /** Organization website URL */
+    url?: string;
+    /** GitHub organization URL */
+    github?: string;
+}
+/**
+ * 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 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;
+    };
+}
+/**
+ * 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 https://github.com/happyvertical/smrt/issues/543
+ * @see {@link ExportFileConfig}
  */
-declare global {
-    var __smrtConfigCache: SmrtConfig | null | undefined;
-    var __smrtRuntimeConfig: Partial<SmrtConfig> | undefined;
+export 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;
 }
-
-
-declare global {
-    var __smrtRuntimeConfig: Partial<SmrtConfig> | undefined;
+/**
+ * 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 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;
+}
+/**
+ * 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 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;
+}
+/**
+ * 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 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>;
+    };
 }
-
-
 /**
- * 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).
+ * Options accepted by {@link loadConfig}.
  *
- * @see https://github.com/happyvertical/smrt/issues/543
+ * All fields are optional; omitting them triggers cosmiconfig's default
+ * search behaviour (scan `cwd` upward for `smrt.config.{js,mjs,cjs,json}`).
  */
-declare global {
-    var __smrtLoaderCachedConfig: SmrtConfig | null | undefined;
-    var __smrtLoaderExplorer: ReturnType<typeof cosmiconfig> | null | undefined;
+export 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;
 }
+//# sourceMappingURL=types.d.ts.map