brane 0.1.1 → 0.3.0

package/dist/test/read-events.test.js

@@ -0,0 +1,220 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { appendEvent, readEvents } from "../db/events.js";
+/**
+ * Populate a narrative with N events labeled msg-0 through msg-(N-1).
+ * Returns the seq of the last event inserted.
+ */
+function populate(db, nid, count) {
+    let lastSeq = 0;
+    for (let i = 0; i < count; i++) {
+        const e = appendEvent(db, nid, "narration", { content: `msg-${i}` });
+        lastSeq = e.seq;
+    }
+    return lastSeq;
+}
+describe("readEvents", () => {
+    // ── after (replaces heard) ──────────────────────────────────────
+    describe("after", () => {
+        it("returns events after a cursor (like heard)", () => {
+            const db = createTestDb();
+            populate(db, "n1", 5);
+            const events = readEvents(db, "n1", { after: 2 });
+            assert.equal(events.length, 3);
+            assert.equal(events[0].content, "msg-2"); // seq 3
+            assert.equal(events[2].content, "msg-4"); // seq 5
+        });
+        it("after: 0 returns all events", () => {
+            const db = createTestDb();
+            populate(db, "n1", 3);
+            const events = readEvents(db, "n1", { after: 0 });
+            assert.equal(events.length, 3);
+        });
+        it("after beyond max seq returns empty", () => {
+            const db = createTestDb();
+            populate(db, "n1", 3);
+            const events = readEvents(db, "n1", { after: 100 });
+            assert.equal(events.length, 0);
+        });
+    });
+    // ── before ──────────────────────────────────────────────────────
+    describe("before", () => {
+        it("returns events before a cursor", () => {
+            const db = createTestDb();
+            populate(db, "n1", 5);
+            const events = readEvents(db, "n1", { before: 4 });
+            assert.equal(events.length, 3); // seq 1, 2, 3
+            assert.equal(events[0].content, "msg-0");
+            assert.equal(events[2].content, "msg-2");
+        });
+        it("before: 1 returns empty (nothing before seq 1)", () => {
+            const db = createTestDb();
+            populate(db, "n1", 3);
+            const events = readEvents(db, "n1", { before: 1 });
+            assert.equal(events.length, 0);
+        });
+        it("before beyond max seq returns all events", () => {
+            const db = createTestDb();
+            populate(db, "n1", 3);
+            const events = readEvents(db, "n1", { before: 100 });
+            assert.equal(events.length, 3);
+        });
+    });
+    // ── after + before (bounded range) ─────────────────────────────
+    describe("after + before", () => {
+        it("returns events in a bounded range", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            const events = readEvents(db, "n1", { after: 3, before: 7 });
+            assert.equal(events.length, 3); // seq 4, 5, 6
+            assert.equal(events[0].content, "msg-3");
+            assert.equal(events[2].content, "msg-5");
+        });
+        it("empty range returns empty", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            // after: 5, before: 6 → only seq > 5 AND seq < 6 → nothing
+            const events = readEvents(db, "n1", { after: 5, before: 6 });
+            assert.equal(events.length, 0);
+        });
+        it("adjacent cursors return single event", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            // after: 4, before: 6 → seq 5 only
+            const events = readEvents(db, "n1", { after: 4, before: 6 });
+            assert.equal(events.length, 1);
+            assert.equal(events[0].content, "msg-4");
+        });
+        it("inverted range (after >= before) returns empty", () => {
+            const db = createTestDb();
+            populate(db, "n1", 5);
+            const events = readEvents(db, "n1", { after: 5, before: 3 });
+            assert.equal(events.length, 0);
+        });
+    });
+    // ── tail ────────────────────────────────────────────────────────
+    describe("tail", () => {
+        it("returns the last N events", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            const events = readEvents(db, "n1", { tail: 3 });
+            assert.equal(events.length, 3);
+            assert.equal(events[0].content, "msg-7"); // seq 8
+            assert.equal(events[2].content, "msg-9"); // seq 10
+        });
+        it("tail larger than total returns all events", () => {
+            const db = createTestDb();
+            populate(db, "n1", 3);
+            const events = readEvents(db, "n1", { tail: 100 });
+            assert.equal(events.length, 3);
+        });
+        it("tail: 1 returns only the last event", () => {
+            const db = createTestDb();
+            populate(db, "n1", 5);
+            const events = readEvents(db, "n1", { tail: 1 });
+            assert.equal(events.length, 1);
+            assert.equal(events[0].content, "msg-4");
+        });
+        it("tail: 0 returns empty", () => {
+            const db = createTestDb();
+            populate(db, "n1", 5);
+            const events = readEvents(db, "n1", { tail: 0 });
+            assert.equal(events.length, 0);
+        });
+    });
+    // ── tail + before (backward pagination) ────────────────────────
+    describe("tail + before", () => {
+        it("returns last N events before a cursor", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            // Last 3 before seq 8 → seq 5, 6, 7
+            const events = readEvents(db, "n1", { tail: 3, before: 8 });
+            assert.equal(events.length, 3);
+            assert.equal(events[0].content, "msg-4"); // seq 5
+            assert.equal(events[2].content, "msg-6"); // seq 7
+        });
+        it("backward pagination walks through entire history", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            // Page 1: last 3 → seq 8, 9, 10
+            const page1 = readEvents(db, "n1", { tail: 3 });
+            assert.equal(page1.length, 3);
+            assert.equal(page1[0].seq, 8);
+            // Page 2: last 3 before seq 8 → seq 5, 6, 7
+            const page2 = readEvents(db, "n1", { tail: 3, before: page1[0].seq });
+            assert.equal(page2.length, 3);
+            assert.equal(page2[0].seq, 5);
+            // Page 3: last 3 before seq 5 → seq 2, 3, 4
+            const page3 = readEvents(db, "n1", { tail: 3, before: page2[0].seq });
+            assert.equal(page3.length, 3);
+            assert.equal(page3[0].seq, 2);
+            // Page 4: last 3 before seq 2 → seq 1 (partial page)
+            const page4 = readEvents(db, "n1", { tail: 3, before: page3[0].seq });
+            assert.equal(page4.length, 1);
+            assert.equal(page4[0].seq, 1);
+            // Page 5: before seq 1 → empty (done)
+            const page5 = readEvents(db, "n1", { tail: 3, before: page4[0].seq });
+            assert.equal(page5.length, 0);
+        });
+    });
+    // ── after + tail (last N after a cursor) ───────────────────────
+    describe("after + tail", () => {
+        it("returns the last N events after a cursor", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            // Events after seq 2, but only the last 3 → seq 8, 9, 10
+            const events = readEvents(db, "n1", { after: 2, tail: 3 });
+            assert.equal(events.length, 3);
+            assert.equal(events[0].content, "msg-7"); // seq 8
+            assert.equal(events[2].content, "msg-9"); // seq 10
+        });
+    });
+    // ── after + before + tail (bounded + limited) ──────────────────
+    describe("after + before + tail", () => {
+        it("returns last N events within a bounded range", () => {
+            const db = createTestDb();
+            populate(db, "n1", 20);
+            // Range: seq 6-14 (after 5, before 15), tail 3 → seq 12, 13, 14
+            const events = readEvents(db, "n1", { after: 5, before: 15, tail: 3 });
+            assert.equal(events.length, 3);
+            assert.equal(events[0].seq, 12);
+            assert.equal(events[2].seq, 14);
+        });
+    });
+    // ── no parameters ──────────────────────────────────────────────
+    describe("defaults", () => {
+        it("no parameters returns all events (like after: 0)", () => {
+            const db = createTestDb();
+            populate(db, "n1", 5);
+            const events = readEvents(db, "n1", {});
+            assert.equal(events.length, 5);
+        });
+        it("empty narrative returns empty", () => {
+            const db = createTestDb();
+            const events = readEvents(db, "nonexistent", {});
+            assert.equal(events.length, 0);
+        });
+    });
+    // ── ordering ───────────────────────────────────────────────────
+    describe("ordering", () => {
+        it("always returns events in ascending seq order", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            // tail queries internally sort DESC then reverse
+            const events = readEvents(db, "n1", { tail: 5 });
+            for (let i = 1; i < events.length; i++) {
+                assert.ok(events[i].seq > events[i - 1].seq, `seq ${events[i].seq} should be > ${events[i - 1].seq}`);
+            }
+        });
+        it("after+before returns in ascending order", () => {
+            const db = createTestDb();
+            populate(db, "n1", 10);
+            const events = readEvents(db, "n1", { after: 2, before: 8 });
+            for (let i = 1; i < events.length; i++) {
+                assert.ok(events[i].seq > events[i - 1].seq);
+            }
+        });
+    });
+});
+//# sourceMappingURL=read-events.test.js.map

package/dist/test/remote-meld.test.js

@@ -0,0 +1,115 @@
+/**
+ * `brane meld --remote`: a remote machine (Fly, a VPS) cannot show a
+ * presence prompt, so the device token is minted on the operator's machine
+ * and the remote gets only its hash (`BRANE_DEVICE_TOKEN_SHA256`), adopted as
+ * its daemon starts. The remote sends back only its address (`brane meld
+ * --connection`).
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createTestDb } from "./helpers.js";
+import { bootstrapTokens, DbTokenStore, REMOTE_MELD_LABEL, parseTokenHashes } from "../db/tokens.js";
+import { TokenRing, UNUSED_TOKEN_LAPSE_MS, hashToken, mintRemoteToken } from "../daemon/token-ring.js";
+import { buildMeldUrl, fillHash, meldLink, readMeldReply, refusesRemoteMeld } from "../commands/meld.js";
+const T0 = Date.UTC(2026, 9, 5, 12);
+function setup() {
+    const db = createTestDb();
+    const tokenFile = join(mkdtempSync(join(tmpdir(), "brane-remote-meld-")), ".daemon_token");
+    let n = 0;
+    return { db, tokenFile, mint: () => `local-${++n}` };
+}
+describe("the remote token's hash", () => {
+    it("is the SHA-256 the daemon checks tokens by", () => {
+        const { token, hash } = mintRemoteToken();
+        assert.equal(hash, hashToken(token));
+        assert.match(hash, /^[0-9a-f]{64}$/);
+        assert.ok(token.length >= 40, "32 random bytes");
+        assert.notEqual(mintRemoteToken().token, token);
+    });
+    it("goes into the --send command wherever it says {hash}, and nowhere else", () => {
+        const h = hashToken("t");
+        assert.equal(fillHash("fly secrets set BRANE_DEVICE_TOKEN_SHA256={hash} -a x", h), `fly secrets set BRANE_DEVICE_TOKEN_SHA256=${h} -a x`);
+        assert.equal(fillHash("a={hash} b={hash}", h), `a=${h} b=${h}`);
+        assert.throws(() => fillHash("fly secrets set BRANE_DEVICE_TOKEN_SHA256=oops", h), /\{hash\}/);
+    });
+    it("is read from the secret strictly, dropping anything malformed", () => {
+        const h = hashToken("t");
+        assert.deepEqual(parseTokenHashes(undefined), []);
+        assert.deepEqual(parseTokenHashes(""), []);
+        assert.deepEqual(parseTokenHashes(` ${h.toUpperCase()} , not-a-hash, ${h}`), [h]);
+    });
+});
+describe("adopting a remote hash at startup", () => {
+    it("makes the token on the operator's machine a working device token, and the hash only", () => {
+        const { db, tokenFile, mint } = setup();
+        const { token, hash } = mintRemoteToken();
+        const boot = bootstrapTokens(db, { tokenFile, mint, configuredHashes: [hash], now: T0 });
+        assert.deepEqual(boot.adopted, [REMOTE_MELD_LABEL]);
+        const ring = new TokenRing(new DbTokenStore(db), () => "unused");
+        const auth = ring.authenticate(token, T0 + 1);
+        assert.equal(auth.ok && auth.record.kind, "device");
+        assert.equal(auth.ok && auth.record.label, REMOTE_MELD_LABEL);
+        assert.ok(!JSON.stringify(db.prepare("SELECT * FROM tokens").all()).includes(token));
+    });
+    it("adopts a hash once: the secret stays set across restarts, and a revoked one stays revoked", () => {
+        const { db, tokenFile, mint } = setup();
+        const { token, hash } = mintRemoteToken();
+        bootstrapTokens(db, { tokenFile, mint, configuredHashes: [hash], now: T0 });
+        const store = new DbTokenStore(db);
+        const row = store.live("device").find((r) => r.label === REMOTE_MELD_LABEL);
+        store.revoke([row.id], T0 + 1);
+        const again = bootstrapTokens(db, { tokenFile, mint, configuredHashes: [hash], now: T0 + 2 });
+        assert.deepEqual(again.adopted, []);
+        const ring = new TokenRing(store, () => "unused");
+        assert.equal(ring.authenticate(token, T0 + 3).ok, false);
+    });
+    it("lapses like any QR if nobody scans it", () => {
+        const { db, tokenFile, mint } = setup();
+        const { token, hash } = mintRemoteToken();
+        bootstrapTokens(db, { tokenFile, mint, configuredHashes: [hash], now: T0 });
+        const ring = new TokenRing(new DbTokenStore(db), () => "unused");
+        assert.equal(ring.authenticate(token, T0 + UNUSED_TOKEN_LAPSE_MS + 1).ok, false);
+    });
+});
+describe("the remote daemon's address", () => {
+    const c = { daemonHost: "daemon-x.tail.ts.net:8443", scheme: "https", useLocal: false, isLoopbackFallback: false, tlsDegraded: false };
+    it("is found among whatever else the --ask command printed", () => {
+        const out = `Connecting to fdaa::3... complete\n${JSON.stringify({ ready: true, ...c })}\r\n`;
+        assert.deepEqual(readMeldReply(out), { kind: "address", connection: c });
+    });
+    it("is waited for while the machine restarts, its daemon starts, or Tailscale has no name yet", () => {
+        assert.equal(readMeldReply(null).kind, "wait");
+        assert.deepEqual(readMeldReply('{"ready":false,"reason":"no daemon is running yet"}\n'), {
+            kind: "wait",
+            reason: "no daemon is running yet",
+        });
+        // A QR for 127.0.0.1 would be useless, and a wrong one costs a restart.
+        const loopback = readMeldReply(JSON.stringify({ ready: true, ...c, daemonHost: "127.0.0.1:8443", isLoopbackFallback: true }));
+        assert.deepEqual(loopback, { kind: "wait", reason: "the remote machine has no Tailscale name yet" });
+    });
+    it("calls an answer with no JSON line an older brane, which ran a plain meld", () => {
+        assert.deepEqual(readMeldReply("\nScan this QR code to meld:\n█▀▀▀▀▀█\n"), { kind: "old" });
+        assert.deepEqual(readMeldReply('{"daemonHost": 1}'), { kind: "old" });
+    });
+    it("makes the same URL brane meld would have, with the token minted elsewhere", () => {
+        const db = createTestDb();
+        db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('daemon_tls', 'true')").run();
+        for (const local of [false, true]) {
+            const full = buildMeldUrl({ db, daemon: { port: "8443", token: "tok" }, tailscaleHost: "h.ts.net", local });
+            const { url: _u, ...connection } = buildMeldUrl({ db, daemon: { port: "8443", token: "" }, tailscaleHost: "h.ts.net", local });
+            assert.equal(meldLink(connection, "tok"), full.url);
+        }
+    });
+});
+describe("refusesRemoteMeld", () => {
+    it("refuses in an agent's session, which would read the printed token", () => {
+        assert.match(refusesRemoteMeld({ BRANE_NARRATIVE_SECRET: "x" }) ?? "", /outside an agent session/);
+    });
+    it("runs from the operator's shell", () => {
+        assert.equal(refusesRemoteMeld({}), null);
+    });
+});
+//# sourceMappingURL=remote-meld.test.js.map

package/dist/test/revive-cli.test.js

@@ -0,0 +1,93 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { buildReviveBody, formatReviveResult } from "../commands/revive.js";
+import { daemonRequest } from "../daemon/client.js";
+describe("buildReviveBody", () => {
+    it("sends nothing at all when no flags are given", () => {
+        // The daemon's defaults (LIVE-loop prompt, same agent) must stay in
+        // charge of everything the operator didn't ask about.
+        assert.deepEqual(buildReviveBody({}), {});
+    });
+    it("maps --no-prompt onto the API's snake_case no_prompt", () => {
+        assert.deepEqual(buildReviveBody({ "no-prompt": true }), { no_prompt: true });
+    });
+    it("omits no_prompt when the flag is absent rather than sending false", () => {
+        assert.deepEqual(buildReviveBody({ prompt: "carry on" }), { prompt: "carry on" });
+    });
+    it("passes --agent through for the agent-switch path", () => {
+        assert.deepEqual(buildReviveBody({ agent: "goose", prompt: "hi" }), {
+            agent: "goose",
+            prompt: "hi",
+        });
+    });
+});
+describe("formatReviveResult", () => {
+    it("names the revived session and its agent", () => {
+        assert.equal(formatReviveResult("claude-abc12345", {
+            status: "revived",
+            nid: "claude-abc12345",
+            agent: "claude",
+        }), "Revived claude-abc12345 (claude)");
+    });
+    it("reports an already-running session without claiming to have restarted it", () => {
+        assert.equal(formatReviveResult("claude-abc12345", {
+            status: "already_running",
+            nid: "claude-abc12345",
+            agent: "claude",
+        }), "Session claude-abc12345 is already running.");
+    });
+    it("names the twin, not the narrative it continues from", () => {
+        // The distinction the old in-process CLI could not make: an absorbed or
+        // agent-switched revive spawns a *new* narrative, and printing the
+        // requested id would point the operator at the wrong pane.
+        assert.equal(formatReviveResult("chatgpt-0f9e8d7c", {
+            status: "continued",
+            nid: "goose-11223344",
+            agent: "goose",
+        }), "Continued chatgpt-0f9e8d7c as goose-11223344 (goose)");
+    });
+    it("degrades quietly when an older daemon doesn't report the agent", () => {
+        assert.equal(formatReviveResult("claude-abc12345", { status: "revived", nid: "claude-abc12345" }), "Revived claude-abc12345");
+    });
+});
+describe("revive over daemonRequest", () => {
+    let server;
+    let endpoint;
+    const seen = [];
+    before(async () => {
+        server = createServer((req, res) => {
+            let body = "";
+            req.on("data", (c) => (body += c));
+            req.on("end", () => {
+                seen.push({ method: req.method ?? "", url: req.url ?? "", body });
+                if (req.url?.startsWith("/api/revive/claude-abc12345")) {
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ status: "revived", nid: "claude-abc12345", agent: "claude" }));
+                }
+                else {
+                    res.writeHead(404, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Unknown narrative: nope" }));
+                }
+            });
+        });
+        await new Promise((r) => server.listen(0, "127.0.0.1", r));
+        const port = server.address().port;
+        endpoint = { baseUrl: `http://127.0.0.1:${port}`, token: "tok", port: String(port) };
+    });
+    after(async () => {
+        await new Promise((r) => server.close(() => r()));
+    });
+    it("POSTs the nid in the path and the flags in the body", async () => {
+        const result = await daemonRequest(endpoint, `/api/revive/${encodeURIComponent("claude-abc12345")}`, { method: "POST", body: buildReviveBody({ prompt: "resume the audit" }) });
+        assert.equal(result.status, "revived");
+        assert.equal(result.agent, "claude");
+        const req = seen.find((r) => r.url === "/api/revive/claude-abc12345");
+        assert.equal(req?.method, "POST");
+        assert.deepEqual(JSON.parse(req?.body ?? "{}"), { prompt: "resume the audit" });
+    });
+    it("surfaces the daemon's unknown-narrative error verbatim", async () => {
+        await assert.rejects(() => daemonRequest(endpoint, "/api/revive/nope", { method: "POST", body: {} }), /^Error: Unknown narrative: nope$/);
+    });
+});
+//# sourceMappingURL=revive-cli.test.js.map

package/dist/test/search-floor.test.js

@@ -0,0 +1,206 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { MIN_SEMANTIC_SCORE, initMemorySchema, searchHybrid, upsertChunks, } from "../memory/storage.js";
+// Synthetic vectors throughout — no embedding model. The floor is a numeric
+// boundary, and pinning it needs similarities chosen to the second decimal,
+// which is exactly what a real embedder won't give you twice. (The
+// model-backed end-to-end path stays covered by search.test.ts.)
+const DIM = 384;
+/** A unit vector along `axis`. Distinct axes are orthogonal, so cosine
+ *  similarity between them is 0; blending toward the query axis dials
+ *  similarity to any value we want. */
+function axisVector(axis) {
+    const v = new Float32Array(DIM);
+    v[axis] = 1;
+    return v;
+}
+/** A unit vector whose cosine similarity to `axisVector(0)` is `target`.
+ *  Built by rotating within the (0, axis) plane, so the result stays unit
+ *  length and sqlite-vec's cosine distance comes back as 1 - target. */
+function vectorWithSimilarity(target, axis = 1) {
+    const v = new Float32Array(DIM);
+    v[0] = target;
+    v[axis] = Math.sqrt(Math.max(0, 1 - target * target));
+    return v;
+}
+const QUERY = axisVector(0);
+function seed(chunks) {
+    const db = createTestDb();
+    initMemorySchema(db);
+    chunks.forEach((c, i) => {
+        db.prepare(`INSERT OR IGNORE INTO narratives (id, brane_id, agent_type, role, created_at, status)
+       VALUES (?, 'brane-test', 'claude', 'worker', 0, 'active')`).run(c.nid);
+        upsertChunks(db, [{
+                id: `${c.nid}:${i + 1}`,
+                narrative_id: c.nid,
+                seq: i + 1,
+                content: c.content,
+                time: 1000 + i,
+                vector: vectorWithSimilarity(c.similarity, i + 1),
+            }]);
+    });
+    return db;
+}
+function byNid(results, nid) {
+    return results.find((r) => r.narrative_id === nid);
+}
+describe("searchHybrid — semantic relevance floor", () => {
+    it("drops an unrelated chunk that a single co-occurring term boosted", () => {
+        // The real failure this exists to prevent: a query term appears in an
+        // otherwise-unrelated chunk, earning +0.5, which lifted it above genuinely
+        // relevant matches.
+        const db = seed([
+            { nid: "claude-relevant", content: "the follow flag stays armed after the correction", similarity: 0.92 },
+            { nid: "claude-unrelated", content: "a correction-clock runs slower than the capture-clock", similarity: 0.55 },
+        ]);
+        const results = searchHybrid(db, QUERY, "correction to the follow flag", 10);
+        assert.ok(byNid(results, "claude-relevant"), "the relevant chunk survives");
+        assert.equal(byNid(results, "claude-unrelated"), undefined, "a bare term co-occurring in unrelated text is not enough to qualify");
+    });
+    it("keeps a weakly-similar chunk when every query term matched it", () => {
+        // Exact-keyword evidence outranks similarity: an FTS hit means *all* terms
+        // are present, so a rare identifier still wins even if the embedder shrugs.
+        const db = seed([
+            { nid: "claude-lexical", content: "followFlagRef is disarmed in cancelPendingPins", similarity: 0.2 },
+        ]);
+        const results = searchHybrid(db, QUERY, "followFlagRef cancelPendingPins", 10);
+        const hit = byNid(results, "claude-lexical");
+        assert.ok(hit, "an all-terms match survives a similarity well under the floor");
+        assert.equal(hit.match, "keyword");
+    });
+    it("keeps an exact phrase match regardless of similarity", () => {
+        const db = seed([
+            { nid: "claude-phrase", content: "correctness resting on commit ordering is the real defect", similarity: 0.1 },
+        ]);
+        const results = searchHybrid(db, QUERY, '"correctness resting on commit ordering"', 10);
+        const hit = byNid(results, "claude-phrase");
+        assert.ok(hit, "phrase matches bypass the floor");
+        assert.equal(hit.match, "phrase");
+    });
+    it("keeps a chunk with no keyword overlap when similarity clears the floor", () => {
+        const db = seed([
+            { nid: "claude-semantic", content: "entirely different wording about the same subject", similarity: 0.88 },
+        ]);
+        const results = searchHybrid(db, QUERY, "zzzz yyyy", 10);
+        const hit = byNid(results, "claude-semantic");
+        assert.ok(hit, "pure semantic relevance still qualifies");
+        assert.equal(hit.match, "semantic");
+    });
+    it("never returns empty when nothing clears the floor — marks results weak", () => {
+        // The bound on the floor's risk: a loosely-remembered search degrades to
+        // low-confidence results, never to a blank page.
+        const db = seed([
+            { nid: "claude-loose", content: "vaguely adjacent material with no shared terms", similarity: 0.6 },
+        ]);
+        const results = searchHybrid(db, QUERY, "zzzz yyyy", 10);
+        assert.equal(results.length, 1, "the only candidate is still returned");
+        assert.equal(results[0].match, "weak", "and is labelled as not having qualified");
+    });
+    it("drops weak rows only when a qualified row replaces them", () => {
+        // The precise guarantee: dropping is conditional on something better
+        // surviving. Same weak chunk as above, now with a qualified peer.
+        const weak = { nid: "claude-loose", content: "vaguely adjacent material with no shared terms", similarity: 0.6 };
+        const alone = searchHybrid(seed([weak]), QUERY, "zzzz yyyy", 10);
+        assert.equal(alone.length, 1, "alone, the weak row is kept");
+        const withPeer = searchHybrid(seed([weak, { nid: "claude-strong", content: "clearly on topic", similarity: 0.95 }]), QUERY, "zzzz yyyy", 10);
+        assert.ok(byNid(withPeer, "claude-strong"), "the qualified row is returned");
+        assert.equal(byNid(withPeer, "claude-loose"), undefined, "and displaces the weak one");
+    });
+    it("reports the semantic score separately from the fused rank", () => {
+        // Without this a caller cannot tell "ranked because it means the same
+        // thing" from "ranked because a common word appeared".
+        const db = seed([
+            { nid: "claude-scored", content: "on topic and containing zzzz", similarity: 0.9 },
+        ]);
+        const results = searchHybrid(db, QUERY, "zzzz", 10);
+        const hit = byNid(results, "claude-scored");
+        assert.ok(hit.semantic !== undefined, "semantic score is exposed");
+        assert.ok(Math.abs(hit.semantic - 0.9) < 0.02, `semantic score reflects similarity, not the boost (got ${hit.semantic})`);
+        // `score` is a fused *rank*, not a similarity, so its magnitude is not
+        // comparable to `semantic` — under reciprocal-rank fusion a lone row scores
+        // around 1/61. What has to hold is that the two report different things:
+        // keyword evidence lifts the fused rank without touching the similarity the
+        // floor reads.
+        const withoutKeyword = byNid(searchHybrid(db, QUERY, "qqqq", 10), "claude-scored");
+        assert.ok(hit.score > withoutKeyword.score, `the keyword hit lifts the fused rank (${hit.score} vs ${withoutKeyword.score})`);
+        assert.equal(withoutKeyword.semantic, hit.semantic, "while similarity is unchanged");
+    });
+    it("keeps keyword strength distinguishable instead of clipping it", () => {
+        // The old `min(1, -bm25/10)` normalization clipped: on a real corpus every
+        // match from bm25 -10 through -20 came back as exactly 1.0, so a tight hit
+        // and an incidental all-terms hit in a long document were indistinguishable
+        // by the time the floor saw them. bm25 discounts for document length; that
+        // signal has to survive normalization to be worth anything.
+        const term = "followFlagRef";
+        const filler = "unrelated narration text that goes on at some length. ".repeat(40);
+        const db = seed([
+            { nid: "claude-tight", content: `${term} disarmed`, similarity: 0.1 },
+            { nid: "claude-diffuse", content: `${filler} ${term} ${filler}`, similarity: 0.1 },
+        ]);
+        const results = searchHybrid(db, QUERY, term, 10);
+        const tight = byNid(results, "claude-tight");
+        const diffuse = byNid(results, "claude-diffuse");
+        assert.ok(tight?.lexical !== undefined && diffuse?.lexical !== undefined, "both matches report a keyword strength");
+        assert.ok(tight.lexical > diffuse.lexical, `a tight match scores above a diffuse one (tight=${tight.lexical}, diffuse=${diffuse.lexical})`);
+        assert.ok(tight.lexical < 1, "and neither saturates at the top of the range");
+    });
+    it("gates on similarity alone, not on the boosted score", () => {
+        // A chunk sitting just under the floor still collects keyword credit — one
+        // of the two query terms appears in it — which is why the gate has to read
+        // `semantic` rather than the fused `score`. Under the old additive scoring
+        // the +0.5 term bonus carried such a row past any threshold worth setting;
+        // under rank fusion the coverage multiplier does the same in miniature. The
+        // gate is unchanged by either, which is the point.
+        const justUnder = MIN_SEMANTIC_SCORE - 0.05;
+        const db = seed([
+            { nid: "claude-boosted", content: "unrelated text mentioning zzzz once", similarity: justUnder },
+        ]);
+        const boosted = byNid(searchHybrid(db, QUERY, "zzzz qqqq", 10), "claude-boosted");
+        assert.equal(boosted?.match, "weak", "keyword credit does not promote it past the floor");
+        // ...and it really was credited: the same row, queried without the term it
+        // contains, ranks lower.
+        const plain = byNid(searchHybrid(db, QUERY, "qqqq wwww", 10), "claude-boosted");
+        assert.ok((boosted?.score ?? 0) > (plain?.score ?? 0), `the term hit raised its rank (${boosted?.score} vs ${plain?.score})`);
+    });
+});
+describe("searchHybrid — quoted phrases are requirements", () => {
+    it("excludes a semantically similar row that lacks the phrase", () => {
+        // The leak this closes: FTS enforces the phrase on its own arm, but the
+        // vector arm runs independently and used to union in rows that never
+        // contained it — so quoting ranked rather than restricted.
+        const db = seed([
+            { nid: "claude-has", content: "correctness resting on commit ordering is the defect", similarity: 0.3 },
+            { nid: "claude-similar", content: "the commit ordering here is a bit subtle", similarity: 0.95 },
+        ]);
+        const results = searchHybrid(db, QUERY, '"correctness resting on commit ordering"', 10);
+        assert.ok(byNid(results, "claude-has"), "the row containing the phrase is returned");
+        assert.equal(byNid(results, "claude-similar"), undefined, "high similarity does not substitute for the exact phrase");
+    });
+    it("returns nothing when no row contains the phrase", () => {
+        // Deliberately unlike the relevance floor, which never empties a result
+        // set: quoting is an exact instruction, and zero results is the true answer.
+        const db = seed([
+            { nid: "claude-close", content: "commit ordering matters for correctness", similarity: 0.97 },
+        ]);
+        const results = searchHybrid(db, QUERY, '"correctness resting on commit ordering"', 10);
+        assert.equal(results.length, 0, "no near-misses, no weak fallback");
+    });
+    it("requires every phrase when several are quoted", () => {
+        const db = seed([
+            { nid: "claude-both", content: "the follow flag went stale and cancelPendingPins ran", similarity: 0.2 },
+            { nid: "claude-one", content: "the follow flag went stale, nothing else happened", similarity: 0.9 },
+        ]);
+        const results = searchHybrid(db, QUERY, '"follow flag went stale" "cancelPendingPins ran"', 10);
+        assert.ok(byNid(results, "claude-both"), "a row with both phrases is returned");
+        assert.equal(byNid(results, "claude-one"), undefined, "one of two phrases is not enough");
+    });
+    it("leaves unquoted queries unrestricted", () => {
+        const db = seed([
+            { nid: "claude-semantic", content: "totally different wording", similarity: 0.9 },
+        ]);
+        const results = searchHybrid(db, QUERY, "follow flag went stale", 10);
+        assert.ok(byNid(results, "claude-semantic"), "bare terms still match on meaning alone");
+    });
+});
+//# sourceMappingURL=search-floor.test.js.map