@yurtsever/capsa 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/index.js

@@ -10227,6 +10227,10 @@ var Store = class {
       }
     }));
   }
+  /** All chunks of one item, in document order. */
+  chunksForItem(itemId) {
+    return this.db.prepare("SELECT id, item_id, idx, heading_path, text FROM chunks WHERE item_id = ? ORDER BY idx").all(itemId);
+  }
   listItems() {
     return this.db.prepare("SELECT * FROM items ORDER BY kind, rel_path").all();
   }
@@ -10566,6 +10570,40 @@ function rrf(lists, k = DEFAULT_WEIGHTS.rrfK) {
   return scores;
 }
 
+// ../index/dist/pin.js
+var LEADING_ID = /^([A-Za-z]{1,8}-?\d{1,5}(?:-\d{1,5})?|\d{2,6})(?=[-_.\s]|$)/;
+function leadingId(relPath) {
+  const base = relPath.split(/[\\/]/).pop() ?? "";
+  return LEADING_ID.exec(base)?.[1];
+}
+function pinnedItems(query, items) {
+  const q = query.toLowerCase();
+  const idCount = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const id = leadingId(item.rel_path)?.toLowerCase();
+    if (id)
+      idCount.set(id, (idCount.get(id) ?? 0) + 1);
+  }
+  const out = [];
+  for (const item of items) {
+    const rel = item.rel_path.toLowerCase();
+    if (q.includes(rel)) {
+      out.push(item);
+      continue;
+    }
+    const id = leadingId(item.rel_path);
+    if (!id || (idCount.get(id.toLowerCase()) ?? 0) > 1)
+      continue;
+    const re = new RegExp(`(^|[^\\w-])${escape2(id)}(?=$|[^\\w-])`, "i");
+    if (re.test(query))
+      out.push(item);
+  }
+  return out;
+}
+function escape2(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // ../index/dist/retrieve.js
 async function retrieve(store, embedder, query, options = {}) {
   const started = Date.now();
@@ -10573,31 +10611,73 @@ async function retrieve(store, embedder, query, options = {}) {
   const candidates = options.candidates ?? 30;
   const weights = options.weights ?? DEFAULT_WEIGHTS;
   const minRelative = options.minRelativeScore ?? 0.5;
+  const perItem = /* @__PURE__ */ new Map();
+  const chunks = [];
+  const debug = [];
+  let tokens = 0;
+  const pinned = pinnedItems(query, store.listItems());
+  for (const item of pinned) {
+    for (const c of store.chunksForItem(item.id)) {
+      const t = estimateTokens(c.text);
+      const fits = tokens + t <= maxTokens || chunks.length === 0;
+      if (options.debug) {
+        debug.push({
+          chunkId: c.id,
+          relPath: item.rel_path,
+          headingPath: JSON.parse(c.heading_path),
+          kind: item.kind,
+          status: item.status,
+          vecRank: null,
+          ftsRank: null,
+          fused: 0,
+          factor: 1,
+          score: Number.POSITIVE_INFINITY,
+          kept: fits,
+          why: fits ? "pinned" : "budget"
+        });
+      }
+      if (!fits)
+        continue;
+      perItem.set(item.id, (perItem.get(item.id) ?? 0) + 1);
+      tokens += t;
+      chunks.push({
+        chunkId: c.id,
+        score: Number.POSITIVE_INFINITY,
+        kind: item.kind,
+        status: item.status,
+        updatedAt: item.updated_at,
+        relPath: item.rel_path,
+        headingPath: JSON.parse(c.heading_path),
+        text: c.text,
+        tokens: t
+      });
+    }
+  }
+  const pinnedIds = new Set(pinned.map((i) => i.id));
+  const neighbourCutoff = pinned.length ? Math.max(minRelative, 0.75) : minRelative;
+  const neighbourBudget = pinned.length ? Math.min(maxTokens, tokens + Math.floor(maxTokens / 3)) : maxTokens;
   const [qv] = await embedder.embed([query]);
   const vec = qv ? store.vectorSearch(qv, candidates).map((r) => r.chunkId) : [];
   const fts = store.textSearch(query, candidates).map((r) => r.chunkId);
   const fused = rrf([vec, fts], weights.rrfK);
-  const rows = store.chunksWithItems([...fused.keys()]);
+  const rows = store.chunksWithItems([...fused.keys()]).filter((r) => !pinnedIds.has(r.item_id));
   const now = Date.now();
   const scored = rows.map((r) => {
     const fusedScore = fused.get(r.id) ?? 0;
     const factor = signalFactor({ kind: r.item.kind, status: r.item.status, updatedAt: r.item.updated_at }, weights, now);
     return { row: r, fusedScore, factor, score: fusedScore * factor };
   }).sort((a, b) => b.score - a.score);
-  const perItem = /* @__PURE__ */ new Map();
-  const chunks = [];
-  const debug = [];
-  let tokens = 0;
   const best = scored[0]?.score ?? 0;
-  let cut = false;
+  let cut = tokens >= maxTokens;
+  let kept = 0;
   for (const { row, fusedScore, factor, score } of scored) {
     let why = "kept";
-    if (cut || chunks.length > 0 && score < best * minRelative) {
+    if (cut || kept > 0 && score < best * neighbourCutoff) {
       cut = true;
       why = "cutoff";
     } else if ((perItem.get(row.item_id) ?? 0) >= 2) {
       why = "per-item cap";
-    } else if (tokens + estimateTokens(row.text) > maxTokens && chunks.length > 0) {
+    } else if (tokens + estimateTokens(row.text) > neighbourBudget && chunks.length > 0) {
       why = "budget";
     }
     if (options.debug) {
@@ -10621,6 +10701,7 @@ async function retrieve(store, embedder, query, options = {}) {
     const t = estimateTokens(row.text);
     perItem.set(row.item_id, (perItem.get(row.item_id) ?? 0) + 1);
     tokens += t;
+    kept++;
     chunks.push({
       chunkId: row.id,
       score,
@@ -10632,7 +10713,7 @@ async function retrieve(store, embedder, query, options = {}) {
       text: row.text,
       tokens: t
     });
-    if (tokens >= maxTokens)
+    if (tokens >= neighbourBudget)
       cut = true;
   }
   const durationMs = Date.now() - started;
@@ -10652,15 +10733,15 @@ function rankIn(list, id) {
 function formatDebug(result) {
   if (!result.debug)
     return "";
-  const lines = ["  vec  fts  factor  score    keep  where"];
+  const lines = ["  vec  fts  factor  score    keep         where"];
   for (const d of result.debug) {
     const where = [d.relPath, ...d.headingPath].join(" \u203A ").slice(0, 70);
     lines.push([
       String(d.vecRank ?? "-").padStart(5),
       String(d.ftsRank ?? "-").padStart(4),
       d.factor.toFixed(2).padStart(7),
-      d.score.toFixed(4).padStart(8),
-      (d.kept ? "yes" : d.why).padEnd(12),
+      (Number.isFinite(d.score) ? d.score.toFixed(4) : "pin").padStart(8),
+      (d.kept ? d.why === "pinned" ? "pinned" : "yes" : d.why).padEnd(12),
       where
     ].join(" "));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yurtsever/capsa",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "Your project's knowledge in one capsule. Local-first project memory and cockpit for AI coding agents: indexes runbooks, tickets, plans and instruction files, serves the smallest relevant context over MCP.",
   "type": "module",
   "license": "MIT",