nodedex 0.1.0

package/dist/api-server.js

@@ -0,0 +1,351 @@
+// api-server.ts — thin orchestrator. Creates the Express app, mounts all route
+// modules, and handles startup recovery for the reflect queue.
+// Reference: api-server.v1.ts (the original monolithic version, 3390 lines)
+import express from "express";
+import cors from "cors";
+import { writeFileSync, existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+import path from "path";
+import { reflectQueue, processReflectQueue, reflectPaused, setReflectPaused, spendPaused, setSpendPaused, startCreditAutoResume } from "./routes/state.js";
+import { spendPauseFileExists, readSpendPauseReason } from "./middleware/reflect/cost-guard.js";
+import { createBlocksRouter } from "./routes/blocks.js";
+import { createRecallRouter } from "./routes/recall.js";
+import { createReflectRouter } from "./routes/reflect.js";
+import { createSessionRouter } from "./routes/session.js";
+import { createWorkspaceRouter } from "./routes/workspace.js";
+import { createAdminRouter } from "./routes/admin.js";
+import { createInjectRouter } from "./routes/inject.js";
+import { createChatProxyRouter } from "./routes/chat-proxy.js";
+import { createQuarantineRouter } from "./routes/quarantine.js";
+import { createConversationsRouter } from "./routes/conversations.js";
+import { createFlagsRouter } from "./routes/flags.js";
+import { createUsageRouter } from "./routes/usage.js";
+import { createMcpHttpRouter } from "./routes/mcp-http.js";
+import { startArcInactivityTimer, startBootArcSweep } from "./middleware/reflect/arc-inactivity-timer.js";
+import { startFlagReviewer } from "./middleware/reflect/flag-reviewer-startup.js";
+import { startStageAuditTimer } from "./middleware/reflect/stage-audit-graph.js";
+import { startDescriberTimer } from "./middleware/reflect/describe-roots.js";
+import { startProvenanceReviewerTimer } from "./middleware/reflect/provenance-reviewer.js";
+import { requireAuth, defaultAuthExempt, resolveBindHost, apiTokenEnabled } from "./middleware/auth.js";
+import { startBackupTimer } from "./store/backup.js";
+import { startSchemaHealTimer } from "./middleware/reflect/schema-heal.js";
+export function startApiServer(db, schedulerHealth, port = 3001, embeddings) {
+    const app = express();
+    app.use(cors());
+    // ─── Data directory ───────────────────────────────────────────────────────
+    const __filename_api = fileURLToPath(import.meta.url);
+    const __dirname_api = path.dirname(__filename_api);
+    const dataDir = path.resolve(__dirname_api, "../../data");
+    const serverStartFile = path.join(dataDir, "server_start.txt");
+    // Stamp the current server start time — gap mirror uses this as session boundary
+    try {
+        writeFileSync(serverStartFile, new Date().toISOString(), "utf8");
+    }
+    catch { /* non-fatal */ }
+    // Larger limit on the chat-proxy path — LLM message arrays exceed the 100kb default.
+    // Must precede the global json() so this path is parsed with the bigger cap.
+    app.use("/api/chat", express.json({ limit: "16mb" }));
+    app.use(express.json());
+    // ─── API auth middleware (security slice 1) ───────────────────────────────
+    // Whole-API token lock. Default OFF (NODEDEX_API_TOKEN unset) = open, and the
+    // localhost bind below is the protection — keeps the live dogfood loop + a
+    // naive install working. Set NODEDEX_API_TOKEN to require it on every /api/*
+    // read AND write (a memory graph is maximally sensitive; reads = exfiltration).
+    // Exempts /api/health (supervisors), /api/chat (BYO-key passthrough), /upgrade.
+    // This is the forward-compat seam for the future multi-tenant server — see
+    // middleware/auth.ts. Layered with the ADMIN_TOKEN gate below (which adds an
+    // extra lock on the destructive paths even when the API token is off).
+    app.use(requireAuth({ exempt: defaultAuthExempt }));
+    // ─── Admin auth middleware ────────────────────────────────────────────────
+    // Protects destructive/admin endpoints with NODEDEX_ADMIN_TOKEN env var.
+    // Read-only endpoints (GET /api/blocks, /api/tree, /api/recall-fast, etc.) stay open.
+    // If NODEDEX_ADMIN_TOKEN is not set, admin endpoints are unprotected (local dev default).
+    // Token accepted via: Authorization: Bearer <token>  OR  x-admin-token: <token>
+    const ADMIN_TOKEN = process.env.NODEDEX_ADMIN_TOKEN || "";
+    const ADMIN_PATHS = new Set([
+        "/api/admin/reembed-all",
+        "/api/admin/backup",
+        "/api/admin/config",
+        "/api/session/reset",
+        "/api/reflect/stats/reset",
+        "/api/reflect/pause",
+        "/api/reflect/resume",
+    ]);
+    app.use((req, res, next) => {
+        if (!ADMIN_TOKEN)
+            return next();
+        if (!ADMIN_PATHS.has(req.path))
+            return next();
+        const bearer = (req.headers["authorization"] || "").replace(/^Bearer\s+/i, "").trim();
+        const header = (req.headers["x-admin-token"] || "");
+        if (bearer === ADMIN_TOKEN || header === ADMIN_TOKEN)
+            return next();
+        res.status(401).json({ error: "Unauthorized — NODEDEX_ADMIN_TOKEN required" });
+    });
+    // ─── Mount all route modules ──────────────────────────────────────────────
+    app.use(createAdminRouter(db, schedulerHealth, embeddings));
+    app.use(createBlocksRouter(db));
+    app.use(createRecallRouter(db, embeddings));
+    app.use(createReflectRouter(db, embeddings));
+    app.use(createSessionRouter(db, dataDir));
+    app.use(createWorkspaceRouter(db, embeddings));
+    app.use(createInjectRouter(db, dataDir));
+    app.use(createChatProxyRouter(db, embeddings));
+    app.use(createQuarantineRouter(db));
+    app.use(createConversationsRouter(db));
+    app.use(createFlagsRouter(db));
+    app.use(createUsageRouter());
+    // Streamable-HTTP MCP transport at /mcp — lets a NETWORKED MCP client (e.g. a
+    // Dockerized host via host.docker.internal) use the tools when it can't spawn the
+    // stdio binary itself. Same tool surface as stdio; self-gated by the owner token.
+    // Needs embeddings to build the server (always provided by server.ts).
+    if (embeddings)
+        app.use(createMcpHttpRouter(db, embeddings));
+    // DEBT 5 Phase 10: inactivity safety net (server-side timer).
+    // Default OFF — opt-in via NODEDEX_ARC_INACTIVITY_ENABLED=on. No-op when
+    // off; checks for stale pass01_done turns when on (default every 60s,
+    // threshold 30 min idle). Idempotent — safe to call on each server start.
+    startArcInactivityTimer(db);
+    // Boot sweep: recover arcs a restart stranded mid-extraction (the auto-trigger
+    // is fire-and-forget, so a restart kills an in-flight extraction and leaves the
+    // turns pass01_done with no re-trigger). One-shot, ~90s after boot; gated on arc
+    // mode being on (NODEDEX_ARC_EXTRACTION=1), off-switch NODEDEX_ARC_BOOT_SWEEP=off.
+    startBootArcSweep(db);
+    // DEBT 5 Slice 2: enrichment-cycle workers (both default OFF, opt-in).
+    //   Flag reviewer — consumes pipeline_flags, decides merge/leave/split.
+    //     NODEDEX_FLAG_REVIEWER_ENABLED=on (+ NODEDEX_FLAG_AUTO_MERGE=on for
+    //     Level 2 auto-archive). Default OFF = flags accumulate for manual
+    //     inspection via GET /api/flags.
+    //   Stage AUDIT — periodic graph-health scan writing flags.
+    //     NODEDEX_AUDIT_ENABLED=on. Default OFF.
+    // Both idempotent — safe to call on each server start.
+    startFlagReviewer(db);
+    startStageAuditTimer(db);
+    // Recognition Layer step 1: the DESCRIBER — maintains a surface description
+    // (domain + owner) on each project root, the fuel the recognizer will compare
+    // new knowledge against (docs/PIPELINE-RECOGNITION-LAYER-DESIGN.md §3/§6).
+    // Async LLM worker (mirrors the reviewer, NOT flag-only AUDIT). Default OFF:
+    // NODEDEX_DESCRIBER_ENABLED=on.
+    startDescriberTimer(db);
+    // Gap ④(b): the PROVENANCE MEANING-REVIEWER — consumes the HARD provenance_mismatch
+    // flags the $0 detector wrote, judges grounded-or-fabricated by meaning, and
+    // (Level 2) corrects/demotes. Async LLM worker. Default OFF:
+    // NODEDEX_PROVENANCE_REVIEWER_ENABLED=on (+ NODEDEX_PROVENANCE_AUTO_ACT=on to mutate).
+    startProvenanceReviewerTimer(db);
+    // Ops gap 3: scheduled DB backups (store/backup.ts). DEFAULT ON ($0 +
+    // protective, unlike the LLM timers above); checkpoint-then-copy = consistent
+    // + encryption-preserving. NODEDEX_BACKUP_ENABLED=0 to disable.
+    startBackupTimer(db);
+    // Tier-1 LOCKED-ON ($0 deterministic): retroactively demote old mis-typed blocks
+    // (e.g. an insight with no implication but an observation IS a fact) that predate the
+    // save-time demote or slipped past it. The doc listed this as default-on but no timer
+    // was wired — this closes that gap. NODEDEX_SCHEMA_HEAL_ENABLED=off to disable.
+    startSchemaHealTimer(db);
+    // ─── Upgrade page ────────────────────────────────────────────────────────
+    // Served at /upgrade — users land here from 402 pro_required errors.
+    const LEMON_CHECKOUT = process.env.NODEDEX_CHECKOUT_URL || "https://nodedex.lemonsqueezy.com/checkout";
+    app.get("/upgrade", (_req, res) => {
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        res.send(`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Nodedex Pro</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: #0d0d0d; color: #e8e8e8;
+      min-height: 100vh; display: flex; align-items: center; justify-content: center;
+      padding: 2rem;
+    }
+    .card {
+      background: #141414; border: 1px solid #2a2a2a; border-radius: 12px;
+      max-width: 540px; width: 100%; padding: 2.5rem;
+    }
+    .badge {
+      display: inline-block; background: #1a3a2a; color: #4ade80;
+      font-size: 0.7rem; font-weight: 700; letter-spacing: 0.08em;
+      text-transform: uppercase; padding: 0.25rem 0.6rem; border-radius: 99px;
+      margin-bottom: 1.25rem;
+    }
+    h1 { font-size: 1.75rem; font-weight: 700; margin-bottom: 0.5rem; }
+    .sub { color: #888; font-size: 0.95rem; margin-bottom: 2rem; line-height: 1.5; }
+    .features { list-style: none; margin-bottom: 2rem; }
+    .features li {
+      display: flex; align-items: flex-start; gap: 0.75rem;
+      padding: 0.6rem 0; border-bottom: 1px solid #1e1e1e; font-size: 0.9rem;
+    }
+    .features li:last-child { border-bottom: none; }
+    .check { color: #4ade80; font-size: 1rem; flex-shrink: 0; margin-top: 0.05rem; }
+    .desc { color: #aaa; font-size: 0.8rem; margin-top: 0.15rem; }
+    .cta {
+      display: block; width: 100%; padding: 0.85rem 1.5rem;
+      background: #16a34a; color: #fff; font-size: 1rem; font-weight: 600;
+      border: none; border-radius: 8px; cursor: pointer; text-align: center;
+      text-decoration: none; transition: background 0.15s;
+    }
+    .cta:hover { background: #15803d; }
+    .note { color: #555; font-size: 0.78rem; text-align: center; margin-top: 1rem; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="badge">Pro Required</div>
+    <h1>Nodedex Pro</h1>
+    <p class="sub">
+      You hit a feature that requires a Pro license.<br />
+      Unlock the full pipeline and advanced tooling with one key.
+    </p>
+    <ul class="features">
+      <li>
+        <span class="check">&#10003;</span>
+        <div>
+          <div><strong>Pass 4 — Causal Wiring</strong></div>
+          <div class="desc">Automatically traces cause-effect chains across your entire knowledge graph.</div>
+        </div>
+      </li>
+      <li>
+        <span class="check">&#10003;</span>
+        <div>
+          <div><strong>Session Reports</strong></div>
+          <div class="desc">Full session intelligence reports via <code>/api/session/report</code>.</div>
+        </div>
+      </li>
+      <li>
+        <span class="check">&#10003;</span>
+        <div>
+          <div><strong>workspace_challenge</strong></div>
+          <div class="desc">Challenge stale beliefs and surface contradictions across the graph.</div>
+        </div>
+      </li>
+      <li>
+        <span class="check">&#10003;</span>
+        <div>
+          <div><strong>Free tier included</strong></div>
+          <div class="desc">Pass 0-3 and all core graph operations remain free — no key needed.</div>
+        </div>
+      </li>
+    </ul>
+    <a class="cta" href="${LEMON_CHECKOUT}" target="_blank" rel="noopener">
+      Get Nodedex Pro &rarr;
+    </a>
+    <p class="note">
+      After purchase, set <code>NODEDEX_LICENSE_KEY=&lt;your-key&gt;</code> and restart the server.
+    </p>
+  </div>
+</body>
+</html>`);
+    });
+    // ── Honor the reflect-pause file at boot ────────────────────────────────────
+    // ~/.nodedex/reflect-pause is the user's "stop reflecting" switch (also checked
+    // by the hooks). The in-memory reflectPaused flag used to reset to false on
+    // every restart, so a paused user who restarted the server silently resumed
+    // per-turn reflection AND drained the recovered job queue — the surprise spend
+    // hit on 2026-06-01. Seed the flag from the file so pause survives restarts.
+    try {
+        const pauseFile = path.join(homedir(), ".nodedex", "reflect-pause");
+        if (existsSync(pauseFile)) {
+            setReflectPaused(true);
+            console.log("[reflect] reflect-pause file present at boot — reflection PAUSED (delete ~/.nodedex/reflect-pause + POST /api/reflect/resume to re-enable)");
+        }
+    }
+    catch { /* non-fatal */ }
+    // Honor the SPEND-pause file (cost-breaker / credit-out). Distinct from reflect-pause:
+    // spending stays halted but CAPTURE KEEPS QUEUING, and the auto-resume timer drains it
+    // once credit recovers — so a restart mid-outage doesn't burn credit OR drop turns.
+    try {
+        if (spendPauseFileExists()) {
+            setSpendPaused(true);
+            console.log(`[cost-breaker] spend-pause file present at boot — SPENDING PAUSED (${readSpendPauseReason() ?? "credit/budget"}); capture still queuing; auto-resumes on top-up`);
+        }
+    }
+    catch { /* non-fatal */ }
+    // ─── Startup: recover persisted reflect jobs ──────────────────────────────
+    // Jobs stuck in 'processing' mean the server crashed mid-job — reset to pending.
+    // Jobs in 'pending' or 'retry_wait' are loaded back into the in-memory queue.
+    try {
+        const cleaned = db.cleanupReflectJobs();
+        if (cleaned > 0)
+            console.log(`[reflect-queue] cleaned up ${cleaned} stale DB job(s)`);
+        const staleJobs = db.getActiveReflectJobs();
+        let recovered = 0;
+        for (const row of staleJobs) {
+            if (row.status === 'processing' || (row.status === 'dead' && row.error === 'max retries exceeded')) {
+                db.updateReflectJob(row.id, { status: 'pending', retry_after: null });
+                row.status = 'pending';
+                row.retry_after = null;
+            }
+            try {
+                const payload = JSON.parse(row.payload);
+                const precomputed = row.precomputed ? JSON.parse(row.precomputed) : {};
+                reflectQueue.push({
+                    agentResponse: payload.agentResponse ?? "",
+                    agentThinking: payload.agentThinking ?? "",
+                    userMessage: payload.userMessage ?? "",
+                    loadedBlockIds: payload.loadedBlockIds ?? [],
+                    agentId: row.agent_id ?? undefined,
+                    precomputedPass0: precomputed.pass0 ?? undefined,
+                    precomputedPass1: precomputed.pass1 ?? undefined,
+                    precomputedPass2: precomputed.pass2 ?? undefined,
+                    precomputedPass3PendingBlockIds: precomputed.p3PendingBlockIds ?? undefined,
+                    retryAfter: row.retry_after ?? undefined,
+                    retryAttempts: row.retry_attempts,
+                    dbId: row.id,
+                });
+                recovered++;
+            }
+            catch { /* corrupt row — skip */ }
+        }
+        if (recovered > 0 && !reflectPaused && !spendPaused) {
+            console.log(`[reflect-queue] recovered ${recovered} job(s) from DB — resuming`);
+            processReflectQueue(db, embeddings || undefined).catch(e => console.error("[reflect-queue] recovery worker error:", e));
+        }
+        else if (recovered > 0 && spendPaused) {
+            console.log(`[reflect-queue] recovered ${recovered} job(s) from DB — NOT draining (spending paused: credit/budget). Auto-resumes when the balance recovers.`);
+        }
+        else if (recovered > 0) {
+            console.log(`[reflect-queue] recovered ${recovered} job(s) from DB — NOT draining (reflect paused). Delete ~/.nodedex/reflect-pause + POST /api/reflect/resume to drain.`);
+        }
+    }
+    catch (e) {
+        console.error("[reflect-queue] startup recovery failed:", e);
+    }
+    const bindHost = resolveBindHost();
+    const server = app.listen(port, bindHost, () => {
+        const shown = bindHost === "0.0.0.0" ? "localhost" : bindHost;
+        const lock = apiTokenEnabled() ? "token-locked" : "open (localhost-only)";
+        console.error(`Workspace Web UI API running on http://${shown}:${port} — bound ${bindHost}, ${lock}`);
+        if (embeddings)
+            console.error(`MCP (HTTP) endpoint: http://${shown}:${port}/mcp — for networked clients (e.g. Docker: http://host.docker.internal:${port}/mcp)`);
+        if (bindHost === "0.0.0.0" && !apiTokenEnabled()) {
+            console.error("⚠ SECURITY: bound to 0.0.0.0 (network-reachable) with NO NODEDEX_API_TOKEN — the graph is exposed unauthenticated. Set NODEDEX_API_TOKEN.");
+        }
+    });
+    // Auto-resume the spend-pause once credit tops back up (a separate timer — the drain
+    // loop breaks on spendPaused before it could re-check the budget itself). unref'd, so
+    // it never holds the process open.
+    startCreditAutoResume(db, embeddings || undefined);
+    // Stale-process trap fix: db.init() already opened the DB, and the MCP stdio
+    // transport keeps this process alive — so a server that CAN'T bind the port
+    // would otherwise linger as a zombie holding the DB lock (the accumulation we
+    // hit all session). On EADDRINUSE (or any listen error), release the DB and
+    // EXIT instead of zombie-lingering.
+    server.on("error", (e) => {
+        if (e.code === "EADDRINUSE") {
+            console.error(`✖ port ${port} already in use — another nodedex server is running. Exiting (won't linger holding the DB). Stop the other first, or use scripts/restart.mjs.`);
+        }
+        else {
+            console.error(`✖ API server error: ${e.message}. Exiting.`);
+        }
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+        process.exit(1);
+    });
+    return server;
+}
+//# sourceMappingURL=api-server.js.map

package/dist/api-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-server.js","sourceRoot":"","sources":["../src/api-server.ts"],"names":[],"mappings":"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"}

package/dist/boot-env.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=boot-env.d.ts.map

package/dist/boot-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-env.d.ts","sourceRoot":"","sources":["../src/boot-env.ts"],"names":[],"mappings":""}

package/dist/boot-env.js

@@ -0,0 +1,12 @@
+// boot-env.ts — side-effect module: load ~/.nodedex/.env BEFORE anything else.
+//
+// Imported FIRST in server.ts so this runs before any other module's top-level
+// process.env reads (config consts, provider defaults, …). Precedence: a real env var /
+// --env-file (dev server/.env) already in process.env WINS; this only fills the gaps a
+// fresh install relies on. See home-env.ts.
+import { loadHomeEnv, HOME_ENV_PATH } from "./home-env.js";
+const applied = loadHomeEnv();
+if (applied > 0) {
+    console.error(`[boot] applied ${applied} setting(s) from ${HOME_ENV_PATH} (env / --env-file still win)`);
+}
+//# sourceMappingURL=boot-env.js.map

package/dist/boot-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-env.js","sourceRoot":"","sources":["../src/boot-env.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,+EAA+E;AAC/E,wFAAwF;AACxF,uFAAuF;AACvF,4CAA4C;AAC5C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE3D,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;AAC9B,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;IAChB,OAAO,CAAC,KAAK,CAAC,kBAAkB,OAAO,oBAAoB,aAAa,+BAA+B,CAAC,CAAC;AAC3G,CAAC"}

package/dist/engine/__tests__/search-core.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search-core.test.d.ts.map

package/dist/engine/__tests__/search-core.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-core.test.d.ts","sourceRoot":"","sources":["../../../src/engine/__tests__/search-core.test.ts"],"names":[],"mappings":""}

package/dist/engine/__tests__/search-core.test.js

@@ -0,0 +1,139 @@
+/**
+ * search-core tests — the shared three-signal scorer (MCP workspace_search +
+ * REST /api/search rank identically through this).
+ *
+ * Pins the ranking principle: MATCH QUALITY ONLY. No popularity ranking
+ * (access_count), no freshness decay, no usage penalty — the graph's
+ * highest-value blocks (dead-ends) are old and rarely accessed by design.
+ * Run: node --import=tsx/esm --test src/engine/__tests__/search-core.test.ts
+ */
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { WorkspaceDB } from "../../store/database.js";
+import { searchBlocks, rootContextFor, allWeak } from "../search-core.js";
+const TEST_DB = path.resolve("/tmp/search_core_test.db");
+let db;
+before(async () => {
+    for (const s of ["", "-wal", "-shm"]) {
+        if (fs.existsSync(TEST_DB + s))
+            fs.unlinkSync(TEST_DB + s);
+    }
+    db = new WorkspaceDB(TEST_DB);
+    await db.init();
+});
+after(() => {
+    try {
+        db["db"]?.close();
+    }
+    catch { /* ignore */ }
+    for (const s of ["", "-wal", "-shm"]) {
+        try {
+            if (fs.existsSync(TEST_DB + s))
+                fs.unlinkSync(TEST_DB + s);
+        }
+        catch { /* ignore */ }
+    }
+});
+describe("searchBlocks — match-quality ranking", () => {
+    test("strong match beats popular weak match (no access_count ranking)", async () => {
+        const strong = db.createBlock({
+            label: "garden_dead-end_aphid-spray-failed",
+            type: "dead_end",
+            essence: "Aphid spray failed — neem oil burned the tomato leaves",
+            content: { concepts: ["aphid-spray", "neem-oil", "tomato"] },
+            ttl: "permanent",
+        });
+        const popular = db.createBlock({
+            label: "garden_fact_watering-schedule",
+            type: "fact",
+            essence: "Watering twice a week; the spray bottle is under the sink",
+            content: { concepts: ["watering"] },
+            ttl: "permanent",
+        });
+        // Make the weak block "popular": many reads bump access_count. The OLD REST
+        // path (ORDER BY access_count DESC) would rank it first on any shared term.
+        for (let i = 0; i < 25; i++)
+            db.getBlock(popular.id);
+        const { hits } = await searchBlocks(db, undefined, { query: "aphid spray neem", limit: 5 });
+        assert.ok(hits.length >= 2, "both blocks share the 'spray' term");
+        assert.equal(hits[0].block.id, strong.id, "the actual match must outrank the popular block");
+    });
+    test("signals add: keyword+concept hit outranks keyword-only", async () => {
+        db.createBlock({
+            label: "forge_fact_jwt-mention",
+            type: "fact",
+            essence: "The doc mentions jwt once in passing",
+            content: {},
+            ttl: "permanent",
+        });
+        const both = db.createBlock({
+            label: "forge_decision_jwt-hs256",
+            type: "decision",
+            essence: "Use HS256 jwt tokens for service auth",
+            content: { concepts: ["jwt", "hs256", "auth-tokens"] },
+            ttl: "permanent",
+        });
+        const { hits, signals } = await searchBlocks(db, undefined, { query: "jwt auth", limit: 5 });
+        assert.equal(hits[0].block.id, both.id, "keyword+concept beats keyword-only");
+        assert.ok(hits[0].matchTypes.some((t) => t.startsWith("concept(")), "concept match is explained");
+        assert.equal(signals.semantic, false, "no embeddings passed → semantic signal reported off");
+        assert.equal(signals.keyword, true);
+    });
+    test("type filter restricts hits", async () => {
+        const { hits } = await searchBlocks(db, undefined, { query: "jwt", type: "decision", limit: 5 });
+        assert.ok(hits.length > 0);
+        assert.ok(hits.every((h) => h.block.type === "decision"));
+    });
+    test("no query tokens → empty, never throws", async () => {
+        const { hits } = await searchBlocks(db, undefined, { query: "zzzz_nothing_matches_this", limit: 5 });
+        assert.equal(hits.length, 0);
+    });
+});
+describe("allWeak — the nearest-neighbor shrug detector", () => {
+    const hit = (score, matchTypes) => ({ block: {}, score, matchTypes });
+    test("all semantic-only sub-0.3 hits → weak (off-graph query signature)", () => {
+        assert.equal(allWeak([hit(0.26, ["semantic"]), hit(0.26, ["semantic"])]), true);
+    });
+    test("one strong or multi-signal hit anywhere → not weak", () => {
+        assert.equal(allWeak([hit(0.63, ["semantic", "keyword"]), hit(0.22, ["semantic"])]), false);
+        assert.equal(allWeak([hit(0.45, ["semantic"])]), false, "high score alone disarms it");
+        assert.equal(allWeak([hit(0.25, ["keyword"])]), false, "keyword match alone disarms it");
+    });
+    test("empty result set is not weak (it is simply empty)", () => {
+        assert.equal(allWeak([]), false);
+    });
+});
+describe("rootContextFor — containment attached to hits", () => {
+    test("resolves project_id to root label + truncated essence, once per root", async () => {
+        const root = db.createBlock({
+            label: "garden",
+            type: "project",
+            essence: "Backyard vegetable garden project — pests, soil, and the greenhouse build. " + "x".repeat(60),
+            content: {},
+            ttl: "permanent",
+        });
+        const child = db.createBlock({
+            label: "garden_fact_soil-ph",
+            type: "fact",
+            essence: "Soil pH is 6.2",
+            content: {},
+            ttl: "permanent",
+        });
+        db.updateBlock(child.id, { project_id: root.id });
+        const fresh = db.getBlock(child.id);
+        const ctx = rootContextFor(db, [fresh, fresh]); // duplicate input → single lookup
+        assert.equal(ctx.size, 1);
+        const rc = ctx.get(root.id);
+        assert.equal(rc.root_label, "garden");
+        assert.ok(rc.root_essence.endsWith("…"), "long root essence is truncated");
+        assert.ok(rc.root_essence.length <= 101);
+    });
+    test("blocks without project_id or with dangling project_id are skipped", () => {
+        const orphan = db.getBlock("forge_fact_jwt-mention");
+        const ctx = rootContextFor(db, [orphan]);
+        assert.equal(ctx.size, 0);
+    });
+});
+//# sourceMappingURL=search-core.test.js.map

package/dist/engine/__tests__/search-core.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-core.test.js","sourceRoot":"","sources":["../../../src/engine/__tests__/search-core.test.ts"],"names":[],"mappings":"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"}

package/dist/engine/ai-provider.d.ts

@@ -0,0 +1,45 @@
+export interface GenerateResult<T> {
+    result: T | null;
+    rateLimited: boolean;
+    /** The call failed because the account is OUT OF CREDIT (HTTP 402 / insufficient-credit
+     *  body) — distinct from rateLimited (a transient capacity cap). The reflect queue treats
+     *  this as a spend-pause trigger (preserve + requeue the turn, never drop), so it must be
+     *  surfaced rather than swallowed into a generic null. See isInsufficientCreditError. */
+    creditExhausted?: boolean;
+    thinking?: string;
+    usage?: {
+        input: number;
+        thinking: number;
+        output: number;
+        costUsd?: number;
+    };
+    /** Model that produced this result (or the last attempted, on failure). Instrumentation for run-to-run variance. */
+    model?: string;
+    /**
+     * Full attempt trail across the primary-then-fallback escalation in this single generateStructured() call.
+     * Lets the turn log show *why* a run diverged (e.g. primary truncated → fallback succeeded). One entry per
+     * model invocation; the last entry's outcome matches `result === null` (failure) or `"ok"`.
+     */
+    attempts?: Array<{
+        model: string;
+        outcome: "ok" | "rate_limited" | "truncated" | "empty" | "timeout" | "error";
+    }>;
+}
+export interface LLMProvider {
+    /** Schema-enforced JSON generation — used by pipeline passes 1–4. */
+    generateStructured<T>(systemPrompt: string, userInput: string, schema: object, options?: {
+        thinkingBudget?: number;
+        maxOutputTokens?: number;
+        modelOverride?: string;
+    }): Promise<GenerateResult<T>>;
+    /** Free-form text/JSON generation — route handlers, tools, scheduler jobs. */
+    generate(prompt: string): Promise<string | null>;
+    ping(): Promise<boolean>;
+    isAvailable(): boolean;
+    getName(): string;
+}
+export interface EmbeddingProvider {
+    embed(text: string): Promise<number[] | null>;
+    isAvailable(): boolean;
+}
+//# sourceMappingURL=ai-provider.d.ts.map

package/dist/engine/ai-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-provider.d.ts","sourceRoot":"","sources":["../../src/engine/ai-provider.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB;;;6FAGyF;IACzF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9E,oHAAoH;IACpH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,IAAI,GAAG,cAAc,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;CACnH;AAED,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,kBAAkB,CAAC,CAAC,EAClB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACtF,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEjD,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,WAAW,IAAI,OAAO,CAAC;IACvB,OAAO,IAAI,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAC9C,WAAW,IAAI,OAAO,CAAC;CACxB"}

package/dist/engine/ai-provider.js

@@ -0,0 +1,5 @@
+// ─── AI Provider Abstraction ──────────────────────────────────────────────────
+// Swap AI backends without touching pipeline logic.
+// Supported: gemini (default) | openai | anthropic | openai-compatible (Ollama, Groq, etc.)
+export {};
+//# sourceMappingURL=ai-provider.js.map

package/dist/engine/ai-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-provider.js","sourceRoot":"","sources":["../../src/engine/ai-provider.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,oDAAoD;AACpD,4FAA4F"}