@tpsdev-ai/flair 0.21.0 → 0.22.0

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

@@ -0,0 +1,317 @@
+// ─── retrieveCandidates() — the pure retrieval core (flair bootstrap-scale-fix) ──
+//
+// Extracted from resources/SemanticSearch.ts's post() (Kern-approved
+// refactor, flair#695). Before this module existed,
+// SemanticSearch.post() was one function entangling auth resolution,
+// rate-limiting, HNSW/BM25 retrieval, post-retrieval filtering, the
+// cross-encoder reranker, AND retrievalCount/lastRetrieved hit-tracking side
+// effects — so the ONLY way for MemoryBootstrap (resources/MemoryBootstrap.ts)
+// to get bounded, HNSW-pushed-down candidates was to duplicate the retrieval
+// logic or trip the side effects (an internal bootstrap call spuriously
+// bumping `retrievalCount` would pollute a ranking signal every other agent's
+// searches read).
+//
+// Boundary (Kern's review, folded into the implementation checklist): this
+// function owns SemanticSearch's retrieval + post-retrieval filtering layers —
+// the HNSW leg query construction (sort/select/conditions/limit), the BM25 +
+// union-RRF hybrid fusion, the per-record temporal/expiry/supersede filters,
+// and the scope.isAllowed() defense-in-depth re-check. It does NOT own: auth
+// resolution, rate-limiting, the reranker, or the retrievalCount/lastRetrieved
+// hit-tracking side effects — those stay in SemanticSearch.post()'s wrapper
+// (resources/SemanticSearch.ts) so an internal caller (bootstrap) never trips
+// them.
+//
+// PURE FUNCTION DISCIPLINE (Kern, non-negotiable): every param below is a
+// primitive/plain-value/function — never `this` or a SemanticSearch instance.
+// A core that took `this` would force mocking (or a later re-refactor) for
+// any second caller; this one is callable standalone, no Resource/HTTP
+// context required beyond the optional `ctx` param (only used for
+// withDetachedTxn's transaction-chain workaround — both SemanticSearch and
+// MemoryBootstrap are Harper Resources with their own `ctx`).
+//
+// Returns results AFTER all filters, sorted best-first by `_score` — bounded
+// ONLY by the `limit` the caller chose to push down (the core never
+// multiplies `limit` internally; any overfetch policy — SemanticSearch's
+// CANDIDATE_MULTIPLIER, rerank-topN widening — is the CALLER's decision, made
+// 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 { withDetachedTxn } from "./table-helpers.js";
+import { wrapUntrusted } from "./content-safety.js";
+import { cosineSimilarity } from "./dedup.js";
+import { compositeScore } from "./scoring.js";
+import { buildBM25, fuseRrfNormalized, SEM_LIMIT } from "./bm25.js";
+import { isAllowedBm25Candidate } from "./bm25-filter.js";
+// Convert HNSW cosine distance (1 - similarity) to similarity score.
+function distanceToSimilarity(distance) {
+    return 1 - distance;
+}
+// Default field selection for every retrieval leg — explicit (no raw
+// `embedding`, so the large vector never enters a result payload or a
+// bootstrap-sized candidate pool) and shared between the HNSW leg and the
+// BM25 corpus fetch so a fused id always resolves to the same record shape
+// regardless of which leg produced it. Includes `summary` (agent-set dense
+// compression, resources/Memory.ts) even though SemanticSearch's own callers
+// don't read it — MemoryBootstrap's collision-surfacing block
+// (resources/collision-lib.ts's SemanticMatchInput) reads `m.summary ||
+// m.content`, so dropping it here would silently regress bootstrap's
+// "Others in the room" surface even though SemanticSearch never asserts on
+// its absence.
+const DEFAULT_SELECT = ["id", "agentId", "content", "contentHash", "visibility", "tags", "durability",
+    "source", "createdAt", "updatedAt", "expiresAt", "retrievalCount", "usageCount", "lastRetrieved",
+    "promotionStatus", "promotedAt", "promotedBy", "archived", "archivedAt", "archivedBy",
+    "parentId", "derivedFrom", "sessionId", "lastReflected", "supersedes", "subject", "summary",
+    "validFrom", "validTo", "_safetyFlags"];
+export async function retrieveCandidates(params) {
+    const { queryEmbedding: qEmb, q, conditions, limit, select = DEFAULT_SELECT, includeSuperseded = false, scoring = "raw", temporalBoost = 1.0, sinceDate = null, asOf, minScore = 0, agentId, isAllowed, hybrid, ctx, } = params;
+    const passesAllowed = (record) => !isAllowed || isAllowed(record);
+    const hnswSelect = [...select, "$distance"];
+    const results = [];
+    if (hybrid) {
+        // ─── BM25 + union-RRF hybrid path ────────────────────────────────────
+        // 1. Semantic candidates via HNSW (unchanged fetch). 2. BM25 lexical pass
+        //    over the SCOPED corpus. 3. SECURITY: the BM25 candidate set is filtered
+        //    by the SAME conditions[] + temporal filters BEFORE fusion (the corpus
+        //    is fetched with those conditions, AND re-checked in-process as
+        //    defense-in-depth) so no other agent's memory is ever scored or fused.
+        //    4. Candidate-union RRF → normalize → feed as rawScore to compositeScore.
+        // ── (a) Semantic candidate records (best-first) ──────────────────────
+        const semRecords = [];
+        const semIds = [];
+        if (qEmb) {
+            const semQuery = {
+                sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
+                select: hnswSelect,
+                limit,
+            };
+            if (conditions.length > 0)
+                semQuery.conditions = conditions;
+            const semResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(semQuery));
+            for await (const record of semResults) {
+                if (record.expiresAt && Date.parse(record.expiresAt) < Date.now())
+                    continue;
+                if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate)
+                    continue;
+                if (asOf && record.validFrom && record.validFrom > asOf)
+                    continue;
+                if (asOf && record.validTo && record.validTo <= asOf)
+                    continue;
+                // A past validTo ALWAYS means the record has been closed out
+                // (server supersede path — Memory.ts closeSupersededRecord — sets
+                // validTo without necessarily setting `archived`). Unconditional, not
+                // gated on `asOf`, so a server-superseded record can't resurface just
+                // because its successor isn't co-present in this result set (the
+                // supersededIds filter further down only catches co-presence). A
+                // record with no validTo, or a future validTo, is unaffected.
+                if (record.validTo && Date.parse(record.validTo) < Date.now())
+                    continue;
+                if (!passesAllowed(record))
+                    continue;
+                semRecords.push(record);
+                semIds.push(record.id);
+            }
+        }
+        // ── (b) BM25 candidate records over the SCOPED corpus ────────────────
+        const corpusQuery = conditions.length > 0
+            ? { conditions, select }
+            : { select };
+        const corpusResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(corpusQuery));
+        const allowedById = new Map();
+        const bm25Docs = [];
+        for await (const record of corpusResults) {
+            // Defense-in-depth: re-check the SAME conditions[] + temporal filters
+            // in-process. Even if a Harper query change ever let an out-of-scope
+            // record through, it is dropped here BEFORE it can be BM25-scored/fused.
+            if (!isAllowedBm25Candidate(record, conditions, { sinceDate, asOf }))
+                continue;
+            if (!passesAllowed(record))
+                continue;
+            allowedById.set(record.id, record);
+            bm25Docs.push({ id: record.id, content: record.content });
+        }
+        // Carry semantic candidates that survived their temporal gate into the
+        // allowed map too (so a fused id always resolves to a record). Semantic
+        // records were fetched with the SAME conditions[], so they're in-scope.
+        for (const r of semRecords) {
+            if (!allowedById.has(r.id)) {
+                const { $distance, ...rest } = r;
+                allowedById.set(r.id, rest);
+            }
+        }
+        // ── (c) BM25 lexical ranking → top SEM_LIMIT (only when q present) ────
+        let bm25Ids = [];
+        if (q) {
+            const bm25 = buildBM25(bm25Docs);
+            const ranked = bm25.rank(String(q));
+            bm25Ids = ranked.filter(r => r.score > 0).slice(0, SEM_LIMIT).map(r => r.id);
+        }
+        // ── (d) No retrieval signal at all → full scoped listing ────────────
+        if (!q && !qEmb) {
+            for (const record of allowedById.values()) {
+                const rawScore = 0;
+                let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+                if (temporalBoost > 1.0)
+                    finalScore *= temporalBoost;
+                const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
+                const source = record.agentId !== agentId ? record.agentId : undefined;
+                results.push({
+                    ...record,
+                    content: isFlagged ? wrapUntrusted(record.content, source) : record.content,
+                    _score: Math.round(finalScore * 1000) / 1000,
+                    _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
+                    _source: source,
+                });
+            }
+        }
+        else {
+            // ── Candidate-union RRF → normalized [0,1] rawScore ────────────────
+            const fused = fuseRrfNormalized(semIds, bm25Ids);
+            for (const [id, rrfRaw] of fused) {
+                const record = allowedById.get(id);
+                if (!record)
+                    continue; // should not happen — union ⊆ allowed
+                const rawScore = rrfRaw; // already normalized to [0,1]
+                let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+                if (temporalBoost > 1.0)
+                    finalScore *= temporalBoost;
+                const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
+                const source = record.agentId !== agentId ? record.agentId : undefined;
+                results.push({
+                    ...record,
+                    content: isFlagged ? wrapUntrusted(record.content, source) : record.content,
+                    _score: Math.round(finalScore * 1000) / 1000,
+                    _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
+                    _source: source,
+                });
+            }
+        }
+    }
+    else if (qEmb) {
+        // ─── HNSW vector search path (legacy, hybrid flag OFF — or a caller
+        // like MemoryBootstrap forcing HNSW-leg-only regardless of the flag) ────
+        const query = {
+            sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
+            select: hnswSelect,
+            limit,
+        };
+        if (conditions.length > 0) {
+            query.conditions = conditions;
+        }
+        const memoryResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(query));
+        for await (const record of memoryResults) {
+            if (record.expiresAt && Date.parse(record.expiresAt) < Date.now())
+                continue;
+            if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate)
+                continue;
+            if (asOf && record.validFrom && record.validFrom > asOf)
+                continue;
+            if (asOf && record.validTo && record.validTo <= asOf)
+                continue;
+            if (record.validTo && Date.parse(record.validTo) < Date.now())
+                continue;
+            if (!passesAllowed(record))
+                continue;
+            let semanticScore;
+            if (record.$distance !== undefined) {
+                semanticScore = distanceToSimilarity(record.$distance);
+            }
+            else {
+                // ─── Harper's cosine-sort query omits $distance for a SINGLETON
+                // post-filter result set (see resources/SemanticSearch.ts's original
+                // writeup of this quirk, and test/integration/
+                // semantic-search-singleton-score.test.ts for the real-Harper
+                // reproduction). Fix: point-lookup the record by id and compute
+                // cosine similarity ourselves from its real stored `embedding`
+                // vector. If the stored embedding is missing/empty, cosineSimilarity
+                // returns 0 — the same safe "no match" the old `?? 1` fallback
+                // produced, never a false-high score.
+                const full = await withDetachedTxn(ctx, () => databases.flair.Memory.get(record.id));
+                const storedEmbedding = Array.isArray(full?.embedding) ? full.embedding : [];
+                semanticScore = cosineSimilarity(qEmb, storedEmbedding);
+            }
+            let keywordHit = false;
+            if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
+                keywordHit = true;
+            }
+            const rawScore = semanticScore + (keywordHit ? 0.05 : 0);
+            let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+            if (temporalBoost > 1.0)
+                finalScore *= temporalBoost;
+            const { $distance, ...rest } = record;
+            const isFlagged = rest._safetyFlags && Array.isArray(rest._safetyFlags) && rest._safetyFlags.length > 0;
+            const source = record.agentId !== agentId ? record.agentId : undefined;
+            results.push({
+                ...rest,
+                content: isFlagged ? wrapUntrusted(rest.content, source) : rest.content,
+                _score: Math.round(finalScore * 1000) / 1000,
+                _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
+                _source: source,
+            });
+        }
+    }
+    else {
+        // ─── No embedding available — keyword-only fallback ──────────────────
+        // Full scan is only used when there's no query embedding (e.g. tag-only
+        // or subject-only searches, or when the embedding engine is unavailable).
+        // Pre-existing, out-of-scope-for-this-PR behavior — MemoryBootstrap never
+        // reaches this branch (it only calls in when it already has a
+        // queryEmbedding).
+        const query = conditions.length > 0 ? { conditions } : {};
+        const memoryResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(query));
+        for await (const record of memoryResults) {
+            if (record.expiresAt && Date.parse(record.expiresAt) < Date.now())
+                continue;
+            if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate)
+                continue;
+            if (asOf && record.validFrom && record.validFrom > asOf)
+                continue;
+            if (asOf && record.validTo && record.validTo <= asOf)
+                continue;
+            if (record.validTo && Date.parse(record.validTo) < Date.now())
+                continue;
+            if (!passesAllowed(record))
+                continue;
+            let keywordHit = false;
+            if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
+                keywordHit = true;
+            }
+            const rawScore = keywordHit ? 0.05 : 0;
+            if (q && rawScore === 0)
+                continue;
+            const { embedding, ...rest } = record;
+            let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, rest);
+            if (temporalBoost > 1.0)
+                finalScore *= temporalBoost;
+            const isFlagged = rest._safetyFlags && Array.isArray(rest._safetyFlags) && rest._safetyFlags.length > 0;
+            const source = record.agentId !== agentId ? record.agentId : undefined;
+            results.push({
+                ...rest,
+                content: isFlagged ? wrapUntrusted(rest.content, source) : rest.content,
+                _score: Math.round(finalScore * 1000) / 1000,
+                _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
+                _source: source,
+            });
+        }
+    }
+    // Build superseded set and filter (unless caller opts in to see full
+    // history) — computed from THIS bounded result set alone (per-set, never
+    // cross-applied — see this PR's supersededIds doc in MemoryBootstrap.ts for
+    // the full caveat: the unconditional past-validTo exclusion above is the
+    // primary supersede guard; this co-presence check is a secondary belt).
+    let filteredResults = results;
+    if (!includeSuperseded) {
+        const supersededIds = new Set();
+        for (const r of results) {
+            if (r.supersedes)
+                supersededIds.add(r.supersedes);
+        }
+        filteredResults = results.filter((r) => !supersededIds.has(r.id));
+    }
+    // Apply minimum score filter
+    if (minScore > 0) {
+        filteredResults = filteredResults.filter((r) => r._score >= minScore);
+    }
+    filteredResults.sort((a, b) => b._score - a._score);
+    return filteredResults;
+}

package/dist/version-handshake.js

@@ -0,0 +1,122 @@
+/**
+ * version-handshake.ts — CLI↔server version handshake (flair#695 §B, the
+ * bare-npm rescue): "Every CLI invocation (cheap, cached ~60s) compares:
+ * CLI version, installed-package version, running-server version. Mismatch
+ * → one-line nudge on stderr: `flair 0.23.0 installed but server is running
+ * 0.22.1 — run: flair restart`. Never blocks the command."
+ *
+ * Mirrors src/version-check.ts's discipline exactly (that module compares
+ * installed-vs-latest-PUBLISHED; this one compares installed-vs-RUNNING):
+ * offline-tolerant, short fetch timeout, cached with a TTL, NEVER throws.
+ * The one behavioral difference from version-check.ts: the cache is keyed
+ * per (rootPath, serverUrl) rather than one global file — a single CLI can
+ * legitimately point at more than one local Flair instance (different
+ * ROOTPATH, or a --target-switched remote), and a mismatch cached for one
+ * must never bleed into a nudge about a different one.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+export const DEFAULT_HANDSHAKE_TTL_MS = 60_000;
+export const DEFAULT_HANDSHAKE_TIMEOUT_MS = 1500; // within the spec's 1-2s budget
+export const DEFAULT_HANDSHAKE_CACHE_DIR = join(homedir(), ".flair", ".version-handshake-cache");
+export function defaultHandshakeDeps() {
+    return {
+        fetchImpl: fetch,
+        cacheDir: DEFAULT_HANDSHAKE_CACHE_DIR,
+        ttlMs: DEFAULT_HANDSHAKE_TTL_MS,
+        timeoutMs: DEFAULT_HANDSHAKE_TIMEOUT_MS,
+        now: () => Date.now(),
+    };
+}
+function cacheFileName(rootPath, serverUrl) {
+    return createHash("sha256").update(`${rootPath}|${serverUrl}`).digest("hex").slice(0, 32) + ".json";
+}
+function cacheFilePath(cacheDir, rootPath, serverUrl) {
+    return join(cacheDir, cacheFileName(rootPath, serverUrl));
+}
+function readCache(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        if (typeof raw?.checkedAt === "number" && (typeof raw?.runningVersion === "string" || raw?.runningVersion === null)) {
+            return { runningVersion: raw.runningVersion, checkedAt: raw.checkedAt };
+        }
+        return null;
+    }
+    catch {
+        return null; // corrupt/unreadable cache — treat as absent, never throw
+    }
+}
+function writeCache(path, entry) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(entry));
+    }
+    catch {
+        // Best-effort — a cache-write failure (e.g. read-only $HOME) must never
+        // surface as a command error.
+    }
+}
+/**
+ * Resolves the running server's version (via the public, unauthenticated
+ * `GET /Health` — reachable even before an agent key exists) and compares
+ * it to `cliVersion`. NEVER throws — every failure mode (offline, timeout,
+ * non-2xx, malformed JSON, cache I/O error) resolves to `source:
+ * "unavailable"` with `mismatch: false`, never an exception or a false
+ * nudge.
+ */
+export async function checkServerHandshake(cliVersion, rootPath, serverUrl, injected = {}) {
+    const deps = { ...defaultHandshakeDeps(), ...injected };
+    const path = cacheFilePath(deps.cacheDir, rootPath, serverUrl);
+    const nowMs = deps.now();
+    const cached = readCache(path);
+    if (cached && nowMs - cached.checkedAt < deps.ttlMs) {
+        return {
+            cliVersion,
+            runningVersion: cached.runningVersion,
+            mismatch: !!cached.runningVersion && cached.runningVersion !== cliVersion,
+            source: "cache",
+        };
+    }
+    let fetched = null;
+    try {
+        const res = await deps.fetchImpl(`${serverUrl.replace(/\/+$/, "")}/Health`, {
+            signal: AbortSignal.timeout(deps.timeoutMs),
+        });
+        if (res.ok) {
+            const body = (await res.json());
+            fetched = typeof body?.version === "string" ? body.version : null;
+        }
+    }
+    catch {
+        fetched = null; // offline, DNS failure, timeout, non-JSON body — all the same: couldn't determine it this time
+    }
+    if (fetched !== null) {
+        writeCache(path, { runningVersion: fetched, checkedAt: nowMs });
+        return { cliVersion, runningVersion: fetched, mismatch: fetched !== cliVersion, source: "network" };
+    }
+    if (cached) {
+        // Server unreachable this time — fall back to a stale cache rather than
+        // reporting nothing.
+        return {
+            cliVersion,
+            runningVersion: cached.runningVersion,
+            mismatch: !!cached.runningVersion && cached.runningVersion !== cliVersion,
+            source: "cache",
+        };
+    }
+    return { cliVersion, runningVersion: null, mismatch: false, source: "unavailable" };
+}
+/**
+ * The one-line stderr nudge, or null when there's nothing worth printing
+ * (no mismatch, or nothing to compare against). Exact wording per the spec:
+ * "flair 0.23.0 installed but server is running 0.22.1 — run: flair restart".
+ */
+export function formatHandshakeNudge(result) {
+    if (!result.mismatch || !result.runningVersion)
+        return null;
+    return `flair ${result.cliVersion} installed but server is running ${result.runningVersion} — run: flair restart`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "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",
   "license": "Apache-2.0",
@@ -31,7 +31,6 @@
     "dist/",
     "schemas/",
     "templates/",
-    "ui/",
     "config.yaml",
     "LICENSE",
     "README.md",
@@ -55,11 +54,11 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.1.15",
-    "@harperfast/oauth": "2.1.0",
+    "@harperfast/harper": "5.1.17",
+    "@harperfast/oauth": "2.2.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
-    "harper-fabric-embeddings": "0.2.3",
+    "harper-fabric-embeddings": "^0.3.0",
     "jose": "6.2.2",
     "js-yaml": "4.1.1",
     "node-llama-cpp": "3.18.1",

package/schemas/event.graphql

@@ -9,4 +9,9 @@ type OrgEvent @table(database: "flair") @export {
   refId: String @indexed
   createdAt: String! @indexed
   expiresAt: String @indexed
+  entities: [String] @indexed  # attention-plane vocabulary strings (flair#675); formalizes a typed,
+                               # vocabulary-consistent entity ref (targetIds stays for actor/target
+                               # ids). Additive/nullable — old rows carry no entities, readers
+                               # tolerate absent (same pattern as Presence.activityUpdatedAt).
+                               # See docs/entity-vocabulary.md.
 }

package/schemas/memory.graphql

@@ -5,6 +5,16 @@ type Memory @table(database: "flair") {
   contentHash: String @indexed
   visibility: String
   embedding: [Float] @indexed(type: "HNSW")
+  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
+                               # an undeclared attribute ("X is not a defined attribute"), which the
+                               # zero-touch migration runner's bounded detect()/countPending()/run()
+                               # queries (resources/migrations/embedding-stamp.ts: `embeddingModel
+                               # not_equal <current>`) need in order to stay O(1)-bounded rather than a
+                               # full-corpus scan on every boot. Purely additive — existing rows already
+                               # carry this value on disk; declaring it queryable changes nothing about
+                               # what's written or how embeddings/prefixes behave (#689's gate untouched).
   tags: [String] @indexed
   durability: String @indexed
   source: String
@@ -13,6 +23,18 @@ type Memory @table(database: "flair") {
   expiresAt: String @indexed
   retrievalCount: Int
   lastRetrieved: String
+  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
+                               # contaminated "retrieval counted as usage" signal root-caused in
+                               # flair#623).
   promotionStatus: String   # null | "pending" | "approved" | "rejected"
   promotedAt: String
   promotedBy: String        # authenticated agentId who approved
@@ -41,11 +63,26 @@ type Memory @table(database: "flair") {
                                # stamped by the ORIGINATING instance itself and preserved (never re-stamped) as the record flows through
                                # sync merges. @indexed for the later sync push-query filter (per-record signature verification and the
                                # classifier org-gate are separate, later slices — not built here).
+  entities: [String] @indexed  # attention-plane vocabulary strings (flair#675). Added in v1 (not v2) per K&S
+                               # verdict on FLAIR-ATTENTION-PLANE.md — gives the future attention query
+                               # uniform index pushdown across Memory/WorkspaceState/OrgEvent instead of a
+                               # partial one. Optional/derivable-on-write (no automatic tagging built here —
+                               # that producer is a follow-up); additive/nullable, existing rows carry no
+                               # entities, readers tolerate absent (same pattern as Presence.activityUpdatedAt).
+                               # See docs/entity-vocabulary.md.
 }
 
 # Explicit entity-to-entity relationships with temporal validity.
 # Enables queries like "who was team lead in Q1?" or "what changed about X on date Y?"
 # Inspired by knowledge graph triples with time-bounded validity windows.
+#
+# attention-plane vocabulary note (flair#675): Relationship gets NO `entities`
+# field. `subject`/`object` already hold free-form entity-reference strings
+# and are already @indexed — they're the vocabulary carrier for this table.
+# (Today they're lowercased on write in resources/Relationship.ts's put() but
+# not yet validated against resources/entity-vocab.ts — wiring that
+# validation, so `subject`/`object` are enforced attention-plane vocabulary
+# strings, is a follow-up, not this foundation slice.)
 type Relationship @table(database: "flair") {
   id: ID @primaryKey
   agentId: String! @indexed        # who created this relationship
@@ -61,6 +98,13 @@ type Relationship @table(database: "flair") {
   originatorInstanceId: String @indexed  # federation-edge-hardening slice 1 — see Memory.originatorInstanceId's doc above
                                     # for the full contract (write-time stamp, nullable, preserved across sync merges).
                                     # Stamped server-side in resources/Relationship.ts's put().
+  provenance: String                # JSON blob (relationship-write-path, folded K&S refinement): SAME shape as
+                                    # Memory.provenance above — { v, verified: { agentId, timestamp }, claimed?: { model } }
+                                    # — via the shared resources/provenance.ts buildProvenance(), never a
+                                    # Relationship-specific format. Nullable by design — pre-existing rows read back
+                                    # provenance = null, unchanged behavior (migration-equivalence gate, same
+                                    # discipline as Memory.usageCount/flair#684). Stamped server-side in
+                                    # resources/Relationship.ts's put(); never client-writable.
 }
 
 type Soul @table(database: "flair") {
@@ -87,6 +131,28 @@ type MemoryGrant @table(database: "flair") @export {
   createdAt: String
 }
 
+# MemoryUsage — the dedup ledger for the usage-feedback signal (flair#683).
+# One row per (agentId, memoryId) contribution: `id` is the deterministic
+# composite key `${agentId}:${memoryId}`, so "has this agent already
+# 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.
+#
+# `attribution` is OPAQUE — never parsed, never fed to an LLM, never rendered
+# — a free-text "what used this" hint the caller supplies, sanitized
+# (control-character-stripped, length-capped) and stored as-is for
+# analytics/audit only. Never trust it as anything more than a label.
+type MemoryUsage @table(database: "flair") {
+  id: ID @primaryKey           # `${agentId}:${memoryId}` — the dedup key itself
+  agentId: String! @indexed    # the contributing (verified) agent — never client-forgeable
+  memoryId: String! @indexed   # the memory this contribution counted toward
+  attribution: String          # opaque/sanitized free-text hint (optional)
+  createdAt: String!
+}
+
 # MemoryCandidate — staged distillations from the FLAIR-NIGHTLY-REM cycle.
 # Per specs/FLAIR-NIGHTLY-REM.md § 7. Slice 1 of ops-2qq adds the schema +
 # `flair rem candidates` listing command. Future slices wire the nightly

package/schemas/schema.graphql

@@ -3,48 +3,10 @@
 
 type Presence @table(database: "flair") @export {
   agentId: ID @primaryKey
-  lastHeartbeatAt: BigInt        # unix ms timestamp
+  lastHeartbeatAt: BigInt        # unix ms timestamp — pure liveness beacon; every heartbeat refreshes it
   currentTask: String            # short human string, e.g. "Reviewing flair#467"
-  activity: String @indexed      # "coding" | "reviewing" | "planning" | "idle"
-}
-
-# ─── Observatory tables ───────────────────────────────────────────────────────
-
-type ObsOffice @table(database: "flair") @export {
-  id: ID @primaryKey        # e.g. "office1"
-  name: String!
-  publicKey: String!        # Ed25519 hex public key for auth verification
-  status: String @indexed   # "online" | "offline" | "degraded"
-  lastSeen: String
-  agentCount: Int
-  createdAt: String!
-  updatedAt: String
-}
-
-type ObsAgentSnapshot @table(database: "flair") @export {
-  id: ID @primaryKey        # "{officeId}:{agentId}"
-  officeId: String! @indexed
-  agentId: String! @indexed
-  name: String
-  role: String
-  type: String              # "agent" | "human"
-  model: String
-  status: String @indexed   # "active" | "idle" | "offline"
-  currentTask: String
-  lastActivity: String
-  lastHeartbeat: String
-  updatedAt: String!
-}
-
-type ObsEventFeed @table(database: "flair") @export {
-  id: ID @primaryKey        # "{officeId}:{eventId}"
-  officeId: String! @indexed
-  kind: String! @indexed
-  authorId: String! @indexed
-  summary: String!
-  refId: String @indexed
-  scope: String @indexed
-  createdAt: String! @indexed
-  receivedAt: String!
-  expiresAt: String @indexed
+  activity: String @indexed      # "coding" | "reviewing" | "planning" | "debugging" | "idle"
+  activityUpdatedAt: BigInt      # unix ms — when activity/currentTask were last ASSERTED (natural-presence); nullable/additive, absent on records written before this feature (readers fall back to lastHeartbeatAt)
+  flairVersion: String           # @tpsdev-ai/flair version serving this heartbeat (flair#639); absent on pre-#639 records
+  harperVersion: String          # @harperfast/harper version serving this heartbeat (flair#639); absent on pre-#639 records
 }

package/schemas/workspace.graphql

@@ -11,4 +11,7 @@ type WorkspaceState @table(database: "flair") @export {
   summary: String
   filesChanged: [String]
   createdAt: String!
+  entities: [String] @indexed  # attention-plane vocabulary strings (flair#675); additive/nullable —
+                               # existing rows carry no entities, readers tolerate absent (same
+                               # pattern as Presence.activityUpdatedAt). See docs/entity-vocabulary.md.
 }