@tpsdev-ai/flair 0.18.0 → 0.20.0

package/dist/resources/WorkspaceState.js

@@ -8,15 +8,64 @@
  * Use this.getContext() to access request context (tpsAgent, tpsAgentIsAdmin).
  */
 import { databases } from "@harperfast/harper";
-import { resolveAgentAuth } from "./agent-auth.js";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
 const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
+const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
 export class WorkspaceState extends databases.flair.WorkspaceState {
     /** Auth verdict from the request context. internal = trusted in-process call;
      *  agent = verified Ed25519; anonymous = HTTP with no valid agent → deny. */
     _auth() {
         return resolveAgentAuth(this.getContext?.());
     }
+    /**
+     * Self-authorize now that the global gate is non-rejecting (memory-soul-
+     * read-gate family fix, ops-oox7 — applying the Memory.ts/Soul.ts pattern
+     * to WorkspaceState/Relationship/Integration/MemoryGrant). Closes the same
+     * P0 leak: Harper routes `GET /WorkspaceState/<id>` to get() and the
+     * collection describe (`GET /WorkspaceState`) to a path outside search(),
+     * so neither was gated before this fix — an anonymous caller got a 200 with
+     * full record content. Per-record ownership scoping happens in get() below;
+     * the collection scope is still in search().
+     */
+    allowRead() { return allowVerified(this.getContext?.()); }
+    /**
+     * Override get() to scope by-id reads the same way search() scopes
+     * collection reads (memory-soul-read-gate family fix). Never distinguishes
+     * "doesn't exist" from "exists but not yours" — both return 404, never
+     * 403, so a denied caller can't use get() to enumerate other agents'
+     * workspace-state ids.
+     */
+    async get(target) {
+        // Collection / query reads — the `GET /WorkspaceState/?<query>` form and
+        // the bare collection — arrive as a RequestTarget with `isCollection ===
+        // true`, and are governed by search() (same owner scoping). Only a
+        // genuine by-id get is ownership-checked below. Without this guard,
+        // get() would receive the query's RequestTarget, super.get() would
+        // return the (truthy) result set, and the single-record ownership check
+        // would find no `.agentId` on it (see Memory.ts's get() for the full
+        // rationale — same bug class).
+        if (!target || (typeof target === "object" && target.isCollection)) {
+            return this.search(target);
+        }
+        const auth = await this._auth();
+        // Anonymous by-id read is already blocked at the allowRead() gate (403);
+        // this is defense-in-depth if get() is ever reached directly.
+        if (auth.kind === "anonymous") {
+            return NOT_FOUND();
+        }
+        // Trusted internal call or admin agent — unfiltered, unchanged behavior.
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
+            return super.get(target);
+        }
+        // Non-admin agent: only its own workspace-state records.
+        const record = await super.get(target);
+        if (!record)
+            return NOT_FOUND();
+        if (record.agentId !== auth.agentId)
+            return NOT_FOUND();
+        return record;
+    }
     /**
      * Override search() to scope collection GETs to the authenticated agent's own
      * records. Internal calls + admin agents see all; anonymous is denied
@@ -85,7 +134,12 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return super.delete(id);
         }
-        const record = await this.get(id);
+        // Use super.get(id), NOT this.get(id): the new get() override above 404s
+        // (a truthy Response) for a non-owner id, which would otherwise defeat
+        // the `if (!record)` check below and mis-route a genuinely-missing
+        // record into the FORBIDDEN branch instead of a clean super.delete(id)
+        // no-op. Mirrors Memory.ts's delete() — same rationale, same fix.
+        const record = await super.get(id);
         if (!record)
             return super.delete(id);
         if (record.agentId !== auth.agentId) {

package/dist/resources/agent-auth.js

@@ -16,8 +16,7 @@
  * 30s timestamp window + a per-(agent,nonce) seen-set pruned to that window.
  */
 import { databases } from "@harperfast/harper";
-import { b64ToArrayBuffer } from "./b64.js";
-const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
  * `flair_agent` role), replacing the old admin super_user elevation. Single
@@ -25,31 +24,12 @@ const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
  * provisions it (ensureFlairAgentUser); they MUST agree on the name.
  */
 export const FLAIR_AGENT_USERNAME = "flair-agent";
-// Replay protection: remember recently-seen (agent:nonce), pruned by the window.
-const nonceSeen = new Map();
-// ─── Crypto helpers ───────────────────────────────────────────────────────────
-// b64ToArrayBuffer lives in ./b64.ts (shared with auth-middleware.ts + Presence.ts
-// so the base64/base64url decoder can't drift across the three auth call sites).
-const keyCache = new Map();
-async function importEd25519Key(publicKeyStr) {
-    const cached = keyCache.get(publicKeyStr);
-    if (cached)
-        return cached;
-    // Accept hex (64-char) or base64 (44-char) encoded 32-byte Ed25519 public key.
-    let raw;
-    if (/^[0-9a-f]{64}$/i.test(publicKeyStr)) {
-        const bytes = new Uint8Array(32);
-        for (let i = 0; i < 32; i++)
-            bytes[i] = parseInt(publicKeyStr.slice(i * 2, i * 2 + 2), 16);
-        raw = bytes.buffer;
-    }
-    else {
-        raw = b64ToArrayBuffer(publicKeyStr);
-    }
-    const key = await crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, ["verify"]);
-    keyCache.set(publicKeyStr, key);
-    return key;
-}
+// ─── Crypto + replay-guard helpers ────────────────────────────────────────────
+// WINDOW_MS, isNonceReplay/recordNonce (the ONE shared nonce store), and
+// importEd25519Key all live in ./ed25519-auth.ts (bd ops-c4op) — the single
+// shared implementation imported by auth-middleware.ts, agent-auth.ts, and
+// Presence.ts so a nonce recorded via any one of the three call sites is
+// visible to the other two, and the crypto/decoder logic can't drift.
 // ─── Admin resolution ─────────────────────────────────────────────────────────
 // Admin agents come from FLAIR_ADMIN_AGENTS (comma-separated) OR Agent records
 // with role === "admin". OR-combined, cached 60s. Distinct from Harper's
@@ -89,12 +69,8 @@ async function doVerify(request) {
     const now = Date.now();
     if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)
         return null;
-    // Prune expired nonces, then reject replays within the window.
-    for (const [k, t] of nonceSeen)
-        if (now - t > WINDOW_MS)
-            nonceSeen.delete(k);
-    const nonceKey = `${agentId}:${nonce}`;
-    if (nonceSeen.has(nonceKey))
+    // Reject replays within the window (isNonceReplay prunes expired entries first).
+    if (isNonceReplay(agentId, nonce, now))
         return null;
     const agent = await databases.flair.Agent.get(agentId).catch(() => null);
     if (!agent?.publicKey)
@@ -112,7 +88,7 @@ async function doVerify(request) {
     catch {
         return null;
     }
-    nonceSeen.set(nonceKey, ts);
+    recordNonce(agentId, nonce, ts);
     return { agentId, isAdmin: await isAdmin(agentId) };
 }
 /**

package/dist/resources/auth-middleware.js

@@ -2,7 +2,8 @@ import { patchRecord } from "./table-helpers.js";
 import { server, databases } from "@harperfast/harper";
 import { getEmbedding } from "./embeddings-provider.js";
 import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
-import { b64ToArrayBuffer } from "./b64.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
+import { resolveReadScope } from "./memory-read-scope.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
 // (HDB_ADMIN_PASSWORD / FLAIR_ADMIN_PASSWORD). No filesystem token file.
@@ -30,36 +31,17 @@ function getAdminPass() {
     // No admin password configured — return null and let callers fall through
     return null;
 }
-const WINDOW_MS = 30_000;
-const nonceSeen = new Map();
 // ─── Admin resolution ─────────────────────────────────────────────────────────
 // `isAdmin` (FLAIR_ADMIN_AGENTS env + Agent role==="admin", 60s-cached) now lives
 // in agent-auth.ts as the single source of truth, imported above. During the
 // auth reshape this gate and the per-resource allow* helpers must agree on who's
 // an admin — one implementation guarantees they can't diverge.
-// ─── Crypto helpers ───────────────────────────────────────────────────────────
-// b64ToArrayBuffer lives in ./b64.ts (shared with agent-auth.ts + Presence.ts so
-// the base64/base64url decoder can't drift across the three auth call sites).
-const keyCache = new Map();
-async function importEd25519Key(publicKeyStr) {
-    if (keyCache.has(publicKeyStr))
-        return keyCache.get(publicKeyStr);
-    // Accept hex (64-char) or base64 (44-char) encoded 32-byte Ed25519 public key
-    let raw;
-    if (/^[0-9a-f]{64}$/i.test(publicKeyStr)) {
-        // Hex-encoded raw key (TPS CLI default: Buffer.toString('hex'))
-        const bytes = new Uint8Array(32);
-        for (let i = 0; i < 32; i++)
-            bytes[i] = parseInt(publicKeyStr.slice(i * 2, i * 2 + 2), 16);
-        raw = bytes.buffer;
-    }
-    else {
-        raw = b64ToArrayBuffer(publicKeyStr);
-    }
-    const key = await crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, ["verify"]);
-    keyCache.set(publicKeyStr, key);
-    return key;
-}
+// ─── Crypto + replay-guard helpers ────────────────────────────────────────────
+// WINDOW_MS, isNonceReplay/recordNonce (the ONE shared nonce store), and
+// importEd25519Key all live in ./ed25519-auth.ts (bd ops-c4op) — the single
+// shared implementation imported by auth-middleware.ts, agent-auth.ts, and
+// Presence.ts so a nonce recorded via any one of the three call sites is
+// visible to the other two, and the crypto/decoder logic can't drift.
 async function backfillEmbedding(memoryId) {
     try {
         const record = await databases.flair.Memory.get(memoryId);
@@ -255,11 +237,7 @@ server.http(async (request, nextLayer) => {
     const now = Date.now();
     if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)
         return new Response(JSON.stringify({ error: "timestamp_out_of_window" }), { status: 401 });
-    for (const [k, signatureTs] of nonceSeen.entries())
-        if (now - signatureTs > WINDOW_MS)
-            nonceSeen.delete(k);
-    const nonceKey = `${agentId}:${nonce}`;
-    if (nonceSeen.has(nonceKey))
+    if (isNonceReplay(agentId, nonce, now))
         return new Response(JSON.stringify({ error: "nonce_replay_detected" }), { status: 401 });
     const agent = await databases.flair.Agent.get(agentId);
     if (!agent)
@@ -276,7 +254,7 @@ server.http(async (request, nextLayer) => {
     catch (e) {
         return new Response(JSON.stringify({ error: "signature_verification_failed", detail: e?.message }), { status: 401 });
     }
-    nonceSeen.set(nonceKey, ts);
+    recordNonce(agentId, nonce, ts);
     request.tpsAgent = agentId;
     request._tpsAuthVerified = true;
     request.tpsAgentIsAdmin = await isAdmin(agentId);
@@ -499,27 +477,16 @@ server.http(async (request, nextLayer) => {
                 if (memId) {
                     const record = await databases.flair.Memory.get(memId);
                     if (record && record.agentId && record.agentId !== agentId) {
-                        // Allow office-wide memories
-                        if (record.visibility !== "office") {
-                            // Check MemoryGrant
-                            let hasGrant = false;
-                            try {
-                                for await (const grant of databases.flair.MemoryGrant.search({
-                                    conditions: [{ attribute: "granteeId", comparator: "equals", value: agentId }],
-                                })) {
-                                    if (grant.ownerId === record.agentId &&
-                                        (grant.scope === "read" || grant.scope === "search")) {
-                                        hasGrant = true;
-                                        break;
-                                    }
-                                }
-                            }
-                            catch { }
-                            if (!hasGrant) {
-                                return new Response(JSON.stringify({
-                                    error: `forbidden: cannot read memory owned by ${record.agentId}`,
-                                }), { status: 403, headers: { "Content-Type": "application/json" } });
-                            }
+                        // Centralized read-scope (ops-2dm3 Layer 1): a grant only covers
+                        // the owner's SHARED memories, never their private ones. This
+                        // used to be a `visibility === "office"` bypass (any authenticated
+                        // agent, no grant needed) — that's gone; the private-exclusion is
+                        // now enforced the same way every other read path enforces it.
+                        const scope = await resolveReadScope(agentId);
+                        if (!scope.isAllowed(record)) {
+                            return new Response(JSON.stringify({
+                                error: `forbidden: cannot read memory owned by ${record.agentId}`,
+                            }), { status: 403, headers: { "Content-Type": "application/json" } });
                         }
                     }
                 }

package/dist/resources/bm25-filter.js

@@ -72,6 +72,15 @@ export function passesRecordFilters(record, f = {}) {
         return false;
     if (f.asOf && record?.validTo && record.validTo <= f.asOf)
         return false;
+    // ops-9rc6: a past validTo ALWAYS means the record has been closed out —
+    // either by the server supersede path (Memory.ts closeSupersededRecord sets
+    // validTo without necessarily setting `archived`) or any other writer. This
+    // is unconditional (not gated on `f.asOf`) so a server-superseded record
+    // can never resurface in the DEFAULT (no-asOf) recall path just because its
+    // successor happened not to be co-present in the same result set. A record
+    // with no validTo, or a future validTo, is unaffected.
+    if (record?.validTo && Date.parse(record.validTo) < now)
+        return false;
     return true;
 }
 // The full BM25-candidate security filter: a record is a valid BM25 candidate

package/dist/resources/dedup.js

@@ -26,6 +26,30 @@ export const DEDUP_LEXICAL_THRESHOLD_DEFAULT = 0.5;
 /** Below this content length, similarity scoring is unreliable ("ok" would
  *  match "ok" trivially) — the dedup gate is bypassed entirely. */
 export const DEDUP_MIN_CONTENT_LENGTH = 20;
+/**
+ * Cosine similarity of two equal-length embedding vectors, computed directly
+ * in JS. Used as a fallback for Harper's HNSW cosine-sort query omitting a
+ * computed `$distance` on its top candidate when the query's post-filter
+ * result set contains exactly ONE matching record (ops-ume4, found in
+ * resources/Memory.ts's findConservativeDedupMatch; the identical quirk is
+ * also fixed in resources/SemanticSearch.ts's scoring loop for the same
+ * reason — see ops-syzm there). A mismatched length, empty vector, or
+ * zero-magnitude side yields 0 (no signal, never treated as "identical" by a
+ * degenerate computation).
+ */
+export function cosineSimilarity(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
 /** Jaccard similarity of two token sets: |A∩B| / |A∪B|. An empty side yields 0
  *  (no signal — never treated as "fully similar" by vacuous set equality). */
 export function jaccardSimilarity(tokensA, tokensB) {

package/dist/resources/ed25519-auth.js

@@ -0,0 +1,119 @@
+/**
+ * ed25519-auth — single shared source of truth for the TPS-Ed25519 auth
+ * primitives used at all 3 signature-verification call sites:
+ *
+ *   - resources/auth-middleware.ts  (instance-wide HTTP gate)
+ *   - resources/agent-auth.ts       (resolveAgentAuth's per-resource fallback)
+ *   - resources/Presence.ts         (POST /Presence heartbeat auth)
+ *
+ * Before this module existed, each of the 3 files carried its OWN
+ * module-level `nonceSeen` Map (replay guard) plus its own copy of
+ * `importEd25519Key`. Three independent replay windows meant a nonce
+ * recorded as "seen" via one path was invisible to the other two — a
+ * defense-in-depth gap, and a drift hazard (any future fix to one copy
+ * silently didn't apply to the other two). bd ops-c4op consolidates all
+ * three into this one module so there is exactly ONE replay guard and ONE
+ * key-import implementation, imported by all 3 sites.
+ *
+ * `b64ToArrayBuffer` was already unified into resources/b64.ts in a prior
+ * pass (see that file's header) — re-exported here so callers can import
+ * everything Ed25519-auth-related from one place.
+ *
+ * NOT included here: resources/Federation.ts's replay guard. Federation
+ * uses its own purpose-built NonceStore (federation-crypto.ts) for a
+ * different signing scheme (federation peer-to-peer body signatures, not
+ * agent TPS-Ed25519 auth) — deliberately left alone.
+ *
+ * Signed payload format (must match the TPS CLI signer exactly — changing
+ * it breaks every agent's auth): `${agentId}:${ts}:${nonce}:${METHOD}:${pathname}${search}`.
+ * Auth header format: `TPS-Ed25519 <agentId>:<ts>:<nonce>:<signatureB64>`.
+ * nonceKey format (replay-guard map key): `${agentId}:${nonce}`.
+ */
+import { b64ToArrayBuffer } from "./b64.js";
+export { b64ToArrayBuffer };
+/**
+ * Replay window, in ms. Confirmed identical (30_000) as a literal constant
+ * in auth-middleware.ts and Presence.ts. agent-auth.ts alone additionally
+ * read an (undocumented, never-set-anywhere) `FLAIR_AGENT_AUTH_WINDOW_MS`
+ * env override — see the flag on this in the consolidation report; the
+ * override is preserved here (uniformly, for all 3 sites) since no config,
+ * docs, or test in this repo currently sets that var, so preserving it is
+ * additive/no-op for today's deployments while keeping agent-auth.ts's
+ * stated "plugin-shaped, config via env" design intent.
+ */
+export const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
+// ─── Replay guard (single shared instance) ─────────────────────────────────
+//
+// nonceSeen is the ONE module-level singleton — the whole point of this
+// consolidation. A nonce recorded via any one of the 3 call sites is
+// immediately visible to the other two, because they all import this same
+// module (Node/bun module cache = one instance per process).
+const nonceSeen = new Map();
+/** Remove nonce records older than WINDOW_MS relative to `now`. */
+export function pruneNonces(now = Date.now()) {
+    for (const [k, ts] of nonceSeen) {
+        if (now - ts > WINDOW_MS)
+            nonceSeen.delete(k);
+    }
+}
+/**
+ * Prune expired entries, then report whether (agentId, nonce) has already
+ * been recorded within the current window. Returns true = REPLAY (reject).
+ *
+ * Deliberately does NOT record as a side effect — callers check this BEFORE
+ * verifying the signature and call `recordNonce` only AFTER the signature is
+ * confirmed valid (matches the pre-consolidation per-site behavior at all 3
+ * sites exactly: an invalid-signature attempt never burns the nonce, so a
+ * client that retries with a corrected signature isn't locked out).
+ */
+export function isNonceReplay(agentId, nonce, now = Date.now()) {
+    pruneNonces(now);
+    return nonceSeen.has(`${agentId}:${nonce}`);
+}
+/** Record (agentId, nonce) as seen at `ts`. Call only after successful verification. */
+export function recordNonce(agentId, nonce, ts) {
+    nonceSeen.set(`${agentId}:${nonce}`, ts);
+}
+/**
+ * Test-only escape hatch: clear all recorded nonces. Never called by any
+ * production call site — exists so unit tests can isolate the shared
+ * singleton between cases instead of relying on WINDOW_MS-based expiry.
+ */
+export function __clearNoncesForTest() {
+    nonceSeen.clear();
+}
+// ─── Ed25519 public key import (cached) ────────────────────────────────────
+//
+// Single shared key cache, keyed by the raw publicKeyStr. Consolidating the
+// 3 previously-independent caches into one just avoids redundant
+// crypto.subtle.importKey calls across sites for the same agent — no
+// security-relevant behavior change (the cache holds only CryptoKey handles,
+// never logged or exposed).
+const keyCache = new Map();
+/**
+ * Import an agent's Ed25519 public key as a CryptoKey, cached by the raw
+ * key string. Accepts hex (64-char) or base64/base64url (44-char, or
+ * unpadded) encoded 32-byte Ed25519 public keys — identical logic across
+ * all 3 pre-consolidation copies (auth-middleware.ts, agent-auth.ts,
+ * Presence.ts).
+ */
+export async function importEd25519Key(publicKeyStr) {
+    const cached = keyCache.get(publicKeyStr);
+    if (cached)
+        return cached;
+    // Accept hex (64-char) or base64 (44-char) encoded 32-byte Ed25519 public key.
+    let raw;
+    if (/^[0-9a-f]{64}$/i.test(publicKeyStr)) {
+        // Hex-encoded raw key (TPS CLI default: Buffer.toString('hex'))
+        const bytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++)
+            bytes[i] = parseInt(publicKeyStr.slice(i * 2, i * 2 + 2), 16);
+        raw = bytes.buffer;
+    }
+    else {
+        raw = b64ToArrayBuffer(publicKeyStr);
+    }
+    const key = await crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, ["verify"]);
+    keyCache.set(publicKeyStr, key);
+    return key;
+}

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

@@ -0,0 +1,112 @@
+import { databases } from "@harperfast/harper";
+/**
+ * ─── Centralized Memory read-scoping (ops-2dm3 Layer 1) ─────────────────────
+ *
+ * The SINGLE source every cross-agent Memory read path resolves its scope
+ * through: Memory.search()/Memory.get() (resources/Memory.ts), SemanticSearch
+ * (resources/SemanticSearch.ts), MemoryBootstrap (resources/MemoryBootstrap.ts),
+ * and the by-id GET guard in resources/auth-middleware.ts. Before this module
+ * 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
+ * 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:
+ *   - ALL of the reader's own records, any visibility, unrestricted.
+ *   - A GRANTED owner's records EXCEPT that owner's `private` ones.
+ *
+ * ── 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
+ * 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).
+ */
+/**
+ * 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.
+ */
+export async function resolveAllowedOwners(authAgentId) {
+    const allowedOwners = [authAgentId];
+    try {
+        for await (const grant of databases.flair.MemoryGrant.search({
+            conditions: [{ attribute: "granteeId", comparator: "equals", value: authAgentId }],
+        })) {
+            if (grant.ownerId && (grant.scope === "read" || grant.scope === "search")) {
+                allowedOwners.push(grant.ownerId);
+            }
+        }
+    }
+    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.
+ */
+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);
+    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 { allowedOwners, condition, isAllowed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.18.0",
+  "version": "0.20.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",