@tpsdev-ai/flair 0.19.0 → 0.20.0

package/dist/cli.js

@@ -7123,7 +7123,7 @@ memory.command("add [content]").requiredOption("--agent <id>")
     .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content; ops-wkoh)")
     .option("--subject <text>", "one-line title / entity this memory is about")
     .option("--derived-from <csv>", "Comma-separated source Memory IDs this memory was distilled/reflected from (sets Memory.derivedFrom; used by the `rem rapid` reflection loop)")
-    .option("--visibility <value>", "Memory visibility (sets Memory.visibility). Use 'office' to share office-wide with every team agent; omit (default) to keep it private to this agent (flair#509)")
+    .option("--visibility <value>", "Writer-controlled sharing intent (sets Memory.visibility): 'private' (owner-only, never visible to a grant-holder) or 'shared' (visible to owner + any agent holding a read/search MemoryGrant). Omit to use the server's durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private (flair#509, ops-2dm3)")
     .action(async (contentArg, opts) => {
     const content = contentArg ?? opts.content;
     if (!content) {

package/dist/resources/AdminMemory.js

@@ -342,7 +342,7 @@ export class AdminMemory extends Resource {
         <dl style="display:grid;grid-template-columns:200px 1fr;gap:6px;margin-top:8px;font-family:ui-monospace,SF Mono,monospace;font-size:0.85em">
           <dt style="color:#666">id</dt><dd>${esc(m.id)}</dd>
           <dt style="color:#666">contentHash</dt><dd>${esc(m.contentHash ?? "—")}</dd>
-          <dt style="color:#666">visibility</dt><dd>${esc(m.visibility ?? "private")}</dd>
+          <dt style="color:#666">visibility</dt><dd>${esc(m.visibility ?? "shared (no field — pre-migration default)")}</dd>
         </dl>
       </div>
     `;

package/dist/resources/Memory.js

@@ -4,31 +4,23 @@ import { isAdmin, resolveAgentAuth, allowVerified } from "./agent-auth.js";
 import { getEmbedding, getModelId } from "./embeddings-provider.js";
 import { scanFields, isStrictMode } from "./content-safety.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
-import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, isConservativeMatch, } from "./dedup.js";
+import { resolveReadScope } from "./memory-read-scope.js";
+import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.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" } });
 /**
- * Owner ids a non-admin agent may READ: itself, plus any owner who has
- * granted it a "read" or "search" scoped MemoryGrant. Shared by search()
- * (collection scoping) and get() (per-id ownership check, memory-soul-read-
- * gate fix) so the two paths cannot drift apart — this was previously
- * computed inline only inside search().
+ * Owner ids a non-admin agent may READ (resolveAllowedOwners) and the full
+ * read-scope condition + private-exclusion predicate (resolveReadScope) now
+ * live in ./memory-read-scope.ts — the ONE centralized helper every
+ * cross-agent Memory read path (search()/get() here, SemanticSearch.ts,
+ * MemoryBootstrap.ts, auth-middleware.ts's by-id guard) resolves its scope
+ * through, so the scoping rule cannot drift per-path again (ops-nzxa: a
+ * SemanticSearch inline `visibility === "office"` OR-clause leaked office
+ * memories to any authenticated agent because the rule had scattered). See
+ * that module's doc for the migration invariant (no-visibility-field reads
+ * as "shared", never "private").
  */
-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;
-}
 /**
  * ─── Server-side conservative-duplicate gate (memory-integrity fix) ──────────
  *
@@ -94,7 +86,59 @@ async function findConservativeDedupMatch(ctx, agentId, contentText, embedding,
         }
         if (!top)
             return null;
-        const cosine = 1 - (top.$distance ?? 1);
+        // ─── ops-ume4: Harper's cosine-sort query omits $distance for a SINGLETON
+        // result set ─────────────────────────────────────────────────────────────
+        // Initial working theory was a per-agentId HNSW "cold-start" (first-ever
+        // query cold, second query warm) and the initially-recommended fix was a
+        // same-query retry. Empirically FALSIFIED: a plain retry of the identical
+        // query, 8x with 300ms delays (2.4s total), never recovered a `$distance`
+        // for a genuinely singleton candidate set (exactly one record matching
+        // `agentId equals X AND archived not_equal true`). The actual trigger,
+        // confirmed by direct probing: when this query's post-filter result set
+        // has exactly ONE matching record, `$distance` comes back `undefined` for
+        // it — regardless of how many prior queries have run for that agentId,
+        // how long you wait, or how many other agentIds/records already exist in
+        // the table. The moment a SECOND matching record exists, `$distance` is
+        // populated correctly on the very first query ever issued for that
+        // agentId — no warm-up needed. In practice the singleton case is exactly
+        // an agent's SECOND-ever memory (compared against their first) — the most
+        // common real-world trigger for this bug, and why it looked "permanent
+        // per-agent for the first near-dup query."
+        //
+        // Also NOT a query-shape/conditions issue: the `{operator:"or"}` wrap
+        // SemanticSearch.ts uses elsewhere is unrelated, and neither raising
+        // `limit` past 1 nor changing the conditions shape changes the result —
+        // confirmed empirically. Harper's SORT ordering is correct even in the
+        // singleton case (the right record comes back as `top`); only the
+        // numeric `$distance` annotation is missing. Also confirmed: selecting
+        // "embedding" directly on THIS sort-by-embedding query does not help
+        // either — it comes back as a bare scalar (Harper appears to special-case
+        // the sort attribute in `select`), not the stored vector.
+        //
+        // Fix: when `$distance` is undefined, fetch the ONE candidate's full
+        // record by id (a plain point lookup — not a vector-sort query, so
+        // unaffected by the quirk above) and compute cosine similarity ourselves
+        // in JS from its real stored `embedding` vector against this write's own
+        // `embedding` (this function's parameter), via the same math Harper would
+        // have used (dedup.ts's cosineSimilarity, Harper-free and unit-tested).
+        // This sidesteps the underlying engine quirk entirely rather than
+        // depending on its timing, and works identically whether this is the
+        // agent's first query ever or its thousandth. Never suppresses the write
+        // either way: if the candidate's embedding is somehow also missing (e.g.
+        // a legacy record written before embeddings existed), `cosineSimilarity`
+        // returns 0 — the same safe "no match" signal the pre-fix `?? 1`
+        // fallback produced.
+        let cosine;
+        if (top.$distance !== undefined) {
+            cosine = 1 - top.$distance;
+        }
+        else {
+            console.error("Memory.findConservativeDedupMatch: $distance undefined on a singleton cosine result (ops-ume4) — " +
+                "falling back to a manual cosine computation from the candidate's stored embedding", { agentId, candidateId: top.id });
+            const fullCandidate = await withDetachedTxn(ctx, () => databases.flair.Memory.get(top.id));
+            const candidateEmbedding = Array.isArray(fullCandidate?.embedding) ? fullCandidate.embedding : [];
+            cosine = cosineSimilarity(embedding, candidateEmbedding);
+        }
         const confidence = computeMatchConfidence(contentText, top.content, cosine);
         if (!isConservativeMatch(confidence.cosine, confidence.lexical, cosineThreshold, lexicalThreshold)) {
             return null;
@@ -252,6 +296,20 @@ async function closeSupersededIfNeeded(ctx, content, methodLabel) {
             "(ops-a4t5 — observable, not silent; new record is safely written, old record remains active until retried)", { method: methodLabel, supersededId: content.supersedes, newRecordId: content.id, err });
     }
 }
+/**
+ * ─── Durability-keyed default visibility (ops-2dm3 Layer 1, part A) ─────────
+ *
+ * Writer intent: an explicit `visibility` on the write ALWAYS overrides this
+ * (callers check `content.visibility == null` before calling this). When
+ * unset, the default is keyed off durability — a durable write (the agent
+ * chose to make this stick around) defaults to shared; anything else
+ * defaults to private. "absent" durability (not yet defaulted by the caller)
+ * falls into the private branch, matching the spec's
+ * "standard|ephemeral|absent → private".
+ */
+function defaultVisibilityForDurability(durability) {
+    return durability === "permanent" || durability === "persistent" ? "shared" : "private";
+}
 export class Memory extends databases.flair.Memory {
     /**
      * Self-authorize now that the global gate is non-rejecting. Closes the P0
@@ -301,14 +359,15 @@ export class Memory extends databases.flair.Memory {
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return super.get(target);
         }
-        // Non-admin agent: only its own memories, or an owner's memories it holds
-        // a read/search MemoryGrant for (same owner-set as search() — shared
-        // resolveAllowedOwners helper so the two paths cannot drift).
+        // Non-admin agent: only its own memories (any visibility), or a granted
+        // owner's SHARED memories — never that owner's private ones (ops-2dm3
+        // Layer 1 private-exclusion). Centralized in resolveReadScope() so this
+        // and search() below cannot drift.
         const record = await super.get(target);
         if (!record)
             return NOT_FOUND();
-        const allowedOwners = await resolveAllowedOwners(auth.agentId);
-        if (!allowedOwners.includes(record.agentId))
+        const scope = await resolveReadScope(auth.agentId);
+        if (!scope.isAllowed(record))
             return NOT_FOUND();
         return record;
     }
@@ -337,13 +396,12 @@ export class Memory extends databases.flair.Memory {
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return super.search(query);
         }
-        // Non-admin agent: scope to own + granted owners.
+        // Non-admin agent: scope to own (any visibility) + granted owners' SHARED
+        // memories only (ops-2dm3 Layer 1 private-exclusion). Centralized in
+        // resolveReadScope() so get() above and search() here cannot drift.
         const authAgent = auth.agentId;
-        const allowedOwners = await resolveAllowedOwners(authAgent);
-        // Build the agentId scope condition
-        const agentIdCondition = allowedOwners.length === 1
-            ? { attribute: "agentId", comparator: "equals", value: allowedOwners[0] }
-            : { conditions: allowedOwners.map(id => ({ attribute: "agentId", comparator: "equals", value: id })), operator: "or" };
+        const scope = await resolveReadScope(authAgent);
+        const agentIdCondition = scope.condition;
         // Harper passes `query` as a RequestTarget (extends URLSearchParams) or a
         // conditions array. For URL-based GET /Memory?... calls, URL params are no
         // longer translated to conditions here — callers should use
@@ -392,6 +450,16 @@ export class Memory extends databases.flair.Memory {
         content.createdAt = new Date().toISOString();
         content.updatedAt = content.createdAt;
         content.archived = content.archived ?? false;
+        // ─── Default visibility (durability-keyed) — ops-2dm3 Layer 1, part A ────
+        // post() only ever creates a NEW record — patchRecord/supersede-close/
+        // retrievalCount bumps all route through put() instead (see put()'s
+        // pre-existing-record guard below), so there is no "don't overwrite an
+        // existing record's visibility" concern here. Explicit visibility on the
+        // write ALWAYS overrides; only stamp the default when the caller left it
+        // unset. permanent|persistent → shared; standard|ephemeral|absent → private.
+        if (content.visibility === undefined || content.visibility === null) {
+            content.visibility = defaultVisibilityForDurability(content.durability);
+        }
         // Validate derivedFrom source IDs exist (best-effort, non-blocking)
         if (Array.isArray(content.derivedFrom) && content.derivedFrom.length > 0) {
             const now = content.createdAt;
@@ -509,6 +577,26 @@ export class Memory extends databases.flair.Memory {
         // Set defaults that post() sets — put() is also used for new records via CLI
         content.archived = content.archived ?? false;
         content.createdAt = content.createdAt ?? now;
+        // Fetch the pre-existing record (if any) ONCE — reused below both to
+        // decide whether this PUT is a fresh create (dedup gate applies, default
+        // visibility stamped) or an update/patch (dedup-bypassed, visibility left
+        // untouched). See the dedup-gate block further down for why an existing
+        // id skips the gate; the SAME "does a record already exist" check gates
+        // the visibility default (ops-2dm3 Layer 1 part A): patchRecord/supersede-
+        // close/retrievalCount bumps all route through put() with a MERGED
+        // `{...existing, ...patch}` payload, and must never have their stored
+        // visibility overwritten by a default recomputed from that merged content
+        // — only a genuinely NEW id gets the default stamped.
+        const preExisting = content.id
+            ? await databases.flair.Memory.get(content.id).catch(() => null)
+            : null;
+        // ─── Default visibility (durability-keyed) — ops-2dm3 Layer 1, part A ────
+        // Explicit visibility on the write ALWAYS overrides; only stamp the
+        // default when the caller left it unset AND this is a fresh record.
+        // permanent|persistent → shared; standard|ephemeral|absent → private.
+        if (!preExisting && (content.visibility === undefined || content.visibility === null)) {
+            content.visibility = defaultVisibilityForDurability(content.durability);
+        }
         // supersedes: optional reference to the ID of the memory this one
         // replaces. Validates shape + cross-agent-write authorization (shared
         // with post() — see validateAndAuthorizeSupersedes doc for why PUT needs
@@ -552,7 +640,6 @@ export class Memory extends databases.flair.Memory {
             delete content.lexicalThreshold;
         }
         else if (content.id) {
-            const preExisting = await databases.flair.Memory.get(content.id).catch(() => null);
             if (!preExisting) {
                 dedupMatch = await runDedupGate(ctx, content);
             }

package/dist/resources/MemoryBootstrap.js

@@ -3,6 +3,7 @@ import { allowVerified } from "./agent-auth.js";
 import { getEmbedding } from "./embeddings-provider.js";
 import { wrapUntrusted } from "./content-safety.js";
 import { isTeammate, formatTeamLine } from "./memory-bootstrap-lib.js";
+import { resolveReadScope } from "./memory-read-scope.js";
 /**
  * POST /MemoryBootstrap
  *
@@ -12,11 +13,18 @@ import { isTeammate, formatTeamLine } from "./memory-bootstrap-lib.js";
  *   2. Permanent memories (safety rules, core principles)
  *   3. Recent memories (adaptive window)
  *   4. Task-relevant memories (semantic search if currentTask provided)
+ *   4b. Teammate findings relevant to your task (flair#550 — the SAME scored
+ *      task-relevant set as #4, split by origin: a grant-visible teammate's
+ *      SHARED memory that scores against currentTask lands here instead of
+ *      #4, attributed via "[via <agentId>]". Presentation only — what's
+ *      readable is entirely Layer 1's resolveReadScope()/ops-2dm3; this only
+ *      changes how an already-read cross-agent record is formatted/sectioned)
  *   5. Relationship context (active relationships for mentioned entities)
  *   6. Predicted context (based on channel/surface/subject hints)
  *   7. Team roster (other active agents in this office + a search-first nudge —
- *      bootstrap only ever loads the caller's own memories, so this is the one
- *      place agents learn teammates' findings exist without a separate call)
+ *      bootstrap loads the caller's own memories plus any granted owner's
+ *      SHARED memories (ops-2dm3 Layer 1, never their private ones), so this
+ *      section nudges toward memory_search for anything beyond that window)
  *
  * Prediction: when context signals (channel, surface, subjects) are provided,
  * the bootstrap loads more aggressively — Flair is fast enough that the
@@ -33,12 +41,23 @@ import { isTeammate, formatTeamLine } from "./memory-bootstrap-lib.js";
 function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
-function formatMemory(m, supersedes) {
+// `agentId` is the BOOTSTRAPPING agent (the caller) — used only to decide
+// whether to annotate attribution, never to change what's read (that
+// boundary is resolveReadScope()'s job, upstream of this function). A
+// cross-agent record always carries `_source` (set once, above, when the
+// record's own agentId differs from the bootstrapping agent — see the
+// allMemories loop), so `m._source !== agentId` is the "is this a
+// teammate's finding" check; own memories never carry `_source` at all.
+function formatMemory(m, agentId) {
     const tag = m.durability === "permanent" ? "🔒" : m.durability === "persistent" ? "📌" : "📝";
     const date = m.createdAt ? ` (${m.createdAt.slice(0, 10)})` : "";
     const chain = m.supersedes ? " [supersedes earlier decision]" : "";
-    const base = `${tag} ${m.content}${date}${chain}`;
-    // Wrap flagged memories in safety delimiters
+    const attribution = m._source && m._source !== agentId ? `[via ${m._source}] ` : "";
+    const base = `${tag} ${attribution}${m.content}${date}${chain}`;
+    // Wrap flagged memories in safety delimiters — composes with attribution
+    // above (attribution is baked into `base` before wrapping, so a flagged
+    // teammate memory renders with BOTH the "[via <agent>]" tag and the
+    // untrusted-content wrapper).
     if (m._safetyFlags && Array.isArray(m._safetyFlags) && m._safetyFlags.length > 0) {
         return wrapUntrusted(base, m._source);
     }
@@ -90,6 +109,7 @@ export class BootstrapMemories extends Resource {
             predicted: [],
             relationships: [],
             relevant: [],
+            teammate: [],
             events: [],
         };
         let tokenBudget = maxTokens;
@@ -178,12 +198,13 @@ export class BootstrapMemories extends Resource {
             }
         }
         // --- 1c. Team roster + cross-agent search nudge ---
-        // Bootstrap only ever loads the caller's OWN soul/memories (every query
-        // below filters record.agentId === agentId). Nothing here tells the agent
-        // that teammates exist or that their findings are one memory_search away
-        // — so agents never think to check before re-investigating something a
-        // teammate already solved. This section is fixed-cost (no query text to
-        // format per agent) so it's cheap enough to always include, not budgeted.
+        // Soul is still caller-own-only (unaffected here). Memory loading below
+        // (step 2) now also includes granted owners' SHARED memories (ops-2dm3
+        // Layer 1) — but this section stays: memory_search/SemanticSearch remains
+        // the deliberate, query-driven way to find a teammate's finding, vs.
+        // bootstrap's fixed recent/permanent window. This section is fixed-cost
+        // (no query text to format per agent) so it's cheap enough to always
+        // include, not budgeted.
         //
         // Permissive kind/status checks are DELIBERATE: Agent.ts registration
         // defaults both (`kind ||= "agent"`, `status ||= "active"`), so pre-1.0
@@ -204,13 +225,39 @@ export class BootstrapMemories extends Resource {
             // Agent table may not exist in older / standalone deployments
         }
         // --- 2. Permanent memories (always included, highest priority) ---
+        // Read-scope: own (any visibility) + granted owners' SHARED memories only
+        // (ops-2dm3 Layer 1 — never a granted owner's private ones). Centralized
+        // in resolveReadScope(): the condition is pushed into the Harper query
+        // (so the table itself never returns an out-of-scope row), and
+        // `scope.isAllowed` re-checks in-process as defense-in-depth (same
+        // belt-and-suspenders discipline as SemanticSearch's BM25 pre-fusion
+        // filter) — this is the #550 foundation: bootstrap can now safely expand
+        // beyond own-only without a parallel scoping rule.
+        const scope = await resolveReadScope(agentId);
         const allMemories = [];
-        for await (const record of databases.flair.Memory.search()) {
-            if (record.agentId !== agentId)
+        for await (const record of databases.flair.Memory.search({ conditions: [scope.condition] })) {
+            if (!scope.isAllowed(record))
                 continue;
             if (record.expiresAt && Date.parse(record.expiresAt) < Date.now())
                 continue;
-            allMemories.push(record);
+            // ops-hesq: a past validTo ALWAYS means the record has been closed out
+            // (server supersede path — Memory.ts closeSupersededRecord — sets
+            // validTo without necessarily setting `archived`), same root cause and
+            // fix as ops-9rc6's SemanticSearch/bm25-filter exclusion. Unconditional
+            // so a server-superseded record can't resurface in bootstrap 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;
+            // Attribution for cross-agent (granted-owner) records — same convention
+            // SemanticSearch.ts already uses: formatMemory() below only USES this
+            // when the record also carries _safetyFlags (labels the untrusted-data
+            // wrapper with whose memory it is), it never forces wrapping on its own.
+            // Real Harper's search() results are non-extensible objects — mutating
+            // `record._source = ...` directly throws ("object is not extensible");
+            // shallow-copy instead of mutating in place.
+            allMemories.push(record.agentId !== agentId ? { ...record, _source: record.agentId } : record);
         }
         memoriesAvailable = allMemories.length;
         // Build superseded set: exclude memories that have been replaced by newer ones
@@ -220,9 +267,18 @@ export class BootstrapMemories extends Resource {
                 supersededIds.add(m.supersedes);
         }
         const activeMemories = allMemories.filter((m) => !supersededIds.has(m.id));
-        const permanent = activeMemories.filter((m) => m.durability === "permanent");
+        // #550 design boundary: the permanent / recent / predicted sections are the
+        // agent's OWN working context — own-only, always. Post-Layer-1
+        // `activeMemories` also carries grant-visible teammate records (`_source`
+        // set), but grant-visibility exists to feed the task-relevant "Teammate
+        // findings" surfacing (#550) below, NOT to blend a teammate's memories into
+        // the reader's recent/permanent/predicted view. So these three sections
+        // filter to own (`!m._source`); team knowledge surfaces only when
+        // task-relevant (the teammate section) or via an explicit memory_search.
+        const ownMemories = activeMemories.filter((m) => !m._source);
+        const permanent = ownMemories.filter((m) => m.durability === "permanent");
         for (const m of permanent) {
-            const line = formatMemory(m);
+            const line = formatMemory(m, agentId);
             const cost = estimateTokens(line);
             if (cost <= tokenBudget) {
                 sections.permanent.push(line);
@@ -236,7 +292,7 @@ export class BootstrapMemories extends Resource {
         // --- 3. Recent memories (adaptive window) ---
         // Start with 48h. If nothing found, widen to 7d, then 30d.
         // This prevents empty recent sections for agents that were idle.
-        const nonPermanent = activeMemories
+        const nonPermanent = ownMemories
             .filter((m) => m.durability !== "permanent" && m.createdAt)
             .sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
         let effectiveSince;
@@ -258,7 +314,7 @@ export class BootstrapMemories extends Resource {
         const recentBudget = Math.floor(tokenBudget * 0.4);
         let recentSpent = 0;
         for (const m of recent) {
-            const line = formatMemory(m);
+            const line = formatMemory(m, agentId);
             const cost = estimateTokens(line);
             if (recentSpent + cost > recentBudget) {
                 memoriesTruncated++;
@@ -282,7 +338,7 @@ export class BootstrapMemories extends Resource {
                 ...permanent.map((m) => m.id),
                 ...recent.filter((_, i) => i < sections.recent.length).map((m) => m.id),
             ]);
-            const subjectMemories = activeMemories
+            const subjectMemories = ownMemories
                 .filter((m) => !includedIds.has(m.id) &&
                 m.subject &&
                 predictedSubjects.includes(m.subject.toLowerCase()) &&
@@ -292,7 +348,7 @@ export class BootstrapMemories extends Resource {
             const predictedBudget = Math.floor(tokenBudget * 0.3);
             let predictedSpent = 0;
             for (const m of subjectMemories) {
-                const line = formatMemory(m);
+                const line = formatMemory(m, agentId);
                 const cost = estimateTokens(line);
                 if (predictedSpent + cost > predictedBudget) {
                     memoriesTruncated++;
@@ -362,12 +418,25 @@ export class BootstrapMemories extends Resource {
                 })
                     .filter((s) => s.score > 0.3)
                     .sort((a, b) => b.score - a.score);
+                // #550: split the scored, task-relevant set by origin. Own findings
+                // go to `relevant` as before; a teammate's (grant-visible, already
+                // read-scoped by Layer 1 — `m._source` is only ever set for a
+                // cross-agent record, see the allMemories loop above) go to the new
+                // `teammate` section so the agent can tell it apart at a glance.
+                // Both draw from the SAME `tokenBudget` in one score-ordered pass —
+                // highest-relevance memories win the remaining budget regardless of
+                // which section they land in, so neither section double-spends.
                 for (const { memory: m } of scored) {
-                    const line = formatMemory(m);
+                    const line = formatMemory(m, agentId);
                     const cost = estimateTokens(line);
                     if (cost > tokenBudget)
                         continue;
-                    sections.relevant.push(line);
+                    if (m._source) {
+                        sections.teammate.push(line);
+                    }
+                    else {
+                        sections.relevant.push(line);
+                    }
                     tokenBudget -= cost;
                     memoriesIncluded++;
                 }
@@ -428,6 +497,13 @@ export class BootstrapMemories extends Resource {
         if (sections.relevant.length > 0) {
             parts.push("## Relevant Knowledge\n" + sections.relevant.join("\n"));
         }
+        // #550: teammate findings relevant to the current task — right after the
+        // agent's own task-relevant knowledge. Empty section renders nothing
+        // (no header) so a bootstrap with no grant-visible teammate findings for
+        // this task looks exactly as it did before this feature.
+        if (sections.teammate.length > 0) {
+            parts.push("## Teammate findings relevant to your task\n" + sections.teammate.join("\n"));
+        }
         if (sections.events.length > 0) {
             parts.push("## Recent Org Events\n" + sections.events.join("\n"));
         }
@@ -445,6 +521,7 @@ export class BootstrapMemories extends Resource {
                 predicted: sections.predicted.length,
                 relationships: sections.relationships.length,
                 relevant: sections.relevant.length,
+                teammate: sections.teammate.length,
                 events: sections.events.length,
             },
             tokenEstimate: soulTokens + memoryTokens,

package/dist/resources/Presence.js

@@ -18,9 +18,8 @@
  */
 import { databases } from "@harperfast/harper";
 import { resolveAgentAuth } from "./agent-auth.js";
-import { b64ToArrayBuffer } from "./b64.js";
+import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer } from "./ed25519-auth.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
-const WINDOW_MS = 30_000;
 const CURRENT_TASK_MAX_LENGTH = 200;
 const VALID_ACTIVITIES = new Set(["coding", "reviewing", "planning", "idle"]);
 function idleThresholdMs() {
@@ -31,36 +30,12 @@ function offlineThresholdMs() {
     const env = process.env.PRESENCE_OFFLINE_THRESHOLD_MS;
     return env ? Number(env) || 600_000 : 600_000;
 }
-// ─── Nonce replay protection ──────────────────────────────────────────────────
-const nonceSeen = new Map();
-function pruneNonces() {
-    const now = Date.now();
-    for (const [k, ts] of nonceSeen.entries()) {
-        if (now - ts > WINDOW_MS)
-            nonceSeen.delete(k);
-    }
-}
-// ─── Crypto helpers ───────────────────────────────────────────────────────────
-// b64ToArrayBuffer lives in ./b64.ts (shared with auth-middleware.ts + agent-auth.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);
-    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;
-}
+// ─── Nonce replay + crypto 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.
 // ─── Status derivation (pure — exported for unit testing) ─────────────────────
 export function derivePresenceStatus(now, lastHeartbeatAt, idleMs, offlineMs) {
     const idle = idleMs ?? idleThresholdMs();
@@ -195,9 +170,7 @@ export class Presence extends databases.flair.Presence {
             if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS) {
                 return new Response(JSON.stringify({ error: "timestamp_out_of_window" }), { status: 401, headers: { "Content-Type": "application/json" } });
             }
-            pruneNonces();
-            const nonceKey = `${headerAgentId}:${nonce}`;
-            if (nonceSeen.has(nonceKey)) {
+            if (isNonceReplay(headerAgentId, nonce, now)) {
                 return new Response(JSON.stringify({ error: "nonce_replay_detected" }), { status: 401, headers: { "Content-Type": "application/json" } });
             }
             const agent = await databases.flair.Agent.get(headerAgentId).catch(() => null);
@@ -219,7 +192,7 @@ export class Presence extends databases.flair.Presence {
             catch (e) {
                 return new Response(JSON.stringify({ error: "signature_verification_failed", detail: e?.message }), { status: 401, headers: { "Content-Type": "application/json" } });
             }
-            nonceSeen.set(nonceKey, ts);
+            recordNonce(headerAgentId, nonce, ts);
             agentId = headerAgentId;
         }
         // ── Validate body ────────────────────────────────────────────────────────

package/dist/resources/SemanticSearch.js

@@ -4,6 +4,8 @@ import { getEmbedding, getMode } from "./embeddings-provider.js";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { wrapUntrusted } from "./content-safety.js";
+import { resolveReadScope } from "./memory-read-scope.js";
+import { cosineSimilarity } from "./dedup.js";
 import { isRerankEnabled, getRerankTopN, getRerankBudgetMs, getRerankMinCandidates, rerankCandidates, } from "./rerank-provider.js";
 // Temporal decay + relevance scoring (incl. the OPS-AYGD retrievalBoost cap +
 // relevance floor) lives in ./scoring.ts — a Harper-free module so it can be
@@ -28,8 +30,9 @@ export class SemanticSearch extends Resource {
     // Self-authorize via the Ed25519 agent verify instead of relying on the auth
     // gate's admin super_user elevation (removed in the auth reshape). Any
     // cryptographically-verified agent may search; per-agent RESULT scoping is
-    // enforced in post() below (an agent only sees its own + office-visible +
-    // granted memories). Without this, Harper's default denies the POST for the
+    // enforced in post() below (an agent only sees its own memories, any
+    // visibility, plus granted owners' SHARED memories — never their private
+    // ones). Without this, Harper's default denies the POST for the
     // least-privilege flair_agent role (AccessViolation 403).
     async allowCreate() {
         return allowVerified(this.getContext?.());
@@ -77,21 +80,13 @@ export class SemanticSearch extends Resource {
         const agentId = (authenticatedAgent && !callerIsAdmin)
             ? authenticatedAgent
             : bodyAgentId;
-        const searchAgentIds = new Set();
-        if (agentId)
-            searchAgentIds.add(agentId);
-        if (agentId) {
-            try {
-                for await (const grant of databases.flair.MemoryGrant.search({
-                    conditions: [{ attribute: "granteeId", comparator: "equals", value: agentId }],
-                })) {
-                    if (grant.scope === "search" || grant.scope === "read") {
-                        searchAgentIds.add(grant.ownerId);
-                    }
-                }
-            }
-            catch { /* MemoryGrant may not exist */ }
-        }
+        // Read-scope: own (any visibility) + granted owners' SHARED memories only
+        // (ops-2dm3 Layer 1). Centralized in resolveReadScope() — this used to be
+        // an inline grant-resolution loop here PLUS a `visibility === "office"`
+        // global OR-clause below that leaked ANY authenticated agent's read of
+        // ANY other agent's office-visible memories (ops-nzxa). Both are gone;
+        // this is the ONE scoping resolution for this endpoint now.
+        const scope = agentId ? await resolveReadScope(agentId) : null;
         // Generate query embedding
         let qEmb = queryEmbedding;
         if (!qEmb && q) {
@@ -135,21 +130,12 @@ export class SemanticSearch extends Resource {
         }
         // ─── Build conditions for Harper query ──────────────────────────────────
         const conditions = [];
-        // Agent scoping: filter to allowed agent IDs or office-visible memories
-        if (searchAgentIds.size === 1) {
-            const [id] = searchAgentIds;
-            conditions.push({
-                operator: "or",
-                conditions: [
-                    { attribute: "agentId", comparator: "equals", value: id },
-                    { attribute: "visibility", comparator: "equals", value: "office" },
-                ],
-            });
-        }
-        else if (searchAgentIds.size > 1) {
-            const agentConditions = [...searchAgentIds].map(id => ({ attribute: "agentId", comparator: "equals", value: id }));
-            agentConditions.push({ attribute: "visibility", comparator: "equals", value: "office" });
-            conditions.push({ operator: "or", conditions: agentConditions });
+        // Agent scoping: own (any visibility) OR granted-owner's SHARED memories
+        // (private-exclusion) — the centralized read-scope condition. No agentId
+        // → no scoping condition pushed (trusted internal call / admin without a
+        // target agentId — matches the pre-existing unscoped fallback).
+        if (scope) {
+            conditions.push(scope.condition);
         }
         // Exclude archived records. Use "not_equal" (Harper v5 comparator) instead of
         // "equals false" so records without the archived field are included.
@@ -220,6 +206,10 @@ export class SemanticSearch extends Resource {
                         continue;
                     if (asOf && record.validTo && record.validTo <= asOf)
                         continue;
+                    // ops-9rc6: unconditional past-validTo exclusion (see legacy HNSW
+                    // loop below for the full rationale) — applies regardless of asOf.
+                    if (record.validTo && Date.parse(record.validTo) < Date.now())
+                        continue;
                     semRecords.push(record);
                     semIds.push(record.id);
                 }
@@ -325,7 +315,58 @@ export class SemanticSearch extends Resource {
                     continue;
                 if (asOf && record.validTo && record.validTo <= asOf)
                     continue;
-                const semanticScore = distanceToSimilarity(record.$distance ?? 1);
+                // ops-9rc6: 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 in
+                // the DEFAULT recall path 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;
+                let semanticScore;
+                if (record.$distance !== undefined) {
+                    semanticScore = distanceToSimilarity(record.$distance);
+                }
+                else {
+                    // ─── ops-syzm: Harper's cosine-sort query omits $distance for a
+                    // SINGLETON post-filter result set — the SAME quirk root-caused and
+                    // fixed for the dedup path in ops-ume4 (resources/Memory.ts
+                    // findConservativeDedupMatch / resources/dedup.ts cosineSimilarity).
+                    // Sort ORDER is still correct; only the numeric `$distance`
+                    // annotation is missing on that one record, regardless of the
+                    // query's own `limit` (reproduced here with candidateLimit=50, not
+                    // just limit=1 — the trigger is the post-filter MATCH COUNT, not the
+                    // requested limit).
+                    //
+                    // ops-2dm3 Layer 1 made this common: the no-grants agent scope used
+                    // to ALWAYS be a compound `{operator:"or", conditions:[{agentId},
+                    // {visibility=="office"}]}` condition; resolveReadScope() now emits
+                    // a PLAIN single `{agentId==X}` condition for the common (no-grants)
+                    // case, so a scoped search against an agent with exactly one
+                    // matching memory hits this Harper quirk directly. Before, the OR
+                    // wrap incidentally avoided the singleton shape. The old `?? 1`
+                    // fallback silently collapsed this to similarity 0 — read by
+                    // callers (including the clean-VM CI gate's single-memory init
+                    // probe, #533) as "embeddings not loaded", which is WRONG:
+                    // embeddings ARE loaded, only the score was computed incorrectly.
+                    //
+                    // Fix: point-lookup the record by id (a plain get(), unaffected by
+                    // the sort-query quirk — selecting "embedding" directly on the SAME
+                    // sort-by-embedding query comes back as a bare scalar per ops-ume4's
+                    // findings) and compute cosine similarity ourselves in JS from its
+                    // real stored `embedding` vector against this query's `qEmb`, via
+                    // the same math as the ume4 fallback (dedup.ts's cosineSimilarity).
+                    // Only done on this (rare) undefined-$distance branch — never adds
+                    // a point-lookup to the normal per-record path. If the stored
+                    // embedding is missing/empty (e.g. a legacy pre-embedding record),
+                    // 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;
@@ -364,6 +405,10 @@ export class SemanticSearch extends Resource {
                     continue;
                 if (asOf && record.validTo && record.validTo <= asOf)
                     continue;
+                // ops-9rc6: unconditional past-validTo exclusion (see legacy HNSW
+                // loop above for the full rationale) — applies regardless of asOf.
+                if (record.validTo && Date.parse(record.validTo) < Date.now())
+                    continue;
                 let keywordHit = false;
                 if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
                     keywordHit = true;

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.19.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",