@tpsdev-ai/flair 0.17.0 → 0.19.0

package/dist/resources/Memory.js

@@ -1,10 +1,317 @@
 import { databases } from "@harperfast/harper";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
-import { isAdmin, resolveAgentAuth } from "./agent-auth.js";
+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";
+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().
+ */
+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) ──────────
+ *
+ * NEVER SUPPRESSES A WRITE. This gate only computes a SIGNAL — the caller
+ * (Memory.post / Memory.put) always proceeds to write the new record. When a
+ * conservative match is found, the signal is attached to the RESPONSE only
+ * (deduplicated/matchedId/matchConfidence). There must be no code path where
+ * finding a match causes the write to be skipped: that was the #526 bug (two
+ * topically-close but DISTINCT findings — one about replication
+ * route-directionality, one about DDL/schema replication — and the SECOND was
+ * silently dropped because the old client-side gate returned the existing
+ * record instead of writing).
+ *
+ * Conservative match = raw cosine >= cosineThreshold AND Jaccard token-overlap
+ * >= lexicalThreshold, checked ONLY against the SINGLE top-cosine candidate
+ * (scoped to the same agentId as the write — never cross-agent). If that one
+ * candidate fails either gate, there is no match; we do not fall back to the
+ * 2nd-most-similar candidate.
+ *
+ * Previously this lived client-side (packages/flair-client/src/client.ts,
+ * pre-fix) and only ran for callers that opted into `dedup:true` over HTTP
+ * PUT — the Model-2 /mcp handler (resources/mcp-tools.ts), which calls
+ * Memory.post() directly, got ZERO dedup checking. Moving the gate here makes
+ * it apply uniformly regardless of transport (HTTP PUT vs in-process post()).
+ *
+ * NOTE on HTTP verbs: the Memory schema only exposes PUT over HTTP (a raw
+ * HTTP POST /Memory returns "Memory does not have a post method implemented"
+ * — see src/cli.ts's `flair test` command and commit 2fa6d22 / ops-pj5).
+ * `Memory.post()` IS reachable, but only via an in-process resource
+ * instantiation (as resources/mcp-tools.ts does) — never via the real HTTP
+ * POST route. Because flair-client's write() (used by flair-mcp, the CLI, and
+ * every other integration package) issues an HTTP PUT, the actual
+ * field-observed bug (#526) flows through Memory.put(), not Memory.post().
+ * The gate below is therefore a SHARED helper invoked from both post() and
+ * put() — anchored in the same place the design calls out (Memory.post), but
+ * wired into put() too so the write path real callers actually use is
+ * protected. See memory-integrity-fix report for the full writeup of this
+ * deviation from a literal "gate lives only in Memory.post" reading.
+ */
+async function findConservativeDedupMatch(ctx, agentId, contentText, embedding, cosineThreshold, lexicalThreshold) {
+    if (!agentId || !embedding || embedding.length === 0)
+        return null;
+    try {
+        const query = {
+            sort: { attribute: "embedding", target: embedding, distance: "cosine" },
+            conditions: [
+                { attribute: "agentId", comparator: "equals", value: agentId },
+                { attribute: "archived", comparator: "not_equal", value: true },
+            ],
+            select: ["id", "content", "$distance"],
+            limit: 1,
+        };
+        let top = null;
+        // Detach ctx.transaction around this search — same rationale as
+        // Memory.search()/SemanticSearch.ts: a drained search generator can leave
+        // a CLOSED transaction in ctx's chain that the subsequent WRITE
+        // (super.post/super.put, right after this gate runs) would otherwise
+        // inherit. Detaching here protects that write, not this read.
+        const results = withDetachedTxn(ctx, () => databases.flair.Memory.search(query));
+        for await (const record of results) {
+            top = record;
+            break; // single top-cosine candidate only — never fall back further
+        }
+        if (!top)
+            return null;
+        const cosine = 1 - (top.$distance ?? 1);
+        const confidence = computeMatchConfidence(contentText, top.content, cosine);
+        if (!isConservativeMatch(confidence.cosine, confidence.lexical, cosineThreshold, lexicalThreshold)) {
+            return null;
+        }
+        return { matchedId: top.id, cosine: confidence.cosine, lexical: confidence.lexical };
+    }
+    catch {
+        // Dedup-check failures (embedding engine down, search error, etc.) must
+        // NEVER block or alter the write — treat as "no match found".
+        return null;
+    }
+}
+/**
+ * Run the dedup gate for a create-shaped write. Mutates `content.embedding` /
+ * `content.embeddingModel` when it computes a fresh embedding, so the
+ * existing "generate embedding if missing" step later in post()/put() reuses
+ * it instead of recomputing. Always strips the client-forwarded hint fields
+ * (dedup / dedupThreshold / lexicalThreshold) so they never persist onto the
+ * stored record — they are passthrough tuning hints, not schema fields.
+ *
+ * Returns the match signal, or null (no match / gate not applicable).
+ */
+async function runDedupGate(ctx, content) {
+    const cosineThreshold = typeof content.dedupThreshold === "number" ? content.dedupThreshold : DEDUP_COSINE_THRESHOLD_DEFAULT;
+    const lexicalThreshold = typeof content.lexicalThreshold === "number" ? content.lexicalThreshold : DEDUP_LEXICAL_THRESHOLD_DEFAULT;
+    delete content.dedup;
+    delete content.dedupThreshold;
+    delete content.lexicalThreshold;
+    if (typeof content.content !== "string" || content.content.length < DEDUP_MIN_CONTENT_LENGTH) {
+        return null;
+    }
+    let embedding = Array.isArray(content.embedding) ? content.embedding : null;
+    if (!embedding) {
+        try {
+            embedding = await getEmbedding(content.content);
+        }
+        catch {
+            embedding = null;
+        }
+        if (embedding) {
+            content.embedding = embedding;
+            content.embeddingModel = getModelId();
+        }
+    }
+    if (!embedding)
+        return null;
+    return findConservativeDedupMatch(ctx, content.agentId, content.content, embedding, cosineThreshold, lexicalThreshold);
+}
+/** Build the final write response: always `written: true`, always includes
+ *  `id`, and layers the dedup collision signal on top when present. Never a
+ *  code path where a match suppresses these base fields. */
+function buildWriteResponse(content, result, dedupMatch) {
+    const base = result && typeof result === "object" && !Array.isArray(result) ? result : {};
+    const response = {
+        id: content.id,
+        ...base,
+        written: true,
+        deduplicated: !!dedupMatch,
+    };
+    if (dedupMatch) {
+        response.matchedId = dedupMatch.matchedId;
+        response.matchConfidence = { cosine: dedupMatch.cosine, lexical: dedupMatch.lexical };
+    }
+    return response;
+}
+/**
+ * Read-modify-write close of a superseded record, with the SAME transaction
+ * detachment discipline as findConservativeDedupMatch (each discrete Harper
+ * call individually wrapped — see withDetachedTxn's doc for why a single
+ * wrap around a multi-await async function would not protect the later
+ * call). Does NOT swallow failures (ops-a4t5 fix) — throws so the caller can
+ * log it. Never called before the new record is already written.
+ */
+async function closeSupersededRecord(ctx, oldId, patch) {
+    const existing = await withDetachedTxn(ctx, () => databases.flair.Memory.get(oldId));
+    if (!existing) {
+        throw new Error(`supersede-close: record ${oldId} not found`);
+    }
+    await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...existing, ...patch }));
+}
+/** Does an agent hold a "write" grant from `ownerId`? Same MemoryGrant lookup
+ *  pattern as Memory.search()/SemanticSearch.ts (read/search scopes) — reused
+ *  here for the "write" scope that gates cross-agent supersede. */
+async function hasWriteGrant(granteeId, ownerId) {
+    try {
+        for await (const grant of databases.flair.MemoryGrant.search({
+            conditions: [
+                { attribute: "granteeId", comparator: "equals", value: granteeId },
+                { attribute: "ownerId", comparator: "equals", value: ownerId },
+            ],
+        })) {
+            if (grant.scope === "write")
+                return true;
+        }
+    }
+    catch {
+        /* MemoryGrant table not yet populated — no grant */
+    }
+    return false;
+}
+/**
+ * Shared by post() AND put(): the Memory schema only exposes a working HTTP
+ * PUT route (a raw HTTP POST /Memory 404s with "Memory does not have a post
+ * method implemented" — see src/cli.ts's `flair test` command / commit
+ * 2fa6d22 / ops-pj5). Memory.post() IS reachable, but only via an in-process
+ * resource instantiation (resources/mcp-tools.ts does this). Since
+ * flair-client's write()/update() — used by flair-mcp, the CLI, and every
+ * other integration package — issue HTTP PUT, `supersedes` must be fully
+ * handled (validated, authorized, and closed) from BOTH entry points for the
+ * real-world write path to actually get the fix, not just the in-process one.
+ *
+ * Validates the `supersedes` field's shape and, for a cross-agent supersede,
+ * requires a "write" MemoryGrant from the target's owner (reuses the existing
+ * agent-auth/grant machinery — no parallel auth logic). Returns a Response to
+ * short-circuit with (400/403), or null to continue.
+ */
+async function validateAndAuthorizeSupersedes(content, auth) {
+    if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
+        return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
+            status: 400, headers: { "Content-Type": "application/json" },
+        });
+    }
+    if (content.supersedes && auth.kind === "agent" && !auth.isAdmin) {
+        const target = await databases.flair.Memory.get(content.supersedes).catch(() => null);
+        if (target && target.agentId !== auth.agentId) {
+            if (!(await hasWriteGrant(auth.agentId, target.agentId))) {
+                return FORBIDDEN("forbidden: cannot supersede a memory owned by another agent without a write grant");
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Close the superseded record — called AFTER the new record has already been
+ * written (write-new-BEFORE-close-old, ops-a4t5 fix). Safe failure state is
+ * two active records (recoverable), never a tombstoned-old-with-lost-new.
+ * Failure is logged (observable), never silently swallowed. No-op if
+ * `content.supersedes` is not set.
+ */
+async function closeSupersededIfNeeded(ctx, content, methodLabel) {
+    if (!content.supersedes)
+        return;
+    try {
+        await closeSupersededRecord(ctx, content.supersedes, {
+            validTo: content.validFrom ?? content.createdAt,
+            updatedAt: content.createdAt ?? content.updatedAt,
+        });
+    }
+    catch (err) {
+        // Constant format string + structured data: memory ids are agent-controlled,
+        // so interpolating them into console.error's format position (with a trailing
+        // `err` arg) would let an id containing %s/%o consume/hide the real error
+        // (semgrep unsafe-formatstring). Keep all dynamic values in the data object.
+        console.error("Memory.closeSuperseded: failed to close superseded record after writing new record " +
+            "(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 });
+    }
+}
 export class Memory extends databases.flair.Memory {
+    /**
+     * Self-authorize now that the global gate is non-rejecting. Closes the P0
+     * leak: Harper routes `GET /Memory/<id>` to get() and the collection
+     * describe (`GET /Memory`) to a path outside search() — neither was gated
+     * before this fix, so an anonymous caller got a 200 with full record
+     * content / schema even though search() (and the write paths) correctly
+     * 401/403'd. Per-record ownership/grant scoping happens in get() below;
+     * the collection scope is still in search().
+     *
+     * allowCreate/allowUpdate/allowDelete are deliberately NOT added here:
+     * post()/put()/delete() already self-enforce per-agent ownership inline
+     * (resolveAgentAuth + explicit agentId checks in post()/put(), and the
+     * isAdmin durability check in delete()). Adding allow* on top of that,
+     * unverified, risks regressing owner writes/deletes on a P0 security fix
+     * that is scoped to the read leak — left as-is on purpose.
+     */
+    allowRead() { return allowVerified(this.getContext?.()); }
+    /**
+     * Override get() to scope by-id reads the same way search() scopes
+     * collection reads (memory-soul-read-gate 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'
+     * memory ids.
+     */
+    async get(target) {
+        // Collection / query reads — the `GET /Memory/?<query>` form and the bare
+        // collection — arrive as a RequestTarget with `isCollection === true`, and
+        // are governed by search() (same owner/grant 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, the single-record check would find no `.agentId` on it, and a valid
+        // authenticated self-query would 404 (regression caught by the auth-
+        // middleware e2e "TPS-Ed25519 on GET /Memory/?agentId=X → 200"). A by-id
+        // get (RequestTarget with isCollection false, or a bare id) falls through.
+        if (!target || (typeof target === "object" && target.isCollection)) {
+            return this.search(target);
+        }
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        // 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 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).
+        const record = await super.get(target);
+        if (!record)
+            return NOT_FOUND();
+        const allowedOwners = await resolveAllowedOwners(auth.agentId);
+        if (!allowedOwners.includes(record.agentId))
+            return NOT_FOUND();
+        return record;
+    }
     /**
      * Override search() to scope collection GETs by authenticated agent.
      *
@@ -32,17 +339,7 @@ export class Memory extends databases.flair.Memory {
         }
         // Non-admin agent: scope to own + granted owners.
         const authAgent = auth.agentId;
-        const allowedOwners = [authAgent];
-        try {
-            for await (const grant of databases.flair.MemoryGrant.search({
-                conditions: [{ attribute: "granteeId", comparator: "equals", value: authAgent }],
-            })) {
-                if (grant.ownerId && (grant.scope === "read" || grant.scope === "search")) {
-                    allowedOwners.push(grant.ownerId);
-                }
-            }
-        }
-        catch { /* MemoryGrant table not yet populated — ignore */ }
+        const allowedOwners = await resolveAllowedOwners(authAgent);
         // Build the agentId scope condition
         const agentIdCondition = allowedOwners.length === 1
             ? { attribute: "agentId", comparator: "equals", value: allowedOwners[0] }
@@ -78,20 +375,17 @@ export class Memory extends databases.flair.Memory {
         // resolveAgentAuth (reads the gate's tpsAgent annotation) — NOT context.user
         // .username, which is the fallback "admin" super_user while de-elevation is
         // dormant and would wrongly 403 every agent's own write. internal/admin → pass.
+        let auth;
         {
-            const auth = await resolveAgentAuth(ctx);
+            auth = await resolveAgentAuth(ctx);
             // Anonymous HTTP must NOT write. Pre-flip the global gate rejected no-auth
             // upstream; with the non-rejecting gate, each write path self-enforces (same
             // rule search() applies to reads).
             if (auth.kind === "anonymous") {
-                return new Response(JSON.stringify({ error: "authentication required" }), {
-                    status: 401, headers: { "Content-Type": "application/json" },
-                });
+                return UNAUTH();
             }
             if (auth.kind === "agent" && !auth.isAdmin && content?.agentId && content.agentId !== auth.agentId) {
-                return new Response(JSON.stringify({ error: "forbidden: cannot write memory owned by another agent" }), {
-                    status: 403, headers: { "Content-Type": "application/json" },
-                });
+                return FORBIDDEN("forbidden: cannot write memory owned by another agent");
             }
         }
         content.durability ||= "standard";
@@ -111,23 +405,16 @@ export class Memory extends databases.flair.Memory {
                 catch { }
             }
         }
-        // supersedes: optional reference to the ID of the memory this one replaces
-        if (content.supersedes !== undefined && typeof content.supersedes !== "string") {
-            return new Response(JSON.stringify({ error: "supersedes must be a string (memory ID)" }), {
-                status: 400, headers: { "Content-Type": "application/json" },
-            });
-        }
+        // supersedes: optional reference to the ID of the memory this one
+        // replaces. Validates shape + cross-agent-write authorization (shared
+        // with put() — see validateAndAuthorizeSupersedes doc).
+        const supersedesError = await validateAndAuthorizeSupersedes(content, auth);
+        if (supersedesError)
+            return supersedesError;
         // Temporal validity: validFrom defaults to now, validTo left null for active facts.
-        // When a memory supersedes another, close the superseded memory's validity window.
         if (!content.validFrom) {
             content.validFrom = content.createdAt;
         }
-        if (content.supersedes) {
-            patchRecord(databases.flair.Memory, content.supersedes, {
-                validTo: content.validFrom,
-                updatedAt: content.createdAt,
-            }).catch(() => { });
-        }
         if (content.durability === "ephemeral" && !content.expiresAt) {
             const ttlHours = Number(process.env.FLAIR_EPHEMERAL_TTL_HOURS || 24);
             content.expiresAt = new Date(Date.now() + ttlHours * 3600_000).toISOString();
@@ -147,7 +434,22 @@ export class Memory extends databases.flair.Memory {
                 content._safetyFlags = safety.flags;
             }
         }
-        // Generate embedding from content text
+        // Server-side conservative-duplicate gate (memory-integrity fix). A
+        // supersede write is an intentional version-link, not an ambiguous "is
+        // this a duplicate of something else" situation — bypass the gate for it
+        // (this also gives memory_update's preserveHistory mode dedup-bypass for
+        // free, without a separate flag). NEVER suppresses the write either way.
+        let dedupMatch = null;
+        if (!content.supersedes) {
+            dedupMatch = await runDedupGate(ctx, content);
+        }
+        else {
+            delete content.dedup;
+            delete content.dedupThreshold;
+            delete content.lexicalThreshold;
+        }
+        // Generate embedding from content text (no-op if the dedup gate above
+        // already computed one for this content).
         if (content.content && !content.embedding) {
             const vec = await getEmbedding(content.content);
             if (vec) {
@@ -155,7 +457,16 @@ export class Memory extends databases.flair.Memory {
                 content.embeddingModel = getModelId();
             }
         }
-        return super.post(content);
+        // ── Write the new record FIRST ──────────────────────────────────────────
+        const result = await super.post(content);
+        // ── THEN close the superseded record (ops-a4t5 fix) ─────────────────────
+        // Write-new-BEFORE-close-old: the previous order (close-old via a fire-
+        // and-forget `.catch(()=>{})` BEFORE the new write) could tombstone the
+        // old record and then lose the new one if the write failed afterward.
+        // Now the safe failure state is two active records (recoverable), never
+        // a lost write — and the failure is logged, never silently swallowed.
+        await closeSupersededIfNeeded(ctx, content, "post");
+        return buildWriteResponse(content, result, dedupMatch);
     }
     async put(content) {
         // Reindex migration bypass: admin-only escape hatch used by the
@@ -181,19 +492,16 @@ export class Memory extends databases.flair.Memory {
         // write memories it owns, via resolveAgentAuth (gate annotation), not
         // context.user.username (the dormant-de-elevation fallback is "admin").
         // The _reindex admin path above bypasses this.
+        const ctx = this.getContext?.();
+        let auth;
         {
-            const octx = this.getContext?.();
-            const auth = await resolveAgentAuth(octx);
+            auth = await resolveAgentAuth(ctx);
             // Anonymous HTTP must NOT write (non-rejecting gate → self-enforce here).
             if (auth.kind === "anonymous") {
-                return new Response(JSON.stringify({ error: "authentication required" }), {
-                    status: 401, headers: { "Content-Type": "application/json" },
-                });
+                return UNAUTH();
             }
             if (auth.kind === "agent" && !auth.isAdmin && content?.agentId && content.agentId !== auth.agentId) {
-                return new Response(JSON.stringify({ error: "forbidden: cannot write memory owned by another agent" }), {
-                    status: 403, headers: { "Content-Type": "application/json" },
-                });
+                return FORBIDDEN("forbidden: cannot write memory owned by another agent");
             }
         }
         const now = new Date().toISOString();
@@ -201,6 +509,16 @@ 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;
+        // 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
+        // this too: it's the only HTTP-reachable create path).
+        const supersedesError = await validateAndAuthorizeSupersedes(content, auth);
+        if (supersedesError)
+            return supersedesError;
+        if (content.supersedes && !content.validFrom) {
+            content.validFrom = content.createdAt;
+        }
         // Content safety scan on updated content + summary (ops-i2jb).
         if (content.content || content.summary) {
             const safety = scanFields(content, ["content", "summary"]);
@@ -219,7 +537,36 @@ export class Memory extends databases.flair.Memory {
                 content._safetyFlags = null;
             }
         }
-        // Re-generate embedding if content changed
+        // Server-side conservative-duplicate gate (memory-integrity fix). PUT is
+        // an upsert: only run the gate for a FRESH create (target id does not yet
+        // exist) that is NOT a supersede-link write. An update of an EXISTING id
+        // (memory_update's default same-id overwrite path) is an intentional,
+        // explicit overwrite, and a supersede-link write is an intentional
+        // version-link — neither is an ambiguous "is this a duplicate of
+        // something else" write, so both are dedup-bypassed automatically, no
+        // separate flag needed. NEVER suppresses the write either way.
+        let dedupMatch = null;
+        if (content.supersedes) {
+            delete content.dedup;
+            delete content.dedupThreshold;
+            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);
+            }
+            else {
+                delete content.dedup;
+                delete content.dedupThreshold;
+                delete content.lexicalThreshold;
+            }
+        }
+        else {
+            dedupMatch = await runDedupGate(ctx, content);
+        }
+        // Re-generate embedding if content changed (no-op if the dedup gate above
+        // already computed one for this content).
         if (content.content && !content.embedding) {
             const vec = await getEmbedding(content.content);
             if (vec) {
@@ -240,10 +587,22 @@ export class Memory extends databases.flair.Memory {
         if (content.promotionStatus === "approved") {
             content.durability = "permanent";
         }
-        return super.put(content);
+        // ── Write the new/updated record FIRST ──────────────────────────────────
+        const result = await super.put(content);
+        // ── THEN close the superseded record (ops-a4t5 fix; see post()) ────────
+        await closeSupersededIfNeeded(ctx, content, "put");
+        return buildWriteResponse(content, result, dedupMatch);
     }
     async 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/non-granted id, which would
+        // otherwise short-circuit the `record.durability === "permanent"` check
+        // below (a Response has no .durability) and silently bypass the
+        // admin-only permanent-delete guard for cross-agent deletes. This keeps
+        // delete()'s own pre-existing ownership/admin logic exactly as it was
+        // before the read-gate fix — the read-scoping override must not leak
+        // into delete()'s internal record lookup.
+        const record = await super.get(id);
         if (!record)
             return super.delete(id);
         if (record.durability === "permanent") {

package/dist/resources/MemoryGrant.js

@@ -1,7 +1,8 @@
 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" } });
 /**
  * MemoryGrant — an agent (ownerId) grants another (granteeId) scoped access to its
  * memories. Self-authorizes now that the global gate is non-rejecting (previously a
@@ -16,6 +17,52 @@ export class MemoryGrant extends databases.flair.MemoryGrant {
     _auth() {
         return resolveAgentAuth(this.getContext?.());
     }
+    /**
+     * Self-authorize now that the global gate is non-rejecting (memory-soul-
+     * read-gate family fix, ops-oox7 — same pattern as Memory.ts/Soul.ts/
+     * WorkspaceState.ts/Relationship.ts/Integration.ts). Closes the same P0
+     * leak: Harper routes `GET /MemoryGrant/<id>` to get() and the collection
+     * describe (`GET /MemoryGrant`) outside search(), so neither was gated
+     * before this fix — an anonymous caller got a 200 with full grant content.
+     * Per-record owner/grantee 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). A grant is visible
+     * to either party (ownerId OR granteeId), mirroring search()'s owner-OR-
+     * grantee scope. 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' grant ids.
+     */
+    async get(target) {
+        // Collection / query reads arrive as a RequestTarget with
+        // `isCollection === true`, and are governed by search() (same owner/
+        // grantee scoping). Only a genuine by-id get is ownership-checked below
+        // — 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: visible if it's the owner OR the grantee (parity with
+        // search()'s owner-OR-grantee scope).
+        const record = await super.get(target);
+        if (!record)
+            return NOT_FOUND();
+        if (record.ownerId !== auth.agentId && record.granteeId !== auth.agentId)
+            return NOT_FOUND();
+        return record;
+    }
     async search(query) {
         const auth = await this._auth();
         if (auth.kind === "anonymous")
@@ -59,7 +106,13 @@ export class MemoryGrant extends databases.flair.MemoryGrant {
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return super.delete(id, context);
         }
-        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/non-grantee 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, context) no-op. Mirrors Memory.ts's delete() — same
+        // rationale, same fix.
+        const record = await super.get(id);
         if (!record)
             return super.delete(id, context);
         if (record.ownerId !== auth.agentId) {