sensemaking 0.8.0 → 0.9.0

package/dist/esm/config.js

@@ -4,27 +4,42 @@ 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 = 2;
+export const SUPPORTED_CONFIG_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 (absent = on); embed is opt-in (absent = off) -- most trees don't need vectors.
+// links/sections/rank are opt-out toggles in the top-level `features` block; embed is not a
+// member of that block -- it is derived from whether any declared preset has semantic on.
 const FEATURE_NAMES = [
     'links',
     'sections',
     'rank',
     'embed'
 ];
-const OPT_OUT_NAMES = [
+// 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';
-// Opt-out features: absent block or key means enabled. `rank` additionally requires `links`.
-// `embed` is the opposite: enabled only when the config says so.
+export function presetNames(cfg) {
+    return Object.keys(cfg.presets);
+}
+// A preset's own resolved 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 at all: true when at least one declared preset wants vectors.
+export function anyPresetEmbeds(cfg) {
+    return 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 any declared
+// preset has semantic on.
 export function featureEnabled(cfg, name) {
-    var _cfg_features, _cfg_features1;
-    if (name === 'embed') return Boolean((_cfg_features = cfg.features) === null || _cfg_features === void 0 ? void 0 : _cfg_features.embed);
-    const enabled = ((_cfg_features1 = cfg.features) === null || _cfg_features1 === void 0 ? void 0 : _cfg_features1[name]) !== false;
+    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;
 }
@@ -39,40 +54,158 @@ export function featureStates(cfg) {
         off: FEATURE_NAMES.filter((name)=>!featureEnabled(cfg, name))
     };
 }
-// Resolved embed settings, or null when the feature is off.
+// Resolved embed provider settings, or null when no preset wants embeddings at all.
 export function embedConfig(cfg) {
-    var _o_model, _o_type;
-    var _cfg_features;
-    const e = (_cfg_features = cfg.features) === null || _cfg_features === void 0 ? void 0 : _cfg_features.embed;
-    if (!e) return null;
-    const o = e === true ? {} : e;
+    var _cfg_embed, _e_model, _e_type;
+    if (!anyPresetEmbeds(cfg)) return null;
+    const e = (_cfg_embed = cfg.embed) !== null && _cfg_embed !== void 0 ? _cfg_embed : {};
     return {
-        model: (_o_model = o.model) !== null && _o_model !== void 0 ? _o_model : DEFAULT_EMBED_MODEL,
-        type: (_o_type = o.type) !== null && _o_type !== void 0 ? _o_type : 'static',
-        url: o.url,
-        key: o.key
+        model: (_e_model = e.model) !== null && _e_model !== void 0 ? _e_model : DEFAULT_EMBED_MODEL,
+        type: (_e_type = e.type) !== null && _e_type !== void 0 ? _e_type : 'static',
+        url: e.url,
+        key: e.key
     };
 }
-// Cache-key string: embed carries its type + model so a model change rebuilds like a toggle.
+// Cache-key string: embed carries its type + model so a model change rebuilds like a toggle,
+// and every declared preset carries its include/exclude/semantic so an edit to any of those
+// rebuilds too -- indexing and embedding are both derived from presets, so any change to the
+// derivation inputs must invalidate the cache.
 export function featureSignature(cfg) {
-    return enabledFeatures(cfg).map((name)=>{
-        if (name !== 'embed') return name;
-        const e = embedConfig(cfg);
-        return `embed:${e === null || e === void 0 ? void 0 : e.type}:${e === null || e === void 0 ? void 0 : e.model}`;
-    }).join(',');
+    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('|');
+    return [
+        `features:${globalPart}`,
+        embedPart,
+        presetsPart
+    ].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
+    };
+}
+// Resolution precedence: built-ins (k=10, semantic on, whole-index scope) <- named preset's
+// fields (or `default` when none named) <- caller overrides. Each stage overrides only the
+// fields it sets. `opts` here is expected to already carry whatever a saved query and an
+// explicit CLI flag resolved between themselves (src/cli/named.ts does that `cli ?? saved`
+// merge before calling in) -- one `??` per field composes the full four-stage chain, since
+// `??` is associative field-by-field.
+export function resolveSearch(cfg, opts = {}) {
+    var _ref, _opts_k, _opts_where, _opts_include;
+    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;
+    // An explicit include (CLI --include, or a saved search's own `include`) is a full ad hoc
+    // scope override -- it replaces the preset's include/exclude pair rather than layering on
+    // top of it, the same "replaces, doesn't AND" rule --where already uses.
+    const include = (_opts_include = opts.include) !== null && _opts_include !== void 0 ? _opts_include : preset.include;
+    const exclude = opts.include ? undefined : preset.exclude;
+    const semantic = opts.semantic !== undefined ? opts.semantic : preset.semantic !== false;
+    return {
+        presetName,
+        k,
+        where,
+        include,
+        exclude,
+        semantic
+    };
 }
 // Pure per-version steps; loadConfig chains them from the file's version up to SUPPORTED_CONFIG_VERSION.
+// Intermediate shapes predate the current Config type (v1 has no features block, v2 has
+// scan/find not presets/search), so steps work loosely-typed and only the final result is cast
+// back to Config.
 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(OPT_OUT_NAMES.map((name)=>[
+            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;
+            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: true/absent -> simply removed (v3 default is on). An explicit `false`
+        // becomes semantic: false on every preset this migration produces -- there is only ever
+        // one (`default`), since v2 has no notion of multiple scopes, but the rule is written to
+        // apply to "every migrated preset" rather than hardcoded to `default` in case a later
+        // migration step ever produces more than one.
+        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;
+    }
 };
 export function migrateConfig(cfg) {
     var _cfg_version;
@@ -92,15 +225,20 @@ function starterConfig() {
     return {
         $schema: 'https://unpkg.com/sensemaking/schema.json',
         version: SUPPORTED_CONFIG_VERSION,
-        scan: {
-            include: [
-                '**/*.md'
-            ]
+        presets: {
+            default: {
+                include: [
+                    '**/*.md'
+                ],
+                k: 10
+            },
+            large: {
+                include: [
+                    '**/*.md'
+                ],
+                k: 20
+            }
         },
-        features: Object.fromEntries(OPT_OUT_NAMES.map((name)=>[
-                name,
-                true
-            ])),
         queries: {}
     };
 }
@@ -125,114 +263,202 @@ export function findConfigPath(startDir) {
 }
 // Shape check for hand-edited files: a typo'd config fails with a named error, not a
 // TypeError from whatever code touched the missing field first. `queries` is optional
-// on disk (absent = none); `scan.include` has no usable default.
-// Keys each block actually reads. A key outside these sets is accepted and ignored, which
-// looks identical to working -- one field report set `scan.exclude`, saw no change in doc
-// count and no warning, and reasonably concluded the filter had applied. Reported as a
-// warning rather than an error so a config carrying an unknown key still runs.
+// on disk (absent = none); `presets` has no usable default.
+// Unknown top-level keys are reported as a soft warning (cli.ts prints it) rather than an
+// error, so a config carrying a stray field still runs -- but unknown keys inside a preset,
+// features, embed, or saved-query block are hard errors: those blocks are small and fully
+// owned, so a typo there is far more likely a mistake than a forward-compat field.
 const KNOWN_KEYS = new Set([
     '$schema',
     'version',
-    'scan',
+    'presets',
     'features',
-    'defaults',
-    'checks',
+    'embed',
     'queries'
 ]);
-const KNOWN_SCAN_KEYS = new Set([
-    'include'
+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 SAVED_SEARCH_KEYS = new Set([
+    'search',
+    'preset',
+    'include',
+    'where',
+    'k',
+    'semantic'
 ]);
 function unknownConfigKeys(cfg) {
-    const unknown = Object.keys(cfg).filter((k)=>!KNOWN_KEYS.has(k)).map((k)=>k);
-    const scan = cfg.scan;
-    if (scan && typeof scan === 'object' && !Array.isArray(scan)) {
-        unknown.push(...Object.keys(scan).filter((k)=>!KNOWN_SCAN_KEYS.has(k)).map((k)=>`scan.${k}`));
+    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`);
+    }
+}
+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 features = cfg.features;
-    if (features && typeof features === 'object' && !Array.isArray(features)) {
-        unknown.push(...Object.keys(features).filter((k)=>!FEATURE_NAMES.includes(k)).map((k)=>`features.${k}`));
+    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 and each preset's "semantic"`);
+    }
+    for (const [name, v] of Object.entries(block)){
+        if (typeof v !== 'boolean') {
+            throw new SenseError('CONFIG_INVALID', `${configPath}: features.${name} must be a boolean`);
+        }
     }
-    return unknown;
 }
-const SAVED_FIND_KEYS = new Set([
-    'find',
-    'k',
-    'where',
-    'semantic'
-]);
-// A queries.<name> entry that isn't a SQL string must be a saved find: { find, k?, where?, semantic? }.
-function validateSavedFind(name, value, configPath) {
+function validateEmbedBlock(value, configPath) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name} must be a SQL string or { find, k?, where?, semantic? }`);
+        throw new SenseError('CONFIG_INVALID', `${configPath}: embed must be an object of { model?, type?: "static"|"api", url?, key? }`);
     }
-    const entry = value;
-    const unknown = Object.keys(entry).filter((k)=>!SAVED_FIND_KEYS.has(k));
+    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}: queries.${name} has unknown key(s) ${unknown.join(', ')}; a saved find takes find, k, where, semantic`);
+        throw new SenseError('CONFIG_INVALID', `${configPath}: embed has unknown key(s) ${unknown.join(', ')}`);
     }
-    if (typeof entry.find !== 'string') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.find must be a string`);
+    if (embed.model !== undefined && typeof embed.model !== 'string') {
+        throw new SenseError('CONFIG_INVALID', `${configPath}: embed.model must be a 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`);
+    if (embed.type !== undefined && embed.type !== 'static' && embed.type !== 'api') {
+        throw new SenseError('CONFIG_INVALID', `${configPath}: embed.type must be "static" or "api"`);
     }
-    if (entry.where !== undefined && typeof entry.where !== 'string') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.where must be a SQL condition string`);
+    if (embed.url !== undefined && typeof embed.url !== 'string') {
+        throw new SenseError('CONFIG_INVALID', `${configPath}: embed.url must be a string`);
     }
-    if (entry.semantic !== undefined && typeof entry.semantic !== 'boolean') {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.semantic must be a boolean`);
+    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.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.semantic !== undefined && typeof preset.semantic !== 'boolean') {
+        throw new SenseError('CONFIG_INVALID', `${configPath}: presets.${name}.semantic must be a boolean`);
+    }
+    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: a SQL string, { sql }, or a saved search { search, preset?, include?, where?, k?, semantic? }.
+function validateSavedQuery(name, value, configPath) {
+    if (typeof value === 'string') return;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name} must be a SQL string, { sql }, or { search, preset?, include?, where?, k?, semantic? }`);
+    }
+    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, where, k, semantic`);
+        }
+        // A saved query 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.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`);
+        }
+        if (entry.semantic !== undefined && typeof entry.semantic !== 'boolean') {
+            throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name}.semantic must be a boolean`);
+        }
+        return;
+    }
+    throw new SenseError('CONFIG_INVALID', `${configPath}: queries.${name} must be a SQL string, { sql }, or { search, preset?, include?, where?, k?, semantic? }`);
+}
 function validateConfig(parsed, configPath) {
-    var _cfg_features;
-    var _defaults_find;
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
         throw new SenseError('CONFIG_INVALID', `${configPath}: config must be a JSON object`);
     }
     const cfg = parsed;
-    const scan = cfg.scan;
-    if (!scan || !Array.isArray(scan.include) || scan.include.length === 0 || !scan.include.every((g)=>typeof g === 'string')) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: scan.include must be a non-empty array of glob strings`);
+    // `checks` (assertions over saved queries) was removed in v3, not merely deprecated: a
+    // hand-written v3 config still carrying it gets a named rejection rather than a silent
+    // "unknown key" warning, since silence here would hide that the assertion behavior it
+    // implies no longer exists.
+    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`);
     }
-    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 string or saved find`);
+    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(cfg.queries)){
-        if (typeof value === 'string') continue;
-        validateSavedFind(name, value, configPath);
+    for (const [name, value] of Object.entries(presets)){
+        validatePreset(name, value, configPath);
     }
-    const defaults = cfg.defaults;
-    if (defaults !== undefined && (typeof defaults !== 'object' || defaults === null || Array.isArray(defaults) || defaults.find !== undefined && typeof ((_defaults_find = defaults.find) === null || _defaults_find === void 0 ? void 0 : _defaults_find.where) !== 'string')) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: defaults.find.where must be a SQL condition string`);
+    if (presets.default === undefined) {
+        throw new SenseError('CONFIG_INVALID', `${configPath}: presets must include a "default" preset`);
     }
-    const checks = cfg.checks;
-    if (checks !== undefined) {
-        var _cfg_queries;
-        if (typeof checks !== 'object' || checks === null || Array.isArray(checks) || !Object.values(checks).every((v)=>v === 'empty')) {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: checks must be an object of query name -> "empty"`);
-        }
-        const queries = (_cfg_queries = cfg.queries) !== null && _cfg_queries !== void 0 ? _cfg_queries : {};
-        for (const name of Object.keys(checks)){
-            if (queries[name] === undefined) throw new SenseError('CONFIG_INVALID', `${configPath}: checks names "${name}", which is not a saved query`);
-            if (typeof queries[name] !== 'string') throw new SenseError('CONFIG_INVALID', `${configPath}: checks names "${name}", which is a saved find, not a SQL query`);
-        }
+    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 string, { sql }, or saved search`);
     }
-    if (cfg.features !== undefined && (typeof cfg.features !== 'object' || cfg.features === null || Array.isArray(cfg.features))) {
-        throw new SenseError('CONFIG_INVALID', `${configPath}: features must be an object of name -> boolean`);
+    const queries = cfg.queries;
+    for (const [name, value] of Object.entries(queries)){
+        validateSavedQuery(name, value, configPath);
     }
-    for (const [name, value] of Object.entries((_cfg_features = cfg.features) !== null && _cfg_features !== void 0 ? _cfg_features : {})){
-        if (typeof value === 'boolean') continue;
-        // embed alone takes an object form: { model?, type?: static|api, url?, key? }.
-        const embed = value;
-        const shapeOk = name === 'embed' && typeof value === 'object' && value !== null && !Array.isArray(value) && [
-            'model',
-            'url',
-            'key'
-        ].every((f)=>embed[f] === undefined || typeof embed[f] === 'string') && (embed.type === undefined || embed.type === 'static' || embed.type === 'api');
-        if (!shapeOk) {
-            throw new SenseError('CONFIG_INVALID', `${configPath}: features.${name} must be a boolean${name === 'embed' ? ' or { model?, type?: "static"|"api", url?, key? }' : ''}`);
-        }
+    if (cfg.features !== undefined) {
+        validateFeaturesBlock(cfg.features, configPath);
+    }
+    if (cfg.embed !== undefined) {
+        validateEmbedBlock(cfg.embed, configPath);
     }
     return cfg;
 }
@@ -250,19 +476,33 @@ export function loadConfig(explicitPath) {
     }
     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`);
     }
-    let cfg = validateConfig(parsed, configPath);
+    // validateConfig only understands the current v3 shape (presets, saved-query object
+    // shapes); a pre-v3 file on disk is scan/find-shaped and must migrate before it can pass
+    // that check. Validate just enough of the old shape to migrate safely, migrate, then run
+    // the full v3 validateConfig on the migrated result -- the shape that actually lands on
+    // disk and in ResolvedConfig.
+    let cfg;
     let migratedFrom;
     if (version < SUPPORTED_CONFIG_VERSION) {
-        const result = migrateConfig(cfg);
-        cfg = result.cfg;
+        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 {