@tpsdev-ai/flair 0.27.1 → 0.29.0

package/dist/resources/rerank-provider.js

@@ -9,37 +9,86 @@
  *
  * 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
  * new auth boundary.
  *
- * GGUF files are NOT committed; they are provisioned into models/ alongside the
- * embedding GGUF. See docs/rerank-provisioning.md for download sources.
+ * GGUF files are NOT committed; they are provisioned into the models dir
+ * alongside the embedding GGUF — resolved via the SAME `resolveModelsDir()`
+ * the embedding engine uses (FLAIR_MODELS_DIR → <ROOTPATH>/models →
+ * <cwd>/models → ~/.flair/data/models; flair#815 — this file used to hardcode
+ * <cwd>/models, so any deployment whose cwd wasn't the models location failed
+ * init and silently fell open to vector order). 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).
+import { resolveModelsDir } from "./models-dir.js";
+// 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 +96,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 +187,45 @@ function resolveModelKey() {
         return requested;
     return DEFAULT_MODEL;
 }
+/**
+ * Absolute path the reranker GGUF is expected at: `<models dir>/<file>`,
+ * where the models dir is the shared `resolveModelsDir()` (models-dir.ts,
+ * same resolution the embedding engine uses) — the single documented source
+ * of truth (FLAIR_MODELS_DIR override, ROOTPATH/models, cwd/models backward
+ * compat, ~/.flair/data/models default).
+ * flair#815: this used to be a hardcoded `<cwd>/models/<file>`, which broke
+ * (fail-open, silently) in any deployment where Harper's cwd wasn't the
+ * models location — including the recall harness's ephemeral Harpers.
+ * Exported for unit testing (see test/unit/rerank-provider.test.ts).
+ */
+export function resolveRerankModelPath(file) {
+    return join(resolveModelsDir(), file);
+}
+/**
+ * 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,18 +238,25 @@ 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");
-        const modelPath = join(process.cwd(), "models", spec.file);
+        const modelPath = resolveRerankModelPath(spec.file);
         if (!existsSync(modelPath)) {
-            throw new Error(`reranker GGUF not found: models/${spec.file} (provision per docs/rerank-provisioning.md)`);
+            throw new Error(`reranker GGUF not found: ${modelPath} (provision per docs/rerank-provisioning.md; set FLAIR_MODELS_DIR to override the models dir)`);
         }
         // Dynamic import — deferred to avoid Harper 5.x VM linker race (same reason
         // embeddings-provider.ts defers harper-fabric-embeddings).
@@ -116,7 +273,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 +288,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 +341,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 +429,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/dist/resources/usage-recording.js

@@ -26,10 +26,28 @@
  * RecordUsage.post()'s loop, parameterized so Memory.ts can drive it from a
  * write body instead of a dedicated POST body. It NEVER reads the ledger for
  * authority — it only writes contributions; `usedMemoryIds` must never enter
- * an access/scope/attribution/dedup decision (flair#744 slice A invariant 3).
+ * an access/scope/attribution/dedup decision (flair#744 slice A invariant 3;
+ * the flair#775 read-scope gate below is the REVERSE direction — the writer's
+ * scope vets the cited ids, the cited ids never widen anything).
+ *
+ * recordCitations() additionally validates each cited id against the
+ * WRITER's own read-scope before crediting (flair#775, a Kern+Sherlock
+ * binding condition on the locked design): citing a memory the writer cannot
+ * read is silently dropped, uniformly with a nonexistent id — never an
+ * error, never a distinguishable code path (an error, or any response/shape
+ * difference, would leak "that id exists but you can't see it").
+ * POST /RecordUsage is DELIBERATELY not scope-gated — its module doc
+ * establishes usage feedback as a cross-agent contract (agent B reports
+ * using agent A's memory regardless of A's visibility setting);
+ * citation-on-write is a separate write surface with a narrower threat
+ * model (the ids ride along on the WRITER's own memory-creation call, so
+ * crediting an unreadable id would let a writer both probe for and boost
+ * memories it cannot see). So the scope gate lives HERE, not retrofitted
+ * onto recordUsageContribution() — do not "unify" the two surfaces.
  */
 import { databases } from "@harperfast/harper";
 import { withDetachedTxn } from "./table-helpers.js";
+import { resolveReadScope } from "./memory-read-scope.js";
 /**
  * Per-call cap on ids credited in one batch — shared by RecordUsage.post()'s
  * validated `memoryIds` body (rejects a batch over the cap with a 400) and
@@ -106,6 +124,17 @@ export async function recordUsageContribution(ctx, agentId, memoryId, attributio
         return; // deleted between the checks above and now — no-op
     await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...fresh, usageCount: (fresh.usageCount ?? 0) + 1 }));
 }
+/**
+ * Default record fetch for recordCitations()'s read-scope gate — the RAW
+ * Memory table (bypassing the Memory RESOURCE class's own read wrapper; the
+ * same trusted-internal-caller pattern recordUsageContribution() uses) so
+ * `scope.isAllowed` runs against the raw stored record. Never throws: a
+ * fetch failure reads as "not found", which the gate silently drops —
+ * identical to a nonexistent id.
+ */
+async function fetchMemoryForScopeCheck(ctx, memoryId) {
+    return withDetachedTxn(ctx, () => databases.flair.Memory.get(memoryId)).catch(() => null);
+}
 /**
  * Batch citation helper — credits every id in `usedMemoryIds` through
  * `recordFn` (the real `recordUsageContribution` by default), one contribution
@@ -129,16 +158,30 @@ export async function recordUsageContribution(ctx, agentId, memoryId, attributio
  *     validated request body, so an oversized list is trimmed rather than
  *     rejected (unlike RecordUsage.post()'s validated `memoryIds`, which
  *     400s over the same cap).
+ *   - Each cited id is validated against the WRITER's read scope before it
+ *     is credited (flair#775 slice 1, K&S binding condition — see the module
+ *     doc above): the scope is resolved ONCE per batch via resolveReadScope
+ *     (the same single source every cross-agent Memory read path uses), then
+ *     each id gets one raw fetch + one in-process `scope.isAllowed` check.
+ *     Not-found and out-of-scope take the SAME silent-drop branch — there is
+ *     no structurally distinguishable code path, error, or response
+ *     difference between them that a caller could use to probe whether
+ *     another agent's private id exists.
  *   - Each id is credited independently: one id throwing never stops the
  *     rest, and the failure is logged server-side, never surfaced to the
  *     caller (the write already committed by the time this runs).
  *
- * `agentId` passed to `recordFn` is ALWAYS `auth.agentId` — the resolved
- * auth context, never anything derived from `usedMemoryIds` or any other
- * caller-supplied input (flair#744 slice A invariant 4: no forging on
- * behalf of another identity).
+ * `agentId` passed to `recordFn` (and to the scope resolution) is ALWAYS
+ * `auth.agentId` — the resolved auth context, never anything derived from
+ * `usedMemoryIds` or any other caller-supplied input (flair#744 slice A
+ * invariant 4: no forging on behalf of another identity).
+ *
+ * `recordFn` / `fetchFn` / `scopeFn` are unit-test injection seams
+ * (test/unit/usage-recording.test.ts) — production callers pass none of
+ * them and always get the real recordUsageContribution / raw-table fetch /
+ * resolveReadScope.
  */
-export async function recordCitations(ctx, auth, usedMemoryIds, now, recordFn = recordUsageContribution) {
+export async function recordCitations(ctx, auth, usedMemoryIds, now, recordFn = recordUsageContribution, fetchFn = fetchMemoryForScopeCheck, scopeFn = resolveReadScope) {
     if (auth.kind !== "agent")
         return;
     if (!Array.isArray(usedMemoryIds) ||
@@ -147,8 +190,31 @@ export async function recordCitations(ctx, auth, usedMemoryIds, now, recordFn =
         return;
     }
     const ids = [...new Set(usedMemoryIds)].slice(0, MAX_USAGE_IDS_PER_CALL);
+    // Resolve the WRITER's read scope ONCE per batch. Fail CLOSED: if scope
+    // resolution itself fails, drop the whole batch rather than credit
+    // unvetted ids — citations are advisory signal, so losing a batch is
+    // strictly safer than crediting an id the writer may not be able to read.
+    let scope;
+    try {
+        scope = await scopeFn(auth.agentId);
+    }
+    catch (err) {
+        console.error("recordCitations: read-scope resolution failed — batch dropped (no-op)", { err });
+        return;
+    }
     for (const id of ids) {
         try {
+            // flair#775 slice 1 read-scope gate. The raw fetch + in-process
+            // predicate is deliberately ONE branch for both "doesn't exist" and
+            // "exists but out of the writer's read scope" — uniform silent drop
+            // (see the module doc). recordUsageContribution's own existence
+            // re-check makes this a second point-lookup of the same record;
+            // accepted — keeping the shared ledger core byte-identical for
+            // RecordUsage.post() is worth two point-lookups on a ≤20-id advisory
+            // batch.
+            const record = await fetchFn(ctx, id);
+            if (!record || !scope.isAllowed(record))
+                continue;
             await recordFn(ctx, auth.agentId, id, undefined, now);
         }
         catch (err) {

package/dist/resources/version.js

@@ -0,0 +1,33 @@
+/**
+ * version.ts — shared runtime-version resolver.
+ *
+ * Reads the running @tpsdev-ai/flair version from the bundled package.json.
+ * `process.env.npm_package_version` is only populated inside `npm run`, so
+ * reading package.json relative to THIS running module is the only way to
+ * report the version of the code that's actually executing.
+ *
+ * Extracted from the duplicated copies in resources/Presence.ts and
+ * resources/AdminInstance.ts (flair#831). Those modules still carry their
+ * own copies for now — migrating them is a follow-up.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+export function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}

package/docs/assets/flair-cross-orchestrator.cast

@@ -3,7 +3,7 @@
 [0.001, "o", "  Flair  \u00b7  same identity, every orchestrator\r\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n"]
 [1.3, "o", "$ # One agent identity. One memory store. Three orchestrators.\r\n"]
 [1.2, "o", "$ flair init --client all --agent flint\r\n"]
-[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude/mcp.json)\r\n"]
+[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude.json)\r\n"]
 [0.18, "o", "  \u001b[32m\u2713\u001b[0m Codex CLI     wired (~/.codex/config.toml)\r\n"]
 [0.18, "o", "  \u001b[32m\u2713\u001b[0m Gemini CLI    wired (~/.gemini/settings.json)\r\n\r\n"]
 [1.0, "o", "  Each MCP client now connects to:  http://127.0.0.1:9926\r\n"]

package/docs/bridges.md

@@ -101,7 +101,7 @@ A few things worth knowing:
 - **`--agent` is required** unless your descriptor maps an `agentId` column. If you forget, `flair bridge import` errors with a one-line operator-pointer hint plus a structured `BridgeRuntimeError` JSON on stderr.
 - **`--dry-run` is your friend.** Validates the descriptor, parses every record, applies the mapping, but skips the PUT. Use it to confirm the count and check a few records before committing.
 - **Output is throttled** to one progress line every 2 seconds (or every 25 records, whichever comes first), so big imports don't flood your terminal.
-- **Errors are structured.** Every error includes `bridge`, `op`, `path`, `record`, `field`, `expected`, `got`, `hint` (per [§10 of the spec](../specs/FLAIR-BRIDGES.md#-10-error-format)). The `hint` is the part you act on; the rest is for an LLM to self-correct without operator help.
+- **Errors are structured.** Every error includes `bridge`, `op`, `path`, `record`, `field`, `expected`, `got`, `hint` (per [Error format](#error-format) below). The `hint` is the part you act on; the rest is for an LLM to self-correct without operator help.
 
 ## Shape A — Declarative YAML
 
@@ -286,6 +286,6 @@ If you want an agent to write a bridge for you, here's the one-shot prompt:
 
 That's the bar. If an agent can't ship a working bridge from this doc plus the scaffold, the doc is the bug.
 
-## Full spec
+## Authority
 
-The authoritative contract is in [`specs/FLAIR-BRIDGES.md`](../specs/FLAIR-BRIDGES.md). This doc is the user-facing view; the spec covers edge cases, future extensions, and design rationale.
+This document is the authoritative contract for the bridge plugin system: the record schema, both plugin shapes, discovery, distribution, trust, round-trip testing, and the error format are all specified above. There is no separate design spec — the original planning document was retired once the system shipped, and its design-rationale and milestone-scoping sections are preserved in git history rather than maintained here.

package/docs/mcp-clients.md

@@ -38,9 +38,11 @@ Flair runs as a local server at `http://127.0.0.1:19926` by default. The MCP ser
 
 Pick whichever you use. The MCP server is the same package; only the config syntax differs.
 
+> **Pin the version.** The snippets below use the bare package name for readability. `flair init` wires clients to a **pinned** spec (`@tpsdev-ai/flair-mcp@<version>`) on purpose: an unpinned reference re-resolves to whatever is currently published on every agent session, so any future publish reaches your machine silently. If you wire by hand, append the version you intend to run — `@tpsdev-ai/flair-mcp@0.28.0` — and bump it deliberately. `flair init` is the easier path and does this for you.
+
 ### Claude Code
 
-The canonical approach is the `claude mcp add` CLI (writes to `~/.claude/mcp.json`):
+The canonical approach is the `claude mcp add` CLI (writes to `~/.claude.json`):
 
 ```bash
 claude mcp add flair --scope user \

package/docs/n8n.md

@@ -93,7 +93,7 @@ If any of those don't hold, use Flair's CLI / SDK clients (which support per-age
 
 ## Get By Tag — coming soon
 
-The Flair Search node currently exposes Semantic Search and Get By Subject. **Get By Tag** is deferred until `flair-client.memory.list` exposes a `tags` filter (tracked in the [n8n-node spec](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) §6). Workaround for now: use Semantic Search and let the model filter results by tags in the response.
+The Flair Search node currently exposes Semantic Search and Get By Subject. **Get By Tag** is deferred until `flair-client.memory.list` exposes a `tags` filter. Workaround for now: use Semantic Search and let the model filter results by tags in the response.
 
 ## Worked examples
 
@@ -117,6 +117,5 @@ Same Flair instance, same memories, different surfaces.
 
 ## See also
 
-- [Spec — `@tpsdev-ai/n8n-nodes-flair`](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) — implementation plan, design decisions, anti-patterns
 - [Bridges](./bridges.md) — how Flair memories flow between hosts and instances
 - [Federation](./federation.md) — hub-and-spoke replication

package/docs/notes/rem-ux.md

@@ -1,6 +1,6 @@
 # REM UX — trigger model, attach semantics, review loop
 
-> Design note accompanying REM slice 2 (#707). Describes the intended user experience of in-process distillation so the CLI/docs surfaces stay coherent as the feature grows. Parent spec: `specs/FLAIR-NIGHTLY-REM.md`; slice spec: `specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md`.
+> Design note accompanying REM slice 2 (#707). Describes the intended user experience of in-process distillation so the CLI/docs surfaces stay coherent as the feature grows. See [`docs/rem.md`](../rem.md) for the REM configuration and command reference.
 
 ## Triggers — three, nothing implicit
 

package/docs/rem.md

@@ -2,6 +2,8 @@
 
 REM (Reflect · Extract · Merge) is Flair's memory-curation cycle: it reads an agent's recent memories, distills them into candidate insights, and stages those candidates for explicit human/agent review — nothing is ever auto-promoted. `flair rem rapid` runs it on demand; `flair rem nightly enable` runs it on a schedule. See [`docs/notes/rem-ux.md`](notes/rem-ux.md) for the full trigger model, locality guarantees, and the review-loop UX this page's commands feed into.
 
+> **⚠️ Prerequisite: a configured generative backend.** All REM commands (`rapid`, `nightly`, `candidates`, `promote`, `reject`) require Harper's `models.generate()` to be wired — without it, REM calls fail with `Reflection error: No generative backend configured`. Set up a backend first (see [Configuration](#configuration) below) before running any REM command. The fastest path is Ollama with a non-thinking model, which needs zero credentials and keeps all traffic local.
+
 ## Configuration
 
 Distillation runs **server-side**, via Harper's model-access API (`models.generate()`). Flair ships zero provider code — which backend answers a REM call is entirely a Harper `models:` configuration decision.