@tpsdev-ai/flair 0.20.1 → 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-check.js

@@ -0,0 +1,167 @@
+/**
+ * version-check.ts — offline-tolerant, cached check of whether the installed
+ * @tpsdev-ai/flair is behind the latest published npm release.
+ *
+ * Motivation (flair#587): a laptop install sat on 0.16.1 through v0.17.0 and
+ * v0.19.0 (P0 security fixes) and v0.18.0 (memory-integrity fix) — `flair
+ * status` reported "✓ all checks passing" the whole time. Nothing anywhere
+ * in the CLI told the operator they were behind. `flair status` and `flair
+ * doctor` both wire this in.
+ *
+ * Non-negotiable design constraints — this must never make status/doctor
+ * WORSE:
+ *   - Offline-tolerant: a failed/timed-out registry fetch falls back to a
+ *     stale cache, or is skipped entirely. NEVER throws, NEVER hangs (short
+ *     fetch timeout).
+ *   - Cached with a TTL so a healthy network doesn't cost a registry round
+ *     trip on every single `flair status`/`flair doctor` invocation.
+ *   - No advisory data — we don't know which release fixed which CVE, so the
+ *     severity heuristic is purely the version GAP (major/minor count), not
+ *     "did this release carry a security fix". See classifyGap().
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseSemverCore } from "./fabric-upgrade.js";
+export const FLAIR_PKG_NAME = "@tpsdev-ai/flair";
+export const DEFAULT_CACHE_PATH = join(homedir(), ".flair", ".version-check-cache.json");
+/** How long a cached "latest" answer is trusted before we re-hit the registry. */
+export const DEFAULT_TTL_MS = 12 * 60 * 60 * 1000; // 12h
+/** Registry fetch timeout — this runs on every status/doctor call, so it must stay short. */
+export const DEFAULT_TIMEOUT_MS = 3000;
+function readCacheFile(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        if (typeof raw?.latest === "string" && typeof raw?.checkedAt === "number") {
+            return { latest: raw.latest, checkedAt: raw.checkedAt };
+        }
+        return null;
+    }
+    catch {
+        // Corrupt/unreadable cache — treat as absent, never throw.
+        return null;
+    }
+}
+function writeCacheFile(path, entry) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(entry), "utf-8");
+    }
+    catch {
+        // Best-effort — a cache-write failure must never surface as a
+        // status/doctor error (e.g. read-only $HOME).
+    }
+}
+async function defaultFetchLatest(timeoutMs) {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${FLAIR_PKG_NAME}/latest`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return typeof data?.version === "string" ? data.version : null;
+    }
+    catch {
+        // Offline, DNS failure, timeout, registry 5xx, bad JSON — all the same:
+        // we couldn't determine "latest" over the network this time.
+        return null;
+    }
+}
+export function defaultVersionCheckDeps() {
+    return {
+        fetchLatest: defaultFetchLatest,
+        cachePath: DEFAULT_CACHE_PATH,
+        ttlMs: DEFAULT_TTL_MS,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        now: () => Date.now(),
+        readCache: readCacheFile,
+        writeCache: writeCacheFile,
+    };
+}
+/**
+ * Resolve the latest published @tpsdev-ai/flair version, preferring a fresh
+ * cache hit over a network round trip, and falling back to a stale cache (or
+ * giving up quietly) when the registry is unreachable. NEVER throws.
+ */
+export async function checkVersion(installed, injected = {}) {
+    const deps = { ...defaultVersionCheckDeps(), ...injected };
+    const nowMs = deps.now();
+    const cached = deps.readCache(deps.cachePath);
+    if (cached && nowMs - cached.checkedAt < deps.ttlMs) {
+        return { installed, latest: cached.latest, source: "cache" };
+    }
+    // Defense-in-depth: the default fetchLatest already catches everything
+    // internally (network error, timeout, non-2xx, bad JSON) and resolves
+    // null rather than rejecting. This try/catch guards the contract even if
+    // a caller-injected fetchLatest misbehaves and throws/rejects instead —
+    // status/doctor must never crash or hang on a version check either way.
+    let fetched = null;
+    try {
+        fetched = await deps.fetchLatest(deps.timeoutMs);
+    }
+    catch {
+        fetched = null;
+    }
+    if (fetched) {
+        deps.writeCache(deps.cachePath, { latest: fetched, checkedAt: nowMs });
+        return { installed, latest: fetched, source: "network" };
+    }
+    // Registry unreachable/timed out — fall back to a stale cache rather than
+    // reporting nothing, but never block or throw trying to get a fresh one.
+    if (cached) {
+        return { installed, latest: cached.latest, source: "cache" };
+    }
+    return { installed, latest: null, source: "unavailable" };
+}
+const NO_GAP = { severity: "none", majorBehind: false, releasesBehind: 0 };
+/**
+ * Classify how far `installed` is behind `latest` using major.minor.patch
+ * math only — we don't have advisory data, so:
+ *   - any major version behind, or ≥2 minor versions behind → "red" (loud;
+ *     heuristic for "you've likely missed a security fix")
+ *   - a single minor version behind, or a patch-only gap → "yellow"
+ *   - equal, ahead, or unparseable → "none"
+ */
+export function classifyGap(installed, latest) {
+    const a = parseSemverCore(installed);
+    const b = parseSemverCore(latest);
+    if (!a || !b)
+        return NO_GAP;
+    const [aMaj, aMin, aPatch] = a;
+    const [bMaj, bMin, bPatch] = b;
+    if (bMaj > aMaj)
+        return { severity: "red", majorBehind: true, releasesBehind: 0 };
+    if (bMaj < aMaj)
+        return NO_GAP; // installed is ahead (e.g. local/pre-release build)
+    if (bMin > aMin) {
+        const releasesBehind = bMin - aMin;
+        return { severity: releasesBehind >= 2 ? "red" : "yellow", majorBehind: false, releasesBehind };
+    }
+    if (bMin < aMin)
+        return NO_GAP; // ahead on minor
+    if (bPatch > aPatch)
+        return { severity: "yellow", majorBehind: false, releasesBehind: bPatch - aPatch };
+    return NO_GAP; // equal, or ahead on patch
+}
+/**
+ * Build the human-readable nudge line for `flair status`/`flair doctor`, or
+ * null when there's nothing worth printing — current, ahead (local/dev
+ * build), or we couldn't determine latest at all (offline with no cache).
+ * Callers own icon/color; this returns plain text plus a severity to color by.
+ */
+export function formatVersionNudge(result) {
+    if (!result.latest)
+        return null;
+    const gap = classifyGap(result.installed, result.latest);
+    if (gap.severity === "none")
+        return null;
+    const countHint = gap.majorBehind
+        ? "major version"
+        : `${gap.releasesBehind} release${gap.releasesBehind === 1 ? "" : "s"}`;
+    const message = `flair ${result.installed} is behind — latest is ${result.latest} (${countHint} behind). ` +
+        `Upgrade: npm i -g ${FLAIR_PKG_NAME}@latest`;
+    return { severity: gap.severity, message };
+}

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.20.1",
+  "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.14",
-    "@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/agent.graphql

@@ -22,6 +22,13 @@ type Agent @table(database: "flair") @export {
 
   createdAt: String!
   updatedAt: String
+  originatorInstanceId: String @indexed  # federation-edge-hardening slice 1 — write-time instance identity,
+                                   # stamped server-side in resources/Agent.ts's post()/put() from
+                                   # resources/instance-identity.ts's localInstanceId(). Nullable (existing rows
+                                   # read null = clean upgrade); preserved (never re-stamped) as the record flows
+                                   # through federation sync merges. See schemas/memory.graphql's Memory.
+                                   # originatorInstanceId for the full contract — same field, same idiom, this is
+                                   # one of the 4 synced tables (Memory/Soul/Agent/Relationship).
 }
 
 # Credential table — auth surfaces for Principals.

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.
 }