@tpsdev-ai/flair 0.27.1 → 0.28.0

package/dist/cli.js

@@ -8873,6 +8873,28 @@ program
     }
 });
 // ─── flair reembed ────────────────────────────────────────────────────────────
+//
+// ROOT-CAUSE GUARD — recall graph correctness (recall-hnsw-graph-heal).
+// `flair reembed` replaces the stored embedding of many rows IN PLACE (it
+// clears embedding/embeddingModel, then re-PUTs through Memory.put()'s regen
+// branch — the same bulk in-place re-embed path resources/migrations/
+// embedding-stamp.ts uses). Historically, an OLDER (pre-fix) Harper's
+// INCREMENTAL HNSW update left stale/asymmetric reverse edges under bulk
+// re-embed, which collapsed prod recall in July. That engine bug is FIXED in
+// the Harper this ships against (5.1.22) — its update path reconstructs the
+// prior vector and does the reverse-edge cleanup the old build skipped — so a
+// bulk re-embed no longer corrupts the graph. DEFENSE-IN-DEPTH RULE (a
+// prudent, version-independent default, not a workaround for a live bug): pair
+// any BULK re-embed with a structural graph REBUILD trigger rather than relying
+// on incremental HNSW updates to converge (today: the
+// `@indexed(type:"HNSW", M:16)` descriptor bump in schemas/memory.graphql,
+// which makes Harper clear + rebuild the graph cleanly from the stored vectors
+// on the next boot — see resources/migrations/graph-heal.ts). Do NOT use
+// resources/MemoryReindex.ts's `_reindex` for graph correctness (it re-PUTs the
+// same vector through the incremental path and rebuilds nothing). If a `flair
+// reembed` run ever materially changes the vector space (e.g. a model swap),
+// follow it with a deploy that trips the structural reindex (bump the HNSW
+// descriptor / restart after a schema change).
 program
     .command("reembed")
     .description("Re-generate embeddings for memories with stale or missing model tags")

package/dist/resources/migrations/embedding-stamp.js

@@ -101,6 +101,29 @@
  * OTHER, not-yet-understood counting artifact; this lets the runner PROVE
  * (via `.get()`, a primary-key lookup — always live, never index-assisted)
  * that a nonzero countPending() result is real before halting on it.
+ *
+ * ROOT-CAUSE GUARD — recall graph correctness (recall-hnsw-graph-heal).
+ * This migration RE-EMBEDS rows in BULK via `PUT /Memory/:id` — it replaces
+ * the stored vector of many rows in place. Historically, an OLDER (pre-fix)
+ * Harper's INCREMENTAL HNSW update left stale/asymmetric reverse edges under
+ * exactly this kind of bulk re-embed (order-dependent), which collapsed prod
+ * recall (p@3 0.25) in July. That engine bug is FIXED in the Harper this ships
+ * against (5.1.22): its index() reconstructs the prior vector from the stored
+ * node and carries the node's real connections into the reverse-edge cleanup
+ * the old build skipped, so a bulk re-embed no longer corrupts the graph.
+ * DEFENSE-IN-DEPTH RULE (a prudent, version-independent default — not a
+ * workaround for a live bug): pair any BULK re-embed with a structural graph
+ * REBUILD trigger rather than relying on incremental HNSW updates to converge
+ * — it keeps recall correct regardless of engine version, closes the rare
+ * decode-failure edge case, and heals a graph already corrupted on disk by an
+ * older engine. Do NOT reach for resources/MemoryReindex.ts's `_reindex` for
+ * graph correctness (it re-PUTs the same vector through the incremental path
+ * and rebuilds nothing). The lever flair uses is a structural schema-descriptor
+ * change: the `@indexed(type:"HNSW", M:16)` bump in schemas/memory.graphql
+ * ships alongside this migration precisely so a graph corrupted under an older
+ * engine is rebuilt on the upgrade boot (observed/ledgered by
+ * resources/migrations/graph-heal.ts). Before enabling any FUTURE bulk
+ * re-embed, ship a structural reindex trigger with it.
  */
 import { databases } from "@harperfast/harper";
 import { getModelId } from "../embeddings-provider.js";

package/dist/resources/migrations/graph-heal.js

@@ -0,0 +1,250 @@
+/**
+ * graph-heal.ts — the recall graph-heal OBSERVABILITY migration.
+ *
+ * WHAT ACTUALLY HEALS: nothing in this file. The heal is entirely
+ * schema-driven — `schemas/memory.graphql`'s `embedding` field now declares
+ * `@indexed(type: "HNSW", M: 16)` (M:16 = Harper's own default, a zero
+ * behavior change). On the first boot after upgrade, Harper structurally
+ * diffs the persisted per-attribute HNSW descriptor (built with NO options on
+ * every pre-this-change install) against the schema and, because
+ * `canonicalizeIndexOptions` does NOT inject defaults (`{type:"HNSW"}` and
+ * `{type:"HNSW",M:16}` are DIFFERENT canonical keys — verified against the
+ * installed @harperfast/harper source, resources/databases.js:
+ * canonicalizeIndexOptions + the `indexOptionsChanged` reset of
+ * `lastIndexedKey` to undefined), clears the graph store and rebuilds it
+ * CLEANLY from the already-correct stored vectors. That rebuild heals the
+ * stale/asymmetric reverse-edge corruption that an OLDER (pre-fix) Harper's
+ * INCREMENTAL HNSW update left on disk during the July bulk embedding-stamp
+ * re-embed — a fresh index of the same vectors finds the true neighbors, the
+ * mangled live graph did not. The corruption is HISTORICAL: the installed
+ * Harper (5.1.22) already fixes that incremental-update path —
+ * HierarchicalNavigableSmallWorld reconstructs the prior vector from the
+ * stored node and carries its real connections into the reverse-edge cleanup
+ * the old build skipped — so current Harper no longer produces it; it just
+ * still persists on disk in stores re-embedded under the old engine. The heal
+ * is therefore version-agnostic: it repairs any such store regardless of the
+ * Harper now running. No re-embed happens — only the graph is rebuilt from the
+ * vectors already on disk.
+ *
+ * WHY THIS MIGRATION EXISTS ANYWAY: the heal is invisible — Harper triggers
+ * it, this code cannot force it, and there is no Harper API to observe it
+ * directly. So this migration's ONLY job is to VERIFY + LEDGER that recall is
+ * healthy after the boot, so the heal is auditable and version-gated (runs
+ * once per upgrade, then the runner's state-file short-circuit — state.ts —
+ * skips it). It touches ZERO rows: riskClass 'derived-only', countPending()
+ * is always 0, run() writes one structural-only OrgEvent and returns
+ * `processed: 0`. The runner (resources/migrations/runner.ts) then records
+ * success in the state file, short-circuiting every subsequent boot at this
+ * version.
+ *
+ * NON-THROWING throughout (invariant II — the runner halts-not-bricks): a
+ * canary that can't run, an index still mid-rebuild, or a ledger-write
+ * failure all degrade to "not verified this boot, retry next boot" or a
+ * best-effort skip — never an exception into the boot path.
+ *
+ * DEFENSE-IN-DEPTH RULE (a prudent, version-independent default — NOT a
+ * workaround for a live bug): any BULK re-embed of the corpus should be paired
+ * with a structural graph REBUILD (a full runIndexing pass) rather than
+ * relying on the engine's incremental `index()` updates to converge. The
+ * installed Harper (5.1.22) DOES converge — its update path is fixed — but the
+ * rebuild keeps recall correct regardless of engine version, closes the rare
+ * decode-failure edge case, and is what heals a store already corrupted on
+ * disk by an older engine. The lever flair uses for that rebuild is a
+ * structural-schema change (the M:16 descriptor bump that ships with this
+ * migration) — see the guard comments in
+ * resources/migrations/embedding-stamp.ts and the `flair reembed` path in
+ * src/cli.ts. Do NOT use resources/MemoryReindex.ts's `_reindex` for graph
+ * correctness — it re-PUTs the same vector through the incremental path and
+ * does not rebuild the graph.
+ */
+import { databases } from "@harperfast/harper";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const GRAPH_HEAL_ID = "graph-heal";
+/** How many rows to scan for a canary that carries a real embedding. Bounded — detect() must stay cheap. */
+const CANARY_SCAN_LIMIT = 8;
+function defaultMemoryTable() {
+    return databases.flair.Memory;
+}
+function defaultOrgEventTable() {
+    return databases.flair.OrgEvent;
+}
+/**
+ * Same "resolve the running package's own version" idiom as
+ * resources/health.ts / resources/migration-boot.ts. Inlined (not imported
+ * from migration-boot) to avoid an import cycle: migration-boot → registry →
+ * graph-heal. Purely informational — it only stamps the ledger detail blob;
+ * a "dev" fallback is harmless.
+ */
+function resolveRunningVersionLocal() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "..", "package.json"), // dist/resources/migrations → root
+            join(here, "..", "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return String(pkg.version);
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return process.env.npm_package_version ?? "dev";
+}
+/**
+ * Pick a canary row that carries a real embedding vector: scan a bounded
+ * handful of rows and `.get()` the first one whose stored `embedding` is a
+ * non-empty array. `.get()` (a primary-key read) always returns the full
+ * record including `embedding`, independent of any `select`/projection
+ * quirk. Returns null when the corpus has no embedded rows at all — a fresh
+ * or empty instance, where there is simply nothing to heal or verify.
+ */
+async function pickCanary(table) {
+    for await (const row of table.search({ select: ["id"], limit: CANARY_SCAN_LIMIT })) {
+        const id = String(row.id ?? "");
+        if (!id)
+            continue;
+        const full = await table.get(id);
+        const emb = full?.embedding;
+        if (Array.isArray(emb) && emb.length > 0)
+            return { id, embedding: emb };
+    }
+    return null;
+}
+/**
+ * The id of the HNSW nearest neighbor of `target` — the exact cosine-sort
+ * query the retrieval path (resources/semantic-retrieval-core.ts) uses,
+ * bounded to rank 1. Throws if the index is unavailable / mid-rebuild; the
+ * caller treats a throw as "not verified this boot".
+ */
+async function topNeighborId(table, target) {
+    for await (const row of table.search({
+        sort: { attribute: "embedding", target, distance: "cosine" },
+        select: ["id"],
+        limit: 1,
+    })) {
+        const id = row.id;
+        return id ? String(id) : null;
+    }
+    return null;
+}
+/**
+ * Canary self-recall: a healthy HNSW graph returns the canary row itself as
+ * the rank-1 neighbor of its OWN stored vector. Cheap, read-only, bounded —
+ * and the cleanest black-box proof the graph rebuilt and is serving (a
+ * mid-rebuild index throws or returns nothing; a store with no embedded rows
+ * has no canary). Never throws (invariant II).
+ */
+async function recallHealthy(table) {
+    try {
+        const canary = await pickCanary(table);
+        if (!canary)
+            return { verified: false, hasData: false };
+        const top = await topNeighborId(table, canary.embedding);
+        return { verified: top === canary.id, hasData: true };
+    }
+    catch {
+        return { verified: false, hasData: true };
+    }
+}
+/** Count rows carrying a real (non-hash-fallback) embedding — the vectors that live in the HNSW graph. Best-effort. */
+async function countEmbeddedVectors(table) {
+    try {
+        let n = 0;
+        for await (const row of table.search({ select: ["embeddingModel"] })) {
+            const m = row.embeddingModel;
+            if (typeof m === "string" && m.length > 0 && m !== "hash-512d")
+                n++;
+        }
+        return n;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Structural-only ledger OrgEvent (Sherlock discipline, same as
+ * resources/migrations/ledger.ts): counts, outcome, version — NEVER a memory
+ * id or content (the canary row's id is deliberately omitted). Written via an
+ * internal (no-HTTP-context) put — resolveAgentAuth(undefined) → internal, the
+ * same trusted server-internal write path the migration ledger already uses.
+ */
+async function writeGraphHealEvent(obs, table) {
+    const countNote = obs.embeddedVectorCount != null
+        ? ` (${obs.embeddedVectorCount} embedded vector${obs.embeddedVectorCount === 1 ? "" : "s"})`
+        : "";
+    await table.put({
+        id: `migration-graph-heal-verified-${obs.at}`,
+        authorId: "flair-migrations",
+        kind: "migration",
+        scope: "full",
+        summary: `HNSW graph-heal: recall ${obs.verified ? "verified healthy" : "unconfirmed"}${countNote}`,
+        detail: JSON.stringify({
+            migrationId: GRAPH_HEAL_ID,
+            verified: obs.verified,
+            canaryRank1: obs.verified,
+            embeddedVectorCount: obs.embeddedVectorCount,
+            runningVersion: obs.runningVersion,
+            verifiedAt: obs.at,
+        }),
+        refId: GRAPH_HEAL_ID,
+        createdAt: obs.at,
+    });
+}
+/**
+ * `getTable`/`getOrgEventTable`/`getVersion`/`now` are injectable so tests can
+ * exercise detect/countPending/run against fakes (matching the mocking style
+ * of embedding-stamp.ts / the unit tests). The real HNSW self-recall + ledger
+ * path is exercised end-to-end in
+ * test/integration/hnsw-graph-heal-e2e.test.ts.
+ */
+export function createGraphHealMigration(getTable = defaultMemoryTable, getOrgEventTable = defaultOrgEventTable, getVersion = resolveRunningVersionLocal, now = () => new Date()) {
+    return {
+        id: GRAPH_HEAL_ID,
+        riskClass: "derived-only",
+        affectsTables: ["Memory"],
+        /**
+         * True only when recall is confirmed healthy AND there is embedded data
+         * to verify — i.e. the graph rebuilt and is serving. Returns false (the
+         * runner marks the migration completed for this boot WITHOUT writing a
+         * success state entry, so detect() runs again next boot) when the index
+         * is still mid-rebuild or the store has nothing embedded yet. This is the
+         * enrollment gate: only a confirmed-healthy boot proceeds to run() +
+         * ledger + the version short-circuit.
+         */
+        async detect() {
+            const { verified } = await recallHealthy(getTable());
+            return verified;
+        },
+        /** Observe-only — never any pending row work. */
+        async countPending() {
+            return 0;
+        },
+        /**
+         * Called exactly once (countPending() is 0 → the runner's batch loop runs
+         * once and breaks). Re-verifies recall for the ledger snapshot, counts
+         * the embedded vectors, writes ONE structural-only OrgEvent, and returns
+         * `processed: 0` so the completion gate (count+marker, derived-only)
+         * passes and the runner records success → short-circuit next boot.
+         */
+        async run(_batchSize) {
+            const table = getTable();
+            const { verified } = await recallHealthy(table);
+            const embeddedVectorCount = await countEmbeddedVectors(table);
+            try {
+                await writeGraphHealEvent({ verified, embeddedVectorCount, runningVersion: getVersion(), at: now().toISOString() }, getOrgEventTable());
+            }
+            catch {
+                // Observability must never brick the runner — a ledger-write failure
+                // is swallowed; the heal itself already happened schema-side.
+            }
+            return { processed: 0, touchedIds: [] };
+        },
+    };
+}

package/dist/resources/migrations/registry.js

@@ -1,10 +1,11 @@
 /**
  * registry.ts — the MigrationRegistry: an ordered list of registered
- * migrations. embedding-stamp always registers; the synthetic CI-only
- * variant registers ONLY when shouldRegisterSyntheticMigration() is true
- * (see synthetic-test-migration.ts's doc for the exact gating rule).
+ * migrations. embedding-stamp and graph-heal always register; the synthetic
+ * CI-only variant registers ONLY when shouldRegisterSyntheticMigration() is
+ * true (see synthetic-test-migration.ts's doc for the exact gating rule).
  */
 import { createEmbeddingStampMigration } from "./embedding-stamp.js";
+import { createGraphHealMigration } from "./graph-heal.js";
 import { createSyntheticTestMigration, shouldRegisterSyntheticMigration } from "./synthetic-test-migration.js";
 export class MigrationRegistry {
     migrations = [];
@@ -23,12 +24,17 @@ export class MigrationRegistry {
     }
 }
 /**
- * Builds the production registry. Always includes embedding-stamp;
- * conditionally includes the CI-only synthetic migration.
+ * Builds the production registry. Always includes embedding-stamp and
+ * graph-heal; conditionally includes the CI-only synthetic migration.
+ *
+ * Order note: graph-heal registers AFTER embedding-stamp so that if a boot
+ * ever runs both, the (verify-only) recall check ledgers the state AFTER any
+ * re-embed work that cycle already applied — never a stale pre-embed reading.
  */
 export function buildRegistry(env = process.env) {
     const registry = new MigrationRegistry();
     registry.register(createEmbeddingStampMigration());
+    registry.register(createGraphHealMigration());
     if (shouldRegisterSyntheticMigration(env)) {
         registry.register(createSyntheticTestMigration());
     }

package/dist/resources/rerank-provider.js

@@ -9,21 +9,62 @@
  *
  * Two inference modes (selected by FLAIR_RERANK_MODEL):
  *
- *  1. "qwen3-reranker-0.6b-q8" (DEFAULT, quality) — Qwen3-Reranker-0.6B is a
- *     causal-LM reranker, NOT a rank-pooling cross-encoder. Its GGUF reports
- *     supportsRanking=false, so node-llama-cpp's createRankingContext() rejects
- *     it. The correct path is generative: format query+doc into the official
- *     instruction prompt ending at the assistant turn, evaluate, and read the
- *     next-token probability of "yes" vs "no":
- *         score = P(yes) / (P(yes) + P(no))
- *     Implemented via seq.controlledEvaluate with generateNext probabilities.
- *     (Validated offline in RERANK-PILOT-RESULTS.md: 4/4 target cases flipped
- *     positive, p@1 6/8→8/8, mean margin 0.028→0.688, ~1.2s / 16 docs on rockit.)
- *
- *  2. "jina-reranker-v2" (latency fallback) — jina-reranker-v2 IS a rank-pooling
+ *  1. "jina-reranker-v2" (DEFAULT, working) — jina-reranker-v2 IS a rank-pooling
  *     cross-encoder; its gpustack GGUF loads via createRankingContext()/rankAll
- *     (supportsRanking=true). ~145ms / 16 docs but weaker (7/8, leaves the
- *     hardest consensus case negative). Selectable where latency is tight.
+ *     (supportsRanking=true). ~145ms / 16 docs in the offline pilot (7/8,
+ *     leaves the hardest consensus case negative — weaker than qwen3's
+ *     generative path in that pilot, but it's the path that actually PRODUCES
+ *     a score inside Harper's process — see #811 / point 2 below).
+ *
+ *  2. "qwen3-reranker-0.6b-q8" (EXPERIMENTAL, quality-if-it-worked) —
+ *     Qwen3-Reranker-0.6B is a causal-LM reranker, NOT a rank-pooling
+ *     cross-encoder. Its GGUF reports supportsRanking=false, so
+ *     createRankingContext() rejects it; the intended path is generative:
+ *     format query+doc into the official instruction prompt ending at the
+ *     assistant turn, evaluate, and read the next-token probability of "yes"
+ *     vs "no": score = P(yes) / (P(yes) + P(no)), via seq.controlledEvaluate
+ *     with generateNext probabilities. Validated OFFLINE, standalone, in
+ *     RERANK-PILOT-RESULTS.md (4/4 target cases flipped positive, p@1
+ *     6/8→8/8, mean margin 0.028→0.688, ~1.2s / 16 docs on rockit) — but
+ *     flair#811 found that INSIDE Harper's resource runtime,
+ *     controlledEvaluate reliably returns empty logits (no decoded output),
+ *     so every generative call throws "generative reranker produced no
+ *     logits" and falls open. Root cause per docs/rerank-provisioning.md's
+ *     "Known limitation": HFE's embedding engine has already initialized a
+ *     separate native llama backend in the same process before this
+ *     provider's own dynamic import runs, and the low-level
+ *     controlledEvaluate + custom-sampler logit readout the generative path
+ *     needs doesn't survive that dual-backend residency (ordinary model
+ *     loading and the jina rank-pooling call both work fine across it — only
+ *     this specific low-level readout is affected). Kept available and
+ *     documented for whoever revisits dual-backend isolation; NOT the
+ *     default until that's fixed.
+ *
+ * Context-budget truncation (flair#811 point 1): real memory content is
+ * routinely far longer than either model's small context window. Every
+ * (query, doc) pair is bounded BEFORE it reaches the engine — a cheap char
+ * pre-cut (`truncateChars`, avoids tokenizing pathological multi-MB content)
+ * followed by an exact token-level cut (`truncateForModel`, uses the loaded
+ * model's own tokenizer — the real guarantee, since char/token ratio varies
+ * a lot across prose/code/CJK/emoji). Budgets are derived from the context
+ * size each mode actually requests (both NUMERIC, not "auto" — node-llama-cpp
+ * grants a numeric contextSize exactly as asked, see GENERATIVE_CONTEXT_SIZE/
+ * RANK_CONTEXT_SIZE below) minus reserved template + query overhead. This
+ * makes the `rankAll`/context-overflow throw effectively unreachable in
+ * normal operation instead of guaranteed on any real-length memory.
+ *
+ * Config re-validated on every use (flair#811 point 3): `ensureInit()` used
+ * to cache `_modelKey`/`_state` permanently on first call — a later change to
+ * FLAIR_RERANK_MODEL (or a transient first-call failure) had NO effect for
+ * the lifetime of the process, since `_state === "ready"` (or `"failed"`)
+ * short-circuited every subsequent call without re-reading env. `needsReinit()`
+ * now compares the currently-resolved model key against what's actually
+ * loaded and re-initializes (disposing old handles first) whenever they
+ * differ, so "configured model X, served model Y" can no longer persist
+ * silently across calls. This is the most likely, directly-fixable
+ * code-level cause of the model-mismatch symptom reported in #811; without a
+ * live process repro we can't rule out an additional contributing factor,
+ * but this closes the gap regardless of the exact prior trigger.
  *
  * Serving path = the same in-process node-llama-cpp the embedding engine ships.
  * No Ollama (no logprobs, no rerank endpoint — verified), no network hop, no
@@ -33,13 +74,15 @@
  * embedding GGUF. See docs/rerank-provisioning.md for download sources.
  */
 import { join } from "node:path";
-// Known reranker models → GGUF filename + inference mode. The default is the
-// quality model (Qwen3 generative). jina is the latency model (rank API).
+// Known reranker models → GGUF filename + inference mode. jina is the DEFAULT
+// (working — see file header, flair#811): its rank-pooling path completes
+// inside Harper. qwen3 is EXPERIMENTAL: its generative path is validated
+// offline but reliably fails open inside Harper today (empty logits).
 const MODELS = {
-    "qwen3-reranker-0.6b-q8": { file: "Qwen3-Reranker-0.6B-q8_0.gguf", mode: "generative" },
     "jina-reranker-v2": { file: "jina-reranker-v2-base.Q8_0.gguf", mode: "rank" },
+    "qwen3-reranker-0.6b-q8": { file: "Qwen3-Reranker-0.6B-q8_0.gguf", mode: "generative" },
 };
-const DEFAULT_MODEL = "qwen3-reranker-0.6b-q8";
+const DEFAULT_MODEL = "jina-reranker-v2";
 // Official Qwen3-Reranker prompt scaffold (generative yes/no judgement).
 const QWEN_PREFIX = '<|im_start|>system\nJudge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or "no".<|im_end|>\n<|im_start|>user\n';
 const QWEN_SUFFIX = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\n";
@@ -47,9 +90,71 @@ const QWEN_INSTRUCT = "Given a web search query, retrieve relevant passages that
 function buildQwenPrompt(q, doc) {
     return `${QWEN_PREFIX}<Instruct>: ${QWEN_INSTRUCT}\n<Query>: ${q}\n<Document>: ${doc}${QWEN_SUFFIX}`;
 }
-// Cap per-document content fed to the reranker. Short atomic notes are the norm;
-// this bounds context blow-up + latency on the occasional huge memory.
-const MAX_DOC_CHARS = 2000;
+// ── Context-budget truncation (flair#811 point 1) ──────────────────────────
+// See the file header for the two-layer rationale. Budgets are derived from
+// the context size each mode actually requests, minus reserved overhead —
+// not a flat guess detached from either number.
+/** Context size requested for the generative (Qwen3) context. NUMERIC (not
+ * "auto"), so node-llama-cpp grants exactly this many tokens — verified
+ * against node-llama-cpp 3.18.1's resolveContextContextSizeOption: a numeric
+ * contextSize is granted as-is (or context creation throws
+ * InsufficientMemoryError); only "auto"/object requests get VRAM-adaptive
+ * shrinking. */
+const GENERATIVE_CONTEXT_SIZE = 1024;
+/** Context size requested for the rank (jina) context — see
+ * createRankingContext() below. Also numeric, same guarantee. */
+const RANK_CONTEXT_SIZE = 2048;
+/** Reserved tokens for the Qwen3 prompt scaffold (QWEN_PREFIX + INSTRUCT +
+ * SUFFIX + <|im_start|>/<|im_end|> special tokens). Rough estimate from the
+ * literal scaffold text is ~130-140 tokens; 180 leaves real headroom above
+ * that estimate rather than sitting right on top of it — we don't have the
+ * actual Qwen3-Reranker tokenizer available to measure exactly (no GGUF in
+ * this worktree), so this errs generous. Belt-and-suspenders: scoreGenerative
+ * also hard-checks the FINAL built prompt against GENERATIVE_CONTEXT_SIZE
+ * and throws (fail-open) rather than proceeding if this margin ever isn't
+ * enough — see there. */
+const GENERATIVE_TEMPLATE_OVERHEAD_TOKENS = 180;
+/** Rank mode's DEFAULT template (no GGUF `chat_template.rerank` metadata) is
+ * just BOS + EOS + SEP + EOS — ~4 tokens. But if the loaded GGUF DOES carry
+ * a custom rerank template (LlamaRankingContext prefers it when present),
+ * that template's literal text adds more; we can't inspect the actual jina
+ * GGUF's metadata from this worktree (no model files here), so this reserves
+ * well above the no-template case. If the real template needs more than
+ * this, `rankAll()` still throws its own clean, caught error (existing
+ * fail-open path) rather than corrupting anything. */
+const RANK_TEMPLATE_OVERHEAD_TOKENS = 64;
+/** Queries are normally a handful of words. Bounding them caps the worst
+ * case so a pathologically long query can never eat the whole doc budget or
+ * overflow the context on its own. */
+const MAX_QUERY_TOKENS = 128;
+/** Per-mode doc token budgets: context size minus template overhead minus
+ * the reserved query budget. This is the number `truncateForModel()` enforces
+ * exactly (via the model's own tokenizer) for candidate document text. */
+const GENERATIVE_DOC_BUDGET_TOKENS = GENERATIVE_CONTEXT_SIZE - GENERATIVE_TEMPLATE_OVERHEAD_TOKENS - MAX_QUERY_TOKENS;
+const RANK_DOC_BUDGET_TOKENS = RANK_CONTEXT_SIZE - RANK_TEMPLATE_OVERHEAD_TOKENS - MAX_QUERY_TOKENS;
+// Cheap CHAR pre-cuts — layer 1 (see file header). Deliberately generous
+// (not a tight token-accurate estimate): their only job is keeping us from
+// ever tokenizing a pathological multi-MB memory blob before layer 2
+// (`truncateForModel`'s exact token-level cut) does the real enforcement.
+const GENERATIVE_DOC_CHAR_PRECUT = 2000;
+const RANK_DOC_CHAR_PRECUT = 5000;
+const QUERY_CHAR_PRECUT = 800;
+/** Pure, trivial char-length cap — layer 1 of truncation. Returns `text`
+ * UNCHANGED (same reference) when already within budget, so callers can
+ * skip unnecessary work; otherwise returns the first `maxChars` characters.
+ * Exported for unit testing (see test/unit/rerank-provider.test.ts). */
+export function truncateChars(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, Math.max(0, maxChars));
+}
+/** Pure, trivial token-array cap — layer 2's core slice. Exported for unit
+ * testing independent of a real tokenizer. */
+export function truncateTokenBudget(tokens, maxTokens) {
+    if (tokens.length <= maxTokens)
+        return tokens;
+    return tokens.slice(0, Math.max(0, maxTokens));
+}
 let _state = "uninitialized";
 let _initError;
 let _warnedOnce = false;
@@ -76,6 +181,31 @@ function resolveModelKey() {
         return requested;
     return DEFAULT_MODEL;
 }
+/**
+ * Decide whether `ensureInit()` needs to (re)run the engine init sequence —
+ * the flair#811 point-3 fix. Pure so the decision matrix is directly
+ * unit-testable without touching the native engine.
+ *
+ * - Never initialized → always init.
+ * - Currently loaded model differs from what's now configured → always
+ *   (re)init, regardless of whether the PREVIOUS attempt was "ready" or
+ *   "failed" — a config change deserves a fresh attempt under the new
+ *   config. This is the fix: the old code short-circuited on `_state ===
+ *   "ready"`/`"failed"` unconditionally, so a later FLAIR_RERANK_MODEL
+ *   change (or a transient first-call failure under a config that was since
+ *   corrected) had NO effect for the life of the process.
+ * - Same model, already "ready" → no-op (don't reload a loaded GGUF).
+ * - Same model, already "failed" → no-op (don't retry-storm a config that's
+ *   still broken; avoids hammering a persistently-unavailable engine on
+ *   every search).
+ */
+export function needsReinit(state, cachedModelKey, requestedModelKey) {
+    if (state === "uninitialized")
+        return true;
+    if (cachedModelKey !== requestedModelKey)
+        return true;
+    return false;
+}
 /** Discover the platform addon binary the same way embeddings-provider.ts does. */
 async function findAddonPath() {
     const { existsSync } = await import("node:fs");
@@ -88,12 +218,19 @@ async function findAddonPath() {
     return undefined;
 }
 async function ensureInit() {
-    if (_state === "ready")
+    const requested = resolveModelKey();
+    if (!needsReinit(_state, _modelKey, requested))
         return;
-    if (_state === "failed")
-        return; // already logged once — don't thrash
+    // Reinitializing under a new config (or first-ever init) — drop any
+    // previously loaded engine handles and let a fresh init attempt warn again
+    // if IT fails too (a new config's failure is a new fact, not a repeat of
+    // the old one).
+    if (_state === "ready")
+        await disposeHandles().catch(() => { });
+    _state = "uninitialized";
+    _warnedOnce = false;
     try {
-        _modelKey = resolveModelKey();
+        _modelKey = requested;
         const spec = MODELS[_modelKey];
         _mode = spec.mode;
         const { existsSync } = await import("node:fs");
@@ -116,7 +253,7 @@ async function ensureInit() {
         _llama = await _nlc.getLlama();
         _model = await _llama.loadModel({ modelPath });
         if (_mode === "generative") {
-            _ctx = await _model.createContext({ contextSize: 1024 });
+            _ctx = await _model.createContext({ contextSize: GENERATIVE_CONTEXT_SIZE });
             _seq = _ctx.getSequence();
             // Resolve yes/no token ids (both case variants — the post-</think>
             // position puts mass on "yes"/"Yes").
@@ -131,9 +268,11 @@ async function ensureInit() {
             if (!_model.fileInsights?.supportsRanking) {
                 throw new Error(`model ${spec.file} does not support ranking (not a rank-pooling cross-encoder)`);
             }
-            // Context must fit query + the longest document (jina concatenates them).
-            // 512 is too small for real memories; 2048 covers MAX_DOC_CHARS + query.
-            _rankCtx = await _model.createRankingContext({ contextSize: 2048 });
+            // Context must fit query + the longest document (jina concatenates
+            // them). 512 is too small for real memories; RANK_CONTEXT_SIZE (2048)
+            // is what RANK_DOC_BUDGET_TOKENS/truncateForModel() are derived from —
+            // see the file header.
+            _rankCtx = await _model.createRankingContext({ contextSize: RANK_CONTEXT_SIZE });
         }
         _state = "ready";
     }
@@ -182,9 +321,51 @@ async function resetSequence() {
     catch { /* ignore */ }
     _seq = _ctx.getSequence();
 }
+/**
+ * Bound `text` to at most `maxTokens` tokens using the loaded model's own
+ * tokenizer — layer 2 of the truncation scheme (see file header). Layer 1's
+ * cheap char pre-cut runs first (`truncateChars`, avoids tokenizing
+ * pathological multi-MB content); if the pre-cut string still tokenizes over
+ * budget (dense code/CJK/emoji content packs more tokens per char than the
+ * pre-cut assumes), the token array itself is cut and detokenized back to
+ * text. This is the actual guarantee: whatever this returns tokenizes to
+ * AT MOST `maxTokens` tokens (specialTokens=false — plain content text, no
+ * markup interpretation), full stop. Not exported/pure (needs `_model`); its
+ * two building blocks (`truncateChars`, `truncateTokenBudget`) are each unit
+ * tested directly.
+ */
+function truncateForModel(text, maxChars, maxTokens) {
+    const precut = truncateChars(text, maxChars);
+    const tokens = _model.tokenize(precut, false);
+    if (tokens.length <= maxTokens)
+        return precut;
+    const bounded = truncateTokenBudget(Array.from(tokens), maxTokens);
+    return _model.detokenize(bounded, false);
+}
 /** Generative yes/no score for one (query, doc) pair. */
 async function scoreGenerative(q, doc) {
-    const tokens = _model.tokenize(buildQwenPrompt(q, doc.slice(0, MAX_DOC_CHARS)), true);
+    // Bound query + doc BEFORE building the prompt (flair#811 point 1) — see
+    // truncateForModel's doc and the file header for the two-layer rationale.
+    // Each is tokenized/bounded independently, then concatenated into the
+    // template; GENERATIVE_TEMPLATE_OVERHEAD_TOKENS' margin absorbs the small
+    // boundary-tokenization variance a separate-then-concatenate cut can
+    // introduce (BPE isn't always compositional across a splice point).
+    const boundedQuery = truncateForModel(q, QUERY_CHAR_PRECUT, MAX_QUERY_TOKENS);
+    const boundedDoc = truncateForModel(doc, GENERATIVE_DOC_CHAR_PRECUT, GENERATIVE_DOC_BUDGET_TOKENS);
+    const tokens = _model.tokenize(buildQwenPrompt(boundedQuery, boundedDoc), true);
+    // Belt-and-suspenders: the per-field bounding above reserves
+    // GENERATIVE_TEMPLATE_OVERHEAD_TOKENS of margin for the template, but a
+    // splice-boundary tokenization surprise is still conceivable. We can't
+    // truncate the COMBINED prompt itself (it would cut the required
+    // assistant-turn suffix the model needs to answer at the right position),
+    // so if it's still over budget here, throw cleanly and let the caller fall
+    // open — better than handing an oversized prompt to controlledEvaluate,
+    // which doesn't throw on overflow the way rankAll does and could silently
+    // context-shift/corrupt instead (a plausible contributor to the "empty
+    // logits" symptom in #811, alongside the documented dual-backend issue).
+    if (tokens.length > GENERATIVE_CONTEXT_SIZE) {
+        throw new Error(`generative reranker prompt (${tokens.length} tokens) exceeds context size (${GENERATIVE_CONTEXT_SIZE}) after truncation`);
+    }
     // Reset the sequence so each pair is scored independently (deterministic) and
     // a prior eval can't poison this one ("Eval has failed" after a bad state).
     await resetSequence();
@@ -228,8 +409,15 @@ export async function rerankScores(query, docs) {
     if (_state !== "ready")
         throw new Error("reranker not ready");
     if (_mode === "rank") {
-        const trimmed = docs.map((d) => String(d ?? "").slice(0, MAX_DOC_CHARS));
-        return runExclusive(() => _rankCtx.rankAll(query, trimmed));
+        // Bound query + every doc BEFORE rankAll (flair#811 point 1) — rankAll
+        // computes ALL documents' token lengths up front and throws "The input
+        // lengths of some of the given documents exceed the context size" if
+        // ANY one exceeds RANK_CONTEXT_SIZE (verified against node-llama-cpp
+        // 3.18.1's LlamaRankingContext.rankAll). truncateForModel makes that
+        // effectively unreachable instead of routine on real memory content.
+        const boundedQuery = truncateForModel(query, QUERY_CHAR_PRECUT, MAX_QUERY_TOKENS);
+        const trimmed = docs.map((d) => truncateForModel(String(d ?? ""), RANK_DOC_CHAR_PRECUT, RANK_DOC_BUDGET_TOKENS));
+        return runExclusive(() => _rankCtx.rankAll(boundedQuery, trimmed));
     }
     // generative — score sequentially under the engine lock (single shared
     // sequence; deterministic). The whole batch holds the lock for one search so

package/docs/rerank-provisioning.md

@@ -13,8 +13,8 @@ turning it on (`FLAIR_RERANK_ENABLED=true`) or running the recall-bench A/B.
 
 | `FLAIR_RERANK_MODEL` | GGUF filename (under `models/`) | Source | Inference mode |
 |---|---|---|---|
-| `qwen3-reranker-0.6b-q8` (default) | `Qwen3-Reranker-0.6B-q8_0.gguf` | `Mungert/Qwen3-Reranker-0.6B-GGUF` (q8_0) | generative yes/no |
-| `jina-reranker-v2` | `jina-reranker-v2-base.Q8_0.gguf` | `gpustack/jina-reranker-v2-base-multilingual-GGUF` (q8_0) | rank-pooling cross-encoder |
+| `jina-reranker-v2` (**default**, working) | `jina-reranker-v2-base.Q8_0.gguf` | `gpustack/jina-reranker-v2-base-multilingual-GGUF` (q8_0) | rank-pooling cross-encoder |
+| `qwen3-reranker-0.6b-q8` (**experimental** — see Known limitation) | `Qwen3-Reranker-0.6B-q8_0.gguf` | `Mungert/Qwen3-Reranker-0.6B-GGUF` (q8_0) | generative yes/no |
 
 Download into `models/` next to the embedding GGUF, e.g.:
 
@@ -36,11 +36,17 @@ vector order — it never blocks or breaks search.
 | Env var | Default | Meaning |
 |---|---|---|
 | `FLAIR_RERANK_ENABLED` | unset (**OFF**) | Master flag. `"true"` to enable. |
-| `FLAIR_RERANK_MODEL` | `qwen3-reranker-0.6b-q8` | Model + inference mode (table above). |
+| `FLAIR_RERANK_MODEL` | `jina-reranker-v2` | Model + inference mode (table above). Re-read on every rerank call — changing it takes effect on the NEXT call (that call pays a one-time model-(re)load cost and can itself fall back to vector order if the load exceeds `FLAIR_RERANK_BUDGET_MS`; subsequent calls run at normal latency). |
 | `FLAIR_RERANK_TOPN` | `50` | Candidate count fed to the reranker; caps the HNSW fetch. |
 | `FLAIR_RERANK_BUDGET_MS` | `2500` | Hard latency budget; exceeded → vector order. |
 | `FLAIR_RERANK_MIN_CANDIDATES` | `2` | Skip rerank below this many candidates. |
 
+Candidate document (and query) text is truncated to a per-model context budget
+before it ever reaches the engine — see `resources/rerank-provider.ts`'s file
+header ("Context-budget truncation"). This is not operator-configurable
+(the budgets are derived from each mode's fixed context size); flagged here
+only so a truncated rerank input isn't a surprise.
+
 ## Why this serving path (not Ollama, not a microservice)
 
 - **In-process node-llama-cpp** is the same engine the embedding engine already
@@ -62,6 +68,34 @@ detects this (`out.length === 0`), throws, and **fails open to vector order** (i
 never writes corrupt scores). Net effect today: with `FLAIR_RERANK_MODEL=qwen3-...`
 the rerank stage cleanly no-ops inside Harper.
 
-The `jina-reranker-v2` rank-API path (`createRankingContext()` / `rankAll`) works
-inside Harper. See the integration PR for the live recall-bench A/B numbers and the
-go/no-go read.
+flair#811 (the live-corpus Phase-1 gate) found the qwen3 path erroring on every
+call in production and root-caused two compounding issues, fixed in that PR:
+
+1. **Context overflow on real documents.** The offline pilot's 16-doc fixture was
+   short synthetic prose; real memory content routinely exceeds either model's
+   small context window (1024 tokens for the generative context, 2048 for the
+   rank context). `resources/rerank-provider.ts` now truncates every (query, doc)
+   pair to a budget derived from each mode's actual context size before it ever
+   reaches the engine (see that file's header). This doesn't fix the dual-backend
+   empty-logits limitation above, but it removes overflow as a SEPARATE, more
+   easily hit failure mode — and may have been a contributing cause of the
+   empty-logits symptom itself (an overflowing `controlledEvaluate` call doesn't
+   throw the way `rankAll` does; it's plausible an oversized prompt silently
+   context-shifted rather than decoding cleanly, though we couldn't confirm
+   this without a live repro).
+2. **Config not re-read after first init.** The provider used to cache which
+   model was loaded PERMANENTLY on first successful (or failed) init — a later
+   change to `FLAIR_RERANK_MODEL` had no effect until the process restarted, so
+   "configured model X, served model Y" could persist silently for the life of
+   the process. Now re-validated on every call (`needsReinit()`); a config
+   change is picked up on the next rerank.
+
+**Given the above, `jina-reranker-v2` is now the DEFAULT model** — its rank-API
+path (`createRankingContext()` / `rankAll`) completes inside Harper. `qwen3` stays
+selectable and documented for whoever revisits the dual-backend isolation
+question; it is not the default until the empty-logits limitation is actually
+fixed (truncation alone doesn't fix it — see point 1 above, it only removes a
+compounding cause).
+
+See the integration PR / flair#811 for the live recall-bench A/B numbers and the
+go/no-go read on `jina-reranker-v2` as the default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
@@ -76,6 +76,9 @@
     "@node-llama-cpp/win-arm64": "3.18.1",
     "@node-llama-cpp/win-x64": "3.18.1"
   },
+  "overrides": {
+    "react-native-fs": "npm:empty-npm-package@1.0.0"
+  },
   "devDependencies": {
     "@playwright/test": "1.59.1",
     "@types/node": "24.11.0",

package/schemas/memory.graphql

@@ -4,7 +4,25 @@ type Memory @table(database: "flair") {
   content: String!
   contentHash: String @indexed
   visibility: String
-  embedding: [Float] @indexed(type: "HNSW")
+  embedding: [Float] @indexed(type: "HNSW", M: 16)   # M:16 is Harper's own HNSW default
+                               # (HierarchicalNavigableSmallWorld M default) — declaring it explicitly is a
+                               # ZERO behavior / graph-quality change. Its ONLY effect is the recall-heal
+                               # trigger (resources/migrations/graph-heal.ts): Harper persists each HNSW
+                               # attribute's option descriptor and, on boot, structurally diffs it against
+                               # the schema (databases.ts canonicalizeIndexOptions — sorts keys, coerces
+                               # numeric strings, but does NOT inject defaults, so `{type:"HNSW"}` and
+                               # `{type:"HNSW",M:16}` are DIFFERENT canonical keys). A store whose descriptor
+                               # was persisted WITHOUT options (every pre-this-change install) therefore sees
+                               # a structural diff on the first boot after upgrade → runIndexing clears the
+                               # graph store and rebuilds it CLEANLY from the already-correct stored vectors
+                               # (lastIndexedKey reset to undefined). This heals graphs left stale by Harper's
+                               # incremental HNSW update after a bulk in-place re-embed (the July embedding-
+                               # stamp re-embed corrupted prod's reverse edges; a fresh index of the SAME
+                               # vectors finds the true neighbors, the incrementally-updated one didn't).
+                               # NO re-embed — the stored vectors are untouched; only the graph is rebuilt.
+                               # Fires once per instance (the descriptor is then persisted to match); brief
+                               # vector-search 503 window during the rebuild (~seconds; BM25/direct keep
+                               # serving). Do NOT remove the `M: 16` — reverting it removes the upgrade heal.
   embeddingModel: String @indexed  # ops-1l18: previously written (resources/Memory.ts stamps every
                                # write) but never DECLARED in this schema, so it was storable but not
                                # queryable — Harper's Table.search({conditions}) rejects a condition on