sensemaking 0.7.2 → 0.9.0

package/dist/cjs/config.js

@@ -21,6 +21,9 @@ _export(exports, {
     get SUPPORTED_CONFIG_VERSION () {
         return SUPPORTED_CONFIG_VERSION;
     },
+    get anyPresetEmbeds () {
+        return anyPresetEmbeds;
+    },
     get embedConfig () {
         return embedConfig;
     },
@@ -47,6 +50,18 @@ _export(exports, {
     },
     get migrateConfig () {
         return migrateConfig;
+    },
+    get presetNames () {
+        return presetNames;
+    },
+    get presetSemanticEnabled () {
+        return presetSemanticEnabled;
+    },
+    get resolvePreset () {
+        return resolvePreset;
+    },
+    get resolveSearch () {
+        return resolveSearch;
     }
 });
 var _nodefs = require("node:fs");
@@ -148,6 +163,42 @@ function _object_spread_props(target, source) {
     }
     return target;
 }
+function _object_without_properties(source, excluded) {
+    if (source == null) return {};
+    var target = {}, sourceKeys, key, i;
+    if (typeof Reflect !== "undefined" && Reflect.ownKeys) {
+        sourceKeys = Reflect.ownKeys(Object(source));
+        for(i = 0; i < sourceKeys.length; i++){
+            key = sourceKeys[i];
+            if (excluded.indexOf(key) >= 0) continue;
+            if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue;
+            target[key] = source[key];
+        }
+        return target;
+    }
+    target = _object_without_properties_loose(source, excluded);
+    if (Object.getOwnPropertySymbols) {
+        sourceKeys = Object.getOwnPropertySymbols(source);
+        for(i = 0; i < sourceKeys.length; i++){
+            key = sourceKeys[i];
+            if (excluded.indexOf(key) >= 0) continue;
+            if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue;
+            target[key] = source[key];
+        }
+    }
+    return target;
+}
+function _object_without_properties_loose(source, excluded) {
+    if (source == null) return {};
+    var target = {}, sourceKeys = Object.getOwnPropertyNames(source), key, i;
+    for(i = 0; i < sourceKeys.length; i++){
+        key = sourceKeys[i];
+        if (excluded.indexOf(key) >= 0) continue;
+        if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue;
+        target[key] = source[key];
+    }
+    return target;
+}
 function _sliced_to_array(arr, i) {
     return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
 }
@@ -168,25 +219,39 @@ function _unsupported_iterable_to_array(o, minLen) {
 }
 var CONFIG_FILENAME = 'sense.config.json';
 var STATE_DIR = '.sense';
-var SUPPORTED_CONFIG_VERSION = 2;
-// Each feature owns its tables, parse-time extraction, and reconcile step; verbs 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.
+var 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 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.
 var FEATURE_NAMES = [
     'links',
     'sections',
     'rank',
     'embed'
 ];
-var OPT_OUT_NAMES = [
+// v1 -> v2 migration only: the features v2 introduced as opt-out (embed was opt-in then).
+var V2_OPT_OUT_NAMES = [
     'links',
     'sections',
     'rank'
 ];
 var DEFAULT_EMBED_MODEL = 'minishlab/potion-retrieval-32M';
+function presetNames(cfg) {
+    return Object.keys(cfg.presets);
+}
+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;
+}
+function anyPresetEmbeds(cfg) {
+    return presetNames(cfg).some(function(name) {
+        return presetSemanticEnabled(cfg, name);
+    });
+}
 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);
-    var 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);
+    var 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;
 }
@@ -206,39 +271,166 @@ function featureStates(cfg) {
     };
 }
 function embedConfig(cfg) {
-    var _o_model, _o_type;
-    var _cfg_features;
-    var e = (_cfg_features = cfg.features) === null || _cfg_features === void 0 ? void 0 : _cfg_features.embed;
-    if (!e) return null;
-    var o = e === true ? {} : e;
+    var _cfg_embed, _e_model, _e_type;
+    if (!anyPresetEmbeds(cfg)) return null;
+    var 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
     };
 }
 function featureSignature(cfg) {
-    return enabledFeatures(cfg).map(function(name) {
-        if (name !== 'embed') return name;
-        var e = embedConfig(cfg);
-        return "embed:".concat(e === null || e === void 0 ? void 0 : e.type, ":").concat(e === null || e === void 0 ? void 0 : e.model);
+    var globalPart = enabledFeatures(cfg).filter(function(name) {
+        return name !== 'embed';
     }).join(',');
+    var e = embedConfig(cfg);
+    var embedPart = e ? "embed:".concat(e.type, ":").concat(e.model) : 'embed:off';
+    // One keyed segment per preset so a rebuild notice can name exactly which preset moved.
+    var presetsPart = _to_consumable_array(presetNames(cfg)).sort().map(function(name) {
+        var _p_exclude;
+        var p = cfg.presets[name];
+        var include = _to_consumable_array(p.include).sort().join('+');
+        var exclude = _to_consumable_array((_p_exclude = p.exclude) !== null && _p_exclude !== void 0 ? _p_exclude : []).sort().join('+');
+        return "preset:".concat(name, ":").concat(include, ":").concat(exclude, ":").concat(p.semantic === false ? 'off' : 'on');
+    }).join('|');
+    return [
+        "features:".concat(globalPart),
+        embedPart,
+        presetsPart
+    ].join('|');
+}
+function resolvePreset(cfg, name) {
+    var presetName = name !== null && name !== void 0 ? name : 'default';
+    var preset = cfg.presets[presetName];
+    if (!preset) throw new _errorsts.SenseError('PRESET_UNKNOWN', 'unknown preset "'.concat(presetName, '"; declared presets: ').concat(presetNames(cfg).join(', ')));
+    return {
+        name: presetName,
+        preset: preset
+    };
+}
+function resolveSearch(cfg) {
+    var opts = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    var _ref, _opts_k, _opts_where, _opts_include;
+    var _resolvePreset = resolvePreset(cfg, opts.preset), presetName = _resolvePreset.name, preset = _resolvePreset.preset;
+    var k = (_ref = (_opts_k = opts.k) !== null && _opts_k !== void 0 ? _opts_k : preset.k) !== null && _ref !== void 0 ? _ref : 10;
+    var 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.
+    var include = (_opts_include = opts.include) !== null && _opts_include !== void 0 ? _opts_include : preset.include;
+    var exclude = opts.include ? undefined : preset.exclude;
+    var semantic = opts.semantic !== undefined ? opts.semantic : preset.semantic !== false;
+    return {
+        presetName: presetName,
+        k: k,
+        where: where,
+        include: include,
+        exclude: exclude,
+        semantic: 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.
 var 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: function(cfg) {
         return _object_spread_props(_object_spread({}, cfg), {
             version: 2,
-            features: Object.fromEntries(OPT_OUT_NAMES.map(function(name) {
+            features: Object.fromEntries(V2_OPT_OUT_NAMES.map(function(name) {
                 return [
                     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: function(cfg) {
+        var _prevDefaults_find;
+        var scan = cfg.scan, defaults = cfg.defaults, features = cfg.features, checks = cfg.checks, queries = cfg.queries, rest = _object_without_properties(cfg, [
+            "scan",
+            "defaults",
+            "features",
+            "checks",
+            "queries"
+        ]);
+        var scanInclude = scan.include;
+        var nextQueries = {};
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = Object.entries(queries !== null && queries !== void 0 ? queries : {})[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var _step_value = _sliced_to_array(_step.value, 2), name = _step_value[0], value = _step_value[1];
+                if (typeof value === 'string') {
+                    nextQueries[name] = value;
+                    continue;
+                }
+                var entry = value;
+                var 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;
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+        var prevDefaults = defaults;
+        var 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.
+        var prevFeatures = features !== null && features !== void 0 ? features : {};
+        var 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.
+        var embedProvider = _type_of(prevFeatures.embed) === 'object' && prevFeatures.embed !== null ? prevFeatures.embed : undefined;
+        var _embed = prevFeatures.embed, restFeatures = _object_without_properties(prevFeatures, [
+            "embed"
+        ]);
+        var 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');
+        }
+        var result = _object_spread_props(_object_spread({}, 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;
     }
 };
 function migrateConfig(cfg) {
@@ -259,17 +451,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(function(name) {
-            return [
-                name,
-                true
-            ];
-        })),
         queries: {}
     };
 }
@@ -293,124 +488,248 @@ 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.
 var KNOWN_KEYS = new Set([
     '$schema',
     'version',
-    'scan',
+    'presets',
     'features',
-    'defaults',
-    'checks',
+    'embed',
     'queries'
 ]);
-var KNOWN_SCAN_KEYS = new Set([
-    'include'
+var KNOWN_PRESET_KEYS = new Set([
+    'include',
+    'exclude',
+    'k',
+    'semantic',
+    'where'
+]);
+var KNOWN_FEATURE_KEYS = new Set([
+    'links',
+    'sections',
+    'rank'
+]);
+var KNOWN_EMBED_KEYS = new Set([
+    'model',
+    'type',
+    'url',
+    'key'
+]);
+var SAVED_SEARCH_KEYS = new Set([
+    'search',
+    'preset',
+    'include',
+    'where',
+    'k',
+    'semantic'
 ]);
 function unknownConfigKeys(cfg) {
-    var unknown = Object.keys(cfg).filter(function(k) {
+    return Object.keys(cfg).filter(function(k) {
         return !KNOWN_KEYS.has(k);
-    }).map(function(k) {
-        return k;
     });
-    var scan = cfg.scan;
-    if (scan && (typeof scan === "undefined" ? "undefined" : _type_of(scan)) === 'object' && !Array.isArray(scan)) {
-        var _unknown;
-        (_unknown = unknown).push.apply(_unknown, _to_consumable_array(Object.keys(scan).filter(function(k) {
-            return !KNOWN_SCAN_KEYS.has(k);
-        }).map(function(k) {
-            return "scan.".concat(k);
-        })));
-    }
-    var features = cfg.features;
-    if (features && (typeof features === "undefined" ? "undefined" : _type_of(features)) === 'object' && !Array.isArray(features)) {
-        var _unknown1;
-        (_unknown1 = unknown).push.apply(_unknown1, _to_consumable_array(Object.keys(features).filter(function(k) {
-            return !FEATURE_NAMES.includes(k);
-        }).map(function(k) {
-            return "features.".concat(k);
-        })));
-    }
-    return unknown;
+}
+function isNonEmptyStringArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every(function(g) {
+        return 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) {
+    var cfg = (typeof parsed === "undefined" ? "undefined" : _type_of(parsed)) === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    var scan = cfg === null || cfg === void 0 ? void 0 : cfg.scan;
+    if (!cfg || !scan || !isNonEmptyStringArray(scan.include)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": scan.include must be a non-empty array of glob strings"));
+    }
+}
+function validateFeaturesBlock(value, configPath) {
+    if ((typeof value === "undefined" ? "undefined" : _type_of(value)) !== 'object' || value === null || Array.isArray(value)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": features must be an object of name -> boolean"));
+    }
+    var block = value;
+    var unknown = Object.keys(block).filter(function(k) {
+        return !KNOWN_FEATURE_KEYS.has(k);
+    });
+    if (unknown.length > 0) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": features has unknown key(s) ").concat(unknown.join(', '), '; embed is not a features key -- see the top-level "embed" block and each preset\'s "semantic"'));
+    }
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = Object.entries(block)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array(_step.value, 2), name = _step_value[0], v = _step_value[1];
+            if (typeof v !== 'boolean') {
+                throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": features.").concat(name, " must be a boolean"));
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+}
+function validateEmbedBlock(value, configPath) {
+    if ((typeof value === "undefined" ? "undefined" : _type_of(value)) !== 'object' || value === null || Array.isArray(value)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ': embed must be an object of { model?, type?: "static"|"api", url?, key? }'));
+    }
+    var embed = value;
+    var unknown = Object.keys(embed).filter(function(k) {
+        return !KNOWN_EMBED_KEYS.has(k);
+    });
+    if (unknown.length > 0) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": embed has unknown key(s) ").concat(unknown.join(', ')));
+    }
+    if (embed.model !== undefined && typeof embed.model !== 'string') {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": embed.model must be a string"));
+    }
+    if (embed.type !== undefined && embed.type !== 'static' && embed.type !== 'api') {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ': embed.type must be "static" or "api"'));
+    }
+    if (embed.url !== undefined && typeof embed.url !== 'string') {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": embed.url must be a string"));
+    }
+    if (embed.key !== undefined && typeof embed.key !== 'string') {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": embed.key must be a string"));
+    }
+}
+function validatePreset(name, value, configPath) {
+    if ((typeof value === "undefined" ? "undefined" : _type_of(value)) !== 'object' || value === null || Array.isArray(value)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": presets.").concat(name, " must be an object"));
+    }
+    var preset = value;
+    var unknown = Object.keys(preset).filter(function(k) {
+        return !KNOWN_PRESET_KEYS.has(k);
+    });
+    if (unknown.length > 0) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": presets.").concat(name, " has unknown key(s) ").concat(unknown.join(', '), "; a preset takes include, exclude, k, semantic, where"));
+    }
+    if (!isNonEmptyStringArray(preset.include)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": presets.").concat(name, ".include must be a non-empty array of glob strings"));
+    }
+    if (preset.exclude !== undefined && !isNonEmptyStringArray(preset.exclude)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": presets.").concat(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 _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": presets.").concat(name, ".k must be a positive integer"));
+    }
+    if (preset.semantic !== undefined && typeof preset.semantic !== 'boolean') {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": presets.").concat(name, ".semantic must be a boolean"));
+    }
+    if (preset.where !== undefined && typeof preset.where !== 'string') {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": presets.").concat(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 === "undefined" ? "undefined" : _type_of(value)) !== 'object' || value === null || Array.isArray(value)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, " must be a SQL string, { sql }, or { search, preset?, include?, where?, k?, semantic? }"));
+    }
+    var entry = value;
+    if ('sql' in entry) {
+        var unknown = Object.keys(entry).filter(function(k) {
+            return k !== 'sql';
+        });
+        if (unknown.length > 0) {
+            throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, " has unknown key(s) ").concat(unknown.join(', '), "; a { sql } query takes only sql"));
+        }
+        if (typeof entry.sql !== 'string' || entry.sql.trim() === '') {
+            throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, ".sql must be a non-empty string"));
+        }
+        return;
+    }
+    if ('search' in entry) {
+        var unknown1 = Object.keys(entry).filter(function(k) {
+            return !SAVED_SEARCH_KEYS.has(k);
+        });
+        if (unknown1.length > 0) {
+            throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, " has unknown key(s) ").concat(unknown1.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 _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, ".search must be non-empty text"));
+        }
+        if (entry.preset !== undefined && (typeof entry.preset !== 'string' || entry.preset.length === 0)) {
+            throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, ".preset must be a preset name"));
+        }
+        if (entry.include !== undefined && !isNonEmptyStringArray(entry.include)) {
+            throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, ".include must be a non-empty array of glob strings"));
+        }
+        if (entry.where !== undefined && typeof entry.where !== 'string') {
+            throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(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 _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, ".k must be a positive integer"));
+        }
+        if (entry.semantic !== undefined && typeof entry.semantic !== 'boolean') {
+            throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(name, ".semantic must be a boolean"));
+        }
+        return;
+    }
+    throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries.").concat(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 === "undefined" ? "undefined" : _type_of(parsed)) !== 'object' || parsed === null || Array.isArray(parsed)) {
         throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": config must be a JSON object"));
     }
     var cfg = parsed;
-    var scan = cfg.scan;
-    if (!scan || !Array.isArray(scan.include) || scan.include.length === 0 || !scan.include.every(function(g) {
-        return typeof g === 'string';
-    })) {
-        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(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 _errorsts.SenseError('CONFIG_INVALID', "".concat(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 (_type_of(cfg.queries) !== 'object' || cfg.queries === null || Array.isArray(cfg.queries) || !Object.values(cfg.queries).every(function(q) {
-        return typeof q === 'string';
-    })) {
-        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries must be an object of name -> SQL string"));
-    }
-    var defaults = cfg.defaults;
-    if (defaults !== undefined && ((typeof defaults === "undefined" ? "undefined" : _type_of(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 _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": defaults.find.where must be a SQL condition string"));
-    }
-    var checks = cfg.checks;
-    if (checks !== undefined) {
-        var _cfg_queries;
-        if ((typeof checks === "undefined" ? "undefined" : _type_of(checks)) !== 'object' || checks === null || Array.isArray(checks) || !Object.values(checks).every(function(v) {
-            return v === 'empty';
-        })) {
-            throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ': checks must be an object of query name -> "empty"'));
+    var presets = cfg.presets;
+    if (!presets || (typeof presets === "undefined" ? "undefined" : _type_of(presets)) !== 'object' || Array.isArray(presets) || Object.keys(presets).length === 0) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": presets must be a non-empty object of preset name -> { include, exclude?, k?, semantic?, where? }"));
+    }
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = Object.entries(presets)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array(_step.value, 2), name = _step_value[0], value = _step_value[1];
+            validatePreset(name, value, configPath);
         }
-        var queries = (_cfg_queries = cfg.queries) !== null && _cfg_queries !== void 0 ? _cfg_queries : {};
-        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
         try {
-            for(var _iterator = Object.keys(checks)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-                var name = _step.value;
-                if (queries[name] === undefined) throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ': checks names "').concat(name, '", which is not a saved query'));
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
             }
-        } catch (err) {
-            _didIteratorError = true;
-            _iteratorError = err;
         } finally{
-            try {
-                if (!_iteratorNormalCompletion && _iterator.return != null) {
-                    _iterator.return();
-                }
-            } finally{
-                if (_didIteratorError) {
-                    throw _iteratorError;
-                }
+            if (_didIteratorError) {
+                throw _iteratorError;
             }
         }
     }
-    if (cfg.features !== undefined && (_type_of(cfg.features) !== 'object' || cfg.features === null || Array.isArray(cfg.features))) {
-        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": features must be an object of name -> boolean"));
+    if (presets.default === undefined) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ': presets must include a "default" preset'));
+    }
+    if (cfg.queries === undefined) cfg.queries = {};
+    if (_type_of(cfg.queries) !== 'object' || cfg.queries === null || Array.isArray(cfg.queries)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": queries must be an object of name -> SQL string, { sql }, or saved search"));
     }
+    var queries = cfg.queries;
     var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
     try {
-        var _loop = function() {
-            var _step_value = _sliced_to_array(_step1.value, 2), name = _step_value[0], value = _step_value[1];
-            if (typeof value === 'boolean') return "continue";
-            // embed alone takes an object form: { model?, type?: static|api, url?, key? }.
-            var embed = value;
-            var shapeOk = name === 'embed' && (typeof value === "undefined" ? "undefined" : _type_of(value)) === 'object' && value !== null && !Array.isArray(value) && [
-                'model',
-                'url',
-                'key'
-            ].every(function(f) {
-                return embed[f] === undefined || typeof embed[f] === 'string';
-            }) && (embed.type === undefined || embed.type === 'static' || embed.type === 'api');
-            if (!shapeOk) {
-                throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(configPath, ": features.").concat(name, " must be a boolean").concat(name === 'embed' ? ' or { model?, type?: "static"|"api", url?, key? }' : ''));
-            }
-        };
-        for(var _iterator1 = Object.entries((_cfg_features = cfg.features) !== null && _cfg_features !== void 0 ? _cfg_features : {})[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true)_loop();
+        for(var _iterator1 = Object.entries(queries)[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+            var _step_value1 = _sliced_to_array(_step1.value, 2), name1 = _step_value1[0], value1 = _step_value1[1];
+            validateSavedQuery(name1, value1, configPath);
+        }
     } catch (err) {
         _didIteratorError1 = true;
         _iteratorError1 = err;
@@ -425,6 +744,12 @@ function validateConfig(parsed, configPath) {
             }
         }
     }
+    if (cfg.features !== undefined) {
+        validateFeaturesBlock(cfg.features, configPath);
+    }
+    if (cfg.embed !== undefined) {
+        validateEmbedBlock(cfg.embed, configPath);
+    }
     return cfg;
 }
 function loadConfig(explicitPath) {
@@ -441,19 +766,33 @@ function loadConfig(explicitPath) {
     }
     var raw = (0, _nodefs.readFileSync)(configPath, 'utf8');
     var 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 === "undefined" ? "undefined" : _type_of(parsed)) !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new _errorsts.SenseError('CONFIG_INVALID', "".concat(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.
     var version = (typeof parsed === "undefined" ? "undefined" : _type_of(parsed)) === 'object' && parsed !== null && typeof parsed.version === 'number' ? parsed.version : 1;
     if (version > SUPPORTED_CONFIG_VERSION) {
         throw new _errorsts.SenseError('CONFIG_VERSION_UNSUPPORTED', "config version ".concat(version, " requires a newer sense"));
     }
-    var 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.
+    var cfg;
     var migratedFrom;
     if (version < SUPPORTED_CONFIG_VERSION) {
-        var result = migrateConfig(cfg);
-        cfg = result.cfg;
+        validateLegacyScan(parsed, configPath);
+        var result = migrateConfig(parsed);
+        cfg = validateConfig(result.cfg, configPath);
         migratedFrom = result.from;
         (0, _nodefs.writeFileSync)(configPath, "".concat(JSON.stringify(cfg, null, 2), "\n"));
+    } else {
+        cfg = validateConfig(parsed, configPath);
     }
     var unknownKeys = unknownConfigKeys(cfg);
     return _object_spread_props(_object_spread({}, cfg), {