@tpsdev-ai/flair 0.27.1 → 0.29.0

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.29.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
@@ -26,13 +44,17 @@ type Memory @table(database: "flair") {
   usageCount: Int              # flair#683: verified-USE signal, distinct from retrievalCount (a
                                # search HIT). Additive/nullable — absent reads as 0, existing rows
                                # unaffected. NEVER auto-incremented on search/retrieval; the ONLY
-                               # writer is the dedicated usage-feedback endpoint (resources/
-                               # MemoryUsage.ts), which does a targeted patchRecord increment on
-                               # this field alone (never through Memory.put() — see that
-                               # resource's module doc for why: usage-feedback writes to ANOTHER
-                               # agent's memory, and Memory's ownership check would 403 every
-                               # legit call). Drives usageBoost in resources/scoring.ts, which
-                               # replaces retrievalBoost in compositeScore (retrievalCount was the
+                               # writer is resources/usage-recording.ts's recordUsageContribution()
+                               # — the shared ledger core behind BOTH usage surfaces: POST
+                               # /RecordUsage (resources/RecordUsage.ts) and citation-on-write
+                               # (resources/Memory.ts post()/put() → recordCitations(), which also
+                               # validates each cited id against the writer's read scope,
+                               # flair#775). It does a targeted get-then-put increment on this
+                               # field alone (never through Memory.put() — see RecordUsage.ts's
+                               # module doc for why: usage feedback writes to ANOTHER agent's
+                               # memory, and Memory's ownership check would 403 every legit
+                               # call). Drives usageBoost in resources/scoring.ts, which replaces
+                               # retrievalBoost in compositeScore (retrievalCount was the
                                # contaminated "retrieval counted as usage" signal root-caused in
                                # flair#623).
   promotionStatus: String   # null | "pending" | "approved" | "rejected"
@@ -137,9 +159,12 @@ type MemoryGrant @table(database: "flair") @export {
 # contributed to this memory's usageCount" is a single point-lookup, not a
 # query. This is what makes the anti-gaming dedup rule ("each (agent, memory)
 # pair contributes at most 1 to usageCount" — Sherlock) enforceable: the
-# dedicated endpoint (resources/MemoryUsage.ts) only bumps Memory.usageCount
-# when a NEW row is created here; a repeat call from the same agent for the
-# same memory is a no-op against a row that already exists.
+# shared ledger core (resources/usage-recording.ts's recordUsageContribution(),
+# reached via POST /RecordUsage and via citation-on-write's recordCitations())
+# only bumps Memory.usageCount when a NEW row is created here; a repeat call
+# from the same agent for the same memory is a no-op against a row that
+# already exists. resources/MemoryUsage.ts guards this table's own HTTP
+# surface (it is not the writer).
 #
 # `attribution` is OPAQUE — never parsed, never fed to an LLM, never rendered
 # — a free-text "what used this" hint the caller supplies, sanitized
@@ -154,7 +179,7 @@ type MemoryUsage @table(database: "flair") {
 }
 
 # MemoryCandidate — staged distillations from the FLAIR-NIGHTLY-REM cycle.
-# Per specs/FLAIR-NIGHTLY-REM.md § 7. Slice 1 of ops-2qq adds the schema +
+# Per docs/rem.md. Slice 1 of ops-2qq adds the schema +
 # `flair rem candidates` listing command. Future slices wire the nightly
 # cycle that populates this table and the promote/reject endpoints.
 #