sensemaking 0.25.1 → 0.27.0

package/dist/cjs/commands/map.d.cts

@@ -1,21 +1,30 @@
 import type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/index.js';
-import type { Row } from '../output/output.js';
-import type { Store } from '../store/types.js';
+import type { FieldStat, Store } from '../store/types.js';
 import type { PresetCoverage } from './status.js';
 export interface TreeMap {
     docs: {
         count: number;
         bytes: number;
     };
-    fields: Row[];
+    fields: TreeMapField[];
     fieldsTotal: number;
     features: {
         on: FeatureName[];
         off: FeatureName[];
     };
     presets: PresetCoverage[];
-    hubs: Row[];
-    recent: Row[];
+    hubs: TreeMapHub[];
+    recent: TreeMapRecent[];
     recentCaveat: string | null;
 }
+export type TreeMapField = FieldStat;
+export type TreeMapHub = {
+    path: string;
+    rank: number;
+    title: string;
+};
+export type TreeMapRecent = {
+    path: string;
+    modified: string;
+};
 export declare function mapTree(store: Store, cfg: ResolvedConfig, overrides?: SearchOverrides): Promise<TreeMap>;

package/dist/cjs/commands/map.d.ts

@@ -1,21 +1,30 @@
 import type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/index.js';
-import type { Row } from '../output/output.js';
-import type { Store } from '../store/types.js';
+import type { FieldStat, Store } from '../store/types.js';
 import type { PresetCoverage } from './status.js';
 export interface TreeMap {
     docs: {
         count: number;
         bytes: number;
     };
-    fields: Row[];
+    fields: TreeMapField[];
     fieldsTotal: number;
     features: {
         on: FeatureName[];
         off: FeatureName[];
     };
     presets: PresetCoverage[];
-    hubs: Row[];
-    recent: Row[];
+    hubs: TreeMapHub[];
+    recent: TreeMapRecent[];
     recentCaveat: string | null;
 }
+export type TreeMapField = FieldStat;
+export type TreeMapHub = {
+    path: string;
+    rank: number;
+    title: string;
+};
+export type TreeMapRecent = {
+    path: string;
+    modified: string;
+};
 export declare function mapTree(store: Store, cfg: ResolvedConfig, overrides?: SearchOverrides): Promise<TreeMap>;

package/dist/cjs/commands/map.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "mapTree", {
 var _indexts = require("../config/index.js");
 var _serialqueryts = require("../lib/serial-query.js");
 var _scopets = require("./scope.js");
+var _snapshotts = require("./snapshot.js");
 var _statusts = require("./status.js");
 function _array_like_to_array(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
@@ -194,6 +195,12 @@ function mapIndexed(store, cfg, overrides) {
                         return _ts_generator(this, function(_state) {
                             switch(_state.label){
                                 case 0:
+                                    return [
+                                        4,
+                                        (0, _snapshotts.assertQuerySnapshot)(store, cfg)
+                                    ];
+                                case 1:
+                                    _state.sent();
                                     _tmp = [
                                         store
                                     ];
@@ -201,14 +208,14 @@ function mapIndexed(store, cfg, overrides) {
                                         4,
                                         (0, _scopets.scopedPaths)(store, cfg, overrides)
                                     ];
-                                case 1:
+                                case 2:
                                     return [
                                         4,
                                         _scopets.setupMapScope.apply(void 0, _tmp.concat([
                                             _state.sent()
                                         ]))
                                     ];
-                                case 2:
+                                case 3:
                                     _state.sent();
                                     scopeWhere = 'WHERE "path" IN (SELECT "path" FROM _map_scope)';
                                     scopeAnd = 'AND f."path" IN (SELECT "path" FROM _map_scope)';
@@ -216,18 +223,18 @@ function mapIndexed(store, cfg, overrides) {
                                         4,
                                         store.prepare('SELECT COUNT(*) AS count, COALESCE(SUM("_size"), 0) AS bytes FROM frontmatter '.concat(scopeWhere))
                                     ];
-                                case 3:
+                                case 4:
                                     return [
                                         4,
                                         _state.sent().get()
                                     ];
-                                case 4:
+                                case 5:
                                     docs = _state.sent();
                                     return [
                                         4,
                                         store.docs.columns()
                                     ];
-                                case 5:
+                                case 6:
                                     columns = _state.sent().filter(function(name) {
                                         return !_scopets.INTERNAL_COLUMNS.has(name);
                                     });
@@ -235,20 +242,20 @@ function mapIndexed(store, cfg, overrides) {
                                     // every distinct type observed across the scope is reported, not just the first.
                                     allFields = [];
                                     _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
-                                    _state.label = 6;
-                                case 6:
+                                    _state.label = 7;
+                                case 7:
                                     _state.trys.push([
-                                        6,
-                                        11,
+                                        7,
                                         12,
-                                        13
+                                        13,
+                                        14
                                     ]);
                                     _iterator = chunk(columns, MAP_COLUMN_CHUNK)[Symbol.iterator]();
-                                    _state.label = 7;
-                                case 7:
+                                    _state.label = 8;
+                                case 8:
                                     if (!!(_iteratorNormalCompletion = (_step = _iterator.next()).done)) return [
                                         3,
-                                        10
+                                        11
                                     ];
                                     group = _step.value;
                                     _1 = (_ = (_allFields = allFields).push).apply;
@@ -259,33 +266,33 @@ function mapIndexed(store, cfg, overrides) {
                                         4,
                                         store.docs.fieldStats(group, scopeWhere)
                                     ];
-                                case 8:
+                                case 9:
                                     _1.apply(_, _tmp1.concat([
                                         _to_consumable_array.apply(void 0, [
                                             _state.sent()
                                         ])
                                     ]));
-                                    _state.label = 9;
-                                case 9:
+                                    _state.label = 10;
+                                case 10:
                                     _iteratorNormalCompletion = true;
                                     return [
                                         3,
-                                        7
+                                        8
                                     ];
-                                case 10:
+                                case 11:
                                     return [
                                         3,
-                                        13
+                                        14
                                     ];
-                                case 11:
+                                case 12:
                                     err = _state.sent();
                                     _didIteratorError = true;
                                     _iteratorError = err;
                                     return [
                                         3,
-                                        13
+                                        14
                                     ];
-                                case 12:
+                                case 13:
                                     try {
                                         if (!_iteratorNormalCompletion && _iterator.return != null) {
                                             _iterator.return();
@@ -298,45 +305,45 @@ function mapIndexed(store, cfg, overrides) {
                                     return [
                                         7
                                     ];
-                                case 13:
+                                case 14:
                                     allFields.sort(function(a, b) {
                                         return b.coverage - a.coverage;
                                     });
                                     fields = allFields.slice(0, 20);
                                     if (!(0, _indexts.featureEnabled)(cfg, 'rank')) return [
                                         3,
-                                        16
+                                        17
                                     ];
                                     return [
                                         4,
                                         store.prepare('SELECT f."path" AS path, round(f."_rank" * 100, 2) AS rank, content.title FROM frontmatter f JOIN content ON content.path = f."path" WHERE f."_rank" IS NOT NULL '.concat(scopeAnd, ' ORDER BY f."_rank" DESC, f."path" ASC LIMIT 8'))
                                     ];
-                                case 14:
+                                case 15:
                                     return [
                                         4,
                                         _state.sent().all()
                                     ];
-                                case 15:
+                                case 16:
                                     _tmp2 = _state.sent();
                                     return [
                                         3,
-                                        17
+                                        18
                                     ];
-                                case 16:
-                                    _tmp2 = [];
-                                    _state.label = 17;
                                 case 17:
+                                    _tmp2 = [];
+                                    _state.label = 18;
+                                case 18:
                                     hubs = _tmp2;
                                     return [
                                         4,
                                         store.prepare('SELECT "path", "_mtime" AS mtime FROM frontmatter '.concat(scopeWhere, ' ORDER BY "_mtime" DESC, "path" ASC LIMIT 5'))
                                     ];
-                                case 18:
+                                case 19:
                                     return [
                                         4,
                                         _state.sent().all()
                                     ];
-                                case 19:
+                                case 20:
                                     recent = _state.sent().map(function(r) {
                                         return {
                                             path: r.path,
@@ -347,12 +354,12 @@ function mapIndexed(store, cfg, overrides) {
                                         4,
                                         store.prepare("SELECT COUNT(*) AS n FROM frontmatter ".concat(scopeWhere, ' GROUP BY CAST("_mtime" / 1000 AS INTEGER) ORDER BY n DESC LIMIT 1'))
                                     ];
-                                case 20:
+                                case 21:
                                     return [
                                         4,
                                         _state.sent().get()
                                     ];
-                                case 21:
+                                case 22:
                                     topSecond = _state.sent();
                                     recentCaveat = topSecond && docs.count > 1 && topSecond.n > docs.count / 2 ? "".concat(topSecond.n, " of ").concat(docs.count, " files share one modified second, so recency likely reflects a checkout or copy, not edit history") : null;
                                     _tmp3 = {
@@ -365,7 +372,7 @@ function mapIndexed(store, cfg, overrides) {
                                         4,
                                         (0, _statusts.presetCoverage)(store, cfg)
                                     ];
-                                case 22:
+                                case 23:
                                     return [
                                         2,
                                         (_tmp3.presets = _state.sent(), _tmp3.hubs = hubs, _tmp3.recent = recent, _tmp3.recentCaveat = recentCaveat, _tmp3)

package/dist/cjs/commands/map.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/map.ts"],"sourcesContent":["import type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/index.ts';\nimport { featureEnabled, featureStates } from '../config/index.ts';\nimport { serialQuery } from '../lib/serial-query.ts';\nimport type { Row } from '../output/output.ts';\nimport type { FieldStat, Store } from '../store/types.ts';\nimport { INTERNAL_COLUMNS, scopedPaths, setupMapScope } from './scope.ts';\nimport type { PresetCoverage } from './status.ts';\nimport { presetCoverage } from './status.ts';\n\nexport interface TreeMap {\n  docs: { count: number; bytes: number };\n  fields: Row[]; // top 20 by coverage; fieldsTotal carries the real count\n  fieldsTotal: number;\n  features: { on: FeatureName[]; off: FeatureName[] };\n  presets: PresetCoverage[];\n  hubs: Row[];\n  recent: Row[];\n  recentCaveat: string | null;\n}\n\n// A result row is capped at SQLITE_MAX_COLUMN (2000, default); two aggregate expressions per\n// field keeps a chunk's row width safely under that regardless of how many fields the tree has.\nconst MAP_COLUMN_CHUNK = 300;\n\n// \"YYYY-MM-DD HH:MM:SS\" UTC, the exact shape sqlite's datetime(ms / 1000, 'unixepoch') prints;\n// formatted in JS so the query stays dialect-free.\nfunction utcSecond(ms: number): string {\n  return new Date(ms).toISOString().slice(0, 19).replace('T', ' ');\n}\n\nfunction chunk<T>(items: T[], size: number): T[][] {\n  const out: T[][] = [];\n  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));\n  return out;\n}\n\n// What is this scope: fixed-size output regardless of tree size. Coverage and features stay\n// global -- they describe the tree, not the current question.\nexport function mapTree(store: Store, cfg: ResolvedConfig, overrides: SearchOverrides = {}): Promise<TreeMap> {\n  return serialQuery(store, () => mapIndexed(store, cfg, overrides));\n}\n\nasync function mapIndexed(store: Store, cfg: ResolvedConfig, overrides: SearchOverrides): Promise<TreeMap> {\n  return store.transaction(async () => {\n    await setupMapScope(store, await scopedPaths(store, cfg, overrides));\n    const scopeWhere = 'WHERE \"path\" IN (SELECT \"path\" FROM _map_scope)';\n    const scopeAnd = 'AND f.\"path\" IN (SELECT \"path\" FROM _map_scope)';\n\n    const docs = (await (await store.prepare(`SELECT COUNT(*) AS count, COALESCE(SUM(\"_size\"), 0) AS bytes FROM frontmatter ${scopeWhere}`)).get()) as { count: number; bytes: number };\n\n    const columns = (await store.docs.columns()).filter((name) => !INTERNAL_COLUMNS.has(name));\n    // Observed types, not declared: a field can be text in most notes and numeric in a few, so\n    // every distinct type observed across the scope is reported, not just the first.\n    const allFields: FieldStat[] = [];\n    for (const group of chunk(columns, MAP_COLUMN_CHUNK)) allFields.push(...(await store.docs.fieldStats(group, scopeWhere)));\n    allFields.sort((a, b) => b.coverage - a.coverage);\n    const fields = allFields.slice(0, 20) as unknown as Row[];\n\n    const hubs = featureEnabled(cfg, 'rank')\n      ? ((await (await store.prepare(`SELECT f.\"path\" AS path, round(f.\"_rank\" * 100, 2) AS rank, content.title FROM frontmatter f JOIN content ON content.path = f.\"path\" WHERE f.\"_rank\" IS NOT NULL ${scopeAnd} ORDER BY f.\"_rank\" DESC, f.\"path\" ASC LIMIT 8`)).all()) as Row[])\n      : [];\n\n    const recent = ((await (await store.prepare(`SELECT \"path\", \"_mtime\" AS mtime FROM frontmatter ${scopeWhere} ORDER BY \"_mtime\" DESC, \"path\" ASC LIMIT 5`)).all()) as Array<{ path: string; mtime: number }>).map((r) => ({ path: r.path, modified: utcSecond(r.mtime) }));\n\n    // A fresh clone/copy stamps files with checkout time, not edit history; second granularity\n    // matches the `recent` table above and is coarse enough to catch that without an exact-ms match.\n    const topSecond = (await (await store.prepare(`SELECT COUNT(*) AS n FROM frontmatter ${scopeWhere} GROUP BY CAST(\"_mtime\" / 1000 AS INTEGER) ORDER BY n DESC LIMIT 1`)).get()) as { n: number } | undefined;\n    const recentCaveat = topSecond && docs.count > 1 && topSecond.n > docs.count / 2 ? `${topSecond.n} of ${docs.count} files share one modified second, so recency likely reflects a checkout or copy, not edit history` : null;\n\n    return { docs, fields, fieldsTotal: allFields.length, features: featureStates(cfg), presets: await presetCoverage(store, cfg), hubs, recent, recentCaveat };\n  });\n}\n"],"names":["mapTree","MAP_COLUMN_CHUNK","utcSecond","ms","Date","toISOString","slice","replace","chunk","items","size","out","i","length","push","store","cfg","overrides","serialQuery","mapIndexed","transaction","allFields","scopeWhere","scopeAnd","docs","columns","group","fields","hubs","recent","topSecond","recentCaveat","scopedPaths","setupMapScope","prepare","get","filter","name","INTERNAL_COLUMNS","has","fieldStats","sort","a","b","coverage","featureEnabled","all","map","r","path","modified","mtime","count","n","fieldsTotal","features","featureStates","presetCoverage","presets"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/map.ts"],"sourcesContent":["import type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/index.ts';\nimport { featureEnabled, featureStates } from '../config/index.ts';\nimport { serialQuery } from '../lib/serial-query.ts';\nimport type { FieldStat, Store } from '../store/types.ts';\nimport { INTERNAL_COLUMNS, scopedPaths, setupMapScope } from './scope.ts';\nimport { assertQuerySnapshot } from './snapshot.ts';\nimport type { PresetCoverage } from './status.ts';\nimport { presetCoverage } from './status.ts';\n\nexport interface TreeMap {\n  docs: { count: number; bytes: number };\n  fields: TreeMapField[]; // top 20 by coverage; fieldsTotal carries the real count\n  fieldsTotal: number;\n  features: { on: FeatureName[]; off: FeatureName[] };\n  presets: PresetCoverage[];\n  hubs: TreeMapHub[];\n  recent: TreeMapRecent[];\n  recentCaveat: string | null;\n}\n\nexport type TreeMapField = FieldStat;\n\nexport type TreeMapHub = {\n  path: string;\n  rank: number;\n  title: string;\n};\n\nexport type TreeMapRecent = {\n  path: string;\n  modified: string;\n};\n\n// A result row is capped at SQLITE_MAX_COLUMN (2000, default); two aggregate expressions per\n// field keeps a chunk's row width safely under that regardless of how many fields the tree has.\nconst MAP_COLUMN_CHUNK = 300;\n\n// \"YYYY-MM-DD HH:MM:SS\" UTC, the exact shape sqlite's datetime(ms / 1000, 'unixepoch') prints;\n// formatted in JS so the query stays dialect-free.\nfunction utcSecond(ms: number): string {\n  return new Date(ms).toISOString().slice(0, 19).replace('T', ' ');\n}\n\nfunction chunk<T>(items: T[], size: number): T[][] {\n  const out: T[][] = [];\n  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));\n  return out;\n}\n\n// What is this scope: fixed-size output regardless of tree size. Coverage and features stay\n// global -- they describe the tree, not the current question.\nexport function mapTree(store: Store, cfg: ResolvedConfig, overrides: SearchOverrides = {}): Promise<TreeMap> {\n  return serialQuery(store, () => mapIndexed(store, cfg, overrides));\n}\n\nasync function mapIndexed(store: Store, cfg: ResolvedConfig, overrides: SearchOverrides): Promise<TreeMap> {\n  return store.transaction(async () => {\n    await assertQuerySnapshot(store, cfg);\n    await setupMapScope(store, await scopedPaths(store, cfg, overrides));\n    const scopeWhere = 'WHERE \"path\" IN (SELECT \"path\" FROM _map_scope)';\n    const scopeAnd = 'AND f.\"path\" IN (SELECT \"path\" FROM _map_scope)';\n\n    const docs = (await (await store.prepare(`SELECT COUNT(*) AS count, COALESCE(SUM(\"_size\"), 0) AS bytes FROM frontmatter ${scopeWhere}`)).get()) as { count: number; bytes: number };\n\n    const columns = (await store.docs.columns()).filter((name) => !INTERNAL_COLUMNS.has(name));\n    // Observed types, not declared: a field can be text in most notes and numeric in a few, so\n    // every distinct type observed across the scope is reported, not just the first.\n    const allFields: FieldStat[] = [];\n    for (const group of chunk(columns, MAP_COLUMN_CHUNK)) allFields.push(...(await store.docs.fieldStats(group, scopeWhere)));\n    allFields.sort((a, b) => b.coverage - a.coverage);\n    const fields = allFields.slice(0, 20);\n\n    const hubs = featureEnabled(cfg, 'rank')\n      ? ((await (await store.prepare(`SELECT f.\"path\" AS path, round(f.\"_rank\" * 100, 2) AS rank, content.title FROM frontmatter f JOIN content ON content.path = f.\"path\" WHERE f.\"_rank\" IS NOT NULL ${scopeAnd} ORDER BY f.\"_rank\" DESC, f.\"path\" ASC LIMIT 8`)).all()) as TreeMapHub[])\n      : [];\n\n    const recent = ((await (await store.prepare(`SELECT \"path\", \"_mtime\" AS mtime FROM frontmatter ${scopeWhere} ORDER BY \"_mtime\" DESC, \"path\" ASC LIMIT 5`)).all()) as Array<{ path: string; mtime: number }>).map((r) => ({ path: r.path, modified: utcSecond(r.mtime) }));\n\n    // A fresh clone/copy stamps files with checkout time, not edit history; second granularity\n    // matches the `recent` table above and is coarse enough to catch that without an exact-ms match.\n    const topSecond = (await (await store.prepare(`SELECT COUNT(*) AS n FROM frontmatter ${scopeWhere} GROUP BY CAST(\"_mtime\" / 1000 AS INTEGER) ORDER BY n DESC LIMIT 1`)).get()) as { n: number } | undefined;\n    const recentCaveat = topSecond && docs.count > 1 && topSecond.n > docs.count / 2 ? `${topSecond.n} of ${docs.count} files share one modified second, so recency likely reflects a checkout or copy, not edit history` : null;\n\n    return { docs, fields, fieldsTotal: allFields.length, features: featureStates(cfg), presets: await presetCoverage(store, cfg), hubs, recent, recentCaveat };\n  });\n}\n"],"names":["mapTree","MAP_COLUMN_CHUNK","utcSecond","ms","Date","toISOString","slice","replace","chunk","items","size","out","i","length","push","store","cfg","overrides","serialQuery","mapIndexed","transaction","allFields","scopeWhere","scopeAnd","docs","columns","group","fields","hubs","recent","topSecond","recentCaveat","assertQuerySnapshot","scopedPaths","setupMapScope","prepare","get","filter","name","INTERNAL_COLUMNS","has","fieldStats","sort","a","b","coverage","featureEnabled","all","map","r","path","modified","mtime","count","n","fieldsTotal","features","featureStates","presetCoverage","presets"],"mappings":"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"}

package/dist/cjs/commands/path.d.cts

@@ -0,0 +1,14 @@
+import type { ResolvedConfig, SearchOverrides } from '../config/index.js';
+import type { Store } from '../store/types.js';
+/**
+ * Options for {@link findPath}. Scope fields constrain intermediate nodes; `maxDepth` limits the
+ * number of traversed links and must be a positive integer when supplied.
+ */
+export type PathOptions = Omit<SearchOverrides, 'k'> & {
+    maxDepth?: number;
+};
+/**
+ * Finds the shortest undirected link path between two indexed notes. Endpoints resolve across
+ * the indexed tree and remain permitted outside the scope applied to intermediate nodes.
+ */
+export declare function findPath(store: Store, cfg: ResolvedConfig, fromArg: string, toArg: string, options?: PathOptions): Promise<string[] | null>;

package/dist/cjs/commands/path.d.ts

@@ -0,0 +1,14 @@
+import type { ResolvedConfig, SearchOverrides } from '../config/index.js';
+import type { Store } from '../store/types.js';
+/**
+ * Options for {@link findPath}. Scope fields constrain intermediate nodes; `maxDepth` limits the
+ * number of traversed links and must be a positive integer when supplied.
+ */
+export type PathOptions = Omit<SearchOverrides, 'k'> & {
+    maxDepth?: number;
+};
+/**
+ * Finds the shortest undirected link path between two indexed notes. Endpoints resolve across
+ * the indexed tree and remain permitted outside the scope applied to intermediate nodes.
+ */
+export declare function findPath(store: Store, cfg: ResolvedConfig, fromArg: string, toArg: string, options?: PathOptions): Promise<string[] | null>;

package/dist/cjs/commands/path.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "findPath", {
+    enumerable: true,
+    get: function() {
+        return findPath;
+    }
+});
+var _indexts = require("../config/index.js");
+var _errorsts = require("../errors.js");
+var _traversets = require("../graph/traverse.js");
+var _serialqueryts = require("../lib/serial-query.js");
+var _peekts = require("./peek.js");
+var _scopets = require("./scope.js");
+var _snapshotts = require("./snapshot.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 _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
+        };
+    }
+}
+function findPath(store, cfg, fromArg, toArg) {
+    var options = arguments.length > 4 && arguments[4] !== void 0 ? arguments[4] : {};
+    return (0, _serialqueryts.serialQuery)(store, function() {
+        return findScopedPath(store, cfg, fromArg, toArg, options);
+    });
+}
+function findScopedPath(store, cfg, fromArg, toArg, options) {
+    return _async_to_generator(function() {
+        return _ts_generator(this, function(_state) {
+            if (options.maxDepth !== undefined && (!Number.isFinite(options.maxDepth) || !Number.isInteger(options.maxDepth) || options.maxDepth <= 0)) {
+                throw new _errorsts.SenseError('SEARCH_OPTION_INVALID', 'path option "maxDepth" must be a positive finite integer, got '.concat(String(options.maxDepth)));
+            }
+            // Validate the named preset before opening the snapshot; repeat it inside because preset_files
+            // and the compatibility assertion below belong to the final published generation.
+            (0, _indexts.resolveSearch)(cfg, options);
+            return [
+                2,
+                store.transaction(function() {
+                    return _async_to_generator(function() {
+                        var paths, from, to, allowed;
+                        return _ts_generator(this, function(_state) {
+                            switch(_state.label){
+                                case 0:
+                                    return [
+                                        4,
+                                        (0, _snapshotts.assertQuerySnapshot)(store, cfg)
+                                    ];
+                                case 1:
+                                    _state.sent();
+                                    (0, _indexts.resolveSearch)(cfg, options);
+                                    return [
+                                        4,
+                                        store.prepare('SELECT "path" FROM frontmatter')
+                                    ];
+                                case 2:
+                                    return [
+                                        4,
+                                        _state.sent().all()
+                                    ];
+                                case 3:
+                                    paths = _state.sent().map(function(row) {
+                                        return row.path;
+                                    });
+                                    from = (0, _peekts.resolveNote)(paths, fromArg);
+                                    to = (0, _peekts.resolveNote)(paths, toArg);
+                                    return [
+                                        4,
+                                        (0, _scopets.scopedPaths)(store, cfg, options)
+                                    ];
+                                case 4:
+                                    allowed = _state.sent();
+                                    return [
+                                        2,
+                                        (0, _traversets.findPathInSnapshot)(store, from, to, {
+                                            maxDepth: options.maxDepth,
+                                            allowed: allowed
+                                        })
+                                    ];
+                            }
+                        });
+                    })();
+                })
+            ];
+        });
+    })();
+}
+/* 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/commands/path.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/path.ts"],"sourcesContent":["import type { ResolvedConfig, SearchOverrides } from '../config/index.ts';\nimport { resolveSearch } from '../config/index.ts';\nimport { SenseError } from '../errors.ts';\nimport { findPathInSnapshot } from '../graph/traverse.ts';\nimport { serialQuery } from '../lib/serial-query.ts';\nimport type { Store } from '../store/types.ts';\nimport { resolveNote } from './peek.ts';\nimport { scopedPaths } from './scope.ts';\nimport { assertQuerySnapshot } from './snapshot.ts';\n\n/**\n * Options for {@link findPath}. Scope fields constrain intermediate nodes; `maxDepth` limits the\n * number of traversed links and must be a positive integer when supplied.\n */\nexport type PathOptions = Omit<SearchOverrides, 'k'> & {\n  maxDepth?: number;\n};\n\n/**\n * Finds the shortest undirected link path between two indexed notes. Endpoints resolve across\n * the indexed tree and remain permitted outside the scope applied to intermediate nodes.\n */\nexport function findPath(store: Store, cfg: ResolvedConfig, fromArg: string, toArg: string, options: PathOptions = {}): Promise<string[] | null> {\n  return serialQuery(store, () => findScopedPath(store, cfg, fromArg, toArg, options));\n}\n\nasync function findScopedPath(store: Store, cfg: ResolvedConfig, fromArg: string, toArg: string, options: PathOptions): Promise<string[] | null> {\n  if (options.maxDepth !== undefined && (!Number.isFinite(options.maxDepth) || !Number.isInteger(options.maxDepth) || options.maxDepth <= 0)) {\n    throw new SenseError('SEARCH_OPTION_INVALID', `path option \"maxDepth\" must be a positive finite integer, got ${String(options.maxDepth)}`);\n  }\n  // Validate the named preset before opening the snapshot; repeat it inside because preset_files\n  // and the compatibility assertion below belong to the final published generation.\n  resolveSearch(cfg, options);\n  return store.transaction(async () => {\n    await assertQuerySnapshot(store, cfg);\n    resolveSearch(cfg, options);\n    const paths = ((await (await store.prepare('SELECT \"path\" FROM frontmatter')).all()) as Array<{ path: string }>).map((row) => row.path);\n    const from = resolveNote(paths, fromArg);\n    const to = resolveNote(paths, toArg);\n    const allowed = await scopedPaths(store, cfg, options);\n    return findPathInSnapshot(store, from, to, { maxDepth: options.maxDepth, allowed });\n  });\n}\n"],"names":["findPath","store","cfg","fromArg","toArg","options","serialQuery","findScopedPath","maxDepth","undefined","Number","isFinite","isInteger","SenseError","String","resolveSearch","transaction","paths","from","to","allowed","assertQuerySnapshot","prepare","all","map","row","path","resolveNote","scopedPaths","findPathInSnapshot"],"mappings":";;;;+BAsBgBA;;;eAAAA;;;uBArBc;wBACH;0BACQ;6BACP;sBAEA;uBACA;0BACQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAc7B,SAASA,SAASC,KAAY,EAAEC,GAAmB,EAAEC,OAAe,EAAEC,KAAa;QAAEC,UAAAA,iEAAuB,CAAC;IAClH,OAAOC,IAAAA,0BAAW,EAACL,OAAO;eAAMM,eAAeN,OAAOC,KAAKC,SAASC,OAAOC;;AAC7E;AAEA,SAAeE,eAAeN,KAAY,EAAEC,GAAmB,EAAEC,OAAe,EAAEC,KAAa,EAAEC,OAAoB;;;YACnH,IAAIA,QAAQG,QAAQ,KAAKC,aAAc,CAAA,CAACC,OAAOC,QAAQ,CAACN,QAAQG,QAAQ,KAAK,CAACE,OAAOE,SAAS,CAACP,QAAQG,QAAQ,KAAKH,QAAQG,QAAQ,IAAI,CAAA,GAAI;gBAC1I,MAAM,IAAIK,oBAAU,CAAC,yBAAyB,AAAC,iEAAyF,OAAzBC,OAAOT,QAAQG,QAAQ;YACxI;YACA,+FAA+F;YAC/F,kFAAkF;YAClFO,IAAAA,sBAAa,EAACb,KAAKG;YACnB;;gBAAOJ,MAAMe,WAAW,CAAC;;4BAGjBC,OACAC,MACAC,IACAC;;;;oCALN;;wCAAMC,IAAAA,+BAAmB,EAACpB,OAAOC;;;oCAAjC;oCACAa,IAAAA,sBAAa,EAACb,KAAKG;oCACI;;wCAAMJ,MAAMqB,OAAO,CAAC;;;oCAA3B;;wCAAO,cAAuDC,GAAG;;;oCAA3EN,QAAQ,AAAE,cAAiGO,GAAG,CAAC,SAACC;+CAAQA,IAAIC,IAAI;;oCAChIR,OAAOS,IAAAA,mBAAW,EAACV,OAAOd;oCAC1BgB,KAAKQ,IAAAA,mBAAW,EAACV,OAAOb;oCACd;;wCAAMwB,IAAAA,oBAAW,EAAC3B,OAAOC,KAAKG;;;oCAAxCe,UAAU;oCAChB;;wCAAOS,IAAAA,8BAAkB,EAAC5B,OAAOiB,MAAMC,IAAI;4CAAEX,UAAUH,QAAQG,QAAQ;4CAAEY,SAAAA;wCAAQ;;;;oBACnF;;;;IACF"}

package/dist/cjs/commands/peek.d.cts

@@ -2,19 +2,42 @@ import type { FeatureName, ResolvedConfig, SearchOverrides } from '../config/ind
 import type { Row } from '../output/output.js';
 import type { Store } from '../store/types.js';
 export declare function resolveNote(paths: string[], arg: string): string;
+/** Structured, bounded metadata returned by the root {@link peek} API. */
 export interface Peek {
     path: string;
     tokens: number;
     frontmatter: Row;
+    /** Set when frontmatter parsing failed, distinguishing that case from an empty block. */
     parseError: string | null;
-    sections: Row[];
+    sections: PeekSection[];
     outbound: string[];
     backlinks: string[];
     unresolved: string[];
+    /** Totals before each bounded list is truncated. */
     sectionsTotal: number;
     outboundTotal: number;
     backlinksTotal: number;
     unresolvedTotal: number;
+    /** Disabled features whose result blocks are omitted rather than returned empty. */
     off: FeatureName[];
 }
-export declare function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides?: SearchOverrides): Promise<Peek>;
+/** A section description, with an inclusive source line range and token estimate, not section prose. */
+export interface PeekSection {
+    level: number;
+    heading: string;
+    start_line: number;
+    end_line: number;
+    tokens: number;
+}
+/** Options for the root {@link peek} API. */
+export interface PeekOptions extends SearchOverrides {
+    /** Maximum section descriptions. Defaults to 20; must be a positive safe integer. */
+    sectionCountLimit?: number;
+    /** Maximum entries in each link group independently. Defaults to 20; must be a positive safe integer. */
+    linkCountLimit?: number;
+}
+/**
+ * Returns indexed metadata for a note in scope. Exact excluded paths fail before scoped basename
+ * resolution; resolved neighbors stay in scope, while unresolved written targets remain visible.
+ */
+export declare function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides?: PeekOptions): Promise<Peek>;