@tpsdev-ai/flair 0.28.0 → 0.30.0

package/dist/resources/migrations/visibility-backfill.js

@@ -0,0 +1,232 @@
+/**
+ * visibility-backfill.ts — backfills the `visibility` field on Memory rows
+ * written before flair#509 (the durability-keyed default-visibility slice),
+ * which never stamped `visibility` at all. riskClass 'derived-only':
+ * `visibility` here is a derived stamp recomputable at any time from
+ * `durability` (which remains on the row, untouched, forever) — never the
+ * only copy of anything (invariant I) — and this migration only ever writes
+ * into a field that is CURRENTLY EMPTY, so the cheapest posture applies:
+ * metadata-only snapshot, no content-hash gate (row-count + stamp
+ * convergence only, same as `embedding-stamp`/`graph-heal`).
+ *
+ * WHY THIS EXISTS: `resources/Memory.ts`'s `defaultVisibilityForDurability`
+ * (flair#509) only stamps `visibility` on a WRITE — a row that has sat
+ * untouched since before that slice shipped has no `visibility` field at
+ * all. `src/cli.ts`'s federation push filter (`isFederationPrivateVisibility`)
+ * excludes only `visibility === "private"` — by design, per
+ * `resources/memory-visibility.ts`'s migration invariant, an ABSENT
+ * `visibility` field is NOT private and must keep syncing exactly as
+ * before (so today's single-org fleet never silently stops replicating
+ * pre-#509 rows). That is correct while every federation peer IS this same
+ * org's own fleet. A cross-organization hub pairing is coming, and at that
+ * point an absent-visibility row that should have been private (a
+ * `standard`/`ephemeral` note, never intended to leave the instance) would
+ * cross an org boundary it never should. This migration closes that gap
+ * proactively: once every row carries an explicit `visibility`, "absent"
+ * becomes the empty set, and the existing filter (unchanged, zero new
+ * behavior in it) is correct as-is for the cross-org case too.
+ *
+ * THE RULE (flair#509 — reused, not reinvented): `permanent`/`persistent`
+ * durability -> `shared`; `standard`/`ephemeral` durability, OR durability
+ * absent/unrecognised -> `private` (fail-safe: never widen access on a row
+ * whose intent this migration cannot actually determine).
+ * `deriveVisibilityFromDurability` below mirrors
+ * `resources/Memory.ts`'s (unexported) `defaultVisibilityForDurability`
+ * byte-for-byte. Deliberately DUPLICATED rather than imported: importing
+ * `resources/Memory.ts` here would drag in its module-top-level
+ * `export class Memory extends (databases as any).flair.Memory` — a class
+ * EXTENDS that only resolves once a live Harper has already registered the
+ * base `Memory` resource, which unit tests (no real Harper; see
+ * `test/unit/migrations-visibility-backfill.test.ts`) cannot satisfy. Same
+ * reasoning, same shape, as `src/cli.ts`'s `isFederationPrivateVisibility`
+ * duplicating `resources/memory-visibility.ts`'s `isPrivateVisibility`
+ * rather than importing it (see that file's comment) — both are one-line,
+ * pure, and load-bearing enough that a comment pointing at the canonical
+ * definition is the safer contract than a shared import with a landmine
+ * behind it. If this rule ever changes, both copies must change together.
+ *
+ * NEVER OVERWRITES an existing `visibility` value — that is an explicit
+ * author decision (their own call, even if it disagrees with what this
+ * migration would have derived). Only rows where `visibility` is
+ * null/undefined are eligible, and `run()` below re-verifies that on a
+ * freshly-read record immediately before writing (the actual enforcement
+ * of "never overwrite" — see the write-gate comment there), independent of
+ * how precisely the candidate-selection query below narrowed things.
+ *
+ * THE CANDIDATE QUERY — why it looks different from `embedding-stamp`'s:
+ * `visibility` is declared in `schemas/memory.graphql` but NOT `@indexed`
+ * (unlike `embeddingModel`, which flair#807 needed indexed for its own
+ * pending query). Every condition against it is therefore already a
+ * full-table-scan filter (`resources/search.ts`'s `filterByType`), whether
+ * or not the comparator is negated — the `not_equals`-forces-an-index-bypass
+ * mechanism `embedding-stamp.ts` depends on (flair#807) is simply moot for
+ * an attribute with no index to be stale in the first place. What DOES
+ * still matter, and is the same lesson flair#807 taught: a strict-equals
+ * filter (`recordValue === value`) never matches a row whose property was
+ * NEVER SET (`recordValue` reads back as `undefined`, and `undefined !==
+ * null`), so `{comparator: "equals", value: null}` alone would silently
+ * miss every truly-absent row — exactly the rows this migration exists to
+ * find. A NEGATED comparator does match them (`undefined !== "private"` is
+ * true), so the pending condition here is `visibility not_equals "private"
+ * AND visibility not_equals "shared"` — no separate `equals: null` leg
+ * needed (unlike `embedding-stamp`, whose write path can leave an
+ * intermediate explicit-null state on a failed HTTP regen; this migration's
+ * write is a single in-process read-modify-write that either fully
+ * succeeds or leaves the row in its exact prior state, so there is no
+ * intermediate state to add a leg for). This exact `not_equal`-covers-
+ * absent-and-null-and-nothing-else-with-the-value-itself semantics is
+ * already relied on, in production, by `resources/memory-read-scope.ts`'s
+ * cross-agent read-scope condition on this SAME field (`visibility !=
+ * 'private'` — "which INCLUDES records missing the field entirely") — this
+ * migration's query is not a new risk, it is the same proven mechanic.
+ *
+ * A garbage third value (something other than "private"/"shared"/absent)
+ * would also match this AND-of-two-`not_equals` condition — Harper's query
+ * algebra has no "attribute is absent" primitive to exclude that case at
+ * the query level. No code path in this codebase ever writes such a value
+ * today (confirmed by grep — every write site either omits `visibility`,
+ * defaults it via `defaultVisibilityForDurability`, or passes an operator-
+ * supplied string straight through with no allowlist, so nothing rules it
+ * out categorically either). The write-gate in `run()` is what actually
+ * protects against this, not the query: a row is only ever written to if a
+ * freshly-read `.get()` shows `visibility` is STILL null/undefined at write
+ * time. A genuinely garbage-valued row would be pulled in as a candidate,
+ * re-checked, found to already carry an explicit (if unexpected) value, and
+ * skipped — untouched, exactly like any other already-set row. Worst case
+ * this makes `countPending()` overcount relative to what `run()` will ever
+ * actually touch, which would show up as a real, visible completion-gate
+ * halt (`resources/migrations/runner.ts`'s "completion gate failed:
+ * rowsRemaining=N") rather than a silent skip or a false success — halt-
+ * don't-brick (invariant II), and worth surfacing loudly if it ever
+ * happens, since a garbage `visibility` value is itself a bug worth seeing.
+ *
+ * THE WRITE PATH — deliberately NOT `embedding-stamp`'s loopback-HTTP
+ * `PUT /Memory/:id` trick. That mechanism exists ONLY because
+ * `embedding-stamp` needs `resources/Memory.ts`'s SUBCLASS override (the
+ * `content.content && !content.embedding` regen branch) to actually fire,
+ * and the raw `databases.flair.Memory` reference (what this migration and
+ * that one both get via their table accessor) resolves to the RAW
+ * underlying table, silently skipping every subclass override — see that
+ * file's module doc for the full, empirically-confirmed mechanism. This
+ * migration needs NO subclass business logic (no dedup, no regen, no
+ * provenance stamping, no rate limiting) — it is a narrow, single-field
+ * patch, which is exactly the shape `resources/table-helpers.ts`'s
+ * `patchRecord` documents and this codebase already uses directly against
+ * the RAW table for the same kind of narrow metadata write:
+ * `resources/auth-middleware.ts`'s `backfillEmbedding()` (patches
+ * `embedding`), `resources/MemoryReflect.ts` and `resources/Memory.ts`
+ * itself (both patch `lastReflected` this exact way). Per that file's own
+ * warning, Harper's raw `.put()` is FULL RECORD REPLACEMENT — a partial
+ * object silently deletes every field not included — so `run()` below
+ * always spreads the freshly-read `existing` record before adding
+ * `visibility`, the same read-modify-write shape `patchRecord` implements
+ * (inlined here rather than calling that helper directly only because
+ * `run()` already needs its own `.get()` for the write-gate check above,
+ * and re-using that same read avoids a second, redundant round-trip).
+ *
+ * NO `recheckPending()`: that hook exists specifically to catch a stale
+ * SECONDARY INDEX diverging from live values (flair#807, `embedding-stamp`
+ * doc above) — a failure mode that requires an index to go stale in the
+ * first place. `visibility` has no index at all (every read here is
+ * already a live-record scan), so there is no analogous divergence for a
+ * safety net to guard against. Same reasoning `graph-heal.ts` (also
+ * `derived-only`, also unindexed-field-adjacent) already applies by also
+ * omitting it.
+ */
+import { databases } from "harper";
+function defaultMemoryTable() {
+    return databases.flair.Memory;
+}
+export const VISIBILITY_BACKFILL_ID = "visibility-backfill";
+/**
+ * flair#509's rule, reused verbatim (see module doc for why this is a
+ * deliberate duplicate of `resources/Memory.ts`'s
+ * `defaultVisibilityForDurability` rather than an import). Total function —
+ * every input maps to exactly one of the two valid outputs, and the
+ * fail-safe branch (`private`) is the ELSE of the allowlist check, so any
+ * absent/null/unrecognised/wrong-typed `durability` value falls into it by
+ * construction, never needs its own case.
+ */
+export function deriveVisibilityFromDurability(durability) {
+    return durability === "permanent" || durability === "persistent" ? "shared" : "private";
+}
+/**
+ * Rows this migration still needs to touch: `visibility` is neither
+ * "private" nor "shared" — see module doc for why this AND-of-two-
+ * `not_equals` correctly matches both a truly-absent property and an
+ * explicit `null`, without a separate `equals: null` leg.
+ */
+function pendingCondition() {
+    return [
+        { attribute: "visibility", comparator: "not_equals", value: "private" },
+        { attribute: "visibility", comparator: "not_equals", value: "shared" },
+    ];
+}
+/**
+ * `getTable` is injectable so unit tests exercise this migration's full
+ * detect/countPending/run logic against an in-memory fake table (matching
+ * `embedding-stamp.ts`'s DI style) — no real Harper needed. Unlike
+ * `embedding-stamp`, there is no separate HTTP mechanism to inject: the
+ * write IS the table's own `.put()`, already covered by the same fake.
+ */
+export function createVisibilityBackfillMigration(getTable = defaultMemoryTable) {
+    return {
+        id: VISIBILITY_BACKFILL_ID,
+        riskClass: "derived-only",
+        affectsTables: ["Memory"],
+        async detect() {
+            const table = getTable();
+            for await (const _row of table.search({ conditions: pendingCondition(), limit: 1 })) {
+                return true;
+            }
+            return false;
+        },
+        async countPending() {
+            const table = getTable();
+            let n = 0;
+            for await (const _row of table.search({ conditions: pendingCondition() }))
+                n++;
+            return n;
+        },
+        async run(batchSize) {
+            const table = getTable();
+            const candidates = [];
+            for await (const row of table.search({ conditions: pendingCondition(), limit: batchSize })) {
+                candidates.push(row);
+            }
+            const touchedIds = [];
+            for (const row of candidates) {
+                const id = String(row.id ?? "");
+                if (!id)
+                    continue;
+                const existing = await table.get(id);
+                if (!existing)
+                    continue; // deleted since the search above — nothing to fix
+                // The write-gate: this is what actually enforces "never overwrite an
+                // existing visibility value", independent of how precisely the
+                // candidate query above narrowed things (see module doc — a
+                // garbage third value would still be pulled in as a candidate).
+                // Re-checks the FRESHLY-READ record, not the (possibly stale)
+                // search-result row, and doubles as the idempotency/concurrent-
+                // writer guard `embedding-stamp.ts` gets from its own analogous
+                // pre-write check.
+                if (existing.visibility !== undefined && existing.visibility !== null)
+                    continue;
+                const derived = deriveVisibilityFromDurability(existing.durability);
+                // Never-widen invariant, asserted, not just tested: the only two
+                // values `deriveVisibilityFromDurability` can ever produce are
+                // "private"/"shared" (see its own doc), so this can never fire
+                // today — it exists to fail loudly (halting this migration via the
+                // runner's mid-batch-throw path, never a silent bad write) if a
+                // future edit to that function ever widens its return type or is
+                // bypassed via a type-unsafe call.
+                if (derived !== "private" && derived !== "shared") {
+                    throw new Error(`visibility-backfill: derived an invalid visibility for row ${id} — refusing to write`);
+                }
+                await table.put({ ...existing, visibility: derived });
+                touchedIds.push(id);
+            }
+            return { processed: touchedIds.length, touchedIds };
+        },
+    };
+}

package/dist/resources/models-dir.js

@@ -0,0 +1,55 @@
+/**
+ * models-dir.ts — the ONE place that decides where model GGUFs live.
+ *
+ * Extracted from embeddings-provider.ts (flair#815) so the reranker
+ * (rerank-provider.ts) can share the exact same resolution WITHOUT importing
+ * embeddings-provider: several unit-isolated tests `mock.module()` the whole
+ * embeddings-provider module (with only the named exports THEY consume), and
+ * bun's module cache is process-wide — so any new cross-module import of
+ * embeddings-provider from another resource makes those mocks incomplete and
+ * kills unrelated test files at module load. This module is tiny, pure
+ * node-stdlib, and never mocked, so both providers (and any future model
+ * consumer) can depend on it safely.
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Resolve the directory model GGUFs live in / download into — shared by the
+ * embedding engine (embeddings-boot.ts's `register()` options) and the
+ * cross-encoder reranker (rerank-provider.ts, flair#815 — it used to hardcode
+ * `<cwd>/models`, silently failing open wherever Harper's cwd wasn't the
+ * models location).
+ *
+ * Resolution order (everything writable, never the read-only package dir):
+ *   1. FLAIR_MODELS_DIR        — explicit operator/docker override.
+ *   2. <ROOTPATH>/models       — Harper's data dir (Flair passes ROOTPATH =
+ *                                ~/.flair/data when it spawns Harper). User-
+ *                                owned and writable even on sudo-global installs.
+ *   3. <cwd>/models            — ONLY if a model already lives there. Backward
+ *                                compat for existing writable installs that
+ *                                downloaded into the package dir before this fix;
+ *                                never used as a download target on fresh installs.
+ *   4. ~/.flair/data/models    — last-resort default when ROOTPATH is unset.
+ *
+ * The chosen dir is always writable, so the embeddings engine can download the
+ * model on first use without hitting EACCES on a root-owned package dir.
+ *
+ * Tested independently (test/unit/embeddings-models-dir.test.ts, via
+ * embeddings-provider's re-export) as the single documented source of truth
+ * for this default.
+ */
+export function resolveModelsDir() {
+    const override = process.env.FLAIR_MODELS_DIR;
+    if (override)
+        return override;
+    const rootPath = process.env.ROOTPATH;
+    if (rootPath)
+        return join(rootPath, "models");
+    // Backward compat: a prior (writable) install may have the model cached in
+    // the package dir. Reuse it rather than re-downloading — but only if present.
+    const cwdModels = join(process.cwd(), "models");
+    if (existsSync(cwdModels))
+        return cwdModels;
+    return join(homedir(), ".flair", "data", "models");
+}

package/dist/resources/record-types.js

@@ -127,8 +127,8 @@
  *
  * `remEligible` — MUST be `false` for every entry in v1 (typed as the
  * literal `false`, not `boolean`, so a stray `true` is a compile error, not
- * just a runtime policy mistake). REM's nightly gather step
- * (specs/FLAIR-NIGHTLY-REM.md §11) is hardcoded to `GET /Memory?agentId=…`
+ * just a runtime policy mistake). REM's nightly gather step (see docs/rem.md)
+ * is hardcoded to `GET /Memory?agentId=…`
  * — single table, single agent, by construction. There is no multi-table
  * distillation input path to opt into yet; the field exists so a future
  * REM generalization doesn't require a breaking schema change to every
@@ -315,6 +315,34 @@ export const RECORD_TYPES = {
         federation: "included",
         mcp: { toolPrefix: "soul", readVerbs: ["get"], writeVerbs: ["store"] },
     },
+    // MemoryCandidate — flair#849. A candidate is an unreviewed draft
+    // distillation staged by the FLAIR-NIGHTLY-REM cycle (docs/rem.md);
+    // `readScope: "owner-only"` (not "open-within-org") is deliberate: a
+    // candidate must not be org-readable before a human/agent reviewer
+    // explicitly promotes or rejects it — this is the standard-review-bar
+    // choice per this file's header doc's review-gate tiering (an
+    // "open-within-org" or "none" entry would additionally require Sherlock's
+    // explicit security sign-off, which this entry does not carry). No
+    // `embedding` — the claim text has no dedicated recall surface (it isn't
+    // Memory.content). No `mcp` — no MCP tool exposes this table today.
+    MemoryCandidate: {
+        table: "MemoryCandidate",
+        ownerField: "agentId",
+        identity: "gated",
+        readScope: "owner-only",
+        attribution: { post: "validate-truthy", put: "validate-truthy" },
+        // No provenance field on the schema (schemas/memory.graphql) — nobody
+        // stamps buildProvenance() for this table.
+        provenance: false,
+        remEligible: false,
+        // Not in Federation.ts's push table map nor src/cli.ts's
+        // runFederationSyncOnce hardcoded list (`["Memory", "Soul", "Agent",
+        // "Relationship"]`) — per this file's header doc's federation section,
+        // a new type's registration must not silently inherit whatever that
+        // filter does or doesn't already exclude, so this is "excluded" by the
+        // same reasoning, not by omission.
+        federation: "excluded",
+    },
 };
 // ─── Composite MCP tools (the second, and only other, reviewed chokepoint) ─
 //

package/dist/resources/rerank-provider.js

@@ -70,10 +70,16 @@
  * 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";
+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
@@ -181,6 +187,20 @@ 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
@@ -234,9 +254,9 @@ async function ensureInit() {
         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).

package/dist/resources/semantic-retrieval-core.js

@@ -36,7 +36,7 @@
 // before calling in). Never exposes which internal leg (BM25+RRF hybrid vs.
 // legacy HNSW-only vs. keyword-only fallback) produced a given result — the
 // output shape is identical regardless of `hybrid`.
-import { databases } from "@harperfast/harper";
+import { databases } from "harper";
 import { withDetachedTxn } from "./table-helpers.js";
 import { wrapUntrusted } from "./content-safety.js";
 import { cosineSimilarity } from "./dedup.js";

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 { databases } from "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";
+}