sensemaking 0.27.1 → 0.28.1

package/dist/cjs/store/engine.js

@@ -0,0 +1,362 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ENGINE_CHECK_DOCS () {
+        return ENGINE_CHECK_DOCS;
+    },
+    get ENGINE_CHECK_QUERIES () {
+        return ENGINE_CHECK_QUERIES;
+    },
+    get ENGINE_IDENTITY_META_KEY () {
+        return ENGINE_IDENTITY_META_KEY;
+    },
+    get checkEngine () {
+        return checkEngine;
+    },
+    get engineCheckFailed () {
+        return engineCheckFailed;
+    },
+    get engineIdentity () {
+        return engineIdentity;
+    },
+    get npmRemedy () {
+        return npmRemedy;
+    },
+    get selectBuilders () {
+        return selectBuilders;
+    }
+});
+var _semver = /*#__PURE__*/ _interop_require_default(require("semver"));
+var _errorsts = require("../errors.js");
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) resolve(value);
+    else Promise.resolve(value).then(_next, _throw);
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else obj[key] = value;
+    return obj;
+}
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+var ENGINE_IDENTITY_META_KEY = 'engine_identity';
+function engineIdentity(pkg, version) {
+    return "".concat(pkg, "@").concat(version !== null && version !== void 0 ? version : 'unknown');
+}
+function selectBuilders(defaults, patches, version) {
+    var selected = defaults;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = patches[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var patch = _step.value;
+            if (version !== undefined && _semver.default.satisfies(version, patch.range, {
+                includePrerelease: true
+            })) selected = _object_spread({}, selected, patch.builders);
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return selected;
+}
+var ENGINE_CHECK_DOCS = [
+    {
+        path: 'b-text.md',
+        title: 'Garden',
+        summary: '',
+        text: 'The dog runs past two cats.'
+    },
+    {
+        path: 'c-cjk.md',
+        title: 'Kitchen',
+        summary: '',
+        text: '日本語のメモ'
+    },
+    {
+        path: 'z-title.md',
+        title: 'Running dogs',
+        summary: '',
+        text: 'A note about pets.'
+    }
+];
+var ENGINE_CHECK_QUERIES = [
+    {
+        terms: 'run',
+        paths: [
+            'z-title.md',
+            'b-text.md'
+        ]
+    },
+    {
+        terms: 'dog cat',
+        paths: [
+            'b-text.md'
+        ]
+    },
+    {
+        terms: '日本',
+        paths: [
+            'c-cjk.md'
+        ]
+    }
+];
+function npmRemedy(pkg, range) {
+    return "run `npm install ".concat(pkg, "@").concat(range, "` for a tested version (tested ").concat(range, ")");
+}
+function checkEngine(store, identity, remedy, query) {
+    return _async_to_generator(function() {
+        var _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, expected, paths, err1, err;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        9,
+                        10,
+                        11
+                    ]);
+                    _iterator = ENGINE_CHECK_QUERIES[Symbol.iterator]();
+                    _state.label = 2;
+                case 2:
+                    if (!!(_iteratorNormalCompletion = (_step = _iterator.next()).done)) return [
+                        3,
+                        8
+                    ];
+                    expected = _step.value;
+                    paths = void 0;
+                    _state.label = 3;
+                case 3:
+                    _state.trys.push([
+                        3,
+                        5,
+                        ,
+                        6
+                    ]);
+                    return [
+                        4,
+                        query(expected.terms)
+                    ];
+                case 4:
+                    paths = _state.sent();
+                    return [
+                        3,
+                        6
+                    ];
+                case 5:
+                    err1 = _state.sent();
+                    throw engineCheckFailed(store, identity, remedy, 'searching "'.concat(expected.terms, '" failed (').concat(err1.message, ")"));
+                case 6:
+                    if (paths.join('\n') !== expected.paths.join('\n')) {
+                        throw engineCheckFailed(store, identity, remedy, 'searching "'.concat(expected.terms, '" returned [').concat(paths.join(', '), "], expected [").concat(expected.paths.join(', '), "]"));
+                    }
+                    _state.label = 7;
+                case 7:
+                    _iteratorNormalCompletion = true;
+                    return [
+                        3,
+                        2
+                    ];
+                case 8:
+                    return [
+                        3,
+                        11
+                    ];
+                case 9:
+                    err = _state.sent();
+                    _didIteratorError = true;
+                    _iteratorError = err;
+                    return [
+                        3,
+                        11
+                    ];
+                case 10:
+                    try {
+                        if (!_iteratorNormalCompletion && _iterator.return != null) {
+                            _iterator.return();
+                        }
+                    } finally{
+                        if (_didIteratorError) {
+                            throw _iteratorError;
+                        }
+                    }
+                    return [
+                        7
+                    ];
+                case 11:
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+function engineCheckFailed(store, identity, remedy, failure) {
+    return new _errorsts.SenseError('STORE_CAPABILITY_MISSING', 'store "'.concat(store, '" cannot use ').concat(identity, ": ").concat(failure, "; ").concat(remedy));
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/store/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/open-source/ai/sensemaking/src/store/engine.ts"],"sourcesContent":["import semver from 'semver';\nimport { SenseError } from '../errors.ts';\n\n// Which native engine built a derived index. A different engine rebuilds the cache, as a schema change does:\n// native index formats and scoring belong to the engine, not to sensemaking's schema.\nexport const ENGINE_IDENTITY_META_KEY = 'engine_identity';\n\nexport function engineIdentity(pkg: string, version: string | undefined): string {\n  return `${pkg}@${version ?? 'unknown'}`;\n}\n\n/**\n * One version-specific replacement of a store's SQL builders. `range` matches the engine version (the npm package's,\n * or Node's bundled SQLite for sqlite), prereleases included since every `@duckdb/node-api` release is one;\n * `reason` names the observed difference.\n */\nexport interface EnginePatch<Builders> {\n  range: string;\n  reason: string;\n  builders: Partial<Builders>;\n}\n\n// Later patches win where ranges overlap, so a narrower fix is listed after the broader one it refines.\nexport function selectBuilders<Builders extends object>(defaults: Builders, patches: readonly EnginePatch<Builders>[], version: string | undefined): Builders {\n  let selected = defaults;\n  for (const patch of patches) {\n    if (version !== undefined && semver.satisfies(version, patch.range, { includePrerelease: true })) selected = { ...selected, ...patch.builders };\n  }\n  return selected;\n}\n\nexport interface EngineCheckDoc {\n  path: string;\n  title: string;\n  summary: string;\n  text: string;\n}\n\n// Expected results every store must reproduce. The title match sorts last by path, so an engine whose scores\n// collapse to zero (Turso's fts_score silent mode) or lose field weights reorders 'run' and fails the check.\nexport const ENGINE_CHECK_DOCS: readonly EngineCheckDoc[] = [\n  { path: 'b-text.md', title: 'Garden', summary: '', text: 'The dog runs past two cats.' },\n  { path: 'c-cjk.md', title: 'Kitchen', summary: '', text: '日本語のメモ' },\n  { path: 'z-title.md', title: 'Running dogs', summary: '', text: 'A note about pets.' },\n];\n\nexport const ENGINE_CHECK_QUERIES: ReadonlyArray<{ terms: string; paths: string[] }> = [\n  { terms: 'run', paths: ['z-title.md', 'b-text.md'] },\n  { terms: 'dog cat', paths: ['b-text.md'] },\n  { terms: '日本', paths: ['c-cjk.md'] },\n];\n\n// What to do when an npm-installed engine fails: get a version from the tested range.\nexport function npmRemedy(pkg: string, range: string): string {\n  return `run \\`npm install ${pkg}@${range}\\` for a tested version (tested ${range})`;\n}\n\n// Runs the store's real lexical query over ENGINE_CHECK_DOCS; any thrown error or wrong result fails the engine.\nexport async function checkEngine(store: string, identity: string, remedy: string, query: (terms: string) => Promise<string[]>): Promise<void> {\n  for (const expected of ENGINE_CHECK_QUERIES) {\n    let paths: string[];\n    try {\n      paths = await query(expected.terms);\n    } catch (err) {\n      throw engineCheckFailed(store, identity, remedy, `searching \"${expected.terms}\" failed (${(err as Error).message})`);\n    }\n    if (paths.join('\\n') !== expected.paths.join('\\n')) {\n      throw engineCheckFailed(store, identity, remedy, `searching \"${expected.terms}\" returned [${paths.join(', ')}], expected [${expected.paths.join(', ')}]`);\n    }\n  }\n}\n\nexport function engineCheckFailed(store: string, identity: string, remedy: string, failure: string): SenseError {\n  return new SenseError('STORE_CAPABILITY_MISSING', `store \"${store}\" cannot use ${identity}: ${failure}; ${remedy}`);\n}\n"],"names":["ENGINE_CHECK_DOCS","ENGINE_CHECK_QUERIES","ENGINE_IDENTITY_META_KEY","checkEngine","engineCheckFailed","engineIdentity","npmRemedy","selectBuilders","pkg","version","defaults","patches","selected","patch","undefined","semver","satisfies","range","includePrerelease","builders","path","title","summary","text","terms","paths","store","identity","remedy","query","expected","err","message","join","failure","SenseError"],"mappings":";;;;;;;;;;;QAwCaA;eAAAA;;QAMAC;eAAAA;;QAzCAC;eAAAA;;QAqDSC;eAAAA;;QAcNC;eAAAA;;QAjEAC;eAAAA;;QA8CAC;eAAAA;;QA9BAC;eAAAA;;;6DAvBG;wBACQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAIpB,IAAML,2BAA2B;AAEjC,SAASG,eAAeG,GAAW,EAAEC,OAA2B;IACrE,OAAO,AART,AAQU,UAAED,KAAI,KAAwB,OAArBC,oBAAAA,qBAAAA,UAAW;AAC9B;AAcO,SAASF,eAAwCG,QAAkB,EAAEC,OAAyC,EAAEF,OAA2B;IAChJ,IAAIG,WAAWF;QACV,kCAAA,2BAAA;;QAAL,QAAK,YAAeC,4BAAf,SAAA,6BAAA,QAAA,yBAAA,iCAAwB;YAAxB,IAAME,QAAN;YACH,IAAIJ,YAAYK,aAAaC,eAAM,CAACC,SAAS,CAACP,SAASI,MAAMI,KAAK,EAAE;gBAAEC,mBAAmB;YAAK,IAAIN,WAAW,mBAAKA,UAAaC,MAAMM,QAAQ;QAC/I;;QAFK;QAAA;;;iBAAA,6BAAA;gBAAA;;;gBAAA;sBAAA;;;;IAGL,OAAOP;AACT;AAWO,IAAMZ,oBAA+C;IAC1D;QAAEoB,MAAM;QAAaC,OAAO;QAAUC,SAAS;QAAIC,MAAM;IAA8B;IACvF;QAAEH,MAAM;QAAYC,OAAO;QAAWC,SAAS;QAAIC,MAAM;IAAS;IAClE;QAAEH,MAAM;QAAcC,OAAO;QAAgBC,SAAS;QAAIC,MAAM;IAAqB;CACtF;AAEM,IAAMtB,uBAA0E;IACrF;QAAEuB,OAAO;QAAOC,OAAO;YAAC;YAAc;SAAY;IAAC;IACnD;QAAED,OAAO;QAAWC,OAAO;YAAC;SAAY;IAAC;IACzC;QAAED,OAAO;QAAMC,OAAO;YAAC;SAAW;IAAC;CACpC;AAGM,SAASnB,UAAUE,GAAW,EAAES,KAAa;IAClD,OAAO,AAAC,oBAA2BA,OAAPT,KAAI,KAA2CS,OAAxCA,OAAM,mCAAwC,OAANA,OAAM;AACnF;AAGO,SAAed,YAAYuB,KAAa,EAAEC,QAAgB,EAAEC,MAAc,EAAEC,KAA2C;;YACvH,2BAAA,mBAAA,gBAAA,WAAA,OAAMC,UACLL,OAGKM;;;;oBAJN,kCAAA,2BAAA;;;;;;;;;oBAAA,YAAkB9B;;;2BAAlB,6BAAA,QAAA;;;;oBAAM6B,WAAN;oBACCL,QAAAA,KAAAA;;;;;;;;;oBAEM;;wBAAMI,MAAMC,SAASN,KAAK;;;oBAAlCC,QAAQ;;;;;;oBACDM;oBACP,MAAM3B,kBAAkBsB,OAAOC,UAAUC,QAAQ,AAAC,cAAwC,OAA3BE,SAASN,KAAK,EAAC,cAAmC,OAAvB,AAACO,KAAcC,OAAO,EAAC;;oBAEnH,IAAIP,MAAMQ,IAAI,CAAC,UAAUH,SAASL,KAAK,CAACQ,IAAI,CAAC,OAAO;wBAClD,MAAM7B,kBAAkBsB,OAAOC,UAAUC,QAAQ,AAAC,cAA0CH,OAA7BK,SAASN,KAAK,EAAC,gBAA8CM,OAAhCL,MAAMQ,IAAI,CAAC,OAAM,iBAAyC,OAA1BH,SAASL,KAAK,CAACQ,IAAI,CAAC,OAAM;oBACxJ;;;oBATG;;;;;;;;;;;;oBAAA;oBAAA;;;;;;;6BAAA,6BAAA;4BAAA;;;4BAAA;kCAAA;;;;;;;;;;;;IAWP;;AAEO,SAAS7B,kBAAkBsB,KAAa,EAAEC,QAAgB,EAAEC,MAAc,EAAEM,OAAe;IAChG,OAAO,IAAIC,oBAAU,CAAC,4BAA4B,AAAC,UAA8BR,OAArBD,OAAM,iBAA4BQ,OAAbP,UAAS,MAAgBC,OAAZM,SAAQ,MAAW,OAAPN;AAC5G"}

package/dist/cjs/store/native.d.cts

@@ -2,10 +2,13 @@ export interface NativeDescriptor {
     store: string;
     pkg: string;
     sizeHint: string;
-    /** Optional exact package version required by this native binding. */
-    version?: string;
-    /** npm specifier used only when installation is required (imports stay bare). */
-    installSpec?: string;
+    /** The tested semver range: sensemaking's own `peerDependencies` entry for `pkg` (see `peerRange`). */
+    range: string;
+}
+export interface NativeModule<T> {
+    api: T;
+    version: string | undefined;
 }
 export declare function packageNodeModules(): string;
-export declare function loadOrInstall<T>(descriptor: NativeDescriptor, nodeModulesPath: string, importName?: string): Promise<T>;
+export declare function peerRange(pkg: string): string;
+export declare function loadOrInstall<T>(descriptor: NativeDescriptor, nodeModulesPath: string, importName?: string): Promise<NativeModule<T>>;

package/dist/cjs/store/native.d.ts

@@ -2,10 +2,13 @@ export interface NativeDescriptor {
     store: string;
     pkg: string;
     sizeHint: string;
-    /** Optional exact package version required by this native binding. */
-    version?: string;
-    /** npm specifier used only when installation is required (imports stay bare). */
-    installSpec?: string;
+    /** The tested semver range: sensemaking's own `peerDependencies` entry for `pkg` (see `peerRange`). */
+    range: string;
+}
+export interface NativeModule<T> {
+    api: T;
+    version: string | undefined;
 }
 export declare function packageNodeModules(): string;
-export declare function loadOrInstall<T>(descriptor: NativeDescriptor, nodeModulesPath: string, importName?: string): Promise<T>;
+export declare function peerRange(pkg: string): string;
+export declare function loadOrInstall<T>(descriptor: NativeDescriptor, nodeModulesPath: string, importName?: string): Promise<NativeModule<T>>;

package/dist/cjs/store/native.js

@@ -14,12 +14,16 @@ _export(exports, {
     },
     get packageNodeModules () {
         return packageNodeModules;
+    },
+    get peerRange () {
+        return peerRange;
     }
 });
 var _nodefs = require("node:fs");
 var _nodemodule = /*#__PURE__*/ _interop_require_default(require("node:module"));
 var _nodepath = require("node:path");
 var _nodeurl = require("node:url");
+var _semver = /*#__PURE__*/ _interop_require_default(require("semver"));
 var _errorsts = require("../errors.js");
 function _array_like_to_array(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
@@ -212,19 +216,33 @@ function _unsupported_iterable_to_array(o, minLen) {
 // ~110MB), so it is required lazily inside the gated branch below, not for every store/index.ts load.
 var _require = typeof require === 'undefined' ? _nodemodule.default.createRequire(require("url").pathToFileURL(__filename).toString()) : require;
 var _dirname = (0, _nodepath.dirname)(typeof __filename !== 'undefined' ? __filename : (0, _nodeurl.fileURLToPath)(require("url").pathToFileURL(__filename).toString()));
-function packageNodeModules() {
+// Walks up from this file's own directory rather than a fixed dot-count: it sits at a
+// different depth under src/ than under built dist/{cjs,esm}/store output.
+function packageRoot() {
     var dir = _dirname;
     for(;;){
         var candidate = (0, _nodepath.join)(dir, 'package.json');
         if ((0, _nodefs.existsSync)(candidate)) {
-            var pkg = JSON.parse((0, _nodefs.readFileSync)(candidate, 'utf8'));
-            if (pkg.name === 'sensemaking') return (0, _nodepath.join)(dir, 'node_modules');
+            var manifest = JSON.parse((0, _nodefs.readFileSync)(candidate, 'utf8'));
+            if (manifest.name === 'sensemaking') return {
+                dir: dir,
+                manifest: manifest
+            };
         }
         var parent = (0, _nodepath.dirname)(dir);
         if (parent === dir) throw new Error('could not locate the sensemaking package root to install a native dependency into');
         dir = parent;
     }
 }
+function packageNodeModules() {
+    return (0, _nodepath.join)(packageRoot().dir, 'node_modules');
+}
+function peerRange(pkg) {
+    var _packageRoot_manifest_peerDependencies;
+    var range = (_packageRoot_manifest_peerDependencies = packageRoot().manifest.peerDependencies) === null || _packageRoot_manifest_peerDependencies === void 0 ? void 0 : _packageRoot_manifest_peerDependencies[pkg];
+    if (!range) throw new Error("sensemaking's package.json declares no peerDependencies entry for ".concat(pkg));
+    return range;
+}
 var installing = new Map();
 // De-dupes concurrent installs: since the install is async, concurrent callers await the same
 // in-flight promise, keyed by specifier and target. A failed install is not cached, so a later call retries.
@@ -241,6 +259,13 @@ function installOnce(specifier, nodeModulesPath) {
     }
     return promise;
 }
+function readPackageMetadata(pkgDir) {
+    try {
+        return JSON.parse((0, _nodefs.readFileSync)((0, _nodepath.join)(pkgDir, 'package.json'), 'utf8'));
+    } catch (unused) {
+        return undefined;
+    }
+}
 // Node caches a bare specifier's resolution, including a "not found" miss, for the process
 // lifetime; use the installed entry directly, as a URL for ESM and a path for CJS.
 function resolveEntrySpecifier(importName, nodeModulesPath) {
@@ -253,32 +278,12 @@ function resolveEntrySpecifier(importName, nodeModulesPath) {
     var entryPath = (0, _nodepath.join)(pkgDir, entry);
     return typeof require === 'undefined' ? (0, _nodeurl.pathToFileURL)(entryPath).href : entryPath;
 }
-function readPackageMetadata(pkgDir) {
-    try {
-        return JSON.parse((0, _nodefs.readFileSync)((0, _nodepath.join)(pkgDir, 'package.json'), 'utf8'));
-    } catch (unused) {
-        return undefined;
-    }
-}
-function targetPackageMetadata(importName, nodeModulesPath) {
-    var pkgDir = _nodepath.join.apply(void 0, [
-        nodeModulesPath
-    ].concat(_to_consumable_array(importName.split('/'))));
-    return {
-        exists: (0, _nodefs.existsSync)(pkgDir),
-        metadata: readPackageMetadata(pkgDir)
-    };
-}
-function resolvedPackageMetadata(importName) {
+function resolvedVersion(importName) {
     try {
         var dir = (0, _nodepath.dirname)(_require.resolve(importName));
         for(;;){
-            var manifest = (0, _nodepath.join)(dir, 'package.json');
-            if ((0, _nodefs.existsSync)(manifest)) {
-                var pkg = readPackageMetadata(dir);
-                if (!pkg) return undefined;
-                if (pkg.name === importName) return pkg;
-            }
+            var pkg = readPackageMetadata(dir);
+            if ((pkg === null || pkg === void 0 ? void 0 : pkg.name) === importName) return pkg.version;
             var parent = (0, _nodepath.dirname)(dir);
             if (parent === dir) return undefined;
             dir = parent;
@@ -287,35 +292,26 @@ function resolvedPackageMetadata(importName) {
         return undefined;
     }
 }
-function versionContractError(descriptor, installed) {
-    var _descriptor_installSpec;
-    var installSpec = (_descriptor_installSpec = descriptor.installSpec) !== null && _descriptor_installSpec !== void 0 ? _descriptor_installSpec : descriptor.pkg;
-    var detail = installed ? "".concat(descriptor.pkg, "@").concat(installed, " is installed") : "".concat(descriptor.pkg, " has missing or unreadable version metadata");
-    return new _errorsts.SenseError('STORE_DEPENDENCY_MISSING', 'store "'.concat(descriptor.store, '" needs ').concat(installSpec, ", but ").concat(detail, "; refusing to overwrite it -- run `npm install ").concat(installSpec, "` yourself and try again"));
-}
-function assertExpectedVersion(descriptor, metadata) {
-    if (!descriptor.version) return;
-    if (!(metadata === null || metadata === void 0 ? void 0 : metadata.version) || metadata.version !== descriptor.version) throw versionContractError(descriptor, metadata === null || metadata === void 0 ? void 0 : metadata.version);
+// Any installed version is used; one outside the tested range is reported, not refused (the store's engine check decides).
+function reportVersion(descriptor, version) {
+    if (version && _semver.default.satisfies(version, descriptor.range)) return;
+    console.error('sense: store "'.concat(descriptor.store, '" using ').concat(descriptor.pkg, "@").concat(version !== null && version !== void 0 ? version : 'unknown version', " (tested ").concat(descriptor.range, ")"));
 }
 function loadOrInstall(_0, _1) {
     return _async_to_generator(function(descriptor, nodeModulesPath) {
-        var importName, target, loaded, unused, _descriptor_installSpec, _descriptor_installSpec1, installSpec, displaySpec, installErr, loaded1, loadErr;
+        var importName, api, version, unused, spec, installSpec, installErr, _readPackageMetadata, api1, version1, loadErr;
         var _arguments = arguments;
         return _ts_generator(this, function(_state) {
             switch(_state.label){
                 case 0:
                     importName = _arguments.length > 2 && _arguments[2] !== void 0 ? _arguments[2] : descriptor.pkg;
-                    if (descriptor.version) {
-                        target = targetPackageMetadata(importName, nodeModulesPath);
-                        if (target.exists) assertExpectedVersion(descriptor, target.metadata);
-                    }
                     _state.label = 1;
                 case 1:
                     _state.trys.push([
                         1,
                         3,
                         ,
-                        11
+                        4
                     ]);
                     return [
                         4,
@@ -324,43 +320,53 @@ function loadOrInstall(_0, _1) {
                         })
                     ];
                 case 2:
-                    loaded = _state.sent();
+                    api = _state.sent();
+                    version = resolvedVersion(importName);
+                    reportVersion(descriptor, version);
                     return [
-                        3,
-                        11
+                        2,
+                        {
+                            api: api,
+                            version: version
+                        }
                     ];
                 case 3:
                     unused = _state.sent();
-                    installSpec = (_descriptor_installSpec = descriptor.installSpec) !== null && _descriptor_installSpec !== void 0 ? _descriptor_installSpec : importName;
-                    displaySpec = (_descriptor_installSpec1 = descriptor.installSpec) !== null && _descriptor_installSpec1 !== void 0 ? _descriptor_installSpec1 : descriptor.pkg;
-                    console.error('sense: store "'.concat(descriptor.store, '" needs ').concat(displaySpec, "; installing it now (one-time download, ").concat(descriptor.sizeHint, ")..."));
-                    _state.label = 4;
+                    return [
+                        3,
+                        4
+                    ];
                 case 4:
+                    spec = "".concat(descriptor.pkg, "@").concat(descriptor.range);
+                    installSpec = "".concat(importName, "@").concat(descriptor.range);
+                    console.error('sense: store "'.concat(descriptor.store, '" needs ').concat(spec, "; installing it now (one-time download, ").concat(descriptor.sizeHint, ")..."));
+                    _state.label = 5;
+                case 5:
                     _state.trys.push([
-                        4,
-                        6,
+                        5,
+                        7,
                         ,
-                        7
+                        8
                     ]);
                     return [
                         4,
                         installOnce(installSpec, nodeModulesPath)
                     ];
-                case 5:
+                case 6:
                     _state.sent();
                     return [
                         3,
-                        7
+                        8
                     ];
-                case 6:
-                    installErr = _state.sent();
-                    throw new _errorsts.SenseError('STORE_DEPENDENCY_MISSING', 'store "'.concat(descriptor.store, '" needs ').concat(displaySpec, ", and installing it automatically failed (").concat(installErr.message, "); this can happen offline, in a sandboxed environment, or when node_modules is read-only or owned by another user (e.g. under a global install) -- run `npm install ").concat(displaySpec, "` yourself and try again"));
                 case 7:
+                    installErr = _state.sent();
+                    throw new _errorsts.SenseError('STORE_DEPENDENCY_MISSING', 'store "'.concat(descriptor.store, '" needs ').concat(spec, ", and installing it automatically failed (").concat(installErr.message, "); this can happen offline, in a sandboxed environment, or when node_modules is read-only or owned by another user (e.g. under a global install) -- run `npm install ").concat(spec, "` yourself and try again"));
+                case 8:
                     _state.trys.push([
-                        7,
-                        9,
+                        8,
+                        10,
                         ,
-                        10
+                        11
                     ]);
                     return [
                         4,
@@ -368,26 +374,25 @@ function loadOrInstall(_0, _1) {
                             return /*#__PURE__*/ _interop_require_wildcard(require(p));
                         })
                     ];
-                case 8:
-                    loaded1 = _state.sent();
-                    assertExpectedVersion(descriptor, targetPackageMetadata(importName, nodeModulesPath).metadata);
+                case 9:
+                    api1 = _state.sent();
+                    version1 = (_readPackageMetadata = readPackageMetadata(_nodepath.join.apply(void 0, [
+                        nodeModulesPath
+                    ].concat(_to_consumable_array(importName.split('/')))))) === null || _readPackageMetadata === void 0 ? void 0 : _readPackageMetadata.version;
+                    reportVersion(descriptor, version1);
                     return [
                         2,
-                        loaded1
+                        {
+                            api: api1,
+                            version: version1
+                        }
                     ];
-                case 9:
-                    loadErr = _state.sent();
-                    throw new _errorsts.SenseError('STORE_DEPENDENCY_MISSING', 'store "'.concat(descriptor.store, '" installed ').concat(displaySpec, " but it could not be loaded (").concat(loadErr.message, "); it may not be available for this platform (").concat(process.platform, "-").concat(process.arch, ") -- run `npm install ").concat(displaySpec, "` to see the underlying error"));
                 case 10:
-                    return [
-                        3,
-                        11
-                    ];
+                    loadErr = _state.sent();
+                    throw new _errorsts.SenseError('STORE_DEPENDENCY_MISSING', 'store "'.concat(descriptor.store, '" installed ').concat(spec, " but it could not be loaded (").concat(loadErr.message, "); it may not be available for this platform (").concat(process.platform, "-").concat(process.arch, ") -- run `npm install ").concat(spec, "` to see the underlying error"));
                 case 11:
-                    if (descriptor.version) assertExpectedVersion(descriptor, resolvedPackageMetadata(importName));
                     return [
-                        2,
-                        loaded
+                        2
                     ];
             }
         });