sensemaking 0.12.2 → 0.13.0

package/dist/esm/config.js

@@ -1,599 +0,0 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { SenseError } from './errors.js';
-export const CONFIG_FILENAME = 'sense.config.json';
-export const STATE_DIR = '.sense';
-// Highest sense.config.json `version` this build understands. Older versions auto-migrate on load.
-export const SUPPORTED_CONFIG_VERSION = 4;
-// v1 and v2 were `scan`/`find`-shaped; v3 introduced `presets`. Only the former need the
-// legacy shape check before migrating.
-const FIRST_PRESET_VERSION = 3;
-// Each feature owns its tables, parse-time extraction, and reconcile step; commands degrade when one is off.
-// links/sections/rank are opt-out toggles in the top-level `features` block; embed is not a
-// member of that block -- it is on exactly when an `embed` block names a model.
-const FEATURE_NAMES = [
-    'links',
-    'sections',
-    'rank',
-    'embed'
-];
-// v1 -> v2 migration only: the features v2 introduced as opt-out (embed was opt-in then).
-const V2_OPT_OUT_NAMES = [
-    'links',
-    'sections',
-    'rank'
-];
-export const DEFAULT_EMBED_MODEL = 'minishlab/potion-retrieval-32M';
-export function presetNames(cfg) {
-    return Object.keys(cfg.presets);
-}
-// Whether the tree names a model at all.
-export function embedEnabled(cfg) {
-    var _cfg_embed;
-    return typeof ((_cfg_embed = cfg.embed) === null || _cfg_embed === void 0 ? void 0 : _cfg_embed.model) === 'string' && cfg.embed.model.length > 0;
-}
-// A preset's own vector participation: absent or true means on, false means off.
-export function presetSemanticEnabled(cfg, name) {
-    var _cfg_presets_name;
-    return ((_cfg_presets_name = cfg.presets[name]) === null || _cfg_presets_name === void 0 ? void 0 : _cfg_presets_name.semantic) !== false;
-}
-// Whether embedding needs to run: a model is named AND some preset wants vectors.
-export function anyPresetEmbeds(cfg) {
-    return embedEnabled(cfg) && presetNames(cfg).some((name)=>presetSemanticEnabled(cfg, name));
-}
-// Opt-out features (default on): absent block or key means enabled. `rank` additionally
-// requires `links`. `embed` is derived, not a features-block member: on iff `embed` names a model.
-export function featureEnabled(cfg, name) {
-    var _cfg_features;
-    if (name === 'embed') return anyPresetEmbeds(cfg);
-    const enabled = ((_cfg_features = cfg.features) === null || _cfg_features === void 0 ? void 0 : _cfg_features[name]) !== false;
-    if (name === 'rank') return enabled && featureEnabled(cfg, 'links');
-    return enabled;
-}
-export function enabledFeatures(cfg) {
-    return FEATURE_NAMES.filter((name)=>featureEnabled(cfg, name));
-}
-// Feature states, so "off" and "empty" stay distinguishable in output. `embed` is excluded:
-// it is not a features-block toggle, and `status` reports it on its own line.
-export function featureStates(cfg) {
-    const reported = FEATURE_NAMES.filter((name)=>name !== 'embed');
-    return {
-        on: reported.filter((name)=>featureEnabled(cfg, name)),
-        off: reported.filter((name)=>!featureEnabled(cfg, name))
-    };
-}
-// Resolved embed provider settings, or null when the config names no model. There is no
-// fallback to DEFAULT_EMBED_MODEL: that constant is a template `init` and the v4 migration
-// write into the file, never an implicit runtime default.
-export function embedConfig(cfg) {
-    var _e_type;
-    if (!embedEnabled(cfg)) return null;
-    const e = cfg.embed;
-    return {
-        model: e.model,
-        type: (_e_type = e.type) !== null && _e_type !== void 0 ? _e_type : 'static',
-        url: e.url,
-        key: e.key
-    };
-}
-// The configured FTS5 tokenizer, or undefined for the built-in default. Undefined rather than
-// the default string so featureSignature can leave the segment off entirely for trees that
-// never set it, which is what keeps existing indexes from rebuilding on upgrade.
-export function contentTokenize(cfg) {
-    var _cfg_content;
-    const tokenize = (_cfg_content = cfg.content) === null || _cfg_content === void 0 ? void 0 : _cfg_content.tokenize;
-    return tokenize === undefined || tokenize.trim() === '' ? undefined : tokenize.trim();
-}
-// Cache key over everything indexing derives from, so any change to those inputs rebuilds.
-export function featureSignature(cfg) {
-    const globalPart = enabledFeatures(cfg).filter((name)=>name !== 'embed').join(',');
-    const e = embedConfig(cfg);
-    const embedPart = e ? `embed:${e.type}:${e.model}` : 'embed:off';
-    // One keyed segment per preset so a rebuild notice can name exactly which preset moved.
-    const presetsPart = [
-        ...presetNames(cfg)
-    ].sort().map((name)=>{
-        var _p_exclude;
-        const p = cfg.presets[name];
-        const include = [
-            ...p.include
-        ].sort().join('+');
-        const exclude = [
-            ...(_p_exclude = p.exclude) !== null && _p_exclude !== void 0 ? _p_exclude : []
-        ].sort().join('+');
-        return `preset:${name}:${include}:${exclude}:${p.semantic === false ? 'off' : 'on'}`;
-    }).join('|');
-    const tokenize = contentTokenize(cfg);
-    const parts = [
-        `features:${globalPart}`,
-        embedPart
-    ];
-    if (tokenize !== undefined) parts.push(`tokenize:${tokenize}`);
-    parts.push(presetsPart);
-    return parts.join('|');
-}
-// Looks up a declared preset by name, defaulting to `default`. Throws naming every declared
-// preset when an explicit name is not declared -- the `default` fallback is never unknown
-// itself (validateConfig requires it).
-export function resolvePreset(cfg, name) {
-    const presetName = name !== null && name !== void 0 ? name : 'default';
-    const preset = cfg.presets[presetName];
-    if (!preset) throw new SenseError('PRESET_UNKNOWN', `unknown preset "${presetName}"; declared presets: ${presetNames(cfg).join(', ')}`);
-    return {
-        name: presetName,
-        preset
-    };
-}
-// Precedence, per field: built-ins <- named preset (or `default`) <- caller overrides.
-// `opts` arrives with any saved-query/CLI merge already resolved (src/cli/named.ts).
-export function resolveSearch(cfg, opts = {}) {
-    var _ref, _opts_k, _opts_where, _opts_include, _opts_exclude;
-    const { name: presetName, preset } = resolvePreset(cfg, opts.preset);
-    const k = (_ref = (_opts_k = opts.k) !== null && _opts_k !== void 0 ? _opts_k : preset.k) !== null && _ref !== void 0 ? _ref : 10;
-    const where = (_opts_where = opts.where) !== null && _opts_where !== void 0 ? _opts_where : preset.where;
-    // Each overrides its own side only, so neither clears the other.
-    const include = (_opts_include = opts.include) !== null && _opts_include !== void 0 ? _opts_include : preset.include;
-    // --no-exclude widens past the preset's exclusions; an explicit --exclude alongside it is
-    // still the scope for this command, since it says what to leave out rather than what to keep.
-    const exclude = (_opts_exclude = opts.exclude) !== null && _opts_exclude !== void 0 ? _opts_exclude : opts.noExclude ? undefined : preset.exclude;
-    return {
-        presetName,
-        k,
-        where,
-        include,
-        exclude,
-        semantic: preset.semantic !== false
-    };
-}
-// Pure per-version steps, chained by loadConfig. Intermediate shapes predate the Config type,
-// so steps are loosely typed and only the final result is cast back.
-const MIGRATIONS = {
-    // v1 -> v2: features block introduced, opt-out features enabled (matches the old implicit
-    // behavior of `links` etc. not existing). embed stays absent -- opt-in.
-    1: (cfg)=>({
-            ...cfg,
-            version: 2,
-            features: Object.fromEntries(V2_OPT_OUT_NAMES.map((name)=>[
-                    name,
-                    true
-                ]))
-        }),
-    // v2 -> v3: mechanical-minimal, by decision -- only what keeps an existing config loading.
-    // No restructuring, no preset inference, no query rewriting; real trees get hand-migrated
-    // separately to actually use presets.
-    2: (cfg)=>{
-        var _prevDefaults_find;
-        const { scan, defaults, features, checks, queries, ...rest } = cfg;
-        const scanInclude = scan.include;
-        const nextQueries = {};
-        for (const [name, value] of Object.entries(queries !== null && queries !== void 0 ? queries : {})){
-            if (typeof value === 'string') {
-                nextQueries[name] = value;
-                continue;
-            }
-            const entry = value;
-            // Loosely typed on purpose: this step emits the v3 shape, which still had `semantic`.
-            // The v3 -> v4 step below strips it.
-            const search = {
-                search: entry.find
-            };
-            if (entry.k !== undefined) search.k = entry.k;
-            if (entry.where !== undefined) search.where = entry.where;
-            // semantic: true was opt-in; it is now the default, so it drops. semantic: false is kept.
-            if (entry.semantic === false) search.semantic = false;
-            nextQueries[name] = search;
-        }
-        const prevDefaults = defaults;
-        const defaultWhere = prevDefaults === null || prevDefaults === void 0 ? void 0 : (_prevDefaults_find = prevDefaults.find) === null || _prevDefaults_find === void 0 ? void 0 : _prevDefaults_find.where;
-        // features.embed false becomes semantic:false on every preset produced here.
-        const prevFeatures = features !== null && features !== void 0 ? features : {};
-        const embedWasOff = prevFeatures.embed === false;
-        // Object form carried provider settings (model/type/url/key), not a toggle -- they move
-        // to the v3 top-level `embed` block verbatim; dropping them would silently switch an
-        // api tree back to the built-in static model.
-        const embedProvider = typeof prevFeatures.embed === 'object' && prevFeatures.embed !== null ? prevFeatures.embed : undefined;
-        const { embed: _embed, ...restFeatures } = prevFeatures;
-        const defaultPreset = {
-            include: scanInclude
-        };
-        if (defaultWhere !== undefined) defaultPreset.where = defaultWhere;
-        if (embedWasOff) defaultPreset.semantic = false;
-        // checks (assertions over saved queries) was removed in v3; its queries still run under
-        // `queries`, just without the pass/fail assertion -- reachable now only as a saved query.
-        if (checks !== undefined) {
-            console.error('sense: v2 "checks" was removed in v3 (sense check no longer asserts on saved queries); its queries are carried over under "queries" -- a returned row set is now the reader\'s judgment');
-        }
-        const result = {
-            ...rest,
-            version: 3,
-            presets: {
-                default: defaultPreset
-            },
-            queries: nextQueries
-        };
-        if (embedProvider !== undefined) result.embed = embedProvider;
-        if (Object.keys(restFeatures).length > 0) result.features = restFeatures;
-        return result;
-    },
-    // v3 -> v4: write the model into the file, wrap bare-string queries as { sql }, drop a saved
-    // search's `semantic` (its preset decides). Same effective model, so nothing re-embeds.
-    3: (cfg)=>{
-        var _cfg_queries, _cfg_embed;
-        const presets = cfg.presets;
-        const embedded = Object.values(presets).some((p)=>p.semantic !== false);
-        const nextQueries = {};
-        for (const [name, value] of Object.entries((_cfg_queries = cfg.queries) !== null && _cfg_queries !== void 0 ? _cfg_queries : {})){
-            // v3's bare string meant SQL by inference; v4 makes every entry name its verb.
-            if (typeof value === 'string') {
-                nextQueries[name] = {
-                    sql: value
-                };
-                continue;
-            }
-            if (typeof value !== 'object' || value === null || !('search' in value)) {
-                nextQueries[name] = value;
-                continue;
-            }
-            const { semantic: _semantic, ...rest } = value;
-            nextQueries[name] = rest;
-        }
-        const prev = (_cfg_embed = cfg.embed) !== null && _cfg_embed !== void 0 ? _cfg_embed : {};
-        const result = {
-            ...cfg,
-            version: 4,
-            queries: nextQueries
-        };
-        if (embedded) {
-            var _prev_model, _prev_type;
-            result.embed = {
-                model: (_prev_model = prev.model) !== null && _prev_model !== void 0 ? _prev_model : DEFAULT_EMBED_MODEL,
-                type: (_prev_type = prev.type) !== null && _prev_type !== void 0 ? _prev_type : 'static',
-                ...prev.url !== undefined ? {
-                    url: prev.url
-                } : {},
-                ...prev.key !== undefined ? {
-                    key: prev.key
-                } : {}
-            };
-        } else {
-            delete result.embed;
-            // Dropping settings silently would look like a bug in a tree that had configured an
-            // api endpoint and then turned vectors off; say it, since v4 has no way to carry
-            // provider settings for a tree that does not embed.
-            if (Object.keys(prev).length > 0) console.error('sense: every preset has "semantic": false, so v4 drops the "embed" block (vectors stay off); re-add it, or set a preset\'s semantic back to true, to turn them on');
-        }
-        return result;
-    }
-};
-export function migrateConfig(cfg) {
-    var _cfg_version;
-    const from = (_cfg_version = cfg.version) !== null && _cfg_version !== void 0 ? _cfg_version : 1;
-    let current = cfg;
-    for(let v = from; v < SUPPORTED_CONFIG_VERSION; v++){
-        const step = MIGRATIONS[v];
-        if (!step) throw new SenseError('CONFIG_VERSION_UNSUPPORTED', `no migration from config version ${v}`);
-        current = step(current);
-    }
-    return {
-        cfg: current,
-        from
-    };
-}
-function starterConfig() {
-    return {
-        $schema: 'https://unpkg.com/sensemaking/schema.json',
-        version: SUPPORTED_CONFIG_VERSION,
-        presets: {
-            default: {
-                include: [
-                    '**/*.md'
-                ],
-                k: 10
-            },
-            large: {
-                include: [
-                    '**/*.md'
-                ],
-                k: 20
-            }
-        },
-        // Written out rather than defaulted in code: this line is what makes `sense download`
-        // fetch 124 MB, so it belongs where it can be read and changed.
-        embed: {
-            model: DEFAULT_EMBED_MODEL,
-            type: 'static'
-        },
-        queries: {}
-    };
-}
-// Refuses to overwrite an existing config.
-export function initConfig(dir) {
-    const configPath = join(dir, CONFIG_FILENAME);
-    if (existsSync(configPath)) {
-        throw new SenseError('CONFIG_EXISTS', `${CONFIG_FILENAME} already exists in ${dir}`);
-    }
-    writeFileSync(configPath, `${JSON.stringify(starterConfig(), null, 2)}\n`);
-    return configPath;
-}
-export function findConfigPath(startDir) {
-    let dir = resolve(startDir);
-    for(;;){
-        const candidate = join(dir, CONFIG_FILENAME);
-        if (existsSync(candidate)) return candidate;
-        const parent = dirname(dir);
-        if (parent === dir) return null;
-        dir = parent;
-    }
-}
-// Shape check for hand-edited files, so a typo names itself instead of surfacing as a
-// TypeError. Unknown top-level keys warn (forward compat); unknown keys inside a block error.
-const KNOWN_KEYS = new Set([
-    '$schema',
-    'version',
-    'presets',
-    'features',
-    'embed',
-    'content',
-    'queries'
-]);
-const KNOWN_PRESET_KEYS = new Set([
-    'include',
-    'exclude',
-    'k',
-    'semantic',
-    'where'
-]);
-const KNOWN_FEATURE_KEYS = new Set([
-    'links',
-    'sections',
-    'rank'
-]);
-const KNOWN_EMBED_KEYS = new Set([
-    'model',
-    'type',
-    'url',
-    'key'
-]);
-const KNOWN_CONTENT_KEYS = new Set([
-    'tokenize'
-]);
-const SAVED_SEARCH_KEYS = new Set([
-    'search',
-    'preset',
-    'include',
-    'exclude',
-    'where',
-    'k'
-]);
-function unknownConfigKeys(cfg) {
-    return Object.keys(cfg).filter((k)=>!KNOWN_KEYS.has(k));
-}
-function isNonEmptyStringArray(value) {
-    return Array.isArray(value) && value.length > 0 && value.every((g)=>typeof g === 'string' && g.length > 0);
-}
-// Pre-v3 shape check, just enough for migrateConfig to run safely (it reads scan.include
-// directly). The full v3 shape is checked by validateConfig once migration has produced it.
-function validateLegacyScan(parsed, configPath) {
-    const cfg = typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : null;
-    const scan = cfg === null || cfg === void 0 ? void 0 : cfg.scan;
-    if (!cfg || !scan || !isNonEmptyStringArray(scan.include)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: scan.include must be a non-empty array of glob strings`);
-    }
-}
-// Only the shape is checked here. Whether the linked SQLite accepts the tokenizer is settled
-// by probing it in db.ts, so this never has to carry a table of which version added what.
-function validateContentBlock(value, configPath) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: content must be an object of { tokenize?: string }`);
-    }
-    const block = value;
-    const unknown = Object.keys(block).filter((k)=>!KNOWN_CONTENT_KEYS.has(k));
-    if (unknown.length > 0) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: content has unknown key(s) ${unknown.join(', ')}; content takes tokenize`);
-    }
-    if (block.tokenize !== undefined && (typeof block.tokenize !== 'string' || block.tokenize.trim() === '')) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: content.tokenize must be a non-empty string, e.g. "trigram" or "unicode61 tokenchars '-_'"`);
-    }
-}
-function validateFeaturesBlock(value, configPath) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: features must be an object of name -> boolean`);
-    }
-    const block = value;
-    const unknown = Object.keys(block).filter((k)=>!KNOWN_FEATURE_KEYS.has(k));
-    if (unknown.length > 0) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: features has unknown key(s) ${unknown.join(', ')}; embed is not a features key -- see the top-level "embed" block`);
-    }
-    for (const [name, v] of Object.entries(block)){
-        if (typeof v !== 'boolean') {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: features.${name} must be a boolean`);
-        }
-    }
-}
-function validateEmbedBlock(value, configPath) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: embed must be an object of { model?, type?: "static"|"api", url?, key? }`);
-    }
-    const embed = value;
-    const unknown = Object.keys(embed).filter((k)=>!KNOWN_EMBED_KEYS.has(k));
-    if (unknown.length > 0) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: embed has unknown key(s) ${unknown.join(', ')}`);
-    }
-    if (embed.model !== undefined && typeof embed.model !== 'string') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: embed.model must be a string`);
-    }
-    // The block exists to name a model; provider settings without one would read as "vectors
-    // configured" while embedding stays off, which is the ambiguity v4 removed.
-    if (embed.model === undefined || embed.model === '') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: embed.model is required when the "embed" block is present (it is what turns vectors on); remove the block to index without vectors`);
-    }
-    if (embed.type !== undefined && embed.type !== 'static' && embed.type !== 'api') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: embed.type must be "static" or "api"`);
-    }
-    if (embed.url !== undefined && typeof embed.url !== 'string') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: embed.url must be a string`);
-    }
-    if (embed.key !== undefined && typeof embed.key !== 'string') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: embed.key must be a string`);
-    }
-}
-function validatePreset(name, value, configPath) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets.${name} must be an object`);
-    }
-    const preset = value;
-    const unknown = Object.keys(preset).filter((k)=>!KNOWN_PRESET_KEYS.has(k));
-    if (unknown.length > 0) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets.${name} has unknown key(s) ${unknown.join(', ')}; a preset takes include, exclude, k, semantic, where`);
-    }
-    if (!isNonEmptyStringArray(preset.include)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets.${name}.include must be a non-empty array of glob strings`);
-    }
-    if (preset.exclude !== undefined && !isNonEmptyStringArray(preset.exclude)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets.${name}.exclude must be a non-empty array of glob strings`);
-    }
-    if (preset.semantic !== undefined && typeof preset.semantic !== 'boolean') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets.${name}.semantic must be a boolean`);
-    }
-    if (preset.k !== undefined && (typeof preset.k !== 'number' || !Number.isInteger(preset.k) || preset.k <= 0)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets.${name}.k must be a positive integer`);
-    }
-    if (preset.where !== undefined && typeof preset.where !== 'string') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets.${name}.where must be a SQL condition string`);
-    }
-}
-// A queries.<name> entry: { sql } or a saved search { search, preset?, include?, exclude?, where?, k? }.
-function validateSavedQuery(name, value, configPath) {
-    // A bare string used to mean SQL. It now fails rather than being inferred: an entry says
-    // which of the two verbs it runs, the same choice the CLI makes explicit.
-    if (typeof value === 'string') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name} must say which verb it runs: { "sql": ${JSON.stringify(value.length > 40 ? `${value.slice(0, 37)}...` : value)} } to run it as SQL, or { "search": "..." } for a ranked search`);
-    }
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name} must be { sql } or { search, preset?, include?, exclude?, where?, k? }`);
-    }
-    const entry = value;
-    if ('sql' in entry) {
-        const unknown = Object.keys(entry).filter((k)=>k !== 'sql');
-        if (unknown.length > 0) {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name} has unknown key(s) ${unknown.join(', ')}; a { sql } query takes only sql`);
-        }
-        if (typeof entry.sql !== 'string' || entry.sql.trim() === '') {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.sql must be a non-empty string`);
-        }
-        return;
-    }
-    if ('search' in entry) {
-        const unknown = Object.keys(entry).filter((k)=>!SAVED_SEARCH_KEYS.has(k));
-        if (unknown.length > 0) {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name} has unknown key(s) ${unknown.join(', ')}; a saved search takes search, preset, include, exclude, where, k`);
-        }
-        // A saved entry saves a question; a scope without a question is just flags.
-        if (typeof entry.search !== 'string' || entry.search.trim() === '') {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.search must be non-empty text`);
-        }
-        if (entry.preset !== undefined && (typeof entry.preset !== 'string' || entry.preset.length === 0)) {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.preset must be a preset name`);
-        }
-        if (entry.include !== undefined && !isNonEmptyStringArray(entry.include)) {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.include must be a non-empty array of glob strings`);
-        }
-        if (entry.exclude !== undefined && !isNonEmptyStringArray(entry.exclude)) {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.exclude must be a non-empty array of glob strings`);
-        }
-        if (entry.where !== undefined && typeof entry.where !== 'string') {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.where must be a SQL condition string`);
-        }
-        if (entry.k !== undefined && (typeof entry.k !== 'number' || !Number.isInteger(entry.k) || entry.k <= 0)) {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.k must be a positive integer`);
-        }
-        return;
-    }
-    throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name} must be { sql } or { search, preset?, include?, exclude?, where?, k? }`);
-}
-function validateConfig(parsed, configPath) {
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: config must be a JSON object`);
-    }
-    const cfg = parsed;
-    // `checks` is rejected by name, not warned: silence would hide that assertions are gone.
-    if (cfg.checks !== undefined) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: checks was removed in v3 -- sense check no longer asserts on saved queries; a returned row set is the reader's judgment`);
-    }
-    const presets = cfg.presets;
-    if (!presets || typeof presets !== 'object' || Array.isArray(presets) || Object.keys(presets).length === 0) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets must be a non-empty object of preset name -> { include, exclude?, k?, semantic?, where? }`);
-    }
-    for (const [name, value] of Object.entries(presets)){
-        validatePreset(name, value, configPath);
-    }
-    if (presets.default === undefined) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: presets must include a "default" preset`);
-    }
-    if (cfg.queries === undefined) cfg.queries = {};
-    if (typeof cfg.queries !== 'object' || cfg.queries === null || Array.isArray(cfg.queries)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: queries must be an object of name -> { sql } or { search }`);
-    }
-    const queries = cfg.queries;
-    for (const [name, value] of Object.entries(queries)){
-        validateSavedQuery(name, value, configPath);
-    }
-    if (cfg.features !== undefined) {
-        validateFeaturesBlock(cfg.features, configPath);
-    }
-    if (cfg.embed !== undefined) {
-        validateEmbedBlock(cfg.embed, configPath);
-    }
-    if (cfg.content !== undefined) {
-        validateContentBlock(cfg.content, configPath);
-    }
-    return cfg;
-}
-export function loadConfig(explicitPath) {
-    let configPath;
-    if (explicitPath) {
-        configPath = resolve(process.cwd(), explicitPath);
-        if (!existsSync(configPath)) throw new SenseError('CONFIG_NOT_FOUND', `config not found: ${configPath}`);
-    } else {
-        const found = findConfigPath(process.cwd());
-        if (!found) {
-            throw new SenseError('CONFIG_NOT_FOUND', `could not find ${CONFIG_FILENAME} in ${process.cwd()} or any parent directory`);
-        }
-        configPath = found;
-    }
-    const raw = readFileSync(configPath, 'utf8');
-    const parsed = JSON.parse(raw);
-    // Ahead of both the version gate and legacy/current shape checks: a non-object file (or
-    // an array -- typeof [] is also 'object') is malformed at every version, so it gets one
-    // error regardless of which branch would otherwise run.
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: config must be a JSON object`);
-    }
-    // Version gate before shape validation: a config written by a newer sense should fail
-    // with "requires a newer sense", not with shape errors its own version may not have.
-    const version = typeof parsed === 'object' && parsed !== null && typeof parsed.version === 'number' ? parsed.version : 1;
-    if (version > SUPPORTED_CONFIG_VERSION) {
-        throw new SenseError('CONFIG_VERSION_UNSUPPORTED', `config version ${version} requires a newer sense`);
-    }
-    // validateConfig only knows the current shape, so scan-shaped files (pre-v3) get a minimal
-    // check, migrate, then the full one on the result.
-    let cfg;
-    let migratedFrom;
-    if (version < SUPPORTED_CONFIG_VERSION) {
-        if (version < FIRST_PRESET_VERSION) validateLegacyScan(parsed, configPath);
-        const result = migrateConfig(parsed);
-        cfg = validateConfig(result.cfg, configPath);
-        migratedFrom = result.from;
-        writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}\n`);
-    } else {
-        cfg = validateConfig(parsed, configPath);
-    }
-    const unknownKeys = unknownConfigKeys(cfg);
-    return {
-        ...cfg,
-        baseDir: dirname(configPath),
-        configPath,
-        migratedFrom,
-        unknownKeys: unknownKeys.length > 0 ? unknownKeys : undefined
-    };
-}