@tpsdev-ai/flair 0.20.1 → 0.21.0

package/dist/resources/federation-nonce-store.js

@@ -0,0 +1,195 @@
+/**
+ * federation-nonce-store.ts — persistent backing for the federation
+ * anti-replay NonceStore (federation-edge-hardening slice 4).
+ *
+ * The gap: `federationNonceStore` in Federation.ts was a bare in-memory Map
+ * (`createNonceStore()` in federation-crypto.ts). On process restart it's
+ * wiped, so a signed federation request captured within its ±30s freshness
+ * window (verifyBodySignatureFresh) could be replayed once, post-restart.
+ * This module closes that window by backing the SAME `NonceStore` interface
+ * with the `Nonce` Harper table, while keeping every method synchronous —
+ * `verifyBodySignatureFresh` and its 2 call sites in Federation.ts are
+ * UNCHANGED (they still call `.has()` / `.set()` / `.evict()` with no
+ * `await`), so the entire existing federation-crypto-replay test suite
+ * (all synchronous assertions) keeps working unmodified.
+ *
+ * How the sync interface stays sync against an inherently-async DB API:
+ *   - `has()` / `evict()` read/mutate an in-memory Map (via the existing
+ *     `createNonceStore()`), exactly as before — no DB round trip.
+ *   - `set()` updates that same in-memory Map synchronously (so replay
+ *     detection within THIS process's lifetime is unchanged), and fires an
+ *     async `Nonce.put()` in the background (not awaited) to persist the
+ *     nonce for the NEXT restart. A failed/slow persist never blocks or
+ *     fails request handling — see the perf/durability tradeoff note below.
+ *   - `hydrate()` is the new piece: an explicit async step that loads
+ *     not-yet-expired rows from the `Nonce` table into the in-memory Map.
+ *     Call it once, on startup, BEFORE the store starts guarding live
+ *     traffic — that's what makes a nonce recorded by the PREVIOUS process
+ *     visible to a FRESH store instance after a restart (the whole point).
+ *
+ * Known tradeoff (flagged, not fixed here — would require making NonceStore
+ * async, which ripples into ~40 synchronous call sites across
+ * federation-crypto-replay.test.ts + federation-sync-e2e.test.ts):
+ * `set()`'s persistence is fire-and-forget. A crash in the narrow gap
+ * between "response sent" and "async put() resolved" can still lose that
+ * one nonce — narrowing the replay window to that gap, not eliminating it
+ * outright. Defense-in-depth: the ±30s freshness check + signature
+ * verification are still the primary guards; this closes the common case
+ * (graceful restart / redeploy), not the crash-mid-request edge case.
+ */
+import { createNonceStore } from "./federation-crypto.js";
+/** 2x the standard 30s freshness window — matches the in-memory `evict()` cutoff already used by verifyBodySignatureFresh. */
+export const DEFAULT_RETENTION_MS = 60_000;
+async function resolveDb(opts, cache) {
+    if (opts.db)
+        return opts.db;
+    if (!cache.db) {
+        cache.db = import("@harperfast/harper").then((h) => h.databases);
+    }
+    return cache.db;
+}
+/**
+ * Create a `NonceStore` backed by the `Nonce` Harper table.
+ *
+ * Wraps the existing in-memory `createNonceStore()` (unchanged behavior for
+ * `has()`/`set()`/`evict()` within this process) and adds:
+ *   - background persistence of newly-set nonces (`set()`)
+ *   - an explicit `hydrate()` to reload previously-persisted nonces (used
+ *     at startup, and by tests simulating a restart with a fresh instance)
+ */
+export function createPersistentNonceStore(opts = {}) {
+    const memory = createNonceStore();
+    const dbCache = {};
+    return {
+        has(key) {
+            return memory.has(key);
+        },
+        evict(olderThan) {
+            memory.evict(olderThan);
+        },
+        set(key, value) {
+            memory.set(key, value);
+            // Fire-and-forget persistence — see module header for the tradeoff.
+            void (async () => {
+                try {
+                    const db = await resolveDb(opts, dbCache);
+                    await db.flair.Nonce.put({ id: key, seenAt: value });
+                }
+                catch (err) {
+                    console.error("[federation-nonce-store] failed to persist nonce (in-memory record already made — this process's replay guard is unaffected):", err?.message ?? err);
+                }
+            })();
+        },
+        async hydrate(hydrateOpts) {
+            const retentionMs = hydrateOpts?.retentionMs ?? DEFAULT_RETENTION_MS;
+            const now = hydrateOpts?.now ?? Date.now();
+            const cutoff = now - retentionMs;
+            try {
+                const db = await resolveDb(opts, dbCache);
+                for await (const row of db.flair.Nonce.search()) {
+                    if (row?.id != null && typeof row.seenAt === "number" && row.seenAt >= cutoff) {
+                        memory.set(String(row.id), row.seenAt);
+                    }
+                }
+            }
+            catch (err) {
+                console.error("[federation-nonce-store] failed to hydrate from Nonce table (starting with an empty replay guard):", err?.message ?? err);
+            }
+        },
+    };
+}
+// ─── Eviction sweep — periodic Nonce table hygiene ─────────────────────────
+//
+// Mirrors federation-cleanup.ts's 5-min setInterval hub-pattern. Decoupled
+// from the in-memory `evict()` above (which runs per-request and only trims
+// the local Map): this sweep deletes rows from the `Nonce` TABLE itself so
+// it doesn't grow unbounded across restarts. No native TTL in this repo —
+// same app-managed-sweep idiom as PairingToken cleanup.
+//
+// Runs on every instance (hub AND spoke) — unlike PairingToken cleanup
+// (hub-only, since only hubs issue pairing tokens), both FederationPair and
+// FederationSync can be the RECEIVING side of a signed request on either
+// role, so both roles accumulate rows in the Nonce table and both need the
+// sweep.
+const NONCE_CLEANUP_INTERVAL_MS = 300_000; // 5 minutes
+let nonceCleanupTimer = null;
+/**
+ * Core sweep logic — exposed for unit testing. Deletes `Nonce` rows with
+ * `seenAt` older than `retentionMs` (default: 2x the 30s freshness window).
+ */
+export async function runNonceCleanupTick(opts = {}) {
+    let db;
+    if (opts.db) {
+        db = opts.db;
+    }
+    else {
+        const harper = await import("@harperfast/harper");
+        db = harper.databases;
+    }
+    const retentionMs = opts.retentionMs ?? DEFAULT_RETENTION_MS;
+    const now = opts.now ?? Date.now();
+    const cutoff = now - retentionMs;
+    const toDelete = [];
+    let scanned = 0;
+    try {
+        for await (const row of db.flair.Nonce.search()) {
+            scanned++;
+            if (typeof row?.seenAt === "number" && row.seenAt < cutoff) {
+                toDelete.push(row.id);
+            }
+        }
+    }
+    catch (err) {
+        console.error("[federation-nonce-store] failed to query Nonce records:", err?.message ?? err);
+        return { deleted: 0, scanned: 0 };
+    }
+    let deleted = 0;
+    for (const id of toDelete) {
+        try {
+            await db.flair.Nonce.delete(id);
+            deleted++;
+        }
+        catch (err) {
+            console.error("[federation-nonce-store] failed to delete expired nonce:", err?.message ?? err);
+        }
+    }
+    return { deleted, scanned };
+}
+/**
+ * Initialise the periodic Nonce-table eviction sweep (5-min cadence).
+ *
+ * In test environments, callers pass a mock `db` via `opts` so this module
+ * never imports @harperfast/harper at the top level (mirrors
+ * federation-cleanup.ts's `initFederationCleanup`).
+ */
+export async function initNonceStoreCleanup(opts) {
+    const immediate = opts?.immediateTick ?? true;
+    let db;
+    if (opts?.db) {
+        db = opts.db;
+    }
+    else {
+        try {
+            const harper = await import("@harperfast/harper");
+            db = harper.databases;
+        }
+        catch (err) {
+            console.error("[federation-nonce-store] failed to load @harperfast/harper:", err?.message ?? err);
+            return;
+        }
+    }
+    const retentionMs = opts?.retentionMs ?? DEFAULT_RETENTION_MS;
+    console.log("[federation-nonce-store] starting nonce eviction sweep (5-min cadence)");
+    if (nonceCleanupTimer)
+        clearInterval(nonceCleanupTimer);
+    nonceCleanupTimer = setInterval(() => {
+        runNonceCleanupTick({ db, retentionMs }).catch((err) => {
+            console.error("[federation-nonce-store] cleanup tick error:", err?.message ?? err);
+        });
+    }, NONCE_CLEANUP_INTERVAL_MS);
+    if (immediate) {
+        runNonceCleanupTick({ db, retentionMs }).catch((err) => {
+            console.error("[federation-nonce-store] initial cleanup tick error:", err?.message ?? err);
+        });
+    }
+}

package/dist/resources/instance-identity.js

@@ -0,0 +1,53 @@
+import { databases } from "@harperfast/harper";
+/**
+ * ─── Local instance identity (federation-edge-hardening slice 1) ────────────
+ *
+ * The write-time `originatorInstanceId` stamp (Memory.ts/Soul.ts/Agent.ts/
+ * Relationship.ts post()/put()) needs to know THIS instance's own federation
+ * identity — the same `id` FederationInstance.get() (resources/Federation.ts)
+ * finds-or-creates on first boot and persists in the `Instance` table
+ * (schemas/federation.graphql). Exactly one row is expected in a given
+ * instance's own Instance table — that row IS this instance; other instances
+ * it has paired with live in the separate `Peer` table, never here.
+ *
+ * Deliberately READ-ONLY: this module never creates an Instance row — that
+ * first-boot bootstrap (keypair generation + keystore write) stays
+ * FederationInstance.get()'s job (resources/Federation.ts). If no Instance
+ * row exists yet (a fresh, never-federated instance, or a unit-test
+ * environment with no Instance table at all), localInstanceId() resolves to
+ * null and callers stamp nothing — originatorInstanceId is nullable by
+ * design (schemas/memory.graphql), and a null tag reads as "pre-tag /
+ * local-origin by default" per the federation-edge-hardening design.
+ *
+ * Cached at module scope after the FIRST successful resolution — a write
+ * must not pay a DB lookup every call. An unresolved (null) result is NOT
+ * cached, since that state can legitimately change later (federation gets
+ * bootstrapped after this process already started serving writes) and the
+ * cost of re-checking only applies to instances that have never federated.
+ */
+let cachedInstanceId = null;
+export async function localInstanceId() {
+    if (cachedInstanceId)
+        return cachedInstanceId;
+    try {
+        for await (const row of databases.flair.Instance.search()) {
+            if (row?.id) {
+                cachedInstanceId = row.id;
+            }
+            break; // exactly one row expected — this instance's own identity
+        }
+    }
+    catch {
+        // Instance table not present (test env / not yet migrated) — no local id.
+    }
+    return cachedInstanceId;
+}
+/**
+ * Test-only: force re-resolution on the next localInstanceId() call. The
+ * module-level cache otherwise persists across test files that share the
+ * same `bun test` process (same collision class documented in
+ * memory-integrity.test.ts re: the Memory class singleton).
+ */
+export function _resetLocalInstanceIdCacheForTests() {
+    cachedInstanceId = null;
+}

package/dist/resources/memory-bootstrap-lib.js

@@ -38,5 +38,5 @@ export function formatTeamLine(teammateIds) {
     const plural = teammateIds.length === 1 ? "agent shares" : "agents share";
     return (`${teammateIds.length} other ${plural} this Flair office (${wrapUntrusted(teammateIds.join(", "))}). ` +
         `Before deep-diving an unfamiliar problem, search their memories for related work — ` +
-        `\`memory_search\` covers any agent you hold a search grant from.`);
+        `\`memory_search\` covers any agent's non-private memories on this instance (open-within-org read; no grant required).`);
 }

package/dist/resources/memory-read-scope.js

@@ -1,6 +1,7 @@
 import { databases } from "@harperfast/harper";
+import { PRIVATE_VISIBILITY, isPrivateVisibility } from "./memory-visibility.js";
 /**
- * ─── Centralized Memory read-scoping (ops-2dm3 Layer 1) ─────────────────────
+ * ─── Centralized Memory read-scoping (the original grant-gated read model → within-org-read-open) ─
  *
  * The SINGLE source every cross-agent Memory read path resolves its scope
  * through: Memory.search()/Memory.get() (resources/Memory.ts), SemanticSearch
@@ -9,40 +10,49 @@ import { databases } from "@harperfast/harper";
  * existed, SemanticSearch had its OWN inline grant-resolution + a
  * `visibility === "office"` global OR-clause that leaked ANY authenticated
  * agent's read of ANY other agent's memories once that memory happened to
- * carry `visibility: "office"` (ops-nzxa). Scattering the scoping rule per
+ * carry `visibility: "office"` (the office-visibility read leak). Scattering the scoping rule per
  * path is exactly how that leak happened — this module exists so it can't
  * happen again: one rule, one place, every path imports it.
  *
- * This is a plain-function module (no `class X extends databases.flair.X`) —
- * deliberately, so it can be safely imported + exercised under DIFFERENT
- * `@harperfast/harper` mocks from multiple test/unit/ files in the same bun
- * process without the class-capture collision documented in
- * test/unit/memory-soul-read-gate.test.ts (that collision is specific to a
- * class whose `extends` clause evaluates `databases.flair.X` at module-eval
- * time; a plain function that reads `databases` inside its body at CALL time
- * does not have that problem).
- *
- * ── The model (private | shared) ─────────────────────────────────────────────
- * `Memory.visibility` is writer intent: "private" (owner-only) or "shared"
- * (visible to anyone holding a read/search MemoryGrant on the owner). A
- * reader's full read-scope is:
+ * ── The model (open-within-org read) ─────────────────────────────────────────
+ * Knowledge-refinement, not access-control (per the MEMORY-MODEL-REFRAME):
+ * an org/instance is one shared knowledge base. `Memory.visibility` is writer
+ * intent: "private" is the ONLY owner-only exception; anything else (`shared`,
+ * null/absent) is org-open — readable by ANY verified agent on this instance,
+ * not just owners who happen to hold a per-owner MemoryGrant. A reader's full
+ * read-scope is:
  *   - ALL of the reader's own records, any visibility, unrestricted.
- *   - A GRANTED owner's records EXCEPT that owner's `private` ones.
+ *   - EVERY other agent's non-private record on this instance.
+ * The federation edge (resources/Federation.ts's push filter / src/cli.ts's
+ * runFederationSyncOnce) is the only remaining hard access boundary — it
+ * already excludes `private` rows from ever leaving this instance. Within an
+ * instance, there is no per-owner grant gate on READS anymore: MemoryGrant is
+ * no longer consulted by this module at all (see resolveAllowedOwners's doc
+ * below for why the function itself still exists).
  *
- * ── The migration invariant (non-negotiable) ─────────────────────────────────
- * Existing memories (written before this field existed) have NO `visibility`
- * field. They must read EXACTLY as before: to whoever holds a grant today.
- * So a record with no `visibility` field is treated as "shared" — this is why
- * the exclusion condition is `visibility != 'private'` (`not_equal`, which
+ * ── The no-visibility-field invariant (non-negotiable) ───────────────────────
+ * Existing memories (written before the `visibility` field existed) have NO
+ * `visibility` field. A record with no `visibility` field is NOT private — it
+ * reads exactly like an explicit `shared` record (org-open). This is why the
+ * exclusion condition is `visibility != 'private'` (`not_equal`, which
  * INCLUDES records missing the field entirely), never `visibility == 'shared'`
- * (`equals`, which would EXCLUDE them and silently break every existing grant
- * relationship — nothing is retroactively made private, nothing broadened).
+ * (`equals`, which would EXCLUDE them and silently retroactively privatize
+ * every legacy row) — nothing is retroactively made private, nothing is
+ * excluded from the broadening that wasn't already excluded before it. There
+ * is no migration/backfill step: pure-open means every pre-existing record
+ * reads as non-private automatically, the moment this code is deployed —
+ * gating that on an operator-run step would itself be a knob the
+ * emergent-trust reframe rejects (zero knobs).
  */
 /**
- * Owner ids a non-admin agent may READ: itself, plus any owner who has
- * granted it a "read" or "search" scoped MemoryGrant. This is the pre-existing
- * owner-set resolution (unchanged in shape/behavior) — resolveReadScope()
- * below builds the full private-exclusion-aware scope on top of it.
+ * Owner ids a non-admin agent holds an explicit "read" or "search" scoped
+ * MemoryGrant from (plus itself). NO LONGER used by resolveReadScope() below
+ * — reads are open-within-org now, so a per-read grant lookup is dead weight
+ * on every read path. Kept exported and unchanged in shape/behavior because
+ * it is still the right tool for "who has this agent explicitly granted
+ * itself to" listings / admin tooling (grants remain a real, inspectable
+ * relationship — they just no longer gate reads). Do NOT delete this
+ * function, and do NOT reintroduce a call to it from resolveReadScope().
  */
 export async function resolveAllowedOwners(authAgentId) {
     const allowedOwners = [authAgentId];
@@ -58,55 +68,32 @@ export async function resolveAllowedOwners(authAgentId) {
     catch { /* MemoryGrant table not yet populated — ignore */ }
     return allowedOwners;
 }
-const PRIVATE = "private";
 /**
- * Resolve the full read-scope (owner set + condition + in-process predicate)
- * for a reader. This is the ONE function every cross-agent Memory read path
- * must call — see the module doc above.
+ * Resolve the full read-scope (condition + in-process predicate) for a
+ * reader. This is the ONE function every cross-agent Memory read path must
+ * call — see the module doc above. No longer async-dependent on a DB lookup
+ * (MemoryGrant is not consulted for reads), but stays declared `async` /
+ * Promise-returning for call-site stability — every existing caller already
+ * `await`s it.
  */
 export async function resolveReadScope(authAgentId) {
-    const allowedOwners = await resolveAllowedOwners(authAgentId);
-    const grantedOwners = allowedOwners.filter((id) => id !== authAgentId);
-    const selfCondition = { attribute: "agentId", comparator: "equals", value: authAgentId };
-    let condition;
-    if (grantedOwners.length === 0) {
-        // No grants held — the reader's scope is just its own records. Emitting
-        // the plain leaf condition here (rather than an `or` with a single
-        // branch) keeps the common case's query shape identical to what
-        // Memory.search() emitted before this change.
-        condition = selfCondition;
-    }
-    else {
-        const grantedOwnerCondition = grantedOwners.length === 1
-            ? { attribute: "agentId", comparator: "equals", value: grantedOwners[0] }
-            : { operator: "or", conditions: grantedOwners.map((id) => ({ attribute: "agentId", comparator: "equals", value: id })) };
-        condition = {
-            operator: "or",
-            conditions: [
-                selfCondition,
-                {
-                    operator: "and",
-                    conditions: [
-                        grantedOwnerCondition,
-                        // not_equal (NOT equals 'shared') — see module doc: a record with
-                        // NO visibility field must still read as shared. This is the
-                        // migration-equivalence invariant, enforced in the condition
-                        // itself so every path that uses it gets it for free.
-                        { attribute: "visibility", comparator: "not_equal", value: PRIVATE },
-                    ],
-                },
-            ],
-        };
-    }
-    const grantedSet = new Set(grantedOwners);
+    // Open-within-org read: own records (any visibility) OR any non-private
+    // record on the instance. No grant lookup — see module doc.
+    const condition = {
+        operator: "or",
+        conditions: [
+            { attribute: "agentId", comparator: "equals", value: authAgentId },
+            // not_equal (NOT equals 'private') — see module doc: a record with NO
+            // visibility field must still read as non-private (the migration-
+            // equivalence invariant), enforced in the condition itself so every
+            // path that uses it gets it for free.
+            { attribute: "visibility", comparator: "not_equal", value: PRIVATE_VISIBILITY },
+        ],
+    };
     const isAllowed = (record) => {
         if (!record)
             return false;
-        if (record.agentId === authAgentId)
-            return true;
-        if (!record.agentId || !grantedSet.has(record.agentId))
-            return false;
-        return record.visibility !== PRIVATE;
+        return record.agentId === authAgentId || !isPrivateVisibility(record.visibility);
     };
-    return { allowedOwners, condition, isAllowed };
+    return { allowedOwners: [authAgentId], condition, isAllowed };
 }

package/dist/resources/memory-visibility.js

@@ -0,0 +1,37 @@
+/**
+ * ─── The single "is this Memory private" predicate (federation-edge-hardening
+ * slice 2: one rule, one place) ───────────────────────────────────
+ *
+ * Shared by BOTH:
+ *   - resources/memory-read-scope.ts's resolveReadScope() — the cross-agent
+ *     READ scope every read path (Memory.search/get, SemanticSearch,
+ *     MemoryBootstrap, the by-id auth-middleware guard) resolves through.
+ *   - src/cli.ts's runFederationSyncOnce() — the federation-sync PUSH filter
+ *     that must not replicate `private` memories to peer instances.
+ *
+ * Deliberately has ZERO imports — not even "@harperfast/harper". That is
+ * intentional and load-bearing: src/cli.ts is a standalone CLI entrypoint
+ * that runs OUTSIDE any running Harper instance (e.g. `flair federation
+ * sync` invoked from a cron/launchd job). resources/memory-read-scope.ts
+ * imports `databases` from "@harperfast/harper", and that package's
+ * top-level init eagerly resolves storage paths and THROWS when there is no
+ * live Harper runtime backing it (confirmed empirically — it takes down
+ * even `flair --help`). So src/cli.ts must never import
+ * resources/memory-read-scope.ts (or anything else that drags that
+ * side-effecting import in) directly. This module is the safe seam: a pure
+ * function + constant that both sides can import without dragging in
+ * "@harperfast/harper".
+ *
+ * ── The migration invariant (non-negotiable, mirrors memory-read-scope.ts) ──
+ * A record with NO `visibility` field (written before the field existed) is
+ * NOT private — it must keep syncing/reading exactly as before. This is why
+ * the predicate is "is this exactly 'private'", never "is this not 'shared'":
+ * missing/null/anything-other-than-'private' all count as non-private.
+ */
+export const PRIVATE_VISIBILITY = "private";
+/** True only when visibility is the literal string "private". Null, undefined,
+ *  "shared", or any other value are all non-private (see migration invariant
+ *  above) — never invert this to an allowlist of "shared". */
+export function isPrivateVisibility(visibility) {
+    return visibility === PRIVATE_VISIBILITY;
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.20.1",
+  "version": "0.21.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",
@@ -55,7 +55,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.1.14",
+    "@harperfast/harper": "5.1.15",
     "@harperfast/oauth": "2.1.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",

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.